新增示例库逻辑

docs/zh/troubleshooting.md

@@ -0,0 +1,108 @@
+# 故障排查
+
+遇到问题？这里有一些常见问题的解决方案。
+
+---
+
+## 安装问题
+
+### 依赖安装失败
+
+```bash
+# 清理缓存
+uv cache clean
+
+# 重新安装
+uv sync
+```
+
+---
+
+## 配置问题
+
+### ComfyUI 连接失败
+
+**可能原因**:
+- ComfyUI 未运行
+- URL 配置错误
+- 防火墙阻止
+
+**解决方案**:
+1. 确认 ComfyUI 正在运行
+2. 检查 URL 配置（默认 `http://127.0.0.1:8188`）
+3. 在浏览器中访问 ComfyUI 地址测试
+4. 检查防火墙设置
+
+### LLM API 调用失败
+
+**可能原因**:
+- API Key 错误
+- 网络问题
+- 余额不足
+
+**解决方案**:
+1. 检查 API Key 是否正确
+2. 检查网络连接
+3. 查看错误提示中的具体原因
+4. 检查账户余额
+
+---
+
+## 生成问题
+
+### 视频生成失败
+
+**可能原因**:
+- 工作流文件损坏
+- 模型未下载
+- 资源不足
+
+**解决方案**:
+1. 检查工作流文件是否存在
+2. 确认 ComfyUI 已下载所需模型
+3. 检查磁盘空间和内存
+
+### 图像生成失败
+
+**解决方案**:
+1. 检查 ComfyUI 是否正常运行
+2. 尝试在 ComfyUI 中手动测试工作流
+3. 检查工作流配置
+
+### TTS 生成失败
+
+**解决方案**:
+1. 检查 TTS 工作流是否正确
+2. 如使用声音克隆，检查参考音频格式
+3. 查看错误日志
+
+---
+
+## 性能问题
+
+### 生成速度慢
+
+**优化建议**:
+1. 使用本地 ComfyUI（比云端快）
+2. 减少分镜数量
+3. 使用更快的 LLM（如 Qianwen）
+4. 检查网络连接
+
+---
+
+## 其他问题
+
+仍有问题？
+
+1. 查看项目 [GitHub Issues](https://github.com/PixelleLab/Pixelle-Video/issues)
+2. 提交新的 Issue 描述你的问题
+3. 包含错误日志和配置信息以便快速定位
+
+---
+
+## 日志查看
+
+日志文件位于项目根目录：
+- `api_server.log` - API 服务日志
+- `test_output.log` - 测试日志
+