XHIM Developer

主题

XHIM Server 非 Docker 部署 ​

本页面向不使用 Docker 的 Linux 运维人员。服务端使用单个 Go 二进制、PostgreSQL、systemd 和现有 Nginx/Caddy/宝塔反向代理即可运行。 客户端开发者不需要阅读本页。

1. 主机与目录 ​

推荐 Ubuntu 24.04 LTS 或客户已经维护的同等 Linux 发行版。先由 root 创建专用低权限账号和目录：

bash
useradd --system --home /var/lib/xhim --shell /usr/sbin/nologin xhim
install -d -o xhim -g xhim -m 0750 /var/lib/xhim /var/lib/xhim/media
install -d -o root -g xhim -m 0750 /etc/xhim
install -d -o root -g root -m 0755 /opt/xhim/bin

不要用 root 身份运行 XHIM，也不要把服务端放在网站可下载目录。

2. PostgreSQL ​

在 PostgreSQL 16 或更高版本中创建专用角色和数据库。以下只是 psql 中的命令结构，密码必须由客户的密钥系统生成：

sql
CREATE ROLE xhim LOGIN PASSWORD 'REPLACE_WITH_RANDOM_PASSWORD';
CREATE DATABASE xhim OWNER xhim ENCODING 'UTF8';
REVOKE ALL ON DATABASE xhim FROM PUBLIC;

生产环境应开启 PostgreSQL TLS、PITR/WAL 归档和每日加密备份。不要在 URL 中使用 sslmode=disable。

3. 构建不可变二进制 ​

在审核过的 CI 或构建机执行：

bash
cd server
go test ./...
CGO_ENABLED=0 go build -trimpath \
  -ldflags "-s -w -X main.version=VERSION -X main.commit=FULL_COMMIT" \
  -o xhim-server ./cmd/xhim-server
sha256sum xhim-server

将二进制、SHA-256、SBOM、签名和对应的 Git Commit 一起交付。在 目标主机校验签名和 Hash 后，安装为：

bash
install -o root -g root -m 0755 xhim-server /opt/xhim/bin/xhim-server

4. 配置 ​

复制 xhim-server.env.example 到 /etc/xhim/xhim-server.env，替换所有 REPLACE_ME，然后：

bash
chown root:xhim /etc/xhim/xhim-server.env
chmod 0640 /etc/xhim/xhim-server.env

生产环境禁止开启 Development Login。Admin API Key、管理后台 Session Key、JWT 签名私钥、Cursor Key、Media URL Key、Push/OA Webhook Secret 必须来自密钥系统，不能进入 Git、安装包、客户端或宝塔截图。 管理后台使用 XHIM_ADMIN_USERNAME 和密码登录，环境文件只保存 XHIM_ADMIN_PASSWORD_BCRYPT_BASE64，不保存明文密码。初始生成与密码旋转操作见 服务端文档。

5. systemd ​

安装 xhim-server.service：

bash
install -o root -g root -m 0644 xhim-server.service \
  /etc/systemd/system/xhim-server.service
systemctl daemon-reload
systemctl enable --now xhim-server
systemctl status xhim-server --no-pager
journalctl -u xhim-server -n 100 --no-pager

XHIM 启动时自动执行嵌入式数据库 Migration。上线前仍必须先做加密 备份和隔离恢复演练，不能把“启动成功”当成可恢复性证明。

6. 宝塔 / Nginx 反向代理 ​

在宝塔中创建 im.customer.example 站点并申请证书，将站点转发到 http://127.0.0.1:18080。必须同时支持 HTTP API 和 WebSocket：

首次配置域名时建议直接按 配置自定义服务器域名与 HTTPS 操作；下面保留非 Docker 安装所需的等价 Nginx 片段。

nginx
location / {
    proxy_pass http://127.0.0.1:18080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
    proxy_request_buffering off;
    client_max_body_size 256m;
}

宝塔/Nginx 里需要先定义 map $http_upgrade $connection_upgrade；如果面板不允许 修改 http 级别配置，可将 Connection 固定为 upgrade。只有反代与 XHIM 同机且监听 loopback 时才开启 XHIM_TRUST_PROXY_HEADERS=true。 256m 与当前 IM 内核的单个媒体文件上限一致；更小的代理限制会在请求到达 XHIM 前直接返回 HTTP 413。

7. 交付前验证 ​

bash
curl -fsS https://im.customer.example/health/live
curl -fsS https://im.customer.example/health/ready
curl -fsS https://im.customer.example/v1/sdk/config

还必须用真实客户端 Token 验证：登录、WSS Upgrade、发文字、发附件、 两个账号收发和断线重连。如果没有这份客户端 E2E 证据，发布状态 只能记录为“服务启动，业务待验收”。

8. 升级与回滚 ​

  1. 备份 PostgreSQL 和当前二进制；
  2. 在隔离库跑 Migration 和 N/N-1 兼容性验证；
  3. 安装为 /opt/xhim/bin/xhim-server.next，校验签名与 Hash；
  4. 原子替换二进制后 systemctl restart xhim-server；
  5. 验证 health/config/WSS/真实收发；
  6. 异常时先停止流量，根据 Migration 兼容报告回滚二进制或恢复数据库。

不能在未证明新版就绪时删除旧二进制或备份。

XHIM 客户端 SDK 与服务端文档

© 2026 晞晗软件 · Xihan Software