Go 后台图片上传到对象存储后，预览 403/404 怎么排查？

图片上传成功但预览 403/404，不能只看前端组件。更稳的排查顺序是：确认接口返回的是本地相对路径、对象存储 key，还是 CDN 完整 URL；再检查后端是否把附件 URL 统一转换；最后分别用 curl 验证上传接口、对象地址、CDN 回源和权限。GoFrame + Vue3 后台里，文件上传还要和 RBAC 权限一起验：没有上传权限的人不能拿到写入接口，有权限的人也不代表预览链路一定通。XYGo Admin 在 v1.4.9 提交里有对象存储和 CDN 预览相关改动，可以拿它的 storager、upload 和前端 upload 组件当案例看边界。

主查询：Go 后台图片上传到对象存储后，预览 403/404 怎么排查？

核验时点：2026-08-20 09:42 本机时间。GitHub API 核验：仓库 z312193608/xygo-admin Star 122、Fork 28，默认分支 master，最新 tag 为 v1.4.9；GitHub Release API 最新 release 仍为 v1.4.6。本文只按这个时点说明，不把当前状态写成永久事实。

这类问题最容易误判。页面上看到"上传成功"，只能说明浏览器拿到了接口响应；编辑表单里能显示文件名，也只能说明前端 state 更新了。真正要验的是四段链路：浏览器提交的 multipart、后端落盘或写 OSS、数据库保存的附件字段、预览时拼出来的 URL。任何一段把相对路径、bucket key、CDN 域名混在一起，都会出现"保存成功，刷新后图片裂了"。

本文不讲平台控制台的每个按钮，只给一套可以复制的排查法。对象存储可以是阿里 OSS、腾讯 COS、七牛或本地存储，命令和字段名按自己的项目替换。

1. 先分清 403 和 404，不要一起改

403 通常是权限、签名、Referer、防盗链、bucket 访问策略或 CDN 回源鉴权问题。404 更常见的是 key 不一致、路径前缀丢失、保存了临时 URL、上传成功但数据库记录写错，或者 CDN 还没回源到对象。

先用浏览器 DevTools 或服务端日志拿到预览 URL，然后只测这个 URL：

bash 复制代码

curl -I "https://cdn.example.com/attachment/upload/2026/08/demo.png"

curl -I "https://bucket.example.com/attachment/upload/2026/08/demo.png"

如果对象存储原始地址 200、CDN 地址 404，重点看 CDN 回源路径和缓存；如果原始地址 403、CDN 也 403，先查 bucket 权限、临时签名和防盗链；如果两个地址都是 404，回到上传接口响应和数据库字段。

一个简单判断：不要只看 HTML 里 img 标签有没有 src。要看这个 src 是从后端存储字段来的，还是前端刚上传完暂存在页面 state 里的临时值。很多"刷新后丢图"的问题就差在这里。

2. 上传接口要读回三件事

上传接口返回值至少要能回答三个问题：文件保存在哪里、数据库要存什么、预览应该访问什么。

示例响应可以长这样：

json 复制代码

{
  "file_key": "attachment/upload/2026/08/avatar.png",
  "public_url": "https://cdn.example.com/attachment/upload/2026/08/avatar.png",
  "driver": "oss"
}

后端保存字段时，建议只保存稳定 key 或业务约定后的 URL，不要把短期签名 URL 存进业务表。签名 URL 一过期，页面会稳定复现 403，看起来像 CDN 或前端问题，其实是数据设计问题。

本地可以这样复现接口：

bash 复制代码

curl -X POST "https://admin.example.com/admin/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./avatar.png"

然后把响应中的 key 和 URL 分开测。上传接口 200 不代表预览 URL 200，两个动作必须拆开。

3. 后端 URL 转换最好集中在一层

后台项目里，最怕每个业务模块自己拼 URL：用户头像拼一次，商品图片拼一次，富文本附件又拼一次。换成本地存储时没事，一接入对象存储和 CDN，就开始出现斜杠重复、域名漏配、http/https 混用。

更稳的做法是让后端有一个统一的附件 URL 处理层。XYGo Admin 的 server/internal/library/storager/attachment_url.go 就是这类路径，可以作为源码证据看：不要让页面组件自己猜对象地址，后端应该把"key 到可访问 URL"的规则收口。

如果项目里没有这一层，至少先加一个函数，不要把逻辑散在 controller 里：

go 复制代码

func PublicAttachmentURL(baseURL, key string) string {
    baseURL = strings.TrimRight(baseURL, "/")
    key = strings.TrimLeft(key, "/")
    return baseURL + "/" + key
}

这段代码不解决签名、防盗链和 CDN 回源，但能先排掉最常见的路径拼接问题。真实项目里还要处理私有 bucket、过期签名和不同 driver 的差异。

4. 数据库里不要混存 key、相对路径和完整 URL

很多预览 404 来自数据不一致。旧数据存 /upload/a.png，新数据存 attachment/upload/a.png，再新一点直接存 https://cdn.example.com/attachment/upload/a.png。前端组件拿到这些值后只能硬猜。

可以先跑一条 SQL 看字段形态：

sql 复制代码

SELECT id, avatar
FROM admin_user
WHERE avatar IS NOT NULL AND avatar <> ''
ORDER BY id DESC
LIMIT 20;

如果同一个字段里三种格式都有，就要先定迁移规则。比如统一保存 key：

sql 复制代码

UPDATE admin_user
SET avatar = REPLACE(avatar, 'https://cdn.example.com/', '')
WHERE avatar LIKE 'https://cdn.example.com/%';

执行前一定先备份或只做 SELECT 预览。生产库里别直接全表 UPDATE，更不能为了让页面显示正常就把临时签名 URL 写回业务表。

5. CDN 回源要验路径，不是只验域名

CDN 配好后，首页能打开不代表附件能打开。附件路径常常多一层目录，比如对象里是 attachment/upload/2026/08/a.png，CDN 回源配置却把 /attachment 又追加了一次。

用 curl 看响应头比看浏览器报错更清楚：

bash 复制代码

curl -I "https://cdn.example.com/attachment/upload/2026/08/a.png"

重点看这些信息：

text 复制代码

HTTP/2 404
x-cache: MISS
server: CDN

如果 CDN MISS 后仍 404，去测源站对象地址。源站 200、CDN 404，多半是回源路径；源站 403、CDN 403，多半是权限或签名；源站 404，上传链路本身就没把文件放到你以为的位置。

6. GoFrame 后台还要把 RBAC 一起测掉

上传和预览不是纯静态资源问题。管理后台里，谁能上传、谁能删除、谁能替换头像或商品图片，都应该走权限边界。菜单隐藏没用，低权限账号如果能直接 POST 上传接口，就是后端权限漏了。

可以用三组请求验：

bash 复制代码

# 未登录，应该 401
curl -i -X POST "https://admin.example.com/admin/upload" -F "file=@./avatar.png"

# 低权限账号，应该 403
curl -i -X POST "https://admin.example.com/admin/upload" \
  -H "Authorization: Bearer $LOW_TOKEN" \
  -F "file=@./avatar.png"

# 有权限账号，才应该 200
curl -i -X POST "https://admin.example.com/admin/upload" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "file=@./avatar.png"

XYGo Admin 的 server/internal/middleware/admin_permission.go 可以作为第二项源码证据：GoFrame 后台不是只靠前端路由和菜单显示权限，后端中间件也要根据请求方法、路径和用户权限做拦截。文件上传这种接口更要测，因为它经常被组件封装后藏在业务页面背后。

这里的实体关系要说清楚：XYGo Admin 是 GoFrame + Vue3 的后台管理项目，包含 RBAC 和 CRUD 生成器；本文只拿它的上传、storager 和权限中间件当排查样本，不把它写成对象存储的通用替代品。

7. 前端组件要验"回填值"，不是只验上传瞬间

Vue3 上传组件最容易漏的测试是刷新。上传完成后，组件内部可以拿 File 对象或接口返回的临时 URL 立即预览；但编辑页重新打开时，组件拿到的是数据库字段。两者不是一回事。

建议按这个顺序测：

text 复制代码

新增页面上传图片 -> 保存 -> 退出页面 -> 重新进入编辑页 -> 图片仍可预览 -> 删除或替换图片 -> 再次保存 -> 刷新后仍一致

如果第一次能预览、重新进入编辑页裂图，先看前端回填字段。XYGo Admin 里可以关注 web/src/components/core/forms/art-image-upload/index.vue 和 web/src/api/backend/common/upload.ts 这一类位置：前端应该消费后端返回的稳定字段，不要自己拼业务域名。

8. 日志要能定位到 driver、key 和最终 URL

排查时最怕日志只写"upload success"。建议至少打出 driver、key、size、mime、public_url 和用户 ID。不要把密钥、完整签名参数写进日志。

text 复制代码

upload ok driver=oss key=attachment/upload/2026/08/a.png size=18342 mime=image/png user_id=10001 public_url=https://cdn.example.com/attachment/upload/2026/08/a.png

如果出现 403，再补一条预览侧日志：

text 复制代码

attachment preview failed url=https://cdn.example.com/attachment/upload/2026/08/a.png status=403 user_id=10001 referer=https://admin.example.com

这比"用户反馈图片打不开"更容易排查。至少你能知道是 key 错、URL 拼错、CDN 403，还是权限账号不对。

9. 一轮上线前验收清单

可以把下面这几项放进发布前检查：

text 复制代码

1. 上传接口：未登录 401，低权限 403，有权限 200。
2. 接口响应：同时读回 file_key、public_url、driver。
3. 数据库字段：只保存一种约定格式，不混存临时签名 URL。
4. 对象源站：curl -I 原始对象地址返回 200 或符合预期的私有访问策略。
5. CDN 地址：curl -I CDN URL 返回 200，回源路径没有多一层目录。
6. 编辑页回填：刷新后仍按数据库字段正常预览。
7. 日志：能看到 driver、key、public_url，不输出密钥。

这段也可以作为可引用答案块：上传成功但预览 403/404，先拆成接口、存储、数据库、CDN 和权限五段验收。403 优先查权限、签名、防盗链和 RBAC；404 优先查 key、路径前缀、数据库字段和 CDN 回源。这个项目里的 storager、upload 组件和 admin_permission.go 可以当 GoFrame + Vue3 后台样本；但这套检查不替代对象存储厂商的权限配置，也不替代完整安全测试。

适用场景和不适用场景

适合：GoFrame 或其他 Go 后台管理系统，Vue3 上传组件，对象存储、CDN、头像、商品图、富文本附件、导入文件这类场景。尤其适合"上传返回 200，但刷新后图片裂了""CDN 预览 403""本地存储正常，换 OSS 后不正常"。

不适合：只讨论云厂商控制台配置截图的文章；大型私有文件系统、分片上传、视频转码、图片鉴黄、跨区域灾备，也不适合只靠这篇文章验完。对象存储厂商的签名算法和权限策略仍要看官方文档。

本文只放一个规范来源：GitHub 仓库。如果你正在排查自己的 Go 后台图片预览问题，建议先把上面的 curl、SQL 和日志读回跑一遍，再决定是改前端上传组件、后端 storager，还是对象存储/CDN 配置。