Choruz 是一个本地优先的人机协作平台，人、AI Agent 在类似 Slack 的空间里通过消息、任务与文件协同工作。本文是一份面向新手的 Choruz 生产运维指南，带你从零开始：接入 Prometheus 监控 Choruz 的/metrics端点、配置 3 条核心告警规则、按 Runbook 流程完成健康巡检、故障排查与版本回滚。

一、Choruz 生产架构速览：4 个核心组件与端口

Choruz 的 host-native 部署（non_docker模式）由以下几部分构成，先记住它们的端口，后面所有监控和排查都围绕它们展开：

用户看到的一切——群聊、私聊、附件、终端会话——都跑在这套后端之上：

服务单元模板可直接参考 infra/ops/systemd/choruz-api-gateway.service（Linux systemd）与 infra/ops/launchd/（macOS launchd），反向代理配置见 infra/ops/caddy/Caddyfile。

二、5 分钟接入 Prometheus：抓取 /metrics 端点

Choruz 每个二进制都内置了一个 Prometheus 文本格式的/metrics端点（指标注册实现见 crates/choruz-common/src/metrics.rs）。先手动验证：

curl -fsS http://127.0.0.1:3000/metrics

看到# HELP/# TYPE开头的输出即说明采集就绪。在 Prometheus 中为两个后端各配置一个 job：

scrape_configs: - job_name: choruz-api-gateway static_configs: - targets: ["127.0.0.1:3000"] metrics_path: /metrics - job_name: choruz-pipeline static_configs: - targets: ["127.0.0.1:3020"] metrics_path: /metrics

💡 注意：网关（3000）与管线（3020）必须分开抓取——"缺少采集点或就绪探测失败"本身就是主机可用性事故，因为进程没起来时连错误计数都不存在。

Choruz 核心指标速查表（来自 docs/operations/slo.md）：

三、配置 Choruz 告警规则：3 条必须有的核心告警

仓库自带现成的告警规则文件 infra/ops/alerts/choruz-alerts.yaml，直接加载到你的 Alertmanager 即可：

配合 SLO 中的值班规则（docs/operations/slo.md）：

• 🚨 网关宕机超过 2 分钟 → 立即呼叫值班（page）
• 🚨/readyz连续失败超 2 分钟（即使/healthz还正常）→ 立即 page
• 🚨 消息写入 P95 延迟超过 500ms 持续 10 分钟 → 立即 page
• 📋 积压超阈值超 5 分钟 → 开工单

SLO 基线建议：API 可用率 99.9%/月（约每月 43 分钟错误预算）、SendMessageP95 < 150ms、断线重连恢复 < 3s。

四、日常巡检：健康检查与冒烟测试命令清单

把下面 6 步当作每日巡检（源自 docs/operations/runbook.md 的 Standard Checks）：

pnpm host:status # 1. 主机与服务状态 pnpm api:smoke # 2. API 冒烟测试 curl -fsS http://127.0.0.1:3000/healthz # 3. 网关存活 curl -fsS http://127.0.0.1:3000/readyz # 4. 网关就绪 curl -fsS http://127.0.0.1:3020/readyz # 5. 管线就绪 curl -fsS http://127.0.0.1:3000/metrics # 6. 指标可抓取

最后再检查一遍 infra/host/.env 是否有配置漂移。/healthz只证明进程活着，/readyz才是可接流的权威信号——两者要分开看。冒烟脚本细节可参考 infra/host/smoke.sh 与 infra/host/status.sh。

五、故障排查 Runbook：4 类常见事故处置步骤

事故 1：API 网关挂了

1. systemctl status choruz-api-gateway（macOS 用launchctl print system/com.choruz.api-gateway）
2. 查日志：/var/log/choruz/api-gateway.log
3. 二进制缺失或过期 → 按 docs/operations/deploy.md 的 managed device upgrades 流程启用已验证包
4. 最新发布有问题 → 用同一流程的 verified rollback 回滚，并带就绪 URL 复检

事故 2：事件积压持续增长

1. 查/metrics中的choruz_event_backlog_total
2. 确认 Webhook 目标返回2xx
3. 调用POST /v1/webhooks/flush重试待投递事件
4. 积压仍在涨 → 重启choruz-api-gateway，验证客户端能从 cursor 断点续传

事故 3：WAL 恢复报错

对choruz_wal_recovery_success == 0告警（进程存活监控要单独配置；健康的/readyz不能证明 WAL 恢复成功）：

1. 找启动时的WAL crash recovery incomplete摘要与WAL recovery operation failed记录，用stage/path/error字段区分权限、库损坏、持久化失败
2. 先保留沙箱_wal目录与 SQLite sidecar 文件，再修复有证据的存储/权限问题
3. 受控重启管线重新扫描，复核新摘要与恢复指标，再单独核对受影响命令的重试/死信记录

⚠️ 不要为了消除告警而删库或把未完成的工作标记成功。

事故 4：无头主机启动失败

choruz-server会内嵌 PostgreSQL 并监管网关与管线。以 stderr 中第一个失败（而非最后的关闭消息）为准：

事故 5：密钥轮换失败

1. 确认审计中有agent.secret_rotated
2. 核对无 token 泄漏到日志
3. 由签入的人类身份重新轮换
4. 客户端卡死时：禁用该 principal 并创建替换 agent

六、追踪一次用户交互：从告警定位到根因

定位"某用户某时刻操作异常"类问题时，推荐这条链路：

1. 设置CHORUZ_LOG_FORMAT=json，让服务 stderr 输出结构化日志，配合进程监管器做日志轮转
2. 用trace_id/request_id串联请求日志，再按 trace、turn、command 标识关联已提交消息
3. 用 activity CLI 导出受影响时间窗的观测数据（用法见 docs/operations/cli.md）

注意两点边界：客户端观测不是服务端审计证据；"终端完成缺失"可能只是进程断开，不等于用户做了某个决定。持久化记录才是行为分析的权威来源。

七、发布与回滚：让每次变更可验证、可退回

发布门禁清单（docs/operations/runbook.md Release Checklist）：

1. cargo test --workspace
2. pnpm web:check与pnpm web:build
3. pnpm host:smoke与pnpm api:smoke
4. infra/ops/check.sh
5. 使用已验证的 CI 产物激活部署（不要部署 PR/fork 产物）

激活与回滚用仓库自带 helper（要求 Python 3.12+）：

python3 infra/ops/verify-archive.py /path/to/choruz.tar.gz COMMIT_SHA python3 infra/ops/release.py deploy /path/to/extracted-release \ --releases /srv/choruz/releases \ --health-url http://127.0.0.1:3000/readyz \ --health-url http://127.0.0.1:3020/readyz \ --health-url http://127.0.0.1:3100/docs

helper 会先校验哈希、可执行权限与平台基线，再原子替换current并等待就绪；失败时自动恢复已验证的previous版本。回滚后务必重跑pnpm api:smoke并确认/metrics与告警面板恢复绿色。

⚠️ 关键认知：二进制回滚不会撤销数据库迁移。回滚前先备份并核对 schema 兼容性（详见 docs/operations/deploy.md）。

八、运维文档与脚本导航 📚

按这套流程走一遍：/metrics可抓取 → 3 条告警在线 → 巡检清单每日跑 → 4 类事故有章法 → 发布回滚可验证。你的 Choruz 生产环境就具备了从"能跑"到"敢跑"的运维底座。