using-sops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using sops

使用sops

Repositories that use this layout commit their secrets to git as sops-encrypted dotenv files, one per deployment environment:

secrets/dev.env

secrets/prod.env

. The files decrypt with age identities. There is no

.env

, no secrets service, and no session to log in to. Every checkout, worktree, and cloud sandbox has the encrypted files at clone; the only input anywhere is an age private key.

pnpm secrets

(

tools/secrets.ts

) is the only interface. Do not call

sops

directly in a repo that has the wrapper.

采用此结构的仓库会将密钥以sops加密的dotenv文件形式提交至Git，每个部署环境对应一个文件：

secrets/dev.env

、

secrets/prod.env

。这些文件通过age身份进行解密。无需

.env

文件、密钥服务，也无需登录会话。每次克隆代码时，所有检出目录、工作树和云沙箱都会包含加密文件；唯一需要输入的内容就是age私钥。

pnpm secrets

（

tools/secrets.ts

）是唯一的操作接口。在包含该封装脚本的仓库中，请勿直接调用

sops

命令。

Identities

身份标识

Identity	Scope	Where the private key lives	Decrypts
`agent`	user-wide	`~/.config/sops/age/keys.txt` on every machine agents run on; `SOPS_AGE_KEY` in cloud sandboxes	`dev.env`
`personal`	user-wide	the user's password manager	every file
`prod`	per project	that project's production platform only	`prod.env`

.sops.yaml

lists recipients by public key. Encrypting needs no private key; decrypting or editing needs one recipient's private key.

agent

and

personal

are local-development keys shared by every project;

prod

is minted per project so one leaked deploy variable exposes one project.

身份标识	适用范围	私钥存储位置	可解密文件
`agent`	全局用户级	所有运行agent的机器上的 `~/.config/sops/age/keys.txt` ；云沙箱中的 `SOPS_AGE_KEY` 环境变量	`dev.env`
`personal`	全局用户级	用户的密码管理器	所有文件
`prod`	项目级	仅对应项目的生产平台	`prod.env`

.sops.yaml

文件通过公钥列出接收方。加密操作无需私钥；解密或编辑操作需要其中一个接收方的私钥。

agent

和

personal

是所有项目共享的本地开发密钥；

prod

密钥为每个项目单独生成，这样即使某个部署变量泄露，也只会影响一个项目。

Agent workflow

Agent工作流

Dev secrets are yours to manage without asking:

pnpm secrets show dev                    # everything, decrypted
pnpm secrets get dev STRIPE_KEY
pnpm secrets set dev STRIPE_KEY sk_test_1
pnpm secrets unset dev STRIPE_KEY
pnpm secrets exec dev -- node apps/worker/src/main.ts

exec

puts the decrypted values in the child's environment (over the shell's), removes

SOPS_AGE_KEY*

from it, forwards signals, and exits with the child's status.

Prod secrets need elevation. When a task requires reading or writing

prod.env

Check for
```
.age/elevated
```
in this checkout. If present, prod commands work; carry on.
If absent, ask the user to run, in a terminal of their own:
```
op read 'op://Personal/age-personal/private key' | pnpm secrets elevate
```
(or however their password manager prints the key). Say why you need it.
Elevation is per checkout and lasts until
```
.age/elevated
```
is deleted. Do not copy it into another worktree.

When you add a variable, add it to the env schema and to every

secrets/<env>.env

you can decrypt. If you cannot decrypt prod, say so in the PR: the typed env check fails the prod boot until the value is set, which is the intended signal.

Never write an

AGE-SECRET-KEY-...

into a tracked file, a log, or a commit. Never put

personal

prod

in a cloud environment.

开发环境密钥可自行管理，无需申请：

pnpm secrets show dev                    # 解密并显示所有密钥
pnpm secrets get dev STRIPE_KEY
pnpm secrets set dev STRIPE_KEY sk_test_1
pnpm secrets unset dev STRIPE_KEY
pnpm secrets exec dev -- node apps/worker/src/main.ts

exec

命令会将解密后的值注入子进程的环境变量中（覆盖Shell环境变量），移除其中的

SOPS_AGE_KEY*

变量，转发信号，并以子进程的状态码退出。

生产环境密钥需要权限提升。当任务需要读取或写入

prod.env

时：

检查当前检出目录中是否存在
```
.age/elevated
```
文件。如果存在，生产环境相关命令可正常执行；继续操作即可。
如果不存在，请让用户在自己的终端中运行以下命令：
```
op read 'op://Personal/age-personal/private key' | pnpm secrets elevate
```
（或使用其密码管理器输出私钥的其他方式）。同时说明需要权限的原因。
权限提升仅对当前检出目录有效，直到
```
.age/elevated
```
文件被删除。请勿将该文件复制到其他工作树中。

添加变量时，请将其添加到环境变量 schema 中，以及所有你能解密的

secrets/<env>.env

文件中。如果你无法解密生产环境文件，请在PR中说明：类型化环境检查会导致生产环境启动失败，直到变量被设置，这是预期的提示信号。

切勿将

AGE-SECRET-KEY-...

写入已追踪的文件、日志或提交记录中。切勿将

personal

或

prod

密钥放入云环境中。

Human setup

人工配置

For the one-time steps (generating keys, installing

sops

and

age

, wiring the

agent

key into agent tools and cloud sandboxes, configuring the prod platform, and rotating keys), read

references/setup.md

. When the user asks to be reminded of the steps, walk them through that file in order.

For the sops and age behavior the design relies on (identity union,

updatekeys

exec-env

limitations, dotenv quirks), read

references/sops-notes.md

关于一次性配置步骤（生成密钥、安装

sops

和

age

工具、将

agent

密钥接入agent工具和云沙箱、配置生产平台以及密钥轮换），请阅读

references/setup.md

文件。当用户需要提醒配置步骤时，请引导他们按顺序阅读该文件。

关于本设计所依赖的sops和age特性（身份联合、

updatekeys

、

exec-env

限制、dotenv特性），请阅读

references/sops-notes.md

文件。