Vault密钥托管安全存储AI中转API密钥

很多开发者把AI中转服务的API密钥写死在配置文件或环境变量里，一旦泄露就会被盗刷。
HashiCorp Vault 是专业的密钥托管工具，可以帮你安全存储并控制谁、什么应用能读取这些密钥。
本文以零基础视角带你完成整个流程。

准备环境：在服务器上启动Vault

首先确保你的服务器是 Linux 环境（Ubuntu 或 CentOS 均可），并安装 Vault。
这里使用开发模式做演示，生产环境请配置持久化后端。

1. 下载 Vault 二进制包并解压（以最新稳定版为例）：

wget https://releases.hashicorp.com/vault/1.15.0/vault_1.15.0_linux_amd64.zip
unzip vault_1.15.0_linux_amd64.zip
sudo mv vault /usr/local/bin/

1. 启动开发模式（所有数据在内存中，重启丢失）：

vault server -dev -dev-listen-address=0.0.0.0:8200

1. 保存输出的 Root Token 和 Unseal Key（生产环境多个，此处只有一个），后续操作需要这个 Root Token。

将AI中转API密钥写入Vault

使用 KV（Key-Value）存储引擎保存密钥。
默认路径是 secret/，你也可以自定义。

1. 打开另一个终端，设置 Vault 地址并登录：

export VAULT_ADDR='http://<你的服务器IP>:8200'
export VAULT_TOKEN='<上面得到的Root Token>'

1. 启用 KV 存储引擎 v2（默认已启用，但显式启用更清晰）：

vault secrets enable -version=2 kv

1. 写入你的AI中转API密钥，例如路径为 secret/ai-gateway，键名 api_key：

vault kv put secret/ai-gateway api_key=sk-your-real-key-here

1. 验证写入是否成功：

vault kv get secret/ai-gateway

输出应显示你的密钥值（默认隐藏，可加 -field=api_key 查看）。

控制谁可以读：配置策略和令牌

直接给应用 Root Token 不安全，应该创建只读策略并生成限权令牌。

1. 创建一个策略文件 read-only.hcl：

path "secret/data/ai-gateway" {
  capabilities = ["read"]
}

1. 写入策略：

vault policy write read-ai-key ./read-only.hcl

1. 创建一个绑定该策略的令牌：

vault token create -policy=read-ai-key

输出中的 token 字段就是新令牌，把这个令牌交给你的应用。

在应用中安全读取密钥

无论你的应用是 Python 脚本还是 Node.js，都可以通过 Vault API 读取密钥。
以 curl 为例：

curl --header "X-Vault-Token: <上面生成的只读令牌>" \
     http://<服务器IP>:8200/v1/secret/data/ai-gateway

返回的 JSON 中 data.data.api_key 就是你的API密钥。

如果使用 Python，可以用 requests 或 hvac 库（推荐用 hvac 更简洁）。

避坑指南

• 开发模式重启后数据全丢，生产环境务必使用 Consul、Raft 或文件等持久化后端，并做好备份。
• 不要将 Root Token 写在代码里或提交到 Git，建议用 Vault Agent 或临时令牌注入。
• Vault 默认监听 127.0.0.1，生产需配置证书和 TLS，避免明文传输密钥。
• 密钥路径权限越细越好，不要给整个 secret/* 的读权限。

常见问题

Q: Vault 启动失败提示端口占用？
A: 检查 port 8200 是否被占用，可改用 -dev-listen-address=0.0.0.0:8201。

Q: 写入后无法读取，报 permission denied？
A: 检查策略文件中的路径是否写对了版本号 v2 引擎路径必须带 data/ 段，例如 secret/data/ai-gateway。

Q: 如何让 Vault 在后台持续运行？
A: 使用系统服务或 nohup，但开发模式仅限测试。生产请用 systemd。

验证效果

最终，你的AI中转API密钥不再明文存放在服务器文件里。
只有持有有效令牌的应用才能通过 Vault API 读取，且你可以随时撤销令牌、更新密钥或审计读取记录。
建议尽快将现有服务迁移到这套方案中。

如果你在处理 Vault 密钥托管时遇到特殊情况，优先回看本文避坑和高频问题部分，再根据实际环境调整策略。