1password

1Password

概述

本技能全面介绍如何使用 1Password 的密钥管理生态系统，涵盖用于本地开发的 op CLI、用于自动化的服务账户、用于项目密钥的 Developer Environments，以及 Kubernetes 集成，包括原生的 1Password Operator 和 External Secrets Operator。

快速参考

命令结构

1Password CLI 使用名词-动词结构：op <noun> <verb> [flags]

# Authentication
op signin                    # Sign in to account
op signout                   # Sign out
op whoami                    # Show signed-in account info

# Secret retrieval
op read "op://vault/item/field"              # Read single secret
op run -- <command>                          # Inject secrets as env vars
op inject -i template.env -o .env            # Inject secrets into file

# Item management
op item list                                 # List all items
op item get <item>                           # Get item details
op item create --category login              # Create new item
op item edit <item> field=value              # Edit item
op item delete <item>                        # Delete item

# Vault management
op vault list                                # List vaults
op vault get <vault>                         # Get vault info
op vault create <name>                       # Create vault

# Document management
op document list                             # List documents
op document get <document>                   # Download document
op document create <file> --vault <vault>    # Upload document

工作流决策树

What do you need to do?
├── Retrieve a secret for local development?
│   └── Use: op read, op run, or op inject
├── Manage project environment variables?
│   └── See: Developer Environments (below)
├── Manage items/vaults in 1Password?
│   └── Use: op item, op vault, op document commands
├── Automate secrets in CI/CD?
│   └── Use: Service Accounts with OP_SERVICE_ACCOUNT_TOKEN
├── Sync secrets to Kubernetes?
│   ├── Using External Secrets Operator?
│   │   └── See: External Secrets Operator Integration
│   └── Using native 1Password Operator?
│       └── See: 1Password Kubernetes Operator
└── Configure shell plugins for CLI tools?
    └── Use: op plugin commands

Developer Environments

Developer Environments 提供专用位置，用于将项目密钥作为环境变量存储、整理和管理。CLI 工具提供 TypeScript/Bun 和 Python SDK 两种版本。

功能概览

功能	GUI	TypeScript CLI	Python SDK CLI
创建环境	是	bun run create	uv run op-env-create
更新环境	是	bun run update	uv run op-env-update
删除环境	是	bun run delete	uv run op-env-delete
显示环境	是	bun run show	uv run op-env-show
列出环境	是	bun run list	uv run op-env-list
导出到 .env	是	bun run export	uv run op-env-export
挂载 .env 文件	是（测试版）	否	否

CLI 工具设置（TypeScript）

这些工具使用 TypeScript 编写，需要 Bun 运行时：

# Navigate to tools directory
cd tools

# Run any tool with bun
bun run src/op-env-create.ts --help
bun run src/op-env-list.ts --help

# Or use npm scripts
bun run create -- --help
bun run list -- --help

CLI 工具设置（Python SDK）

Python 工具使用官方 onepassword-sdk 包，需要安装 uv：

# Navigate to tools-python directory
cd tools-python

# Install dependencies
uv sync

# Run any tool
uv run op-env-create --help
uv run op-env-list --help

要求： Python 3.9+、OP_SERVICE_ACCOUNT_TOKEN 环境变量。

何时使用 SDK 与 CLI

使用场景	推荐方案	原因
Python 应用（FastAPI、Django）	Python SDK	原生异步，无子进程开销
Shell 脚本、CI/CD 流水线	TypeScript CLI 或 op CLI	可直接集成 CLI
批量解析密钥	Python SDK	使用 resolve_all() 提高效率
基于标签筛选	TypeScript CLI	SDK 不支持标签筛选
交互式本地开发	二者皆可	两者的接口完全相同

SecretsManager（Python SDK）

适用于需要在运行时解析密钥的 Python 应用：

from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # Single secret (with caching)
    api_key = await sm.get("op://Production/API/key")

    # Batch resolve
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # Load all vars from an environment item
    env = await sm.resolve_environment("my-app-prod", "Production")

完整的 SDK 参考和集成模式，请参阅 references/python-sdk.md。

环境工作流

1. 创建环境

# From inline variables
bun run src/op-env-create.ts my-app-dev Personal \
    API_KEY=secret \
    DB_HOST=localhost \
    DB_PORT=5432

# From .env file
bun run src/op-env-create.ts my-app-prod Production --from-file .env.prod

# Combine file + inline (inline overrides file)
bun run src/op-env-create.ts azure-config Shared --from-file .env EXTRA_KEY=value

# With custom tags
bun run src/op-env-create.ts secrets DevOps --tags "env,production,api" KEY=value

2. 列出环境

# List all environments (tagged with 'environment')
bun run src/op-env-list.ts

# Filter by vault
bun run src/op-env-list.ts --vault Personal

# Filter by tags
bun run src/op-env-list.ts --tags "production"

# JSON output
bun run src/op-env-list.ts --json

3. 显示环境详情

# Show with masked values (default)
bun run src/op-env-show.ts my-app-dev Personal

# Show with revealed values
bun run src/op-env-show.ts my-app-dev Personal --reveal

# JSON output
bun run src/op-env-show.ts my-app-dev Personal --json

# Show only variable names
bun run src/op-env-show.ts my-app-dev Personal --keys

4. 更新环境

# Update/add single variable
bun run src/op-env-update.ts my-app-dev Personal API_KEY=new-key

# Merge from .env file
bun run src/op-env-update.ts my-app-dev Personal --from-file .env.local

# Remove variables
bun run src/op-env-update.ts my-app-dev Personal --remove OLD_KEY,DEPRECATED

# Update and remove in one command
bun run src/op-env-update.ts my-app-dev Personal NEW_KEY=value --remove OLD_KEY

5. 导出环境

# Export to .env file (standard format)
bun run src/op-env-export.ts my-app-dev Personal > .env

# Docker-compatible format (quoted values)
bun run src/op-env-export.ts my-app-dev Personal --format docker > .env

# op:// references template (for op run/inject)
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

# JSON format
bun run src/op-env-export.ts my-app-dev Personal --format json

# Add prefix to all variables
bun run src/op-env-export.ts azure-config Shared --prefix AZURE_ > .env

6. 删除环境

# Interactive deletion (asks for confirmation)
bun run src/op-env-delete.ts my-app-dev Personal

# Force delete without confirmation
bun run src/op-env-delete.ts my-app-dev Personal --force

# Archive instead of permanent delete
bun run src/op-env-delete.ts my-app-dev Personal --archive

环境密钥引用

使用密钥引用格式访问单个变量：

op://<vault>/<environment>/variables/<key>

示例：

# Read single variable
op read "op://Personal/my-app-dev/variables/API_KEY"

# Use in template file (.env.tpl)
API_KEY=op://Personal/my-app-dev/variables/API_KEY
DB_HOST=op://Personal/my-app-dev/variables/DB_HOST

集成模式

配合 op run 使用（推荐）

# 1. Export environment as op:// template
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

# 2. Run command with injected secrets
op run --env-file .env.tpl -- ./deploy.sh
op run --env-file .env.tpl -- docker compose up
op run --env-file .env.tpl -- npm start
op run --env-file .env.tpl -- python app.py

配合 op inject 使用

# 1. Create template with op:// references
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > config.tpl

# 2. Inject secrets into file
op inject -i config.tpl -o .env

# 3. Use the generated .env file
source .env && ./app

配合 Docker Compose 使用

# 1. Export environment
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

# 2. Run docker compose with secrets
op run --env-file .env.tpl -- docker compose up -d

在 CI/CD 中使用（GitHub Actions）

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          API_KEY: op://CI-CD/my-app-prod/variables/API_KEY
          DB_PASSWORD: op://CI-CD/my-app-prod/variables/DB_PASSWORD

      - name: Deploy
        run: ./deploy.sh

为环境命名

请根据 1Password Developer Environment 中存储的凭据用途为其命名，例如： <project>-azure-rg-<name>-dev、<team>-pim、<project>-github。请将环境的实际清单保存在被 git 忽略的本地笔记中，不要保存在已提交（且可能公开）的技能文件中。

密钥检索

密钥引用格式

引用密钥的标准格式：

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

示例：

• op://Development/AWS/access_key_id
• op://Production/Database/password
• op://Shared/API Keys/github_token

直接读取密钥

# Read a specific field
op read "op://Development/AWS/access_key_id"

# Read with JSON output
op item get "AWS" --vault Development --format json

# Read specific field from item
op item get "AWS" --vault Development --fields access_key_id

将密钥注入命令

op run 命令会将密钥注入为环境变量：

# Run command with secrets
op run --env-file=.env.tpl -- ./deploy.sh

# Example .env.tpl file:
# AWS_ACCESS_KEY_ID=op://Development/AWS/access_key_id
# AWS_SECRET_ACCESS_KEY=op://Development/AWS/secret_access_key

将密钥注入文件

op inject 命令会替换模板文件中的密钥引用：

# Inject secrets from template to output file
op inject -i config.tpl.yaml -o config.yaml

# Example config.tpl.yaml:
# database:
#   host: localhost
#   password: op://Production/Database/password

条目管理

创建条目

# Create a login item
op item create --category login \
  --title "My Service" \
  --vault Development \
  username=admin \
  password=secretpassword

# Create with generated password
op item create --category login \
  --title "New Account" \
  --generate-password

# Create from JSON template
op item create --template item.json

条目模板（JSON）

{
  "title": "my-service-credentials",
  "vault": {"id": "vault-uuid-or-name"},
  "category": "LOGIN",
  "fields": [
    {"label": "username", "value": "admin", "type": "STRING"},
    {"label": "password", "value": "secret", "type": "CONCEALED"},
    {"label": "api_key", "value": "key123", "type": "CONCEALED"}
  ]
}

编辑条目

# Edit a field
op item edit "My Service" password=newpassword

# Add a new field
op item edit "My Service" api_key=newkey

# Edit with specific vault
op item edit "My Service" --vault Development password=newpassword

服务账户

服务账户支持在不使用个人凭据的情况下进行自动化操作。

前提条件

• 1Password CLI 版本为 2.18.0 或更高版本
• 有效的 1Password 订阅
• 创建服务账户的管理员权限

创建服务账户

通过 CLI：

# Create with read-only access
op service-account create "CI/CD Pipeline" \
  --vault Production:read_items

# Create with write access
op service-account create "Deployment Bot" \
  --vault Production:read_items,write_items

# Create with vault creation permission
op service-account create "Provisioning Bot" \
  --vault Production:read_items,write_items \
  --can-create-vaults

使用服务账户

导出服务账户令牌：

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

然后使用常规 CLI 命令——它们会自动通过服务账户进行身份验证。

服务账户限制

• 无法访问 Personal、Private、Employee 或默认的 Shared 保管库
• 创建后无法修改权限
• 每个账户最多只能创建 100 个服务账户
• 受速率限制约束

CI/CD 集成

GitHub Actions

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        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-CD/AWS/access_key_id
          AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

      - name: Deploy
        run: ./deploy.sh

GitLab CI

deploy:
  image: 1password/op:2
  variables:
    OP_SERVICE_ACCOUNT_TOKEN: $OP_SERVICE_ACCOUNT_TOKEN
  script:
    - export AWS_ACCESS_KEY_ID=$(op read "op://CI-CD/AWS/access_key_id")
    - export AWS_SECRET_ACCESS_KEY=$(op read "op://CI-CD/AWS/secret_access_key")
    - ./deploy.sh

CircleCI

version: 2.1
orbs:
  onepassword: onepassword/secrets@1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - onepassword/exec:
          command: ./deploy.sh
          env:
            AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
            AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

External Secrets Operator 集成

External Secrets Operator（ESO）会将机密从 1Password 同步到 Kubernetes。

前提条件

1. 1Password Connect Server（v1.5.6+）
2. 凭据文件（1password-credentials.json）
3. 用于身份验证的访问令牌
4. 已在集群中安装 External Secrets Operator

Connect Server 设置

# Create automation environment and get credentials
# This generates 1password-credentials.json and an access token

# Create Kubernetes secret for Connect Server credentials
kubectl create secret generic onepassword-credentials \
  --from-file=1password-credentials.json

# Create secret for access token
kubectl create secret generic onepassword-token \
  --from-literal=token=your-access-token

部署 Connect Server

apiVersion: apps/v1
kind: Deployment
metadata:
  name: onepassword-connect
spec:
  replicas: 1
  selector:
    matchLabels:
      app: onepassword-connect
  template:
    metadata:
      labels:
        app: onepassword-connect
    spec:
      containers:
        - name: connect-api
          image: 1password/connect-api:latest
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: credentials
              mountPath: /home/opuser/.op/1password-credentials.json
              subPath: 1password-credentials.json
      volumes:
        - name: credentials
          secret:
            secretName: onepassword-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: onepassword-connect
spec:
  selector:
    app: onepassword-connect
  ports:
    - port: 8080
      targetPort: 8080

ClusterSecretStore 配置

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect:8080
      vaults:
        production: 1
        staging: 2
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token
            namespace: external-secrets
            key: token

ExternalSecret 示例

基本机密检索：

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: database-credentials
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: Database             # Item title in 1Password
        property: username        # Field label
    - secretKey: password
      remoteRef:
        key: Database
        property: password

使用带正则表达式的 dataFrom：

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: env-config
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: app-env
  dataFrom:
    - find:
        path: app-config          # Item title
        name:
          regexp: "^[A-Z_]+$"     # Match all uppercase env vars

PushSecret（从 Kubernetes 推送到 1Password）

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-generated-secret
spec:
  refreshInterval: 1h
  secretStoreRefs:
    - name: onepassword
      kind: ClusterSecretStore
  selector:
    secret:
      name: generated-credentials
  data:
    - match:
        secretKey: api-key
        remoteRef:
          remoteKey: generated-api-key
          property: password
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: production
          tags:
            - generated
            - kubernetes

1Password Kubernetes Operator

原生 1Password Operator 可直接集成，无需使用 External Secrets Operator。

通过 Helm 安装

helm repo add 1password https://1password.github.io/connect-helm-charts
helm install connect 1password/connect \
  --set-file connect.credentials=1password-credentials.json \
  --set operator.create=true \
  --set operator.token.value=your-access-token

OnePasswordItem CRD

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: database-secret
spec:
  itemPath: "vaults/Production/items/Database"

这会创建一个名为 database-secret 的 Kubernetes Secret，其中包含 1Password 条目的所有字段。

自动重启配置

启用机密变更时自动重启部署：

# Operator-level (environment variable)
AUTO_RESTART=true

# Namespace-level (annotation)
apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    operator.1password.io/auto-restart: "true"

# Deployment-level (annotation)
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    operator.1password.io/auto-restart: "true"

Shell 插件

Shell 插件可为第三方 CLI 启用自动身份验证。

可用插件

# List available plugins
op plugin list

# Common plugins: aws, gh, stripe, vercel, fly, etc.

插件设置

# Initialize AWS plugin
op plugin init aws

# This configures shell aliases to use 1Password for AWS credentials
# Add to your shell profile as instructed

使用 1Password 的 Git 工作流

使用 1Password 管理 GitHub 身份验证，以执行 Git 操作（推送、拉取、克隆）。

快速设置

运行设置脚本以完成所有配置：

./scripts/setup-gh-plugin.sh

手动设置

第 1 步：初始化 gh 插件

# Sign in to 1Password
op signin

# Initialize gh plugin (interactive - select your GitHub token)
op plugin init gh

第 2 步：配置 Git 凭据助手

# Remove any broken credential helpers
git config --global --unset-all credential.https://github.com.helper 2>/dev/null

# Set gh as the credential helper for GitHub
git config --global credential.https://github.com.helper '!/opt/homebrew/bin/gh auth git-credential'
git config --global credential.https://gist.github.com.helper '!/opt/homebrew/bin/gh auth git-credential'

第 3 步：添加 Shell 集成

添加到你的 ~/.zshrc 或 ~/.bashrc：

# 1Password CLI plugins
source ~/.config/op/plugins.sh

工作原理

┌─────────────────────────────────────────────────────────────────┐
│                        Git Push Workflow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   git push                                                       │
│      │                                                           │
│      ▼                                                           │
│   Git credential helper                                          │
│      │                                                           │
│      ▼                                                           │
│   gh auth git-credential                                         │
│      │                                                           │
│      ▼                                                           │
│   1Password plugin (via op wrapper)                              │
│      │                                                           │
│      ▼                                                           │
│   1Password (biometric/password unlock)                          │
│      │                                                           │
│      ▼                                                           │
│   Token retrieved and passed to git                              │
│      │                                                           │
│      ▼                                                           │
│   Push completes successfully                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

多个 GitHub 账户

如果你使用多个 GitHub 账户，可以按仓库配置凭据：

# For a specific repo, use a different 1Password item
cd /path/to/work-repo
git config credential.https://github.com.helper '!/opt/homebrew/bin/gh auth git-credential'

# Or use includeIf in ~/.gitconfig for path-based selection
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

常见问题排查

“保管库中未找到条目”错误

这表示 1Password 插件指向了已删除的令牌：

# Remove the broken plugin configuration
rm ~/.config/op/plugins/used_items/gh.json

# Re-initialize
op plugin init gh

gh 被别名为 op plugin run

如果 gh 被设置为通过 1Password 运行的别名，但无法正常工作：

# Check the alias
which gh  # Shows: gh: aliased to op plugin run -- gh

# Run gh directly to bypass the alias
/opt/homebrew/bin/gh auth status

Git 提示输入用户名/密码

验证凭据助手是否已配置：

git config --list | grep credential

应显示：

credential.https://github.com.helper=!/opt/homebrew/bin/gh auth git-credential

故障排查

常见问题

身份验证失败：

# Check current session
op whoami

# Sign in again
op signin

# For service accounts, verify token
echo $OP_SERVICE_ACCOUNT_TOKEN | head -c 10

未找到条目：

# List items in vault to verify name
op item list --vault "Vault Name"

# Use item ID instead of name for reliability
op item get --vault Development dh7fjsh3kd8fjs

CI/CD 中权限被拒绝：

# Verify service account has access to vault
op vault list  # Should show accessible vaults

# Check rate limits
op service-account ratelimit

External Secrets 未同步：

# Check ExternalSecret status
kubectl describe externalsecret <name>

# Check Connect Server logs
kubectl logs -l app=onepassword-connect

# Verify SecretStore connection
kubectl describe secretstore <name>

最佳实践

1. 使用机密引用（op://），而不是在脚本中硬编码保管库/条目名称
2. 自动化时优先使用服务账户，而不是个人账户
3. 尽量缩小权限范围——仅授予必要的保管库访问权限
4. 在脚本中使用条目 ID以确保稳定性（名称可能会更改）
5. 登录地址变更时轮换服务账户令牌
6. 在 Kubernetes 中启用自动重启，以无缝轮换机密
7. 按环境使用单独的保管库（dev、staging、prod）
8. 为条目添加标签，以便整理和筛选

资源

参考资料

• references/cli-commands.md - 完整的 CLI 命令参考
• references/kubernetes-examples.md - Kubernetes 清单示例
• references/python-sdk.md - Python SDK 参考和集成指南
• references/environments/README.md - Developer Environments 指南

工具

使用 TypeScript 和 Python 编写的环境管理命令行工具：

操作	TypeScript (tools/)	Python (tools-python/)
创建	bun run create	uv run op-env-create
更新	bun run update	uv run op-env-update
删除	bun run delete	uv run op-env-delete
显示	bun run show	uv run op-env-show
列出	bun run list	uv run op-env-list
导出	bun run export	uv run op-env-export

TypeScript 要求： Bun 运行时 Python 要求： Python 3.9+、uv、OP_SERVICE_ACCOUNT_TOKEN

# TypeScript tools
cd tools && bun run src/op-env-list.ts --help

# Python SDK tools
cd tools-python && uv sync && uv run op-env-list --help

模板

环境和集成模板（位于 templates/）：

模板	描述
env.template	标准 .env 文件模板
env-op-refs.template	包含 op:// 引用的模板
github-actions-env.yaml	GitHub Actions 工作流示例
docker-compose-env.yaml	注入密钥的 Docker Compose 配置

脚本

• scripts/setup-gh-plugin.sh - 设置集成 1Password 的 GitHub CLI
• scripts/setup-service-account.sh - 创建并配置服务账户
• scripts/sync-check.sh - 验证 External Secrets 同步状态

外部文档

• 1Password CLI 文档
• 服务账户指南
• 开发环境
• 本地 .env 文件
• Kubernetes Operator
• External Secrets 提供程序

---

注意事项

• 服务账户、Connect Server 和 CLI 身份验证模式在速率限制、保管库可见性和凭据结构方面各不相同 — 使用 op 进行交互操作的脚本不一定能通过服务账户令牌正常运行。
• op inject 会在渲染时解析 op://... 引用 — 提交到 git 的模板是安全的；渲染后的输出绝不会接触 git。
• 除非设置了 OP_DEVICE，CLI 会提示进行生物识别验证 — 未设置该环境变量的 CI 容器会静默失败，就像没有任何密钥一样。
• Shell 插件（op plugin init）会在 Shell 启动时加载 — 更新插件后，必须打开新的 Shell 才会生效。
• op read op://vault/item/field 会返回重复项中的第一个匹配项 — 对于字段名称相同的项目，解析顺序按字典序，而非创建日期。