部署运维与排错 FAQ
本页汇总 ModelBridge 在 Cloudflare Workers / Pages、EdgeOne Makers、阿里云 ESA 与自建 Node.js 24 + SQLite 状态服务上线期间的高频故障及定位方法。
网关启动与权限配置类问题
Q:访问 /admin 登录或调用 /api/* 返回 503 Service Unavailable?
原生 DO 模式与远程网关模式在缺少必要依赖时均会直接拒绝服务(Fail Closed),不会降级为内存或无鉴权模式:
- 检查运行平台是否已配置
ADMIN_PASSWORD(去掉首尾空白后非空)。 - 原生 DO 模式:检查
wrangler.toml是否同时绑定了CONFIG_STORE(指向AppConfigStore)与KV。若将代码部署至 Cloudflare Pages 并引用外部 Worker 的 DO,确认durable_objects.bindings已设置script_name。 - 远程网关模式(
cloudflare-remote、edgeone、esa):检查MODELBRIDGE_STATE_URL与MODELBRIDGE_STATE_TOKEN是否均已作为运行时 Secret 注入。
Q:远程网关读写配置失败,日志出现 401 或 Origin 被状态服务拒绝?
src/state/service.mjs 与 src/self-hosted/server.mjs 对服务间 RPC 实施双重校验:
- 来源精确匹配:状态服务校验请求头中的来源与
MODELBRIDGE_STATE_ORIGINS列表。MODELBRIDGE_STATE_ORIGINS必须是逗号分隔的精确 HTTPS Origin(如https://gw1.example,https://gw2.example),不能包含尾部/、子路径或*通配符。 - 令牌一致与格式校验:
MODELBRIDGE_STATE_TOKEN必须为 32–512 位无空白可见 ASCII 字符,且网关侧与状态服务侧完全一致。 - URL 固定路径:网关侧
MODELBRIDGE_STATE_URL必须以/_modelbridge/state结尾,不接受查询参数、fragment 或user:pass@用户信息。
Q:自建状态服务启动直接报错退出(拒绝加载配置或数据库)?
逐项排查 src/self-hosted/server.mjs 与 src/state/sqlite.mjs 的安全前置条件:
MODELBRIDGE_STATE_TOKEN与MODELBRIDGE_STATE_TOKEN_FILE必须且只能设置其一,同时设置或均缺失都会报错。MODELBRIDGE_STATE_PUBLIC_ORIGIN必须是精确的https://...来源(不能带/、路径或端口以外多余成分)。DB_PATH若指向已存在的文件,其硬链接计数必须为nlink === 1,且 SQLite 头中的APPLICATION_ID必须匹配0x4d425331(空库或新建库会自动初始化,非 ModelBridge 数据库文件会被拒绝覆盖)。
边缘平台预算与反代问题
Q:EdgeOne Makers 部署后请求体报 413 Payload Too Large,或提示找不到静态目录?
- 请求体预算:EdgeOne Makers 适配器(
src/platforms/edgeone.mjs)通过PLATFORM_LIMITS.edgeone将单次入口请求体限制在1 MiB(Cloudflare 与 ESA 为16 MiB),超大 Base64 图片或多轮长上下文会直接触发413。超出此预算请改用 Cloudflare Workers、ESA,或精简上下文长度。 - 静态产物路径:
deploy/edgeone/edgeone.json配置了"outputDirectory": "./public",构建脚本node tools/build-platforms.mjs会在dist/edgeone/public/生成占位静态目录;请基于dist/edgeone/整目录部署,避免手动删空public/导致 Makers 构建失败。
Q:阿里云 ESA 频繁触发 503 platform_subrequest_limit 或超时中断?
src/platforms/esa.mjs 通过 PLATFORM_LIMITS.esa 明确约束了单次请求的运行时预算:
- 单次请求最多
4次外部fetch。注意:远程状态读取、Antigravity OAuth token 刷新、上游重试候选(最多尝试 3 个账号)以及末尾用量统计都会消耗子请求额度。在 ESA 上若配置多个失效账号引发连续重试或同时叠加远程用量写入,极易触及第 4 次上限。 - 解决建议:保证 ESA 上的首选上游账号凭据健康有效;控制候选账号数量避免无效链式重试;并留意 ESA 首包超时
9000ms与总执行时间115000ms预算,避免给极慢的推理链路分配过多超时等待。 - 入口文件:
deploy/esa/esa.jsonc使用"entry": "./worker.js",不要用根目录_worker.js直接覆盖dist/esa/worker.js。
Q:为什么前端或管理面板有时报错,状态却像被“重新执行了一遍”?
检查你放在状态服务或自建网关前面的反向代理(Nginx / Caddy / 云 WAF):
- 代理层绝不能对状态服务
/_modelbridge/state或推理路由开启自动重试(Caddy 模板deploy/self-hosted-state/Caddyfile明确设置了lb_retries 0)。 - 确保反代对状态服务使用 HTTP/1.1(Caddy 中为
protocols h1)并透传原始协议与真实来源。
自建 SQLite 运维与备份问题
Q:可以直接用 cp 拷贝正在运行的 .sqlite 文件做热备份吗?
不建议直接拷贝主文件。自建状态库运行在 WAL 模式(synchronous = FULL)下,未 checkpoint 的事务写入位于 -wal 伴生文件中,直接复制主 .sqlite 文件会丢失最近提交或导致快照不一致。
请使用内置维护工具执行在线安全快照:
sh
node tools/state-admin.mjs backup --db ./data/modelbridge.sqlite --out ./backups/modelbridge-$(date +%F).sqlitetools/state-admin.mjs backup 会调用 node:sqlite 的在线 backup() API 生成独立事务快照,并将输出切换为 DELETE 日志模式后通过唯一临时目录与排他硬链接发布(避免覆盖既有文件或受到硬链接篡改)。
Q:如何从 Cloudflare DO 在线迁出配置并导入自建 SQLite?
完整步骤与容量边界说明请参见 关键架构决策与迁移。
下一步
- 核对协议端点的请求体限制、模型映射优先级与错误码格式,请参阅 接口、安全与路由契约。