worker: BACKEND_ORIGINS_JSON 写入 wrangler.toml 的 [vars](明文例外)

Cloudflare Git 集成会提示"Update your Wrangler configuration with these changes to
keep deployments in sync",原因是 UI 上的 origin 列表没在仓库里。接受该建议:origin
列表只是公开可达的 https 地址,不是凭据,所以可以随仓库走——配置在 PR 里可审,
预览环境也能拿到它(secret 只存在于 dashboard,preview 拿不到)。

wrangler.toml 加了「明文例外的边界」评论:一旦出现内网地址 / 带内嵌凭据的 URL /
不想公开的 staging 主机名,立刻从 [vars] 删掉改用 wrangler secret put(git 历史
不可逆)。其余三个 LB_* 保持可调参数不写死。

已用实际解析器验证:parseBackendOrigins 返回 [{url: https://messageweave-eu-1.motofans.club,
healthPath: /healthz}];npm test 32 通过 0 失败;wrangler deploy --dry-run 通过,
配置里可见 env.BACKEND_ORIGINS_JSON 绑定。
This commit is contained in:
anonsaber 2026-09-30 19:07:17 +08:00
parent d7033066e2
commit aa78c13161
2 changed files with 28 additions and 17 deletions

View File

@ -62,13 +62,15 @@
| 变量 | 必填 | 说明 | | 变量 | 必填 | 说明 |
|---|---|---| |---|---|---|
| `BACKEND_ORIGINS_JSON` | 是(secret) | JSON 数组,形如 `["https://a.platform1.example","https://b.platform2.example"]`;必须全部 https、无内嵌凭据/query/fragment/路径。 | | `BACKEND_ORIGINS_JSON` | 是 | JSON 数组,形如 `["https://a.platform1.example","https://b.platform2.example"]`;必须全部 https、无内嵌凭据/query/fragment/路径。已写在 `wrangler.toml` 的 `[vars]`。 |
| `LB_REQUEST_TIMEOUT_MS` | 否 | 单 origin 请求超时;默认 `10000`。建议 > 最坏 cold start + 最长 JMAP 拉取。 | | `LB_REQUEST_TIMEOUT_MS` | 否 | 单 origin 请求超时;默认 `10000`。建议 > 最坏 cold start + 最长 JMAP 拉取。 |
| `LB_MAX_ATTEMPTS` | 否 | 每请求最多 origin 尝试次数;默认 `2`(= 1 次故障转移)。`POST /reconcile` 固定为 `1`。 | | `LB_MAX_ATTEMPTS` | 否 | 每请求最多 origin 尝试次数;默认 `2`(= 1 次故障转移)。`POST /reconcile` 固定为 `1`。 |
| `LB_RECONCILE_TIMEOUT_MS` | 否 | 仅 `POST /reconcile` 的单 origin 超时覆盖;默认 `320000`(须大于后端锁初租 300s + 心跳余量)。 | | `LB_RECONCILE_TIMEOUT_MS` | 否 | 仅 `POST /reconcile` 的单 origin 超时覆盖;默认 `320000`(须大于后端锁初租 300s + 心跳余量)。 |
| `LB_HEALTH_TTL_MS` | 否 | 健康探测缓存 TTL;默认 `30000`。 | | `LB_HEALTH_TTL_MS` | 否 | 健康探测缓存 TTL;默认 `30000`。 |
> secret 通过 `wrangler secret put BACKEND_ORIGINS_JSON` 注入;`wrangler.toml` 里 `vars` 保持为空,不写明文。 > 默认写在 `wrangler.toml` 的 `[vars]`(**明文例外**,因为当前值只是公开可达的 https origin,
> 不是凭据)。一旦要放内网地址、带内嵌凭据的 URL、或不想公开的 staging 主机名,
> 立刻改用 `npx wrangler secret put BACKEND_ORIGINS_JSON` 并把该行从 `[vars]` 删掉。
## 本地 / CI 验证 ## 本地 / CI 验证
@ -89,14 +91,15 @@ npm run check
```bash ```bash
cd cloudflare-worker cd cloudflare-worker
# 安装 dev dep(仅 wrangler): # 安装 dev dep(仅 wrangler):
npm install npm install --no-audit --no-fund
# 注入 secret: # BACKEND_ORIGINS_JSON 已写在 wrangler.toml 的 [vars],直接部署:
npx wrangler secret put BACKEND_ORIGINS_JSON # 粘贴 ["https://a.example","https://b.example"]
# 可选调参:
npx wrangler secret put LB_REQUEST_TIMEOUT_MS # 建议 10000
npx wrangler secret put LB_MAX_ATTEMPTS # 默认 2
# 部署:
npx wrangler deploy npx wrangler deploy
# 可选调参(默认值已够用;要覆盖就用 dashboard 的 Add Variable):
# LB_REQUEST_TIMEOUT_MS / LB_MAX_ATTEMPTS / LB_RECONCILE_TIMEOUT_MS / LB_HEALTH_TTL_MS
# 仅当 [vars] 里要放非公开值时才改用 secret 注入:
npx wrangler secret put BACKEND_ORIGINS_JSON
# 部署后确认:
curl https://<your-worker>.workers.dev/healthz
``` ```
健康探针: 健康探针:

View File

@ -9,15 +9,17 @@
# http/非 https/内嵌凭据。 # http/非 https/内嵌凭据。
# - 不代理 Redis/JMAP(C-NO-DB / C-REDIS-ONLY-STATE):Worker 只做请求转发,后端连自己的 Redis。 # - 不代理 Redis/JMAP(C-NO-DB / C-REDIS-ONLY-STATE):Worker 只做请求转发,后端连自己的 Redis。
# - 不使用 WebSocket/SSE/长轮询(C-NO-LONG-CONN):纯请求-响应转发。 # - 不使用 WebSocket/SSE/长轮询(C-NO-LONG-CONN):纯请求-响应转发。
# - 后端 secret 走 `wrangler secret`(见 README),不进代码/日志(SAF-LOG-PURITY / C-NO-SECRET-IN-IMAGE; # - 真 secret 不进代码/日志(SAF-LOG-PURITY / C-NO-SECRET-IN-IMAGE;C-LB-SHARED-SECRETS:
# C-LB-SHARED-SECRETS:所有后端实例共享同一组 secret)。 # 所有后端实例共享同一组 secret)。唯一明文例外是 [vars] 里的 BACKEND_ORIGINS_JSON——
# 它的值只是公开 https origin,不是凭据(见该段的「明文例外的边界」)。
# - 日志无密钥(SAF-LOG-PURITY):只打「方法/路径/origin/失败类别」,origin 清单走 secret。 # - 日志无密钥(SAF-LOG-PURITY):只打「方法/路径/origin/失败类别」,origin 清单走 secret。
# - 仅允许转发 safelist 路由(C-LB-SINGLE-REG-URL);未知路径 404。 # - 仅允许转发 safelist 路由(C-LB-SINGLE-REG-URL);未知路径 404。
# #
# 部署: # 部署:
# cd cloudflare-worker # cd cloudflare-worker
# npx wrangler secret put BACKEND_ORIGINS_JSON # 见下方示例格式
# npx wrangler deploy # npx wrangler deploy
# BACKEND_ORIGINS_JSON 现在写在下方 [vars](见该段的注释与例外条款);
# 仅当里面出现非公开值时才改用 `npx wrangler secret put BACKEND_ORIGINS_JSON`。
name = "messageweave-lb" name = "messageweave-lb"
main = "src/index.js" main = "src/index.js"
@ -25,13 +27,19 @@ compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat_v2"] compatibility_flags = ["nodejs_compat_v2"]
# 统一 HTTPS 入站(C-HTTPS-URL;平台代 TLS,Worker 内为短请求模型)。 # 统一 HTTPS 入站(C-HTTPS-URL;平台代 TLS,Worker 内为短请求模型)。
# 后端 origin 为 secret(不经明文 env 流转)。BACKEND_ORIGINS_JSON 只接受 # BACKEND_ORIGINS_JSON 只接受「字符串数组」——每项是一个 https origin;不支持
# 「字符串数组」——每项是一个 https origin;不支持 {"url":…, "weight":…} 这种 # {"url":…, "weight":…} 这种对象形式(parseBackendOrigin 只认字符串,对象项会让
# 对象形式(parseBackendOrigin 只认字符串,对象项会让整份配置解析失败, # 整份配置解析失败,而配置是**每个请求**重新解析的,所以会表现为**每个请求都 503**,
# 而配置是**每个请求**重新解析的,所以会表现为**每个请求都 503**,不是启动即失败): # 不是启动即失败):
# BACKEND_ORIGINS_JSON 形如 ["https://a.platform1.example","https://b.platform2.example"] # BACKEND_ORIGINS_JSON 形如 ["https://a.platform1.example","https://b.platform2.example"]
# LB_HEALTH_TTL_MS 可选,健康缓存 TTL(默认 30000) # LB_HEALTH_TTL_MS 可选,健康缓存 TTL(默认 30000)
# LB_REQUEST_TIMEOUT_MS 可选,单 origin 超时(默认 10000,建议 > 最坏 cold start) # LB_REQUEST_TIMEOUT_MS 可选,单 origin 超时(默认 10000,建议 > 最坏 cold start)
# LB_MAX_ATTEMPTS 可选,每请求最多 origin 尝试次数(默认 2:首次 + 1 次故障转移, # LB_MAX_ATTEMPTS 可选,每请求最多 origin 尝试次数(默认 2:首次 + 1 次故障转移,
# 对应 deployment.md §10.4「有界重试其它实例(建议 1 次)」) # 对应 deployment.md §10.4「有界重试其它实例(建议 1 次)」)
vars = {} #
# ⚠️ 明文例外的边界:[vars] 里的 origin 只能是**公开可达的 https origin**(当前就是)。
# 一旦出现内网地址、带内嵌凭据的 URL、或不想公开的 staging 主机名,立刻从 [vars] 删掉,
# 改用 `npx wrangler secret put BACKEND_ORIGINS_JSON`(git 历史不可逆,删掉不等于没进过库)。
# 其余三个 LB_* 保持可调、不写死,用 dashboard 的 Add Variable 覆盖默认值即可。
[vars]
BACKEND_ORIGINS_JSON = '["https://messageweave-eu-1.motofans.club"]'