使用 Vault 管理密钥

Agent-Lab 如何使用 Vault

Agent-Lab 使用 HashiCorp Vault 进行安全的密钥管理：API 密钥、数据库凭据和其他敏感值都存放在 Vault 中，而不是数据库或环境变量文件中。在应用启动期间，当前生效的 ConfigSource 会连接 Vault 并加载配置载荷；集成在数据库中存储的只是引用，敏感值则按需从 Vault 中获取。

设置 Vault

在本地开发时，Compose 栈自带一个使用开发配置的 Vault 服务器（UI 地址为 http://localhost:8200，登录令牌为 dev-only-token）。参见运行应用。

在生产环境中，使用部署指南中的 Terraform 模块 terraform/08_vault-instance/ 来创建实例——包括 init + unseal 流程：

kubectl --namespace vault exec vault-0 -- vault operator init \
    -key-shares=1 \
    -key-threshold=1 \
    -format=json > cluster-keys.json

export VAULT_UNSEAL_KEY=$(jq -r ".unseal_keys_b64[]" cluster-keys.json)
kubectl --namespace vault exec vault-0 -- vault operator unseal $VAULT_UNSEAL_KEY

预置密钥载荷

VaultConfigSource 读取单个 KV-v2 密钥（挂载点为 secret，路径为 app_secrets），并将其映射到应用的配置键上。载荷中的各个键列在配置参考中；使用 Vault CLI 一次性写入即可：

vault kv put secret/app_secrets \
  api_base_url="https://<agent_lab_fqdn>" \
  cdp_url="http://<cdp_host>:9222" \
  auth_enabled="true" \
  auth_url="https://<auth_fqdn>" \
  auth_realm="<realm_name>" \
  auth_client_id="<client_name>" \
  auth_client_secret="<client_secret>" \
  broker_url="redis://:<password>@<redis_host>:6379/0" \
  db_url="postgresql://<user>:<pass>@<db_host>:5432/agent_lab" \
  db_vectors="postgresql://<user>:<pass>@<db_host>:5432/agent_lab_vectors" \
  db_checkpoints="postgresql://<user>:<pass>@<db_host>:5432/agent_lab_checkpoints"

当应用无法（或不应）使用静态 VAULT_TOKEN 时，只要设置了 VAULT_K8S_ROLE，默认配置源就会自动切换为 KubernetesVaultConfigSource——它使用 Pod 的投射（projected）ServiceAccount 令牌进行认证，因此无需预置或轮换任何静态令牌。

生产环境

遵循我们的云原生原则，我们推荐采用 Vault Kubernetes 高可用部署。15_agent-lab-dependencies/ Terraform 模块负责接入运行时凭据；应用会在启动时通过配置约定获取所有配置。