feat: 更新OCI Provider版本至7.20并集成Vault配置

refactor: 重构Terraform配置以使用Consul和Vault存储敏感信息 docs: 添加Vault实施文档和配置指南 chore: 清理不再使用的配置文件和脚本 feat: 添加Nomad集群领导者发现脚本和文档 feat: 实现MCP配置共享方案和同步脚本 style: 更新README中的网络访问注意事项 test: 添加Consul Provider集成测试脚本
2025-09-29 01:42:57 +00:00
parent ad531936dd
commit f72b17a34f
38 changed files with 3741 additions and 888 deletions
--- a/docs/vault/ansible_vault_integration.md
+++ b/docs/vault/ansible_vault_integration.md
@@ -0,0 +1,268 @@
+# Ansible与HashiCorp Vault集成指南
+
+本文档介绍如何将Ansible与HashiCorp Vault集成，以安全地管理和使用敏感信息。
+
+## 1. 安装必要的Python包
+
+首先，需要安装Ansible的Vault集成包：
+
+```bash
+pip install hvac
+```
+
+## 2. 配置Ansible使用Vault
+
+### 2.1 创建Vault连接配置
+
+创建一个Vault连接配置文件 `vault_config.yml`：
+
+```yaml
+vault_addr: http://localhost:8200
+vault_role_id: "your-approle-role-id"
+vault_secret_id: "your-approle-secret-id"
+```
+
+### 2.2 创建Vault查询角色
+
+在Vault中创建一个专用于Ansible的AppRole：
+
+```bash
+# 启用AppRole认证
+vault auth enable approle
+
+# 创建策略
+cat > ansible-policy.hcl <<EOF
+path "kv/data/ansible/*" {
+  capabilities = ["read"]
+}
+EOF
+
+vault policy write ansible ansible-policy.hcl
+
+# 创建AppRole
+vault write auth/approle/role/ansible \
+    token_policies="ansible" \
+    token_ttl=1h \
+    token_max_ttl=4h
+
+# 获取Role ID
+vault read auth/approle/role/ansible/role-id
+
+# 生成Secret ID
+vault write -f auth/approle/role/ansible/secret-id
+```
+
+## 3. 在Ansible中使用Vault
+
+### 3.1 使用lookup插件
+
+在Ansible playbook中使用`hashi_vault`查找插件：
+
+```yaml
+---
+- name: 使用HashiCorp Vault的示例
+  hosts: all
+  vars:
+    vault_addr: "http://localhost:8200"
+    role_id: "{{ lookup('file', '/path/to/role_id') }}"
+    secret_id: "{{ lookup('file', '/path/to/secret_id') }}"
+    
+    # 从Vault获取数据库密码
+    db_password: "{{ lookup('hashi_vault', 'secret=kv/data/ansible/db:password auth_method=approle role_id=' + role_id + ' secret_id=' + secret_id + ' url=' + vault_addr) }}"
+  
+  tasks:
+    - name: 配置数据库连接
+      template:
+        src: db_config.j2
+        dest: /etc/app/db_config.ini
+```
+
+### 3.2 使用环境变量
+
+也可以通过环境变量设置Vault认证信息：
+
+```yaml
+---
+- name: 使用环境变量的Vault示例
+  hosts: all
+  environment:
+    VAULT_ADDR: "http://localhost:8200"
+    VAULT_ROLE_ID: "{{ lookup('file', '/path/to/role_id') }}"
+    VAULT_SECRET_ID: "{{ lookup('file', '/path/to/secret_id') }}"
+  
+  tasks:
+    - name: 从Vault获取密钥
+      set_fact:
+        api_key: "{{ lookup('hashi_vault', 'secret=kv/data/ansible/api:key') }}"
+```
+
+## 4. 创建Vault密钥模块
+
+创建一个自定义的Ansible角色，用于管理Vault中的密钥：
+
+### 4.1 角色结构
+
+```
+roles/
+└── vault_secrets/
+    ├── defaults/
+    │   └── main.yml
+    ├── tasks/
+    │   └── main.yml
+    └── vars/
+        └── main.yml
+```
+
+### 4.2 主任务文件
+
+`roles/vault_secrets/tasks/main.yml`:
+
+```yaml
+---
+- name: 确保Vault令牌有效
+  block:
+    - name: 获取Vault令牌
+      set_fact:
+        vault_token: "{{ lookup('hashi_vault', 'auth_method=approle role_id=' + vault_role_id + ' secret_id=' + vault_secret_id + ' url=' + vault_addr) }}"
+      no_log: true
+  rescue:
+    - name: Vault认证失败
+      fail:
+        msg: "无法从Vault获取有效令牌"
+
+- name: 从Vault读取密钥
+  set_fact:
+    secrets: "{{ lookup('hashi_vault', 'secret=' + vault_path + ' token=' + vault_token + ' url=' + vault_addr) }}"
+  no_log: true
+  
+- name: 设置各个密钥变量
+  set_fact:
+    "{{ item.key }}": "{{ item.value }}"
+  with_dict: "{{ secrets.data.data }}"
+  no_log: true
+```
+
+## 5. 将现有Ansible Vault迁移到HashiCorp Vault
+
+### 5.1 创建迁移脚本
+
+创建一个脚本来自动迁移Ansible Vault内容到HashiCorp Vault：
+
+```bash
+#!/bin/bash
+# migrate_to_hashicorp_vault.sh
+
+# 设置变量
+ANSIBLE_VAULT_FILE=$1
+VAULT_PATH=$2
+VAULT_ADDR=${VAULT_ADDR:-"http://localhost:8200"}
+
+# 检查参数
+if [ -z "$ANSIBLE_VAULT_FILE" ] || [ -z "$VAULT_PATH" ]; then
+  echo "用法: $0 <ansible_vault_file> <vault_path>"
+  echo "示例: $0 group_vars/all/vault.yml kv/ansible/group_vars/all"
+  exit 1
+fi
+
+# 检查Vault登录状态
+if ! vault token lookup >/dev/null 2>&1; then
+  echo "请先登录Vault: vault login <token>"
+  exit 1
+fi
+
+# 解密Ansible Vault文件
+echo "解密Ansible Vault文件..."
+TEMP_FILE=$(mktemp)
+ansible-vault decrypt --output="$TEMP_FILE" "$ANSIBLE_VAULT_FILE"
+
+# 将YAML转换为JSON并存储到HashiCorp Vault
+echo "迁移密钥到HashiCorp Vault..."
+python3 -c "
+import yaml, json, sys, subprocess
+with open('$TEMP_FILE', 'r') as f:
+    data = yaml.safe_load(f)
+for key, value in data.items():
+    cmd = ['vault', 'kv', 'put', '$VAULT_PATH/' + key, 'value=' + json.dumps(value)]
+    subprocess.run(cmd)
+"
+
+# 清理临时文件
+rm "$TEMP_FILE"
+
+echo "迁移完成! 数据已存储在Vault路径: $VAULT_PATH/"
+```
+
+### 5.2 执行迁移
+
+```bash
+# 赋予脚本执行权限
+chmod +x migrate_to_hashicorp_vault.sh
+
+# 执行迁移
+./migrate_to_hashicorp_vault.sh group_vars/all/vault.yml kv/ansible/group_vars/all
+```
+
+## 6. 更新Ansible配置
+
+### 6.1 修改ansible.cfg
+
+更新`ansible.cfg`文件，添加Vault相关配置：
+
+```ini
+[defaults]
+vault_identity_list = dev@~/.ansible/vault_dev.txt, prod@~/.ansible/vault_prod.txt
+
+[hashi_vault_collection]
+url = http://localhost:8200
+auth_method = approle
+role_id = /path/to/role_id
+secret_id = /path/to/secret_id
+```
+
+### 6.2 更新现有Playbook
+
+将现有playbook中的Ansible Vault引用替换为HashiCorp Vault引用：
+
+```yaml
+# 旧方式
+- name: 使用Ansible Vault变量
+  debug:
+    msg: "数据库密码: {{ vault_db_password }}"
+
+# 新方式
+- name: 使用HashiCorp Vault变量
+  debug:
+    msg: "数据库密码: {{ lookup('hashi_vault', 'secret=kv/data/ansible/db:password') }}"
+```
+
+## 7. 最佳实践
+
+1. **避免硬编码认证信息**：使用环境变量或外部文件存储Vault认证信息
+2. **限制令牌权限**：为Ansible创建的Vault令牌仅授予必要的最小权限
+3. **设置合理的TTL**：为Vault令牌设置合理的生命周期，避免长期有效的令牌
+4. **使用no_log**：对包含敏感信息的任务使用`no_log: true`防止日志泄露
+5. **定期轮换认证凭据**：定期轮换AppRole的Secret ID
+6. **使用CI/CD集成**：在CI/CD流程中集成Vault认证，避免手动管理令牌
+
+## 8. 故障排除
+
+### 8.1 常见问题
+
+1. **认证失败**：
+   - 检查Role ID和Secret ID是否正确
+   - 验证AppRole是否有正确的策略附加
+
+2. **路径错误**：
+   - KV v2引擎需要在路径中包含`data`，例如`kv/data/path`而不是`kv/path`
+
+3. **权限问题**：
+   - 确保AppRole有足够的权限访问请求的密钥
+
+### 8.2 调试技巧
+
+```yaml
+- name: 调试Vault查询
+  debug:
+    msg: "{{ lookup('hashi_vault', 'secret=kv/data/ansible/db:password auth_method=approle role_id=' + role_id + ' secret_id=' + secret_id + ' url=' + vault_addr) }}"
+  vars:
+    ansible_hashi_vault_debug: true
--- a/docs/vault/vault-cluster.nomad
+++ b/docs/vault/vault-cluster.nomad
@@ -0,0 +1,94 @@
+job "vault-cluster" {
+  datacenters = ["dc1"]
+  type = "service"
+
+  group "vault-servers" {
+    count = 3
+
+    constraint {
+      attribute = "${node.unique.name}"
+      operator  = "regexp"
+      value     = "(warden|ash3c|master)"
+    }
+
+    task "vault" {
+      driver = "podman"
+
+      config {
+        image = "hashicorp/vault:latest"
+        ports = ["api", "cluster"]
+        
+        # 确保容器在退出时不会自动重启
+        command = "vault"
+        args = [
+          "server",
+          "-config=/vault/config/vault.hcl"
+        ]
+        
+        # 容器网络设置
+        network_mode = "host"
+        
+        # 安全设置
+        cap_add = ["IPC_LOCK"]
+      }
+
+      template {
+        data = <<EOH
+storage "consul" {
+  address = "127.0.0.1:8500"
+  path    = "vault/"
+  token   = "{{ with secret "consul/creds/vault" }}{{ .Data.token }}{{ end }}"
+}
+
+listener "tcp" {
+  address     = "0.0.0.0:8200"
+  tls_disable = 1  # 生产环境应启用TLS
+}
+
+api_addr = "http://{{ env "NOMAD_IP_api" }}:8200"
+cluster_addr = "http://{{ env "NOMAD_IP_cluster" }}:8201"
+
+ui = true
+disable_mlock = true
+EOH
+        destination = "vault/config/vault.hcl"
+      }
+
+      volume_mount {
+        volume      = "vault-data"
+        destination = "/vault/data"
+        read_only   = false
+      }
+
+      resources {
+        cpu    = 500
+        memory = 1024
+        
+        network {
+          mbits = 10
+          port "api" { static = 8200 }
+          port "cluster" { static = 8201 }
+        }
+      }
+
+      service {
+        name = "vault"
+        port = "api"
+        
+        check {
+          name     = "vault-health"
+          type     = "http"
+          path     = "/v1/sys/health"
+          interval = "10s"
+          timeout  = "2s"
+        }
+      }
+    }
+
+    volume "vault-data" {
+      type      = "host"
+      read_only = false
+      source    = "vault-data"
+    }
+  }
+}
--- a/docs/vault/vault_implementation_proposal.md
+++ b/docs/vault/vault_implementation_proposal.md
@@ -0,0 +1,169 @@
+# HashiCorp Vault 实施方案论证
+
+## 1. 项目现状分析
+
+### 1.1 现有基础设施
+- **多云环境**: Oracle Cloud, 华为云, Google Cloud, AWS, DigitalOcean
+- **基础设施管理**: OpenTofu (Terraform)
+- **配置管理**: Ansible
+- **容器编排**: Nomad + Podman
+- **服务发现**: Consul (部署在warden、ash3c、master三个节点上)
+- **CI/CD**: Gitea Actions
+
+### 1.2 当前密钥管理现状
+- 部分使用Ansible Vault管理敏感信息
+- 存在明文密钥存储在代码库中(如`security/secrets/key.md`)
+- 缺乏统一的密钥管理和轮换机制
+- 没有集中的访问控制和审计机制
+
+### 1.3 安全风险
+- 明文密钥存储导致潜在的安全漏洞
+- 缺乏密钥轮换机制增加了长期凭据泄露的风险
+- 分散的密钥管理增加了维护难度和安全风险
+- 缺乏审计机制，难以追踪谁在何时访问了敏感信息
+
+## 2. HashiCorp Vault 解决方案
+
+### 2.1 Vault 简介
+HashiCorp Vault是一个密钥管理和数据保护工具，专为现代云环境设计，提供以下核心功能：
+- 密钥和敏感数据的安全存储
+- 动态生成临时凭据
+- 数据加密服务
+- 详细的审计日志
+- 精细的访问控制
+
+### 2.2 Vault 如何解决当前问题
+- **集中式密钥管理**: 所有密钥和敏感信息统一存储和管理
+- **动态密钥生成**: 为数据库、云服务等生成临时凭据，减少长期凭据泄露风险
+- **自动密钥轮换**: 定期自动轮换密钥，提高安全性
+- **访问控制**: 基于角色的访问控制，确保只有授权用户能访问特定密钥
+- **审计日志**: 详细记录所有密钥访问操作，便于安全审计
+- **与现有基础设施集成**: 与Nomad和Consul无缝集成
+
+## 3. 部署方案
+
+### 3.1 部署架构
+建议在现有的Consul集群节点(warden、ash3c、master)上部署Vault，形成高可用的Vault集群：
+
+```
+-------------------+    +-------------------+    +-------------------+
+|      warden       |    |       ash3c       |    |      master       |
+|                   |    |                   |    |                   |
+|  +-------------+  |    |  +-------------+  |    |  +-------------+  |
+|  |   Consul    |  |    |  |   Consul    |  |    |  |   Consul    |  |
+|  +-------------+  |    |  +-------------+  |    |  +-------------+  |
+|                   |    |                   |    |                   |
+|  +-------------+  |    |  +-------------+  |    |  +-------------+  |
+|  |    Vault    |  |    |  |    Vault    |  |    |  |    Vault    |  |
+|  +-------------+  |    |  +-------------+  |    |  +-------------+  |
+-------------------+    +-------------------+    +-------------------+
+```
+
+### 3.2 存储后端
+使用现有的Consul集群作为Vault的存储后端，利用Consul的高可用性和一致性特性：
+- Vault数据加密存储在Consul中
+- 利用Consul的分布式特性确保数据的高可用性
+- Vault服务器本身无状态，便于扩展和维护
+
+### 3.3 资源需求
+每个节点上的Vault服务建议配置：
+- CPU: 2-4核
+- 内存: 4-8GB
+- 存储: 20GB (用于日志和临时数据)
+
+### 3.4 网络配置
+- Vault API端口: 8200
+- Vault集群通信端口: 8201
+- 配置TLS加密所有通信
+- 设置适当的防火墙规则，限制对Vault API的访问
+
+## 4. 实施计划
+
+### 4.1 准备阶段
+1. **环境准备**
+   - 在目标节点上安装必要的依赖
+   - 生成TLS证书用于Vault通信加密
+   - 配置防火墙规则
+
+2. **配置文件准备**
+   - 创建Vault配置文件
+   - 配置Consul存储后端
+   - 设置TLS和加密参数
+
+### 4.2 部署阶段
+1. **初始部署**
+   - 在三个节点上安装Vault
+   - 配置为使用Consul作为存储后端
+   - 初始化Vault并生成解封密钥
+
+2. **高可用性配置**
+   - 配置Vault集群
+   - 设置自动解封机制
+   - 配置负载均衡
+
+### 4.3 集成阶段
+1. **与现有系统集成**
+   - 配置Nomad使用Vault获取密钥
+   - 更新Ansible脚本，使用Vault API获取敏感信息
+   - 集成到CI/CD流程中
+
+2. **密钥迁移**
+   - 将现有密钥迁移到Vault
+   - 设置密钥轮换策略
+   - 移除代码库中的明文密钥
+
+### 4.4 验证和测试
+1. **功能测试**
+   - 验证Vault的基本功能
+   - 测试密钥访问和管理
+   - 验证高可用性和故障转移
+
+2. **安全测试**
+   - 进行渗透测试
+   - 验证访问控制策略
+   - 测试审计日志功能
+
+## 5. 运维和管理
+
+### 5.1 日常运维
+- 定期备份Vault数据
+- 监控Vault服务状态
+- 审查审计日志
+
+### 5.2 灾难恢复
+- 制定详细的灾难恢复计划
+- 定期进行恢复演练
+- 确保解封密钥的安全存储
+
+### 5.3 安全最佳实践
+- 实施最小权限原则
+- 定期轮换根密钥
+- 使用多因素认证
+- 定期审查访问策略
+
+## 6. 实施时间表
+
+| 阶段 | 任务 | 时间估计 |
+|------|------|----------|
+| 准备 | 环境准备 | 1天 |
+| 准备 | 配置文件准备 | 1天 |
+| 部署 | 初始部署 | 1天 |
+| 部署 | 高可用性配置 | 1天 |
+| 集成 | 与现有系统集成 | 3天 |
+| 集成 | 密钥迁移 | 2天 |
+| 测试 | 功能和安全测试 | 2天 |
+| 文档 | 编写运维文档 | 1天 |
+| **总计** | | **12天** |
+
+## 7. 结论和建议
+
+基于对当前基础设施和安全需求的分析，我们强烈建议在现有的Consul集群节点上部署HashiCorp Vault，以提升项目的安全性和密钥管理能力。
+
+主要优势包括：
+- 消除明文密钥存储的安全风险
+- 提供集中式的密钥管理和访问控制
+- 支持动态密钥生成和自动轮换
+- 与现有的HashiCorp生态系统(Nomad、Consul)无缝集成
+- 提供详细的审计日志，满足合规要求
+
+通过在现有节点上部署Vault，我们可以充分利用现有资源，同时显著提升项目的安全性，为多云环境提供统一的密钥管理解决方案。
--- a/docs/vault/vault_setup_guide.md
+++ b/docs/vault/vault_setup_guide.md
@@ -0,0 +1,252 @@
+# Vault 部署和配置指南
+
+本文档提供了在现有Consul集群节点上部署和配置HashiCorp Vault的详细步骤。
+
+## 1. 前置准备
+
+### 1.1 创建数据目录
+
+在每个节点上创建Vault数据目录：
+
+```bash
+sudo mkdir -p /opt/vault/data
+sudo chown -R nomad:nomad /opt/vault
+```
+
+### 1.2 生成TLS证书（生产环境必须）
+
+```bash
+# 生成CA证书
+vault operator generate-root -generate-only -type=tls > ca.cert
+
+# 生成服务器证书
+vault operator generate-server-cert > server.cert
+```
+
+## 2. 部署Vault集群
+
+### 2.1 使用Nomad部署
+
+将`vault-cluster.nomad`文件提交到Nomad：
+
+```bash
+nomad job run vault-cluster.nomad
+```
+
+### 2.2 验证部署状态
+
+```bash
+# 检查Nomad任务状态
+nomad job status vault-cluster
+
+# 检查Vault服务状态
+curl http://localhost:8200/v1/sys/health
+```
+
+## 3. 初始化和解封Vault
+
+### 3.1 初始化Vault
+
+在任一节点上执行：
+
+```bash
+# 初始化Vault，生成解封密钥和根令牌
+vault operator init -key-shares=5 -key-threshold=3
+```
+
+**重要提示：** 安全保存生成的解封密钥和根令牌！
+
+### 3.2 解封Vault
+
+在每个节点上执行解封操作（需要至少3个解封密钥）：
+
+```bash
+# 解封Vault
+vault operator unseal <解封密钥1>
+vault operator unseal <解封密钥2>
+vault operator unseal <解封密钥3>
+```
+
+## 4. 配置Vault
+
+### 4.1 登录Vault
+
+```bash
+# 设置Vault地址
+export VAULT_ADDR='http://127.0.0.1:8200'
+
+# 使用根令牌登录
+vault login <根令牌>
+```
+
+### 4.2 启用密钥引擎
+
+```bash
+# 启用KV v2密钥引擎
+vault secrets enable -version=2 kv
+
+# 启用AWS密钥引擎（如需要）
+vault secrets enable aws
+
+# 启用数据库密钥引擎（如需要）
+vault secrets enable database
+```
+
+### 4.3 配置访问策略
+
+```bash
+# 创建策略文件
+cat > nomad-server-policy.hcl <<EOF
+path "kv/data/nomad/*" {
+  capabilities = ["read"]
+}
+EOF
+
+# 创建策略
+vault policy write nomad-server nomad-server-policy.hcl
+
+# 创建令牌
+vault token create -policy=nomad-server
+```
+
+## 5. 与Nomad集成
+
+### 5.1 配置Nomad使用Vault
+
+编辑Nomad配置文件（`/etc/nomad.d/nomad.hcl`），添加Vault配置：
+
+```hcl
+vault {
+  enabled = true
+  address = "http://127.0.0.1:8200"
+  token   = "<Nomad服务器的Vault令牌>"
+}
+```
+
+### 5.2 重启Nomad服务
+
+```bash
+sudo systemctl restart nomad
+```
+
+## 6. 迁移现有密钥到Vault
+
+### 6.1 存储API密钥
+
+```bash
+# 存储OCI API密钥
+vault kv put kv/oci/api-key key="$(cat /root/mgmt/security/secrets/key.md)"
+
+# 存储其他云服务商密钥
+vault kv put kv/aws/credentials aws_access_key_id="<访问密钥ID>" aws_secret_access_key="<秘密访问密钥>"
+```
+
+### 6.2 配置密钥轮换策略
+
+```bash
+# 为数据库凭据配置自动轮换
+vault write database/config/mysql \
+    plugin_name=mysql-database-plugin \
+    connection_url="{{username}}:{{password}}@tcp(database.example.com:3306)/" \
+    allowed_roles="app-role" \
+    username="root" \
+    password="<数据库根密码>"
+
+# 配置角色
+vault write database/roles/app-role \
+    db_name=mysql \
+    creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';" \
+    default_ttl="1h" \
+    max_ttl="24h"
+```
+
+## 7. 安全最佳实践
+
+### 7.1 启用审计日志
+
+```bash
+# 启用文件审计设备
+vault audit enable file file_path=/var/log/vault/audit.log
+```
+
+### 7.2 配置自动解封（生产环境）
+
+对于生产环境，建议配置自动解封机制，可以使用云KMS服务：
+
+```hcl
+# AWS KMS自动解封配置示例
+seal "awskms" {
+  region     = "us-west-2"
+  kms_key_id = "<AWS KMS密钥ID>"
+}
+```
+
+### 7.3 定期轮换根密钥
+
+```bash
+# 轮换根密钥
+vault operator rotate
+```
+
+## 8. 故障排除
+
+### 8.1 检查Vault状态
+
+```bash
+# 检查Vault状态
+vault status
+
+# 检查密封状态
+vault status -format=json | jq '.sealed'
+```
+
+### 8.2 检查Consul存储
+
+```bash
+# 检查Consul中的Vault数据
+consul kv get -recurse vault/
+```
+
+### 8.3 常见问题解决
+
+- **Vault启动失败**：检查配置文件语法和权限
+- **解封失败**：确保使用正确的解封密钥
+- **API不可访问**：检查防火墙规则和监听地址配置
+
+## 9. 备份和恢复
+
+### 9.1 备份Vault数据
+
+```bash
+# 备份Consul中的Vault数据
+consul snapshot save vault-backup.snap
+```
+
+### 9.2 恢复Vault数据
+
+```bash
+# 恢复Consul快照
+consul snapshot restore vault-backup.snap
+```
+
+## 10. 日常维护
+
+### 10.1 监控Vault状态
+
+```bash
+# 设置Prometheus监控
+vault write sys/metrics/collector prometheus
+```
+
+### 10.2 查看审计日志
+
+```bash
+# 分析审计日志
+cat /var/log/vault/audit.log | jq
+```
+
+### 10.3 定期更新Vault版本
+
+```bash
+# 更新Vault版本（通过更新Nomad作业）
+nomad job run -detach vault-cluster.nomad