# 客户的 Vault 还没到位，带机密的仓库照样能交接

> SOPS 只加密值，git diff 依然可读，解密用的 age 密钥留在客户手里。

原文: https://fdetimes.net/zh/tools/sops-age-secrets-repo-handover/

项目进入最后一周。仓库能跑，流水线全绿，只剩一个问题卡着交接：数据库密码和 API 密钥放在哪里？客户说 Vault “下个季度”再搭。仓库里不能留明文 `.env` 文件，机密也不能通过聊天工具发送。

SOPS 和 age 能干净利落地解决这个问题。SOPS 是一款加密文件编辑器，支持 YAML、JSON、ENV、INI 和二进制文件。

它可以借助 AWS KMS、GCP KMS、Azure Key Vault、HuaweiCloud KMS、PGP 和 age 加密。选择 age，就能绕开所有外部密钥管理服务，包括客户还没有的那套 Vault。

对前线部署工程师（FDE）来说，这就是“交接完成”和“等客户准备好再交接”的区别。机密以加密形式随仓库一起交付，只有持有密钥的人才能读取。

## 两个工具，各管什么？

客户的安全团队问这些工具是否可信时，答案是现成的：SOPS 于 2015 年诞生于 Mozilla，2023 年作为 Sandbox 项目捐赠给云原生计算基金会（CNCF），采用 MPL-2.0 许可证。

age 由 Filippo Valsorda 和 benjojo 设计，既是文件加密工具，也是一种格式和一个 Go 库。它的理念是：密钥短小且显式，没有配置选项，遵循 UNIX 式的可组合性。对负责交接的人来说，“没有选项”本身就是优点：不存在的东西，客户也就无从配错。

分工很清楚。age 负责密码学部分。SOPS 理解文件结构：哪些是键，哪些是值，哪些值需要隐藏。

## 加密值，而不是整个文件

SOPS 与整文件加密的不同之处在于，它只加密叶子值（即没有子节点的值），键名保持明文。设想一个四行的 `config/prod.yaml`：

```yaml
db_host: db.internal
db_port: 5432
db_password: s3cret-pass
openai_api_key: sk-xxxx
```

加密之前，需要拿到解密方的公钥。SOPS 接受 SSH 公钥作为 age 接收方，所以最简单的做法是向客户的运维工程师要一份他们已在使用的 SSH 公钥。

对应的私钥从不离开他们的机器，也不会进入仓库。私钥照旧放在他们平时存放 SSH 密钥的地方，你只需要公钥那一半。

拿到公钥后，加密只需一个 `--age` 参数，无需任何服务器（多个接收方用逗号分隔，也可以写在 `SOPS_AGE_RECIPIENTS` 变量里）：

```bash
sops -e --age <client-public-key>,<your-public-key> \
  --encrypted-regex '^(db_password|openai_api_key)$' \
  config/prod.yaml > config/prod.enc.yaml
```

有了 `encrypted_regex`，只有匹配正则的键会被加密。结果大致如下，`ENC[...]` 代表缩略后的密文：

```yaml
db_host: db.internal
db_port: 5432
db_password: ENC[...]
openai_api_key: ENC[...]
```

持有对应私钥的人运行 `sops -d config/prod.enc.yaml` 即可还原明文。客户的工程师没有密钥也能读到主机和端口，方便排查问题。每次修改端口，git diff 都会指向 `db_port` 这一行，而不像整文件加密那样给出一大段无意义的字符。

**要点:** 只加密值、保留明文键名：diff 依然可读，机密依然封存。

SOPS 还会对所有值计算一个消息认证码（MAC），用来发现未经授权新增或删除的值。这样，没有密钥的人很难悄悄在加密文件里插入或删除某个值。但已经持有密钥的人仍然可以重新加密文件，所以真正要严格把守的是接收方列表。

## 一份够交接用的 .sops.yaml

为了不让任何人去记参数，把规则写进仓库根目录的 `.sops.yaml`：

```yaml
creation_rules:
  - path_regex: config/prod/.*\.yaml$
    encrypted_regex: '^(db_password|openai_api_key)$'
    age: <client-ops-lead-key>,<your-key>
  - path_regex: .*\.yaml$
    encrypted_regex: '^(db_password|openai_api_key)$'
    age: <whole-dev-team-key>
```

关键在顺序。规则逐条检查，第一条命中即生效。如果把通用的 `.*\.yaml$` 规则放在前面，prod 文件也会匹配它，生产环境的机密就会为整个开发团队加密，这恰恰是要避免的。具体规则永远放在最上面。

## 需要向客户讲清的限制

正则只能保护它认识的名字。如果半年后有人新增了一个 `db_pass` 键，而正则只匹配 `db_password`，这个值就会以明文留在仓库里。交接前，要么换成更宽泛的模式，要么在 README 中写明命名约定。

其次是 git 历史。即使把某位前接收方的密钥从 `.sops.yaml` 中移除，对方仍能解密旧的提交。撤销某人的访问权限，实际意味着更换机密本身，而不只是重新加密文件。交接当天的最后一步，应该是把自己的密钥从列表中移除，再由客户轮换机密。

另外，由于没有中心服务器，也就没有谁读过哪个机密的日志。如果客户需要这一点，Vault 或 KMS 仍是最终目的地，SOPS 只是通往那里的桥梁。

## 先学什么，简历上写什么

先热身：用自己的 SSH 密钥加密一个 YAML 文件，改一个值，看看 diff。然后写一份多环境的 `.sops.yaml`。整个过程一个晚上就够。

简历上不要泛泛写“机密管理”，而是写“使用 SOPS 和 age 加密机密并交接仓库，解密密钥由客户自行持有”。这句话说明你考虑的是客户独立运行系统的那一天，而不只是演示那一天。

好的项目，结束于客户无需再给你打电话就能自己运维。一份顺序正确的 `.sops.yaml`，在这件事上比任何冗长的交接文档都管用。

**本周动手试试:**

- 从副业项目里找一个带机密的配置文件，以自己的 SSH 公钥作为 age 接收方，用 SOPS 加密后提交，再改一个值，看看 git diff。
- 写一份包含两条规则（prod 和默认）的 .sops.yaml，然后故意调换顺序，观察 prod 文件被加密给了错误的人。
- 新增一个不匹配 encrypted_regex 的键 db_pass，检查它是否以明文暴露。

## 信源

- [getsops/sops (GitHub)](https://github.com/getsops/sops)

- [SOPS: Secrets OPerationS (getsops.io docs)](https://getsops.io/docs/)

- [sops | CNCF](https://www.cncf.io/projects/sops/)

- [FiloSottile/age (GitHub)](https://github.com/FiloSottile/age)

- [Age (SOPS docs)](https://getsops.io/docs/usage/identities/age/)

- [Config file (SOPS docs)](https://getsops.io/docs/usage/identities/config-file/)

- [Reference (SOPS docs)](https://getsops.io/docs/reference/)
