feat(nginx): 内置路由 nginx 作为统一入口，宿主机 nginx 只需一条 proxy_pass

将 nginx 容器从可选 profile 改为 base 必启服务，绑定 127.0.0.1:11223。
新增 config/nginx/conf.d/xuqm.conf 按 Docker 服务名路由所有内部请求。
部署完成提示从多条 location 精简为单条 proxy_pass http://127.0.0.1:11223。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

config/nginx/conf.d/xuqm.conf

@@ -0,0 +1,99 @@
+server {
+  listen 80;
+  server_name _;
+
+  charset utf-8;
+  client_max_body_size 100m;
+
+  # 健康检查（宿主机 nginx 探活用）
+  location /health {
+    return 200 "ok\n";
+    add_header Content-Type text/plain;
+  }
+
+  # 版本管理 — 必须在通用 /api/ 之前
+  location /api/v1/updates/ {
+    proxy_pass         http://update-service:8084/api/v1/updates/;
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 60s;
+  }
+
+  location /api/v1/rn/ {
+    proxy_pass         http://update-service:8084/api/v1/rn/;
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 120s;
+  }
+
+  # IM HTTP — 必须在通用 /api/ 之前
+  location /api/im/ {
+    proxy_pass         http://im-service:8082/api/im/;
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 60s;
+  }
+
+  # IM WebSocket
+  location /ws/im {
+    proxy_pass         http://im-service:8082/ws/im;
+    proxy_http_version 1.1;
+    proxy_set_header   Upgrade $http_upgrade;
+    proxy_set_header   Connection "upgrade";
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_read_timeout 3600s;
+  }
+
+  # License — 必须在通用 /api/ 之前
+  location /api/license/ {
+    proxy_pass         http://license-service:8085/api/license/;
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 60s;
+  }
+
+  # 文件上传下载
+  location /file/ {
+    proxy_pass             http://file-service:8086/file/;
+    proxy_set_header       Host $host;
+    proxy_set_header       X-Real-IP $remote_addr;
+    proxy_set_header       X-Forwarded-For $proxy_add_x_forwarded_for;
+    client_max_body_size   500m;
+    proxy_read_timeout     300s;
+    proxy_send_timeout     300s;
+  }
+
+  # 核心 API（兜底，在所有具体 /api/xxx/ 之后）
+  location /api/ {
+    proxy_pass         http://tenant-service:9001/api/;
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 60s;
+  }
+
+  location /actuator/ {
+    proxy_pass       http://tenant-service:9001/actuator/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+  }
+
+  # 运营后台
+  location /ops {
+    proxy_pass       http://ops-web:80;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+  }
+
+  # 控制台前端（兜底路由，必须最后）
+  location / {
+    proxy_pass       http://tenant-web:80;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+  }
+}

docker-compose.yml

@@ -83,16 +83,15 @@ services:
     restart: unless-stopped
 
   # ---------------------------------------------------------------------------
-  # Nginx 反向代理（可选，profile: nginx-bundled）
+  # 内置路由 nginx（必须）
-  # 默认不启动 — 用户通常用宿主机自己的 nginx 代理到各服务端口。
+  # 统一处理所有内部路由，对外只暴露 127.0.0.1:11223。
-  # 需要内置 nginx 时：COMPOSE_PROFILES=...,nginx-bundled
+  # 宿主机 nginx 只需一条 proxy_pass http://127.0.0.1:11223 即可。
   # ---------------------------------------------------------------------------
   nginx:
     image: nginx:1.27-alpine
-    profiles: ["nginx-bundled"]
+    profiles: ["base"]
     ports:
-      - "80:80"
+      - "127.0.0.1:11223:80"
-      - "443:443"
     volumes:
       - ./config/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
       - ./config/nginx/conf.d:/etc/nginx/conf.d:ro

docs/runbook.md

@@ -20,52 +20,37 @@ curl -fsSL https://xuqinmin.com/xuqmGroup/XuqmGroup-PrivateDeploy/raw/branch/mai
 
 ## Nginx 配置
 
-部署完成后，将以下 location 块加入宿主机 nginx 的 server 配置：
+部署内置了一个 nginx 容器处理所有内部路由，对外只暴露 `127.0.0.1:11223`。
+
+宿主机 nginx 的 server 块内只需加一条：
 
 ```nginx
-charset utf-8;
+location / {
-client_max_body_size 100m;
+    proxy_pass         http://127.0.0.1:11223;
-
-location /api/v1/updates/ { proxy_pass http://127.0.0.1:11229/api/v1/updates/; }
-location /api/v1/rn/      { proxy_pass http://127.0.0.1:11229/api/v1/rn/; }
-location /api/im/         { proxy_pass http://127.0.0.1:11228/api/im/; }
-location /ws/im {
-    proxy_pass http://127.0.0.1:11228/ws/im;
     proxy_http_version 1.1;
-    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header   Upgrade $http_upgrade;
-    proxy_set_header Connection "upgrade";
+    proxy_set_header   Connection "upgrade";
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_read_timeout 3600s;
 }
-location /api/license/    { proxy_pass http://127.0.0.1:11231/api/license/; }
-location /file/ {
-    proxy_pass http://127.0.0.1:11225/file/;
-    client_max_body_size 500m;
-    proxy_read_timeout 300s;
-}
-location /api/            { proxy_pass http://127.0.0.1:11224/api/; }
-location /actuator/       { proxy_pass http://127.0.0.1:11224/actuator/; }
-location /ops             { proxy_pass http://127.0.0.1:11227; }
-location /                { proxy_pass http://127.0.0.1:11226; }
 ```
 
-> location 顺序不可颠倒：精确路径（`/api/im/`、`/api/v1/`、`/api/license/`）必须在通用路径（`/api/`）前面。
+> `proxy_http_version 1.1` 和 `Upgrade`/`Connection` 头是 WebSocket（IM）必需的，不能省略。
+
+内置 nginx 路由配置在 `config/nginx/conf.d/xuqm.conf`，使用 Docker 服务名路由到各容器，无需关心具体端口。
 
 ---
 
-## 端口对照表
+## 端口说明
 
-| 宿主机端口 | 服务 | 容器内端口 | 说明 |
+| 宿主机端口 | 说明 |
-|-----------|------|-----------|------|
+|-----------|------|
-| 11224 | tenant-service | 9001 | 核心 API |
+| **11223** | 内置 nginx 入口（宿主机 nginx 指向此端口） |
-| 11225 | file-service | 8086 | 文件上传下载 |
+| 11224–11231 | 各业务容器（绑定 127.0.0.1，调试用） |
-| 11226 | tenant-web | 80 | 控制台前端 |
-| 11227 | ops-web | 80 | 运营后台前端 |
-| 11228 | im-service | 8082 | IM HTTP + WebSocket |
-| 11229 | update-service | 8084 | 版本管理 + RN 热更新 |
-| 11230 | license-service | 8085 | License 校验 |
-| 11231 | push-service | 8083 | 厂商推送 |
 
-所有端口绑定 `127.0.0.1`，外部不可直接访问。
+各业务容器端口仅用于直接调试，正常流量全部走 11223。
 
 ---
 

scripts/deploy.sh

@@ -248,7 +248,7 @@ REGISTRY_USER=${REGISTRY_USER}
 REGISTRY_PASSWORD=${REGISTRY_PASSWORD}
 IMAGE_TAG=${IMAGE_TAG}
 
-# 启用全量服务（nginx 容器默认不启动，用户自行配置宿主机 nginx）
+# 启用全量服务（含内置路由 nginx，宿主机 nginx 只需一条 proxy_pass 到 11223）
 COMPOSE_PROFILES=base,infra-mysql,infra-redis,im,push,update,license
 
 # MySQL（managed 模式，Docker 容器托管）
@@ -918,43 +918,22 @@ if [ "$DEPLOY_MODE" = "new" ]; then
 else
   printf '    密码:   同生产平台密码（原样迁移，未重置）\n'
 fi
-printf '\n  \033[1m容器端口（请在您的 nginx 中配置代理）：\033[0m\n'
+printf '\n  \033[1m宿主机 nginx 配置（server 块内加入以下内容即可）：\033[0m\n'
-printf '    控制台前端    127.0.0.1:11226  → 代理 /\n'
-printf '    运营后台      127.0.0.1:11227  → 代理 /ops\n'
-printf '    核心 API      127.0.0.1:11224  → 代理 /api/ /actuator/\n'
-printf '    文件服务      127.0.0.1:11225  → 代理 /file/ /api/file/\n'
-printf '    IM 服务       127.0.0.1:11228  → 代理 /api/im/ /ws/im\n'
-printf '    版本管理      127.0.0.1:11230  → 代理 /api/v1/updates/ /api/v1/rn/\n'
-printf '    License 服务  127.0.0.1:11231  → 代理 /api/license/\n'
-printf '    推送服务      127.0.0.1:11229  （厂商回调，按需代理）\n'
-printf '\n  \033[1mNginx 配置参考（复制到您的 nginx server 块）：\033[0m\n'
 printf '\033[0;37m'
 cat <<'NGINX_REF'
-  charset utf-8;
+  location / {
-  client_max_body_size 100m;
+    proxy_pass         http://127.0.0.1:11223;
-
-  location /api/v1/updates/ { proxy_pass http://127.0.0.1:11230/api/v1/updates/; }
-  location /api/v1/rn/      { proxy_pass http://127.0.0.1:11230/api/v1/rn/; }
-  location /api/im/         { proxy_pass http://127.0.0.1:11228/api/im/; }
-  location /ws/im {
-    proxy_pass http://127.0.0.1:11228/ws/im;
     proxy_http_version 1.1;
-    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header   Upgrade $http_upgrade;
-    proxy_set_header Connection "upgrade";
+    proxy_set_header   Connection "upgrade";
+    proxy_set_header   Host $host;
+    proxy_set_header   X-Real-IP $remote_addr;
+    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_read_timeout 3600s;
   }
-  location /api/license/    { proxy_pass http://127.0.0.1:11231/api/license/; }
-  location /file/ {
-    proxy_pass http://127.0.0.1:11225/file/;
-    client_max_body_size 500m;
-    proxy_read_timeout 300s;
-  }
-  location /api/            { proxy_pass http://127.0.0.1:11224/api/; }
-  location /actuator/       { proxy_pass http://127.0.0.1:11224/actuator/; }
-  location /ops             { proxy_pass http://127.0.0.1:11227; }
-  location /                { proxy_pass http://127.0.0.1:11226; }
 NGINX_REF
 printf '\033[0m'
+printf '  内置 nginx 已处理全部路由，无需再配置各服务端口。\n'
 printf '\n  \033[1m部署目录：\033[0m  %s\n' "$ROOT_DIR"
 printf '  \033[1m审计日志：\033[0m  %s/logs/audit.log\n' "$ROOT_DIR"
-printf '\n\033[1;32m  部署成功！配置好 nginx 后即可访问：%s\033[0m\n\n' "${CONSOLE_BASE}"
+printf '\n\033[1;32m  部署成功！在宿主机 nginx 加上以上配置后即可访问：%s\033[0m\n\n' "${CONSOLE_BASE}"