关键架构决策与迁移指南
本页沉淀 ModelBridge 在存储权威、容错语义、平台预算与反代验收方面的核心架构决策(ADR),并提供从 Cloudflare 原生 Durable Object / KV 迁往自建 Node.js 24 + SQLite 的标准化操作流程。最近一次全仓代码同步与回归验证记录见 文档校准与验证记录。
关键架构决策(ADR)
ADR-001:单一配置权威,禁止多主双写与静默降级
- 决策:每个部署实例在运行时只能绑定一个配置权威——要么是原生 Cloudflare
AppConfigStore(DO SQLite),要么是通过MODELBRIDGE_STATE_URL访问的远端状态服务(self-hosted-state或state-service)。当ADMIN_PASSWORD、CONFIG_STORE/KV(原生模式)或MODELBRIDGE_STATE_*(远程模式)缺失时直接返回503。 - 依据:防止配置(特别是已撤销的
apiKeys、已禁用账号或刷新中的 OAuth token)在内存缓存、KV 与多个边缘节点之间出现脑裂或延迟失效。 - 容量与边界:远程 HTTP 状态 RPC 约束请求体上限为
2 MiB(STATE_REQUEST_LIMIT)、响应体上限为16 MiB(STATE_RESPONSE_LIMIT);自建 SQLite 运维导入文件上限为16 MiB + 1 KiB(CONFIG_FILE_LIMIT),单库以WAL模式 +synchronous = FULL+BEGIN IMMEDIATE串行化写入。
ADR-002:Cloudflare KV 仅用于 DO 首次初始化迁移
- 决策:原生 Cloudflare 模式中,
KV只在AppConfigStore(实例名app-config-v1)尚无配置数据时读取一次旧键config完成初始化迁入;此后所有读取与写入均由 DO 单独承担,不再回写KV。 - 依据:Workers KV 的最终一致性不适合承载即时生效的密钥撤销、登录失败计数锁定(15 分钟 10 次)及多账号并发变更。
ADR-003:仅对明确拒绝(401/403/404/429)执行有限候选切换
- 决策:
shouldRetryUpstream仅在收到上游明确的401、403、404、429拒绝时,才在随机洗牌后的最多 3 个匹配账号中继续尝试下一个候选;对于5xx、网络故障、120s首包/流空闲超时、超32 MiB响应或无效200载荷一律立即返回错误。同时 Caddy 反代模板强制声明lb_retries 0与protocols h1。 - 依据:一旦上游已经受理生成,中途断连或
5xx后自动重发不仅会导致客户被重复计费,还会瞬间耗尽阿里云 ESA 单请求仅有4次外部fetch的硬预算。
ADR-004:按平台注入硬预算而非“尽量运行后碰运气”
- 决策:
src/platforms/shared.mjs中的PLATFORM_LIMITS在请求进入核心网关前注入平台能力与资源上限——Cloudflare16 MiB、EdgeOne Makers1 MiB、阿里云 ESA16 MiB/4次出站fetch/9000ms首包 /115000ms总时长。 - 依据:提前给出可读的结构化
413/503错误,防止在边缘平台强行终止 Isolate 进程前留下半截未完成的状态写入。
ADR-005:自建状态服务强约束与反代 TLS 独立验收
- 决策:
src/self-hosted/server.mjs默认仅监听127.0.0.1:8788,校验DB_PATH文件硬链接nlink === 1与 SQLiteAPPLICATION_ID = 0x4d425331、MODELBRIDGE_STATE_TOKEN与_FILE严格二选一、以及MODELBRIDGE_STATE_ORIGINS精确 HTTPS 来源匹配;并发容器与 HTTPS 反代验收脚本由pnpm run verify:container与pnpm run verify:tls提供。
迁移与容灾 Runbook:从 Cloudflare DO / State-Service 迁往自建 SQLite
仓库内置工具 tools/state-admin.mjs 负责全量配置的离线导出、严格校验导入与在线一致性备份。
1. 从运行中的远程状态端或 state-service 导出配置
需要确保运行导出的机器网络来源在远端 MODELBRIDGE_STATE_ORIGINS 允许列表中(通过 MODELBRIDGE_STATE_EXPORT_ORIGIN 声明精确 HTTPS 来源):
sh
MODELBRIDGE_STATE_URL="https://state.example/_modelbridge/state" \
MODELBRIDGE_STATE_TOKEN="<你的32~512位令牌>" \
MODELBRIDGE_STATE_EXPORT_ORIGIN="https://gateway.example" \
node tools/state-admin.mjs export-remote --out ./migration-config.json导出文件包含明文上游凭据与实例密钥,请存放在受限权限目录中并在迁入后安全清理,切勿提交到 Git 仓库。
2. 导入到全新的自建 SQLite 数据库
import 命令仅向尚未包含配置的全新/空数据库写入数据,且会校验 JSON 大小(<= 16 MiB + 1 KiB)与合法配置结构:
sh
node tools/state-admin.mjs import \
--db ./data/modelbridge.sqlite \
--file ./migration-config.json3. 在线热备份与快照验证
日常运维禁止直接用 cp 拷贝 WAL 运行中的 .sqlite 文件,请始终使用内置 backup 命令生成已合并日志(DELETE 模式)的独立单文件快照:
sh
node tools/state-admin.mjs backup \
--db ./data/modelbridge.sqlite \
--out ./backups/modelbridge-snapshot.sqlite4. 切换边缘网关指向
- 启动
dist/self-hosted-state/(及 TLS 反代)并在MODELBRIDGE_STATE_ORIGINS中加入全部边缘网关的精确 HTTPS 来源。 - 更新
cloudflare-remote/edgeone/esa平台环境变量中的MODELBRIDGE_STATE_URL与MODELBRIDGE_STATE_TOKEN。 - 登录
/admin核对账号列表、apiKeys与自定义模型映射是否完整,并使用新网关发起一次实际推理调用与一次密钥撤销测试验证写链路即时生效。