doppler-secret-validation

Doppler 密钥验证

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生变化，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

用于在 Doppler 密钥管理中安全地添加、验证和测试 API 令牌及凭据的工作流。

何时使用此技能

在以下情况下使用此技能：

• 用户提供了 API 令牌或凭据（PyPI、GitHub、AWS 等）
• 用户提到“添加到 Doppler”“存储密钥”或“验证令牌”
• 用户想在生产环境使用前测试身份验证
• 用户需要验证密钥的存储和获取情况

工作流

步骤 1：测试令牌格式（添加到 Doppler 之前）

存储到 Doppler 之前，先验证令牌格式：

# Check token format, length, prefix
python3 -c "token = 'TOKEN_VALUE'; print(f'Prefix: {token[:20]}...'); print(f'Length: {len(token)}')"

常见令牌格式：

• PyPI：pypi-...（179 个字符）
• GitHub：ghp_...（40 个以上字符）
• AWS：20 个字符的访问密钥 + 40 个字符的密钥

步骤 2：将密钥添加到 Doppler

doppler secrets set SECRET_NAME="value" --project PROJECT --config CONFIG

示例：

doppler secrets set PYPI_TOKEN="pypi-AgEI..." \
  --project private-config --config prd

重要：CLI 不支持 --note。请通过仪表板添加备注：

1. https://dashboard.doppler.com
2. 导航至：PROJECT → CONFIG → SECRET_NAME
3. 编辑 → 添加描述性备注

步骤 3：验证存储

使用捆绑的验证脚本：

/usr/bin/env bash << 'VALIDATE_EOF'
ROOT="$(cc-plugin-root devops-tools)"
cd "$ROOT/skills/doppler-secret-validation"
uv run scripts/validate_secret.py \
  --project PROJECT \
  --config CONFIG \
  --secret SECRET_NAME
VALIDATE_EOF

此脚本会验证：

1. 密钥存在于 Doppler 中
2. 密钥可以成功获取
3. 可通过 doppler run 注入环境变量

示例：

uv run scripts/validate_secret.py \
  --project private-config \
  --config prd \
  --secret PYPI_TOKEN

步骤 4：测试 API 身份验证

使用捆绑的身份验证测试脚本（针对特定 API 调整 test_api_authentication()）：

/usr/bin/env bash << 'CONFIG_EOF'
ROOT="$(cc-plugin-root devops-tools)"
doppler run --project PROJECT --config CONFIG -- \
  "$ROOT/skills/doppler-secret-validation/scripts/test_api_auth.py" \
    --secret SECRET_NAME \
    --api-url API_ENDPOINT
CONFIG_EOF

示例（PyPI）：

doppler run --project private-config --config prd -- \
  uv run scripts/test_api_auth.py \
    --secret PYPI_TOKEN \
    --api-url https://upload.pypi.org/legacy/

步骤 5：记录用法

验证后，为用户记录用法模式：

/usr/bin/env bash << 'CONFIG_EOF_2'
# Pattern 1: Doppler run (recommended for CI/scripts)
doppler run --project PROJECT --config CONFIG -- COMMAND

# Pattern 2: Manual export (for troubleshooting)
export SECRET_NAME=$(doppler secrets get SECRET_NAME \
  --project PROJECT --config CONFIG --plain)
CONFIG_EOF_2

步骤 5b：目录范围的 Doppler 配置（本地开发）

对于按目录设置的凭据，只需通过 doppler setup 将目录绑定到 Doppler 项目/配置一次；之后在该目录中运行的每条 doppler run 命令都会自动使用该配置，无需指定 --project/--config：

cd ~/project && doppler setup --project myproject --config prd --no-interactive
doppler run -- COMMAND

GitHub 令牌例外：不要将 Doppler 中的 GH_TOKEN/GITHUB_TOKEN 注入目录（ADR 2026-06-21）。GitHub 多账户身份验证由仓库的 origin 主机别名驱动，并通过 ~/.claude/tools/bin/gh-token-for-repo 为每个仓库动态解析令牌。

常见模式

多种配置（dev、stg、prd）

将密钥添加到多个环境：

# Production
doppler secrets set TOKEN="prod-value" --project foo --config prd

# Development
doppler secrets set TOKEN="dev-value" --project foo --config dev

跨配置验证密钥

/usr/bin/env bash << 'CONFIG_EOF_3'
for config in dev stg prd; do
  echo "=== $config ==="
  doppler secrets get TOKEN --project foo --config $config --plain | head -c 20
  echo "..."
done
CONFIG_EOF_3

安全指南

1. 绝不记录完整密钥：使用 ${SECRET:0:20}... 进行遮蔽
2. 优先使用 doppler run：将密钥的作用范围限制在单条命令内
3. 仅在管道传输时使用 --plain：供人阅读的视图会遮蔽密钥
4. 按环境分隔配置：隔离 dev/stg/prd

捆绑资源

• scripts/validate_secret.py - 完整的验证套件（存在性、获取、注入）
• scripts/test_api_auth.py - API 身份验证测试模板
• references/doppler-patterns.md - 常见 CLI 模式和示例

参考

• Doppler 文档：https://docs.doppler.com/docs
• CLI 安装：brew install dopplerhq/cli/doppler
• 有关完整模式，请参阅 doppler-patterns.md

---

故障排查

问题	原因	解决方案
未找到密钥	指定了错误的项目/配置	使用 doppler secrets ls --project X --config 验证
身份验证测试失败，返回 401	令牌已过期或无效	重新生成令牌，然后重新添加到 Doppler
doppler run 卡住	CLI 正在等待输入	添加 --no-interactive 标志
令牌前缀不匹配	使用了错误的令牌类型	检查预期格式（pypi-、ghp-、AKIA 等）
未找到验证脚本	目录上下文错误	使用 cc-plugin-root devops-tools 查找插件根目录，然后 cd 到技能目录
获取的密钥为空	密钥名称拼写错误	列出密钥：doppler secrets ls --project X
多个配置令人困惑	不同环境中的密钥各不相同	每条命令都使用明确的 --config 标志

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确定当前位置。 — 在编辑前找到此 SKILL.md 的规范路径。
1. 出了什么问题？ — 修复导致问题的说明。
2. 哪些做法比预期更有效？ — 将其列为推荐做法。
3. 有哪些内容已偏离实际？ — 修复与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。 — 在演进日志中记录触发原因、修复内容和证据。

不要拖延。下次调用会继承你留下的所有内容。