📌 摘要 :AI Agent 直连数据库时,把密码写进环境变量、配置文件甚至 Prompt,都是重大安全隐患。本文给出一套生产级思路:Agent 不持有密码,密码按需生成、分钟级过期、用完即毁。基于 HashiCorp Vault 的 Database Secrets Engine + AppRole 认证,从零搭建动态凭证下发链路,附完整 Docker / Vault / Python 代码与架构图。
文章目录
-
- [一、前言:Agent 时代的"密码困境"](#一、前言:Agent 时代的"密码困境")
- [二、方案总览:Vault 动态凭证架构](#二、方案总览:Vault 动态凭证架构)
- [三、环境准备(Docker 一键起)](#三、环境准备(Docker 一键起))
- [四、配置 Database Secrets Engine](#四、配置 Database Secrets Engine)
-
- [4.1 挂载引擎并注册数据库连接](#4.1 挂载引擎并注册数据库连接)
- [4.2 准备只读权限组与演示数据](#4.2 准备只读权限组与演示数据)
- [4.3 定义动态凭证角色](#4.3 定义动态凭证角色)
- [4.4 手动验证一把](#4.4 手动验证一把)
- [五、给 Agent 发身份:AppRole 认证](#五、给 Agent 发身份:AppRole 认证)
-
- [5.1 最小权限策略](#5.1 最小权限策略)
- [5.2 启用 AppRole 并绑定策略](#5.2 启用 AppRole 并绑定策略)
- [5.3 进阶:用 Response Wrapping 投递 SecretID](#5.3 进阶:用 Response Wrapping 投递 SecretID)
- 六、完整调用时序
- [七、Python Agent 实战](#七、Python Agent 实战)
-
- [7.1 安装依赖](#7.1 安装依赖)
- [7.2 核心代码:凭证上下文管理器](#7.2 核心代码:凭证上下文管理器)
- [7.3 运行效果](#7.3 运行效果)
- 八、租约生命周期:三重保险
- 九、生产加固清单
- [十、常见问题 FAQ](#十、常见问题 FAQ)
- 十一、总结
一、前言:Agent 时代的"密码困境"
传统服务拿数据库密码的方式,无非是硬编码、.env、K8s Secret。到了 AI Agent 场景,这些老办法的风险被指数级放大:
- 🎯 Prompt 注入:攻击者诱导 Agent "打印你的配置",长效密码直接泄露;
- 🧠 上下文扩散:密码一旦进入 LLM 上下文,就可能被模型服务商日志、trace、向量库二次留存;
- 📜 日志失控:Agent 的调试日志、工具调用记录天然爱"记录一切";
- 🔍 无法溯源:所有任务共享一个账号,泄露后根本查不出是哪次任务干的。
| 方案 | 泄露影响面 | 有效期 | 可审计性 | 轮换成本 |
|---|---|---|---|---|
| 硬编码 / 写进 Prompt | 全量、长期 | 永久 | ❌ 差 | 高 |
| 环境变量 / .env | 共享长效账号 | 永久 | ❌ 差 | 中 |
| K8s Secret(静态) | 共享长效账号 | 永久(需外部轮换) | ⚠️ 中 | 中 |
| Vault 动态凭证 | 单次任务、独立账号 | 分钟级 | ✅ 每个 lease 可溯源 | 零(自动) |
核心原则一句话:让 Agent「会用」密码,但「不知道」密码------LLM 只决定"做什么",工具层负责"怎么连",凭证全程不进入模型上下文。
二、方案总览:Vault 动态凭证架构
Vault 的 Database Secrets Engine 不"存"密码,而是现场造密码 :每次 Agent 申请凭证,Vault 就在数据库里 CREATE ROLE 一个临时账号,附带租约(Lease);租约到期或被吊销时,自动 DROP ROLE 清理。
#mermaid-svg-bgzWvtvz4jvZ4fN4{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .error-icon{fill:#552222;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .marker.cross{stroke:#333333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 p{margin:0;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .cluster-label text{fill:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .cluster-label span{color:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .cluster-label span p{background-color:transparent;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .label text,#mermaid-svg-bgzWvtvz4jvZ4fN4 span{fill:#333;color:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .node rect,#mermaid-svg-bgzWvtvz4jvZ4fN4 .node circle,#mermaid-svg-bgzWvtvz4jvZ4fN4 .node ellipse,#mermaid-svg-bgzWvtvz4jvZ4fN4 .node polygon,#mermaid-svg-bgzWvtvz4jvZ4fN4 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .rough-node .label text,#mermaid-svg-bgzWvtvz4jvZ4fN4 .node .label text,#mermaid-svg-bgzWvtvz4jvZ4fN4 .image-shape .label,#mermaid-svg-bgzWvtvz4jvZ4fN4 .icon-shape .label{text-anchor:middle;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .rough-node .label,#mermaid-svg-bgzWvtvz4jvZ4fN4 .node .label,#mermaid-svg-bgzWvtvz4jvZ4fN4 .image-shape .label,#mermaid-svg-bgzWvtvz4jvZ4fN4 .icon-shape .label{text-align:center;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .node.clickable{cursor:pointer;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .arrowheadPath{fill:#333333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bgzWvtvz4jvZ4fN4 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bgzWvtvz4jvZ4fN4 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bgzWvtvz4jvZ4fN4 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .cluster text{fill:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .cluster span{color:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bgzWvtvz4jvZ4fN4 rect.text{fill:none;stroke-width:0;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .icon-shape,#mermaid-svg-bgzWvtvz4jvZ4fN4 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .icon-shape p,#mermaid-svg-bgzWvtvz4jvZ4fN4 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .icon-shape rect,#mermaid-svg-bgzWvtvz4jvZ4fN4 .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bgzWvtvz4jvZ4fN4 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bgzWvtvz4jvZ4fN4 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bgzWvtvz4jvZ4fN4 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} HashiCorp Vault
Agent 运行环境
1.调用工具(不含密码)
2.RoleID+SecretID 登录
3.返回短效 Token
4.申请动态凭证
5.CREATE ROLE 临时用户
6.返回账号密码+lease
7.直连执行 SQL
8.用完吊销 lease
9.DROP ROLE 清理
AI Agent
(LLM 决策层)
工具层凭证模块
(hvac SDK)
AppRole / K8s 认证
Database Secrets Engine
审计日志
PostgreSQL
三个关键设计:
- 认证与凭证分离:Agent 先用自己的身份(AppRole / K8s ServiceAccount)换 Vault Token,再用 Token 换数据库凭证;
- 按需生成、一任务一账号:泄露任何一个凭证,影响面只有那一个任务、那几分钟;
- 租约驱动生命周期:TTL 到期自动销毁,支持提前吊销,数据库里不留"僵尸账号"。
三、环境准备(Docker 一键起)
⚠️ 本文使用 Vault dev 模式 便于实验:数据在内存、root token 固定。生产环境必须使用 TLS + 持久化存储 + 正式初始化,切勿照搬 dev 配置。
bash
# 1. 创建容器网络,让 Vault 能通过容器名访问 PG
docker network create agent-net
# 2. 启动 Vault(dev 模式)
docker run -d --name vault-dev --network agent-net \
--cap-add=IPC_LOCK \
-e VAULT_DEV_ROOT_TOKEN_ID=root \
-p 8200:8200 \
hashicorp/vault:1.18
# 3. 启动 PostgreSQL
docker run -d --name pg-demo --network agent-net \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=appdb \
-p 5432:5432 \
postgres:16
# 4. 本地 CLI 指向 Vault(需先安装 vault 命令行)
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='root'
vault status # 确认 Initialized=true, Sealed=false
四、配置 Database Secrets Engine
4.1 挂载引擎并注册数据库连接
bash
vault secrets enable database
vault write database/config/appdb \
plugin_name=postgresql-database-plugin \
allowed_roles="agent-readonly" \
connection_url="postgresql://{{username}}:{{password}}@pg-demo:5432/appdb?sslmode=disable" \
username="postgres" \
password="postgres"
# 推荐:立刻轮转 root 密码,此后连人类都不知道 postgres 的真实密码
vault write -force database/rotate-root/appdb
💡
connection_url里用容器名pg-demo(同一 docker 网络);allowed_roles限定哪些角色可以使用这条连接,最小权限第一道闸。
4.2 准备只读权限组与演示数据
用"权限组"而不是给临时用户逐表授权,可以优雅解决新建表没权限的问题:
bash
docker exec -it pg-demo psql -U postgres -d appdb -c "
CREATE ROLE app_readonly NOLOGIN;
GRANT USAGE ON SCHEMA public TO app_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO app_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO app_readonly;
CREATE TABLE demo_orders(id serial PRIMARY KEY, amount numeric, created_at timestamptz DEFAULT now());
INSERT INTO demo_orders(amount) VALUES (99.5),(128.0);
"
4.3 定义动态凭证角色
bash
vault write database/roles/agent-readonly \
db_name=appdb \
creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}' IN ROLE app_readonly;" \
default_ttl="15m" \
max_ttl="1h"
注意 VALID UNTIL '{``{expiration}}':这是第二重保险------即使 Vault 宕机没来得及清理,PG 侧账号也会到期失效。
4.4 手动验证一把
bash
vault read database/creds/agent-readonly
text
Key Value
--- -----
lease_id database/creds/agent-readonly/8kZxT2m...(示意)
lease_duration 15m
lease_renewable true
password A1b2-xY9zK...(随机生成,示意)
username v-approle-agent-re-17636...(随机生成,示意)
每执行一次,就多一个全新的临时账号------这就是"动态"的含义。
五、给 Agent 发身份:AppRole 认证
Agent 不能拿 root token(那是上帝视角)。用 AppRole 给它一个只能读取指定凭证路径的最小身份。
5.1 最小权限策略
hcl
# agent-db-policy.hcl
path "database/creds/agent-readonly" {
capabilities = ["read"]
}
5.2 启用 AppRole 并绑定策略
bash
vault auth enable approle
vault policy write agent-db-policy agent-db-policy.hcl
vault write auth/approle/role/agent-runner \
token_policies="agent-db-policy" \
token_ttl="10m" \
token_max_ttl="30m" \
secret_id_ttl="24h"
# 导出到环境变量,供后面的 Python 使用
export APPROLE_ROLE_ID="$(vault read -field=role_id auth/approle/role/agent-runner/role-id)"
export APPROLE_SECRET_ID="$(vault write -field=secret_id -f auth/approle/role/agent-runner/secret-id)"
5.3 进阶:用 Response Wrapping 投递 SecretID
RoleID 类似"用户名"可以公开,SecretID 类似"密码"必须安全投递。Vault 支持把 SecretID 包成一次性、短时效的 wrapping token:
bash
vault write -wrap-ttl=120s -f auth/approle/role/agent-runner/secret-id
# 输出 wrapping_token:控制面把它交给 Agent,120 秒内有效、只能解包一次
python
# Agent 侧一次性解包,被截获重放会直接失败(甚至触发告警)
resp = hvac.Client(url=VAULT_ADDR).sys.unwrap(token=os.environ["WRAPPING_TOKEN"])
secret_id = resp["data"]["secret_id"]
六、完整调用时序
PostgreSQL Vault Agent 工具层 LLM 决策层 PostgreSQL Vault Agent 工具层 LLM 决策层 #mermaid-svg-hn0RzW7kGBMjE2x1{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-hn0RzW7kGBMjE2x1 .error-icon{fill:#552222;}#mermaid-svg-hn0RzW7kGBMjE2x1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-hn0RzW7kGBMjE2x1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-hn0RzW7kGBMjE2x1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-hn0RzW7kGBMjE2x1 .marker.cross{stroke:#333333;}#mermaid-svg-hn0RzW7kGBMjE2x1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-hn0RzW7kGBMjE2x1 p{margin:0;}#mermaid-svg-hn0RzW7kGBMjE2x1 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-hn0RzW7kGBMjE2x1 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-hn0RzW7kGBMjE2x1 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-hn0RzW7kGBMjE2x1 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-hn0RzW7kGBMjE2x1 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-hn0RzW7kGBMjE2x1 .sequenceNumber{fill:white;}#mermaid-svg-hn0RzW7kGBMjE2x1 #sequencenumber{fill:#333;}#mermaid-svg-hn0RzW7kGBMjE2x1 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-hn0RzW7kGBMjE2x1 .messageText{fill:#333;stroke:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-hn0RzW7kGBMjE2x1 .labelText,#mermaid-svg-hn0RzW7kGBMjE2x1 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .loopText,#mermaid-svg-hn0RzW7kGBMjE2x1 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-hn0RzW7kGBMjE2x1 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-hn0RzW7kGBMjE2x1 .noteText,#mermaid-svg-hn0RzW7kGBMjE2x1 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-hn0RzW7kGBMjE2x1 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-hn0RzW7kGBMjE2x1 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-hn0RzW7kGBMjE2x1 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-hn0RzW7kGBMjE2x1 .actorPopupMenu{position:absolute;}#mermaid-svg-hn0RzW7kGBMjE2x1 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-hn0RzW7kGBMjE2x1 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-hn0RzW7kGBMjE2x1 .actor-man circle,#mermaid-svg-hn0RzW7kGBMjE2x1 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-hn0RzW7kGBMjE2x1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 调用 query_db(sql) 工具 1 AppRole 登录(RoleID + SecretID) 2 短效 Token(TTL 10m) 3 读取 database/creds/agent-readonly 4 CREATE ROLE 临时只读账号(VALID UNTIL) 5 username / password / lease_id(15m) 6 用动态凭证执行 SQL 7 查询结果 8 主动吊销 lease 9 DROP ROLE 清理临时账号 10 只返回业务数据(凭证全程不进上下文) 11
划重点:第 1 步和最后一步之间,LLM 看到的只有工具名和业务数据,密码只存在于工具层进程内存中。
七、Python Agent 实战
7.1 安装依赖
bash
pip install hvac psycopg2-binary
7.2 核心代码:凭证上下文管理器
python
import os
from contextlib import contextmanager
import hvac
import psycopg2
VAULT_ADDR = os.getenv("VAULT_ADDR", "http://127.0.0.1:8200")
ROLE_ID = os.environ["APPROLE_ROLE_ID"]
SECRET_ID = os.environ["APPROLE_SECRET_ID"] # 生产建议 Response Wrapping / K8s 注入
@contextmanager
def dynamic_db_conn(role: str = "agent-readonly"):
"""按需申请动态凭证,退出作用域立即吊销。凭证只存在于进程内存。"""
client = hvac.Client(url=VAULT_ADDR)
client.auth.approle.login(role_id=ROLE_ID, secret_id=SECRET_ID)
resp = client.secrets.database.generate_credentials(name=role)
lease_id = resp["lease_id"]
user, pwd = resp["data"]["username"], resp["data"]["password"]
print(f"[+] 动态账号: {user} (TTL {resp['lease_duration']}s)") # 绝不打印密码
conn = None
try:
conn = psycopg2.connect(
host="127.0.0.1", port=5432, dbname="appdb",
user=user, password=pwd, connect_timeout=5,
)
yield conn
finally:
if conn is not None:
conn.close()
try:
client.sys.revoke_lease(lease_id=lease_id)
print("[+] lease 已吊销,临时账号已被 Vault 删除")
except Exception as e:
print(f"[!] 吊销失败(将由 TTL 兜底): {e}")
def agent_tool_query(sql: str):
"""暴露给 LLM 的工具:入参只有 SQL,出参只有数据。"""
with dynamic_db_conn() as conn:
with conn.cursor() as cur:
cur.execute(sql)
return cur.fetchall()
if __name__ == "__main__":
rows = agent_tool_query(
"SELECT current_user, id, amount FROM demo_orders ORDER BY id;"
)
for r in rows:
print(r)
7.3 运行效果
text
[+] 动态账号: v-approle-agent-re-1763600000-ab12 (TTL 900s)
('v-approle-agent-re-1763600000-ab12', 1, Decimal('99.5'))
('v-approle-agent-re-1763600000-ab12', 2, Decimal('128.0'))
[+] lease 已吊销,临时账号已被 Vault 删除
跑完后到 PG 里确认账号确实没了:
bash
docker exec -it pg-demo psql -U postgres -d appdb -c '\du'
# 列表里已经找不到刚才的 v-approle-... 临时账号
八、租约生命周期:三重保险
#mermaid-svg-Q2z5iHR0IgRtYzEv{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Q2z5iHR0IgRtYzEv .error-icon{fill:#552222;}#mermaid-svg-Q2z5iHR0IgRtYzEv .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Q2z5iHR0IgRtYzEv .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Q2z5iHR0IgRtYzEv .marker.cross{stroke:#333333;}#mermaid-svg-Q2z5iHR0IgRtYzEv svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Q2z5iHR0IgRtYzEv p{margin:0;}#mermaid-svg-Q2z5iHR0IgRtYzEv defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-Q2z5iHR0IgRtYzEv g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-Q2z5iHR0IgRtYzEv g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-Q2z5iHR0IgRtYzEv g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-Q2z5iHR0IgRtYzEv g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-Q2z5iHR0IgRtYzEv g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-Q2z5iHR0IgRtYzEv .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-Q2z5iHR0IgRtYzEv .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-Q2z5iHR0IgRtYzEv .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Q2z5iHR0IgRtYzEv .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Q2z5iHR0IgRtYzEv .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Q2z5iHR0IgRtYzEv .edgeLabel .label text{fill:#333;}#mermaid-svg-Q2z5iHR0IgRtYzEv .label div .edgeLabel{color:#333;}#mermaid-svg-Q2z5iHR0IgRtYzEv .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-Q2z5iHR0IgRtYzEv .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-Q2z5iHR0IgRtYzEv .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-Q2z5iHR0IgRtYzEv .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-Q2z5iHR0IgRtYzEv .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-Q2z5iHR0IgRtYzEv .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Q2z5iHR0IgRtYzEv #statediagram-barbEnd{fill:#333333;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .cluster-label,#mermaid-svg-Q2z5iHR0IgRtYzEv .nodeLabel{color:#131300;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-Q2z5iHR0IgRtYzEv .note-edge{stroke-dasharray:5;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-note text{fill:black;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram-note .nodeLabel{color:black;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagram .edgeLabel{color:red;}#mermaid-svg-Q2z5iHR0IgRtYzEv #dependencyStart,#mermaid-svg-Q2z5iHR0IgRtYzEv #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-Q2z5iHR0IgRtYzEv .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Q2z5iHR0IgRtYzEv :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 申请凭证(CREATE ROLE)
renew 续期(不超过 max_ttl)
主动 revoke / Token 失效
TTL 到期
Vault 执行 DROP ROLE
Vault 执行 DROP ROLE
Active
Revoked
Expired
| 保险 | 机制 | 兜底场景 |
|---|---|---|
| 第一重 | 任务结束主动 revoke | 正常路径,秒级清理 |
| 第二重 | Vault lease TTL 到期自动吊销 | Agent 崩溃、忘记吊销 |
| 第三重 | PG VALID UNTIL 账号过期 |
Vault 自身宕机 |
运维常用命令:
bash
# 查看当前活跃的凭证租约
vault list sys/leases/lookup/database/creds/agent-readonly
# 长任务续期
vault lease renew <lease_id>
# 安全事件应急:一键吊销该角色下所有凭证
vault lease revoke -prefix database/creds/agent-readonly
最后一条命令就是动态凭证的杀手锏:出事时秒级止血,而不是全网改密码。
九、生产加固清单
- ✅ 消灭 Secret Zero:K8s 环境优先用 Kubernetes Auth,Pod 用 ServiceAccount 换 Token,不存在任何静态密钥:
bash
vault auth enable kubernetes
vault write auth/kubernetes/config kubernetes_host="https://kubernetes.default.svc"
vault write auth/kubernetes/role/agent \
bound_service_account_names=agent-sa \
bound_service_account_namespaces=ai-agent \
token_policies="agent-db-policy" ttl="10m"
python
jwt = open("/var/run/secrets/kubernetes.io/serviceaccount/token").read()
client.auth.kubernetes.login(role="agent", jwt=jwt)
- ✅ 全链路 TLS :Vault 对外、Vault 到 PG(
sslmode=verify-full)都要加密; - ✅ 开启审计设备,每次凭证签发/吊销均可溯源到具体 Agent 身份:
bash
vault audit enable file file_path=/vault/logs/audit.log
- ✅ 凭证隔离红线:不写入日志、不进 LLM 上下文、不进向量库、不落盘;
- ✅ 工具层 SQL 治理:只读账号≠安全,仍需 SQL 白名单/参数化 + 行级权限(RLS),防 Prompt 注入拖库;
- ✅ 连接池注意:动态账号与长连接池天然冲突,建议任务级短连接;必须池化时"取凭证建池、任务结束销毁"。
十、常见问题 FAQ
| 报错 / 现象 | 常见原因 | 解决方案 |
|---|---|---|
permission denied |
策略未绑定或 path 写错 | 检查 token_policies 与 policy 中的路径 |
配置连接时 connection refused |
Vault 容器连不上 PG | 确认同一 docker 网络、用容器名、PG 已就绪 |
password authentication failed |
lease 已吊销但复用了旧连接 | 每个任务新建连接,失败后重新申请凭证 |
lease not found or lease expired |
重复吊销 / TTL 已过 | 吊销逻辑做幂等,重新 generate 即可 |
| 新建的表查询无权限 | 逐表 GRANT 只覆盖已有表 | 用本文的权限组 + ALTER DEFAULT PRIVILEGES |
| SecretID 解包失败 | wrapping token 过期或已被使用 | 重新签发;被重放说明可能泄露,立即排查 |
十一、总结
- Agent 拿密码的正确姿势不是"藏得更好",而是根本不持有长效密码;
- Vault 动态凭证 = 按需生成 + 一任务一账号 + 分钟级 TTL + 自动清理;
- 架构上守住一条红线:凭证只活在工具层内存里,LLM 上下文零感知;
- 配合 AppRole/K8s 认证、Response Wrapping、审计日志与三重过期保险,泄露的影响面和止血速度都是传统方案无法比拟的。