部署与配置：KV 命名空间、KV_BASE_URL 与常见排障
这篇写给“已经一键部署了，但总有一个环节不工作”的你。
在这个项目里，部署的坑往往不是“构建失败”，而是：
- KV 命名空间没绑定全
KV_BASE_URL没配（或配错）- 内部鉴权 key 不一致
这些问题的共同点是：表现很像业务 bug，但其实是环境问题。
必备 KV 命名空间（少一个都不行）
部署时需要绑定至少以下 KV：
CONFIG_KVCHANNELS_KVAPPS_KVOPENIDS_KVMESSAGES_KV
它们分别存储：
- 系统配置、token 缓存
- 渠道配置
- 应用配置与索引
- 绑定用户信息
- 消息历史
如果你少绑了其中任何一个，系统可能还能“部分可用”，但你会遇到各种随机失败。
KV_BASE_URL：别赌同源推断
项目的 KV 读写是通过 Edge Functions 代理完成的（Node Functions -> HTTP -> Edge Functions）。
这意味着 Node Functions 需要知道“对外可访问的 baseUrl”，才能拼出：
{baseUrl}/api/kv/...
因此你几乎总是应该显式配置：
KV_BASE_URL=https://your-domain.com
如果不设置，典型现象是：
- 同源推断失败
- 走到错误的 host
- 进而导致 “KV get failed / fetch error”
内部鉴权 key（X-Internal-Key）：KV 代理的门禁
KV 代理 API 通过 X-Internal-Key 做“内部调用鉴权”。
在本地调试时常见是：
.env.local提供INTERNAL_DEBUG_KEY
在构建/生产环境使用构建时生成的密钥（见 node-functions/shared/kv-client.ts 引入的 internal-key.json）。
如果 key 不一致，你会看到一个非常“统一”的症状：
- 所有 KV 操作都失败（看起来像服务全挂了）
一张排障决策树：优先定位“是哪一跳坏了”
flowchart TD
A["请求失败/功能异常"] --> B{是所有接口都失败吗?}
B -->|是| C[优先检查 KV 代理链路]
B -->"|"否"| D["按功能定位：send/绑定/渠道/token"]
C --> C1{KV_BASE_URL 是否正确?}
C1 -->|否| C2[修正为完整 https 域名]
C1 -->"|"是"|" C3{ /api/kv/* 可访问吗? }
C3 -->"|"否"| C4["检查 Edge Functions 部署/路由"]
C3 -->|是| C5{ X-Internal-Key 是否一致? }
C5 -->"|"否"| C6["检查 INTERNAL_DEBUG_KEY/构建 key"]
C5 -->|"是"| C7[检查 KV 命名空间绑定是否齐全]
经验建议（减少未来排障成本）
- 把
KV_BASE_URL当成“必填项”写进你的部署 checklist。 - 第一次部署完成后，优先验证：
- 能否读写 KV
- 能否获取 token（渠道验证）
- 能否写入消息历史
- 一旦你拥有“历史记录”，排障会简单很多：你能把失败归类成“配置问题/权限问题/网络问题”。