Skip to content

HuLa:公网 IM 全栈部署实战 ​

案例概览 ​

HuLa 即时通讯系统的全栈公网部署,2026-11-18 完成并通过真实 UI 验收。后端是 Java Spring Cloud 微服务(HuLa-Server),前端是 Vue 3 + Tauri 的 HuLa(web 模式构建),全部运行在内网 Linux 上,通过 frp 内网穿透经阿里云公网机对外提供 HTTPS 服务;对象存储 MinIO、中继 coturn、流媒体 SRS 一并公网化。

项值
公网入口阿里云 47.118.23.26(frps)
业务主机内网 Linux 192.168.31.97(frpc,frpc.service 常驻)
前端域名hula.miwangdb.com(静态站)
API 域名hula-api.miwangdb.com(反代到 gateway 18760)
HTTPS 证书在 .97 的 1panel OpenResty 上终结
后端6 个 systemd 微服务,JDK 25,Nacos 注册/配置中心

网络拓扑 ​

text
        公网用户 (浏览器 / Android APK)
                 |
                 | HTTPS 443 / HTTP 80 / SSH 22
                 v
   +-----------------------------------+
   | 阿里云 47.118.23.26   frps          |
   | TCP 22/80/443/18504                |
   | UDP 3478 + 49160-49200 (coturn)    |
   | UDP 8000 (SRS)                     |
   +-----------------------------------+
                 ^
                 | frp 隧道(frpc 主动外连)
                 v
   +-----------------------------------+
   | 内网 Linux 192.168.31.97  frpc     |
   |                                   |
   | 1panel OpenResty (HTTPS 证书)      |
   |   hula.miwangdb.com     -> 静态站  |
   |   hula-api.miwangdb.com -> :18760 |
   |                                   |
   | hula-gateway :18760               |
   | hula-oauth / base / system /      |
   | im / ws  (systemd, JDK 25)        |
   | Nacos / MinIO / coturn / SRS      |
   +-----------------------------------+

frp 转发 TCP 22/80/443/18504,以及 coturn 的 42 条 UDP(3478 + 49160-49200)和 SRS 的 UDP 8000。注意 frpc 从 loopback 向本机服务转发,这一点直接导致了后文 coturn 中继候选的坑。

后端与前端组成 ​

后端六个微服务全部由 systemd 托管,jar 统一放在 /srv/apps/hula/<svc>/app.jar,JDK 25,注册与配置走 Nacos:

systemd 服务职责
hula-gateway网关,监听 18760,API 域名的反代目标
hula-oauth认证授权
hula-base基础服务(含 base_config 配置表)
hula-system系统管理
hula-imIM 业务
hula-wsWebSocket 长连接

前端 HuLa 以 web 模式构建(feat/web-mode 分支,pnpm 构建),产物为静态站,由 OpenResty 托管。

项目与任务的划分 ​

deploy 侧一共三个项目、四个任务。项目负责「构建 + 部署」的可重复流水线(Git 准备开启);任务负责一次性运维作业(无 Git、无依赖):

名称形态内容
hula-server-build项目拉 gitee.com/ppnt/HuLa-Server master,Maven 构建
hula-server-start项目发布 jar 到 /srv/apps/hula/<svc>/ 并重启对应 systemd 服务
hula-web项目拉 ppnt/HuLa feat/web-mode,pnpm 构建并发布静态站
hula-recon任务13 步环境勘察
hula-oss-config任务MinIO 公网直传配置
hula-ice-config任务coturn / ICE 配置
hula-srs-config任务SRS 公网化配置

这四个任务最初被误建为项目,后来才迁移为任务并归档旧项目。这是「项目 vs 任务」划分的真实教训:勘察与配置类作业没有源码、不需要 Git 准备、也不该出现在依赖编排里,建成项目只会让项目列表和运行语义变得混乱。迁移方法见从项目迁移到任务,概念边界见核心概念。

更新流程 ​

日常更新只有两步,构建必须发生在 deploy-server 上,本地不上传构建产物:

bash
# 1) 本地开发完成后 push 到 Gitee
git push origin master        # 或 feat/web-mode

# 2) 在 deploy 上运行对应项目(Git 准备会拉取最新提交)
deploy run hula-server-build --wait
deploy run hula-server-start --wait
deploy run hula-web --wait

平台的 Git 准备保证每次运行对应远端分支的当前提交;运行终态与日志遵循统一的运行生命周期。

经验与坑 ​

命令 ID 与步骤 ID 的稳定性差异 ​

项目的命令 ID 每次 project update 都会重新生成,选择性运行前必须重新 project get 拿最新 ID;任务的步骤 ID 是 1 起的位置序号,update 后不变,task run --step-id 可以直接用:

bash
deploy project get hula-server-start --json     # 每次 update 后重新读命令 ID
deploy run hula-server-start --command-id <id> --wait

deploy task run hula-ice-config --step-id 3 -f  # 步骤 ID 稳定,无需重读

MinIO 公网直传:location 不能带尾斜杠 ​

OpenResty 反代 MinIO 时 location ^~ /dev 不能写成 /dev/:带尾斜杠会把 GET /dev?location=(SDK 查询 bucket 位置的请求)301 重定向,SDK 跟随重定向时复用原签名,导致 SignatureDoesNotMatch。反代还必须保留原始 Host:

nginx
location ^~ /dev {
    proxy_pass http://127.0.0.1:9000;
    proxy_set_header Host $http_host;
}

改 base_config 表后必须刷新缓存 ​

直接改数据库的 base_config 表不会生效,服务读的是 Redis 缓存。必须调用 PUT /anyTenant/config/batchUpdate 刷新缓存;靠重启服务来「让配置生效」不可靠。

coturn 的 external-ip 映射 ​

frpc 从 loopback 转发流量,coturn 看到的对端地址是 127.0.0.1,若不加映射,中继候选会把 127.0.0.1 返回给公网客户端。turnserver.conf 需要:

text
external-ip=47.118.23.26/127.0.0.1

SRS 的 CANDIDATE 变更必须重建容器 ​

SRS 用 docker compose 运行,修改 compose 里的 CANDIDATE 环境变量后,docker compose restart 不会应用新 env,必须重建容器:

bash
docker compose up -d srs

安全组放行要逐条核对 ​

截至写作时,阿里云安全组的 UDP 8000 尚未放行,SRS 的公网验证仍是待办;coturn 的 UDP(3478 + 49160-49200)已放行,STUN 与 TURN Allocate 均验证通过。公网化组件时,把「安全组规则」当成验收清单的一项逐条核对,不要假设 TCP 通了 UDP 也通。更多排错入口见故障排查。

验收结果 ​

验收全部基于真实客户端行为,而非平台运行状态:

验收项结果
真实 UI 登录(公网域名)通过
发送文字消息通过
头像上传 + 公网下载全链路全部 HTTP 200
Android 公网版 APK 真机通过
coturn STUN / TURN Allocate通过(UDP 已放行)
SRS 公网验证待办(安全组 UDP 8000 未放行)

延伸阅读 ​