部署指南（Docker Compose）

在一台 VPS 上从零部署完整 Argus 栈。部署物在仓库 infra/deploy/： docker-compose.deploy.yml（16+ 容器全栈）+ .env.example（全部环境变量）+ scripts/（bootstrap / 部署 / 备份 / 恢复 / 升级 / 回滚）。

前置：一台 Ubuntu 24.04 LTS 主机（2 vCPU / 4 GB 起，见硬件要求）、一个域名（DNS 可控）、本地 SSH 公钥。

DNS：两条 A 记录

Argus 需要两个域名：一个给上报入口 / 演示页，一个给 Console。在 DNS 服务商创建：


argus.example.com           A   <VPS-IP>   # 上报入口（ingestion 经 Caddy）
console.argus.example.com   A   <VPS-IP>   # Console

使用 Cloudflare 时这两条记录须设 proxied=No（DNS only）——Caddy 用 Let’s Encrypt HTTP 验证签发证书，代理会挡掉验证请求。

初始化 VPS（bootstrap）

SSH 进主机 root，跑 bootstrap 脚本：


curl -fsSL https://raw.githubusercontent.com/MatrixFutureLabs/x-argus/main/infra/deploy/scripts/bootstrap-vps.sh | bash

完成后：Docker / docker compose 已装、ufw 防火墙放行 22/80/443、argus 用户（docker 组）与 /opt/argus 目录就位。

配置 .env

切到 argus 用户，clone 仓库并从模板生成 .env：


su - argus && cd /opt/argus
git clone https://github.com/MatrixFutureLabs/x-argus.git .
cp infra/deploy/.env.example infra/deploy/.env
chmod 600 infra/deploy/.env
vim infra/deploy/.env

填写所有 changeme-* 字段，关键项：

变量	说明
`STAGE_DOMAIN` / `STAGE_CONSOLE_DOMAIN`	上一步的两个域名
`CADDY_ACME_EMAIL`	真实邮箱（Let’s Encrypt 注册用，拒绝 `ops@example.com` 这类占位）
`CLICKHOUSE_PASSWORD` / `POSTGRES_PASSWORD`	强随机（`openssl rand -hex 16`）
`ARGUS_DSN_PUBLIC` / `ARGUS_DSN_SECRET` / `ARGUS_DSN_PROJECT`	项目上报凭据，见 DSN 与 HMAC
`NEXT_PUBLIC_ARGUS_DSN`	Console 自我上报（dogfood）用的完整 DSN
`CONSOLE_BASIC_AUTH_USER` / `CONSOLE_BASIC_AUTH_HASH`	Console basic auth（hash 用 `docker run --rm caddy:2 caddy hash-password --plaintext '...'` 生成）
`ARGUS_ADMIN_TOKEN`	跨租户运营后台口令，强随机；留空且未开非安全模式时后台 fail-closed 拒绝一切登录
`IDENTITY_KMS_KEY` / `SESSION_SECRET`	identity 加密 / 会话密钥（KMS key 须恰好 32 字符）

DSN 一致性是最常见的翻车点：ARGUS_DSN_PUBLIC/SECRET、ARGUS_PROJECT_CREDENTIALS、 NEXT_PUBLIC_ARGUS_DSN 三处必须用完全相同的 public/secret，否则 HMAC 验签 401 （上报、日志回捞、反馈附件上传三条链路分别验签）。

部署


bash infra/deploy/scripts/deploy.sh

期望：各服务 Up + healthcheck (healthy)。失败时看单个服务日志：


docker compose -f infra/deploy/docker-compose.deploy.yml --env-file infra/deploy/.env logs <service>

验证

https://argus.example.com/ → demo 页可触发 crash / log；
https://console.argus.example.com/ → basic auth 后进 Console，/issues 能看到刚触发的崩溃；
巡检 + 冒烟：


argus-doctor                                            # 全栈健康巡检
bash scripts/ci/smoke-stage.sh https://argus.example.com  # 期望 [smoke] PASS ✓

Caddy 与域名 / TLS

Caddy 按 .env 里的两个域名自动向 Let’s Encrypt 申请并续期证书，无需手工管理。拿不到证书时依次检查：

ufw status 确认 80/443 放行；
dig argus.example.com +short 确认 DNS 已生效且未过代理；
CADDY_ACME_EMAIL 是真实邮箱；
docker logs argus-caddy 2>&1 | grep -i cert 看具体报错。

每日备份与恢复

三套数据存储每日错峰备份到 S3 兼容对象存储（示例用 Cloudflare R2，.env 填 R2_* 四项），保留 7 天，走容器化 rclone（宿主机无需装 rclone）：

存储	脚本	时间
ClickHouse（事件数据）	`backup-clickhouse.sh`	03:00
PostgreSQL（元数据，所有 `argus_*` 库）	`backup-postgres.sh`	03:15
MinIO（日志 / 符号 / 反馈对象桶）	`backup-minio.sh`	03:30


crontab /opt/argus/infra/deploy/crontab   # 安装定时任务
crontab -l                                # 验证

恢复（破坏性，须显式确认；省略备份名 = 取最新一份）：


CONFIRM=yes bash infra/deploy/scripts/restore-clickhouse.sh
CONFIRM=yes bash infra/deploy/scripts/restore-postgres.sh
CONFIRM=yes bash infra/deploy/scripts/restore-minio.sh

备份 ↔ 恢复闭环可用 bash scripts/ci/check-backup-restore.sh 端到端自验（仅需 docker）。备份脚本成功后会上报”备份新鲜度”元数据，argus-doctor 超 24 小时未见成功备份会 WARN。

升级与回滚


bash scripts/ops/upgrade.sh        # 升级前自动备份三库 → 应用新镜像 → 健康校验 → 失败自动回滚
bash infra/deploy/scripts/rollback.sh <tag> [--restore]   # 手动回滚到指定镜像 tag（--restore 连数据一起恢复）

自托管模式（无 Stripe）

.env 不设置 STRIPE_API_KEY 时 identity 自动进入自托管模式：配额完全不拦截、不发配额警告邮件、/checkout-session 返回 400 self_hosted。自托管不需要接任何计费。

完整 runbook（含 GitHub Actions 自动部署、production 手动发布流程、Stripe 接入、AI 闭环观测）见 infra/deploy/README.md。部署后遇到问题先查故障排查。