📚 课程目录第3章 Secrets模型定义

Secrets模型定义：名称、类型、值、元数据

好，我们开始第三章节。上一章聊了为什么需要统一的Secrets接口规范，这一章咱们直接切入核心——Secrets模型到底长什么样。

我个人习惯把Secrets看成一个小型数据包：它要有名字、有类型、有真正的秘密值，还得附带一堆元数据。你想想看，如果没有这个模型，大家各自按自己理解存密码、存密钥、存证书……最后就是一团乱麻。我曾在一个微服务项目里见过五种不同的Secrets存储格式，光解析就让人头大。

那么标准模型应该包含哪几样？说白了就四个要素：名称、类型、值、元数据。下面我们逐个拆解。

名称（Name）—— 给你的秘密起个好名字

名字看着简单，但我在项目中见过的教训可不少。有的团队用 password123 这种带数字的，有的用中文拼音，还有的直接空着……后来排查问题的时候，谁都不知道这个 a1b2c3 到底是干嘛的密钥。

我建议的命名规范是：

全小写，用下划线分隔（snake_case）。比如 db_master_password、jwt_signing_key。
避免特殊字符，特别是空格、点（.）、中划线（-）在某些后端存储里会被转义。
带上业务上下文：尽量体现环境（prod/staging）、资源（db/api/cert）和用途（password/key/）。

✅ 推荐命名	❌ 不推荐命名
`production_db_password`	`pass123`（无上下文）
`staging_api__v2`	`api--v2`（中划线）
`app_certificate_pem`	`cert.pem`（点）

个人小技巧：我在团队里推行过一个“名称模板”工具，自动根据环境+资源+用途生成名字，大家不用再自己编了。上线后几乎没再出现过重名或歧义的问题。

类型（Type）—— 别什么都当字符串存

很多新手直接把密钥存成 string 类型，但不同类型的数据需要不同的处理方式。比如 JSON 类型的Secrets 需要解析验证层级，证书类型 需要包含有效期检查，keypair 得同时保存公钥私钥。

我推荐的标准类型枚举：

类型	用途	注意事项
`string`	普通密码、	长度限制？是否需 URL 编码？
`bytes`	二进制密钥、证书 DER	Base64 编码后再存储
`json`	多字段结构（如数据库连接串）	存储前验证 JSON 合法性
`keypair`	RSA/EC 密钥对	公钥和私钥分开字段
`certificate`	X.509 证书（含链）	额外元数据：签发者、有效期
`opaque`	不透明二进制 blob	仅需加解密，不关注内容

为什么要区分类型？我曾经遇到一个坑：某服务把 PEM 格式的证书当 string 存，结果换行符被自动替换了，导致证书解析失败。后来我们加了类型检查，对 certificate 类型强制保留原始 Base64 编码，问题才解决。

值（Value）—— 核心秘密怎么存？

值本身是最敏感的部分。在接口规范里，我们需要定义清楚：值到底存明文还是密文？我见过两种模式：

明文模式：Secrets 值以明文形式写入 API 请求，由服务端负责加密存储。适合运维人员直接查看的场景。
密文模式：客户端用服务端公钥加密后提交，服务端存密文。适合敏感环境，比如 CI/CD 流水线。

我的建议：接口规范里必须明确声明当前请求使用的是哪种模式。可以在元数据里加一个字段 encryption: "plain" | "encrypted"。这样接收方可以做出相应处理。

另外值的长度限制也需要定义。我习惯设一个默认上限（比如 10 KB），但允许通过元数据覆盖。你总不想让一个几百兆的证书文件把 API 撑爆吧。

元数据（Meta）—— 让秘密有“身份信息”

元数据是我认为最容易被人忽略但最有价值的部分。一个 Secrets 模型除了名称、类型、值之外，还应该附带：

版本号：每次更新自动递增，方便回滚。
创建时间 / 更新时间：ISO8601 格式。
过期时间：可以自动轮换，提升安全性。
标签（Tags）：用于分类和搜索，比如 ["db", "prod"]。
访问权限：哪些服务或用户可读/可写。
描述：不超过 200 字的用途说明。

我看过一个真实的线上事故：某个过期后没人通知，导致线上服务中断 3 小时。原因就是元数据里没记录过期时间，运维完全不知道什么时候过期。后来我们在规范里强制加上了 expires_at 字段，到期前自动发告警。

注意！元数据本身也可能包含敏感信息（比如访问权限里列出了服务名）。我建议在传输元数据时至少使用 TLS，不要在日志或监控系统里明文打印。

一个完整的 Secrets 模型示例

我们把上面说的整合成一个 JSON 示例，方便你直接在项目里参考：

{
  "name": "production_db_master_password",
  "type": "string",
  "value": "s3cr3tPa$$w0rd",
  "meta": {
    "version": 1,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "expires_at": "2025-07-15T10:30:00Z",
    "tags": ["db", "production", "mysql"],
    "access": {
      "read": ["db-service", "ops-tool"],
      "write": ["admin-console"]
    },
    "description": "生产数据库 MySQL 的 root 密码",
    "encryption": "plain"
  }
}

嗯，这里需要强调：接口规范里字段名的大小写要保持一致。我统一用小写蛇形，因为很多语言的 SDK 能直接反序列化，少出兼容性问题。

避坑指南

最后分享几个我踩过的坑：

不要把敏感信息写在名称里（比如 password_admin 暴露了角色）
类型 json 的 value 在传输时必须压缩成一行，否则某些 HTTP 框架会截断
元数据里的 expires_at 建议用 UTC 时间，避免时区混乱
名称长度最好限制在 128 字符以内，部分存储后端对键名有长度限制