Archon 部署实战指南本地、Docker 与云 VPS 全场景部署方案详解【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/ArchonArchon 是一款开源的 AI 编码 harness 构建工具通过编排 Claude Code、Codex、Pi 等 AI 助手让 AI 编码过程变得确定、可重复。本文以官方部署文档packages/docs-web/src/content/docs/deployment/index.md为主线系统讲解 Archon 的四种部署方式本地、Docker、云 VPS、Windows、三种数据库选型以及 E2E 测试环境的搭建并结合仓库中的 Compose 配置、cloud-init 脚本与迁移文件进行源码级印证。读完本文你将掌握从个人笔记本跑通开发环境到VPS 上 7×24 小时运行并自动签发 HTTPS 证书的完整实操路径。部署方式总览Archon 既可以运行在本机用于开发调试也可以部署到服务器实现常驻运行。官方文档给出了四条主流路径对应仓库packages/docs-web/src/content/docs/deployment/下的四份指南方式适用场景对应指南文档本地运行开发调试、个人使用Local DevelopmentDocker自托管服务器、CI 环境Docker Guide云 VPS7×24 常驻运行、自动 HTTPSCloud DeploymentWindowsWindows 原生或 WSL2Windows Setup四条路径的核心理念一致Archon 不捆绑 AI 助手只负责编排。你需要至少安装并配置一个 AI 助手Claude Code 或 Codex并准备用于仓库克隆的 GitHub TokenGH_TOKEN/GITHUB_TOKEN。数据库选型SQLite 还是 PostgreSQL选项配置方式适用场景SQLite默认零配置只需不设置DATABASE_URL单用户、CLI 使用、本地开发远程 PostgreSQL将DATABASE_URL指向托管数据库云部署、多用户共享访问本地 PostgreSQLDocker 加--profile with-db参数自托管、基于 Docker 的部署SQLite 数据存放在~/.archon/archon.dbDocker 容器内为/.archon/archon.db首次运行自动初始化无需任何手工步骤.env.example中说明SQLite 是零配置默认项而 PostgreSQL 更适合 20 并发工作流的重度并行场景MAX_CONCURRENT_CONVERSATIONS10默认并发上限PostgreSQL 下可以放开。值得注意的一个坑Docker 容器内ARCHON_HOME会被忽略——容器始终使用/.archon作为数据根目录。想控制宿主上的数据位置要用ARCHON_DATA详见下文 Docker 小节。本地开发部署Local Development本地开发 SQLite 是官方推荐的默认组合完全不需要配置数据库。前置条件Bun 1.0 及以上版本至少安装并配置一个 AI 助手Claude Code 或 Codex——Archon 只编排、不内置它们一个用于仓库克隆的 GitHub TokenGH_TOKEN/GITHUB_TOKEN。源码安装bun run会自动通过node_modules解析 Claude Code 的cli.js而编译后的 Archon 二进制则必须显式配置CLAUDE_BIN_PATH或assistants.claude.claudeBinaryPath见 .env.example 中CLAUDE_BIN_PATH的注释它支持原生安装器路径、npm 全局路径和 Windows 平台目录三种写法。安装与启动# 1. 克隆并安装依赖 git clone https://github.com/coleam00/Archon cd Archon bun install # 2. 配置环境变量 cp .env.example .env nano .env # 填入 AI 助手 TokenClaude、Codex 或 Pi # 3. 启动服务器 Web UISQLite 自动检测无需配置数据库 bun run dev # 4. 打开 Web UI # http://localhost:5173开发模式下会同时运行两个服务服务地址用途Web UIhttp://localhost:5173React 前端Vite 开发服务器API Serverhttp://localhost:3090后端 API SSE 流式推送本地改用 PostgreSQL可选docker compose --profile with-db up -d postgres # 然后在 .env 中设置 # DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/remote_coding_agent数据库 schema 会在容器首次启动时通过挂载的迁移文件自动创建全新安装无需手工执行psql。本地生产构建bun run build # 构建前端 bun run start # 服务器在 3090 端口同时提供 API 和 Web UI验证安装curl http://localhost:3090/health # 期望输出: {status:ok}Docker 部署Compose 服务与 ProfilesDocker 是自托管与 CI 环境的首选。仓库根目录 docker-compose.yml 定义了 4 个服务其中只有app是无条件启动的基础服务其余三个都挂在可选 profile 下命令启动内容docker compose up -dApp SQLite零配置默认docker compose --profile with-db up -dApp PostgreSQLdocker compose --profile cloud up -dApp Caddy自动 HTTPSdocker compose --profile with-db --profile cloud up -dApp PostgreSQL Caddydocker compose --profile with-db --profile cloud --profile auth up -d全部四个服务含表单登录注意不存在external-dbprofile。使用外部 PostgreSQLSupabase、Neon、AWS RDS 等时只需在.env设置DATABASE_URL然后不加任何 profile 直接docker compose up -d基础app服务始终会启动。零配置默认SQLite不启用任何 profileSQLite 数据库文件存放在archon_data卷中无需数据库容器。这是最快的起步方式。with-db本地 PostgreSQL启动 PostgreSQL 17 容器并在.env中设置连接串DATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agent注意 host 必须写成 Docker 服务名postgres而不是localhost容器间通过 compose 网络通信。schema 在首次启动时自动初始化PostgreSQL 默认在宿主127.0.0.1:5432暴露可用POSTGRES_PORT覆盖供外部工具连接。根目录 compose 还做了两处关键挂载见 docker-compose.yml./migrations/000_combined.sql:/docker-entrypoint-initdb.d/000_combined.sql:ro容器初始化脚本全新数据库自动建表./migrations:/migrations:ro保留手工执行迁移的入口。cloudCaddy 自动 HTTPS追加 Caddy 反向代理caddy:2-alpine由 Lets Encrypt 自动签发并续期 TLS 证书同时处理 HTTP→HTTPS 跳转、HTTP/3QUIC和 SSE 流式转发。启动前必须满足 4 个前提compose 文件中caddy服务depends_onapp 的健康检查创建 Caddyfilecp Caddyfile.example Caddyfile.env中设置DOMAINarchon.example.com域名 A 记录指向服务器 IP防火墙开放 80 与 443 端口443 的 UDP 用于 HTTP/3。端口与健康检查重要差异场景默认端口说明本地开发bun run dev3090服务器默认端口Docker3000由.env中的PORT控制${PORT:-3000}Worktree 隔离环境3190-4089按路径哈希自动分配覆盖任意例如PORT4000 bun dev# Docker 内 curl http://localhost:3000/api/health # 本地开发两个都能用 curl http://localhost:3090/health curl http://localhost:3090/api/health # 更细粒度的健康检查两种场景通用 curl http://localhost:3090/health/db # 数据库连通性 curl http://localhost:3090/health/concurrency # 并发状态compose 中 app 服务的healthcheck用的是http://localhost:${PORT:-3000}/api/health见 docker-compose.yml间隔 30 秒、超时 10 秒、3 次重试、15 秒启动宽限。Docker 健康检查只认/api/health不认/health——这也是 Caddy 能正确等 app 就绪后再转发流量的依据。数据目录ARCHON_DATA 与 ARCHON_USER_HOME容器内所有数据位于/.archon/workspaces、worktrees、artifacts、日志、SQLite 库默认挂载到 Docker 管理的命名卷archon_data。想存到宿主指定路径# .env — 控制 /.archon 在宿主上的位置 ARCHON_DATA/opt/archon-data该目录需可被容器用户写入UID 1001即appusermkdir -p /opt/archon-data sudo chown -R 1001:1001 /opt/archon-data此外容器以appuser运行$HOME/home/appuser默认持久化为命名卷archon_user_home这样 AI 助手的用户级状态在容器重建后不会丢失路径持久化内容~/.claude/Claude Code 技能、命令、agents、hooks、MCP 配置、会话历史、记忆、OAuth 状态等~/.codex/Codex 认证auth.json~/.pi/agent/Pi 的auth.json、models.json、全局设置与会话~/.gitconfig提交身份、签名配置、自定义别名~/.bash_historydocker compose exec app bash的 shell 历史~/.config/gh/GitHub CLI 登录态同样可以换成宿主目录ARCHON_USER_HOME/opt/archon-user-home也需要chown 1001:1001。入口脚本会在每次容器启动时修复归属权限且只处理属主错误的文件保证大卷启动不拖慢。macOS 注意在 Docker Desktop / VirtioFS bind mount 下宿主拒绝将文件属主重映射为容器 UID 1001权限修复必然失败导致容器退出。这是刻意保留的 opt-in 逃生通道.env中设置ARCHON_ALLOW_ROOT_FALLBACK1可改为以 root 继续运行同时导出IS_SANDBOX1绕过 Claude provider 的 UID-0 安全检查AI 子进程将以 root 运行。官方明确警告该变量永不自动启用Linux 上正确做法是sudo chown -R 1001:1001 path而不是启用 root fallback。镜像构建与预构建镜像官方预构建镜像ghcr.io/coleam00/archon:latest已内置 Claude Code通过 npm 安装并预设CLAUDE_BIN_PATH开箱即用。仓库 Dockerfile 采用三阶段构建deps安装全部依赖含 web 构建所需的 devDependenciesweb-build用 Vite 构建 React Web UIproduction仅含生产依赖 预构建前端资产的精简镜像。镜像内容要点见 Docker Guide 的 Building the Image 一节运行时Bun 1.2直接运行 TypeScript无编译步骤系统依赖git、curl、ghGitHub CLI、postgresql-client、Chromium浏览器工具预装 agent-browserVercel Labs通过 CDP 支持 E2E 测试工作流使用系统 ChromiumAGENT_BROWSER_EXECUTABLE_PATH/usr/bin/chromium用户非 root 的appuserUID 1001Claude Code SDK 强制要求目录/.archon/workspaces、/.archon/worktrees。自建镜像或想在预构建镜像上叠加自定义工具无需改动被追踪的 Dockerfile复制Dockerfile.user.example为Dockerfile.user、复制docker-compose.override.example.yml为docker-compose.override.yml两文件已被 gitignore改动不会污染仓库Compose 会自动合并 override。Docker 中的 AI 凭证必填Docker 容器不支持CLAUDE_USE_GLOBAL_AUTHtrue——容器里没有本地claudeCLI。必须显式提供凭证# Claude二选一 # OAuth Token在本机执行 claude setup-token 后复制 CLAUDE_CODE_OAUTH_TOKENsk-ant-oat01-xxxxx # 或 API Keyconsole.anthropic.com/settings/keys CLAUDE_API_KEYsk-ant-xxxxx # 或用 Codex四件套来自本机 ~/.codex/auth.json CODEX_ID_TOKENeyJhbGc... CODEX_ACCESS_TOKENeyJhbGc... CODEX_REFRESH_TOKENrt_... CODEX_ACCOUNT_ID6a6a7ba6-...若未配置任何 AI 凭证app 启动会报no_ai_credentials错误。平台 Token 可选Telegram/Discord/Slack 机器人、GH_TOKEN、WEBHOOK_SECRET等完整清单见 .env.example。云 VPS 部署cloud-init 一键与手动两种路径云部署的目标是 24/7 常驻运行 自动 HTTPS。官方强烈建议使用仓库自带的 Compose 文件并强调在 VPS 上直接编辑/opt/archon/.env不要运行archon setup向导——该向导写的是 Archon 自己的 CLI 环境文件不是 Docker Compose 消费的仓库.env。路径一cloud-init 最快上手官方提供了现成的 deploy/cloud-init.yml把它粘贴到 VPS 厂商的User Data / Cloud-Init字段即可自动完成全部安装约 5-8 分钟。脚本实际执行可从文件内容逐一核对安装 Docker Docker Compose 插件配置 UFW 防火墙22、80、443 的 TCP/UDP——443/udp 是 HTTP/3 QUIC 所需创建 2GB swapfile防止小内存 VPS 构建镜像时 OOM克隆仓库到/opt/archon从示例生成.env和Caddyfile创建仅加入 docker 组、无 sudo的archon专用用户管理操作请用默认云用户或 root预拉取postgres:17-alpine与caddy:2-alpine镜像并构建 Archon 镜像。厂商粘贴位置速查DigitalOcean 在 Create Droplet → Advanced Options → User DataAWS EC2 在 Launch Instance → Advanced Details → User DataLinode 在 Create Linode → Add Tags → MetadataHetzner 在 Create Server → Cloud configVultr 在 Deploy → Additional Features → Cloud-Init User-Data。开机后 SSH 登录完成收尾# 确认安装完成 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 # 启动全部服务 cd /opt/archon docker compose --profile with-db --profile cloud up -d别忘了先做好 DNS把域名的 A 记录指向服务器 IP否则 Caddy 无法签发证书。路径二手动服务器配置如果不想用 cloud-init 或需要更多控制官方也提供了逐步手册详见 Cloud Deployment要点如下准备Ubuntu 22.04推荐 1-2 vCPU / 2GB 内存4GB 更佳/ 20GB SSD先在本机ssh-keygen -t ed25519生成密钥建用户adduser deploy并加入 sudo 组复制 SSH 公钥PasswordAuthentication no关闭密码登录UFW 开放 22/80/443装依赖curl -fsSL https://get.docker.com | shapt install -y docker-compose-plugin git postgresql-clientDNS域名解析商建 A 记录Name:archon或Value: 服务器 IP等待 5-60 分钟传播克隆git clone https://github.com/coleam00/Archon .到/opt/archon配置cp .env.example .env后编辑核心变量见上表数据库推荐托管 PostgreSQLSupabase/Neon也可用本地with-db容器Caddyfilecp Caddyfile.example CaddyfileDOMAIN设置好后无需手工编辑Caddyfile 会自动读取{$DOMAIN}与{$PORT}启动远程库用docker compose --profile cloud up -d --build本地库加--profile with-db验证curl https://archon.yourdomain.com/api/health期望{status:ok}浏览器访问域名应显示 Web UI。数据库迁移全自动收敛这是最省心的部分——不需要手工迁移步骤。app 每次启动都会在一个 advisory-lock 事务内执行幂等的 migrations/000_combined.sql全新安装和版本升级走同一条路径。启动后可用以下命令确认建表结果psql $DATABASE_URL -c \dt # 应看到remote_agent_codebases, remote_agent_conversations, # remote_agent_sessions, remote_agent_isolation_environments, # remote_agent_workflow_runs, remote_agent_workflow_events, # remote_agent_messages, remote_agent_codebase_env_vars, # remote_agent_users, remote_agent_user_identities日志中出现db.pg_schema_init_completed即表示收敛成功。仓库的 migrations 目录还维护了从001_initial_schema.sql到023_add_default_branch_to_codebases.sql的完整增量迁移历史可供追溯 schema 演进。Web UI 访问保护Basic Auth 与表单登录公网暴露 Web UI 时建议加访问控制两种方式选其一不要同时使用方式一Caddy Basic Auth零额外容器# 生成 bcrypt 哈希 docker run caddy caddy hash-password --plaintext YOUR_PASSWORD # 写入 .env$ 必须转义为 $$否则 Compose 会做变量插值 CADDY_BASIC_AUTHbasicauth protected { admin $$2a$$14$$hash } # 重启 Caddy docker compose --profile cloud restart caddy浏览器会弹出原生凭证对话框。/webhooks/*与/api/health自动豁免webhook 走 HMAC 签名校验健康检查需要公开可达。方式二表单登录auth-service 侧车样式化 HTML 登录页# 1. 生成 bcrypt 哈希首次运行会构建 auth-service 镜像 docker compose --profile auth run --rm auth-service \ node -e require(bcryptjs).hash(YOUR_PASSWORD, 12).then(h console.log(h)) # 2. 生成随机 cookie 签名密钥 docker run --rm node:22-alpine \ node -e console.log(require(crypto).randomBytes(32).toString(hex)) # 3. 写入 .envbcrypt 里的每个 $ 都要写成 $$ AUTH_USERNAMEadmin AUTH_PASSWORD_HASH$$2b$$12$$REPLACE_WITH_YOUR_HASH COOKIE_SECRETREPLACE_WITH_64_HEX_CHARS然后在Caddyfile中启用 Option A 表单认证块取消handle /login、handle /logout、handle { forward_auth ... }的注释并注释掉底部默认无认证的handle块最后docker compose --profile with-db --profile cloud --profile auth up -d启动。默认会话 24 小时COOKIE_MAX_AGE86400可改COOKIE_MAX_AGE3600缩短访问/logout可退出登录。PostgreSQL 部署的进阶选择Better Auth 原生登录。官方文档说明当.env同时设置DATABASE_URLPostgres与BETTER_AUTH_SECRET≥32 字符openssl rand -base64 32生成时Web UI 会启用基于 Better Auth 的真实邮箱/密码登录挂载在/api/auth/*支持ARCHON_AUTH_ALLOWED_EMAILS邀请白名单与ARCHON_AUTH_OPEN_SIGNUP开放注册默认关闭注册、只允许登录并会在服务端强制校验每个/api/*请求无会话返回 401。这是 SQLite/单机安装之外的推荐方案。维护与更新# 查看日志 docker compose --profile cloud logs -f app # 更新git pull 重建 cd /opt/archon git pull docker compose --profile with-db --profile cloud up -d --build # 重启 / 停止 docker compose --profile cloud restart docker compose --profile cloud down # 停止数据保留 docker compose --profile cloud down -v # 停止并删除卷破坏性操作 # 磁盘清理 docker system prune -a docker volume prune配置 GitHub Webhooks可选服务器可通过 HTTPS 访问后在 GitHub 仓库 Settings → Hooks 添加 webhook字段值Payload URLhttps://archon.yourdomain.com/webhooks/githubContent typeapplication/jsonSecret.env中的WEBHOOK_SECRETopenssl rand -hex 32生成EventsIssues、Issue comments、Pull requests配置完成后可在 issue 中你的机器人 can you analyze this issue?测试触发。WEBHOOK_SECRET也可配合GITHUB_ALLOWED_USERS白名单使用见 .env.example。Windows 部署原生 Bun 与 WSL2Archon 在 Windows 上有两种运行方式Windows 原生 Bun适用于基础使用服务器、Web UI、简单工作流无需 WSL2。安装 Windows 版 Bun 后bun install bun run dev即可WSL2官方推荐完整兼容 git worktree 隔离、shell 工作流步骤以及依赖 Unix 工具链的 CLI 功能。WSL2 安装五步走# 1. 安装 WSL2Win10 2004 / Win11 wsl --install # 2. 打开 Ubuntu创建用户名/密码 # 3. 在 WSL2 内安装 Bun curl -fsSL https://bun.sh/install | bash source ~/.bashrc # 4. 克隆安装 git clone https://github.com/coleam00/Archon cd Archon bun install # 5. 全局暴露 CLI 并验证 cd packages/cli bun link archon versionWSL2 可通过/mnt/c/访问 Windows 文件性能上建议把项目放在 WSL2 文件系统~/projects/内archon workflow run assist --cwd /mnt/c/Users/YourName/Projects/my-repo 这段代码是做什么的原生 Windows 的常见问题陈旧进程导致端口被占症状是 Web UI 一直转圈或启动报EADDRINUSE。诊断与修复netstat -ano | findstr :3090 # 找到占用端口的 PID tasklist | findstr 12345 # 确认是哪个进程 taskkill /F /PID 12345 # 按 PID 杀掉首选 taskkill /F /IM bun.exe # 或多个残留进程时 taskkill /F /IM node.exe切勿taskkill掉claude.exe——那是正在运行的 Claude Code 会话。睡眠打断工作流原生 Windows 上工作流运行期间 Archon 通过SetThreadExecutionState保持系统唤醒仅抑制系统睡眠屏幕仍可关闭最后一个运行结束即自动释放无需任何配置。Docker Desktop 的 Windows 专属坑务必从 WSL 构建不要在 PowerShell 里构建Docker Desktop 在构建上下文传输时无法跟随 Bun workspace 符号链接会报The file cannot be accessed by the system改用 WSL 终端docker compose up -d即可行尾符问题仓库用.gitattributes强制 shell 脚本使用 LF。老克隆遇到exec docker-entrypoint.sh: no such file or directory时重新克隆或执行git rm --cached -r . git reset --hard。E2E 测试环境Archon 通过 agent-browserVercel Labs在archon-validate-pr等工作流中做端到端浏览器测试。这是可选的外部依赖——核心功能不依赖它。安装方式npm install -g agent-browser agent-browser install # 下载 Chrome for Testing 浏览器引擎 # 验证 agent-browser --version agent-browser open https://example.com agent-browser close依赖 agent-browser 的资源和用途archon-validate-pr工作流PR 验证的 E2E 阶段、validate-ui技能全面 UI 测试、replicate-issue技能浏览器复现 issue以及两个 E2E 命令模板主分支/特性分支。各平台注意点Docker已预装无需操作镜像内AGENT_BROWSER_EXECUTABLE_PATH/usr/bin/chromiummacOS / Linux执行上述安装命令即可守护进程启动失败时pkill -f daemon.js后重试Windowsagent-browser 在 Windows 上有已知 bugUnix domain socket 不兼容解决方式是在 WSL 里跑 agent-browser、开发服务器跑在 Windows详见 E2E Testing on WSL不装 agent-browser非 E2E 工作流完全不受影响E2E 节点会因 agent 无法调用agent-browser而失败——此时 agent 被提示在 2 次连接失败后停止并生成仅代码评审报告但这是提示词层面的指令而非自动化逻辑结果取决于模型遵循程度。常见故障排查速查表症状处理app 启动报no_ai_credentials容器不支持CLAUDE_USE_GLOBAL_AUTHtrue在.env显式设置CLAUDE_CODE_OAUTH_TOKEN/CLAUDE_API_KEY或 Codex 四件套Caddy 报not a directoryCaddyfile不存在被 Docker 建成了目录删除后cp Caddyfile.example Caddyfile重启Caddy 拿不到 SSL 证书dig 域名检查 DNS 传播等 5-60 分钟、ufw status确认 80/443 开放、docker compose logs caddy看签发日志健康检查失败Docker 用/api/health而非/healthPostgreSQL connection refusedDATABASE_URL的 host 要用服务名postgres而非localhostdocker compose ps postgres检查容器健康/.archon/权限错误Linux宿主sudo chown -R 1001:1001 路径macOS VirtioFS 无法 chown 时考虑ARCHON_ALLOW_ROOT_FALLBACK1有安全代价容器反复重启docker compose logs --tail50 app常见原因是缺.env、凭证无效、数据库不可达端口冲突本地 3090、Docker 3000.env设PORT3001覆盖小结从个人笔记本到生产 VPSArchon 的部署路径非常清晰本地bun run dev加 SQLite 五分钟跑通开发环境Docker 通过 Compose profiles 按需组合 PostgreSQL、Caddy HTTPS 与表单登录云 VPS 用 cloud-init 一把梭完成 Docker、防火墙、swap 与镜像构建Windows 用户则推荐 WSL2 获得完整兼容。全程无需手工迁移数据库——幂等的 migrations/000_combined.sql 会在每次启动时自动收敛 schema。按照本文任一路径完成部署后记得用健康检查端点验证再按需接入 GitHub Webhooks 与平台适配器即可让 Archon 在服务器上 7×24 地为你执行确定、可重复的 AI 编码工作流。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考