fix(livekit): 统一信令/媒体端口为 17880/17881/17882，修复接听后双方网络错误

根因：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>

scripts/fix-livekit-ports.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# 修复语音通话“门号不一致”（信令通、媒体不通）问题。
+# 根因：LiveKit 的 config/livekit.yaml 里媒体端口(7881/7882)与宿主实际映射(17881/17882)不一致，
+#       导致 LiveKit 向客户端宣告的媒体地址连不上。
+# 修复：统一 .env / config/livekit.yaml / docker-compose.yaml 三处端口为 17880/17881/17882，
+#       只重启 livekit 容器。
+#
+# 用法（在服务器仓库目录里执行，且已 git pull 到含本修复的版本）：
+#   ./scripts/fix-livekit-ports.sh
+#
+# 该脚本幂等，可重复执行；会先备份再改动，失败可回退。
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+TS="$(date +%Y%m%d-%H%M%S)"
+BK="backup-livekit-ports-$TS"
+mkdir -p "$BK"
+echo "==> 备份当前配置到 $BK/"
+for f in .env config/livekit.yaml docker-compose.yaml; do
+  [ -f "$f" ] && cp -p "$f" "$BK/$(basename "$f")"
+done
+[ -f "$BK/.env" ] || echo "(未找到 .env，跳过备份)"
+
+# 1. 校验仓库文件已含修复（config/livekit.yaml 端口应为 17880/17881/17882）
+grep -q '^port: 17880' config/livekit.yaml || { echo "✗ config/livekit.yaml 未包含 port: 17880，请先 git pull 更新仓库后再执行本脚本"; exit 1; }
+grep -q 'tcp_port: 17881' config/livekit.yaml || { echo "✗ config/livekit.yaml 未包含 tcp_port: 17881"; exit 1; }
+grep -q 'udp_port: 17882' config/livekit.yaml || { echo "✗ config/livekit.yaml 未包含 udp_port: 17882"; exit 1; }
+
+# 2. 对齐 .env 三个端口
+if [ ! -f .env ]; then
+  cp .env.example .env
+  echo "==> 未找到 .env，已从 .env.example 生成"
+fi
+sed -i 's|^LIVEKIT_PORT=.*|LIVEKIT_PORT=17880|' .env
+sed -i 's|^LIVEKIT_RTC_TCP_PORT=.*|LIVEKIT_RTC_TCP_PORT=17881|' .env
+sed -i 's|^LIVEKIT_RTC_UDP_PORT=.*|LIVEKIT_RTC_UDP_PORT=17882|' .env
+# 若这三行原本不存在，则追加
+grep -q '^LIVEKIT_PORT=' .env || echo 'LIVEKIT_PORT=17880' >> .env
+grep -q '^LIVEKIT_RTC_TCP_PORT=' .env || echo 'LIVEKIT_RTC_TCP_PORT=17881' >> .env
+grep -q '^LIVEKIT_RTC_UDP_PORT=' .env || echo 'LIVEKIT_RTC_UDP_PORT=17882' >> .env
+echo "==> .env 三个端口已设为 17880/17881/17882"
+
+# 3. 只重建 livekit 容器（不动其它服务）
+docker compose up -d --force-recreate livekit
+
+# 4. 校验
+echo "==> 等待 livekit 就绪..."
+sleep 3
+docker compose ps livekit
+echo
+echo "==> 请确认防火墙放通 17880/TCP、17881/TCP、17882/UDP（默认已在本机监听）："
+ss -tlnp 2>/dev/null | grep -E ':(17880|17881)' || true
+ss -ulnp 2>/dev/null | grep ':17882' || true
+echo
+echo "==> 完成。回退方法："
+echo "    cp $BK/.env .env 2>/dev/null; git checkout -- config/livekit.yaml docker-compose.yaml; docker compose up -d --force-recreate livekit"

scripts/selftest.sh

@@ -18,7 +18,7 @@ MINIO_SK="$(env_get MINIO_SECRET_ACCESS_KEY)"; MINIO_SK="${MINIO_SK:-openIM123}"
 MINIO_PORT="$(env_get MINIO_PORT)"; MINIO_PORT="${MINIO_PORT:-10005}"
 LK_KEY="$(env_get LIVEKIT_API_KEY)"
 LK_SECRET="$(env_get LIVEKIT_API_SECRET)"
-LK_PORT="$(env_get LIVEKIT_PORT)"; LK_PORT="${LK_PORT:-7880}"
+LK_PORT="$(env_get LIVEKIT_PORT)"; LK_PORT="${LK_PORT:-17880}"
 LK_HTTP="http://${IP}:${LK_PORT}"
 LK_WS="ws://${IP}:${LK_PORT}"
 LK_CLI_IMAGE="livekit/livekit-cli:v2.18.2"