API 域名与环境

Open API 部署在你自己的环境（私有化/自托管），没有固定的公有云域名。调用地址由三部分组成：部署域名 + 路径前缀 /im/v2 + 接口路径；例如 https://im.example.com/im/v2/user/register。

私有化部署地址​

环境示例地址说明
本地开发 / 自测http://127.0.0.1:8080服务端缺省监听 127.0.0.1:8080；启动时设置 IM_ADDR 可改端口（例如 18080），示例中的地址需同步替换
测试 / 预发https://im-test.example.com建议与生产同构：反向代理 + HTTPS + 独立应用与密钥
生产（私有化）https://im.example.com对外只暴露 HTTPS；证书、限流、鉴权审计在网关层完成
内网服务调用http://im.internal:18080仅限可信内网；跨网调用请使用 HTTPS 或专线
生产环境请使用 HTTPS

当前仓库内的本地演示部署默认无 TLS、无反向代理，仅用于本机或可信内网。生产环境请在 IM Server 前置反向代理并强制 HTTPS。

路径前缀​

路径前缀
/im/v2

所有 Open API 的路径都以 /im/v2 开头；接口文档中的“路径”列展示的是相对路径，完整请求地址 = {部署地址}/im/v2{接口路径}。

接口完整请求地址示例
user.registerhttps://im.example.com/im/v2/user/register
message.private.publishhttps://im.example.com/im/v2/message/private/publish
callback.delivery.listhttps://im.example.com/im/v2/callback/delivery/list

X-Request-Id​

响应信封中的 requestId 用于串联请求与日志。调用方可以通过可选请求头 X-Request-Id 指定追踪 ID；缺省、为空或超过 128 字符时由服务端生成，响应中回声该值。

Shell
curl -sS -X POST "https://im.example.com/im/v2/user/register" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req_7f3a9c" \
  -H "App-Key: demo" -H "Nonce: 9f2a7c1b" \
  -H "Timestamp: 1750000000000" -H "Signature: 372e885320aabd997aafc5491f9d90fdca94432e" \
  -d '{"userId":"user1","name":"Alice"}'
JSON
{
  "code": 0,
  "data": {
    "userId": "user1",
    "name": "Alice",
    "createdAt": 1750000000000
  },
  "requestId": "req_7f3a9c"
}

协议与网络​

  • Open API：HTTP/1.1 或 HTTP/2，POST + JSON；生产环境建议 HTTP/2 与 TLS 1.2+。
  • 客户端长连接使用另一套端点（WebSocket /ws），与 Open API 分离部署或复用同一反向代理。
  • 反向代理需透传请求头（App-Key / Nonce / Timestamp / Signature / X-Request-Id），并确保请求体不被改写。
  • 如使用 CDN/WAF，请将 Open API 路径排除在缓存之外，避免 POST 请求被缓存。

相关说明​