企业官网建设流程全解析

Archon Docker 部署完全指南：自动 HTTPS、PostgreSQL 与 Web UI 一站式落地

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

本文是 Archon 开源仓库《Docker Guide》的深度实战版。你将学会用cloud-init 一键初始化 VPS、用Docker Desktop 本地跑通 Web UI，以及如何通过Compose Profile按需组合 SQLite/PostgreSQL/Caddy 自动 HTTPS，并掌握镜像构建、数据持久化、双认证方案与排障技巧——所有结论均可对照仓库中的 docker-compose.yml、Dockerfile、docker-entrypoint.sh 与 Caddyfile.example 逐一验证。

Archon 是一套面向 AI 编程助手的开源 harness 构建器，Docker 是其面向服务器与本地桌面场景的官方部署方式。容器内预装 Claude Code（官方ghcr.io/coleam00/archon镜像通过 npm 安装并预置CLAUDE_BIN_PATH，无需额外配置）；若你自建镜像省略了 npm 安装步骤，则需要自行设置CLAUDE_BIN_PATH指向挂载的cli.js（详见 AI Assistants → Binary path configuration）。

一、三种部署路径总览

三种方式最终都落在同一套 docker-compose.yml 上，差异仅在于初始化方式与启用的 Profile。

二、Cloud-Init：最快的 VPS 部署

最省事的路径：把 cloud-init 配置粘进 VPS 厂商的User Data字段，新建服务器时自动完成全部安装。

文件：deploy/cloud-init.yml

使用方法

1. 创建一台 VPS（推荐Ubuntu 22.04+；文件头部注明已在 Ubuntu 22.04+、Debian 12+ 测试）；
2. 将deploy/cloud-init.yml的内容粘贴到 "User Data" / "Cloud-Init" 字段；
3. 通过厂商 UI 添加你的 SSH 公钥；
4. 创建服务器，等待约5～8 分钟初始化完成。

它实际安装了什么

对照 deploy/cloud-init.yml 的runcmd段，可以看到完整执行序列：

• Docker + Docker Compose：curl -fsSL https://get.docker.com | sh，并把archon用户加入 docker 组；
• UFW 防火墙：放行22/tcp、80/tcp、443/tcp以及443/udp（后者为 Caddy HTTP/3 QUIC 预留）；
• 2GB swapfile：fallocate -l 2G /swapfile并写入 fstab，避免小规格 VPS 在镜像构建阶段 OOM；
• 克隆仓库到/opt/archon，并复制.env.example → .env、Caddyfile.example → Caddyfile；
• 创建专用archon用户（仅 docker 组、无 sudo），并把默认用户的 SSH 公钥复制过去以便直接登录；
• 预拉取postgres:17-alpine与caddy:2-alpine镜像，然后以archon身份执行docker compose build构建应用镜像；
• 构建完成后写入/opt/archon/SETUP_COMPLETE标记文件。

开机后收尾

# 检查初始化是否完成 cat /opt/archon/SETUP_COMPLETE # 编辑凭据与域名 nano /opt/archon/.env # 至少要设置： # CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-... # DOMAIN=archon.example.com # DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent # （可选）为 Web UI 配置 Basic Auth： # docker run caddy caddy hash-password --plaintext 'YOUR_PASSWORD' # 写入 .env：CADDY_BASIC_AUTH=basicauth @protected { admin $$2a$$14$$<hash> } # 启动 cd /opt/archon docker compose --profile with-db --profile cloud up -d

别忘了 DNS：启动前先把域名的 A 记录指向服务器 IP。

各厂商粘贴位置速查

三、本地 Docker Desktop（Windows / macOS）

无需域名与 VPS，仅使用 SQLite 与 Web UI 即可本地运行。

快速开始

git clone https://github.com/coleam00/Archon.git cd Archon cp .env.example .env # 编辑 .env：设置 CLAUDE_CODE_OAUTH_TOKEN 或 CLAUDE_API_KEY docker compose up -d

浏览器访问http://localhost:3000即可打开 Web UI。

Windows 专属注意事项

• 必须在 WSL 中构建，而不是 PowerShell。Docker Desktop 在构建上下文传输时无法跟随 Bun workspace 的符号链接。若看到The file cannot be accessed by the system错误，请打开 WSL 终端：

cd /mnt/c/Users/YourName/path/to/Archon docker compose up -d

• 行尾符：仓库通过.gitattributes强制 shell 脚本使用 LF 行尾。若你在该配置加入前克隆且遇到exec docker-entrypoint.sh: no such file or directory，请重新克隆，或执行：

git rm --cached -r . git reset --hard

本机部署得到什么

本地改用 PostgreSQL（可选）

docker compose --profile with-db up -d

然后在.env中添加：

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

四、手动服务器安装（全流程）

不想用 cloud-init、或需要更多控制权时的分步替代方案。

1. 安装 Docker

# 以 Ubuntu/Debian 为例 curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # 注销并重新登录，使组变更生效 exit # 重新 ssh 登录 # 验证 docker --version docker compose version

2. 克隆仓库

git clone https://github.com/coleam00/Archon.git cd Archon

3. 配置环境变量

cp .env.example .env cp Caddyfile.example Caddyfile nano .env

需要在.env中设置的项（完整清单见仓库根目录 .env.example，每个变量都带注释说明）：

# AI 助手 —— 至少配置一种 # 方案 A：Claude OAuth token（在本机执行 `claude setup-token` 获取） CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx # 方案 B：Claude API key（来自 console.anthropic.com/settings/keys） # CLAUDE_API_KEY=sk-ant-xxxxx # 域名 —— 指向本服务器的域名或子域名 DOMAIN=archon.example.com # 数据库 —— 连接 Docker 内的 PostgreSQL 容器 # 不设置则使用 SQLite（上手足够，但推荐 PostgreSQL） DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent # Basic Auth（可选）—— 公网暴露 Web UI 时启用 # 若使用基于 IP 的防火墙规则则跳过。 # 生成哈希：docker run caddy caddy hash-password --plaintext 'YOUR_PASSWORD' # CADDY_BASIC_AUTH=basicauth @protected { admin $$2a$$14$$... } # 平台 Token（按需启用） # TELEGRAM_BOT_TOKEN=123456789:ABCdef... # SLACK_BOT_TOKEN=xoxb-... # SLACK_APP_TOKEN=xapp-... # GH_TOKEN=ghp_... # GITHUB_TOKEN=ghp_...

Docker 不支持CLAUDE_USE_GLOBAL_AUTH=true——容器内没有本地的claudeCLI，必须显式提供CLAUDE_CODE_OAUTH_TOKEN或CLAUDE_API_KEY。

若启用--profile with-db却未设置DATABASE_URL，应用会回退到 SQLite 并输出警告：PostgreSQL 容器在跑，但并没有被使用。

4. 域名指向服务器

在域名注册商处创建 DNSA 记录：

等待 DNS 传播（通常 5～60 分钟），可用dig archon.example.com验证。

5. 开放防火墙端口

sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443 sudo ufw --force enable

6. 启动

docker compose --profile with-db --profile cloud up -d

这会启动三个容器：

• app—— Archon 服务器 + Web UI
• postgres—— PostgreSQL 17 数据库（首次启动自动初始化 schema）
• caddy—— 反向代理 + Let's Encrypt 自动 HTTPS

7. 验证

# 检查所有容器都在运行 docker compose --profile with-db --profile cloud ps # 查看日志 docker compose logs -f app docker compose logs -f caddy # 测试 HTTPS（在本机执行） curl https://archon.example.com/api/health

浏览器打开https://archon.example.com，应能看到 Archon Web UI。

五、Compose Profile：按需组合服务

Archon 用 Docker Compose profiles 实现"可选 PostgreSQL / 可选 HTTPS"，可自由混搭（命令与效果见 docker-compose.yml 顶部注释）：

:::note没有external-dbprofile。使用外部 PostgreSQL（Supabase、Neon 等）时，只需在.env中设置DATABASE_URL，然后不带任何 profile 运行docker compose up -d。基础的app服务始终启动。 :::

无 Profile（SQLite）

零配置默认项。无需数据库容器——SQLite 文件存放在archon_data卷中。

--profile with-db（PostgreSQL）

启动一个 PostgreSQL 17 容器。在.env中设置连接串：

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

schema 在首次启动时自动初始化；PostgreSQL 以${POSTGRES_PORT:-5432}暴露给外部工具（注意 compose 中绑定的是127.0.0.1，仅本机可访问）。

--profile cloud（Caddy HTTPS）

增加一个 Caddy 反向代理，自动从 Let's Encrypt 申请 TLS 证书。

启动前必须满足：

1. 已创建Caddyfile：cp Caddyfile.example Caddyfile
2. .env中已设置DOMAIN
3. DNS A 记录指向服务器 IP
4. 80、443 端口已开放

Caddy 负责 HTTPS 证书、HTTP→HTTPS 跳转、HTTP/3 与 SSE 流式传输。从 Caddyfile.example 可以看到：/webhooks/*与/api/health被定义为始终绕过认证的公开路径，SSE 接口/api/stream/*使用flush_interval -1保证实时推送，并统一附加了安全响应头（X-Content-Type-Options、X-Frame-Options、HSTS 等）。

认证方案一：Basic Auth（浏览器弹窗）

Caddy 可以对除 webhooks（/webhooks/*）与健康检查（/api/health）之外的所有路由强制 HTTP Basic Auth。该方案零额外容器、配置最简单，但浏览器显示的是原生凭据弹窗。若你使用基于 IP 的防火墙或其他网络级访问控制，可以跳过。

启用步骤：

1. 生成 bcrypt 密码哈希：

   docker run caddy caddy hash-password --plaintext 'YOUR_PASSWORD'

2. 在.env中设置CADDY_BASIC_AUTH（bcrypt 哈希中的$必须写成$$转义）：

   CADDY_BASIC_AUTH=basicauth @protected { admin $$2a$$14$$abc123... }

3. 重启：docker compose --profile cloud restart caddy

之后访问 Archon 域名时浏览器会提示输入用户名/密码。Webhook 端点绕过认证，因为它们使用 HMAC 签名校验。禁用方式：将CADDY_BASIC_AUTH留空或不设置——Caddyfile 会把它展开为空。

重要：请始终用docker run caddy caddy hash-password生成哈希——切勿把明文密码写进.env。

认证方案二：表单认证（HTML 登录页）

与 Basic Auth 的浏览器弹窗不同，表单认证会渲染一套带样式的深色模式 HTML 登录页，支持 24 小时会话 Cookie 与登出。它基于一个轻量的auth-servicesidecar 容器（见 auth-service/server.js）配合 Caddy 的forward_auth指令实现，因此多一个容器。

何时选哪种：

• 表单认证：深色登录页、24h 会话 Cookie、支持登出；需要额外容器。
• Basic Auth：零额外容器、更简单；浏览器显示原生凭据对话框。

PostgreSQL 部署的推荐替代：优先使用原生 Web UI 登录（Better Auth）（BETTER_AUTH_SECRET），它用真实的每用户账户取代单用户的auth-servicesidecar。自助注册默认关闭——用ARCHON_AUTH_ALLOWED_EMAILS（白名单）邀请成员，或显式设置ARCHON_AUTH_OPEN_SIGNUP=true开放注册。启用后 Better Auth 还会在服务端拦截/api/*（无会话一律401），可完全替代forward_authsidecar。sidecar 仍可用（也是 SQLite/单机安装的保留方案），但在 Postgres 上已不是推荐路径。

表单认证设置步骤：

1. 生成 bcrypt 密码哈希：

   docker compose --profile auth run --rm auth-service \ node -e "require('bcryptjs').hash('YOUR_PASSWORD', 12).then(h => console.log(h))"

   首次运行会构建 auth-service 镜像。保存输出哈希（以$2b$12$...开头）。

2. 生成随机 Cookie 签名密钥：

   docker run --rm node:22-alpine \ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. 在.env中设置：

   AUTH_USERNAME=admin AUTH_PASSWORD_HASH=$$2b$$12$$REPLACE_WITH_YOUR_HASH COOKIE_SECRET=REPLACE_WITH_64_HEX_CHARS

   哈希中的每个$都要写成$$；否则 Docker Compose 会把它当作变量插值。

4. 更新Caddyfile（如尚未复制，先从Caddyfile.example复制）：

   • 取消注释"Option A" 表单认证块（handle /login、handle /logout、handle { forward_auth ... }三个块）；
   • 注释掉site 块底部的默认 "No auth"handle { ... }块。

5. 同时启用cloud与auth两个 profile 启动：

   docker compose --profile with-db --profile cloud --profile auth up -d

6. 访问你的域名——会被重定向到/login。

登出：访问/logout清除会话 Cookie 并回到登录页。

会话时长：默认 24 小时（COOKIE_MAX_AGE=86400），可在.env覆盖：

COOKIE_MAX_AGE=3600 # 1 小时

注意：不要同时启用表单认证与 Basic Auth。二选一，另一个保持禁用（要么CADDY_BASIC_AUTH留空，要么从 Caddyfile 移除 basic auth 的@protected块）。

六、关键配置详解

端口默认值

:::caution Docker 默认端口是3000（compose 中为${PORT:-3000}），而本地开发默认是3090。如需修改 Docker 端口，在.env中设置PORT。 :::

Docker 健康检查使用/api/health（而非/health）：

# 容器内 curl http://localhost:3000/api/health # 本地开发（两者都可用） curl http://localhost:3090/health curl http://localhost:3090/api/health

这一点在 docker-compose.yml 的healthcheck段有直接体现：curl -f http://localhost:${PORT:-3000}/api/health，间隔 30s、超时 10s、3 次重试、15s 启动宽限。

AI 凭据（必填）

容器内无法使用CLAUDE_USE_GLOBAL_AUTH=true——没有本地claudeCLI。必须在.env中显式设置凭据：

Claude（二选一）：

# OAuth token —— 在本机运行 `claude setup-token` 获取 CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx # 或 API key —— 来自 console.anthropic.com/settings/keys CLAUDE_API_KEY=sk-ant-xxxxx

Codex（备选）：

CODEX_ID_TOKEN=eyJhbGc... CODEX_ACCESS_TOKEN=eyJhbGc... CODEX_REFRESH_TOKEN=rt_... CODEX_ACCOUNT_ID=6a6a7ba6-...

平台 Token（可选）

TELEGRAM_BOT_TOKEN=123456789:ABCdef... SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... DISCORD_BOT_TOKEN=... GH_TOKEN=ghp_... GITHUB_TOKEN=ghp_... WEBHOOK_SECRET=...

服务器设置（可选）

PORT=3000 # 默认：3000 DOMAIN=archon.example.com # --profile cloud 必填 LOG_LEVEL=info # fatal|error|warn|info|debug|trace MAX_CONCURRENT_CONVERSATIONS=10

完整变量清单与逐条注释见 .env.example。

数据目录

容器把所有数据存放在/.archon/（workspaces、worktrees、artifacts、logs、SQLite 数据库），默认是一个 Docker 托管卷。若要存到宿主机指定位置，在.env中设置ARCHON_DATA：

# 将 Archon 数据存到指定宿主机路径 ARCHON_DATA=/opt/archon-data

:::note.env.example中的ARCHON_HOME在Docker 内被忽略——容器固定使用/.archon。用ARCHON_DATA（宿主机 bind-mount 源）来控制/.archon在宿主机上的位置。两者都会经env_file: .env泄漏进容器环境，这是无害但符合预期的行为（docker-entrypoint.sh 启动时也会打印提示）。 :::

目录会自动创建。请确保路径对 UID 1001（容器用户）可写：

mkdir -p /opt/archon-data sudo chown -R 1001:1001 /opt/archon-data

若未设置ARCHON_DATA，Docker 自动管理卷（archon_data）——数据在重启与重建后依然保留，但存放在 Docker 存储内部。

用户主目录（持久化）

容器以appuser运行，$HOME=/home/appuser。基础 compose 默认将/home/appuser挂载为命名卷（archon_user_home），因此用户级状态在容器重建后无需任何操作即可保留：

若要改用宿主机 bind-mount，在.env中设置ARCHON_USER_HOME：

ARCHON_USER_HOME=/opt/archon-user-home

宿主路径必须对 UID 1001 可写——首次启动前 chown 一次：

mkdir -p /opt/archon-user-home sudo chown -R 1001:1001 /opt/archon-user-home

entrypoint 每次容器启动都会修复属主，只 touch 属主错误的文件，因此即使卷很大启动也很快；后续重建无需重新 chown。

:::caution bind-mount 路径不会继承镜像内置的~/.gitconfig（Docker 只在首次创建时把镜像内容复制进命名卷，从不复制进 bind mount）。entrypoint 仍会在运行时为/.archon/workspaces与/.archon/worktrees的仓库注册 gitsafe.directory，功能不受影响——但 bind-mount 的~/.gitconfig是空白的，任何作者身份/签名配置都需要在容器内用git config --global显式设置。 :::

若未设置ARCHON_USER_HOME，Docker 自动管理卷（archon_user_home）。清空它：docker compose down && docker volume rm archon_archon_user_home。

将 Pi 数据迁移到 ARCHON_DATA 卷（可选）

默认情况下 Pi 的数据目录（~/.pi/agent/）通过上面的archon_user_home卷持久化。若希望 Pi 数据与其他/.archon/数据放一起（例如用同一卷备份），在.env中设置PI_CODING_AGENT_DIR重定向：

# 可选 —— 仅当你希望 Pi 数据落在 ARCHON_DATA 卷上时需要 PI_CODING_AGENT_DIR=/.archon/pi

这必须在容器启动前设置；Pi SDK 在每次文件路径查找时都会读取该变量。

macOS bind mount 的 root 回退（opt-in）

每次启动时 entrypoint 都会修复/.archon与/home/appuser的属主使其对appuser（UID 1001）可写，然后降权运行。在macOS bind mount（VirtioFS）上这个属主修复必然失败——宿主机控制文件属主且拒绝把宿主 UID 重映射到容器的 UID 1001——于是容器以退出码 1 崩溃循环。Linux 上的只读挂载与 SELinux/AppArmor 拒绝也会同样失败。

ARCHON_ALLOW_ROOT_FALLBACK就是为这种情况准备的显式逃生舱：

# .env —— 属主修复失败时选择以 root 运行 ARCHON_ALLOW_ROOT_FALLBACK=1

该变量在属主修复成功时不起作用——Linux 上卷属主正确的部署完全不受影响。

:::caution 这是刻意的安全取舍，绝不会自动启用。以 root 运行同时会设置IS_SANDBOX=1，绕过 Claude provider 的 UID-0 安全防护（否则它会拒绝 root 下的bypassPermissions）——即 AI 子进程将在容器内以 root 运行。这在单操作员的 macOS 开发机上可接受（bind mount 已限定容器能触及的范围）；但在 Linux 上这是错误的修法——那里的失败意味着卷属主真的坏了——应在宿主机执行sudo chown -R 1001:1001 <path>，而不是 opt-in。 :::

--container文件夹级隔离在 Docker 中不可用

文件夹项目的容器后端（archon workflow run … --container）每次运行会启动一个兄弟 Docker 容器来隔离工作流的写入。它需要 shell 出到dockerCLI——既要有 Docker CLI 二进制，也要能访问宿主 Docker daemon 的 socket（/var/run/docker.sock）。

当 Archon 自身跑在 Docker 里（本 compose 栈）时，--container不工作：应用镜像没有dockerCLI，compose 栈也刻意不挂载/var/run/docker.sock。--container运行会在 preflight 阶段快速失败，报 "Cannot connect to the Docker daemon"（该报错信息明确点名了 dockerized 场景）。Worktree 隔离（git 仓库的默认项）与 in-place 文件夹运行不受影响——只有--container后端需要 daemon。

:::caution 把 Docker socket 挂进应用容器以启用--container是严重的安全妥协，不属于官方支持的 compose 栈。socket 等同于root：任何能触达它的进程都能启动特权容器进而控制宿主机。结合native-overlay 的 CAP_SYS_ADMIN 逃逸，爆炸半径远超单次运行。若你在单租户、operator 可信的宿主机上接受这一取舍，请先阅读 packages/isolation/docker/SECURITY.md——它完整记录了容器后端的威胁模型。要在不暴露 socket 的前提下使用--container，请在宿主机直接运行Archon（非 Docker 安装）并搭配本地 Docker daemon。 :::

GitHub CLI 认证

.env中的GH_TOKEN会被自动读取。替代方案：

docker compose exec app gh auth login

另外，docker-entrypoint.sh 会在启动时利用GH_TOKEN配置 git credential helper，使容器内 HTTPS clone 免密完成（token 只存在于环境中，不写入~/.gitconfig）。

七、GitHub Webhooks

服务器通过 HTTPS 可达之后：

1. 打开https://github.com/<owner>/<repo>/settings/hooks
2. 添加 webhook：
   • Payload URL：https://archon.example.com/webhooks/github
   • Content type：application/json
   • Secret：.env中的WEBHOOK_SECRET
   • Events：Issues、Issue comments、Pull requests

八、使用预构建镜像

不需要从源码构建的用户：

mkdir archon && cd archon curl -O https://raw.githubusercontent.com/coleam00/Archon/main/deploy/docker-compose.yml curl -O https://raw.githubusercontent.com/coleam00/Archon/main/.env.example cp .env.example .env # 编辑 .env —— 设置 AI 凭据、DOMAIN 等 docker compose up -d

使用ghcr.io/coleam00/archon:latest。要加 PostgreSQL，取消 compose 文件中postgres服务的注释并在.env设置DATABASE_URL。要在预构建镜像之上叠加自定义工具，见下文"自定义镜像"。

九、构建镜像

Dockerfile 采用三阶段构建：

1. deps—— 安装全部依赖（包括 web 构建所需的 devDependencies；注意使用--linker=hoisted以兼容 Vite/Rollup 的扁平 node_modules 布局）
2. web-build—— 用 Vite 构建 React Web UI（产物输出到packages/web/dist/）
3. production—— 仅含生产依赖与预构建 web 静态资源的精简生产镜像

docker build -t archon . docker run --env-file .env -p 3000:3000 archon

镜像里有什么：

• 运行时：Bun 1.2+（直接运行 TypeScript，无编译步骤）
• 系统依赖：git、curl、gh（GitHub CLI）、postgresql-client、Chromium，另有 ripgrep（Claude Code / Codex 的默认代码搜索工具）与 jq（bash 工作流节点的 JSON 处理）
• 浏览器工具：agent-browser（Vercel Labs）——通过 CDP 驱动系统 Chromium 实现 E2E 测试工作流（AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium）
• 应用：全部 10 个 workspace 包（源码）+ 预构建 Web UI
• 用户：非 root 的appuser（UID 1001）——Claude Code SDK 的要求
• Archon 目录：/.archon/workspaces、/.archon/worktrees

多阶段构建让镜像保持精简——不含 devDependencies、测试文件、文档或.git/。镜像内还通过useradd -m -u 1001 appuser创建非 root 用户，并在构建期用 gosu 注册/.archon/workspaces、/.archon/worktrees的safe.directory条目（对应 docker-entrypoint.sh 在运行期的补充注册）。

自定义镜像

在不改动受跟踪 Dockerfile 的前提下增加工具：

1. 复制示例：
   • 本地/开发：cp Dockerfile.user.example Dockerfile.user
   • 服务器/部署：cp deploy/Dockerfile.user.example Dockerfile.user
2. 编辑Dockerfile.user——按需取消注释并扩展示例（如安装 apt 包、gh 扩展、npm 全局包、自定义二进制）。
3. 复制 override 文件：
   • 本地/开发：cp docker-compose.override.example.yml docker-compose.override.yml
   • 服务器/部署：cp deploy/docker-compose.override.example.yml docker-compose.override.yml
4. 运行docker compose up -d——Compose 自动合并 override。

其中deploy/Dockerfile.user.example以FROM ghcr.io/coleam00/archon:latest为基础（无需本地构建即可拉取预构建镜像），而deploy/docker-compose.override.example.yml为app服务补充完整的build:段（指向Dockerfile.user），Compose 检测到二者并存时自动改用本地构建。Dockerfile.user与docker-compose.override.yml均被 gitignore，自定义内容不会入库。

十、日常维护

查看日志

docker compose logs -f # 所有服务 docker compose logs -f app # 仅 app docker compose logs --tail=100 app # 最近 100 行

更新

git pull docker compose --profile with-db --profile cloud up -d --build

重启

docker compose restart # 全部 docker compose restart app # 仅 app

停止

docker compose down # 停止容器（数据保留） docker compose down -v # 停止并删除卷（破坏性操作！）

数据库迁移（PostgreSQL）

应用每次启动都会在 advisory-lock 事务中运行幂等的 migrations/000_combined.sql 来收敛 schema。全新安装与版本升级都自动完成——拉取新镜像后无需手动执行psql。postgres 容器上的migrations/挂载仅作为全新卷的无操作保留。

清理 Docker 资源

docker system prune -a # 移除未使用的镜像/容器 docker volume prune # 移除未使用的卷（谨慎！） docker system df # 检查磁盘占用

十一、故障排查

App 无法启动："no_ai_credentials"

未配置 AI 助手。Docker 不支持CLAUDE_USE_GLOBAL_AUTH=true。在.env中设置其中之一：

• CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...（在本机运行claude setup-token获取）
• CLAUDE_API_KEY=sk-ant-...（来自 console.anthropic.com）
• 或 Codex 凭据（CODEX_ID_TOKEN、CODEX_ACCESS_TOKEN等）

Caddy 启动失败："not a directory"

error mounting "Caddyfile": not a directory

Caddyfile不存在——Docker 在原地创建了目录。修复：

rm -rf Caddyfile cp Caddyfile.example Caddyfile docker compose --profile cloud up -d

Caddy 拿不到 SSL 证书

# 检查 DNS 传播 dig archon.example.com # 应返回你的服务器 IP # 检查 Caddy 日志 docker compose logs caddy # 检查防火墙 sudo ufw status # 80 和 443 端口必须开放

常见原因：DNS 未传播（等待 5～60 分钟）、防火墙拦截 80/443、.env中域名拼写错误。

健康检查失败

Docker 健康检查用的是/api/health（不是/health）：

curl http://localhost:3000/api/health

PostgreSQL 连接被拒

使用--profile with-db时，确认：

1. DATABASE_URL的主机名是postgres（Docker 服务名），而不是localhost：

   DATABASE_URL=postgresql://postgres:postgres@postgres:5432/remote_coding_agent

2. postgres 容器健康：docker compose ps postgres
3. 迁移已执行：docker compose logs postgres查看 init 脚本输出

/.archon/权限错误

容器以appuser（UID 1001）运行。entrypoint 每次启动都会尝试修复/.archon与/home/appuser的属主，失败时退出 1（并输出底层chown错误）。

Linux上使用 bind mount 而非 Docker 卷时，在宿主机修复属主：

sudo chown -R 1001:1001 /path/to/archon-data

macOS（Docker Desktop / VirtioFS bind mount）上，宿主chown无济于事——无论文件在宿主机上归谁所有，宿主机都拒绝把属主重映射到容器的 UID 1001。这种情况（以及其他chown无法修复的失败，如只读挂载或 SELinux/AppArmor 拒绝）请见上文 Root fallback。

端口冲突

Docker 默认端口为 3000（本地开发为 3090）。在.env中修改：

PORT=3001

容器不断重启

docker compose ps docker compose logs --tail=50 app

常见原因：缺少.env文件、凭据无效、数据库不可达。

结语

Archon 的 Docker 部署体系以"一个 Compose 文件 + 按需 Profile"为核心：with-db提供 PostgreSQL、cloud提供 Caddy 自动 HTTPS、auth提供表单登录 sidecar，三者自由组合；数据与用户主目录分别通过ARCHON_DATA与ARCHON_USER_HOME持久化，entrypoint 负责属主修复、gitsafe.directory注册与 Claude 二进制定位，让镜像既安全又免维护。无论你选择 cloud-init 的一键初始化、本地的 Docker Desktop，还是手动服务器安装，都可以在仓库的 docker-compose.yml、Dockerfile、docker-entrypoint.sh 与 .env.example 中找到与本文一一对应的落地依据。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon