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。一、三种部署路径总览场景推荐方式数据库HTTPSVPS 快速上线cloud-initUser DataPostgreSQL可选Caddy 自动 HTTPS本机体验Windows/macOSDocker Desktop docker compose up -dSQLite零配置不需要精细化控制手动服务器安装按需选择按需选择三种方式最终都落在同一套 docker-compose.yml 上差异仅在于初始化方式与启用的 Profile。二、Cloud-Init最快的 VPS 部署最省事的路径把 cloud-init 配置粘进 VPS 厂商的User Data字段新建服务器时自动完成全部安装。文件deploy/cloud-init.yml使用方法创建一台 VPS推荐Ubuntu 22.04文件头部注明已在 Ubuntu 22.04、Debian 12 测试将deploy/cloud-init.yml的内容粘贴到 User Data / Cloud-Init 字段通过厂商 UI 添加你的 SSH 公钥创建服务器等待约58 分钟初始化完成。它实际安装了什么对照 deploy/cloud-init.yml 的runcmd段可以看到完整执行序列Docker Docker Composecurl -fsSL https://get.docker.com | sh并把archon用户加入 docker 组UFW 防火墙放行22/tcp、80/tcp、443/tcp以及443/udp后者为 Caddy HTTP/3 QUIC 预留2GB swapfilefallocate -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_TOKENsk-ant-oat01-... # DOMAINarchon.example.com # DATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agent # 可选为 Web UI 配置 Basic Auth # docker run caddy caddy hash-password --plaintext YOUR_PASSWORD # 写入 .envCADDY_BASIC_AUTHbasicauth protected { admin $$2a$$14$$hash } # 启动 cd /opt/archon docker compose --profile with-db --profile cloud up -d别忘了 DNS启动前先把域名的 A 记录指向服务器 IP。各厂商粘贴位置速查厂商粘贴位置DigitalOceanCreate Droplet → Advanced Options → User DataAWS EC2Launch Instance → Advanced Details → User DataLinodeCreate Linode → Add Tags → Metadata (User Data)HetznerCreate Server → Cloud config → User DataVultrDeploy → Additional Features → Cloud-Init User-Data三、本地 Docker DesktopWindows / 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本机部署得到什么能力状态Web UIhttp://localhost:3000数据库SQLite自动、零配置HTTPS / Caddy本地不需要认证无单用户、仅限 localhost平台适配器可选Telegram、Slack 等本地改用 PostgreSQL可选docker compose --profile with-db up -d然后在.env中添加DATABASE_URLpostgresql://postgres:postgrespostgres: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 version2. 克隆仓库git clone https://github.com/coleam00/Archon.git cd Archon3. 配置环境变量cp .env.example .env cp Caddyfile.example Caddyfile nano .env需要在.env中设置的项完整清单见仓库根目录 .env.example每个变量都带注释说明# AI 助手 —— 至少配置一种 # 方案 AClaude OAuth token在本机执行 claude setup-token 获取 CLAUDE_CODE_OAUTH_TOKENsk-ant-oat01-xxxxx # 方案 BClaude API key来自 console.anthropic.com/settings/keys # CLAUDE_API_KEYsk-ant-xxxxx # 域名 —— 指向本服务器的域名或子域名 DOMAINarchon.example.com # 数据库 —— 连接 Docker 内的 PostgreSQL 容器 # 不设置则使用 SQLite上手足够但推荐 PostgreSQL DATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agent # Basic Auth可选—— 公网暴露 Web UI 时启用 # 若使用基于 IP 的防火墙规则则跳过。 # 生成哈希docker run caddy caddy hash-password --plaintext YOUR_PASSWORD # CADDY_BASIC_AUTHbasicauth protected { admin $$2a$$14$$... } # 平台 Token按需启用 # TELEGRAM_BOT_TOKEN123456789:ABCdef... # SLACK_BOT_TOKENxoxb-... # SLACK_APP_TOKENxapp-... # GH_TOKENghp_... # GITHUB_TOKENghp_...Docker 不支持CLAUDE_USE_GLOBAL_AUTHtrue——容器内没有本地的claudeCLI必须显式提供CLAUDE_CODE_OAUTH_TOKEN或CLAUDE_API_KEY。若启用--profile with-db却未设置DATABASE_URL应用会回退到 SQLite 并输出警告PostgreSQL 容器在跑但并没有被使用。4. 域名指向服务器在域名注册商处创建 DNSA 记录类型名称值Aarchon根域名用服务器公网 IP等待 DNS 传播通常 560 分钟可用dig archon.example.com验证。5. 开放防火墙端口sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443 sudo ufw --force enable6. 启动docker compose --profile with-db --profile cloud up -d这会启动三个容器app—— Archon 服务器 Web UIpostgres—— PostgreSQL 17 数据库首次启动自动初始化 schemacaddy—— 反向代理 Lets Encrypt 自动 HTTPS7. 验证# 检查所有容器都在运行 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 顶部注释命令运行内容docker compose up -dApp SQLitedocker compose --profile with-db up -dApp PostgreSQLdocker compose --profile cloud up -dApp CaddyHTTPSdocker compose --profile with-db --profile cloud up -dApp PostgreSQL Caddy:::note没有external-dbprofile。使用外部 PostgreSQLSupabase、Neon 等时只需在.env中设置DATABASE_URL然后不带任何 profile 运行docker compose up -d。基础的app服务始终启动。 :::无 ProfileSQLite零配置默认项。无需数据库容器——SQLite 文件存放在archon_data卷中。--profile with-dbPostgreSQL启动一个 PostgreSQL 17 容器。在.env中设置连接串DATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agentschema 在首次启动时自动初始化PostgreSQL 以${POSTGRES_PORT:-5432}暴露给外部工具注意 compose 中绑定的是127.0.0.1仅本机可访问。--profile cloudCaddy HTTPS增加一个 Caddy 反向代理自动从 Lets Encrypt 申请 TLS 证书。启动前必须满足已创建Caddyfilecp Caddyfile.example Caddyfile.env中已设置DOMAINDNS A 记录指向服务器 IP80、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 的防火墙或其他网络级访问控制可以跳过。启用步骤生成 bcrypt 密码哈希docker run caddy caddy hash-password --plaintext YOUR_PASSWORD在.env中设置CADDY_BASIC_AUTHbcrypt 哈希中的$必须写成$$转义CADDY_BASIC_AUTHbasicauth protected { admin $$2a$$14$$abc123... }重启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 AuthBETTER_AUTH_SECRET它用真实的每用户账户取代单用户的auth-servicesidecar。自助注册默认关闭——用ARCHON_AUTH_ALLOWED_EMAILS白名单邀请成员或显式设置ARCHON_AUTH_OPEN_SIGNUPtrue开放注册。启用后 Better Auth 还会在服务端拦截/api/*无会话一律401可完全替代forward_authsidecar。sidecar 仍可用也是 SQLite/单机安装的保留方案但在 Postgres 上已不是推荐路径。表单认证设置步骤生成 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$...开头。生成随机 Cookie 签名密钥docker run --rm node:22-alpine \ node -e console.log(require(crypto).randomBytes(32).toString(hex))在.env中设置AUTH_USERNAMEadmin AUTH_PASSWORD_HASH$$2b$$12$$REPLACE_WITH_YOUR_HASH COOKIE_SECRETREPLACE_WITH_64_HEX_CHARS哈希中的每个$都要写成$$否则 Docker Compose 会把它当作变量插值。更新Caddyfile如尚未复制先从Caddyfile.example复制取消注释Option A 表单认证块handle /login、handle /logout、handle { forward_auth ... }三个块注释掉site 块底部的默认 No authhandle { ... }块。同时启用cloud与auth两个 profile 启动docker compose --profile with-db --profile cloud --profile auth up -d访问你的域名——会被重定向到/login。登出访问/logout清除会话 Cookie 并回到登录页。会话时长默认 24 小时COOKIE_MAX_AGE86400可在.env覆盖COOKIE_MAX_AGE3600 # 1 小时注意不要同时启用表单认证与 Basic Auth。二选一另一个保持禁用要么CADDY_BASIC_AUTH留空要么从 Caddyfile 移除 basic auth 的protected块。六、关键配置详解端口默认值:::caution Docker 默认端口是3000compose 中为${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_AUTHtrue——没有本地claudeCLI。必须在.env中显式设置凭据Claude二选一# OAuth token —— 在本机运行 claude setup-token 获取 CLAUDE_CODE_OAUTH_TOKENsk-ant-oat01-xxxxx # 或 API key —— 来自 console.anthropic.com/settings/keys CLAUDE_API_KEYsk-ant-xxxxxCodex备选CODEX_ID_TOKENeyJhbGc... CODEX_ACCESS_TOKENeyJhbGc... CODEX_REFRESH_TOKENrt_... CODEX_ACCOUNT_ID6a6a7ba6-...平台 Token可选TELEGRAM_BOT_TOKEN123456789:ABCdef... SLACK_BOT_TOKENxoxb-... SLACK_APP_TOKENxapp-... DISCORD_BOT_TOKEN... GH_TOKENghp_... GITHUB_TOKENghp_... WEBHOOK_SECRET...服务器设置可选PORT3000 # 默认3000 DOMAINarchon.example.com # --profile cloud 必填 LOG_LEVELinfo # fatal|error|warn|info|debug|trace MAX_CONCURRENT_CONVERSATIONS10完整变量清单与逐条注释见 .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_DATADocker 自动管理卷archon_data——数据在重启与重建后依然保留但存放在 Docker 存储内部。用户主目录持久化容器以appuser运行$HOME/home/appuser。基础 compose 默认将/home/appuser挂载为命名卷archon_user_home因此用户级状态在容器重建后无需任何操作即可保留路径持久化内容~/.claude/Claude Code 的 skills、commands、agents、hooks、MCP 配置、projects对话历史、memory、OAuth 状态、keybindings、file-history~/.codex/Codex 认证来自交互式codex login的auth.jsonenv-var 路径经setup-auth每次容器启动都会覆盖它~/.pi/agent/交互式pi /login生成的auth.json以及models.json、全局设置~/.pi/agent/settings.json与会话Archon 的 Pi 适配器每次请求都会读取auth.json与settings.json~/.gitconfig作者身份、签名配置、自定义别名以及镜像内置的safe.directory条目~/.bash_history执行docker compose exec app bash时的 shell 历史~/.config/gh/交互式gh auth login的 GitHub CLI 认证GH_TOKENenv-var 路径无需它若要改用宿主机 bind-mount在.env中设置ARCHON_USER_HOMEARCHON_USER_HOME/opt/archon-user-home宿主路径必须对 UID 1001 可写——首次启动前 chown 一次mkdir -p /opt/archon-user-home sudo chown -R 1001:1001 /opt/archon-user-homeentrypoint 每次容器启动都会修复属主只 touch 属主错误的文件因此即使卷很大启动也很快后续重建无需重新 chown。:::caution bind-mount 路径不会继承镜像内置的~/.gitconfigDocker 只在首次创建时把镜像内容复制进命名卷从不复制进 bind mount。entrypoint 仍会在运行时为/.archon/workspaces与/.archon/worktrees的仓库注册 gitsafe.directory功能不受影响——但 bind-mount 的~/.gitconfig是空白的任何作者身份/签名配置都需要在容器内用git config --global显式设置。 :::若未设置ARCHON_USER_HOMEDocker 自动管理卷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的属主使其对appuserUID 1001可写然后降权运行。在macOS bind mountVirtioFS上这个属主修复必然失败——宿主机控制文件属主且拒绝把宿主 UID 重映射到容器的 UID 1001——于是容器以退出码 1 崩溃循环。Linux 上的只读挂载与 SELinux/AppArmor 拒绝也会同样失败。ARCHON_ALLOW_ROOT_FALLBACK就是为这种情况准备的显式逃生舱# .env —— 属主修复失败时选择以 root 运行 ARCHON_ALLOW_ROOT_FALLBACK1值属主修复失败时的行为未设置 / 非1默认打印底层chown错误并退出 1fail loud——默认行为1打印警告、export IS_SANDBOX1、继续以root运行不降权到appuser该变量在属主修复成功时不起作用——Linux 上卷属主正确的部署完全不受影响。:::caution 这是刻意的安全取舍绝不会自动启用。以 root 运行同时会设置IS_SANDBOX1绕过 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不工作应用镜像没有dockerCLIcompose 栈也刻意不挂载/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 可达之后打开https://github.com/owner/repo/settings/hooks添加 webhookPayload URLhttps://archon.example.com/webhooks/githubContent typeapplication/jsonSecret.env中的WEBHOOK_SECRETEventsIssues、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 采用三阶段构建deps—— 安装全部依赖包括 web 构建所需的 devDependencies注意使用--linkerhoisted以兼容 Vite/Rollup 的扁平 node_modules 布局web-build—— 用 Vite 构建 React Web UI产物输出到packages/web/dist/production—— 仅含生产依赖与预构建 web 静态资源的精简生产镜像docker build -t archon . docker run --env-file .env -p 3000:3000 archon镜像里有什么运行时Bun 1.2直接运行 TypeScript无编译步骤系统依赖git、curl、ghGitHub CLI、postgresql-client、Chromium另有 ripgrepClaude Code / Codex 的默认代码搜索工具与 jqbash 工作流节点的 JSON 处理浏览器工具agent-browserVercel Labs——通过 CDP 驱动系统 Chromium 实现 E2E 测试工作流AGENT_BROWSER_EXECUTABLE_PATH/usr/bin/chromium应用全部 10 个 workspace 包源码 预构建 Web UI用户非 root 的appuserUID 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 的前提下增加工具复制示例本地/开发cp Dockerfile.user.example Dockerfile.user服务器/部署cp deploy/Dockerfile.user.example Dockerfile.user编辑Dockerfile.user——按需取消注释并扩展示例如安装 apt 包、gh 扩展、npm 全局包、自定义二进制。复制 override 文件本地/开发cp docker-compose.override.example.yml docker-compose.override.yml服务器/部署cp deploy/docker-compose.override.example.yml docker-compose.override.yml运行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.userCompose 检测到二者并存时自动改用本地构建。Dockerfile.user与docker-compose.override.yml均被 gitignore自定义内容不会入库。十、日常维护查看日志docker compose logs -f # 所有服务 docker compose logs -f app # 仅 app docker compose logs --tail100 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_AUTHtrue。在.env中设置其中之一CLAUDE_CODE_OAUTH_TOKENsk-ant-oat01-...在本机运行claude setup-token获取CLAUDE_API_KEYsk-ant-...来自 console.anthropic.com或 Codex 凭据CODEX_ID_TOKEN、CODEX_ACCESS_TOKEN等Caddy 启动失败not a directoryerror mounting Caddyfile: not a directoryCaddyfile不存在——Docker 在原地创建了目录。修复rm -rf Caddyfile cp Caddyfile.example Caddyfile docker compose --profile cloud up -dCaddy 拿不到 SSL 证书# 检查 DNS 传播 dig archon.example.com # 应返回你的服务器 IP # 检查 Caddy 日志 docker compose logs caddy # 检查防火墙 sudo ufw status # 80 和 443 端口必须开放常见原因DNS 未传播等待 560 分钟、防火墙拦截 80/443、.env中域名拼写错误。健康检查失败Docker 健康检查用的是/api/health不是/healthcurl http://localhost:3000/api/healthPostgreSQL 连接被拒使用--profile with-db时确认DATABASE_URL的主机名是postgresDocker 服务名而不是localhostDATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agentpostgres 容器健康docker compose ps postgres迁移已执行docker compose logs postgres查看 init 脚本输出/.archon/权限错误容器以appuserUID 1001运行。entrypoint 每次启动都会尝试修复/.archon与/home/appuser的属主失败时退出 1并输出底层chown错误。Linux上使用 bind mount 而非 Docker 卷时在宿主机修复属主sudo chown -R 1001:1001 /path/to/archon-datamacOSDocker Desktop / VirtioFS bind mount上宿主chown无济于事——无论文件在宿主机上归谁所有宿主机都拒绝把属主重映射到容器的 UID 1001。这种情况以及其他chown无法修复的失败如只读挂载或 SELinux/AppArmor 拒绝请见上文 Root fallback。端口冲突Docker 默认端口为 3000本地开发为 3090。在.env中修改PORT3001容器不断重启docker compose ps docker compose logs --tail50 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考