部署与运维

本文档说明 ArcReel 的默认部署、PostgreSQL 生产部署、环境变量、数据持久化、升级、备份、恢复、反向代理和故障排查。正式支持边界见 安全政策，完整信任边界见 安全威胁模型。

部署方式选择

场景	推荐方式	数据库	说明
首次体验、个人轻量使用	deploy/	SQLite	配置最少，启动最快
长期运行、并发访问、正式服务	deploy/production/	PostgreSQL	更适合并发、备份和运维，但不提供用户隔离
本地开发	源码启动	SQLite 或 PostgreSQL	见贡献指南

无论选择哪种方式，项目图片、视频和其他生成资产都需要持久化保存。

ArcReel 当前按单一可信操作员设计，不支持互不信任的用户共享实例。PostgreSQL 生产部署不会增加租户隔离、角色权限或按用户划分的项目授权。

1. 默认部署：SQLite

1.1 启动

git clone https://github.com/ArcReel/ArcReel.git
cd ArcReel/deploy

cp .env.example .env

编辑 .env：

AUTH_USERNAME=admin
AUTH_PASSWORD=请设置强密码
AUTH_TOKEN_SECRET=请设置长期固定的随机密钥
# LOG_LEVEL=INFO

生成随机密钥：

openssl rand -hex 32

启动：

docker compose up -d

验证：

docker compose ps
docker compose logs --tail=100 arcreel
curl http://localhost:1241/health

1.2 持久化目录

默认 Compose 会挂载：

宿主机路径	容器路径	内容
deploy/.env	/app/.env	认证和运行配置
deploy/projects/	/app/projects	数据根：项目、生成资产、默认 SQLite 数据库、日志、Vertex AI 凭据等全部运行数据
deploy/claude_data/	/root/.claude	Agent 运行时相关数据

deploy/projects/ 是 ArcReel 的数据根（ARCREEL_DATA_DIR，容器内为 /app/projects）。项目收在其中的 projects/ 子目录里，其余运行数据与之并列：

deploy/projects/               数据根
├── projects/<项目名>/         项目与生成资产
├── global_assets/             全局资产库
├── users/<user_id>/memory/    Agent 用户记忆
├── arcreel.db                 默认 SQLite 数据库（连同 -wal / -shm）
├── logs/                      应用日志
├── vertex_keys/               Vertex AI 凭据文件
├── trial_runs/                端点「测试连接」的产物
└── runtime/                   迁移完成标记、生成准入锁等运行时状态

只有 projects/ 下名字由英文字母、数字或中划线组成、并且包含 project.json 的目录才算项目，数据根里的其它条目不会出现在项目列表中。设置页「关于」中下载的诊断日志会列出数据根及上述各类数据的实际位置。

备份时归档整个数据根，不要只备份数据库而忽略项目文件。数据库保存任务、配置和索引信息，项目目录保存原始素材和生成文件，两者需要保持一致。

2. 生产部署：PostgreSQL

2.1 启动

cd "$(git rev-parse --show-toplevel)/deploy/production"
cp .env.example .env

编辑 .env：

AUTH_USERNAME=admin
AUTH_PASSWORD=请设置强密码
AUTH_TOKEN_SECRET=请设置长期固定的随机密钥
POSTGRES_PASSWORD=请设置数据库密码
# LOG_LEVEL=INFO

推荐生成只含十六进制字符的密码：

openssl rand -hex 16

默认 Compose 会把 POSTGRES_PASSWORD 的原始值交给 PostgreSQL，同时把它拼入 DATABASE_URL 的密码段。如果密码含有 @、:、/、?、#、% 等 URL 保留字符，连接 URI 中的密码必须做百分号编码。不要把编码后的值直接填入 POSTGRES_PASSWORD：PostgreSQL 需要原始密码，只有 URI 需要编码。

当必须使用特殊字符时，在 .env 中分开保存原始值与编码值：

POSTGRES_PASSWORD='p@ss/word'
POSTGRES_PASSWORD_URLENCODED=p%40ss%2Fword

然后把 deploy/production/docker-compose.yml 中 DATABASE_URL 的密码部分改为 ${POSTGRES_PASSWORD_URLENCODED}；PostgreSQL 容器的 POSTGRES_PASSWORD 仍保持不变。可用 urllib.parse.quote(raw_password, safe="") 生成编码值。如果不想维护这项 Compose 改动，就使用上述十六进制密码。

启动：

docker compose up -d

验证：

docker compose ps
docker compose logs --tail=100 postgres
docker compose logs --tail=100 arcreel
curl http://localhost:1241/health

2.2 PostgreSQL 持久化目录

宿主机路径	内容
deploy/production/pgdata/	PostgreSQL 数据目录
deploy/production/projects/	数据根：项目、媒体资产、日志、Vertex AI 凭据等，布局与默认部署相同，不含数据库
deploy/production/claude_data/	Agent 运行时数据
deploy/production/.env	认证和数据库配置

pgdata/ 只保存 PostgreSQL 集群数据，projects/ 是数据根，保存项目元数据、媒体资产和其余运行数据，两者都必须持久化且配套备份。生产部署通过 DATABASE_URL 使用 PostgreSQL，不会使用 deploy/production/projects/arcreel.db；不要把 SQLite 文件复制进 pgdata/，也不要把两个目录当成可相互替代的数据库备份。

2.3 数据库迁移

ArcReel 在应用启动时运行 Alembic 迁移，将数据库结构升级到当前版本。

启动时还会将可确认归属项目的历史调用记录产物路径改为项目内相对路径，以便移动数据目录后费用明细仍能显示缩略图；无法确认项目根的旧路径会保留并写入启动日志。排队中的旧文本任务按启动时的当前数据目录执行，载荷里的旧目录不再生效。

升级前仍然必须备份。自动迁移解决的是结构升级，不代替可回滚的数据备份。

3. 环境变量

默认部署示例当前包含以下核心变量：

变量	默认值	建议
AUTH_USERNAME	admin	可修改管理员用户名
AUTH_PASSWORD	空	正式部署必须显式设置强密码
AUTH_TOKEN_SECRET	空	正式部署必须设置长期固定随机值
AUTH_ENABLED	true	远程部署不得关闭；设为 false 时全部管理接口无需认证
LOG_LEVEL	INFO	排障时临时改为 DEBUG，完成后恢复
POSTGRES_PASSWORD	无	仅生产部署需要，必须设置
TZ	Asia/Shanghai	可在 Compose 环境中覆盖
DATABASE_URL	SQLite 默认路径	生产 Compose 自动设置 PostgreSQL URL
ARCREEL_DATA_DIR	projects	数据根；项目、默认 SQLite 数据库、日志和 Vertex 凭据都在其下
CORS_ORIGINS	通配	设为白名单时，浏览器型 MCP 客户端的 Origin 也须列入
MCP_PUBLIC_URL	http://localhost:1241/mcp	可选；仅 OAuth 发现型 MCP 客户端需要

注意：

• AUTH_TOKEN_SECRET 变化后，现有登录 Token 会失效。
• AUTH_ENABLED=false 仅适用于受独立网络边界保护的本机环境。Compose 默认把 1241 端口发布到宿主机所有网卡，远程部署不得关闭认证。认证关闭时，启动日志会输出 WARNING。
• .env 中可能包含密钥，不要提交到版本库。
• Vertex 凭据文件应只授予运行 ArcReel 的用户读取权限。
• 文件日志固定写入数据根下的 logs/。旧变量 ARCREEL_LOG_DIR 已不再生效，仍设置时启动日志会提示一次；只需要 stdout 日志时设置 ARCREEL_LOG_FILE_DISABLED=true。
• 第三方模型 API Key 通常在 ArcReel 设置页中管理，不要写入公开文档。

远程 MCP 端点为 /mcp，始终要求 arc- 前缀 API Key；即使 AUTH_ENABLED=false 也不会匿名放行。外部接入不需要额外的 MCP_* 配置：把设置页「外部智能体接入」弹窗给出的端点地址与 API Key 填进客户端即可，通过保留 SSE 长连接的 HTTPS 反向代理、VPN 或安全隧道访问。

服务端不校验请求的 Host 头，端点边界由每请求强制的 API Key 承担；域名归属交给部署形态，请在反向代理上限定 server_name（Nginx）或等价规则，只把预期域名的请求转发给 ArcReel。

CORS_ORIGINS 保持默认通配时，浏览器型 MCP 客户端同样无需配置；一旦收紧为白名单，就要把该客户端的 Origin 也列进去——这一个白名单同时约束应用 API 与 MCP 端点，不存在第二份 MCP 专用清单。MCP_PUBLIC_URL 只用于填写 OAuth 受保护资源元数据（RFC 9728）与 401 challenge，供做发现流程的客户端读取；以 Bearer 直连的 Claude Code、codex 等客户端不会用到，可以不设。

ArcReel 的沙箱要求父进程环境中不保留供应商密钥。以下凭据环境变量存在非空值时，服务会拒绝启动并提示迁移到 WebUI 设置页：

• ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
• ARK_API_KEY / XAI_API_KEY / GEMINI_API_KEY / VIDU_API_KEY
• DASHSCOPE_API_KEY / MINIMAX_API_KEY / AGNES_API_KEY / OPENAI_API_KEY
• GOOGLE_APPLICATION_CREDENTIALS（Vertex 凭据在设置页上传，保存在数据根下的 vertex_keys/）

ANTHROPIC_BASE_URL、模型名等非密钥配置不会单独触发启动拒绝，但仍建议与对应凭据一起在 WebUI 中管理。

4. 健康检查和日志

4.1 健康检查

Compose 使用：

GET /health

手动检查：

curl -f http://localhost:1241/health

4.2 查看日志

# 最近 200 行
docker compose logs --tail=200 arcreel

# 持续跟踪
docker compose logs -f arcreel

# 生产数据库日志
docker compose logs -f postgres

文件日志位于数据根下的 logs/，默认部署为 deploy/projects/logs/。

不要在公开 Issue 中直接粘贴完整日志。提交前先清理：

• API Key；
• Token；
• Base URL 中的凭据；
• 用户输入内容；
• 本地文件路径中的隐私信息。

5. 升级

5.1 升级前

1. 阅读 CHANGELOG 和目标 Release 说明；
2. 确认是否存在破坏性变更；
3. 备份数据根和数据库，见备份与恢复；
4. 记录当前镜像版本；
5. 在可接受的维护窗口执行升级。

ArcReel 不支持降级。升级可能改写数据根布局、数据库结构和项目结构，旧版本无法读取升级后的数据；要回到旧版本，需要停止服务并恢复升级前的备份。

5.2 默认部署升级

从数据根布局调整之前的版本升级时，先沿用原来的 Compose 文件执行下面的命令，再按数据根布局迁移切到单卷 Compose。

在 deploy/ 中：

# 先备份，见后文
docker compose pull
docker compose up -d

docker compose ps
docker compose logs --tail=100 arcreel
curl -f http://localhost:1241/health

5.3 生产部署升级

从数据根布局调整之前的版本升级时，同样先沿用原来的 Compose 文件，再按数据根布局迁移切到单卷 Compose。

在 deploy/production/ 中：

# 先备份数据库和数据根 projects/
docker compose pull
docker compose up -d

docker compose ps
docker compose logs --tail=100 postgres
docker compose logs --tail=200 arcreel
curl -f http://localhost:1241/health

应用启动时会执行数据库迁移。不要在没有备份的情况下跳过多个版本直接升级。

5.4 数据根布局迁移

从项目、数据库等平铺在数据根下的旧版本升级时，首次启动会自动把数据根整理成持久化目录一节所示的布局。数据根仍是原来配置和挂载的那个目录，不需要修改环境变量：

• 项目目录搬进数据根下的 projects/。名字合法但没有 project.json 的目录也原样搬入，只是不显示为项目；与 logs、users、runtime 等系统目录同名的目录除外，它们留在原位。名为 projects 的项目搬入后名字不变。
• _global_assets/ 改名为 global_assets/，.arcreel/users/ 搬到 users/，迁移标记等运行时状态收进 runtime/。
• 数据根上一级 vertex_keys/（Docker 中为 ./vertex_keys 卷）里的凭据并入数据根下的 vertex_keys/：凭据记录对应的文件按凭据编号保存为 vertex_cred_<凭据编号>.json，其余 .json 文件保持原名。
• 已有的 Agent 会话、全局资产、Vertex 凭据、费用记录和排队中的任务随之改写，升级后照常可用。

这些步骤逐步执行，每一步都可以安全重跑：容器被杀或进程崩溃后，下次启动会接着完成。全部完成后在 runtime/ 写入完成标记，之后每次启动只检查这个标记。某一步失败时，启动日志记录 ERROR，服务停止启动，不会在半迁移的布局上继续运行；按日志处理后重启即可续跑。例如数据根的 projects/ 下已有与待搬项目同名的目录时，迁移会停下，需要人工确认保留哪一份。全局资产和用户记忆在新位置已有同名文件时不会停下：旧文件留在原位置，启动日志记录告警。

另有两项不受完成标记控制，每次启动都会检查：

• 默认 SQLite 数据库 .arcreel.db（连同 -wal / -shm）改名为 arcreel.db。这一步在解析数据库地址时完成，先启动应用还是先运行 Alembic 都会连到原来的库。新旧两个文件同时存在时不改名，继续使用 arcreel.db，启动日志记录告警。设置了 DATABASE_URL（含 PostgreSQL）时不动数据库。
• 原先代码目录下的日志目录（Docker 中为 ./logs 卷）里的文件并入数据根下的 logs/，新位置已有同名文件时旧文件留在原处。这一步出错只记录日志、不阻止启动。ARCREEL_LOG_DIR 指向的自定义日志目录不会搬动。

升级前备份整个数据根，连同数据根外的旧日志目录与旧凭据目录（Docker 中为 ./logs、./vertex_keys 卷，其余部署为代码目录下的 logs/ 与数据根上一级的 vertex_keys/）；外部数据库另行备份。迁移会把这两处的文件搬进数据根。旧版本会把 projects/ 当成一个项目，也不认识新的数据库文件名；降级需要恢复这份备份。

新版 Compose 只挂载一个数据卷 ./projects，外加 .env 和 claude_data/，不再挂载 ./logs 与 ./vertex_keys。旧卷里的文件只有在启动时仍挂着才会并入数据根，其中 Vertex 凭据只在布局迁移那一次搬入，写下完成标记后不再处理。因此 Docker 部署从旧版本升级分两个阶段（以下以 deploy/ 为例，生产部署换成 deploy/production/）：

1. 沿用原来的 Compose 升级（零配置）。 不改 Compose 文件，按默认部署升级或生产部署升级执行 docker compose pull 与 docker compose up -d。此时两个旧卷仍挂着，首次启动会把其中的文件并入数据根。在启动日志中确认出现「数据根布局迁移完成」，并确认原来的日志和凭据文件已出现在 deploy/projects/logs/、deploy/projects/vertex_keys/ 下（凭据文件名可能已改为 vertex_cred_<凭据编号>.json）。
2. 之后再切到单卷 Compose。 删去 Compose 中 ./logs 与 ./vertex_keys 两行卷（或换用新版 Compose 文件），再执行 docker compose up -d。之后 deploy/logs/、deploy/vertex_keys/ 可以删除；如果其中还有文件（例如数据根里已有同名文件，或旧卷是只读挂载），先确认不再需要。

如果已经换成新版 Compose、但还没有用新版本启动过，首次启动前把这两行卷临时加回去，再按上面两个阶段操作。

如果已经换成新版 Compose 并用新版本启动过，旧卷里的文件不会再自动并入，需要手工补齐。旧卷里的文件由容器以 root 写入，必要时在命令前加 sudo：

# 在 deploy/ 中执行
docker compose stop arcreel

# 设置页上传的 Vertex 凭据保存为 vertex_cred_<凭据编号>.json，ArcReel 按这个文件名读取，拷贝时保持原名
cp -p vertex_keys/vertex_cred_*.json projects/vertex_keys/
chmod 600 projects/vertex_keys/vertex_cred_*.json

# 旧日志放进 logs/ 下的子目录，避免与新版本已写出的 arcreel.log 同名覆盖
mkdir -p projects/logs/pre-upgrade
cp -Rp logs/. projects/logs/pre-upgrade/

docker compose start arcreel

确认设置页中的 Vertex 凭据可以正常使用后，再删除 deploy/logs/、deploy/vertex_keys/。旧目录里不是 vertex_cred_<凭据编号>.json 这种名字的凭据文件不会被读取，对应凭据需要在设置页重新上传。

5.5 项目结构迁移

应用启动时除数据库迁移外，也会逐个升级数据根 projects/ 目录下的项目结构。只有名字由英文字母、数字或中划线组成，且包含 project.json 的目录会被视为项目并参与迁移及过期备份回收。升级到启用产物状态记录的版本时，ArcReel 会先完整校验项目和正式剧本，再一次性写入项目的产物记录，最后才更新 project.json 的 schema 版本。

迁移提交前会在各文件旁创建带 .bak.v<起点版本>-<时间戳> 后缀的备份，覆盖：

• project.json；
• project.json 登记的正式剧本文件；
• 已存在的 .arcreel_artifacts.json；
• 改写版本记录的迁移另备份 versions/versions.json。

迁移可安全重试：如果上次启动在备份或提交中断，下一次启动会重新校验，并确保至少有一份与迁移前内容完全一致的备份后再继续；内容相同的备份只保留一份，反复失败不会堆出多份。自动生成的这些项目级备份只用于迁移恢复，不能代替数据库与整个数据根的部署级备份。

迁移完成后会在项目目录写入 .migration_report.json，记录这次迁移登记了多少产物、跳过了哪些及原因（例如旧版旁白音频没有可投影的合成设置）。它只作说明，不阻断任何操作；制作状态接口的 migration_report 字段原样透出。

早于产物记录机制生成的视频（旧版本记录没有类型化来源字段）由迁移按当时的项目状态补写来源，升级后照常显示与预览；无法补写的视频会列在迁移报告里。

project.json 里没有画面比例字段的剧情演绎项目（很早期版本创建或导入的项目），分镜图按剧情模式的缺省比例 16:9 判断是否最新，与实际生成时一致。这类项目此前按 9:16 登记的分镜图，升级后会显示为已过期；按需重新生成即可。

分镜里引用的资产如果已删除或改名，或者引用的角色、场景、道具没有可登记的资产图（从未生成、文件丢失，或描述为空导致资产图本身未登记），这张分镜图不会被登记：升级后显示为缺失，并列在迁移报告里。商品资产图是可选的：未声明资产图时，可只用原图；也未声明原图时，可只用文字。但已声明的商品资产图不可用，或已声明的商品原图读不到，同样会阻止分镜图登记。按报告补齐资产登记或资产图、重新上传缺失原图或清掉失效的原图字段，再重新生成该分镜图。

资产图与衍生资产图也按生成时的同一口径登记：角色或商品声明了原图但原图读不到，或资产描述为空，这张资产图不会被登记；衍生的本体资产图不能登记时，衍生资产图同样不登记。它们升级后显示为缺失，并列在迁移报告里。重新上传原图或清掉失效的原图字段、补上描述，再重新生成资产图；本体资产图补齐后再重新生成衍生资产图。升级后，原图丢失的角色与商品也不能再生成资产图，处理方式相同。

升级到「内容确认即转出正式脚本」的版本时，迁移按各集的状态收编：

• 脚本规划已确认、但还没有正式脚本的集，按确认过的脚本规划转出正式脚本，全部分镜标为待编写提示词；转不出来的集列在迁移报告里，重新确认脚本规划即可。
• 已有正式脚本的集保留原有内容；视觉提示词为空的分镜标为待编写，剧情演绎分镜缺的视觉改编描述与参考生视频单元缺的对应原文从脚本规划补齐。
• 已有正式脚本、但从未记录过内容确认的集，以当前脚本规划作为已确认的基线；此后重跑脚本规划只会让该集回到待确认，不影响已有正式脚本继续制作。
• 集的剧本绑定只认逐字等于 scripts/episode_N.json 的写法。某一集绑到别的名字（例如 scripts/custom.json），或写成 episode_N.json、./scripts/episode_N.json、scripts\episode_N.json 这类指向同一份剧本但字面不同的形式，又或者同一个集号在 episodes 里出现多条时，该项目直接迁移失败并停在升级前的版本，项目目录一个字节都不被改动，失败记录写明出问题的集号与绑定。按失败记录里的集号找到那份剧本：不在 scripts/episode_N.json 的挪过去，已经在那里、只是绑定写法不同的不用动文件；再把 project.json 里的 script_file 改成逐字 scripts/episode_N.json（重复的集号条目只留一条）后重启即可继续。

有一类迁移需要先在项目目录旁复制一份完整的项目副本，改写完成后再整目录替换。它对磁盘的要求与善后：

• 迁移开始前会核对可用空间，不足以容纳副本时该项目以「磁盘空间不足」失败，项目目录不被改动；清理磁盘后重启即可继续。
• 替换过程中进程被强制终止（断电、kill -9、容器被 OOM 杀掉）时，项目目录可能短暂缺失，同级会留下以 .<项目名>.v6- 开头的隐藏目录。下一次启动会自动认领并把项目恢复回来，所以不要手工删除这类目录，也不要在项目从列表消失时急着重建项目。
• 项目恢复正常后，这些隐藏目录按与上述备份相同的保留期自动清理。

如果某个项目迁移失败，先保留现场并查看启动日志，不要手工修改 schema 版本或删除备份文件。修复损坏的项目引用或权限后再重启服务。

5.6 固定版本

latest 适合快速体验，但生产环境更适合固定 Release 标签。

将 Compose 中的镜像改为：

image: arcreel/arcreel:X.Y.Z

升级时显式修改版本，可以降低无意中拉取新版本的风险。

6. 备份与恢复

6.1 SQLite 部署备份

数据根已经包含项目、默认 SQLite 数据库、日志和 Vertex 凭据，文件系统备份只需归档数据根，外加 .env 与 claude_data/。

先确认宿主机上的实际数据根目录，再停止写入。默认 Compose 使用 deploy/projects/；如果通过 ARCREEL_DATA_DIR 和自定义挂载改变了容器内路径，请把 data_dir 改为该挂载对应的宿主机绝对路径：

cd deploy

data_dir="$(cd projects && pwd)"
# 自定义数据目录示例：data_dir="/srv/arcreel/projects"

docker compose stop arcreel

备份：

backup_stamp="$(date +%Y%m%d-%H%M%S)"
umask 077
mkdir -p backups
chmod 700 backups

tar -czf "backups/arcreel-config-${backup_stamp}.tar.gz" \
  .env claude_data

tar -czf "backups/arcreel-projects-${backup_stamp}.tar.gz" \
  -C "${data_dir}" .

服务停止后再归档整个 data_dir，可以让 arcreel.db 与项目资产保持在同一时点。配置归档与数据归档必须使用相同时间标签并配套保存；umask 077 与备份目录模式 0700 会限制其中凭据和项目资产的读取权限。不要在 ArcReel 写入时只复制 arcreel.db：WAL 模式下，已提交交易可能仍在 arcreel.db-wal 中，丢失或错配 WAL 文件会造成数据丢失甚至损坏。如果无法停服，应使用 SQLite Online Backup API（例如 sqlite3 的 .backup）或 VACUUM INTO 生成一致快照，而不是直接 cp 主数据库文件。

恢复服务：

docker compose start arcreel

恢复时：

1. 停止 ArcReel；
2. 备份当前目录，避免覆盖后无法回退；
3. 将配置归档中的 .env 和 claude_data/ 恢复到原位置，并将配套数据归档完整解压到空的 data_dir；
4. 启动并检查 /health；
5. 打开几个项目验证图片、视频和版本历史。

6.2 PostgreSQL 部署备份

先停止 ArcReel 应用，保留 PostgreSQL 运行，避免备份数据库和项目文件期间继续产生写入：

cd "$(git rev-parse --show-toplevel)/deploy/production"
umask 077
mkdir -p backups
chmod 700 backups
docker compose stop arcreel

backup_stamp="$(date +%Y%m%d-%H%M%S)"

docker compose exec -T postgres sh -c \
  'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_dump -h 127.0.0.1 -U arcreel -d arcreel' \
  > "backups/arcreel-db-${backup_stamp}.sql"

tar -czf "backups/arcreel-files-${backup_stamp}.tar.gz" \
  .env docker-compose.yml projects claude_data

docker compose start arcreel

数据库备份和文件备份使用同一时间标签，必须配套保存和恢复。文件备份中的 projects/ 是数据根，已包含日志与 Vertex 凭据。文件备份包含当前 docker-compose.yml，因此特殊字符密码所需的 DATABASE_URL 定制也会随 .env 一起恢复。umask 077 与备份目录模式 0700 会让宿主机重定向生成的 SQL 文件和文件归档仅对当前用户可读写。

pg_dump 会使用 libpq 的 PGPASSWORD。上述命令只在 PostgreSQL 容器内的该次 pg_dump 进程中设置它，因此 docker compose exec -T 可以非交互执行，也不会把密码展开到宿主机命令行。长期的宿主机备份自动化应改用权限为 0600 的 PostgreSQL password file，不要把密码写进脚本或备份文件名。

如果 tar 报 Permission denied，说明挂载目录中存在由容器内 root 用户创建、宿主机当前用户不可读的文件。可用 sudo 重新执行对应的 tar 命令，并在完成后限制备份文件的读取权限。

6.3 PostgreSQL 恢复

恢复前停止 ArcReel，保留 PostgreSQL：

cd "$(git rev-parse --show-toplevel)/deploy/production"
docker compose stop arcreel

backup_stamp=YYYYMMDD-HHMMSS
tar -xzf "backups/arcreel-files-${backup_stamp}.tar.gz"

文件归档会恢复 .env、docker-compose.yml、数据根 projects/ 和 claude_data/。以下流程还会删除目标 arcreel 数据库中的现有数据；先确认同一 backup_stamp 的数据库与文件备份完整，并在隔离环境演练恢复流程。

重建空数据库后再导入，避免与已有表结构或数据冲突：

docker compose exec -T postgres \
  dropdb -U arcreel --maintenance-db=postgres --if-exists --force arcreel

docker compose exec -T postgres \
  createdb -U arcreel --maintenance-db=postgres -O arcreel arcreel

cat "backups/arcreel-db-${backup_stamp}.sql" | \
  docker compose exec -T postgres psql -v ON_ERROR_STOP=1 -U arcreel -d arcreel

数据库导入成功后，重新启动：

docker compose start arcreel
curl -f http://localhost:1241/health

恢复策略取决于是否覆盖现有数据库、是否跨版本以及备份时服务是否仍有写入。生产环境应定期做真实恢复演练，而不只是确认备份文件存在。

7. 反向代理与 HTTPS

ArcReel 当前不支持直接暴露到公网。私有远程部署必须启用认证，并通过 TLS、VPN 或安全隧道保护传输。不要把 1241 端口直接发布到不受信任的网络。建议：

• 使用 Nginx、Caddy、Traefik 或云负载均衡器；
• 配置 HTTPS；
• 只允许代理服务器访问 ArcReel 容器端口；
• 保留 SSE 长连接；
• 设置足够的上传大小和读取超时。

官方 Compose 文件默认使用 1241:1241，会把后端端口发布到宿主机的所有网络接口；仅添加反向代理不会关闭这条直连路径。反向代理运行在同一宿主机时，启动前将 arcreel 服务的端口映射改为仅监听 loopback：

ports:
  - "127.0.0.1:1241:1241"

如果反向代理运行在容器网络或其他主机上，应取消不必要的宿主机端口发布，并通过容器网络、主机防火墙或等效网络策略保证只有代理能够访问 ArcReel 后端。

Nginx 示例：

server {
    listen 443 ssl http2;
    server_name arcreel.example.com;

    ssl_certificate /etc/letsencrypt/live/arcreel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/arcreel.example.com/privkey.pem;

    client_max_body_size 2g;

    location / {
        proxy_pass http://127.0.0.1:1241;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # ArcReel 使用 SSE 推送 Agent 回复和项目事件
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

证书配置取决于你的基础设施，可以使用 ACME/Let's Encrypt 或云平台托管证书。

8. 容器权限与 Agent 沙箱

ArcReel 在 Linux 和 macOS 启动时会严格检查 Agent 沙箱，所需工具缺失或不可用时会拒绝启动。Windows 原生环境没有 bwrap，会自动降级为受限的 Bash 命令白名单；该模式只保证项目创建与基础流程，生产部署建议使用 WSL2 或 Docker Desktop。

环境	工具	安装
macOS	sandbox-exec	系统自带，无需额外安装
Linux 本地开发	bwrap + socat	Ubuntu/Debian：sudo apt install bubblewrap socat；Fedora：sudo dnf install bubblewrap socat；Arch：sudo pacman -S bubblewrap socat
Docker	bwrap + socat	官方镜像已包含
Windows 原生	无 bwrap 沙箱	自动降级为 Bash 命令白名单；推荐 WSL2 / Docker Desktop

官方 Compose 为 Agent Bash 沙箱配置了：

• seccomp:unconfined
• apparmor:unconfined
• NET_ADMIN

这些设置用于支持容器中的 bwrap 隔离和嵌套网络命名空间，但也意味着容器获得了比普通 Web 应用更高的权限。

生产部署建议：

• 使用专用主机或至少使用隔离良好的运行环境；
• 不把 Docker Socket 挂载到容器；
• 不额外挂载不必要的宿主机目录；
• 限制管理页面访问范围；
• 及时更新 ArcReel 和基础镜像；
• 只为 Agent 配置必要的网络和文件访问权限；
• 对未知来源的项目输入保持谨慎。

Docker 镜像虽然已包含 bwrap 和 socat，宿主机的 user namespace 或 AppArmor 策略仍可能阻止沙箱启动。启动失败时应根据服务输出的 SANDBOX_* 诊断修复，不要改成特权模式绕过检查，也不要在不了解影响的情况下删除官方 Compose 的沙箱配置。

9. 监控建议

最低限度应监控：

• /health 是否可用；
• 容器是否频繁重启；
• 磁盘剩余空间；
• projects/ 增长速度；
• PostgreSQL 数据目录大小；
• 任务失败率；
• 供应商限流和额度不足；
• 备份最近成功时间。

媒体资产增长通常快于数据库，应优先为项目目录设置容量告警。

10. 常见故障

服务无法启动

docker compose ps
docker compose logs --tail=300 arcreel

检查：

• .env 是否存在；
• 端口 1241 是否被占用；
• 镜像是否成功拉取；
• 挂载目录是否可写；
• 生产部署是否设置 POSTGRES_PASSWORD。

健康检查失败

curl -v http://localhost:1241/health
docker compose logs --tail=300 arcreel

如果容器刚启动，先确认是否仍在执行数据库迁移。

无法登录

• 检查 AUTH_USERNAME；
• 检查 .env 中的 AUTH_PASSWORD；
• 如果首次启动时密码留空，查看是否已被回写；
• 修改 AUTH_TOKEN_SECRET 后需要重新登录。

Agent 请求失败

• 验证 Agent 凭据；
• 检查 Base URL 和模型名称；
• 检查网络和代理；
• 查看供应商是否限流；
• 使用少量内容验证，不要一上来就用完整小说跑通全流程。

任务一直排队

• 查看图像、视频和音频并发设置；
• 检查是否有长时间停留在运行中的异常任务；
• 查看供应商 RPM 配额；
• 检查前序任务是否尚未完成。

磁盘快速增长

在 Compose 目录中重点检查数据根各部分的占用：

du -sh projects/*
find projects/projects -type f -size +500M

不要直接删除当前项目引用的文件。优先通过项目归档、清理无用项目和保留必要版本控制空间。

11. 上线检查清单

• 使用 PostgreSQL；
• 固定 Release 镜像版本；
• 设置强 AUTH_PASSWORD；
• 设置固定 AUTH_TOKEN_SECRET；
• 配置 HTTPS；
• 不直接暴露 1241；
• 验证 SSE 可正常工作；
• 备份数据库和数据根；
• 完成一次恢复演练；
• 配置磁盘和健康检查告警；
• 确认模型 API Key 不出现在日志和仓库；
• 阅读许可证和 NOTICE。