第三方集成接口

本章节梳理 Cirrus CDN 在“对外可编程”和“可观测/可治理”层面的集成面：涵盖 API 生态、日志与事件采集、以及与 BI/监控平台的对接方式与最佳实践。

1. API 生态（API‑first）

接口风格：RESTful JSON，版本前缀 /api/v1/*；完整端点与模型见《API 参考》。
OpenAPI：运行后可访问交互式文档（Swagger UI）与 OpenAPI 规范，可用于生成多语言 SDK。
鉴权与令牌：
- Cookie 会话（面向浏览器 Dashboard）。
- Bearer Token（机器对机器）：支持 Master Token 与“服务令牌”两级。建议：在自动化/CI 中使用“服务令牌”，并按项目/环境分发、定期轮换。
幂等与重试：
- 读取类 GET 天然幂等。
- 覆盖更新类 PUT 视为幂等（相同载荷多次提交等价）。
- 任务触发类接口（如证书签发）返回 202，客户端应轮询查询状态或通过日志/监控获知结果。
速率限制与退避：建议客户端对 429/5xx 采用指数退避重试策略；避免热循环触发 ACME 或大规模 PURGE。
最小权限：Master Token 仅用于令牌管理；其他调用应使用“服务令牌”。严禁将 Master Token 下发到边缘或客户端。
审计与可追溯：建议在调用侧记录请求 ID、调用人/令牌 ID 与关键变更对象，便于与后续日志、告警关联。

快速落地：结合《API 参考》中的示例命令，先以 Master Token 建立“服务令牌”，随后将服务令牌注入 CI/自动化系统，即可完成与域名 CRUD、缓存刷新、证书生命周期等的编排集成。

Cirrus 组件默认向标准输出（stdout/stderr）输出结构化日志，推荐将容器日志统一汇聚到日志平台（Loki/ELK/Datadog 等）。

OpenResty 访问/错误日志：
- 已集成 Prometheus 日志指标采集与关键请求阶段计数/直方图。
- 推荐使用 Loki Docker Logging Driver 将容器日志直接推送到 Loki（见仓库内 Loki 集成指南）。
- 字段建议：时间戳、域名/主机、请求路径、状态码、上游耗时、缓存命中状态等，便于下游检索与 SLO 看板构建。
后台任务与 ACME/DNS 流程：
- Celery 对 ACME 签发、续期、节点健康检查等输出结构化日志（包含任务 ID/域名等上下文）。
- 失败/跳过/并发锁等分支会明确标记，便于检索与重试策略编排。
事件总线与内部频道（高级）：
- 系统内部使用 Redis Pub/Sub（如 cdn:purge、cdn:cname:dirty）。如需与外部事件平台打通，可在私有环境内增加桥接进程，安全地将必要事件转发到 Kafka/Pulsar 等。

实践建议：

指标（Metrics）：
- OpenResty 暴露 Prometheus 指标（默认端口 9145，见《运维与监控》）。
- 后端对 ACME/DNS/健康检查亦有计数与日志。部署时请将 prometheus/ 抓取配置与 grafana/ 看板模板一并导入。
Grafana 看板：
- 仓库自带 grafana/ 预制看板（包括 OpenResty 请求/缓存命中、证书健康、节点状态等），可直接绑定 Loki + Prometheus 数据源。
- 建议按环境与租户维度做变量筛选，形成运营/研发/值班三类视图。
告警（Alerting）：
- 在 Prometheus 侧以“错误率、P95/P99 延迟、缓存命中率、证书到期窗口、健康检查失败连击”等规则作为基础告警。
- 结合 Loki 做“错误日志骤增/特定异常模式”类告警，作为指标告警的补充。
BI 数据消费：
- 运营指标可通过 Prometheus 导出或日志平台定期 ETL 至数据仓库，构建域名级 UV/PV、回源率、带宽成本等模型。
- 对接方式：指标导流（Prom → DWH）、日志查询导出（Loki/ELK → 表格/对象存储），或通过 /api/v1 定期抽取域名与配置快照。

API 编排：
- 参考《API 参考》完成域名 CRUD、缓存刷新、证书签发/续期编排。
- 建立服务令牌并在 CI/自动化中使用；对 429/5xx 采用退避重试。
日志汇聚：
- 采用容器日志直推方案（推荐：Loki Driver）。
- 定义索引字段（域名、环境、业务线、节点），与告警联动。
指标与看板：
- Prometheus 抓取 OpenResty 9145 指标；导入 grafana/ 看板模板；对接告警渠道。
合规与安全：
- 令牌最小权限与轮换；Redis 访问控制；日志去标识化。