1. 架构概述

  • 架构模式: 3 节点高可用,使用 Vault 自带的 Integrated Storage (Raft) 协议。
    使用 Vault 官方推荐的 HA 模式:
  Client / LB
      |
      | 8200 HTTPS
      v
  vault-01 / vault-02 / vault-03
      |
      | 8201 Raft cluster
      v
  Integrated Storage / Raft
  • 环境: Ubuntu 22.04, Docker
  • 网络: Docker host 模式,直接绑定主机网卡,提升网络性能,避免 NAT 层问题。
  • 存储路径: /data/vault/(独立挂载数据盘,建议做好 LVM 或磁盘快照)。
  • Vault 版本: hashicorp/vault:1.17.6
  • 安全:
    • 全链路 TLS(API 8200 + Cluster 8201)
    • 私有自建 CA 签发各节点证书
    • 关闭 Docker 0.0.0.0 默认暴露,明确绑定内网 IP。
    • 8201 只允许 3 台 Vault 节点互通。
    • 8200 只暴露给负载均衡器、运维网段或业务网段。

节点信息

主机名内网 IP角色
vault-0110.0.5.57Leader / Follower
vault-0210.0.5.58Follower
vault-0310.0.5.59Follower

2. 基础环境准备 (三台节点均执行)

创建需要的目录并配置目录权限:

mkdir -p /data/vault/{config,data,logs,tls}

# Vault 容器内以 vault(100) 用户运行,配置相应的挂载点权限
chown -R 100:1000 /data/vault/data /data/vault/logs
chmod 750 /data/vault
chmod 750 /data/vault/data /data/vault/logs
chmod 750 /data/vault/config /data/vault/tls

(可选) 配置 hosts 文件,确保相互可通过主机名解析:

cat >> /etc/hosts <<'EOF'
10.0.5.57 vault-01
10.0.5.58 vault-02
10.0.5.59 vault-03
EOF

防火墙最少放行:

# 节点之间
ufw allow from 10.0.5.57 to any port 8200 proto tcp
ufw allow from 10.0.5.57 to any port 8201 proto tcp
ufw allow from 10.0.5.58 to any port 8200 proto tcp
ufw allow from 10.0.5.58 to any port 8201 proto tcp
ufw allow from 10.0.5.59 to any port 8200 proto tcp
ufw allow from 10.0.5.59 to any port 8201 proto tcp

# 客户端或负载均衡器访问 8200,按你的实际网段改
ufw allow from <LB或业务网段> to any port 8200 proto tcp

3. 生成并分发 TLS 证书 (在 vault-01 上执行)

生产环境强烈建议开启 TLS,不建议裸奔 8200 API 和 8201 集群通信端口。

3.1 创建私有 CA

mkdir -p /data/vault/pki
cd /data/vault/pki

# 生成 CA 密钥
openssl genrsa -out vault-ca.key 4096
# 生成 CA 证书
openssl req -x509 -new -nodes \
  -key vault-ca.key \
  -sha256 \
  -days 3650 \
  -out vault-ca.crt \
  -subj "/CN=vault-internal-ca"

3.2 生成节点证书 (以 vault-01 为例)

cat > vault-01.cnf <<'EOF'
[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
req_extensions = req_ext

[dn]
CN = vault-01

[req_ext]
subjectAltName = @alt_names

[alt_names]
DNS.1 = vault-01
IP.1 = 10.0.5.57
IP.2 = 127.0.0.1
EOF

openssl genrsa -out vault-01.key 2048
openssl req -new -key vault-01.key -out vault-01.csr -config vault-01.cnf
openssl x509 -req -in vault-01.csr -CA vault-ca.crt -CAkey vault-ca.key \
  -CAcreateserial -out vault-01.crt -days 825 -sha256 \
  -extensions req_ext -extfile vault-01.cnf

注意: vault-02 和 vault-03 的证书用同样的方法生成,只需替换上面的 CN、DNS.1、IP.1 以及文件名。

3.3 分发证书

将生成的证书放至对应的 /data/vault/tls/ 目录下,并确保文件名为 ca.crt、vault.crt 和 vault.key。

# vault-01 节点:
cp vault-ca.crt /data/vault/tls/ca.crt
cp vault-01.crt /data/vault/tls/vault.crt
cp vault-01.key /data/vault/tls/vault.key

# 分发并重命名到 vault-02:
scp vault-ca.crt vault-02.crt vault-02.key root@10.0.5.58:/data/vault/tls/
# 到 vault-02 上改名:
cd /data/vault/tls
mv vault-ca.crt ca.crt
mv vault-02.crt vault.crt
mv vault-02.key vault.key

# vault-03 同理...

# 三台节点调整权限:
chown -R 100:1000 /data/vault/tls
chmod 644 /data/vault/tls/ca.crt /data/vault/tls/vault.crt
chmod 640 /data/vault/tls/vault.key

4. 编写配置文件

4.1 Vault 配置文件 (/data/vault/config/vault.hcl)

以 vault-01 为例,三台节点只需要修改 api_addr、cluster_addr、node_id 和 listener 中的 address / cluster_address。

ui = true
disable_mlock = false

# 当前节点的实际内网 IP
api_addr     = "https://10.0.5.57:8200"
cluster_addr = "https://10.0.5.57:8201"

listener "tcp" {
  # 指定绑定的内网 IP
  address         = "10.0.5.57:8200"
  cluster_address = "10.0.5.57:8201"

  tls_cert_file   = "/vault/tls/vault.crt"
  tls_key_file    = "/vault/tls/vault.key"
  tls_min_version = "tls12"
}

storage "raft" {
  path    = "/vault/data"
  node_id = "vault-01"  # 其它节点分别为 vault-02, vault-03

  retry_join {
    leader_api_addr     = "https://10.0.5.57:8200"
    leader_ca_cert_file = "/vault/tls/ca.crt"
  }
  retry_join {
    leader_api_addr     = "https://10.0.5.58:8200"
    leader_ca_cert_file = "/vault/tls/ca.crt"
  }
  retry_join {
    leader_api_addr     = "https://10.0.5.59:8200"
    leader_ca_cert_file = "/vault/tls/ca.crt"
  }
}

4.2 Docker Compose 配置 (/data/vault/docker-compose.yml)

采用 host 网络模式,避免 command 冲突和端口占用,三台主机配置一致:

services:
  vault:
    image: hashicorp/vault:1.17.6
    container_name: vault
    restart: unless-stopped
    network_mode: host

    # 关键:避免镜像 entrypoint 引起配置重复加载
    command: server

    cap_add:
      - IPC_LOCK

    security_opt:
      - no-new-privileges:true

    ulimits:
      memlock:
        soft: -1
        hard: -1

    volumes:
      - /data/vault/config:/vault/config:ro
      - /data/vault/data:/vault/data
      - /data/vault/logs:/vault/logs
      - /data/vault/tls:/vault/tls:ro

    environment:
      # 在容器内用于自引用的变量
      VAULT_ADDR: "https://127.0.0.1:8200"
      VAULT_CACERT: "/vault/tls/ca.crt"

5. 宿主机安装对应版本的 Vault CLI

为了方便在宿主机执行命令,安装与 Docker 镜像版本一致的 Vault CLI。

# 下载指定版本的 Vault CLI (保持与 docker 镜像 1.17.6 一致)
cd /tmp
wget https://releases.hashicorp.com/vault/1.17.6/vault_1.17.6_linux_amd64.zip
unzip vault_1.17.6_linux_amd64.zip
sudo install -m 0755 vault /usr/local/bin/vault

# 配置宿主机环境变量信任私有 CA
cat >> ~/.bashrc <<'EOF'
export VAULT_ADDR=https://127.0.0.1:8200
export VAULT_CACERT=/data/vault/tls/ca.crt
EOF
source ~/.bashrc

# 确保宿主机没有后台运行 vault 服务,避免端口冲突
systemctl stop vault || true
systemctl disable vault || true

6. 启动与初始化集群

6.1 启动所有容器

三台节点分别执行:

cd /data/vault
docker compose up -d

6.2 在 vault-01 上初始化集群

仅在 vault-01 上执行一次初始化。设置将密钥分成 5 份,需要 3 份解封。

vault operator init -key-shares=5 -key-threshold=3 -format=json > /root/vault-init.json
chmod 600 /root/vault-init.json

警告: /root/vault-init.json 包含 unseal_keys_b64 及超级管理员 root_token,请离线安全保存。

注意:vault-02、vault-03 不要再执行 vault operator init。只需要启动、自动 join、再 unseal。

6.3 依次解封各节点

查看 /root/vault-init.json 获取解封 key。
分别在 vault-01、vault-02、vault-03 执行解封:

# 每次执行输入一个不同的 unseal_key,执行 3 次
vault operator unseal
vault operator unseal
vault operator unseal

6.4 验证集群状态

在任意节点,使用 root_token 登录验证集群状况:

vault login <your-root-token>
vault operator raft list-peers

期望看到:

Node        Address           State       Voter
----        -------           -----       -----
vault-01    10.0.5.57:8201    leader      true
vault-02    10.0.5.58:8201    follower    true
vault-03    10.0.5.59:8201    follower    true

7. 审计日志与轮转

7.1 开启审计日志 (集群级别)

在任意一台 active 节点执行一次:

vault audit enable file file_path=/vault/logs/audit.log

注意: 配置为集群级生效,但日志会落盘到每个节点各自的 /data/vault/logs/audit.log(只在当时担任 leader 或处理请求的节点实际写入)。

7.2 配置 Logrotate (每台节点均配置)

为了防止日志打满磁盘,配置 Linux 自带的 logrotate:

cat > /etc/logrotate.d/vault-audit <<'EOF'
/data/vault/logs/audit.log {
    daily
    rotate 180
    compress
    missingok
    notifempty
    copytruncate
    create 0640 root root
}
EOF

8. 日常运维建议

8.1 不要长期使用 root token

创建业务与管理员对应的 Role / Policy 后,废弃或封存 Root Token。

创建日常 admin policy 和 token:

vault policy write admin - <<'EOF'
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

vault token create -policy=admin -display-name=admin

8.2 集群重启需要重新解封

目前是 Shamir 手动解封,如果容器或宿主机重启,Vault 会进入 Sealed true 状态,必须重新执行 3 次 vault operator unseal。

后续如果有条件,建议接入:

  • 云 KMS
  • HSM
  • 另一个独立 Vault 的 Transit Seal

8.3 防火墙配置 (UFW/IPTables)

  • 放行 8201 仅允许三台 Vault 节点之间互通。
  • 放行 8200 允许业务或 LB 访问。

8.4 自动快照

可以利用宿主机的 Cron 定期执行以下命令来备份 Raft 数据:

vault operator raft snapshot save /data/vault/backup/raft-snapshot-$(date +%F).snap

8.5 内网负载均衡

如果前面架设 LB (HAProxy/Nginx/F5),建议仅转发 8200,配置健康检查探测 GET /v1/sys/health(支持处理 200 和 429 状态码)。

常见状态码:

200 active
429 standby
472 disaster recovery secondary
473 performance standby
501 not initialized
503 sealed

8.6 做故障切换演练

至少测一次:

# 在 vault-01
docker compose stop vault

8.7 补监控

至少监控这些:

  • 容器是否运行
  • vault status 是否 Sealed false
  • Raft leader 是否存在
  • raft list-peers 是否 3 个 voter
  • /data 磁盘使用率
  • 审计日志是否持续写入
  • 快照任务是否成功
  • 证书过期时间

8.8 启用业务前的最小配置

根据准备用 Vault 存什么,再启用对应 secrets engine,例如 KV v2:

vault secrets enable -path=secret kv-v2

然后创建业务 policy,不要让业务用 admin/root token。业务 token 或 AppRole 只授予必要路径权限。