docs: 同步生成媒体排错说明 (#72)

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Troubleshooting
-wiki_revision: 24b997f29b1dc7d9955f0e0a03223a3944f508c9
-synchronized_at: 2026-08-26T14:51:18Z
+wiki_revision: 7955289af29b65b61f9495b681a9a41f7a551b2d
+synchronized_at: 2026-08-27T01:58:19Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -160,3 +160,13 @@ LIMIT 10;
 - Admin UI 默认双 bundle 构建出现 V8 OOM：先停止本项目开发服务、释放内存并设置 `NODE_OPTIONS=--max-old-space-size=4096` 后重跑。不得把只完成 legacy bundle 记录成完整构建通过。
 - Supervisor 被强制结束后无法重启：确认 PID 文件指向的进程确实不存在后，才能清理过期 PID 并重新启动；随后核对 Portal、Admin API、Admin UI 三个监听端口。
 <!-- issues-67-69-system-troubleshooting:end -->
+
+<!-- issue-72-admin-media-troubleshooting:start -->
+## Admin 详情无法显示生成图片（#72）
+
+1. 确认数据库已到 migration 10 且 dirty=0，四个生成记录 GET API 已登记并授予当前角色。
+2. 确认 `settings.extend.chorus.storage_root` 指向 Portal 实际使用的生成物目录；相对路径按 Admin API 工作目录解析。
+3. 如果 Admin API 启动时报存储目录不可用，先检查目录存在和进程只读权限，不要让 Admin 自动创建目录。
+4. 如果详情能打开但单张图片失败，检查该 input/output 是否属于 URL 中的 generation，以及对象 metadata 的 owner、generation、MIME 是否与数据库一致。接口会返回稳定的资源不存在，不会回显磁盘路径。
+5. 浏览器网络面板中媒体请求应携带 Authorization header，响应应包含 `Cache-Control: no-store` 和 `X-Content-Type-Options: nosniff`；媒体 URL 不应包含 Token。
+<!-- issue-72-admin-media-troubleshooting:end -->