业务平台服务器管理

业务平台服务器，是小匠对接的 JECloud / JEPaaS 后端实例。本章讲在 /admin/servers 里怎么登记一台业务平台、自动派生 WebSocket、做连通性探测，以及生产 / 测试 / 演示多套环境怎么管。

6.1 入口与全局视图

侧边栏进入「服务器管理」，对应路径 /admin/servers。这里登记的服务器，会作为对话回话时调用平台 API、WebSocket 推送、查数据 / 跑脚本的目标地址。

1. 登录 admin 后台，左侧导航点「服务器管理」
2. 页面顶部只有一档「全部 N」分组 tab（平台分组 JEPaaS 暂未上线，已隐藏）
3. 列表以卡片形式展示已登记服务器：名称 / 短代号 / 服务地址 URL / WebSocket URL / 方案 / 最近更新时间
4. 右上角是「+ 新增服务器」按钮 + 搜索框（搜名称 / 短代号 / URL）+ 刷新

提示： 「默认」服务器是干什么的？用户在 chat 里发起对话、桌面端启动时拉欢迎页、setup 向导未指定时的兜底，都走默认服务器。一套环境通常只设一个默认。

6.2 新增一台业务平台服务器

把一台 JECloud 后端接到小匠，只需要填几个字段。表单字段如下（带 * 必填）。

提示： 「平台类型 jecloud / jepaas」UI 当前已隐藏。JEPaaS 适配未上线，所有新增 server 默认 jecloud；代码里字段保留，等 JEPaaS 真正可用时放开。

1. 点列表右上角「+ 新增服务器」，弹出表单（标题「新增服务器」）
2. 填显示名（中文）、短代号（英文）、粘服务地址 URL
3. WebSocket 地址必填，下一节讲「自动获取」省手敲
4. 方案编码默认填 je（多方案部署再调），勾「启用」与「设为默认」
5. 点底部「新增」（编辑态为「保存修改」）。保存前不自动探测，可用列表行尾的「健康检查」按钮单独跑（见 6.4）

注意： 短代号建立后不能改。它是对话历史、审计日志、桌面端缓存的索引键；编辑表单里该字段直接置灰。要换代号只能新增一台再迁移会话。

6.3 「自动获取」WebSocket 地址

WebSocket 地址通常和 HTTP 服务地址走同一 host，但端口可能不同（平台 jesocket 可能挂别的端口）。admin 提供「自动获取」按钮做两步兜底，省手敲打错。

1. 表单里填好 服务地址 URL（必须是合法 http:// 或 https://）
2. 点 WebSocket 地址输入框右侧的「自动获取」按钮（按钮文案会切「获取中…」）
3. 优先级 1：去平台读声明的 JE_CORE_WEBSOCKETURL（真实地址，端口可能与服务地址不同）
4. 优先级 2：拉不到再按服务地址机械派生 — http:// → ws://、https:// → wss://，host 不变，路径固定 /jesocket
5. 结果会覆盖填入 WebSocket 地址框，可手动改

服务地址:        https://je.example.com
平台声明（优先）: wss://je-ws.example.com:9090/jesocket   ← 端口可能与 https 不同
本地派生（兜底）: wss://je.example.com/jesocket           ← 平台无声明时用此

小贴士： 反向代理后端要注意。如果你的 nginx 没把 /jesocket 走 upgrade 升级到 WebSocket，地址虽然对但连不上——去检查 nginx 的 proxy_set_header Upgrade $http_upgrade; 与 proxy_set_header Connection "upgrade";。

6.4 健康检查（连通性探测）

列表卡片右下角的心跳图标按钮（hover 提示「健康检查」），点一下就跑一次连通性探测。表单保存时不自动探测，需要主动点这个按钮。

1. 找到卡片底部右侧的「健康检查」心跳图标按钮，点一下（按钮会置 disabled 防双击）
2. 页面右上角弹一个 toast 提示，几秒内回出结果
3. 成功：✓ {名称}：…（user_msg 由后端返回）
4. 失败：✗ {名称}：… 或 健康检查失败：{detail}
5. 探测结果不改卡片字段，只在 toast 里反馈一次

6.5 设默认 / 启禁 / 删除

卡片底部直接铺开 4 个操作（没有「⋯」收起菜单）：左侧「设为默认」按钮、右侧 启停开关 + 健康检查 + 删除 三个图标。点卡片空白区进入编辑表单。

1. 设为默认：卡片左下「设为默认」按钮，已默认的会显示「已默认」并置 disabled。同一时间只允许一个默认，切换会把旧默认自动取消
2. 启用 / 停用：右下角开关（SwitchWithLabel），切到关 = 停用。toast 提示「{名称}：已启用 / 已停用」
3. 删除：红色图标按钮。默认服务器不能删（图标置 disabled，点击 toast「默认服务器不能删除，请先把别的设为默认」）；非默认弹确认对话框「确认删除「{显示名}」？此操作不可撤销，关联的登录会话会受影响。」
4. 编辑：点卡片空白处打开编辑表单，短代号置灰，其它字段可改

注意： 默认服务器先把别的设为默认才能删。后端无「会话引用计数」联级检查，只挡 is_default 这一道；提示文案直说「关联的登录会话会受影响」，删除前请自己排查依赖。

6.6 多服务器场景：生产 / 测试 / 演示

实际部署里大多不止一台 server。常见的三套环境分布如下。

1. 三套都登记进 /admin/servers，分别填好 URL 与 WebSocket URL
2. 生产代号设默认，测试 / 演示保持非默认
3. 用户端切换：chat 顶部「会话设置」面板里有 server 选择器，启用的服务器都会列出来
4. 审计日志（/admin/audit）会带上 server code，事后可以按服务器筛

小贴士： 演示环境建议单独 db。演示数据经常被改乱，跟测试 db 混在一起会污染回归测试。一台 server = 一套独立后端 = 一个独立 db，是最干净的边界。

6.7 排查常见连不上

连通性探测红叉时，按下面顺序排查最快。

1. URL 写错：尾部多了 /、协议写成 http 但实际只开了 https、端口漏了——浏览器直接打开 URL 看能否出登录页
2. WebSocket 走不通：HTTP 通但 WS 不通，大概率是反代 upgrade 没配。看 nginx：proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
3. 跨域 / 防火墙：内网 admin 连外网 server，或反过来。看 docker compose 网段、安全组、企业防火墙白名单
4. 证书过期：HTTPS 探测出 SSL 错误，openssl s_client -connect host:443 看下到期时间
5. 平台未起来：服务器本身 jecloud 进程挂了，登服务器 docker ps 看下 jecloud 容器状态

提示： 探测信息只看自己别截外。红叉里带的错误码与堆栈是诊断辅助，不要直接转发给客户——里面可能含内网 IP、容器名等敏感信息。

小贴士： 下一步：配好服务器后 → 让一个业务用户去 chat 登录页「服务地址」下拉里选这个新平台 → 进去发一条消息看是否能跑通。

相关

• 首次启动：setup 向导
• 模型管理
• 提示词管理
• 监控：调用 · 审计 · 系统日志