Document single domain gateway routing

ai_knowledge_base_v2/development_records/2026-07-09-single-domain-gateway-routing.md

@@ -0,0 +1,47 @@
+# 单域名路径分流部署调整
+
+日期：2026-07-09
+
+## 需求背景
+
+当前用户端、管理后台和后端 API 分别通过不同端口访问：
+
+- 用户端：`5173`
+- 管理后台：`5174`
+- 后端 API：`8100`
+
+部署内网穿透和域名后，这种方式不利于访问和配置。目标是使用同一个域名，通过不同路径访问不同应用：
+
+- `https://qa.huiyushuyuan.cn/`：默认进入用户端 H5。
+- `https://qa.huiyushuyuan.cn/login`：进入管理后台登录页。
+- `https://qa.huiyushuyuan.cn/api/...`：访问后端 API。
+
+## 处理决策
+
+1. 新增 `gateway` 反向代理服务，作为 Docker 网络内唯一对外入口。
+2. `gateway` 使用 Nginx 做路径分流：
+   - `/api/` 代理到 `backend:8100`
+   - `/login/` 代理到 `admin-web:5174`
+   - `/` 代理到 `user-client:5173`
+3. `/login` 自动跳转到 `/login/`，保证后台资源路径稳定。
+4. 管理后台 Vite `base` 设置为 `/login/`，避免后台资源路径和用户端资源路径冲突。
+5. 用户端和管理后台的 `VITE_API_BASE_URL` 改为 `/api`，让前端在同域名下调用后端。
+6. frpc 默认穿透目标改为 `gateway:80`，不再直接穿透后端 `8100`。
+
+## 风险规避
+
+不能简单把 `/login` 反向代理到后台端口。原因是后台页面里的脚本和资源默认会请求 `/src/...` 或 `/assets/...`，如果不配置独立 base，这些请求会被默认路由分到用户端，导致页面加载错资源或白屏。
+
+因此本次同时调整：
+
+- 代理路径：`/login/`
+- 后台构建 base：`/login/`
+- API 同源路径：`/api`
+
+## 验收标准
+
+- `http://127.0.0.1:8080/` 能打开用户端。
+- `http://127.0.0.1:8080/login` 能进入管理后台登录页。
+- `http://127.0.0.1:8080/api/health` 能访问后端健康检查。
+- 用户端和管理后台通过同域 `/api` 调用后端，不再依赖 `127.0.0.1:8100`。
+- frpc 配置默认指向 `gateway:80`，域名穿透后可用一个域名按路径访问。