集群配置

在部署 VAULT 之前，你需要在 配置清单 中定义固定名称的 vault 分组。VAULT 没有 profile 一类的模式参数，集群模式完全由 vault 分组的成员数推导：

• 单节点：没有高可用，适用于开发、测试、演示与沙箱
• 三节点：可以容忍一个成员故障，配合 L2 VIP 提供高可用入口，适用于生产环境
• 两节点：可以运行，但没有容错能力，按单节点对待

VAULT 使用 OpenBao 内置的 Raft 存储，同一时刻只有一个 active 成员处理写请求，其余成员为 standby，会把收到的请求转发给 active 成员。

单节点

单节点 VAULT 只需要一行配置：

vault: { hosts: { 10.10.10.10: { vault_seq: 1 } }, vars: { vault_cluster: vault } }

除了 IP 地址外，唯一必要的参数是 vault_seq，它决定实例名 vault-<seq>，也决定由哪个成员负责集群的首次初始化（vault_seq 最小的成员）。

单节点模式下 VAULT 通常与 INFRA、ETCD、PGSQL 部署在同一台机器上，做不到“密钥与数据分离”：拿到这台机器的磁盘，就同时拿到了加密数据与解开它的密钥。它适合开发与演示，不应作为生产环境透明加密的密钥来源。

三节点

三节点 VAULT 可以容忍一个成员故障。生产环境建议在 vault 分组上启用 NODE 模块的 L2 VIP，这样服务入口本身也具备高可用：

vault:
  hosts:
    10.10.10.11: { vault_seq: 1 }   # vault_seq 是必选的身份参数，实例名为 vault-1
    10.10.10.12: { vault_seq: 2 }   # 实例号为非负整数，在组内唯一
    10.10.10.13: { vault_seq: 3 }   # 实例号应当终生不变，seq 最小的成员负责首次初始化
  vars:
    vault_cluster: vault            # 集群名，用作监控标签与实例名前缀
    node_cluster: vault             # 成员使用相同的节点集群名，以生成一致的 VRRP 认证
    vip_enabled: true               # 在 vault 节点集群上启用 L2 VIP
    vip_vrid: 129                   # VRRP 路由器 ID，1-254，在同一 L2 网络内必须唯一
    vip_address: 10.10.10.8         # VIP 地址，vault.pigsty 应当解析到这里

all:
  vars:
    node_etc_hosts: [ '10.10.10.8 vault.pigsty' ]   # 所有节点通过 VIP 访问 vault

部署后的拓扑如下：

                  vault.pigsty -> 10.10.10.8 (VIP, node_etc_hosts)
                                   |
        +--------------------------+--------------------------+
        |    keepalived VIP + haproxy :8200 (check /v1/sys/health == 200)
   vault-1 10.10.10.11      vault-2 10.10.10.12      vault-3 10.10.10.13
   openbao :8200/:8201      openbao :8200/:8201      openbao :8200/:8201
        +------------- Raft（仲裁数 2，容忍 1 个成员故障）--------------+

当 vip_enabled 为 true 且成员数大于 1 时，vault.yml 会在每个成员上生成 HAProxy 服务配置 /etc/haproxy/conf.d/vault.cfg：

• 绑定 <VIP>:8200，以 TCP 模式工作，TLS 透传，证书校验仍由客户端与 OpenBao 完成
• 使用 GET /v1/sys/health 做健康检查：active 返回 200，standby 返回 429，被封印返回 503，未初始化返回 501；只有返回 200 的成员会接收流量
• 健康检查本身也走 HTTPS，并使用 /etc/pki/ca.crt 校验成员证书

启用 VIP 后，成员的服务端证书 SAN 中也会包含 VIP 地址。成员的 node_cluster 应当保持一致，否则 NODE 会为它们推导出不同的 VRRP 认证信息，导致 VIP 无法正常漂移。

两节点

两节点 Raft 集群的仲裁数是 2，容忍故障数是 0：任何一个成员故障都会导致整个集群不可用，可用性甚至比单节点更低。

VAULT 不会拒绝部署两节点集群，但会在执行剧本时打印警告。请将它视为扩缩容过程中的临时状态，而不是长期拓扑。

Raft 支持更多成员，但 VAULT 的设计目标与验收范围是 1 个或 3 个成员。

服务域名

所有客户端都应通过 vault_domain（默认为 vault.pigsty）访问 VAULT，完整地址为：

https://vault.pigsty:8200

使用域名而不是 IP 地址的原因是：pg_tde 等消费者会把 KMS 地址持久化到自己的元数据中。只要客户端使用域名，从单节点迁移到三节点、或者更换 VIP 时，只需修改 /etc/hosts，而不必逐个修改消费者的配置。

域名解析通过 NODE 模块的 node_etc_hosts 参数写入每个节点的 /etc/hosts，不依赖 INFRA 节点上的 DNS 服务。这样即使 INFRA 节点不可用，数据库在启动时依然能够找到 KMS。

./node.yml -t node_hosts           # 修改 node_etc_hosts 后，刷新所有节点的 /etc/hosts

服务端证书由 Pigsty CA 签发，每个 Pigsty 纳管节点上都有 CA 证书 /etc/pki/ca.crt，客户端使用它校验 VAULT 的身份即可。

部署位置

在生产环境中，建议把 VAULT 部署在独立的节点上，或者与 ETCD、INFRA 等管控组件共置，不要与使用其密钥的 PostgreSQL 或 Silo 数据节点共置。 透明加密的价值在于密钥与数据分离：数据盘、数据库备份与对象存储泄露时，攻击者无法从同一个地方拿到密钥。

VAULT 自身的资源需求很低，对磁盘的主要要求是低延迟：Raft 日志的每次提交都需要落盘。

密钥材料

VAULT 的全部信任根都保存在管理节点的 files/pki/vault/ 目录中，与 Pigsty CA 放在一起（files/pki/ 默认被 Git 忽略）：

由于每个成员上都有一份 unseal.key 的副本，Pigsty 在分发前会比对校验和：如果某个成员上已有的密钥与管理节点上的不一致，剧本会立即中止，避免用错误的密钥封装数据。

文件系统布局

VAULT 模块在成员节点上创建以下目录和文件：

此外，INFRA 节点上的 /infra/targets/vault/<vault-seq>.yml 是该成员的监控抓取目标。