项目接入 vault¶

消费方项目怎么用 vault 里的凭证和资源。

流程一览¶

vault.json         ←  你写（声明要什么）
    ↓ vault install
.vault/secrets.json + .env  ← CLI 生成（gitignore）
    ↓
代码直接读

1. 初始化¶

cd ~/myproject
vault init

在当前目录生成空骨架：

{
  "$schema": "https://vault-cli.local/schemas/vault-manifest.schema.json",
  "project": "myproject",
  "credentials": {},
  "resources": []
}

2. 声明依赖¶

编辑 vault.json，声明你需要的 credentials 和 resources。

{
  "$schema": "https://vault-cli.local/schemas/vault-manifest.schema.json",
  "project": "xiangqin",
  "vault_min_version": ">=0.3",
  "credentials": {
    "aliyun": {
      "slug": "aliyun-main",
      "fields": ["access_key_id", "access_key_secret", "default_region"],
      "env": {
        "access_key_id": "ALIYUN_ACCESS_KEY_ID",
        "access_key_secret": "ALIYUN_ACCESS_KEY_SECRET",
        "default_region": "ALIYUN_REGION"
      },
      "purpose": "OSS 备份 + DNS 记录"
    },
    "alipay": {
      "slug": "alipay-kongxuanpin",
      "fields": ["app_id", "app_private_key", "alipay_public_key"],
      "env": { "app_id": "ALIPAY_APP_ID" },
      "optional": true
    }
  },
  "resources": [
    { "ref": "aliyun/ecs/i-bp1iswr9bmkv3qh89965", "purpose": "生产服务器" },
    { "ref": "aliyun/oss/myproject-backup", "purpose": "每日备份" }
  ]
}

credentials 字段说明¶

字段	必填	说明
`slug`	✓	vault 里的 credential slug（`vault credential list` 查）
`fields`		白名单字段；不填 = 取全部
`env`		`vault字段名 → ENV_NAME` 映射；只列出的进 .env
`optional`		true 时凭证缺失只报 warning，不报错
`purpose`		人类可读注释

map 的 key 是本地别名¶

credentials.aliyun 里的 aliyun 是你代码里用的本地别名。底下挂的 slug: aliyun-main 是 vault 里的真名。别名层解耦了代码和 vault 命名变动。

resources 只声明不注值¶

Resource 只为 audit + vault who-uses 反查存在，不会把 spec 注入到代码。需要用时 vault resource show <ref>。

3. 安装¶

vault install

输出：

✓ vault.json → 3 credentials
  .vault/secrets.json
  .env  (6 env lines)
  .gitignore  (added .vault/ + .env)

生成的文件：

.vault/secrets.json（结构化，按别名分组）：

{
  "_generated_at": "2026-04-22T13:35:40+00:00",
  "aliyun": {
    "access_key_id": "LTAI...",
    "access_key_secret": "...",
    "default_region": "cn-hangzhou"
  },
  "alipay": { "app_id": "2021...", "app_private_key": "...", "alipay_public_key": "..." }
}

.env（扁平，12-factor 风格）：

ALIYUN_ACCESS_KEY_ID=LTAI...
ALIYUN_ACCESS_KEY_SECRET=...
ALIYUN_REGION=cn-hangzhou
ALIPAY_APP_ID=2021...

4. 代码里使用¶

Python¶

import json, os

# 方式一：结构化
secrets = json.loads(open(".vault/secrets.json").read())
ak = secrets["aliyun"]["access_key_id"]

# 方式二：环境变量（需要先 dotenv.load_dotenv 或 systemd EnvironmentFile）
ak = os.environ["ALIYUN_ACCESS_KEY_ID"]

Node¶

import fs from "fs";
import "dotenv/config";

const secrets = JSON.parse(fs.readFileSync(".vault/secrets.json"));
const ak = secrets.aliyun.access_key_id;
// 或
const ak = process.env.ALIYUN_ACCESS_KEY_ID;

Shell¶

source .env
echo $ALIYUN_ACCESS_KEY_ID

# 或直接 jq
jq -r '.aliyun.access_key_id' .vault/secrets.json

5. 刷新（AK 轮换后）¶

vault sync       # 等价 vault install，覆盖写

6. 反查¶

哪些项目在用某个 credential？

vault who-uses aliyun-main
# /Users/yarnb/xiangqin/vault.json   (credential (alias=aliyun))
# /Users/yarnb/myproject/vault.json  (credential (alias=aliyun))

gitignore¶

vault install 自动把 .vault/ 和 .env 加到 .gitignore（如果还没有）。

CI / 生产环境¶

生产部署时跑 vault install 把本地凭证拉到服务器。或者把 .vault/secrets.json 内容作为 secret manager 的变量（按平台约定）。