运维手册

本文档覆盖 AuthNexus 生产环境的日常运维操作，包括健康监控、日志管理、数据库维护、证书轮换、配置热更新与常见故障排查。

健康监控

节点心跳状态

每个 server_app 节点通过 Channel 1 定期向 Control Plane 发送心跳：

POST /cp/v2/nodes/:id/checkin

心跳负载包含应用版本快照与运行指标（连接数、内存、CPU 等）。管理后台 节点管理 页面可查看：

• 最后心跳时间 — 超过预期间隔（默认 60s）视为异常
• 节点状态 — online / offline / stale
• 应用版本一致性 — 多节点间是否存在版本漂移

建议配置告警规则：心跳超时 > 2 个周期即触发告警。

SSE 连接健康

Channel 2 SSE 长连接用于 CP 向节点推送 hint 事件。健康指标：

指标	正常范围	异常处理
连接状态	每节点 1 条活跃连接	新连接到达自动踢旧连接
Ping 间隔	每 30s 一次 keep-alive	超过 60s 无 ping 视为断开
事件队列	队列未满	队列满时丢弃最旧事件（hint-only 语义安全）

SSE 降级时，Delta Puller 自动切换到快速轮询模式（800ms/5000ms），业务不受影响但 CP 负载会上升。

OCSP Staple 新鲜度

Channel 4 OCSP 独立于 mTLS 通道，节点 OcspStaplingManager 周期性拉取 OCSP Response：

• 正常刷新周期：约 15 分钟（自适应 nextUpdate / 2）
• Staple 有效窗口：SDK 端校验时间窗 maxsec=1800s
• 吊销处理：收到 revoked 时节点继续 staple revoked response 给 SDK（SDK must-staple 验证拒绝握手），管控通道保持存活以便恢复

监控要点：关注 OCSP fetch 失败率与 staple 过期时间。

日志管理

日志级别

级别	用途	注意事项
info（默认）	生产运行	关键业务事件、启动/关闭、错误
debug	本地排查	日志量急剧增长，几十 MB 起跳
trace	深度调试	仅短期开启，污染性能基线

WARNING

生产环境禁止长期开启 debug 或 trace 级别。调试完毕后务必恢复 info。

日志轮转

推荐使用系统级日志轮转工具：

Linux (logrotate)：

/var/log/authnexus/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Windows：通过任务计划程序定期归档日志文件，或使用 NSSM 等服务管理工具的日志轮转功能。

关键日志模式

运维应关注以下日志关键词：

• [ERROR] — 任何错误均需排查
• TLS handshake failed — 证书或 CA 链问题
• OCSP fetch failed — OCSP 通道异常
• delta puller lag — CP 同步延迟
• SSE disconnected — 事件通道断开，自动重连中

数据库维护

Control Plane DB 与 Server Runtime DB 是 两套独立数据库。

SQLite 维护

# VACUUM — 回收空间、优化性能（停机或低峰期执行）
sqlite3 auth_nexus_control.db "VACUUM;"

# 备份 — 使用 SQLite online backup API
sqlite3 auth_nexus_control.db ".backup 'backup_control_$(Get-Date -Format yyyyMMdd).db'"

# 完整性检查
sqlite3 auth_nexus_control.db "PRAGMA integrity_check;"

建议：

• 每周执行一次 VACUUM
• 每日备份，保留 7 天
• 数据库文件与 WAL 一起备份

PostgreSQL 维护

-- 常规 VACUUM + ANALYZE（可在线执行）
VACUUM ANALYZE;

-- 查看表膨胀
SELECT relname, n_dead_tup, last_autovacuum
FROM pg_stat_user_tables
WHERE n_dead_tup > 1000
ORDER BY n_dead_tup DESC;

-- 索引重建（低峰期）
REINDEX DATABASE authnexus CONCURRENTLY;

建议：

• 确认 autovacuum 已启用（默认开启）
• 监控 pg_stat_user_tables 中的死元组数量
• 定期使用 pg_dump 进行逻辑备份
• 大表考虑 pg_repack 在线整理

证书轮换

CA 证书续期

AuthNexus 使用四类独立 CA：

CA	用途	轮换影响
cp_server_ca	CP 服务端证书	影响所有节点到 CP 的连接
cp_node_client_ca	节点客户端证书	影响节点 mTLS 身份验证
tcp_server_ca	业务 TCP 服务端证书	影响所有 SDK 连接
app_client_ca	SDK 客户端证书	影响特定应用的 SDK 认证

CA 续期通过管理后台 PKI 管理页面操作，步骤：

1. 生成新 CA 密钥对与证书
2. 将新 CA 添加为受信（此时新旧 CA 并存）
3. 逐步用新 CA 签发替换证书
4. 确认所有节点/SDK 切换完毕后移除旧 CA

节点证书重新注册

节点证书过期或需要轮换时：

1. 在管理后台撤销旧证书
2. 删除节点本地旧证书文件（必须删除，否则节点用废证书死循环 403）
3. 重启节点，触发 re-enroll 流程
4. 新证书自动签发并下发

DANGER

Re-enroll 决策只看证书文件存在性。如果旧证书文件仍存在，节点会用废证书反复尝试连接。

App Client CA 热替换

App Client CA 支持在线热替换，通过 generation 机制保证一致性：旧 TLS context 上的在途握手会被新 generation 拒绝。

配置热更新

AuthNexus 支持多种配置类型的热更新，通过 Channel 1 + Channel 2 协作完成。

配置类型与推送机制

配置类型	说明	推送方式
server_runtime_settings	服务运行时参数	CP event hint + 节点拉取
app_policy	应用策略	CP event hint + 节点拉取
app_variables	应用变量	CP event hint + 节点拉取
app_client_ca_bundle	应用客户端 CA 包	CP event hint + 节点拉取
app_mtls_trust_bundle	应用 mTLS 信任包	CP event hint + 节点拉取
cp_agent_runtime	CP Agent 运行参数	CP event hint + 节点拉取

配置更新流程：

1. 管理员通过 Admin API 修改配置
2. CP 发送 config.pending event hint（Channel 2 SSE）
3. 节点收到 hint 后通过 POST /cp/v2/nodes/:id/configs/pull 拉取新配置
4. 应用成功后通过 POST /cp/v2/nodes/:id/configs/acks 批量 ACK
5. 应用失败则通过 POST /cp/v2/nodes/:id/configs/errors 上报错误

新增配置类型

在 src/control_plane/service/config_registry.h 中注册，实现 pull / ack / error 三端点逻辑。

故障排查

节点断开连接

现象：节点状态变为 offline，管理后台不再收到心跳。

排查步骤：

1. 检查节点进程是否存活
2. 检查节点到 CP 的网络连通性（端口 9091）
3. 查看节点日志中的 TLS 握手错误
4. 确认节点 mTLS 客户端证书未过期
5. 检查 CP 服务端是否正常运行

TLS 握手失败

现象：日志出现 TLS handshake failed 或 SSL_do_handshake 错误。

常见原因及解决：

原因	诊断方法	解决方案
证书过期	检查证书 notAfter	续期或重新签发
CA 链不完整	验证信任链	补全中间 CA
EKU 不匹配	检查 clientAuth/serverAuth	重新签发含正确 EKU 的证书
SAN 不匹配	检查 urn:authnexus:app:<id> URI SAN	确认 app_id 一致
OCSP must-staple 无 staple	检查 OCSP 通道	修复 OCSP fetch

临时调试：短暂开启 debug 日志级别，查看完整握手过程。

OCSP Fetch 失败

现象：日志出现 OCSP fetch failed，SDK 握手被拒绝。

排查步骤：

1. 确认 CP OCSP 端口（默认 9092）可达
2. OCSP 使用 plain HTTP（非 TLS），检查是否被防火墙拦截
3. 检查 CP OcspResponder 签名 CA 是否正常
4. 节点本地缓存在 nextUpdate 有效期内仍可用

Delta Puller 延迟

现象：auth_epoch_changes 或 server_blacklist_changes 同步滞后。

排查步骤：

1. 确认 SSE 连接是否健康（健康时间隔 5s/30s，降级时 800ms/5000ms）
2. 检查 CP 数据库负载
3. 检查网络延迟与丢包率
4. 查看节点日志中的 delta puller 相关条目

备份与恢复策略

备份内容清单

内容	优先级	备份方式	频率
Control Plane DB	关键	在线备份	每日
PKI CA 密钥	关键	离线加密存储	变更时
节点配置文件	重要	文件复制	变更时
Server Runtime DB	一般	在线备份	每日
日志文件	可选	归档压缩	按轮转策略

恢复流程

1. Control Plane 恢复：还原 CP 数据库 + PKI 密钥 → 启动 control_plane_app → 等待节点自动重连
2. 节点恢复：还原节点配置与证书 → 启动 server_app → 节点自动向 CP checkin 并拉取最新配置
3. 灾难恢复：如果 CP 不可用，已运行的 server_app 节点会基于本地缓存继续服务，Delta Puller 切换到快速轮询等待 CP 恢复

停机维护窗口

推荐的维护操作顺序：

1. 通知相关方维护时间窗口
2. 先停 server_app 节点（SDK 连接会断开）
3. 执行 CP 数据库维护
4. 启动 control_plane_app 并确认就绪
5. 逐个启动 server_app 节点
6. 验证所有节点心跳正常、SSE 连接建立