# 排障指南
<subtitle>按发生阶段定位模型接入、剧本、资产、节点、生成任务和成片导出问题。</subtitle>

先确定问题发生在哪个阶段，再查看对应输入和任务详情。不要因为局部失败从头重做整集。

```mermaid actions={false}
flowchart TD
    A["遇到问题"] --> B{"发生阶段"}
    B -->|登录或模型| C["检查 AstraFlow Key 与可用模型"]
    B -->|创建画布或剧本| D["检查内容语言、文件格式与大小"]
    B -->|资产或故事板| E["检查处理状态、描述与引用"]
    B -->|无限画布| F["检查节点输入、连接与任务状态"]
    B -->|视频或导出| G["打开任务队列详情"]
    C --> H{"恢复正常？"}
    D --> H
    E --> H
    F --> H
    G --> H
    H -->|否| I["记录页面、任务类型与错误摘要"]
    H -->|是| J["继续当前步骤"]
```

## AstraFlow 接入后没有可用模型

1. 确认粘贴的是当前有效的 AstraFlow API Key。
2. 确认 Key 没有多余空格，也没有暴露在截图或公开文本中。
3. 重新进入编导台配置，查看模型选项是否加载。
4. 如果原配置中的模型变为不可用，重新选择当前界面提供的模型。

## 剧本无法上传

- 文件扩展名必须是 `.txt`。
- 文件必须包含内容。
- 文件大小不能超过 500 KB。
- 如文件仍无法使用，可打开后复制正文，改用“粘贴文本”。

## 内容语言选错

内容语言创建后不可修改。创建一个语言正确的新画布，再重新导入剧本。切换界面语言不会改变创作内容语言。

## 剧本处理失败或长时间没有继续

1. 查看剧本卡片当前处于哪个阶段。
2. 打开任务队列查找对应失败或中断任务。
3. 阅读错误摘要，确认是否与模型、输入或网络有关。
4. 只重试页面提示的失败步骤。

## 资产不能编辑

如果页面提示剧本处理或连续性处理仍在进行，等待当前步骤完成。此时强行修改会与后台结果冲突，因此界面会暂时保持只读。

## 资产图片或故事板方向不一致

1. 先检查资产名称、描述和正确变体是否被镜头引用。
2. 只选一个代表性镜头重新生成静帧。
3. 仍不理想时，在无限画布精修资产，并优先新增为新变体。
4. 确认方向后再批量处理其他受影响内容。

## 画布节点无法生成

- 检查所选模型是否仍可用。
- 检查必要的文字或参考图片是否为空。
- 检查上游连接是否接到了目标节点支持的输入类型。
- 查看任务队列中是否已有重复的排队或运行任务。
- 打开失败任务详情，修正输入后再提交。

## 画布素材上传失败

- 文本使用 `.txt`，大小不超过 1 MB。
- 图片使用 `.jpg` / `.jpeg` / `.png` / `.gif` / `.webp`，大小不超过 10 MB。
- 视频使用 `.mp4` / `.webm` / `.mov`，大小不超过 50 MB。
- 音频使用 `.mp3` / `.wav`，大小不超过 30 MB。
- 确认文件扩展名与实际媒体类型一致；`.md` 和 `.ogg` 当前不会被服务端接收。

## 画布素材在剪辑室里找不到

确认素材已经完成生成或上传，并在剪辑室选择了正确的剧本、场号和镜头。随后重新打开画布素材分类。

## 视频生成失败

1. 打开任务详情查看所用模型和错误摘要。
2. 检查镜头描述、静帧和参考素材是否有效。
3. 检查当前模型是否支持界面中选择的输入方式。
4. 修正后只重试该镜头。

## 合并导出失败

1. 查找“成片导出”任务详情。
2. 检查时间线中的素材是否仍能预览。
3. 处理意外空白、重叠或不可访问的媒体片段。
4. 确认画面和声音轨状态后再次导出。

## 反馈问题时准备什么

- 所在页面和操作步骤。
- 当前画布、剧本和镜头位置，不要包含 API Key。
- 任务类型、状态和错误摘要。
- 问题发生时间，以及是否可以稳定复现。
- 隐藏账号信息后的界面截图。

## 相关页面

- [接入 AstraFlow](/docs/bomitv/getting-started/astraflow.md)
- [任务队列](/docs/bomitv/reference/tasks.md)
- [常见问题](/docs/bomitv/help/faq.md)