onepassword-cli-coder

核心模式

密钥引用格式

op://<vault>/<item>/<field>

示例：

op://Development/AWS/access_key_id
op://Production/Database/password
op://Shared/Stripe/secret_key

条目命名约定

格式：{environment}-{service}，采用 kebab-case。每个环境使用一个条目。

模式	示例	不佳的替代写法
{env}-{service}	production-rails	Production Rails
{env}-{provider}	production-dockerhub	API Key
{env}-{provider}-{resource}	production-hetzner-s3	混合环境条目

字段命名

使用能描述凭据类型的语义化字段名：

推荐	不推荐	原因
access_token	value	可自行说明用途
master_key	secret	用途明确具体
secret_access_key	key	与 AWS 命名一致
api_token	token	与其他令牌区分

字段命名规则：

• 尽可能与提供商的术语保持一致（AWS 使用 access_key_id、secret_access_key）
• 统一使用 snake_case
• 命名要具体：当条目包含多个凭据时，使用 database_password，而不只是 password

环境文件（.op.env）

在项目根目录中创建 .op.env：

AWS_ACCESS_KEY_ID=op://Infrastructure/AWS/access_key_id
AWS_SECRET_ACCESS_KEY=op://Infrastructure/AWS/secret_access_key
DIGITALOCEAN_TOKEN=op://Infrastructure/DigitalOcean/api_token
DATABASE_URL=op://Production/PostgreSQL/connection_string
STRIPE_SECRET_KEY=op://Production/Stripe/secret_key

重要： 将其添加到 .gitignore：

# 1Password - NEVER commit
.op.env
*.op.env

使用密钥运行命令

op run --env-file=.op.env -- terraform plan
op run --env-file=.op.env -- rails server

集成模式

Makefile 集成

OP ?= op
OP_ENV_FILE ?= .op.env

# Prefix for all commands needing secrets
CMD = $(OP) run --env-file=$(OP_ENV_FILE) --

deploy:
	$(CMD) kamal deploy

console:
	$(CMD) rails console

migrate:
	$(CMD) rails db:migrate

Docker Compose

op run --env-file=.op.env -- docker compose up

Kamal 部署

# config/deploy.yml
env:
  secret:
    - RAILS_MASTER_KEY
    - DATABASE_URL
    - REDIS_URL

# .kamal/secrets
RAILS_MASTER_KEY=$(op read "op://Production/Rails/master_key")
DATABASE_URL=$(op read "op://Production/PostgreSQL/url")
REDIS_URL=$(op read "op://Production/Redis/url")

CI/CD（GitHub Actions）

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          AWS_ACCESS_KEY_ID: op://CI/AWS/access_key_id
          AWS_SECRET_ACCESS_KEY: op://CI/AWS/secret_access_key

      - run: terraform apply -auto-approve

CLI 命令

读取密钥

op read "op://Vault/Item/field"
op read "op://Vault/Item/field" --format json
op read "op://Vault/TLS/private_key" > /tmp/key.pem && chmod 600 /tmp/key.pem

注入到命令中

DATABASE_URL=$(op read "op://Production/DB/url") rails db:migrate
op run --env-file=.op.env -- ./deploy.sh
op run --account my-team --env-file=.op.env -- terraform apply

管理条目

op vault list
op item list --vault Infrastructure
op item get "AWS" --vault Infrastructure
op item create --category login --vault Infrastructure \
  --title "New Service" --field username=admin --field password=secret123

项目设置

初始配置

op signin
op vault list

cat > .op.env << 'EOF'
AWS_ACCESS_KEY_ID=op://Infrastructure/AWS/access_key_id
AWS_SECRET_ACCESS_KEY=op://Infrastructure/AWS/secret_access_key
DATABASE_URL=op://Production/Database/url
REDIS_URL=op://Production/Redis/url
EOF

op run --env-file=.op.env -- env | grep -E '^(AWS|DATABASE|REDIS)'

占位符工作流

先使用占位值创建条目，之后再填入真实凭据：

op item create --vault myproject --category login \
  --title "production-rails" --field master_key="PLACEHOLDER_UPDATE_BEFORE_DEPLOY"

cat > .kamal/secrets << 'EOF'
RAILS_MASTER_KEY=$(op read "op://myproject/production-rails/master_key")
EOF

# Later: update with real value
op item edit "production-rails" --vault myproject \
  master_key="actual_secret_value_here"

保管库组织方式

单保管库方案（更简单）

使用单个保管库，并通过命名约定区分环境：

Vault: myproject
Items:
  - production-rails
  - production-dockerhub
  - production-hetzner-s3
  - staging-rails
  - staging-dockerhub
  - development-rails

多保管库方案（团队规模）——当团队需要不同的访问控制时使用：

保管库	用途	访问权限
Infrastructure	云提供商凭据	DevOps 团队
Production	生产环境应用密钥	部署系统
Staging	预发布环境	开发团队
Development	本地开发密钥	个人开发者

安全规则

• 将 .op.env 和 *.op.env 添加到 .gitignore——切勿提交
• CI/CD 使用服务账户，而非个人账户
• 切勿将 op read 的输出管道传给日志或 echo
• 切勿在脚本中存储会话令牌
• 在自动化中使用变量表示保管库和条目名称

故障排除

op signin                  # Re-authenticate expired session
op whoami                  # Check current session
op vault list              # Verify vault access
op item list --vault Infrastructure | grep -i aws   # Search for items
op item get "AWS" --vault Infrastructure --format json | jq '.fields[].label'  # Check field names

多账户

在自动化中始终指定账户——切勿依赖“上次登录的账户”：

op vault list --account acme.1password.com
export OP_ACCOUNT=acme.1password.com
op run --account acme.1password.com --env-file=.op.env -- ./deploy.sh

多环境模式

按环境使用独立的环境文件：.op.env.production、.op.env.staging、.op.env.development

ENV ?= development
OP_ENV_FILE = .op.env.$(ENV)

deploy:
	op run --env-file=$(OP_ENV_FILE) -- kamal deploy
# Usage: make deploy ENV=production

参考资料

• references/multiple-accounts.md - 跨账户工作流和 Makefile 集成