sops-age-secrets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SOPS + age Secrets Management

SOPS + age 密钥管理

Encrypt secrets in git with SOPS using age keys. Values are encrypted with AES256-GCM; keys are simple X25519 keypairs.

使用age密钥通过SOPS加密git中的密钥。数值采用AES256-GCM加密；密钥为简单的X25519密钥对。

Quick Reference

快速参考

Task	Command
Generate age key	`age-keygen -o keys.txt`
Extract public key	`age-keygen -y keys.txt`
Encrypt file	`sops encrypt file.yaml > file.enc.yaml`
Decrypt file	`sops decrypt file.enc.yaml`
Edit encrypted file	`sops edit file.enc.yaml`
Update recipients	`sops updatekeys -y file.enc.yaml`
Rotate data key	`sops rotate -i file.enc.yaml`

任务	命令
生成age密钥	`age-keygen -o keys.txt`
提取公钥	`age-keygen -y keys.txt`
加密文件	`sops encrypt file.yaml > file.enc.yaml`
解密文件	`sops decrypt file.enc.yaml`
编辑加密文件	`sops edit file.enc.yaml`
更新接收方	`sops updatekeys -y file.enc.yaml`
轮换数据密钥	`sops rotate -i file.enc.yaml`

Initial Setup

初始设置

1. Generate Keys

1. 生成密钥

bash

undefined

bash

undefined

Create key directory

创建密钥目录

mkdir -p ~/.config/sops/age

Generate keypair

生成密钥对

age-keygen -o ~/.config/sops/age/keys.txt

Output: public key: age1abc123...

输出: public key: age1abc123...

undefined

undefined

2. Create .sops.yaml

2. 创建.sops.yaml

At repository root:

yaml

creation_rules:
  - age: age1yourpublickeyhere...

在仓库根目录下创建：

yaml

creation_rules:
  - age: age1yourpublickeyhere...

3. Encrypt First File

3. 加密第一个文件

bash

sops encrypt config/secrets.yaml > config/secrets.enc.yaml
rm config/secrets.yaml
git add config/secrets.enc.yaml .sops.yaml

bash

sops encrypt config/secrets.yaml > config/secrets.enc.yaml
rm config/secrets.yaml
git add config/secrets.enc.yaml .sops.yaml

Core Workflows

核心工作流

Encrypt New File

加密新文件

bash

undefined

bash

undefined

Create plaintext file

创建明文文件

cat > secrets.yaml << 'EOF' database: password: secret123 api_key: abc-xyz EOF

Encrypt (uses .sops.yaml rules)

加密（使用.sops.yaml中的规则）

sops encrypt secrets.yaml > secrets.enc.yaml rm secrets.yaml

undefined

sops encrypt secrets.yaml > secrets.enc.yaml rm secrets.yaml

undefined

Edit Encrypted File

编辑加密文件

bash

undefined

bash

undefined

Opens decrypted in $EDITOR, re-encrypts on save

在$EDITOR中打开解密后的内容，保存时自动重新加密

sops edit secrets.enc.yaml

undefined

sops edit secrets.enc.yaml

undefined

Decrypt for Use

解密使用

bash

undefined

bash

undefined

To stdout

输出到标准输出

sops decrypt secrets.enc.yaml

To file

输出到文件

sops decrypt secrets.enc.yaml > secrets.yaml

Extract single value

提取单个值

sops decrypt --extract '["database"]["password"]' secrets.enc.yaml

undefined

sops decrypt --extract '["database"]["password"]' secrets.enc.yaml

undefined

Pass to Process (No File)

传递给进程（不生成文件）

bash

undefined

bash

undefined

As environment variables

作为环境变量

sops exec-env secrets.enc.yaml './deploy.sh'

As temporary file

作为临时文件

sops exec-file secrets.enc.yaml 'source {}'

undefined

sops exec-file secrets.enc.yaml 'source {}'

undefined

Multi-Environment Configuration

多环境配置

yaml

undefined

yaml

undefined

.sops.yaml

creation_rules:

Production - admin + CI only

path_regex: ^config/secrets/prod..* age: >- age1admin..., age1cicd...

Staging/Dev - broader access

path_regex: ^config/secrets/.* age: >- age1admin..., age1cicd..., age1dev...

undefined

creation_rules:

生产环境 - 仅管理员和CI可访问

path_regex: ^config/secrets/prod..* age: >- age1admin..., age1cicd...

预发/开发环境 - 更广的访问权限

path_regex: ^config/secrets/.* age: >- age1admin..., age1cicd..., age1dev...

undefined

Selective Encryption

选择性加密

Only encrypt sensitive keys (keeps file readable):

yaml

creation_rules:
  - age: age1...
    encrypted_regex: ^(password|secret|token|key|api_key|private)$

Result:

yaml

database:
  host: localhost           # plaintext
  password: ENC[AES256_GCM,data:...,type:str]  # encrypted

仅加密敏感键（保持文件可读性）：

yaml

creation_rules:
  - age: age1...
    encrypted_regex: ^(password|secret|token|key|api_key|private)$

效果：

yaml

database:
  host: localhost           # 明文
  password: ENC[AES256_GCM,data:...,type:str]  # 加密

CI/CD Integration

CI/CD集成

GitHub Actions

yaml

- name: Decrypt secrets
  env:
    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
  run: sops decrypt config/secrets.enc.yaml > secrets.yaml

Store

AGE-SECRET-KEY-1...

in repository secrets as

SOPS_AGE_KEY

yaml

- name: Decrypt secrets
  env:
    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
  run: sops decrypt config/secrets.enc.yaml > secrets.yaml

将

AGE-SECRET-KEY-1...

作为

SOPS_AGE_KEY

存储在仓库密钥中。

Environment Variables

环境变量

bash

undefined

bash

undefined

Key file location

密钥文件路径

export SOPS_AGE_KEY_FILE=/path/to/keys.txt

Key value directly (CI/CD)

直接传入密钥值（适用于CI/CD）

export SOPS_AGE_KEY="AGE-SECRET-KEY-1..."

undefined

export SOPS_AGE_KEY="AGE-SECRET-KEY-1..."

undefined

Key Management

密钥管理

Add New Recipient

添加新接收方

Update
```
.sops.yaml
```
with new public key
Re-encrypt existing files:
bash
```
sops updatekeys -y file.enc.yaml
```

在
```
.sops.yaml
```
中添加新的公钥
重新加密现有文件：
bash
```
sops updatekeys -y file.enc.yaml
```

Remove Recipient

移除接收方

Remove from
```
.sops.yaml
```

Re-encrypt and rotate:

bash

sops updatekeys -y file.enc.yaml
sops rotate -i file.enc.yaml

从
```
.sops.yaml
```
中删除对应公钥

重新加密并轮换密钥：

bash

sops updatekeys -y file.enc.yaml
sops rotate -i file.enc.yaml

Key Locations

密钥默认路径

Platform	Default Path
Linux	`~/.config/sops/age/keys.txt`
macOS	`~/Library/Application Support/sops/age/keys.txt`

平台	默认路径
Linux	`~/.config/sops/age/keys.txt`
macOS	`~/Library/Application Support/sops/age/keys.txt`

Reference Files

参考文件

File	When to Read
age-keys.md	Key generation, storage, distribution patterns
sops-config.md	.sops.yaml syntax, path rules, key groups
cli-reference.md	Full command reference, all flags
ci-cd-patterns.md	GitHub Actions, GitLab CI, Docker integration
troubleshooting.md	Common errors and solutions

文件	适用场景
age-keys.md	密钥生成、存储、分发模式
sops-config.md	.sops.yaml语法、路径规则、密钥组
cli-reference.md	完整命令参考、所有参数
ci-cd-patterns.md	GitHub Actions、GitLab CI、Docker集成
troubleshooting.md	常见错误与解决方案

Common Issues

常见问题

Problem	Solution
"could not decrypt data key"	Wrong key - check `SOPS_AGE_KEY_FILE` or key location
"no matching keys found"	File uses Shamir key groups - need multiple keys
`.sops.yaml` not found	Run from repo root or ensure file is in parent directory
path_regex not matching	Use regex syntax ( `.\.yaml$` ), not glob ( `.yaml` )

问题	解决方案
"could not decrypt data key"	密钥错误 - 检查 `SOPS_AGE_KEY_FILE` 或密钥存储路径
"no matching keys found"	文件使用Shamir密钥组 - 需要多个密钥才能解密
未找到 `.sops.yaml`	从仓库根目录运行命令，或确保文件位于父目录中
path_regex不匹配	使用正则语法（ `.\.yaml$` ），而非通配符（ `.yaml` ）

Security Notes

安全注意事项

Never commit private keys - Add
```
keys.txt
```
,
```
*.agekey
```
to
```
.gitignore
```
Use dedicated CI keys - Easier to rotate, limit scope
Rotate data keys - Run
```
sops rotate
```
periodically
Limit recipients - Production files should have minimal access

绝对不要提交私钥 - 将
```
keys.txt
```
、
```
*.agekey
```
添加到
```
.gitignore
```
中
使用专用CI密钥 - 更易于轮换，权限范围更小
轮换数据密钥 - 定期执行
```
sops rotate
```
限制接收方范围 - 生产环境文件的可访问人员应尽可能少

Official Documentation

官方文档

Topic	URL
SOPS	https://getsops.io/docs/
SOPS GitHub	https://github.com/getsops/sops
age	https://github.com/FiloSottile/age

主题	URL
SOPS	https://getsops.io/docs/
SOPS GitHub	https://github.com/getsops/sops
age	https://github.com/FiloSottile/age