DramaClaw CE 自托管排错指南：从启动失败到模型网关、ffmpeg 与数据升级的完整排查手册

【免费下载链接】dramaclawA general-purpose AIGC video engine: script to finished film in one pipeline — dramas, ads, product videos, otome games, and more. | 通用 AIGC 视频引擎 —— 从剧本到成片一条流水线漫剧、广告、电商、乙游皆可项目地址https://gitcode.com/gh_mirrors/dr/dramaclaw点击查看免费下载本文基于 docs/zh/guides/troubleshooting.md 编写面向自托管 DramaClaw CE 的用户。无论你是刚执行docker compose up -d就遇到容器秒退还是在模型调用、ffmpeg 合成、数据升级等环节反复踩坑都能按本文的症状—排查对照表逐项定位并结合仓库源码理解每个配置项背后的实现原理。读完你将掌握日志优先的排查思路、启动/端口/健康检查/环境版本的处理方法、模型与网关配置的关键参数NEWAPI_TEXT_TIMEOUT_SECONDS、NEWAPI_TEXT_TRUST_ENV、chat_completions_to_responses_policy等、ffmpeg 与编码器的约束以及数据卷ce-data与升级流程的正确操作姿势。排查总原则先看日志再动手自托管 DramaClaw CE 时绝大多数故障的第一现场都在日志里容器模式docker compose logs -f api实时跟踪 API 服务日志docker compose logs api查看历史输出本地开发模式直接看novelvideo api命令的终端输出。日志会直接暴露配置、端口、数据卷或上游依赖的真实异常比盲目猜测更高效。下文每个故障条目都会给出对应的日志观察点。启动类故障现象排查容器起不来 / 立即退出查看docker compose logs api按启动日志定位配置、端口或数据卷问题。8780端口被占用改 composeports左值如8888:8780或停掉占用进程lsof -i :8780。健康检查一直 unhealthy探活打/api/v1/config若 API 自身报错看启动日志定位真正异常。本地开发起不来Python 版本需3.11–3.123.11,3.13。uv python pin 3.12或装对应版本后uv sync。容器秒退与端口占用容器启动即退出几乎都是配置、端口或数据卷三类问题。docker compose logs api会打印出 Python 启动栈或环境变量校验错误沿着第一条异常往上追即可。8780是 API 默认监听端口。若被占用优先改 compose 文件中ports映射的左值宿主机端口右值保持容器内端口不变例如8888:8780也可以先定位并停掉占用进程lsof -i :8780后按 PID 结束对应进程。注意源码构建时健康检查探活的是容器内127.0.0.1:8780见 Dockerfile因此改端口只影响宿主机侧映射不影响探活逻辑。健康检查一直 unhealthyDramaClaw 的 Docker 镜像内置了健康检查每 30 秒探测一次http://127.0.0.1:8780/api/v1/config要求 2 秒内返回 200--interval30s --timeout5s --start-period20s --retries3见 Dockerfile。这也正是安装指南里用curl http://localhost:8780/api/v1/config验证是否启动成功的同一个端点见 docs/zh/getting-started/installation.md。如果健康检查一直 unhealthy说明 API 进程虽然活着但无法在该端点正常响应——大概率是 API 自身在启动阶段报错如配置缺失、数据库初始化失败。此时不要只盯着健康状态回到docker compose logs api定位真正的启动异常。本地开发的 Python 版本约束本地开发非容器要求 Python3.11–3.12这一点在项目元数据中有硬性声明pyproject.toml中requires-python 3.11,3.13见 pyproject.toml。uv 会依据uv.lock锁定依赖版本因此uv python pin 3.12 # 或安装对应版本的 Python uv sync # 按锁定文件安装依赖如果本机默认 Python 不在该区间uv sync前先切换版本即可。模型 / 网关类故障现象排查模型调用全报错在「设置 → 模型配置」确认当前渠道已配置官方渠道检查 DC key本地 NewAPI 检查服务、runtime token 和上游渠道。某个环节报模型不存在本地 NewAPI 中没有对应逻辑模型映射或目标渠道未启用。详见配置模型供应商。结构化环节报Exceeded maximum output retries角色抽取、剧本规划等纯文本环节正常上游没有返回 function/tool call。任务日志v2.0.3 起会打出重试提示和底层原因。自己做 Chat Completions 格式转换的中转站Codex2API 及类似的 Codex 反代已知会在/v1/chat/completions上丢掉tool_calls到内置 NewAPI 后台给该渠道开启ChatCompletions → Responses Compatibilitychat_completions_to_responses_policy让 NewAPI 用/v1/responses发往上游。文本模型超时调大NEWAPI_TEXT_TIMEOUT_SECONDS默认 120内网网关被系统代理拦截时设NEWAPI_TEXT_TRUST_ENVfalse。参考图功能不可用需配OSS_RELAY_AK/SK纯文本→成片流程可不配。模型调用全报错先核对渠道配置模型链路全线报错时按部署形态分两类排查官方渠道确认 DC key 已正确配置本地 NewAPI依次检查 NewAPI 服务是否存活、runtime token 是否有效、上游渠道是否已启用。前端入口在「设置 → 模型配置」后端逻辑模型与渠道的映射关系详见配置模型供应商。模型不存在逻辑模型映射缺失某个环节报模型不存在几乎总是本地 NewAPI 中没有 DramaClaw 逻辑模型到真实上游模型的映射或目标渠道未启用。需要到 NewAPI 后台补齐映射并启用渠道具体操作同样参考配置模型供应商。Exceeded maximum output retries结构化环节的 tool_calls 丢失这是结构化抽取类任务角色抽取、剧本规划等特有的故障纯文本环节正常但任何需要结构化的环节反复重试后报Exceeded maximum output retries。根因是上游没有返回 function/tool call。DramaClaw 的结构化环节依赖模型的工具调用能力而某些自己做 Chat Completions 格式转换的中转站Codex2API 及类似的 Codex 反代已知会在/v1/chat/completions上丢弃tool_calls导致下游永远等不到结构化输出。排查与修复从v2.0.3 起任务日志会打出重试提示和底层原因先看日志确认是否属于上游未返回 tool call到内置 NewAPI 后台给对应渠道开启ChatCompletions → Responses Compatibility配置项chat_completions_to_responses_policy让 NewAPI 改用/v1/responses发往上游绕过中转站丢tool_calls的问题。这一故障在仓库的配置模型指南中也有对应条目见 docs/zh/getting-started/configuring-models.md可作为同一问题的交叉印证。从源码侧看Exceeded maximum output retries是 PydanticAI 在结构化抽取中对模型多次未按 schema 输出的统一异常表达见 structured_extraction.py仓库测试也专门断言仅报Exceeded maximum output retries本身没有诊断价值必须把原因打进日志见 tests/test_structured_builders.py——这正是文档强调看任务日志底层原因的原因。文本模型超时两个关键环境变量文本模型超时受NEWAPI_TEXT_TIMEOUT_SECONDS控制。文档与环境变量参考标注的默认值为120 秒见 docs/zh/reference/environment-variables.md从源码看config.py中该变量的兜底默认值为 300.0 秒且每个模型还可用{MODEL}_TIMEOUT_SECONDS单独覆盖见 config.py实际生效值以你部署环境的配置为准。遇到超时可将其调大。另一个隐蔽因素是系统代理如果内网网关被系统代理拦截即使调大超时也无济于事。此时设置NEWAPI_TEXT_TRUST_ENVfalse让文本客户端不再读取系统代理。源码中的实现是默认trust_env _env_bool(NEWAPI_TEXT_TRUST_ENV, True)当设为false时构造的httpx.AsyncClient会显式传入trust_envFalse见 config.py。环境变量参考表中该变量的默认值为true见 docs/zh/reference/environment-variables.md。参考图功能依赖对象存储凭据参考图功能不可用时先检查是否配置了OSS_RELAY_AK/OSS_RELAY_SK。这两个变量是对象存储凭据见 config.py在参考图相关的媒体中转与网关设置中都会被读取见 model_gateway_settings.py、storage/media_relay.py。纯文本→成片流程可以完全不配只有需要参考图能力时才必须提供。媒体 / ffmpeg 类故障现象排查合成阶段报找不到 ffmpeg本地开发需自行装 ffmpegDocker 已自带或用FFMPEG_PATH指定路径。见 ffmpeg 指南。合成失败提示编码器不可用默认编码libx264H.264你的 ffmpeg build 须包含它或改VIDEO_CODEC。成片黑屏 / 时长异常多为上游图片/音频产物缺失回看前序环节日志确认素材已生成。ffmpeg 找不到Docker 与本地开发的差异Docker 镜像自带 ffmpeg容器内合成通常不会遇到该问题本地开发需要自行安装 ffmpeg。如果 ffmpeg 装在非标准位置用FFMPEG_PATH显式指定可执行文件路径即可。源码中该变量的默认值是ffmpeg即依赖 PATH 查找见 config.py环境变量参考表中的默认描述同为从 PATH 找见 docs/zh/reference/environment-variables.md。更完整的安装与验证方法见 ffmpeg 指南。编码器不可用libx264 与 VIDEO_CODEC成片默认编码为H.264 /libx264VIDEO_CODEC的默认值源码见 config.py参考表见 docs/zh/reference/environment-variables.md。如果你的 ffmpeg build 未包含libx264编码器合成必然失败。两个出路更换一个包含libx264的 ffmpeg build修改VIDEO_CODEC为你 build 实际支持的编码器H.264 仍是兼容性最好的默认选择。成片黑屏 / 时长异常回查前序素材成片黑屏或时长不对通常是上游图片/音频产物缺失导致。合成只是流水线的最后一棒如果前序的图像生成、音频生成环节有任务失败或产物丢失成片就会缺素材。排查方式是回看前序环节日志逐段确认图片、音频等素材确实生成成功再回头找合成阶段的异常。数据 / 升级类故障现象排查重建后数据没了数据在命名卷ce-data容器内/data。docker compose down保留卷别加-v会删卷。备份见自托管手册。unable to prepare context: path .../dramaclaw-gateway not found源码构建要求网关 checkout 放在本仓旁边。git clone https://github.com/dramaclaw/dramaclaw-gateway.git ../dramaclaw-gateway或在.env里把DRAMACLAW_GATEWAY_SRC设成你的 clone 路径或https://github.com/dramaclaw/dramaclaw-gateway.git#main。升级后报配置错误源码构建docker-compose.ymlgit -C ../dramaclaw-gateway pull git pull docker compose up -d --build。镜像模式docker-compose.release.ymldocker compose -f docker-compose.release.yml pull docker compose -f docker-compose.release.yml up -d如果在.env里钉了DRAMACLAW_VERSION/DRAMACLAW_GATEWAY_VERSION先改版本号。详见自托管手册 §6。重建后数据丢失ce-data 卷的保命守则DramaClaw 的全部持久化数据——项目数据库、设置和生成媒体——都在命名卷ce-data容器内挂载为/data见 docker-compose.yml 与 docker-compose.release.yml。因此docker compose down只停容器、保留卷重建后数据完好千万不要加-vdocker compose down -v会连同命名卷一起删除数据不可恢复只有显式执行docker compose down -v才会删除数据卷。备份与恢复的完整步骤含用docker run --rm -v dramaclaw-ce_ce-data:/data ...打包/解包数据卷的 tar 命令见自托管手册。Docker Compose 还把它固定在/data/output作为成片与产物输出目录同样由ce-data卷持久化见 docs/zh/reference/environment-variables.md。网关 checkout 缺失unable to prepare context源码构建模式下docker-compose.yml的构建上下文默认指向本仓旁边的网关仓库context: ${DRAMACLAW_GATEWAY_SRC:-../dramaclaw-gateway}见 docker-compose.yml。如果那个目录不存在构建就会以unable to prepare context: path .../dramaclaw-gateway not found失败。两种解法把网关 clone 到本仓旁边git clone https://github.com/dramaclaw/dramaclaw-gateway.git ../dramaclaw-gateway用.env指定源把DRAMACLAW_GATEWAY_SRC设成你的 clone 路径或直接给 git 地址让 Docker 拉取# .env DRAMACLAW_GATEWAY_SRC/path/to/your/dramaclaw-gateway # 或 DRAMACLAW_GATEWAY_SRChttps://github.com/dramaclaw/dramaclaw-gateway.git#main从源码结构看网关是独立维护的仓库本仓通过该环境变量决定构建上下文因此两种方式都只是告诉 Docker去哪找网关。升级后报配置错误两套升级流程升级方式取决于你用的是哪套 compose 文件两者命令不同源码构建docker-compose.yml——本仓与网关都是 git checkout先各自拉取再重建git -C ../dramaclaw-gateway pull git pull docker compose up -d --build镜像模式docker-compose.release.yml——直接拉新镜像并重建容器docker compose -f docker-compose.release.yml pull docker compose -f docker-compose.release.yml up -d注意如果之前在.env里钉了DRAMACLAW_VERSION/DRAMACLAW_GATEWAY_VERSION升级前要先改版本号否则拉取/构建的仍是旧版本。完整升级与配置说明见自托管手册§6含.env 不会被升级触碰、ce-data与newapi-data卷原样复用的说明。world 特性3DGS/SHARP类故障现象排查报FileNotFoundError指向BuilderGPT/...这些重特性脚本不在 CE 精简包内纯文本→成片不需要走 3D/体素流程才需补齐。uv sync --extra world安装失败需用 uv非 pip以使依赖 override 生效GPU 加速需 CUDA 环境slim/CPU 环境仅 CPU 路径。world 特性3DGS/SHARP 等属于重负载的可选能力FileNotFoundError指向BuilderGPT/...这些重特性脚本不在 CE 精简包内。纯文本→成片流程完全不需要它们只有走 3D/体素流程才需要补齐对应文件。uv sync --extra world安装失败必须使用uv而非 pip安装否则依赖 override 不会生效同时GPU 加速依赖 CUDA 环境slim/CPU 环境只能走 CPU 路径。还没解决求助渠道如果以上对照表仍未命中你的场景按问题性质选择渠道用法 / 想法到项目 GitHub Discussions 讨论区提问附上你执行的命令与现象确认是 Bug按 Bug 模板提交 issue务必附上日志、复现步骤和环境信息版本、操作系统、部署方式等这三样缺一不可安全问题不要走公开 issue按 SECURITY 中的流程私下报告。提交前建议先跑一遍docker compose logs api或本地novelvideo api输出把关键日志片段直接贴进工单能显著加快定位。相关阅读安装指南 快速开始 自托管手册配置模型供应商 ffmpeg 指南 环境变量参考赞分享【免费下载链接】dramaclawA general-purpose AIGC video engine: script to finished film in one pipeline — dramas, ads, product videos, otome games, and more. | 通用 AIGC 视频引擎 —— 从剧本到成片一条流水线漫剧、广告、电商、乙游皆可项目地址https://gitcode.com/gh_mirrors/dr/dramaclaw点击查看免费下载相关推荐DramaClaw CE 自托管部署指南Docker 三容器编排、模型网关与数据备份恢复实战DramaClaw CE 自托管部署指南Docker 三容器编排、模型网关与数据备份恢复实战 本文以 DramaClaw CE社区版的 docs/zh/gDLSS Swapper 使用指南如何完整替换并回退游戏内的 DLSS 版本DLSS Swapper 使用指南如何完整替换并回退游戏内的 DLSS 版本 DLSS Swapper 是一款 Windows 开源工具用于下载、管理并替换桌面应用kafka-docker常见问题排查手册从启动失败到数据丢失kafka docker常见问题排查手册从启动失败到数据丢失 Apache Kafka作为现代分布式系统的核心消息队列在容器化部署时经常会遇到各种问题。消息队列后端云原生上一篇深度解析 team_create 双参冲突死循环基于 Oh My OpenAgent 的 inline_spec 优先级修复实证下一篇Fleet 日志目的地配置指南从 Filesystem 到 Firehose、Splunk、Kafka 与 Pub/Sub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考