集群高可用与节点协同

在大规模多节点部署场景下，CheeseWAF 提供用于节点 mTLS 身份认证、健康/心跳上报、拓扑状态与编排钩子的集群互联。该互联不是站点策略复制通道。当前可运行路径是单节点 builtin 协调器；选择 etcd 只能记录共享集群要求，当前二进制没有 etcd 后端协调器，因此会 fail-closed，不会从共享部署静默回退到心跳选主。商业化目标是由 native-raft 负责期望状态顺序、epoch fencing 与回滚引用，由 PostgreSQL 保存持久管理真相。在迁移完成前，本页的 etcd 命令只描述 contract，不能据此宣称 native-raft 已交付。

在 Web 管理控制台中可进入 集群管理 模块，或通过命令行 cheesewaf cluster 与 REST API /api/cluster/* 进行管理。

1. 基础配置与模式定义

单机默认配置如下：

deployment:
  mode: "standalone"
cluster:
  enabled: false
  ha_mode: "single-node"
  interconnect:
    listen: "127.0.0.1:9444"
    mtls_required: true

下面的配置描述当前节点互联和准入 contract；它不会让当前二进制直接变成可用于生产的多节点 HA：

1. 将 deployment.mode 设置为 cluster、cluster.enabled 设置为 true，并指定全局统一的 cluster_id。
2. 为每个物理机/虚拟机节点分配唯一的 node_id。
3. 配置 interconnect.advertise_addr 为该节点可被集群内其他节点访问的通信地址。
4. 保持 mtls_required: true，并在各节点配置受信的 ca_file、cert_file 与 key_file 证书文件。

内置共识提供方只支持单节点，并且只保留内存中的配置版本日志。设置 cluster.consensus.provider: etcd 并填写 etcd_endpoints 只能记录共享集群所需的 contract；当前二进制没有 etcd 后端协调器，因此会保持写保护/保护模式，不会把心跳状态冒充为共识。native-raft contract 见商业化架构基线，独立命令的当前启动和 join 限制见独立控制面运行时。这两份文档都不会通过当前配置键启用 native-raft。

脑裂与写保护机制

• cluster.protection.freeze_writes_without_majority：当发生网络分区导致无法形成多数派仲裁时，系统将自动冻结配置写操作，防止数据冲突与脑裂。
• allow_traffic_in_protection_mode：在写保护模式下，数据平面继续为现有业务提供反向代理与安全检测服务。

2. 集群 CLI 命令行运维工具链

CheeseWAF 提供用于集群初始化、令牌/证书操作和心跳检查的 CLI 入口：

1. 主控节点初始化与令牌签发

# 初始化本地单节点集群（互联地址默认只绑定回环）
cheesewaf cluster init

# 签发新的工作节点临时加入令牌（有效期由 --ttl 控制，默认 15m）
cheesewaf cluster token create --ttl 15m

# 查看或吊销现有的加入令牌
cheesewaf cluster token list
export CHEESEWAF_TOKEN_ID='token-id-to-revoke'
cheesewaf cluster token revoke "$CHEESEWAF_TOKEN_ID"

cluster init 初始化节点集群身份与通信配置。接入远程节点前，应将两个地址都改成可路由值（例如使用 --force --advertise-addr 10.0.0.1:9444 --listen 0.0.0.0:9444 重新执行），并配置统一的集群发现与协调后端。

2. 工作节点加入与证书轮换

export CHEESEWAF_CONTROLLER='https://10.0.0.1:9443'
export CHEESEWAF_JOIN_TOKEN='one-time-join-token'
export CHEESEWAF_NODE_ID='node-worker-02'
export CHEESEWAF_ADVERTISE_ADDR='10.0.0.2:9444'
export CHEESEWAF_CONTROLLER_CA='/var/lib/cheesewaf/certs/admin-ca.crt'

# 在工作节点使用一次性令牌与本地 CSR 执行加入
cheesewaf cluster join \
  --controller "$CHEESEWAF_CONTROLLER" \
  --token "$CHEESEWAF_JOIN_TOKEN" \
  --node-id "$CHEESEWAF_NODE_ID" \
  --advertise-addr "$CHEESEWAF_ADVERTISE_ADDR" \
  --ca-file "$CHEESEWAF_CONTROLLER_CA"

export CHEESEWAF_API_TOKEN='management-token-with-write-cluster'

# 请求签发新的节点证书（需已有证书路径；写入后按服务语义 reload/restart）
cheesewaf cluster cert rotate \
  --controller "$CHEESEWAF_CONTROLLER" \
  --ca-file "$CHEESEWAF_CONTROLLER_CA" \
  --api-token-env CHEESEWAF_API_TOKEN
# 检查当前节点的集群健康状态与多数派仲裁
cheesewaf cluster status

--ca-file 用于校验控制器 HTTPS 管理端证书，并不是加入响应返回的集群 CA。若控制器证书链已受系统信任可省略；使用私有 CA 时，应预先准备控制器 CA（例如 admin-ca.crt）。加入命令会在本地生成节点密钥与 CSR，接收集群 CA 和签发证书，并写入配置的数据目录；私钥不会发送给控制器。

证书轮换同样要求节点已有配置的身份/证书路径，并且 API 令牌来源必须三选一（--api-token、--api-token-file 或 --api-token-env）。命令只负责写入替换文件，需按服务的 reload/restart 流程后新证书才会生效。

3. Ansible 批量自动化部署

当前 POST /api/cluster/deploy/ansible 导出器只生成 CheeseWAF 主服务引导包（inventory、变量、playbook、role、配置模板和 README）。它不包含 CWEDP 代理，也不是拿来就能执行的生产包：运行前必须补充经过校验的二进制 URL 和 SHA-256、服务路径；多节点场景还必须填写生成 role 所需的外部 etcd 地址。可选的 deploy/ansible/full.yml 只有在明确设置 provision_only=true、补齐外部控制面预检参数以及 CWEDP 代理 URL 和 SHA-256 时，才能执行只拉取代理的主机交接；这仍不会让 CheeseWAF 的 production 存储变为可运行。插件 CRP 的安装、升级、回滚、签名、晋级及认证分发都不会由 Ansible 执行，这些生命周期操作属于 CWEDP：

• Playbook 导出接口：调用 POST /api/cluster/deploy/ansible，传入目标节点的主机清单、角色（waf / monitor）、SSH 端口与地域标签。响应为 JSON，files 对象将相对文件名（如 inventory.ini、playbook.yml 及角色文件）映射到文本内容；保存后先填写经过校验的二进制变量和 etcd 设置，人工复核命令，再执行 playbook。
• Web 控制台导出：在 Web 管理控制台的 集群管理 模块中，可录入节点拓扑并点击「导出 Ansible 部署包」；下载内容仍需人工补全和复核，不是拿来就能执行的生产包。

4. 集群核心 REST API 参考

单节点部署默认采用 builtin 模式并将状态保存在本地；多节点高可用集群必须配置外部 etcd 端点（etcd_endpoints）以协调分布式状态与选主。