doppler

Doppler 密钥管理

全面支持 Doppler 密钥管理平台：CLI 操作、项目与配置管理、密钥注入、集成同步和安全最佳实践。

触发条件

用户提到以下内容时使用此技能：“doppler”、“密钥管理”、“doppler cli”、“doppler secrets”、“doppler run”、“doppler setup”、“doppler configs”、“doppler projects”、“密钥注入”、“doppler environments”、“服务令牌”。

快速开始

安装 CLI

# macOS
brew install gnupg && brew install dopplerhq/cli/doppler

# Linux (Debian/Ubuntu)
apt-get update && apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -sLf --retry 3 --tlsv1.2 --proto "=https" \
  'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | \
  gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" | \
  tee /etc/apt/sources.list.d/doppler-cli.list
apt-get update && apt-get install doppler

# Shell script (any OS)
curl -sLf --retry 3 --tlsv1.2 --proto "=https" https://get.doppler.com | sh

身份验证与设置

# Login (opens browser for auth)
doppler login

# Setup project in current directory (interactive)
doppler setup

# Non-interactive setup
doppler setup --project my-app --config dev --no-interactive

按意图分类的常见任务

开发者想要……	操作
列出所有密钥	doppler secrets -p <project> -c <config>
获取单个密钥	doppler secrets get SECRET_NAME -p <project> -c <config>
设置密钥	doppler secrets set KEY=value -p <project> -c <config>
设置多个密钥	doppler secrets set KEY1=val1 KEY2=val2
删除密钥	doppler secrets delete SECRET_NAME
使用密钥运行命令	doppler run -- your-command --flags
使用指定配置运行	doppler run -p backend -c dev -- npm start
将密钥下载为文件	doppler secrets download --format env --no-file
列出项目	doppler projects
列出配置	doppler configs -p <project>
列出环境	doppler environments -p <project>
克隆配置	doppler configs clone -p <project> -c <source> --name <new>
查看活动日志	doppler activity
检查当前设置	doppler configure debug
打开控制面板	doppler open
查看当前身份验证用户	doppler me

密钥注入模式

环境变量注入

# Inject secrets as env vars for any command
doppler run -- node server.js
doppler run -- docker compose up
doppler run -- terraform apply

# Run a shell command string
doppler run --command "echo $DATABASE_URL && npm start"

# Only inject specific secrets
doppler run --only-secrets DATABASE_URL,API_KEY -- node server.js

将密钥挂载到文件

# Mount as JSON file (ephemeral, cleaned up after process exits)
doppler run --mount secrets.json -- cat secrets.json

# Mount as .env file
doppler run --mount .env --mount-format env -- your-command

# Mount with template
doppler run --mount config.yaml --mount-template template.yaml -- your-command

模板替换

# Substitute secrets into a template file
doppler secrets substitute template.env.tpl > .env

离线/弹性回退方案

# Run with fallback file (writes encrypted secrets on success, reads on failure)
doppler run --fallback ./fallback.encrypted -- npm start

# Read-only fallback (never update the fallback file)
doppler run --fallback ./fallback.encrypted --fallback-readonly -- npm start

# Offline mode (read directly from fallback, no API contact)
doppler run --fallback-only --fallback ./fallback.encrypted -- npm start

项目与配置层级

Doppler 按层级组织密钥：

Workplace
 └── Project (e.g. "backend", "frontend")
      └── Environment (e.g. "development", "staging", "production")
           └── Config (e.g. "dev", "stg", "prd")
                └── Branch Config (e.g. "dev_feature-x")

配置继承

• 根配置（dev、stg、prd）继承其所属环境
• 分支配置继承其父级配置
• 覆盖按以下顺序级联：环境 → 配置 → 分支配置
• 个人配置允许开发者单独覆盖设置，而不影响团队

集成同步

Doppler 可以自动将密钥同步到外部平台：

平台	用途
AWS Secrets Manager / SSM	ECS、Lambda、EC2 部署
GCP Secret Manager	GKE、Cloud Run、Cloud Functions
Azure Key Vault	AKS、App Service、Functions
Cloudflare Pages / Workers	边缘计算和 Jamstack 部署
Vercel	前端/全栈部署
Firebase Functions / Hosting	Functions 配置和构建时密钥
Serverless Framework	Lambda/无服务器函数密钥
GitHub Actions	CI/CD 密钥
Docker / Docker Compose	容器环境注入
Kubernetes	通过 Doppler Operator 创建密钥对象
Terraform	基础设施即代码
Webapp.io	CI/CD Layerfile 密钥
Heroku	PaaS 部署

服务令牌

对于 CI/CD 和生产环境，请使用服务令牌（只读，作用范围限定为单个配置）：

# Generate a service token via dashboard or API
# Use in CI/CD:
DOPPLER_TOKEN=dp.st.xxx doppler run -- your-command

# Or set as environment variable
export DOPPLER_TOKEN=dp.st.xxx
doppler secrets

安全最佳实践

• 切勿将密钥提交到版本控制中——使用 Doppler 作为唯一可信来源
• 在生产环境使用服务令牌（只读，作用范围限定为配置）
• 使用个人配置进行本地开发覆盖
• 为生产配置启用变更请求（变更前需要审批）
• 定期轮换密钥——使用 Doppler 的轮换提醒
• 尽可能使用 OIDC 身份验证以获取短期令牌
• 通过 doppler activity 和控制面板审计日志审计访问
• 使用分支配置隔离功能分支密钥
• 切勿在生产环境中使用 --no-verify-tls

参考文档

如需深入了解，请查阅以下参考文档：

参考文档	内容
CLI.md	完整的 CLI 命令参考，包含所有子命令和标志
INTEGRATIONS.md	CI/CD、Docker、Kubernetes 和云平台集成模式

故障排除

身份验证问题

1. 运行 doppler me，检查当前身份验证状态
2. 运行 doppler configure debug，查看当前生效的配置
3. 运行 doppler login 重新进行身份验证
4. 检查作用域：doppler configure get token --scope /path/to/project

加载了错误的密钥

1. 检查当前激活的项目/配置：doppler configure debug
2. 验证作用域：在项目目录中运行 doppler setup
3. 使用显式标志：doppler secrets -p project -c config
4. 检查是否有环境变量覆盖：doppler run --preserve-env=false

备用文件问题

1. 确保备用文件路径可写
2. 检查口令是否已更改（默认情况下取决于配置）
3. 使用 doppler run clean 删除旧的备用文件
4. 使用新的 doppler run --fallback ./path -- echo ok 重新生成

服务令牌无法使用

1. 验证令牌是否对应正确的项目和配置
2. 服务令牌为只读，无法设置或删除密钥
3. 检查仪表板中是否已撤销令牌
4. 确保 DOPPLER_TOKEN 环境变量已正确设置

工作流

协助处理 Doppler 相关问题时：

1. 确定任务：设置、密钥管理、注入、集成或调试
2. 检查前提条件：是否已安装 doppler CLI？用户是否已完成身份验证？
3. 确定作用域：我们要处理哪个项目和配置？
4. 查阅参考文档：使用参考文档了解详细的 CLI 标志和集成模式
5. 安全第一：切勿在日志中输出密钥值；列出密钥时使用 --only-names