企业官网建设流程全解析

Archon 云服务器部署完全指南：基于 Docker Compose 与 Caddy 的 24/7 生产化方案

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

本指南完整讲解如何将 Archon（开源 AI 编码 harness 构建器）部署到云 VPS，实现 24/7 常驻运行、Let's Encrypt 自动 HTTPS 与持久化运维。读者将掌握从 VPS 开通、SSH 加固、DNS 解析，到环境配置、数据库迁移、Caddy 反向代理、GitHub Webhook 接入，以及日志查看与版本升级的完整生产链路，可直接照此在 DigitalOcean、AWS EC2、Linode、Vultr 等平台上复现一套可对外服务的 Archon 实例。

See also:Docker 部署完整参考（profiles、构建、配置与故障排查的全量文档）。

导航：前置条件 | 1. 服务器开通与初始化 | 2. DNS 配置 | 3. 克隆仓库 | 4. 环境配置 | 5. 数据库迁移 | 6. Caddy 配置 | 7. 启动服务 | 8. 验证部署 | 9. 配置 GitHub Webhooks | 10. 维护与运维 | 故障排查

Docker Compose 部署方式：本指南使用仓库自带的 Compose 文件。请直接编辑/opt/archon/.env；不要在 VPS 上运行archon setup。该向导写入的是 Archon 自有的 CLI 环境文件，而不是 Docker Compose 消费的仓库.env，两者互不相通。

前置条件

必选项：

• 云 VPS 账户（DigitalOcean、Linode、AWS EC2、Vultr 等均可）
• 域名或子域名（例如archon.yourdomain.com）
• 本机已安装 SSH 客户端
• 具备基本命令行操作能力

推荐配置：

• CPU：1–2 vCPU
• 内存：最低 2GB（推荐 4GB）
• 存储：20GB SSD
• 系统：Ubuntu 22.04 LTS

生成 SSH 密钥（必做）

在创建 VPS 之前，先在本机生成 SSH 密钥对：

# 生成 SSH 密钥（推荐 ed25519） ssh-keygen -t ed25519 -C "archon" # 按提示操作： # - 文件位置：直接回车（使用默认 ~/.ssh/id_ed25519） # - Passphrase：可选，但推荐设置 # 查看公钥（创建 VPS 时需要） cat ~/.ssh/id_ed25519.pub # Windows: type %USERPROFILE%\.ssh\id_ed25519.pub

复制公钥输出——创建 VPS 时需要粘贴到对应输入框。

1. 服务器开通与初始化

创建 VPS 实例（示例）

服务器初始配置

连接服务器：

# 替换为你的服务器 IP（使用前置条件中生成的 SSH 密钥） ssh -i ~/.ssh/id_ed25519 root@your-server-ip

创建部署用户：

# 创建具有 sudo 权限的用户 adduser deploy usermod -aG sudo deploy # 将 root 的 SSH 授权密钥复制给 deploy 用户 mkdir -p /home/deploy/.ssh cp /root/.ssh/authorized_keys /home/deploy/.ssh/ chown -R deploy:deploy /home/deploy/.ssh chmod 700 /home/deploy/.ssh chmod 600 /home/deploy/.ssh/authorized_keys # 在新终端中先测试连接成功后再继续： # ssh -i ~/.ssh/id_ed25519 deploy@your-server-ip

出于安全考虑禁用密码认证：

# 编辑 SSH 配置 nano /etc/ssh/sshd_config

找到并修改为：

PasswordAuthentication no

在 Nano 中保存退出：Ctrl + X -> Y -> 回车

重启 SSH：

systemctl restart ssh # 后续步骤切换到 deploy 用户 su - deploy

配置防火墙：

# 放行 SSH、HTTP、HTTPS（含 HTTP/3） sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443 # 启用防火墙 sudo ufw --force enable # 查看状态 sudo ufw status

安装依赖

安装 Docker：

# 安装 Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将 deploy 用户加入 docker 组 sudo usermod -aG docker deploy # 注销并重新登录，使组权限生效 exit ssh -i ~/.ssh/id_ed25519 deploy@your-server-ip

安装 Docker Compose、Git 与 PostgreSQL 客户端：

# 更新软件包列表 sudo apt update # 安装所需软件包 sudo apt install -y docker-compose-plugin git postgresql-client # 验证安装 docker --version docker compose version git --version psql --version

自动化备选：仓库还提供了 cloud-init 一键初始化脚本，兼容任何支持 cloud-init 的云厂商（DigitalOcean、Hetzner、Linode 等），可自动完成部署用户创建、SSH 密钥搬运、Docker 安装等上述手工步骤，并预留了docker compose --profile with-db --profile cloud up -d的启动入口，适合追求可重复部署的场景。

2. DNS 配置

将你的域名指向服务器 IP。

A 记录设置：

1. 前往域名注册商或 DNS 服务商（Cloudflare、Namecheap 等）
2. 创建一条A 记录：
   • Name:archon（对应archon.yourdomain.com）或@（对应yourdomain.com）
   • Value:服务器公网 IP 地址
   • TTL:300（5 分钟）或默认值

示例（Cloudflare）：

Type: A Name: archon Content: 123.45.67.89 Proxy: Off (DNS Only) TTL: Auto

注意 Proxy 需设为Off（DNS Only），否则 Cloudflare 代理会遮挡真实 IP，导致 Caddy 无法完成 Let's Encrypt 证书签发。

3. 克隆仓库

在服务器上执行：

# 创建应用目录 sudo mkdir -p /opt/archon sudo chown deploy:deploy /opt/archon # 将仓库克隆到该目录 cd /opt/archon git clone https://github.com/coleam00/Archon .

克隆完成后，仓库根目录下应当能看到 docker-compose.yml（定义了 app / postgres / caddy / auth-service 四个服务及其 profiles）、Caddyfile.example（Caddy 反向代理配置模板）、.env.example（全部环境变量模板）等部署关键文件。

4. 环境配置

创建环境文件

# 复制示例文件 cp .env.example .env # 用 nano 编辑 nano .env

4.1 核心配置

设置以下必需变量：

# 数据库 - 使用远端托管 PostgreSQL DATABASE_URL=postgresql://user:password@host:5432/dbname # GitHub tokens（两个填相同值） GH_TOKEN=ghp_your_token_here GITHUB_TOKEN=ghp_your_token_here # 服务器设置（Docker Compose 默认端口 3000） PORT=3000

GitHub Token 设置：

1. 访问 GitHub Settings -> Tokens
2. 点击 "Generate new token (classic)"
3. 勾选 scope：repo
4. 复制 token（以ghp_...开头）
5. 在.env中同时设置GH_TOKEN和GITHUB_TOKEN

数据库选型：

注意：SQLite 是本地开发的默认选择，零配置即可运行。云部署推荐 PostgreSQL，可靠性与网络可达性更好。

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

配置佐证：根目录 docker-compose.yml 中，app服务通过env_file: .env注入全部环境变量，并声明了archon_data与archon_user_home两个命名卷：前者持久化/.archon（workspaces、worktrees、数据库文件等），后者持久化/home/appuser（Claude/Codex/Pi 的配置、~/.gitconfig、shell 历史）。这两个卷正是云部署下容器重建后数据不丢的关键。完整变量清单（含可选的高级项，如并发上限MAX_CONCURRENT_CONVERSATIONS、日志级别LOG_LEVEL、遥测开关等）见 .env.example。

4.2 AI Assistant 配置

至少配置一个 AI 助手。

# 安装 Claude Code CLI（如未安装） # 参考 Claude Code 官方安装文档 # 生成 OAuth token claude setup-token # 复制 token（以 sk-ant-oat01-... 开头）

nano .env

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx

CLAUDE_API_KEY=sk-ant-xxxxx

DEFAULT_AI_ASSISTANT=claude

# 安装 Codex CLI（如未安装） # 认证登录 codex login # 提取凭据 cat ~/.codex/auth.json # Windows: type %USERPROFILE%\.codex\auth.json # 复制全部四个值

nano .env

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

DEFAULT_AI_ASSISTANT=codex

4.3 平台适配器配置

至少配置一个平台。

nano .env

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHI... TELEGRAM_STREAMING_MODE=stream # stream（默认）| batch

# 生成 secret openssl rand -hex 32 # 复制输出

WEBHOOK_SECRET=your_generated_secret_here

保存并退出 nano：Ctrl+X，然后Y，然后Enter

5. 数据库迁移

无需手工执行迁移步骤。应用启动时会在 advisory-lock 事务内运行幂等的 migrations/000_combined.sql 来收敛 schema——全新安装与版本升级走的是同一条路径。如果想确认表已创建，可在应用启动后运行：

# 验证表已创建 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

源码级说明：migrations/000_combined.sql头部注释明确标注其幂等属性（"idempotent - safe to run multiple times"），全部使用CREATE TABLE IF NOT EXISTS/ADD COLUMN语义，共包含 14 张业务表（外加 Better Auth 用户认证相关表）。迁移语句顺序测试 验证了该文件在单事务内自上而下执行的语句布局约束，而 bundled-schema.ts 会将同一份 SQL 打包进二进制，保证容器内外 schema 一致。升级时缺列会自动补齐，日志中看到db.pg_schema_init_completed即代表收敛成功。

6. Caddy 配置

Caddy 提供基于 Let's Encrypt 的自动 HTTPS。

创建 Caddyfile

# 复制示例文件——无需手工编辑 cp Caddyfile.example Caddyfile

Caddyfile 会自动从.env读取{$DOMAIN}和{$PORT}。确保设置了DOMAIN：

DOMAIN=archon.yourdomain.com

Caddy 的工作原理

• 自动从 Let's Encrypt 获取 SSL 证书
• 处理 HTTPS (443) 与 HTTP (80) -> HTTPS 的重定向
• 将请求代理到应用容器
• 自动续期证书

配置佐证：Caddyfile.example 展示了完整的反向代理结构：/webhooks/*与/api/health两条路径始终绕过认证（保证 webhook 可达性与健康检查不被拦截）；其余流量默认无认证，也可切换为 Option A（表单登录，需--profile auth）或 Option B（Basic Auth，设置CADDY_BASIC_AUTH）两种认证方案。对/api/stream/*的 SSE 长连接使用了flush_interval -1禁用缓冲，确保流式输出实时到达浏览器；末尾还配置了X-Content-Type-Options、Strict-Transport-Security等安全响应头与encode gzip zstd压缩。

可选：表单认证

需要带样式的登录页时，使用auth-serviceprofile。生成 bcrypt 哈希与 cookie secret：

docker compose --profile auth run --rm auth-service \ node -e "require('bcryptjs').hash('YOUR_PASSWORD', 12).then(h => console.log(h))" docker run --rm node:22-alpine \ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

将结果添加到/opt/archon/.env：

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

bcrypt 哈希中的每一个$都必须转义为$$；否则 Docker Compose 会将其当作变量插值。在Caddyfile中取消Option A表单认证块的注释，并注释掉默认的无认证handle块。启动时使用--profile cloud --profile auth（使用本地 PostgreSQL 容器时再加--profile with-db）。

auth-service 容器定义见根目录 docker-compose.yml 的auth-service服务（profiles: ["auth"]，构建自 auth-service 目录），其相关环境变量（AUTH_SERVICE_PORT、COOKIE_MAX_AGE等）的默认值与注释见 .env.example。

7. 启动服务

配置工作区权限（仅 Linux）

# 创建工作区目录并设置容器用户（UID 1001）的权限 mkdir -p workspace sudo chown -R 1001:1001 workspace

为什么要 1001：docker-entrypoint.sh 会在容器启动时以appuser（UID 1001）身份修正/.archon与/home/appuser的属主；若挂载的宿主目录属主不符，Claude/Codex 子进程可能静默失败。Linux 上务必执行上述chown，这与.env.example中ARCHON_ALLOW_ROOT_FALLBACK的说明一致——该选项只是 macOS VirtioFS 绑定挂载场景的逃生舱，默认保持 fail-loud。

方案 A：远端 PostgreSQL（推荐）

使用托管数据库时：

# 启动应用与 Caddy 反向代理 docker compose --profile cloud up -d --build # 查看日志 docker compose --profile cloud logs -f app

方案 B：本地 PostgreSQL

使用with-dbprofile 时：

# 启动应用、postgres 与 Caddy docker compose --profile with-db --profile cloud up -d --build # 查看日志 docker compose --profile with-db --profile cloud logs -f app docker compose --profile with-db --profile cloud logs -f postgres

监控启动过程

# 观察启动日志（使用本地 PostgreSQL 时加上 --profile with-db） docker compose --profile cloud logs -f app # 留意以下标志： # [App] Starting Archon # [Database] Connected successfully # [App] Archon is ready!

按Ctrl+C退出日志（服务会继续运行）。

Compose 结构说明：根目录 docker-compose.yml 定义了四个服务及其 profile 归属：app（无 profile，始终启动，带 30s 间隔的健康检查）、postgres（profiles: ["with-db"]，本地数据库选项）、caddy（profiles: ["cloud"]，HTTPS 反向代理，依赖 app 健康检查通过后启动）、auth-service（profiles: ["auth"]，表单登录）。with-db+cloud两个 profile 可叠加使用，与文档第 4.1 节的本地 PostgreSQL 方案一一对应。

8. 验证部署

检查健康端点

在本机执行：

# 基础健康检查 curl https://archon.yourdomain.com/api/health # 期望输出：{"status":"ok"} # 可选：直接验证数据库连通性 psql "$DATABASE_URL" -c 'SELECT 1'

端点实现：/api/health是 Compose 内置健康检查（docker-compose.yml 中healthcheck每 30s 探测一次）与外部监控共用的端点，由 packages/server/src/routes/api.ts 实现；该路径与/api/auth/*一样被列入公开网关白名单（PUBLIC_API_GATE_PREFIXES），确保在开启 Web 认证或网关鉴权时健康检查依然可达。health 返回还包含 Web 适配器信息与并发状态。

检查 SSL 证书

在浏览器中访问https://archon.yourdomain.com/api/health：

• 应显示绿色锁标
• 证书颁发者为 "Let's Encrypt"
• 从 HTTP 自动重定向到 HTTPS

检查 Telegram（如已配置）

在 Telegram 上给 bot 发消息：

/help

应收到 bot 回复的可用命令列表。

9. 配置 GitHub Webhooks

现在应用有了公网 URL，可以配置 GitHub webhooks 了。

生成 Webhook Secret（如第 4 节未生成）

# 在服务器上 openssl rand -hex 32 # 如未设置，将输出复制到 .env 的 WEBHOOK_SECRET

为仓库添加 Webhook

1. 前往：https://github.com/owner/repo/settings/hooks
2. 点击 "Add webhook"

Webhook 配置：

3. 点击 "Add webhook"
4. 在 "Recent Deliveries" 标签页确认投递成功（绿色勾选）

测试 webhook：

在 issue 下评论：

@your-bot-name can you analyze this issue?

Bot 应回复分析结果。

实现细节：webhook 端点/webhooks/github与健康检查一样在 Caddyfile 中位于认证旁路路径（handle /webhooks/*），保证 GitHub 回调不被登录拦截；服务端以WEBHOOK_SECRET校验签名。如需限制触发者，可在.env中设置GITHUB_ALLOWED_USERS（逗号分隔、大小写不敏感的用户名白名单），为空时所有用户都可触发。

10. 维护与运维

查看日志

# 全部服务 docker compose --profile cloud logs -f # 指定服务 docker compose --profile cloud logs -f app docker compose --profile cloud logs -f caddy # 最近 100 行 docker compose --profile cloud logs --tail=100 app

更新应用

# 拉取最新代码 cd /opt/archon git pull # 重建并重启 docker compose --profile cloud up -d --build # 查看日志 docker compose --profile cloud logs -f app

升级后无需手工迁移：应用重启时会再次以幂等方式执行migrations/000_combined.sql收敛 schema，新表/新列自动补齐，日志中的db.pg_schema_init_completed是收敛成功的确认信号。

重启服务

# 重启全部服务 docker compose --profile cloud restart # 重启指定服务 docker compose --profile cloud restart app docker compose --profile cloud restart caddy

停止服务

# 停止全部服务 docker compose --profile cloud down # 停止并删除卷（注意：会删除数据） docker compose --profile cloud down -v

故障排查

Caddy 无法获取 SSL 证书

检查 DNS：

dig archon.yourdomain.com # 应返回服务器 IP

检查防火墙：

sudo ufw status # 应放行 80 和 443 端口

检查 Caddy 日志：

docker compose --profile cloud logs caddy # 查看证书签发尝试

常见原因：

• DNS 尚未传播（等待 5–60 分钟）
• 防火墙阻止了 80/443 端口
• Caddyfile 中域名拼写错误
• A 记录未指向正确 IP

应用无响应

检查是否在运行：

docker compose --profile cloud ps # 应显示 'app' 和 'caddy' 状态为 'Up'

检查健康端点：

curl http://localhost:3000/api/health # 直接测试应用（绕过 Caddy）

检查日志：

docker compose --profile cloud logs -f app

数据库连接错误

远端数据库：

# 从服务器测试连接 psql $DATABASE_URL -c "SELECT 1"

检查环境变量：

cat .env | grep DATABASE_URL

重启应用以重新执行 schema 收敛：

docker compose restart app # 应用每次启动都会重新执行 migrations/000_combined.sql； # 缺失的表/列会被自动补齐（SQL 是幂等的）。 # 日志中出现 db.pg_schema_init_completed 即确认成功。

GitHub Webhook 不工作

检查 webhook 投递：

1. 进入 GitHub 的 webhook 设置
2. 点击 "Recent Deliveries"
3. 查看错误信息

验证 webhook secret：

cat .env | grep WEBHOOK_SECRET # 必须与 GitHub webhook 配置一致

测试 webhook 端点：

curl https://archon.yourdomain.com/webhooks/github # 应返回 400（缺少签名）——说明端点可达

磁盘空间不足

检查磁盘占用：

df -h docker system df

清理 Docker：

# 移除未使用的镜像和容器 docker system prune -a # 移除未使用的卷（谨慎操作） docker volume prune

至此，一套完整的 Archon 云部署已就绪：Caddy 自动 HTTPS、托管或本地 PostgreSQL、Claude Code / Codex 任一 AI 助手、Telegram 或 GitHub Webhooks 平台接入，以及一套可持续升级与排障的运维流程。如需构建自定义镜像（Dockerfile.user）或了解更多 Compose 高级用法，可继续阅读 Docker 部署完整参考。

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