跳到主要内容

常见问题

本文汇总 ArcReel 当前版本中最常见的安装、配置、制作与排障问题。第一次使用时，建议先阅读完整入门教程。具体供应商和模型能力以设置页当前显示为准。

使用 ArcReel 前需要了解哪些能力边界？​

  • 媒体生成依赖第三方模型服务，生成速度、可用性、内容策略和成本受供应商影响。
  • 长篇内容仍需要人工审核分集、角色资产和关键剧情节点，ArcReel 的目标是增强创作者，而不是完全取消审核。
  • 不同视频模型对参考图数量、视频时长、首尾帧、音频和地区可用性的支持不同。
  • Windows 原生环境可以运行部分基础流程，但 Agent 沙箱等 POSIX 能力会降级；优先使用 Linux、macOS、WSL2 或 Docker。
  • 生产环境应使用 PostgreSQL、HTTPS、强密码和定期备份，不建议直接把未加保护的 1241 端口暴露到公网。

安装、部署与更新​

推荐怎样安装？Windows 可以直接运行吗？​

普通用户优先使用 Docker。推荐环境为 Linux、macOS、WSL2 或 Docker Desktop：

git clone https://github.com/ArcReel/ArcReel.git
cd ArcReel/deploy
cp .env.example .env
docker compose up -d

启动后访问 http://localhost:1241；部署在其他主机上时，将 localhost 换成主机地址。

Windows 原生环境可以运行项目创建等基础流程，但 Agent 沙箱会降级，生产部署仍建议使用 WSL2 或 Docker Desktop。Linux/macOS 本地运行需要可用的系统沙箱工具，详见部署补充说明。

Docker 启动后打不开，或者容器反复重启怎么办？​

在实际使用的 deploy/ 或 deploy/production/ 目录执行：

docker compose ps
docker compose logs arcreel

依次检查：

  1. Docker 服务是否正常，ArcReel 容器是否通过健康检查。
  2. 端口 1241 是否已被其他程序占用。
  3. .env 是否存在且容器有权读取；生产部署还必须设置 POSTGRES_PASSWORD。
  4. 日志是否包含 SANDBOX_UNAVAILABLE、SANDBOX_BWRAP_BROKEN 或更具体的修复提示。
  5. 供应商 API Key 是否误放在 .env 中。供应商凭据应在 Web 设置页保存，否则服务会拒绝启动。

不要为了绕过沙箱错误直接把容器改成特权模式；应先按启动日志修复宿主机的 user namespace、AppArmor 或沙箱依赖。

默认登录账号是什么？忘记密码怎么办？​

默认用户名是 admin，可通过 .env 中的 AUTH_USERNAME 修改。AUTH_PASSWORD 留空时，首次启动会生成密码并回写到当前部署目录的 .env，不会把明文密码打印到日志。

忘记密码时，修改 .env 中的 AUTH_PASSWORD。Docker 部署需要重建容器以重新载入环境变量：

docker compose up -d --force-recreate

源码部署则重启 ArcReel 服务。不要在公网部署中关闭身份认证。

Docker 怎样更新？更新会丢失项目吗？​

先完成备份，再在对应的 Compose 目录执行：

docker compose pull
docker compose up -d

ArcReel 启动时会自动执行数据库与项目结构迁移。正常更新不会主动删除已挂载的数据目录，但更新前仍应备份项目目录、数据库和凭据文件。不要使用会删除数据卷的清理命令代替普通更新。

设置页的“关于”区域可以检查新版本并打开发布页，但不会在网页中自动升级服务器。

项目和配置存在哪里？怎样备份或迁移？​

默认 Docker 部署的主要数据位于 Compose 目录：

  • projects/：项目、素材和默认 SQLite 数据库
  • .env：登录与部署配置
  • vertex_keys/：Vertex 凭据文件
  • claude_data/：Agent 会话数据

生产 PostgreSQL 部署还需要备份 PostgreSQL 数据库。全站备份应同时覆盖项目目录、数据库与所需凭据；PostgreSQL 使用 pg_dump / pg_restore，SQLite 应在停止服务后复制，或使用 SQLite 在线备份机制。

Web UI 的项目 ZIP 适合迁移单个项目，但不包含全局供应商配置、账号配置、任务记录、费用记录或 Agent 会话，因此不能代替全站备份。

首次配置与智能体​

开始制作前需要配置哪些凭据？​

ArcReel 智能体与内容生成使用两套独立配置：

  • 智能体供应商负责对话、分析原文和编排制作任务，需要一个可用且已激活的智能体凭据。
  • 生成供应商负责文本、图片、视频和语音生成，需要为实际使用的模态分别配置供应商与模型。

只配置智能体凭据不会自动获得生图或视频能力；只配置生成供应商也无法启动项目内的 AI 助手。项目级生成模型设置优先于全局默认，排障时要确认项目实际选中的供应商和模型。

预置生成供应商和智能体供应商可保存多条凭据，但运行时只使用当前标记为“激活”的一条，不会自动轮换；测试某条凭据也不等于已经激活它。每个自定义供应商当前保存一条 API Key。

怎样让 AI 助手开始或继续制作？​

在项目右侧打开 AI 助手，直接说明“开始制作”或“继续制作”即可。助手会检查项目当前状态，从尚未完成的阶段继续，并在需要审核剧本、资产或分镜时等待确认。

如果助手提示未登录、无法启动或没有可用模型，先到设置页确认智能体凭据已经保存、消息调用探测成功且处于激活状态。模型发现告警不一定阻断消息调用，但应核对实际模型 ID。无需在助手面板另行登录 Claude 网页账号。

出现 Failed to start Claude Code、启动超时或 Control request timeout 怎么办？​

这些提示表示 Agent 进程没有正常启动或未能及时完成初始化，不等同于剧本内容错误。依次检查：

  1. 智能体凭据是否已激活，模型 ID 是否与服务端实际开放的 ID 完全一致。
  2. Docker 容器或服务器能否访问智能体 API，代理、DNS 和 TLS 是否正常。
  3. Docker/WSL/本地环境的 Agent 沙箱是否通过启动检查。
  4. 在设置页“关于”中下载诊断日志，查看错误发生时间附近的具体上游状态码。

连接测试只代表最小请求成功；长会话仍可能受到额度、上下文长度、限流或代理超时影响。

供应商、模型与 API​

ArcReel 支持哪些供应商和模型？​

支持范围以设置页当前的预置供应商、模型列表和能力标记为准。一个供应商被支持，不代表它的所有模型、账号区域和输入形式都可用；图片、视频、文本、语音以及参考图、尾帧、时长和分辨率能力都按具体模型判断。

不要仅根据模型名称猜测能力。新增或调整模型后，应重新确认其媒体类型、调用端点和账号权限。

Base URL 应该怎样填写？​

优先选择预置供应商，让 ArcReel 使用内置地址。自定义供应商应填写服务商 API 文档给出的协议根地址，不要填写控制台网页地址，也不要盲目为所有地址追加同一个 /v1 或 /v1/messages 后缀。

如果返回 404 page not found，通常应核对：

  1. 当前选择的是哪种发现协议和调用协议。
  2. Base URL 是否指向正确区域和 API 根路径。
  3. 服务端是否真的实现了对应的模型列表和生成端点。

怎样接入自定义供应商？​

在设置页添加自定义供应商，填写 Base URL、API Key 和模型发现协议，然后获取模型列表。发现失败时可以手动添加模型，但仍需逐个确认媒体类型与调用端点，再启用并设为全局或项目模型。

模型发现协议只负责列出模型和执行基础连接测试；真实运行使用的是每个模型配置的调用端点。第三方服务能返回模型列表，不代表它完整实现了图片、视频、参考图、异步轮询或结构化输出协议。ArcReel 不对所有声称兼容某协议的服务作可用性承诺。

获取模型列表失败，或者出现 model_not_found 怎么办？​

按以下顺序检查：

  1. 使用服务端公布的精确模型 ID，不要使用展示名称。
  2. 确认 Base URL、账号区域与 API Key 匹配。
  3. 确认账号已开通该模型，并有相应模态的调用权限。
  4. 确认模型已启用，媒体类型和调用端点配置正确。
  5. 检查项目级设置是否仍覆盖着旧模型。

部分兼容服务没有实现模型列表接口，此时可以手动登记模型；但如果真实调用仍返回 404，应由服务提供方确认路由和权限。

为什么连接测试成功，实际生成仍然失败？​

连接测试主要验证凭据、网络和模型发现是否可用，不会完成一次真实的付费图片或视频生成，因此无法覆盖：

  • 模型的生成权限、余额和并发额度
  • 参考图、尾帧、分辨率、宽高比和时长限制
  • 自定义模型的媒体类型与调用端点
  • 异步任务的轮询和结果下载

先确认项目实际使用的供应商和模型，再查看失败任务中的完整上游状态码与错误信息。

遇到 401/403、429 或网络超时怎么办？​

  • 401/403：检查 API Key 是否有效、是否与 Base URL/区域匹配，以及账号是否开通目标模型。
  • 429：检查余额、套餐额度、RPM 和并发限制；降低对应图片、视频或语音通道的并发，等待额度窗口恢复后再试。
  • 网络或超时：从部署 ArcReel 的服务器检查 DNS、TLS、代理和 API 域名连通性。浏览器能访问不代表服务器容器可以访问。

提交生成请求后发生读超时，可能出现“上游已经创建并计费，但 ArcReel 没收到响应”的不确定状态。不要连续盲目重试，应先到供应商控制台检查是否已有任务，避免重复计费。

项目流程与任务​

项目模式以及分镜、宫格和参考生视频路线怎样选择？创建后能改吗？​

创建时需要分别确定两个维度：

  • 内容模式：说书、剧集动画或广告/短片，决定剧本结构和制作流程。
  • 视频生成路线：分镜路线或参考生视频路线，决定视频使用分镜图还是资产参考图。

内容模式和视频生成路线创建后不可更改。宫格不是第三条路线，而是分镜路线中的出图方式；广告/短片项目不支持宫格。创建前请先用短样本确认路线是否符合预期。

  • 分镜路线：剧本 → 角色/场景/道具设计图 → 分镜图 → 视频。生成视频前必须有对应分镜图。
  • 宫格：仍属于分镜路线。系统先生成宫格并切分成各镜头的起始分镜，再由分镜图生成视频。
  • 参考生视频路线：跳过分镜图，直接使用剧本引用的角色、场景和道具设计图作为视频参考。

参考生视频不等于不需要资产图。说书和剧集项目引用的资产缺少设计图时，相关视频会失败；广告/短片缺少产品参考图时，即使任务能够继续，产品还原度也无法保证。

如果视频供应商只收到文本，没有收到分镜或参考图，先确认项目路线、实际模型和自定义模型的调用端点：

  1. 分镜路线会把该镜头的分镜图作为视频起始图。
  2. 参考生视频路线会收集剧本引用的资产设计图。
  3. 所选视频模型及调用端点必须明确支持对应的图生视频或参考生视频能力。

如果自定义模型只登记了文生视频端点，或者能力声明与上游实际接口不一致，ArcReel 无法把参考图按正确协议传给服务端。

源文件支持哪些格式？​

当前支持 .txt、.md、.docx、.epub 和 .pdf。上传后会统一抽取为 UTF-8 文本。

扫描版 PDF 没有可提取文本时不能直接使用，应先进行 OCR；旧式 .doc 文件请先转换为 .docx。如果 TXT/Markdown 出现乱码，请转换为常见文本编码后重新上传。

为什么下一阶段不能进入，或助手没有继续执行？​

通常是前置审核或资产尚未完成：

  1. 说书/剧集项目检查剧本预处理结果是否已确认；确认后再次编辑需要重新确认。广告/短片项目没有这一步。
  2. 检查角色、场景和道具是否只有定义而没有已生成的设计图。
  3. 分镜路线检查目标镜头是否已有分镜图。
  4. 参考生视频路线中，说书/剧集项目检查被引用资产的设计图是否齐全；广告/短片项目至少确认产品原图已上传，缺少参考图虽可能不阻塞任务，但会降低产品保真度。
  5. 展开任务面板，确认是否仍有排队、运行或失败的任务。

不要仅根据顶部阶段编号判断完成状态；左侧资产、剧集状态和任务错误会提供更具体的缺失项。

任务排队、运行、失败、取消或服务重启后应该怎么办？​

图片、视频和语音使用独立任务通道。排队或运行中的单个任务可以取消；运行任务会先进入“取消中”。取消存在依赖关系的任务时，界面会提示可能受影响的下游任务。取消运行中任务只停止 ArcReel 侧处理；上游任务可能仍会继续，已经产生的费用不会自动退回，必要时应到供应商控制台核对。

任务面板没有适用于所有任务类型的统一重试按钮。失败后先展开错误信息并修正配置或输入，再回到对应资产、分镜或视频入口重新生成。不要在原因未明时重复点击生成。

批量任务部分失败时，不需要把已成功的内容全部重做。资产、分镜和整集视频生成会按缺失项补齐，已成功结果不会因单项失败被删除。服务重启后，可安全恢复且已记录上游任务 ID 的视频任务会继续轮询；无法恢复的任务会标记失败，等待用户决定是否重新提交。

为避免重复计费，系统不会无条件把所有运行中任务重新入队。重新生成前先检查已有结果和供应商控制台任务。

画面、视频与声音​

怎样提高角色一致性？​

  1. 先生成并审核角色设计图，再批量生成分镜和视频。
  2. 确认剧本中的目标镜头实际引用了该角色。
  3. 修改角色设计图后，重新生成受影响的分镜和视频；旧结果不会自动更新。
  4. 先用少量镜头验证所选模型的参考图能力，再扩大批量。

生成分镜时，ArcReel 会把该镜头引用的角色、场景和道具设计图作为参考；分镜路线的视频再以分镜图作为首帧，参考生视频路线则直接使用资产图。生成模型仍无法保证逐帧绝对一致。

怎样让相邻镜头更连贯？​

在分镜路线中，非首镜头、未标记为新段落且上一张分镜已经生成时，系统会把上一张分镜作为衔接参考。它有助于延续构图、色调和场景，但不能保证两个独立生成的视频无缝拼接。

先锁定资产和分镜再生成视频，确保相邻镜头的地点、时间、服装和出场角色描述一致。重要转场可以使用支持尾帧的模型，或在剪映等后期工具中处理。

首帧和尾帧怎样使用？​

分镜路线中的分镜图就是视频首帧。每个镜头还可以选择或上传尾帧，但只有当前视频模型明确支持尾帧时才能生成；不支持时系统会拒绝请求，而不是静默忽略。

参考生视频路线没有独立尾帧设置。更换分镜或尾帧后，已有视频不会自动更新，需要重新生成对应视频。

为什么场景设计图里出现了人物？​

场景设计图的提示词会要求画面中不出现人物，但图片模型仍可能不完全遵循约束。此时重新生成场景图，或使用指令式图片编辑移除人物。

场景设计图与剧情分镜图不同：场景设计图应聚焦环境，分镜图则会根据剧情显示人物。

ArcReel 支持配音吗？​

当前 Web UI 的独立旁白 TTS 仅对说书模式开放，可逐段试听或生成全集旁白，并随剪映草稿导出。语音供应商、音色和语速可在全局或项目设置中配置；部分模型不支持语速调整。

视频模型自带人声、角色参考音频和独立旁白 TTS 是不同能力。角色参考音频目前用于参考生视频路线，并且所选视频模型必须明确支持参考音频；分镜路线及仅有声音描述时属于软约束，不能保证跨片段音色完全一致。

费用、数据与导出​

在哪里查看费用和 Token？怎样控制成本？​

项目费用面板会显示图片、视频、文本和音频调用，以及预估与实际费用；设置页可按时间和供应商查看调用统计。

预估依据当前模型的价格声明和项目结构，不等于供应商最终账单。自定义供应商未填写价格、供应商未返回 usage 或价格未登记时，费用可能不完整或显示为 0。不同币种应分别核对，不要直接相加。最终金额以供应商账单为准。

先用少量镜头验证模型、提示词和参考图效果，再批量生成；每个阶段审核通过后再进入下一阶段，避免资产错误扩散造成大面积返工。生成超时后先检查供应商控制台是否已有任务，不要连续重试。

不存在适用于所有项目的固定“每分钟价格”。应结合项目费用预估、实际调用明细和供应商账单评估。

项目 ZIP 与全站备份有什么区别？​

项目 ZIP 用于导入、迁移单个项目，可以选择仅导出当前版本或包含完整版本历史。它不包含全局供应商设置、登录配置、任务与费用记录或 Agent 会话。

需要灾难恢复时，请使用前文的全站备份方式，同时保存项目目录、数据库与所需凭据。

剪映草稿为什么看不到，或者缺少片段？​

导出时选择与本地剪映匹配的 5.x 或 6+ 格式，将 ZIP 直接解压到剪映草稿目录，并重启剪映。草稿只包含已成功生成的视频片段；缺失片段应先回到 ArcReel 补生成再导出。

当前说书模式导出小说原文字幕，广告/短片模式导出口播字幕，剧集模式导出台词与画外音字幕；说书模式还会带上已生成的旁白音轨。完整步骤见剪映草稿导出指南。

有手机 App 吗？支持哪些平台？​

ArcReel 是自托管 Web 应用，目前没有独立的 iOS 或 Android 原生 App。手机可以尝试通过浏览器访问，但不承诺完整的移动端编辑体验。

服务器推荐 Linux、macOS、WSL2 或 Docker。Windows 原生环境只保证项目创建与基础流程，正式部署建议 WSL2 或 Docker Desktop。

可以商用或二次开发吗？​

ArcReel 按 AGPL-3.0 发布，并附带 NOTICE 中的署名和修改声明要求。ArcReel 名称与 Logo 不在 AGPL-3.0 授权范围内。

如果希望在不承担 AGPL 开源义务的前提下进行商业使用，请联系 support@arc-reel.com 了解商业授权。具体项目是否合规应由使用者根据实际分发和部署方式自行评估；本说明不构成法律意见。

故障诊断与求助​

只显示“服务器内部错误”，怎样找到真正原因？​

前端的通用错误提示无法说明根因。先展开任务错误，再查看服务端日志和供应商返回的状态码。Docker 部署可在 Compose 目录执行：

docker compose logs arcreel

也可以在设置页“关于”中下载诊断日志。诊断包会尝试遮蔽系统摘要中的已知凭据，但不会在下载时对已有日志再次全文脱敏；分享前必须人工检查整个诊断包，并删除 API Key、Token、密码、完整 .env、私人接口地址和项目内容。

怎样提交一个可以有效排查的问题？​

提交 GitHub Issue 或寻求社区帮助时，请提供：

  • ArcReel 版本
  • 操作系统以及 Docker、WSL 或源码部署方式
  • 失败的具体步骤和可重复操作
  • 实际选择的供应商、模型与任务类型
  • 错误发生时间、短错误关键词、上游状态码和任务 ID
  • 已人工脱敏的相关日志

不要公开 API Key、Token、密码、完整 .env 或未经检查的诊断包。只有截图和“这个怎么处理”通常不足以定位问题。

效果与成本最佳实践​

“哪个模型最好”“怎样做到 100% 角色一致”“视频怎样绝对无缝”等问题没有适用于所有项目的固定答案。建议采用可验证的小步流程：

  1. 用少量镜头测试目标模型的画风、参考图、时长和审核限制。
  2. 先确定角色、场景和道具设计图，再批量生成分镜。
  3. 让相邻镜头保持地点、时间、服装和角色描述一致。
  4. 只引用当前镜头真正需要的资产，避免参考图过多稀释约束。
  5. 重要转场使用支持尾帧的模型，或交给后期编辑。
  6. 用项目预估规划预算，并以实际调用明细和供应商账单复核。