准备一个已批准入口
使用 Node.js ≥22.12 及 npm(已用 Node 24.16、Wrangler 4.163.0 验证)。网站须为当前账号的活跃 Cloudflare zone,并具备 Worker 与 SQLite Durable Objects 能力。本例用 Worker Route 接在现有 HTTPS 来源前。若网站使用 Cloudflare Pages 或另一 Worker,先集成并测试来源/ASSETS 透传。商品 HTML、页首和页尾仍由您的网站提供。
将 config/site.example.json 复制为 config/site.local.json。websiteOrigin 填已批准的准确 HTTPS 来源,apiOrigin 填管理员分配的 API 来源,encodingVersionId 填分配的 1–32 位可见 ASCII 标识。只有已批准且已写入标签的路径为 /v 时才保留此 entryPath。地区未另行启用时保持 regionEnabled=false。此 JSON 不填 Token。
编辑 wrangler.toml:首次确定 Worker 名称,将所有路由 pattern 和 zone_name 中的 website.example 替换为您的站点。保留 SESSIONS、VerificationSession 与 v1 SQLite migration。使用子域名时,pattern 填准确子域名,zone_name 填其所属 Cloudflare zone。升级保持相同 Worker 名称和命名空间;改名将使用另一份状态。/v* 覆盖动态查询参数,代码只处理配置中的精确入口。更改首跳路由时,始终保留固定的 /v/result* 与 /bg/*:中性结果仍在 /v/result,/bg/* 提供组件与已保存结果。
node --version
npm --version
npm exec --yes --package=wrangler@4.163.0 -- wrangler --version
本机运行并检查构建
在解压包根目录运行模拟器,再打开显示的本机网址。模拟使用合成数据,不向验真 API 发送请求,Ctrl+C 停止。npm test 无依赖;npm run test:full 首次安装锁定原生工具,执行真实 workerd/SQLite 测试。首次需要软件包仓库访问。报告在 test-output/。
以下 dry-run 编译实际 Worker,不部署、不登录、不调用验真 API。它不证明路由归属、秘密已配置、客户网站行为或实卡验收。不要把生产 HTTPS 来源配置直接用于 http://localhost,再把来源拒绝误判为标签失败。
node reference/node-server.mjs
# Stop the simulator before continuing.
npm test
npm run test:full
npm exec --yes --package=wrangler@4.163.0 -- wrangler deploy --config wrangler.toml --dry-run --outdir test-output/worker-dry-run
生成私有秘密文件
通过约定的秘密渠道取得验真 Token。在交互终端执行下方辅助命令:它检查配置,并隐藏输入 BRANDGUARD_VERIFICATION_TOKEN。自动化环境可通过秘密管理器提供同名环境变量。不要把值粘贴到命令参数。输出文件同时含 SITE_CONFIG 和 Token,已由 Git 忽略,且不会覆盖同名文件。
私有文件不得进入静态站点,访问权限仅给部署账号。它属于本机秘密,不作为配置表附件或公开制品。若文件已存在,先核查并主动停用旧私有副本,再生成;辅助工具拒绝覆盖。Windows 权限继承所在目录 ACL,请使用私有用户目录/工作副本。
node scripts/worker-secrets.mjs --config config/site.local.json --out .worker.secrets.local.json
同时部署代码与所需秘密
以下命令会变更您的 Cloudflare 账号。执行前核对实际域名、Worker 名称与私有配置。login 选择您自己的账号;secrets-file 将 SITE_CONFIG、BRANDGUARD_VERIFICATION_TOKEN 与 Worker 一次部署。[secrets].required 声明阻止缺少必需 secret 的真实部署。不用多个 secret put 步骤先发布配置不完整的 Worker。
部署后直接打开普通商品页:不应出现本次通过。按首次接入页执行匿名探测,再用所分配编码进行一次新的实物碰卡,与管理员对照 verificationId、itemId、decidedAt 和判定。刷新及切语言保持原时间与次数。复制地址或已使用的读取不应新增通过。确认秘密已安全保存于获授权的秘密存储后移除本机秘密文件;绝不发布。
npm exec --yes --package=wrangler@4.163.0 -- wrangler login
npm exec --yes --package=wrangler@4.163.0 -- wrangler deploy --config wrangler.toml --secrets-file .worker.secrets.local.json
为已完整配置的 Worker 轮换凭据
只有 Worker 已具备完整有效 SITE_CONFIG 与所需秘密后,才用下方命令更新已换发凭据。Wrangler 在交互提示中接收值,不把值写入命令。secret put 会立即创建并部署新 Worker 版本。与管理员协调新旧凭据启用/撤销,并用一次新碰卡核对。这是客户自行执行的线上变更,不是本机测试。
进阶模板使用 --config wrangler.advanced.toml,并轮换实际目标 binding A 或 B。不把另一入口的凭据混用,也不用此命令首次发布尚未完整配置的 Worker。
npm exec --yes --package=wrangler@4.163.0 -- wrangler secret put BRANDGUARD_VERIFICATION_TOKEN --config wrangler.toml
进阶 多个精确入口
只有两种已批准编码需要不同路径时,才从 config/advanced-multi-entry.example.json 与 wrangler.advanced.toml 开始。编辑后仍保存到 config/site.local.json。entrypoints 替换 entryPath/encodingVersionId,不混用两种格式;分别提供 BRANDGUARD_VERIFICATION_TOKEN_A、BRANDGUARD_VERIFICATION_TOKEN_B。替换所有占位符,若已批准路径不同也要修改 /scan/verify。升级保持相同 Worker 名称。这不能改变已经写入的标签。
仅做进阶本机模拟时,启动 Node 模拟器前将 BG_SITE_CONFIG 设置为 config/advanced-multi-entry.example.json。真实配置仍用同一辅助命令读取私有进阶配置,它会分别提示两个 binding。dry-run 与实际部署都选择进阶模板。在知道 SKU 前,精确路径已选定唯一编码和秘密,适配器不轮试。
npm exec --yes --package=wrangler@4.163.0 -- wrangler deploy --config wrangler.advanced.toml --dry-run --outdir test-output/advanced-worker-dry-run
# After private config and both secrets are ready:
npm exec --yes --package=wrangler@4.163.0 -- wrangler deploy --config wrangler.advanced.toml --secrets-file .worker.secrets.local.json
CLI 与配置参考:Wrangler configuration · Worker secrets