doppler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Doppler Secrets Management

Doppler 密钥管理

Comprehensive assistance for the Doppler secrets management platform: CLI operations, project and config management, secrets injection, integration syncs, and security best practices.

为Doppler密钥管理平台提供全面指导：包括CLI操作、项目与配置管理、密钥注入、集成同步以及安全最佳实践。

Triggers

触发场景

Use this skill when the user mentions: "doppler", "secrets management", "doppler cli", "doppler secrets", "doppler run", "doppler setup", "doppler configs", "doppler projects", "secret injection", "doppler environments", "service tokens".

当用户提及以下内容时使用本技能："doppler"、"secrets management"、"doppler cli"、"doppler secrets"、"doppler run"、"doppler setup"、"doppler configs"、"doppler projects"、"secret injection"、"doppler environments"、"service tokens"。

Quick Start

快速开始

Install CLI

安装CLI

bash

undefined

bash

undefined

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

undefined

curl -sLf --retry 3 --tlsv1.2 --proto "=https" https://get.doppler.com | sh

undefined

Authenticate & Setup

认证与配置

bash

undefined

bash

undefined

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

undefined

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

undefined

Common Tasks by Intent

按意图分类的常见任务

Developer wants to...	Action
List all secrets	`doppler secrets -p <project> -c <config>`
Get a single secret	`doppler secrets get SECRET_NAME -p <project> -c <config>`
Set a secret	`doppler secrets set KEY=value -p <project> -c <config>`
Set multiple secrets	`doppler secrets set KEY1=val1 KEY2=val2`
Delete a secret	`doppler secrets delete SECRET_NAME`
Run command with secrets	`doppler run -- your-command --flags`
Run with specific config	`doppler run -p backend -c dev -- npm start`
Download secrets as file	`doppler secrets download --format env --no-file`
List projects	`doppler projects`
List configs	`doppler configs -p <project>`
List environments	`doppler environments -p <project>`
Clone a config	`doppler configs clone -p <project> -c <source> --name <new>`
View activity logs	`doppler activity`
Check current setup	`doppler configure debug`
Open dashboard	`doppler open`
View who is authenticated	`doppler me`

开发者需求	操作命令
列出所有密钥	`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`

Secrets Injection Patterns

密钥注入模式

Environment Variable Injection

环境变量注入

bash

undefined

bash

undefined

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

运行Shell命令字符串

doppler run --command "echo $DATABASE_URL && npm start"

Only inject specific secrets

仅注入指定密钥

doppler run --only-secrets DATABASE_URL,API_KEY -- node server.js

undefined

doppler run --only-secrets DATABASE_URL,API_KEY -- node server.js

undefined

Mount Secrets to File

将密钥挂载到文件

bash

undefined

bash

undefined

Mount as JSON file (ephemeral, cleaned up after process exits)

挂载为JSON文件（临时文件，进程退出后自动清理）

doppler run --mount secrets.json -- cat secrets.json

Mount as .env file

挂载为.env文件

doppler run --mount .env --mount-format env -- your-command

Mount with template

使用模板挂载

doppler run --mount config.yaml --mount-template template.yaml -- your-command

undefined

doppler run --mount config.yaml --mount-template template.yaml -- your-command

undefined

Template Substitution

模板替换

bash

undefined

bash

undefined

Substitute secrets into a template file

将密钥替换到模板文件中

doppler secrets substitute template.env.tpl > .env

undefined

doppler secrets substitute template.env.tpl > .env

undefined

Fallback for Offline/Resilience

离线/容灾回退方案

bash

undefined

bash

undefined

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)

离线模式（直接从回退文件读取，不调用API）

doppler run --fallback-only --fallback ./fallback.encrypted -- npm start

undefined

doppler run --fallback-only --fallback ./fallback.encrypted -- npm start

undefined

Project & Config Hierarchy

项目与配置层级

Doppler organizes secrets in a hierarchy:

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")

Doppler采用层级结构组织密钥：

工作区
 └── 项目（例如："backend"、"frontend"）
      └── 环境（例如："development"、"staging"、"production"）
           └── 配置（例如："dev"、"stg"、"prd"）
                └── 分支配置（例如："dev_feature-x"）

Config Inheritance

配置继承规则

Root configs (dev, stg, prd) inherit from their environment
Branch configs inherit from their parent config
Overrides cascade: Environment → Config → Branch Config
Personal configs allow individual developer overrides without affecting the team

根配置（dev、stg、prd）从所属环境继承
分支配置从父配置继承
覆盖优先级：环境 → 配置 → 分支配置
个人配置允许开发者进行本地覆盖，不会影响团队配置

Integration Syncs

集成同步

Doppler can automatically sync secrets to external platforms:

Platform	Use Case
AWS Secrets Manager / SSM	ECS, Lambda, EC2 deployments
GCP Secret Manager	GKE, Cloud Run, Cloud Functions
Azure Key Vault	AKS, App Service, Functions
Cloudflare Pages / Workers	Edge & Jamstack deployments
Vercel	Frontend/fullstack deployments
Firebase Functions / Hosting	Functions config & build-time secrets
Serverless Framework	Lambda/serverless function secrets
GitHub Actions	CI/CD secrets
Docker / Docker Compose	Container environment injection
Kubernetes	Secret objects via Doppler Operator
Terraform	Infrastructure as Code
Webapp.io	CI/CD Layerfile secrets
Heroku	PaaS deployments

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	函数配置与构建时密钥
Serverless Framework	Lambda/无服务器函数密钥
GitHub Actions	CI/CD密钥
Docker / Docker Compose	容器环境注入
Kubernetes	通过Doppler Operator管理Secret对象
Terraform	基础设施即代码
Webapp.io	CI/CD Layerfile密钥
Heroku	PaaS部署

Service Tokens

服务令牌

For CI/CD and production, use service tokens (read-only, scoped to a single config):

bash

undefined

在CI/CD和生产环境中，使用服务令牌（只读权限，仅作用于单个配置）：

bash

undefined

Generate a service token via dashboard or API

通过控制台或API生成服务令牌

Use in CI/CD:

在CI/CD中使用：

DOPPLER_TOKEN=dp.st.xxx doppler run -- your-command

Or set as environment variable

或设置为环境变量

export DOPPLER_TOKEN=dp.st.xxx doppler secrets

undefined

export DOPPLER_TOKEN=dp.st.xxx doppler secrets

undefined

Security Best Practices

安全最佳实践

Never commit secrets to version control — use Doppler as the single source of truth
Use service tokens in production (read-only, config-scoped)
Use personal configs for local development overrides
Enable change requests for production configs (requires approval before changes)
Rotate secrets regularly — use Doppler's rotation reminders
Use OIDC authentication where possible for short-lived tokens
Audit access via
```
doppler activity
```
and dashboard audit logs
Use branch configs to isolate feature branch secrets
Never use
--no-verify-tls
in production

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

Reference Documents

参考文档

For deep dives, consult these references:

Reference	Content
CLI.md	Complete CLI command reference with all subcommands and flags
INTEGRATIONS.md	CI/CD, Docker, Kubernetes, cloud platform integration patterns

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

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

Troubleshooting

故障排查

Authentication Issues

认证问题

Run
```
doppler me
```
to check current auth status
Run
```
doppler configure debug
```
to see active configuration
Re-authenticate with
```
doppler login
```

Check scope:

doppler configure get token --scope /path/to/project

运行
```
doppler me
```
检查当前认证状态
运行
```
doppler configure debug
```
查看当前配置
重新认证：
```
doppler login
```

检查权限范围：

doppler configure get token --scope /path/to/project

Wrong Secrets Loaded

加载错误密钥

Check which project/config is active:
```
doppler configure debug
```
Verify scope:
```
doppler setup
```
in the project directory
Use explicit flags:
```
doppler secrets -p project -c config
```
Check for environment variable overrides:
```
doppler run --preserve-env=false
```

检查当前激活的项目/配置：
```
doppler configure debug
```
验证权限范围：在项目目录中运行
```
doppler setup
```
使用显式参数：
```
doppler secrets -p project -c config
```
检查环境变量覆盖：
```
doppler run --preserve-env=false
```

Fallback File Issues

回退文件问题

Ensure fallback path is writable
Check passphrase hasn't changed (config-dependent by default)
Use
```
doppler run clean
```
to remove old fallback files

Regenerate with a fresh

doppler run --fallback ./path -- echo ok

确保回退路径可写
检查密码短语未变更（默认与配置相关）
使用
```
doppler run clean
```
删除旧回退文件

通过

doppler run --fallback ./path -- echo ok

重新生成

Service Token Not Working

服务令牌无法工作

Verify token is for the correct project and config
Service tokens are read-only — cannot set/delete secrets
Check token hasn't been revoked in the dashboard
Ensure
```
DOPPLER_TOKEN
```
env var is set correctly

验证令牌对应正确的项目和配置
服务令牌为只读权限 —— 无法设置/删除密钥
检查令牌是否在控制台被吊销
确保
```
DOPPLER_TOKEN
```
环境变量设置正确

Workflow

工作流程

When helping with Doppler:

Identify the task: Setup, secret management, injection, integration, or debugging
Check prerequisites: Is
```
doppler
```
CLI installed? Is user authenticated?
Determine scope: Which project and config are we working with?
Consult references: Use reference docs for detailed CLI flags and integration patterns
Security first: Never output secret values in logs; use
```
--only-names
```
for listing

当协助处理Doppler相关问题时：

明确任务：配置、密钥管理、注入、集成或故障排查
检查前置条件：是否已安装
```
doppler
```
CLI？用户是否已认证？
确定范围：当前操作的是哪个项目和配置？
查阅参考文档：使用参考文档获取详细的CLI参数和集成模式
安全优先：不要在日志中输出密钥值；使用
```
--only-names
```
参数列出密钥