设计¶
为什么要做 vault¶
凭证 / 证件 / 资源台账散落各处的问题：
- AK / API Key 硬编在代码里 → 仓库泄漏风险
- 同一把 AK 在多个项目里重复配 → 轮换时要改 N 处
- 身份证 / 营业执照 / 合同 PDF 散在各处 → 丢了不知道
- 资源（ECS / OSS / 域名）没统一台账 → 到期了才想起来
vault 把这些全部收进一个加密仓库（git-crypt），CLI + 声明式依赖统一管。
5 层抽象¶
Person (人 / 法人) ← 根
↓ has identity at
Platform (厂商 / 政府 / 银行 / self)
↓
Account (此 person 在此 platform 下的户头)
├── Credential (钥匙)
└── Resource (东西)
└── Attachments (文件字节)
每层一句话定义¶
| 层 | 定义 | 关键字段 | 不存什么 |
|---|---|---|---|
| Person | 一个自然人或法人 | slug, kind, relationship, names | 关系事实（进 knowledge-graph） |
| Platform | 一个来源 / 颁发方 / 托管方 | slug, name, category | 账号 / 钥匙 / 资源 |
| Account | 某 person 在某 platform 下的身份 | slug=<platform>/<name>, owner_ref, kind |
钥匙的值 |
| Credential | 某 account 当前有效的一把钥匙 | slug, account_ref, kind, values | 户头元信息 |
| Resource | 某 account 名下的一个具体东西 | ref=<platform>/<type>/<id>, account_ref, spec, attachments |
钥匙 |
关系自洽约束¶
credential → account（钥匙属于谁的户头）resource → account（东西算谁的账）account → person（户头是谁开的）account → platform（户头在哪家）resource ❌ credential—— 资源不直接指钥匙- 只有单向下行引用，无反向环
Person 的两种使用姿势¶
核心人物（self / 配偶 / 合伙人 / 员工 / 子女）—— 下面完整展开 platform/account/credential/resource。
边缘联系人（朋友 / 客户 / 一次性接触）—— 只存 person 节点 + 扁平属性（phone / email / birthday / notes），不展开下层。
// 核心人物
{
"slug": "wife-lin",
"kind": "natural_person",
"relationship": "spouse",
"names": { "legal": "林某某", "alias": ["老婆"] },
"birth_date": "1990-xx-xx"
}
// 边缘联系人
{
"slug": "friend-wang",
"kind": "natural_person",
"relationship": "friend",
"names": { "legal": "王某" },
"phone": "138xxxx",
"email": "wang@..."
}
self 约定¶
self 是保留 slug，指向 vault 持有者本人。所有 account 的 owner_ref: "self"。
Platform 语义¶
Platform 不限于"商业厂商"，涵盖任何颁发方 / 托管方 / 来源：
| category | 前缀约定 | 例子 |
|---|---|---|
| vendor | 无（裸名） | aliyun / alipay / aws-cloud / pypi |
| government | gov-* |
gov-cn（户籍） / gov-cn-exit-entry / gov-cn-amr / gov-us-wyoming-sos |
| bank | bank-* 或裸名 |
icbc / cmb / ccb |
| education | edu-* |
edu-... |
| certification | cert-* |
cert-... |
| self | self |
自持合同 / 自签文件 |
抽象闭环验证¶
| 场景 | Person | Platform | Account | 产物 |
|---|---|---|---|---|
| 我的阿里云 AK | self | aliyun | aliyun/main | credential |
| 老婆的身份证 | wife-lin | gov-cn | gov-cn/citizen-wife-lin | resource(id-card) + 附件 |
| 合伙人电话 | partner-zhang | —— | —— | person.phone 字段 |
| 公司营业执照 | company-hangzhou-akong | gov-cn-amr | gov-cn-amr/company-hangzhou-akong | resource(business-license) |
| U 盾 | self | icbc | icbc/company-main | credential(kind=hardware_token) |
| 我的婚姻关系 | —— | —— | —— | 不进 vault，进 knowledge-graph |
vault vs knowledge-graph 的边界¶
- vault：装人 + 人名下的东西（身份、钥匙、资源、文件）
- knowledge-graph：装概念 / 决策 / 关系 / 学到的东西
重叠区在"关系"：
- A 拥有 B（所有权）→ vault（通过 owner_ref）
- A 和 B 的非所有权关系（夫妻、合伙、同学、债权债务）→ knowledge-graph 的边
故意不做¶
- lock 文件 + revision —— vault 只存当前值，覆盖式刷新。没遇到"想查历史值"的痛点。加字段不难，等真要再加。
- 操作日志 —— 同上，YAGNI。
- SDK —— 消费方代码直接读
.vault/secrets.json或.env。跨语言、零依赖。 - 资源 → 凭证直接引用 —— 资源归账号（钱由账号付），不直接绑钥匙。一个账号可能同时有多把钥匙（主 AK + RAM 子账号 + STS），哪把都能访问它名下的资源。