运维与可观测性

卓越运维依赖可靠的部署流程、全面的遥测与可复用的恢复手册。本章记录 Cirrus CDN 在生产中依托的工具、指标、日志与运行手册。

部署流程

本地开发

• just up——构建并启动 Docker Compose 栈。
• just down / just down-no-volumes——停止容器，可选择是否删除卷。
• just pytest——运行后端测试（uv run pytest -q）。
• just quicktest——运行排除 ACME/DNS 长耗时用例的精简套件。
• just fmt——格式化 Python 代码（autoflake、isort、black）。

生产部署

• just deploy——调用 ansible/ 中的 Ansible 剧本，使用 INVENTORY 与 PLAYBOOK 环境变量（通过 dotenv 加载）。
• 剧本需按本白皮书所述编排基础设施、注入密钥并渲染配置。

运行时监管

• 进程监管——生产环境使用 init 系统（systemd、Kubernetes）管理 API、worker、beat、OpenResty、NSD 进程；Compose 仅适用于本地开发。
• 健康检查——监控：
  • API /healthz（验证 Redis 可用）。
  • OpenResty http://<node>:9145/healthz（Celery 健康检查使用）。
  • Celery worker 存活（如发送 ping 任务）。

指标与仪表盘

• Prometheus（prometheus/prometheus.dev.yml）每 5 秒抓取 127.0.0.1:9145 的 OpenResty 指标。
• 核心指标：
  • nginx_http_requests_total{host,status}——按主机/状态统计请求率。
  • nginx_http_request_duration_seconds——延迟直方图。
  • nginx_cache_status_total{status}——缓存行为（HIT/MISS/STALE/BYPASS）。
  • nginx_upstream_errors_total、nginx_upstream_timeouts_total——源站健康。
  • nginx_upstream_response_seconds——上游 RTT。
  • nginx_ssl_handshake_errors_total{phase}——TLS 握手问题。
• Grafana——通过 grafana/ 中的配置提供仪表盘，可视化缓存效率、源站健康与请求趋势；按组织策略启用鉴权。
• Celery 指标——当前缺失，建议通过 StatsD/Prometheus exporter 输出任务耗时（见第 11 章）。

日志

• API 与 worker——输出至 stdout/stderr，重点关注 acme_* 事件、Redis 错误与区域重建日志。
• OpenResty 访问日志——写入 /data/access-logs/access.log，由 logrotate 容器轮转；确保保留策略符合隐私法规。
• OpenResty 错误日志——默认位于 /usr/local/openresty/nginx/logs/error.log，用于监控 Redis 连接、后端失败、SSL 错误。
• Celery 日志——cirrus-worker 与 cirrus-beat 容器输出至 stdout；生产环境应接入日志聚合（ELK、Loki）。

告警建议

信号	告警条件	应对措施
缓存命中率下降	突降至阈值以下（如 低于 40%）	检查源站可用性与缓存规则。
源站错误	nginx_upstream_errors_total 激增	排查源站健康与网络延迟。
ACME 失败	acme_fail 日志或 cdn:acme:{domain} 状态为 failed	检查 DNS 对齐与 acme-dns 可达性。
节点下线	健康检查报告 down	诊断节点，必要时通过 /api/v1/nodes 禁用或删除。
Prometheus 抓取失败	节点缺失指标	确认 OpenResty 健康端点可达。

备份与恢复

• Redis 持久化——AOF（--appendonly yes）保障数据持久。应实现备份（RDB 快照、托管服务备份）并定期演练恢复。
• 证书——证书存于 Redis，备份时自动涵盖；需规划安全存储与轮换。
• DNS 区域状态——可从 Redis 重建，无须额外备份，只要 Redis 完好。
• 配置——基础设施即代码（Ansible、Dockerfile）应纳入版本控制，并记录手工变更。

故障排查手册

• 域名返回 404——检查 cdn:dom:{domain} 是否存在；查看 OpenResty 日志是否出现 router: no conf for host。若配置存在，确认 origins 列表非空。
• TLS 握手失败——确认 cdn:cert:{domain} 包含有效 PEM；查看 ssl_loader 日志是否报 parse/set 错误。
• ACME 签发卡住——检查 cdn:acme:lock:{domain} 与 cdn:acme:task:{domain} 是否超时；必要时清理并重试；核对 _acme-challenge CNAME。
• DNS 缺少节点——确认 cdn:node:{id} 的 active 为 "1"，并查看健康检查日志。
• 指标缺失——验证 NGX_METRICS_ALLOW 包含 Prometheus 来源；确认 9145 端口可达；检查 OpenResty 错误日志是否存在 Lua 异常。

测试策略

• tests/ 下自动化测试覆盖 API 行为、ACME 流程与 DNS 健康场景。重大发布前运行 just fresh-test，确保在干净环境验证。
• 集成测试依赖完整 Docker 栈（just up + pytest），覆盖 acme-dns 与 OpenResty 交互。

完善的可观测性与运维实践使 Cirrus CDN 保持韧性。第 11 章以附录收尾，提供速查信息。