主题
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-im | IM 业务 |
hula-ws | WebSocket 长连接 |
前端 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.1SRS 的 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 未放行) |