# 集群控制（L2 辅助主控 + XCC CDN）

> 文档更新：2026-09-27 ｜ 适用版本：v3 ｜ 功能位置：「集群控制」菜单：辅助主控（/cluster/l2）、下发凭证、云端证书、DNS调度、XCC站点

## 这组功能是干什么的

搭建多节点 CDN 集群：由一台「辅助主控（L2）」统一管理所有边缘节点（xcc套件节点），负责汇聚数据、分发站点配置、管理云端证书，并提供自动容灾调度。**集群的全部功能都依赖 L2 已配置且在线**——L2 不在线，本模块各页面均不可用。

角色关系：主控（你的面板）→ L2 辅助主控（集群大脑，装在某台服务器上）→ 多台 xcc套件节点（实际对外的边缘服务器）。

## 辅助主控（L2）

集群管控核心，页面上完成 L2 的全生命周期管理：

- **配置**：L2 服务地址、主控端口、上报端口；
- **安装 / 更新 / 卸载**：生成证书后提供安装命令（复制后到目标服务器执行，或直接在面板里 SSH 执行）；
- **告警**：配置 SMTP 发件邮箱 + 告警策略（启用开关、收件邮箱、冷却时间、每日上限）。告警规则每条独立开关：节点离线（超 3 分钟未上报）、探测连续失败（默认 3 次）、资源过载（CPU/内存/磁盘超阈值，默认 90%）、配置同步超时（超 5 分钟）、证书申请/续期失败；
- **Agent 密钥**：允许接入的节点授权列表，绑定 IP；
- **L2 凭证**：查看已推送到 L2 的 DNS API 凭证（云端证书、DNS 调度使用）。注意：主控侧删除凭证不会自动删除 L2 侧的，需在此手动清理。

## 下发凭证

批量为节点重新生成并下发 L2 凭证：节点表格多选（支持按类型快选），二次确认后批量下发。用于节点凭证过期、更换或信任关系重建的场景。

## 云端证书

L2 级别的 SSL 证书管理（区别于「网站管理 → 证书中心」的本地证书）：

- **ACME 申请**：通过 Let's Encrypt 的 DNS-01 方式，由 L2 自动完成（选 DNS 服务商与凭证，凭证自动同步到 L2）；
- **上传证书**：手动粘贴 PEM/KEY，或从主控证书中心导入；
- **自动续期**：ACME 证书可开启（L2 定时任务执行）；手动上传的证书不支持自动续期；
- **与站点联动**：XCC 站点绑定 L2 证书后，证书续期会自动同步到站点，无需手动换证书。

## DNS 调度（自动容灾）

XCC 边缘集群的自动故障切换：L2 每 2 分钟探测各边缘节点 IP（端口连通性），健康节点自动进入「调度域名」解析、故障节点自动摘除。业务域名只需 CNAME 到调度域名，边缘节点的 IP 与上下线对业务方完全透明。

使用限制（重要）：

- 仅支持**雨云 DNS**（凭证与域名需托管在雨云）；
- **调度域名一经启用不应变更**——变更会断掉业务方已有的 CNAME；
- 故障切换生效时间 ≈ 探测周期 2 分钟 + 解析 TTL 5 分钟，最长约 7 分钟；
- 仅探测端口连通（TCP），无法发现"端口通但应用报错"的故障；
- 调度域名下的 A/AAAA 记录由本功能独占管理，手动添加的会被自动移除。

配置入口在 DNS调度页的「调度配置」抽屉：功能开关 + 雨云凭证 + 域名与主机记录，保存启用后立即触发一轮探测调和。探测记录最多 20 条、IP 全局唯一；「调度事件」卡片展示解析变更事件流。

## XCC 站点（集群 CDN）

XCC（XMP Cloud CDN）的站点管理，与网站管理版操作相似（创建/删除、站点设置、让配置生效机制），但架构不同：

| 维度 | 网站版 | XCC |
|---|---|---|
| 配置分发 | 只作用于选定的单个节点 | 经 L2 自动同步到**所有** xcc套件边缘节点 |
| 节点选择 | 需要选目标节点 | 不需要，L2 统一管理 |
| 静态内容 | 无 | 可上传 ZIP（经 L2 分发到各边缘节点）或填外部 URL |
| SSL 证书 | 自动 Let's Encrypt / 主控证书 / 上传 / L2 | **仅 L2 云端证书** |

- **同步状态抽屉**：查看各边缘节点的配置同步版本与状态（正常 / 同步中 / 超时 / 失败）；
- 配置变更后同样需要手动点「让配置生效」，配置经 L2 推送到全部边缘节点。

## 常见疑问

**问：L2 和主控是什么关系？都要装吗？**
主控是你日常操作的面板；L2 是装在另一台服务器上的"集群大脑"，替主控管理边缘节点。不搭 CDN 集群就完全不用管 L2；要搭，先装 L2，再把节点以 xcc套件类型接入。

**问：XCC 站点的 HTTPS 证书从哪来？**
只用 L2 云端证书：在「云端证书」页申请（可自动续期）或上传，然后绑定到 XCC 站点。续期后自动同步到站点和所有边缘节点。

**问：为什么 DNS 调度只能用雨云？**
当前版本仅对接了雨云 DNS 的 API 实现自动增删解析记录。域名需托管在雨云并配置雨云凭证。

**问：某个边缘节点挂了，用户访问会中断吗？**
已启用 DNS 调度时：故障节点被摘除，访问自动切到健康节点，最长约 7 分钟收敛；未启用调度时没有自动切换。但注意调度只保证"端口连通"，应用层故障（端口通但页面报错）不会被自动发现。

**问：边缘节点的配置怎么更新？**
在 XCC 站点修改配置 → 点「让配置生效」→ L2 自动推送到所有 xcc套件节点，可在同步状态抽屉里逐节点确认结果。

## 指导用户时的注意点

- 集群问题排查的第一步永远是：L2 是否在线（辅助主控页状态）。
- 用户问"证书怎么配"时先分清对象：网站版站点走证书中心/自动维护，XCC 站点只走云端证书——两者不通用。
- 涉及 DNS 调度的操作前，提醒用户调度域名不可变更的限制和约 7 分钟的收敛时间，避免误判"没生效"。
- 「下发凭证」影响所有选中节点的信任关系，执行前让用户确认节点选择范围。