XHIM Developer

主题

XHIM Server 快速部署（Docker） ​

本页用于第一次部署 XHIM Server。完成后，你会得到：

  • 一个可以从手机、桌面端和 Web 访问的 XHIM Server URL；
  • 自动生成且不会写入源码的服务端密钥；
  • 一个可登录的管理后台；
  • 可供 Demo 注册、登录和收发消息的 Development 环境。

这条路径适合开发、验收和客户联调。正式生产环境还必须完成数据库备份、对象 存储、Push、监控、密钥托管和回滚演练，见 生产发布、升级与回滚。

1. 部署前准备 ​

准备一台 Linux 服务器，并确认：

  • 已安装 Docker Engine 和 Docker Compose v2；
  • 域名（例如 im-test.customer.example）已经解析到这台服务器；
  • 公网防火墙放行 TCP 80 和 443；
  • 服务器上没有把 PostgreSQL 或 XHIM 的 18080 端口直接暴露到公网；
  • 已取得 XHIM 源码或正式交付包。

如果暂时没有域名，可以先在同一局域网联调，见 服务端概览中的局域网联调。 公网环境不要使用明文 HTTP。

2. 生成联调配置 ​

在 XHIM 项目根目录执行。把示例域名换成你自己的域名：

bash
cd /path/to/xhim

scripts/dev/configure_server_env.sh \
  --host im-test.customer.example \
  --port 443 \
  --enable-development-login

脚本会：

  1. 生成 server/.env，供服务端和 Docker Compose 使用；
  2. 生成 server/.env.client，只包含客户端可公开使用的接入参数；
  3. 在终端显示一次初始管理员账号和密码。

请立即把管理员密码保存到密码管理器。两个 .env 文件都已被 Git 忽略，不要 上传到代码仓库、聊天工具或工单截图。

如果 server/.env 已存在，脚本会停止，避免覆盖现有密钥。只有在明确要让旧 Token 和旧签名配置失效时才使用 --force。

3. 启动数据库和服务端 ​

使用宝塔、Nginx、Caddy 或云负载均衡提供公网 HTTPS 时，只启动 PostgreSQL 和 XHIM Server；仓库里的 gateway 是本机开发用的内部证书入口，不用于公网域名。

bash
cd server

docker compose --env-file .env up -d --build postgres server
docker compose --env-file .env ps
curl -fsS http://127.0.0.1:18080/health/ready

最后一条命令成功，说明服务端已经在本机回环地址就绪。此时公网还不能访问， 下一步需要把域名反向代理到 127.0.0.1:18080。

4. 配置域名与 HTTPS ​

按 配置自定义服务器域名与 HTTPS 完成以下操作：

  1. 为域名申请有效的公网证书；
  2. 把域名的 HTTPS 流量反向代理到 http://127.0.0.1:18080；
  3. 启用 WebSocket Upgrade；
  4. 把代理上传上限设置为 256m；
  5. 只开放 80/443，不要开放 PostgreSQL 和 18080。

5. 验证公网服务 ​

把域名替换成实际值：

bash
curl -fsS https://im-test.customer.example/health/live
curl -fsS https://im-test.customer.example/health/ready
curl -fsS https://im-test.customer.example/v1/sdk/config | jq '{
  schema_version,
  environment,
  development_phone_auth_enabled,
  server_version
}'

预期结果：

  • health/live 和 health/ready 返回成功；
  • environment 为 development；
  • development_phone_auth_enabled 为 true；
  • 浏览器打开 https://im-test.customer.example/admin/ 能看到登录页。

随后用仓库中的 Demo 或任一正式 SDK 验证：

  1. 注册或登录两个测试账号；
  2. 两个账号建立会话；
  3. 双向发送一条文字消息；
  4. 断开网络后重新连接，确认历史消息仍然存在；
  5. 上传一个附件，确认发送方和接收方都能打开。

只有健康检查和上述真实客户端链路都成功，才算完成联调部署。

6. 交付给客户端开发者 ​

客户端开发者只需要以下信息：

text
XHIM Server URL: https://im-test.customer.example
Login Mode: Development Easy Login
Test Accounts: 由服务端负责人创建或开放注册

不要向客户端提供 Admin Key、Business Key、数据库地址、管理员密码或任何签名 私钥。API、WebSocket、上传和下载地址由服务端配置统一管理，客户端接入时只需 填写一个 XHIM Server URL。

常见问题 ​

现象先检查什么
域名打不开DNS 是否指向当前服务器，80/443 是否放行
返回 502curl http://127.0.0.1:18080/health/ready 是否成功，容器是否健康
浏览器提示证书错误证书是否覆盖当前域名，证书链是否完整
App 能请求 API 但收不到实时消息反向代理是否保留 Upgrade 和 Connection 请求头
Web 端被 CORS 拒绝把 Web 站点的精确 host[:port] 加入 XHIM_ALLOWED_ORIGINS 后重启服务
上传附件返回 413代理的 client_max_body_size 是否为 256m
管理员账号登录失败确认使用首次生成的密码；不要用旧环境的密码登录新数据库
修改域名后客户端仍访问旧地址更新四个公开地址、提升 XHIM_ENDPOINT_REVISION、重启服务并重新获取接入配置

转为生产环境前 ​

不要直接把 Development 配置改名后上线。生产发布至少需要完成：

  • 使用 XHIM_SERVER_ENV=production，并关闭 Development Login；
  • PostgreSQL TLS、加密备份、PITR 和恢复演练；
  • 私有 S3/S3-compatible 媒体存储；
  • APNs、FCM、Huawei Push Kit 或经审核的 Push Provider；
  • 业务登录换取 XHIM 用户凭证，不向 App 下发 Business Key；
  • 密钥系统、证书续期、监控告警和容量评估；
  • 不可变制品、升级前备份、发布后真实客户端验证和可执行回滚。

完整流程见 生产发布、升级与回滚；不使用 Docker 时见 非 Docker 部署，多副本生产部署见 Kubernetes / Helm 高可用部署。

XHIM 客户端 SDK 与服务端文档

© 2026 晞晗软件 · Xihan Software