编码工程师andmultica-agent
5cc2685f03
根因：LiveKit 的 config/livekit.yaml 媒体端口(7881/7882)与宿主实际映射(17881/17882)不一致， 信令走 17880 能通，但媒体被宣告到 7881/7882 连不上。 - config/livekit.yaml: port/tcp_port/udp_port -> 17880/17881/17882 - docker-compose.yaml: 容器侧端口与宿主侧一致(1788x)，不再重映射 - .env.example: 默认端口改为 1788x 并注明三处需一致 - scripts/selftest.sh: LK_PORT 默认值改为 17880 - scripts/fix-livekit-ports.sh: 一键备份+对齐 .env+仅重建 livekit 的修复脚本 - README: 更新端口表、客户端接入参数与排障说明 Co-authored-by: multica-agent <github@multica.ai>
93 lines
5.9 KiB
Markdown
93 lines
5.9 KiB
Markdown
# OpenIM + LiveKit 内网测试环境部署记录
|
||
|
||
内部通讯 App 的服务端测试环境。一键部署后两个测试账号可互发文字/语音/文件消息，并可打通一对一语音通话。
|
||
|
||
## 组件清单
|
||
|
||
| 组件 | 镜像 | 用途 |
|
||
| --- | --- | --- |
|
||
| OpenIM Server | `openim/openim-server:v3.8.3-patch.12` | IM 服务端（REST API + WebSocket 消息网关） |
|
||
| LiveKit | `livekit/livekit-server:v1.13.5` | 语音通话 SFU |
|
||
| account-server | 本地构建（`account-service/`） | 自研公司账号登录（工号+密码、管理员导入名单、管理页），见 `account-service/README.md` |
|
||
| MongoDB / Redis / Etcd / Kafka / MinIO | 见 `.env.example` | OpenIM 依赖组件 |
|
||
|
||
按任务约束做的裁剪（相对官方 openim-docker v3.8）：
|
||
|
||
- 移除 `openim-chat`（GPLv3 授权不利改造，注册登录后续由"公司账号登录"卡自研）
|
||
- 移除 `openim-web-front` / `openim-admin-front`（这两个前端依赖 chat 服务）
|
||
- 监控组件（Prometheus/Grafana 等）保留在 compose profile `m` 下，默认不启动
|
||
|
||
未改动 OpenIM 服务端任何核心代码，全部通过环境变量配置（`IMENV_*`）。
|
||
|
||
## 服务器要求
|
||
|
||
- 内网闲置机器，4 核 8G 起步，磁盘 ≥ 20G
|
||
- 已安装 Docker（含 compose 插件，`docker compose version` 能跑通即可）
|
||
- 不需要公网入口
|
||
|
||
## 端口表（需要对客户端开放的只有前 6 个）
|
||
|
||
| 端口 | 协议 | 用途 |
|
||
| --- | --- | --- |
|
||
| 10001 | TCP/WS | OpenIM 消息网关（客户端长连接） |
|
||
| 10002 | TCP/HTTP | OpenIM REST API |
|
||
| 10005 | TCP/HTTP | MinIO（图片/语音/文件下载） |
|
||
| 10010 | TCP/HTTP | 公司账号服务（员工登录接口 + 管理页） |
|
||
| 17880 | TCP/WS | LiveKit 信令（`.env` 的 `LIVEKIT_PORT` 可改，但必须与 `config/livekit.yaml` 一致） |
|
||
| 17882 | UDP | LiveKit 语音媒体（`LIVEKIT_RTC_UDP_PORT` 可改，同上） |
|
||
| 17881 | TCP | LiveKit 媒体备用通道（`LIVEKIT_RTC_TCP_PORT` 可改，同上） |
|
||
| 10004 | TCP/HTTP | MinIO 控制台（运维用，可不开放） |
|
||
| 12379/12380 | TCP | Etcd（仅容器间用，建议不对外） |
|
||
|
||
## 部署步骤
|
||
|
||
```bash
|
||
git clone ssh://git@192.168.200.36:222/leefer/tongxunruanjian.git
|
||
cd tongxunruanjian
|
||
./scripts/deploy.sh # 自动探测本机内网 IP；也可 ./scripts/deploy.sh 192.168.x.x 指定
|
||
./scripts/selftest.sh # 自测（见下）
|
||
```
|
||
|
||
`deploy.sh` 做的事：首次从 `.env.example` 生成 `.env` → 把服务器 IP 写入 `MINIO_EXTERNAL_ADDRESS`（文件下载链接用这个地址，写错会导致文件发不出）→ 预建数据目录 → `docker compose pull && up -d` → 等待 openim-server 健康检查通过。
|
||
|
||
数据全部落在仓库目录下的 `components/` 里；`.env` 里的密码/密钥是测试环境默认值，正式环境前再换。
|
||
|
||
## 自测覆盖（scripts/selftest.sh）
|
||
|
||
1. 管理员令牌获取（`/auth/get_admin_token`）
|
||
2. 注册测试账号 `test001` / `test002`（`/user/user_register`）
|
||
3. 签发用户令牌，即登录链路（`/auth/get_user_token`）
|
||
4. 两账号互发文字消息（`/msg/send_msg`）
|
||
5. 附件上传 MinIO 并发送语音消息、文件消息
|
||
6. 消息落库回查（`/msg/search_msg`，逐条核对刚发的文字/语音/文件）
|
||
7. LiveKit 一对一：两个客户端进同一房间，主叫发布音频轨，被叫端确认收到轨道
|
||
|
||
全部通过会打印客户端接入参数。失败项会标 `[失败]`，配合 `docker compose logs -f openim-server` 或 `docker compose logs -f livekit` 排查。
|
||
|
||
## 日常运维
|
||
|
||
```bash
|
||
./scripts/restart.sh # 重启全部服务
|
||
./scripts/restart.sh livekit # 只重启某个服务
|
||
docker compose ps # 查看状态
|
||
docker compose logs -f openim-server # 看日志
|
||
docker compose down # 停止（数据保留在 components/）
|
||
docker compose up -d # 再启动
|
||
```
|
||
|
||
## 客户端接入参数（自测通过后）
|
||
|
||
- OpenIM API: `http://<服务器IP>:10002`
|
||
- OpenIM WebSocket: `ws://<服务器IP>:10001`
|
||
- LiveKit: `ws://<服务器IP>:17880`（17880 为默认信令端口；改端口时必须 `.env` 的 `LIVEKIT_PORT`、`config/livekit.yaml` 的 `port`、`docker-compose.yaml` 的容器侧端口三者一起改），API Key/Secret 见 `.env` 的 `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET`
|
||
- 测试账号：`test001` / `test002`（由自测脚本注册）；语音通话时两名用户以各自 identity 进同一房间即可
|
||
|
||
## 常见问题
|
||
|
||
- **文件/语音能发但打不开**：`MINIO_EXTERNAL_ADDRESS` 没写成客户端能访问的 IP。改 `.env` 后 `docker compose up -d` 重建 openim-server。
|
||
- **启动报缺 `ETCD_USERNAME` / `KAFKA_USERNAME` 等警告**：未启用对应组件认证，官方说明可忽略。
|
||
- **openim-server 一直 unhealthy**：`docker exec -it openim-server mage check` 看哪项依赖没通；首次启动需等 30-60 秒。
|
||
- **livekit 启动报 `bind ... 7880/7881: address already in use`**：服务器上这些端口被别的程序占了（`ss -tlnp | grep 788` 查占用者）。不要动别人的服务，把端口统一改成空闲端口（如 17880/17881/17882）——注意**必须三处一起改**：`.env` 的 `LIVEKIT_PORT` / `LIVEKIT_RTC_TCP_PORT` / `LIVEKIT_RTC_UDP_PORT`、`config/livekit.yaml` 的 `port` / `tcp_port` / `udp_port`、`docker-compose.yaml` 里 livekit 的容器侧端口（保持“宿主侧=容器侧”），然后 `docker compose up -d --force-recreate livekit`。只改其中一两处会导致“能邀请、能接听，但接听后双方网络错误”。
|
||
- **livekit 日志报 `secret is too short`**：`LIVEKIT_API_SECRET` 必须 ≥32 字符，换个长密钥后重建 livekit 容器。
|
||
- **语音通话连不上（接听后双方网络错误）**：先确认 `.env` / `config/livekit.yaml` / `docker-compose.yaml` 三处端口一致；再确认服务器防火墙放通 `LIVEKIT_PORT`(TCP)、`LIVEKIT_RTC_TCP_PORT`(TCP)、`LIVEKIT_RTC_UDP_PORT`(UDP)（默认 17880/17881/17882）。UDP 不通时会走 TCP 兜底。
|