【免费下载链接】Choruz项目地址https://gitcode.com/gh_mirrors/ch/Choruz点击查看免费下载Choruz 是一个本地优先的人机协作平台人、AI Agent 在类似 Slack 的空间里通过消息、任务与文件协同工作。本文是一份面向新手的 Choruz 生产运维指南带你从零开始接入 Prometheus 监控 Choruz 的/metrics端点、配置 3 条核心告警规则、按 Runbook 流程完成健康巡检、故障排查与版本回滚。一、Choruz 生产架构速览4 个核心组件与端口Choruz 的 host-native 部署non_docker模式由以下几部分构成先记住它们的端口后面所有监控和排查都围绕它们展开组件作用默认端口choruz-api-gatewayREST API、认证、Webhook 投递3000choruz-pipeline实时管线WebSocket / 事件投递3020Web 应用Next.js用户界面、文档站3100PostgreSQL / CaddyNginx数据库 / 反向代理5432 / —用户看到的一切——群聊、私聊、附件、终端会话——都跑在这套后端之上服务单元模板可直接参考 infra/ops/systemd/choruz-api-gateway.serviceLinux 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 中为两个后端各配置一个 jobscrape_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_event_backlog_total事件积压量生产稳态应低于 500choruz_audit_logs_total审计日志写入特权写操作 100% 有审计行choruz_http_responses_total{class5xx}服务端 5xx 响应数用于错误率告警choruz_activity_batches_total{outcomefailed}认证数据摄入失败批次数进程计数器重试会重复累加choruz_realtime_gateway_up/choruz_agent_gateway_up网关存活状态持续为 1choruz_wal_recovery_success管线 WAL 恢复成功与否必须为 1choruz_principals_total/choruz_conversations_total/choruz_messages_total业务规模基数出现即代表/metrics可达三、配置 Choruz 告警规则3 条必须有的核心告警仓库自带现成的告警规则文件 infra/ops/alerts/choruz-alerts.yaml直接加载到你的 Alertmanager 即可告警触发条件持续时间级别ChoruzApiGatewayDownabsent(choruz_principals_total)2 分钟criticalChoruzEventBacklogGrowingchoruz_event_backlog_total 5005 分钟warningChoruzAuditLogsMissingincrease(choruz_audit_logs_total[15m]) 015 分钟warning配合 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 Checkspnpm 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。五、故障排查 Runbook4 类常见事故处置步骤事故 1API 网关挂了systemctl status choruz-api-gatewaymacOS 用launchctl print system/com.choruz.api-gateway查日志/var/log/choruz/api-gateway.log二进制缺失或过期 → 按 docs/operations/deploy.md 的 managed device upgrades 流程启用已验证包最新发布有问题 → 用同一流程的 verified rollback 回滚并带就绪 URL 复检事故 2事件积压持续增长查/metrics中的choruz_event_backlog_total确认 Webhook 目标返回2xx调用POST /v1/webhooks/flush重试待投递事件积压仍在涨 → 重启choruz-api-gateway验证客户端能从 cursor 断点续传事故 3WAL 恢复报错对choruz_wal_recovery_success 0告警进程存活监控要单独配置健康的/readyz不能证明 WAL 恢复成功找启动时的WAL crash recovery incomplete摘要与WAL recovery operation failed记录用stage/path/error字段区分权限、库损坏、持久化失败先保留沙箱_wal目录与 SQLite sidecar 文件再修复有证据的存储/权限问题受控重启管线重新扫描复核新摘要与恢复指标再单独核对受影响命令的重试/死信记录⚠️ 不要为了消除告警而删库或把未完成的工作标记成功。事故 4无头主机启动失败choruz-server会内嵌 PostgreSQL 并监管网关与管线。以 stderr 中第一个失败而非最后的关闭消息为准日志特征含义与下一步no migrations dir found找不到发布包的migrations/目录恢复完整匹配版本而不是只补 server 二进制embedded postgres failed to start按error字段定位阶段检查磁盘、权限、端口 5433不要删除pgdatabackend spawn failed从同一发布版补齐缺失的兄弟二进制3000/3020 端口须空闲或被预期服务占用backend child failed; terminating choruz-server这是结果不是根因向上找 child-exit 记录再修事故 5密钥轮换失败确认审计中有agent.secret_rotated核对无 token 泄漏到日志由签入的人类身份重新轮换客户端卡死时禁用该 principal 并创建替换 agent六、追踪一次用户交互从告警定位到根因定位某用户某时刻操作异常类问题时推荐这条链路设置CHORUZ_LOG_FORMATjson让服务 stderr 输出结构化日志配合进程监管器做日志轮转用trace_id/request_id串联请求日志再按 trace、turn、command 标识关联已提交消息用 activity CLI 导出受影响时间窗的观测数据用法见 docs/operations/cli.md注意两点边界客户端观测不是服务端审计证据终端完成缺失可能只是进程断开不等于用户做了某个决定。持久化记录才是行为分析的权威来源。七、发布与回滚让每次变更可验证、可退回发布门禁清单docs/operations/runbook.md Release Checklistcargo test --workspacepnpm web:check与pnpm web:buildpnpm host:smoke与pnpm api:smokeinfra/ops/check.sh使用已验证的 CI 产物激活部署不要部署 PR/fork 产物激活与回滚用仓库自带 helper要求 Python 3.12python3 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/docshelper 会先校验哈希、可执行权限与平台基线再原子替换current并等待就绪失败时自动恢复已验证的previous版本。回滚后务必重跑pnpm api:smoke并确认/metrics与告警面板恢复绿色。⚠️ 关键认知二进制回滚不会撤销数据库迁移。回滚前先备份并核对 schema 兼容性详见 docs/operations/deploy.md。八、运维文档与脚本导航 资料路径主机运维 Runbook本文事故章节的来源docs/operations/runbook.mdSLO / 错误预算 / 值班规则docs/operations/slo.md部署、发布与回滚docs/operations/deploy.mdCLI 与 activity 数据追踪docs/operations/cli.mdPrometheus 告警规则infra/ops/alerts/choruz-alerts.yaml服务单元模板infra/ops/systemd/、infra/ops/launchd/冒烟 / 状态 / 启停脚本infra/host/smoke.sh、infra/host/status.sh指标注册实现crates/choruz-common/src/metrics.rs按这套流程走一遍/metrics可抓取 → 3 条告警在线 → 巡检清单每日跑 → 4 类事故有章法 → 发布回滚可验证。你的 Choruz 生产环境就具备了从能跑到敢跑的运维底座。赞分享【免费下载链接】Choruz项目地址https://gitcode.com/gh_mirrors/ch/Choruz点击查看免费下载相关推荐Workbox Streams流式处理实战如何拼接多个资源生成新ResponseWorkbox Streams流式处理实战如何拼接多个资源生成新Response 如果你正在开发 PWA渐进式网页应用一定会遇到这样的场景想把缓存的页前端开发工具如何快速实现AI驱动的3D建模BlenderMCP智能工作流完整指南如何快速实现AI驱动的3D建模BlenderMCP智能工作流完整指南 你是否曾经为复杂的3D建模操作感到头疼是否希望AI助手能直接帮你操作Blender让MCP 服务AI 应用人工智能工具调用CANN/asc-devkit核间同步等待APICrossCoreWaitFlag\ ISASI\ a nameZH CN_TOPIC_0000001787470374 /a 产品支持情况a na人工智能深度学习算子库CANNAscend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考