日常巡检、完整性检查与告警

版本边界

日常运维基线已随正式版本持续交付；本页的生产 Admin Bootstrap 审计与 Secret 应急流程随 v0.8.3 发布，v0.8.4 同样适用。执行前使用 halro version 核对实际二进制。

先区分在线检查与离线维护

在线检查不能代替离线完整性验证。doctor、backup create、backup restore、Usage 维护、Ledger verify/seal 与 Audit verify 都需要数据目录独占锁，必须先停止 Halro。取得锁失败时先找出仍在运行的 进程，不要删除锁文件或复制单个数据文件绕过检查。backup verify 只读取备份归档和 Backup Key， 不访问数据目录，可以在实例运行时独立执行。

config check 只读取待用配置，可以在重启前执行；Metrics 凭据文件有自己的串行化机制，可以按下文 完成在线轮换。其他命令是否可在线执行，以本页明确标注为准。

每日在线巡检

Gateway 与 Admin Listener 都提供：

• /health/live：进程和 HTTP 服务仍在响应；
• /health/ready：当前实例是否可以安全接收业务流量。

Metrics Listener 提供 /health/live 和 /metrics，不提供 /health/ready。常用检查：

halro healthcheck --url http://127.0.0.1:8080/health/ready
curl -fsS http://127.0.0.1:8080/health/live
curl -fsS http://127.0.0.1:8080/health/ready

live=200 只证明进程存活。ready=503 应从响应和 Admin Console → 设置 → 系统状态/诊断 检查实例是否正在 drain、Accounting 是否可用、价格是否隔离，以及配置激活是否过期。Provider 与 Deployment 健康属于业务可用性巡检，不是当前 /health/ready 的直接判定项。

halro stats --config /etc/halro/config.yaml --interval 10s 只适用于没有配置 metrics.credential_file、仍使用 Master Key 派生 Token 的兼容模式。生产推荐的 versioned credential_file 模式下，当前 stats 没有接收独立 Token 文件的参数，应从 Prometheus 或 设置 → 关于与诊断读取同一类持久化写路径和锁等待指标。指标窗口只代表这台主机，不能直接套用 其他磁盘或文件系统的容量结论。

建议每天检查：

• 请求量、错误率、延迟、fallback 与 Provider/Deployment 健康；
• Ledger 写入错误、Usage 队列和分析延迟；
• Project 预算、Token Guard 拒绝与未知价格；
• 证书有效期、Metrics 抓取、Alert 投递与外部 Audit Anchor 新鲜度；
• 备份年龄、最近校验与最近隔离恢复演练结果。

Metrics 不使用 Project、Key、Route、模型、Request ID、源 IP 或原始错误作为无界标签。某些状态 series 缺失表示未知，不能当作零或健康。

变更前检查配置

halro config check --config /etc/halro/config.yaml

校验通过后按部署方式重启，再检查真实 Listener 的 /health/ready 和日志。证书内容、Metrics TLS 文件、日志级别和日志句柄可按配置参数参考使用 SIGHUP； 其他参数需要重启。

离线 doctor

停止 Halro 后执行：

halro doctor --config /etc/halro/config.yaml

doctor 检查配置与目录权限、数据目录独占性、schema、Master Key/Vault、Ledger、Audit、Usage manifest、时区、磁盘空间和资源引用。它不会发起 Provider 网络测试；启动后再从 Admin Console 执行受审计的 Provider/Deployment 测试。

Key Slot 部署还可执行：

halro doctor --config /etc/halro/config.yaml --no-kms

这只做静态检查，不能证明 KMS 解锁或恢复身份可用。完整 doctor 失败时保持实例停止，保存脱敏后的 JSON 结果和日志，按失败域修复；不要截断 WAL、手工编辑数据库或把不完整结果解释成通过。

Usage、Ledger 与 Audit

以下命令都离线执行：

halro usage compact --config /etc/halro/config.yaml
halro usage verify --config /etc/halro/config.yaml
halro usage rebuild-summary --config /etc/halro/config.yaml
halro usage prune --config /etc/halro/config.yaml

halro ledger verify --config /etc/halro/config.yaml
halro ledger seal --config /etc/halro/config.yaml

halro audit verify --config /etc/halro/config.yaml
halro audit verify-anchor \
  --config /etc/halro/config.yaml \
  --anchors /secure-audit/halro-anchors.ndjson

使用原则：

Usage、Ledger 与 Audit

命令	何时使用	通过标准与边界
usage compact	需要立即把 Ledger 新记录写入 Usage 分区	输出新 manifest；它不是备份
usage verify	导出、删旧数据、升级和恢复前后	manifest、记录、费用和 Token 与 Ledger 对账一致
usage rebuild-summary	Usage 派生汇总损坏或无法使用	只从已验证 Ledger 重建；不是修改账务历史的方法
usage prune	按 retention_days 删除过期分析分区	不删除 Ledger；可用 --before YYYY-MM-DD 明确边界
ledger verify	日常完整性、升级和恢复验收	链不能认证时命令失败，保持失败关闭
ledger seal	需要立即封存活动代	不删除历史；封存代仍进入备份与重放
audit verify	核对本地 Audit 链	只能证明当前本地链完整，不等于外部不可抵赖
audit verify-anchor	与独立主机保存的锚文件核对	锚文件必须来自受控离机拉取和留存路径

usage prune 前先执行 usage verify 并确认保留义务；缩短 Admin Console 窗口也不会删除 Ledger， 但历史不会仅靠重新加长窗口自动回到内存视图。

Metrics 凭据轮换

生产非回环 Metrics 使用独立 credential_file 和 mTLS。不要复用 Gateway Key，也不要把 Token 放进 YAML、环境变量、命令参数、截图或工单。

umask 077
halro metrics rotate \
  --config /etc/halro/config.yaml \
  --overlap 10m > /secure-secrets/halro-metrics.token.next

halro metrics list --config /etc/halro/config.yaml
halro metrics verify-audit --config /etc/halro/config.yaml

将新 Token 以文件方式原子交给 Prometheus，确认至少两个抓取周期 up == 1，再按 metrics list 给出的 retiring version 撤销旧版本：

halro metrics revoke --config /etc/halro/config.yaml --version OLD_VERSION

随后证明旧 Token 返回 401，再次执行 metrics verify-audit，并把非敏感链头交给独立审计系统。

Alerts

在 Admin Console → Operations 创建 Generic JSON Webhook；需要认证时使用独立加密 header credential，只允许 Authorization 或 X-Webhook-Token 一类受控 Header，不把密钥放在 URL。 目标必须使用 HTTPS 并通过 Halro 的私网/SSRF 策略。

保存后先执行单端点测试，再执行选择测试，确认接收端、重试、去重和错误分类。告警正文不会包含 Prompt、Response、Provider 凭据、Gateway Key、原始 IP 或原始上游错误。持续检查 halro_alert_delivery_total 与队列深度；Alert 投递本身故障时，必须有独立 dead-man 通道。

最低告警集应覆盖：Halro target/readiness、configuration_stale、Ledger 写错误、Usage 分析落后、 Provider/Deployment 不健康、fallback 或容量压力、Metrics/Audit Anchor、证书到期和 Alert 投递失败。

Bootstrap 审计与 Secret 应急

生产初始化成功后，应在删除 Job 和 bootstrap Secret 之前停止所有 Halro 进程，并离线执行：

halro doctor --config /etc/halro/config.yaml
halro audit verify --config /etc/halro/config.yaml

doctor 会检查 Bootstrap Completion、待投递 Audit 和后续管理员变化；audit verify 还会验证 HMAC 链、checkpoint，以及 Completion 引用的 admin.bootstrap Audit Event 确实存在。相同安装重试必须 沿用稳定 operation-id；只有 created 或 already_completed 才能进入清理阶段。不同 operation ID、 用户名不匹配或状态不明确都应失败关闭，不要换 ID、删库或重置密码绕过。

Setup Token 在首个管理员存在后已经无效，但仍应删除所有副本并检查投影、流水线和日志。若管理员尚未 创建，先停止所有已加载旧 Token 的 Pod，撤销旧 Secret，生成新信封，再启动新 Pod；不要热替换文件。 CSI 或 Kubernetes Secret 清理必须分两阶段：先发布不再挂载 Secret 的工作负载并确认 Pod 可重新调度， 再撤销外部对象。自动化密码在 Completion 前泄露时，停止 Job、轮换密码源，并在完成诊断后使用原 operation-id 重试。完整流程见生产环境 Admin 初始化与 Secret 生命周期。

管理员账户、MFA 与紧急恢复

在 设置 → 管理员账户 中按职责创建 administrator 或 read_only 账号。只读权限由服务端限制为 GET 类查询，适合审计和观察；资源变更、导出、密钥签发和安全操作必须使用管理员账号。不能删除最后 一个管理员，也不要多人共享同一登录身份。

在 设置 → 登录与安全 中为每个管理员分别配置 TOTP 身份验证器。首次启用生成的 10 个恢复码只 完整显示一次，应离线保存；重新生成会立刻废止旧恢复码。添加第二个验证器、撤销设备、关闭 MFA 和 其他敏感操作都要按页面要求重新验证。生产环境使用 admin.mfa_policy: required，并实际演练一次 恢复码登录。

忘记密码或所有验证器均不可用时，停止 Halro 并在主机本地执行离线恢复：

halro admin reset-password \
  --config /etc/halro/config.yaml \
  --username ADMIN_NAME \
  --password-file /secure-secrets/new-admin-password

halro admin reset-mfa --config /etc/halro/config.yaml --username ADMIN_NAME

密码重置和 MFA 重置都会使现有会话失效。恢复后立即登录、重新绑定 MFA、生成并离线保存恢复码， 再检查 Audit 中对应事件。密码文件必须使用受限权限和绝对路径，使用后按组织流程撤销；不要把密码或 TOTP Seed 放在命令参数、环境变量、工单或日志中。

configuration_stale

Admin 变更已经持久化，但新的 topology、鉴权、脱敏或 Token Guard 状态无法安全激活时，Halro 会 令 /health/ready 返回 503，并对数据面返回 503 configuration_stale。这是为了防止旧快照继续 授权已撤销的 Key、使用已删除 Route 或绕过新策略。

处理顺序：

1. 确认 /health/live 仍为 200，保留 /health/ready 的响应；
2. 在 Admin 系统状态记录 activation.domains 中 stale 域、时间和受限原因；
3. 检查 halro_activation_stale、halro_activation_stale_seconds 与首次激活错误；
4. 修复对应的存储、Master Key/Vault 或策略问题，等待后台重新激活；
5. 只有 readiness 恢复 200、stale gauge 为 0 且所有域 current 后才恢复流量。

不要绕过门禁或手工修改数据库。相同原因持续多个恢复周期时，将实例摘流，保留状态与日志；确认 持久化存储和 Master Key 可读后再受控重启。重启不能替代根因修复。

按 Request ID 排查失败

应用应记录 Halro 返回的 Request ID。管理员在 Admin Console → Usage → Failures 按 Project、 Deployment 和 Request ID 定位失败，先查看分类与建议，再决定是否读取捕获内容。

gateway.failure_capture 默认关闭；开启后也只捕获允许的最终失败。点击详情中的 Show 才会读取 Payload 并写入 Audit。记录可能包含脱敏后实际发往上游的 Prompt 和工具参数，仍按客户数据处理； 限制单条大小、每日条数和保留期。策略拒绝的敏感内容不会为诊断而重新保存，捕获失败也不会改变原 请求结果。

排障结束时记录 Request ID、失败分类、受影响时间、修复和验证证据，不复制 Payload 正文。若需要 升级、恢复或密钥轮换，继续执行备份、恢复与恢复演练的门禁。