env-to-fnox

用途

env-to-fnox 用于将项目中的明文 .env 文件迁移到 fnox，并以 1Password（或其它秘密提供方）作为秘密存储后端。fnox 是提供方无关的工具，支持多种后端，包括 1Password、AWS Secrets Manager、Azure Key Vault、HashiCorp Vault 以及 age 加密等。

前置条件

开始前需要确认：

已安装 1Password CLI：op --version
已完成 1Password 认证：op vault list
已安装 mise（可选但推荐）：mise --version

迁移流程

第 1 步：分析现有 .env

读取现有 .env 文件，了解需要迁移哪些秘密：

cat .env

对秘密进行分类：

云服务商凭据（AWS_、ARM_、GOOGLE_*）
API 令牌（CLOUDFLARE_、GITHUB_ 等）
应用秘密（DATABASE_URL、API_KEY 等）
配置值（非秘密默认值，如区域）

第 2 步：安装 fnox

通过 mise 安装 fnox（推荐）：

mise use fnox

或添加到 mise.toml：

[tools]
fnox = "latest"

初始化 fnox 配置：

mise exec -- fnox init
mise exec -- fnox provider add op 1password

第 3 步：创建 1Password 条目

创建单个 1Password 条目来容纳所有秘密。可使用 API Credential 分类进行组织：

op item create \
  --category="API Credential" \
  --title="project-name" \
  --vault="Private" \
  'Field Name[text]=value' \
  'Secret Field[password]=secret-value'

字段命名约定：

使用描述性名称，如 "AWS Access Key ID" 而非 "aws_key"
非敏感值（ID、区域、邮箱）使用 [text]
敏感值（秘密、令牌、密钥）使用 [password]

典型项目示例：

op item create \
  --category="API Credential" \
  --title="myproject" \
  --vault="Private" \
  'AWS Access Key ID[text]=AKIA...' \
  'AWS Secret Access Key[password]=...' \
  'Database URL[password]=postgres://...' \
  'API Token[password]=...'

第 4 步：配置 fnox.toml

更新 fnox.toml 以引用 1Password 条目：

[providers.op]
type = "1password"
vault = "Private"

[secrets]
# 格式：ENV_VAR = { provider = "op", value = "item-title/Field Name" }
AWS_ACCESS_KEY_ID = { provider = "op", value = "myproject/AWS Access Key ID" }
AWS_SECRET_ACCESS_KEY = { provider = "op", value = "myproject/AWS Secret Access Key" }
DATABASE_URL = { provider = "op", value = "myproject/Database URL" }

# 非秘密默认值无需 1Password
AWS_DEFAULT_REGION = { default = "us-east-1" }

第 5 步：与 mise 集成

更新 mise.toml，使用 fnox 替代 .env：

[tools]
fnox = "latest"
# ... 其它工具

[env]
_.source = "fnox export"

移除旧的 .env 引用：

- _.file = ".env"
+ _.source = "fnox export"

第 6 步：验证与清理

测试配置：

# 列出已配置的秘密
mise exec -- fnox list

# 验证某个秘密可以取回
mise exec -- fnox get AWS_ACCESS_KEY_ID

# 测试完整环境
mise exec -- printenv | grep AWS_

验证通过后，删除旧的 .env 文件：

rm .env

提交 fnox.toml（不含秘密，只含引用）：

git add fnox.toml mise.toml
git commit -m "Migrate secrets from .env to fnox + 1Password"

fnox.toml 参考

提供方配置

# 1Password
[providers.op]
type = "1password"
vault = "Private"
# account = "my.1password.com"  # 可选：指定账户

# age 加密（用于存于 git 的加密秘密）
[providers.age]
type = "age"
recipients = ["age1..."]

# AWS Secrets Manager
[providers.aws]
type = "aws-sm"
region = "us-east-1"
prefix = "myapp/"

秘密引用格式

[secrets]
# 1Password：item-title/field-name
SECRET = { provider = "op", value = "myproject/Secret Field" }

# 1Password：完整 op:// URI
SECRET = { provider = "op", value = "op://Vault/Item/Field" }

# 默认值（无需提供方）
REGION = { default = "us-east-1" }

# age 加密值
SECRET = { provider = "age", value = "YWdlLWVu..." }

多环境 Profile

[providers.op]
type = "1password"
vault = "Development"

[secrets]
DATABASE_URL = { provider = "op", value = "dev-db/url" }

[profiles.production.providers.op]
vault = "Production"

[profiles.production.secrets]
DATABASE_URL = { provider = "op", value = "prod-db/url" }

使用方式：FNOX_PROFILE=production fnox export

故障排查

"No configuration file found"：运行 fnox init 创建 fnox.toml，或确认处于正确目录。
1Password 认证错误：确认已登录（op signin），或检查 1Password 设置 > 开发者中是否启用了 "Integrate with other apps"。
Shell 中秘密未加载：若使用 mise，确认已对项目目录运行 mise trust。
mise 安装后找不到 fnox 命令：使用 mise exec -- fnox，或重启 shell 以加载新的 PATH。

适用场景与限制

适用于把项目环境变量从明文 .env 迁移到集中式秘密管理的场景，迁移后提交的 fnox.toml 只包含引用，不包含秘密。资料未提供关于收费、价格、平台兼容性细节或使用效果的数据。