diff --git a/.env.example b/.env.example
index 046f6ac..a9bae20 100644
--- a/.env.example
+++ b/.env.example
@@ -63,8 +63,12 @@ LOG_LEVEL=3
 
 # ===== LiveKit（一对一语音通话）=====
 LIVEKIT_API_KEY=openimLKkey
-LIVEKIT_API_SECRET=openimLKsecretChangeMe123
+# secret 必须 ≥32 字符，否则 LiveKit 启动报 secret is too short
+LIVEKIT_API_SECRET=lk-secret-9f2c7a41d5e8b063f1a4c795e2d8b3a6
+# 三个都是宿主机映射端口；7880/7881/7882 被占用时改成 17880/17881/17882 之类即可
 LIVEKIT_PORT=7880
+LIVEKIT_RTC_TCP_PORT=7881
+LIVEKIT_RTC_UDP_PORT=7882
 
 # ===== 监控端口（可选）=====
 PROMETHEUS_PORT=19090
diff --git a/README.md b/README.md
index 4eb5f3e..b236c3a 100644
--- a/README.md
+++ b/README.md
@@ -31,9 +31,9 @@
 | 10001 | TCP/WS | OpenIM 消息网关（客户端长连接） |
 | 10002 | TCP/HTTP | OpenIM REST API |
 | 10005 | TCP/HTTP | MinIO（图片/语音/文件下载） |
-| 7880 | TCP/WS | LiveKit 信令 |
-| 7882 | UDP | LiveKit 语音媒体 |
-| 7881 | TCP | LiveKit 媒体备用通道（UDP 不通时） |
+| 7880 | TCP/WS | LiveKit 信令（`.env` 的 `LIVEKIT_PORT` 可改） |
+| 7882 | UDP | LiveKit 语音媒体（`LIVEKIT_RTC_UDP_PORT` 可改） |
+| 7881 | TCP | LiveKit 媒体备用通道（`LIVEKIT_RTC_TCP_PORT` 可改） |
 | 10004 | TCP/HTTP | MinIO 控制台（运维用，可不开放） |
 | 12379/12380 | TCP | Etcd（仅容器间用，建议不对外） |
 
@@ -85,5 +85,6 @@ docker compose up -d           # 再启动
 - **文件/语音能发但打不开**：`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: address already in use`**：服务器上 7880 被别的程序占了。先 `ss -tlnp | grep 7880` 看是谁；若不能停掉对方，就改 `.env` 里 `LIVEKIT_PORT=17880` 再 `docker compose up -d`，之后客户端和自测脚本都用新端口（自测脚本会自动读 `.env`）。
+- **livekit 启动报 `bind ... 7880/7881: address already in use`**：服务器上这些端口被别的程序占了（`ss -tlnp | grep 788` 查占用者）。不要动别人的服务，把 `.env` 里 `LIVEKIT_PORT` / `LIVEKIT_RTC_TCP_PORT` / `LIVEKIT_RTC_UDP_PORT` 改成空闲端口（如 17880/17881/17882），再 `docker compose up -d --force-recreate livekit`。之后客户端和自测脚本都用新端口（自测脚本会自动读 `.env`）。
+- **livekit 日志报 `secret is too short`**：`LIVEKIT_API_SECRET` 必须 ≥32 字符，换个长密钥后重建 livekit 容器。
 - **语音通话连不上**：确认服务器 UDP 7882 放行（内网防火墙/安全组）；UDP 不通时会走 TCP 7881 兜底。
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 20f9c96..dec6903 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -369,7 +369,8 @@ services:
       - openim
 
   # LiveKit：语音/视频通话的 SFU，Apache 2.0，自部署。
-  # 客户端通过 ws://<SERVER_IP>:7880 连接，凭 LIVEKIT_API_KEY/SECRET 签发的 token 进房。
+  # 客户端通过 ws://<SERVER_IP>:<LIVEKIT_PORT> 连接，凭 LIVEKIT_API_KEY/SECRET 签发的 token 进房。
+  # 三个宿主端口都可在 .env 调整（7880/7881/7882 被其他服务占用时改映射即可，容器内端口不变）。
   livekit:
     image: ${LIVEKIT_IMAGE}
     container_name: livekit
@@ -378,9 +379,9 @@ services:
     environment:
       LIVEKIT_KEYS: "${LIVEKIT_API_KEY}: ${LIVEKIT_API_SECRET}"
     ports:
-      - "${LIVEKIT_PORT}:7880"    # HTTP / WebSocket 信令
-      - "7881:7881"               # RTC over TCP（UDP 不通时的备用通道）
-      - "7882:7882/udp"           # RTC 媒体（UDP 复用端口）
+      - "${LIVEKIT_PORT:-7880}:7880"              # HTTP / WebSocket 信令
+      - "${LIVEKIT_RTC_TCP_PORT:-7881}:7881"      # RTC over TCP（UDP 不通时的备用通道）
+      - "${LIVEKIT_RTC_UDP_PORT:-7882}:7882/udp"  # RTC 媒体（UDP 复用端口）
     volumes:
       - ./config/livekit.yaml:/etc/livekit.yaml
     networks: