版本与发布

版本与发布说明“当前这套服务端/契约是什么版本、怎么确认部署一致”。自托管版没有在线发布/灰度/回滚控制台；版本由代码与 IDL 冻结修订决定，运行时通过 /health 与 /api/__contract/introspect 自证。

概念​

项值 / 入口说明
IDL 版本v1.0.0冻结修订号以 /docs/changelog 为准
运行时自省GET /api/__contract/introspect返回运行时 operation/事件/错误码，供契约校验器比对
健康检查GET /health{"ok":true}
构建信息启动日志 / 进程版本二进制版本随发布包；无在线版本 API
发布方式替换二进制 + 重启停机会断开 WS；客户端自动重连
  • 契约兼容策略是 additive-only：v1.x 只新增可选字段/接口/事件/错误码，不改语义。
  • 升级前用运行时自省接口比对运行时与契约是否一致。
  • 没有“发布审批/灰度/一键回滚”控制台功能；回滚即换回旧二进制与匹配的数据目录。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#apiconfig（tab #apiconfig：服务与 API 配置）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 确认当前版本

    读 manifest 的 idlVersion/freezeRevision，并调用 introspect 对比。

  2. 升级前备份

    备份 IM_DATA_DIR；确认新版本的数据格式兼容（additive-only）。

  3. 替换并重启

    停止旧进程、替换二进制、以相同环境变量启动；观察 /health。

  4. 升级后校验

    跑契约校验与冒烟；确认客户端重连、消息收发与回调正常。

参数表​

操作方法与路径参数
健康检查GET /health—
运行时契约GET /api/__contract/introspect—
契约清单契约清单（IDL manifest）文件（非 HTTP）
更新日志/docs/changelog页面

示例​

确认部署版本与契约​

Shell
curl -sS http://127.0.0.1:8080/health

curl -sS http://127.0.0.1:8080/api/__contract/introspect | jq '{idlVersion, operations: (.operations|length), errors: (.errors|length)}'

curl -sS -H "X-Admin-Secret: dev-admin" http://127.0.0.1:8080/api/__contract/introspect | jq '{idlVersion, operations: (.operations|length), errors: (.errors|length)}'

常见问题​

有在线版本/发布 API 吗？​

没有。版本随二进制与 IDL 冻结修订，控制台不提供发布操作。

升级会丢数据吗？​

按 additive-only 兼容策略不应丢；仍建议先备份 IM_DATA_DIR。

如何确认文档与运行时代码一致？​

用 contract-check 比对 introspect 与 IDL；文档由同一 IDL 生成。

回滚怎么做？​

停服、换回旧二进制、使用匹配的数据目录启动；没有控制台一键回滚。

相关链接​