故障排查

用途

按页面、任务、模型、媒体和部署链路定位常见故障，先确认根因再进行一次安全重试。

使用前准备

记录发生时间、页面路径、项目或剧集、任务 ID、模型名称、可复现步骤和脱敏错误。不要提供 API Key、Token、完整用户正文或未授权媒体。

配图占位

页面：失败任务或错误状态页面

状态：保留错误摘要、任务 ID 和重试入口

重点区域：状态、错误码、发生时间、结果位置和恢复操作

脱敏要求：隐藏凭据、邮箱、余额、用户正文、媒体和完整供应商响应

操作步骤

页面无法登录或不断跳转

确认访问地址和语言前缀正确，清理旧版本浏览器缓存后重新登录。检查 NextAuth 相关环境变量、数据库连接和服务端日志。访问管理员路径被送回个人页通常表示账号没有管理员权限。

生成任务一直等待

确认 Worker 正在运行。
打开 Bull Board 检查任务是否进入正确队列。
检查 Redis 连接、队列并发和是否存在大量阻塞任务。
不要连续重复提交；记录任务 ID 后交由管理员定位。

模型任务失败

按“页面输入 → 默认模型 → API 凭据 → 供应商余额/权限 → 网络 → Worker 日志”排查。模型不支持当前比例、时长、参考图或输入格式时，应修改参数，而不是直接重试。

StarRouter 图片模型采用同步生成请求，Worker 最多等待 5 分钟。出现 STARSTONE_IMAGE_SUBMIT_TIMEOUT 表示供应商在此时间内未返回结果，可确认供应商状态后重试。

StarRouter 文本模型请求默认最多等待 500 秒；视频提示词改写也显式使用同一上限。超时仍表示供应商未在期限内返回结果，任务可按队列策略重试。

图片、视频或音频无法打开

检查对象存储和媒体 URL、MinIO 端口、文件是否实际写入、当前账号是否有项目权限。开发环境中数据库记录存在但文件不存在，通常表示对象存储未启动或上传阶段失败。

配音不可用

OmniVoice-Studio 是可选接入，默认关闭。需要使用时，将 NEXT_PUBLIC_OMNIVOICE_ENABLED 设为 true 并重新构建前端，再确认 OMNIVOICE_BASE_URL 指向可访问的服务并检查超时配置。关闭时，OmniVoice 模型、声音设计和克隆入口不会显示；CosyVoice 等其他配音能力不受影响。声音克隆还需有效且有授权的音频样本。

修改提示词后没有生效

确认中英文磁盘文件和国际化目录已更新，然后运行提示词 seed、vvicat-sync-prompts --apply 和 npm run check:prompt-i18n。涉及新流程时还需更新知识应用点、默认绑定和初始化快照。

从帮助文档返回后界面颜色异常

平台会在离开帮助文档时清除文档主题状态。若已打开的旧页面仍显示灰暗背景，完整刷新一次以清除旧的客户端状态；问题持续时请记录导航路径和浏览器主题设置。

文档同步检查失败

“缺少配对文档”：在另一语言目录创建或修改相同相对路径的 MDX。
“新增功能入口”：为新页面、API 或工作流新增一对文章，并注册两侧 _meta.ts。
“冲突标记”：根据当前代码重新整理内容，删除 <<<<<<<、=======、>>>>>>>。
修复后运行 npm run check:docs-sync，暂存后可用 npm run check:docs-sync -- --staged 复核。

收集诊断信息

提交问题时提供发生时间、页面路径、项目/剧集范围、任务 ID、模型名称、可复现步骤和脱敏后的错误。不要提交 API Key、Token、完整用户正文或未授权媒体。

结果与状态

排查结束时应得到可验证的原因、修正动作和一次重试结果。若任务已完成但页面未展示，先检查服务端结果与当前资产版本；不要通过重复提交掩盖状态同步问题。

权限和限制

普通用户只查看自己项目的错误与结果；队列、日志和全局配置由管理员检查。
日志与供应商响应可能包含业务上下文，复制前必须脱敏。
数据修复、批量重试、队列清理和权限提升不属于普通故障重试，必须走可审计流程。

常见问题

可以直接再点一次生成吗？

先确认旧任务是否已创建和是否已有结果。只有修正明确原因后才重试一次，避免重复费用。

需要向管理员提供什么？

提供时间、页面路径、项目范围、任务 ID、模型、步骤和脱敏错误，不要提供密钥或完整业务内容。