错误码说明

License 与授权

现象	含义	怎么办
启动时报 License 校验失败	文件损坏、与组织不匹配，或被改过（离线签名验不过）	用原始 License 文件重新导入，不要手工编辑
提示席位已满	成员数达到 License 上限	走维保流程重新签发
提示已过期，只读	License 到期，进入降级模式	续费签发新 License；期间数据仍可读取与导出
客户端连上但组织异常	License 里的组织与实例不匹配	核对是否把测试环境的 License 用到了生产

不要试图修改 License 内容。 它是签名的，改一个字节就验不过——而且这类失败看起来像”系统坏了”，很难第一时间想到是 License 被改过。

部署与依赖

现象	含义	怎么办
容器起不来，日志报镜像缺失	离线镜像没全部 docker load	按清单逐个导入，注意依赖镜像
启动时报数据库连接失败	连接串、用户名、库不存在，或网络策略阻断	先用 psql 手工连一次，排除应用层因素
迁移执行失败	数据库已存在不兼容的结构	迁移只增不改、可重复执行；失败通常是手工改过表结构，先比对
/healthz 不通	服务没起来，或反向代理没转发	先在容器内 curl 127.0.0.1:PORT/healthz，再查代理
客户端报证书错误	内网 CA 未被客户端信任	把内部 CA 装进系统信任库，或换公网可信证书

内网连通

现象	含义	怎么办
客户端一直连不上	XBB_API_BASE 没配，或还在连公有云默认地址	检查客户端 MCP 配置里的 env
能连但检索超时	客户端到服务端的网络策略（防火墙、代理）	从客户端机器 curl 一下服务端地址
部分成员能用、部分不能	网段策略差异	对比两台机器的出口与 DNS

检索能力

现象	含义	怎么办
检索只命中字面词、换个说法就找不到	向量能力未启用，走了关键词模式	检查向量模型文件是否随包部署；管理窗口会显示当前检索模式
检索明显变慢	库很大，或数据库索引/内存不足	先看库规模，再看 PG 的 shared_buffers

与公有版一致的码

这些在私有化环境里同样会出现，含义不变：

E_VALIDATION（入参不合法）、E_NOT_FOUND（找不到或无权可见）、E_SPACE_FORBIDDEN（越界授权）、E_NOT_MEMBER、E_MEMBER_DISABLED、E_INVITE_*、E_INTERNAL。

完整解释见企业云端版 · 错误码说明——两版的行为定义是同一份。

排查前先拿四个事实

xbb version     # 客户端版本
xbb cloud       # 当前模式 + 绑的组织 + API 地址

再加两项环境事实：

• 服务端容器是否都在跑（docker compose ps）；
• 客户端机器能否访问服务端地址（curl）。

这四项能覆盖绝大多数”看起来很奇怪”的情况，尤其是升级后突然不通——十次有八次是 env 里的地址还指向旧实例。

反馈时请带上

现象、发生时间、docker compose logs 的相关片段、客户端 xbb version。

不要贴 License 文件内容，也不要贴数据库连接串明文——排障不需要它们。