实战场景¶
按场景组织的 cookbook。每个场景 5-10 行命令，照抄就能跑。
1. 加一把新的阿里云 RAM 子账号 AK¶
# 1. 建账号（如果还没）
vault account add aliyun/backup-bot
# 编辑器里填：
# kind: ram_subaccount
# owner_ref: self
# parent_account_ref: aliyun/main
# 2. 加凭证
vault credential add aliyun-backup-bot-ak
# 编辑器里填：
# account_ref: aliyun/backup-bot
# kind: ak_sk
# values: { access_key_id, access_key_secret }
# 3. 校验
vault check
2. 轮换 aliyun-main AK（最小心的操作）¶
# 1. 阿里云控制台 → 创建新 AK，不要先删旧的
# （阿里云允许一个账号最多 2 把 AK，并存）
# 2. 先存新 AK 到 vault
vault credential edit aliyun-main
# 改 values.access_key_id + access_key_secret 为新的
# 3. 所有用到它的项目同步
vault who-uses aliyun-main --workspace ~/Documents
# 输出：
# /Users/yarnb/xiangqin/vault.json (credential (alias=aliyun))
# ...
# 4. 每个项目重拉
cd ~/xiangqin && vault sync
cd ~/<其它项目> && vault sync
# 5. 等 24 小时观察，没问题 → 阿里云控制台删旧 AK
为什么要留旧 AK 24 小时：怕有你忘了的消费方（deploy 到 ECS 上的程序、cron job）还在用旧 AK。并存期间它们还能活。
3. 反查"谁在用这个凭证"¶
扫整个工作区的 vault.json，列出每个引用方。
4. 更新身份证（重办、地址变更、换照片）¶
# 1. 旧照片挪出 vault（用于对比）
mv ~/vault/data/files/personal/id_card_front.jpg /tmp/old-id-front.jpg
# 2. 新照片放进去（保持相同路径）
cp ~/Downloads/new-id-front.jpg ~/vault/data/files/personal/id_card_front.jpg
# 3. 如果 ID 号也变了，改 resource
vault resource edit gov-cn/id-card/self
# 编辑 spec / metadata
# 4. 校验附件引用没断
vault check
附件是 content-addressed 的（sha256 在 resource 里记），更新照片后 sha 会变。当前 vault check 不校验 sha，只校验路径存在。未来加 checksum 时要同步更新字段。
5. 登记新买的域名¶
# 1. 建 platform（如果是新注册商）
# 已有 aliyun / cloudflare 不用再建
# 2. 建 resource
vault resource add aliyun/domain/newdomain.com
# 编辑器里填：
# name, account_ref=aliyun/main
# spec: { registrar: aliyun, registered_at, expire_at, tld, reg_type }
# metadata: { icp_filed: false, notes: "..." }
# 3. DNS zone 也建
vault resource add aliyun/dns-zone/newdomain.com
6. 加一位员工（或合伙人）¶
# 1. 建 person
vault person add employee-zhang
# 编辑器里填：
# kind: natural_person
# relationship: employee
# names: { legal: "张三", display: "张三" }
# phone, email, metadata.notes
# 2. 建他的账号（若需要）
vault account add github/employee-zhang
# owner_ref: employee-zhang
# 3. 如果他持有公司某账号
vault account edit github/main
# owner_ref 改成 ["self", "employee-zhang"]（joint ownership）
7. 查某个资源的详细信息¶
# 列所有 ECS
vault resource list --platform aliyun --type ecs
# 看具体一台
vault resource show aliyun/ecs/i-bp1iswr9bmkv3qh89965
# 只看规格字段
vault resource show aliyun/ecs/i-bp1iswr9bmkv3qh89965 --json | jq '.spec'
# 查哪些 alias 指向 gamma
vault resource list --platform aliyun --type ecs --json \
| jq '.[] | select(.alias == "gamma")'
8. 删一个账号（软删 + 审计）¶
vault 目前没有软删机制，删就是永久删。推荐做法：
# 1. 先导出备份到本地临时
vault account show aliyun/readonly --json > /tmp/aliyun-readonly.json
vault credential show aliyun-readonly --unmask --json > /tmp/aliyun-readonly-cred.json
# （这些文件 chmod 600，临时用完 shred）
# 2. 反查引用方
vault who-uses aliyun-readonly
# 3. 删
vault credential rm aliyun-readonly
vault account rm aliyun/readonly
# 4. 校验自洽
vault check
9. 给新项目接入 vault¶
cd ~/newproject
vault init
$EDITOR vault.json # 声明要哪些 credentials + resources
vault install # 生成 .vault/secrets.json + .env
代码里读（无 SDK）：
import json
secrets = json.loads(open(".vault/secrets.json").read())
aliyun_ak = secrets["aliyun"]["access_key_id"]
完整示例见 项目接入。
10. 发现 data/ 有漂移（新改了但没 commit）¶
cd ~/vault
git status -- data/
# 看哪些文件变了
git diff -- data/
# 看具体改了啥（git-crypt 下应该显示明文 diff）
# 确认 OK 就 commit
git add data/
git commit -m "..."
git push
11. CI 挂了，怎么看¶
gh run list --limit 3
gh run view <ID> --log-failed | grep -iE "error|fail" | head
# 或者直接在浏览器
gh run view <ID> --web
详见 运维。