
Cloudflare Secrets Store 配置实战Wrangler 绑定、命令行管理与 CI/CD 集成全指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文是一份以 Secrets Store 配置文档 为主体的实战指南面向在 Cloudflare Workers 上构建应用的开发者系统讲解如何通过wrangler.jsonc/wrangler.toml声明 Secrets Store 绑定、使用wrangler secrets-store命令管理 Store 与密钥、通过 Dashboard 完成可视化配置并在 GitHub Actions / GitLab CI 中实现密钥注入与自动部署。读完本文你将掌握从绑定配置、环境隔离、本地开发到 CI/CD 全链路的云端密钥管理方案。一、Secrets Store 是什么先理解配置的对象Cloudflare Secrets Store 是账户级别的加密密钥管理服务为 Workers 与 AI Gateway 提供集中式密钥存取能力。它与传统的 Worker Secretswrangler secret put每个 Worker 独立一份的核心区别在于Secrets Store 中的密钥属于账户级资源可被多个 Worker 复用并支持审计与团队协作。从仓库参考文档可以确认以下核心概念见 Secrets Store 参考总览Store密钥容器。Beta 阶段每个账户限额 1 个Secret字符串型密钥单条上限 1024 字节Scopes权限边界workers表示可在 Workers 运行时访问ai-gateway表示供 AI Gateway 访问密钥必须带有正确 scope 才能完成绑定Bindings通过env对象将密钥连接到 Worker 运行时区域可用性全球可用但中国网络区域不可用。使用场景决策当多个 Worker 共享同一份凭据、需要集中管理与审计、或需要团队协作时优先选择 Secrets Store而仅单个 Worker 使用的独立密钥继续使用 Worker Secrets 更简单。**配置的三个字段binding / store_id / secret_name**就是本文反复出现的核心理解其含义是后续所有操作的前提字段含义获取方式binding运行时env中的变量名自定义例如API_KEYstore_idStore 的唯一标识wrangler secrets-store store list输出secret_name密钥在 Store 中的标识不含空格创建密钥时指定如stripe_api_key二、Wrangler 配置声明 Secrets Store 绑定2.1 基本绑定Basic Binding在 Worker 项目的wrangler.jsonc中声明secrets_store_secrets数组每个元素声明一条绑定。wrangler.jsonc写法{ secrets_store_secrets: [ { binding: API_KEY, store_id: abc123, secret_name: stripe_api_key } ] }如果项目使用wrangler.toml等价写法为 TOML 数组[[secrets_store_secrets]] binding API_KEY store_id abc123 secret_name stripe_api_key字段说明bindingenv访问时的变量名。配置后代码中通过await env.API_KEY.get()异步读取读取方式详见后文与 API 参考store_id来自wrangler secrets-store store list命令的输出secret_name密钥标识不允许包含空格。需要强调的是Secrets Store 绑定不同于普通配置变量vars或 Worker Secrets。普通变量直接以字符串形式挂在env上而 Secrets Store 绑定是一个具备get(): Promisestring方法的对象必须通过异步调用读取——这正是 绑定配置参考 中Secrets (never in config)原则的延续密钥内容永不写入配置文件配置中只声明从哪里取。2.2 环境专属配置Environment-Specific多环境生产 / 预发是 Secrets Store 配置最常见的实战形态。通过env顶层字段可以为不同环境指向不同的 Store 与密钥名。wrangler.jsonc写法{ env: { production: { secrets_store_secrets: [ { binding: API_KEY, store_id: prod-store, secret_name: prod_api_key } ] }, staging: { secrets_store_secrets: [ { binding: API_KEY, store_id: staging-store, secret_name: staging_api_key } ] } } }wrangler.toml等价写法[env.production] [[env.production.secrets_store_secrets]] binding API_KEY store_id prod-store secret_name prod_api_key [env.staging] [[env.staging.secrets_store_secrets]] binding API_KEY store_id staging-store secret_name staging_api_key从结构上可以看到环境隔离的两个维度一是Store 隔离prod-storevsstaging-store二是密钥名隔离prod_api_keyvsstaging_api_key。这保证了预发环境永远不会读到生产密钥。对应的部署命令可参考 Wrangler 参考 中的wrangler deploy与wrangler deploy --env staging不带--env时默认部署production环境即顶层非 env 段配置带--env staging时部署 staging 段。三、Wrangler 命令行Store 与密钥管理3.1 Store 管理Store 是整个密钥体系的第一层容器。常用命令# 列出所有 Store获取 store_id wrangler secrets-store store list # 创建远程 Store wrangler secrets-store store create my-store --remote # 删除 Store wrangler secrets-store store delete store-id --remote注意--remote标志表示操作作用于云端生产数据store-id取自store list输出。创建/删除 Store 这类账户级操作需要 API Token 具备Account Secrets Store Edit权限见 README 访问控制。3.2 密钥管理生产环境密钥的生命周期操作全部通过wrangler secrets-store secret子命令完成以下命令均作用于生产--remote# 创建交互式输入值 wrangler secrets-store secret create store-id \ --name MY_SECRET --scopes workers --remote # 创建管道方式注入值适合 CI 与脚本 cat secret.txt | wrangler secrets-store secret create store-id \ --name MY_SECRET --scopes workers --remote # 列出 / 获取 / 更新 / 删除 wrangler secrets-store secret list store-id --remote wrangler secrets-store secret get store-id --name MY_SECRET --remote wrangler secrets-store secret update store-id --name MY_SECRET --new-value val --remote wrangler secrets-store secret delete store-id --name MY_SECRET --remote # 复制密钥轮换利器 wrangler secrets-store secret duplicate store-id \ --name ORIG --new-name COPY --remote参数速记参数作用--name密钥名称不含空格--scopes workers声明workers作用域绑定必需--remote操作云端生产数据--new-value更新时的新值--new-nameduplicate 时的新名称需要特别留意的是--name MY_SECRET指的是Store 中的密钥名即配置中的secret_name而绑定名binding只存在于wrangler配置中。二者可以通过 duplicate 命令配合版本化命名如api_key_v2实现零停机轮换具体流程见 patterns.md 的 Secret Rotation 一节。3.3 本地开发Local Development关键约束生产密钥--remote在本地开发中不可访问。wrangler dev只读取本地环境无法读取云端生产密钥。# 创建本地专属密钥不带 --remote wrangler secrets-store secret create store-id --name DEV_KEY --scopes workers wrangler dev # 使用本地密钥 wrangler deploy # 使用生产密钥推荐的最佳实践是为本地与生产使用不同的密钥名并在wrangler.jsonc中用env.development与env.production分开声明{ env: { development: { secrets_store_secrets: [ { binding: API_KEY, store_id: store, secret_name: dev_api_key } ] }, production: { secrets_store_secrets: [ { binding: API_KEY, store_id: store, secret_name: prod_api_key } ] } } }这样本地调试走dev_api_key线上部署走prod_api_key绑定名保持一致代码零改动。本地密钥不计入账户配额详见 gotchas.md 限额表可以放心创建。若本地需要完整模拟生产绑定也可参考 绑定配置参考 中的wrangler dev --remote方案但 Secrets Store 场景下生产密钥无法被本地直接读取因此本地专属密钥 环境隔离是更稳妥的做法。四、Dashboard可视化配置密钥与绑定4.1 创建密钥进入Secrets Store控制台点击Create secret填写Name不允许空格、Value、Scope选Workers、Comment备注点击Save保存后密钥值即被隐藏。4.2 添加绑定在 Worker 上绑定密钥有两种方法方法 1Worker → Settings → Bindings → Add → 选择 Secrets Store方法 2直接在 Worker 设置的绑定下拉框中创建密钥。Dashboard 提供两种部署选项Deploy部署立即 100% 全量生效Save version保存版本仅保存为新版本用于渐进式灰度发布gradual rollout。五、CI/CD密钥注入与自动部署Secrets Store 与 CI/CD 结合时核心模式是CI 平台只保存用于认证的 token而真正的业务密钥通过管道动态注入永不落盘、不入仓库。5.1 GitHub Actions- name: Create secret env: CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }} run: | echo ${{ secrets.API_KEY }} | \ npx wrangler secrets-store secret create $STORE_ID \ --name API_KEY --scopes workers --remote - name: Deploy run: npx wrangler deploy要点CLOUDFLARE_API_TOKEN来自 GitHub Secrets为wrangler提供账户认证CI 场景无法交互式wrangler login必须走 API Token 环境变量见 SKILL.md 认证要求${{ secrets.API_KEY }}是 GitHub Secrets 中的业务密钥值通过echo |管道喂给secret create避免出现在命令行参数与日志中$STORE_ID可在 CI 变量中配置对应wrangler secrets-store store list的输出。5.2 GitLab CIscript: - echo $API_KEY_VALUE | npx wrangler secrets-store secret create $STORE_ID --name API_KEY --scopes workers --remote - npx wrangler deployGitLab 侧将API_KEY_VALUE与STORE_ID配置为 CI/CD VariablesCLOUDFLARE_API_TOKEN同样作为变量提供认证。两步走先注入/更新密钥再部署 Worker保证 Worker 上线时密钥已就绪。六、运行时读取绑定后的代码怎么写配置只是第一步运行时读取是配套动作。Secrets Store 绑定在env中不是字符串而是带get()方法的对象必须异步读取且.get()失败时抛出异常而非返回 null。基础用法详见 API 参考interface Env { API_KEY: { get(): Promisestring }; } export default { async fetch(request: Request, env: Env): PromiseResponse { const apiKey await env.API_KEY.get(); return fetch(https://api.example.com, { headers: { Authorization: Bearer ${apiKey} } }); } }安全实践清单来自 gotchas.md.get()必须用 try/catch 包裹否则异常会导致 500只记录元数据如 Retrieved API_KEY严禁把密钥值写进日志密钥读取结果只能在请求作用域内缓存模块级缓存const KEY await env.X.get()在模块初始化阶段拿不到env必然失败报 Secret not found 时按序排查密钥是否存在、名称是否大小写完全一致区分大小写、是否带workersscope、store_id是否正确scope 不匹配密钥只有ai-gatewayscope时用wrangler secrets-store secret update store-id --name SECRET --scopes workers --remote补上workersscope配额超限Beta 期每账户 100 条时用wrangler secrets-store quota --remote查看配额删除无用密钥或合并重复项。进阶使用模式详见 patterns.md包括版本化命名api_key_v1/v2实现零停机轮换、用 Secrets Store 密钥作为 AES-GCM / HMAC-SHA256 的加密密钥材料、把结构化 JSON 配置作为单条密钥存储并在运行时解析、通过 Service Bindings 让鉴权 Worker 签名 JWT 供其他 Worker 校验等。七、一处配置、多方受益与其他参考文档的关系本配置文档是 Secrets Store 参考集的入口之一整个参考集按任务组织见 secrets-store/README.md任务阅读路径首次配置README → configuration本文→ api给 Worker 加密钥configuration本文→ api实现访问模式api → patterns调试错误gotchas → api密钥轮换patterns → configuration最佳实践gotchas → patterns在更上层本参考隶属于 cloudflare-deploy Skill该 Skill 将 Secrets Store 归入 I need to store data 决策树中的Secrets management → secrets-store/分支与 Workersworkers绑定集成、Wrangler CLIwrangler命令管理互为补充。实际项目中通常先按本文完成绑定配置与密钥管理再结合 bindings 配置参考 统一规划 KV、R2、D1 等全部绑定的声明方式所有绑定共享 64 个的上限。八、配置速查与关键结论绑定三要素bindingenv 变量名、store_id来自store list、secret_name不含空格两种配置文件wrangler.jsoncsecrets_store_secrets数组与wrangler.toml[[secrets_store_secrets]]表功能等价环境隔离env.production/env.staging/env.development分段声明不同 store_id 与 secret_name本地与生产本地密钥不带--remote创建wrangler dev用本地、wrangler deploy用生产CI/CDecho $VALUE | npx wrangler secrets-store secret create ... --remote管道注入 npx wrangler deploy运行时await env.BINDING.get()异步、必须 try/catch、只在请求作用域缓存配额Beta每账户 1 个 Store、100 条密钥、单条 ≤1024 字节本地密钥不计入配额Dashboard 两种部署Deploy 立即全量Save version 用于渐进发布。将上述配置、命令与代码模式组合起来你就能在多个 Worker 之间安全、集中、可审计地复用同一份凭据并将密钥的创建、轮换与 Worker 的部署一并纳入自动化流水线。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考