配置自定义服务器域名与 HTTPS

XHIM 推荐一个环境只使用一个公开域名，例如：

text

https://im.customer.example

这个域名同时承载 HTTP API、WebSocket、媒体上传、媒体下载和管理后台。客户端开发者只填写一个 XHIM Server URL，不需要分别维护多组地址。

1. 先完成 DNS 与端口准备

在 DNS 控制台添加 A 记录，把域名指向服务器公网 IPv4；使用 IPv6 时再加 AAAA 记录。
在云安全组和服务器防火墙中放行 TCP 80、443。
保持 XHIM 只监听 127.0.0.1:18080。
不要把 PostgreSQL、Redis、对象存储管理端口或 18080 暴露到公网。

可以先检查解析结果：

bash

dig +short im.customer.example

DNS 还没有指向当前服务器时，不要申请证书或切换客户端地址。

2. 配置 XHIM 的公开地址

编辑 server/.env。同一个域名使用下面四项配置，WebSocket 路径必须是 /v1/realtime：

dotenv

XHIM_ENDPOINT_REVISION=customer-domain-v2
XHIM_PUBLIC_API_URL=https://im.customer.example
XHIM_PUBLIC_WEBSOCKET_URL=wss://im.customer.example/v1/realtime
XHIM_PUBLIC_UPLOAD_URL=https://im.customer.example
XHIM_PUBLIC_MEDIA_URL=https://im.customer.example

XHIM_SERVER_BIND_ADDRESS=127.0.0.1
XHIM_TRUST_PROXY_HEADERS=true

如果 Web 应用部署在另一个域名，再配置允许的浏览器来源：

dotenv

XHIM_ALLOWED_ORIGINS=app.customer.example,admin.customer.example

填写精确的 host[:port]，不要带 https:// 和路径。与 XHIM 同域的网页不需要重复填写；Production 禁止使用 *。

修改后重启服务：

bash

cd server
docker compose --env-file .env up -d server

只修改域名不需要重新编译 IM 内核，也不需要轮换 Token 签名密钥。提升 XHIM_ENDPOINT_REVISION 是为了让客户端明确识别新的接入配置。

3. 宝塔配置

在宝塔面板中：

打开网站，新增站点 im.customer.example；
打开站点的 SSL，申请 Let's Encrypt 或上传组织证书；
开启强制 HTTPS；
打开 反向代理，目标地址填写 http://127.0.0.1:18080；
在站点 Nginx 配置中确认存在下面的 location /。

nginx

location / {
    proxy_pass http://127.0.0.1:18080;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
    proxy_request_buffering off;
    client_max_body_size 256m;
}

256m 与 XHIM 当前单个媒体文件上限一致。设置更小会让 Nginx 在请求到达 XHIM 之前返回 413 Request Entity Too Large。proxy_request_buffering off 可以避免 Nginx 先把大文件完整写入临时目录。

只有反向代理与 XHIM 位于同一台受控主机，且 XHIM 只监听回环地址时，才启用 XHIM_TRUST_PROXY_HEADERS=true。

4. Caddy 配置

如果不用宝塔/Nginx，Caddy 可以自动申请和续期公网证书：

caddyfile

im.customer.example {
    reverse_proxy 127.0.0.1:18080
}

运行 Caddy 的主机必须能从公网接收 80/443，DNS 也必须已经生效。仓库中的 server/deploy/Caddyfile 使用内部 CA，只用于本机开发，不要直接用于公网域名。

5. 验证域名

先验证 XHIM 本机入口，再验证公网入口：

bash

curl -fsS http://127.0.0.1:18080/health/ready
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 | jq .

然后打开：

text

https://im.customer.example/admin/

最后必须用真实 SDK 登录并完成一次实时连接、双向文字消息和附件上传下载。普通 curl 不能代替带用户凭证的 WebSocket 验收。

6. 更换域名

更换域名时按下面的顺序操作，避免客户端同时失联：

为新域名添加 DNS 并签发证书；
保持旧域名继续可用；
更新四个 XHIM_PUBLIC_*_URL 和 XHIM_ENDPOINT_REVISION；
重启 XHIM，验证新域名的健康、管理后台、登录、WSS 和收发消息；
发布新的客户端接入配置；
等待 DNS TTL 和活跃客户端迁移完成后，再下线旧域名。

如果只是改域名，不要轮换数据库密码、管理员密码和签名密钥。把多项变更拆开，出现问题时更容易回滚。

常见问题

现象	原因与处理
HTTPS 证书申请失败	DNS 未生效、80/443 未开放，或域名已被另一台服务器占用
`502 Bad Gateway`	XHIM 未就绪、代理目标写错，或 XHIM 没有监听 `127.0.0.1:18080`
API 正常但 WebSocket 断开	缺少 Upgrade 请求头，或代理读取超时过短
Web 页面提示 CORS	把 Web 页面的精确来源加入 `XHIM_ALLOWED_ORIGINS` 并重启
附件上传返回 413	`client_max_body_size` 小于 `256m`，或上层 CDN/负载均衡仍有限制
客户端仍连接旧域名	`XHIM_ENDPOINT_REVISION` 未提升，或客户端仍在使用旧 Server URL
管理后台循环登录	代理未传 `X-Forwarded-Proto https`，或浏览器保存了旧域名 Cookie

部署完成后，继续阅读快速部署的公网验收和生产发布、升级与回滚。

配置自定义服务器域名与 HTTPS ​

1. 先完成 DNS 与端口准备 ​

2. 配置 XHIM 的公开地址 ​

3. 宝塔配置 ​

4. Caddy 配置 ​

5. 验证域名 ​

6. 更换域名 ​

常见问题 ​

配置自定义服务器域名与 HTTPS

1. 先完成 DNS 与端口准备

2. 配置 XHIM 的公开地址

3. 宝塔配置

4. Caddy 配置

5. 验证域名

6. 更换域名

常见问题