# ai-gateway 设计：按用户粘性的多机器转发网关

> 状态：方案设计稿（未实施）
> 目标：在多台 ai-server 部署环境下，把同一用户的请求固定转发到该用户所属的机器上。
> 本文只描述方案，不包含代码实施。

---

## 1. 背景与现状约束

### 1.1 需求

1. 能配置多个后端服务地址（多个服务、每个服务多台机器）。
2. 自动转发用户请求：用户注册/首次登录在哪台机器上，后续请求就转发到哪台机器。
3. 部署多台机器时，按用户做粘性路由，而不是普通轮询负载均衡。

### 1.2 仓库现状

- 仓库是 **Spring Boot 单体后端 `ai-server` + Electron/Vue 前端**，没有独立网关、Spring Cloud Gateway、Nginx 配置或服务注册中心。
- 后端统一端口 `8980`，context-path `/js/a`；前端所有请求最终落到 `/js/a/...`。
- 没有自助注册接口：用户由管理员通过 `POST /user/create` 创建，只写入共享 PostgreSQL 的 `sys_user`，不记录所属机器。
- 登录使用 **sa-token 1.46**：token 是不透明 UUID，请求头 `x-token`，登录态和 Token-Session 都存 Redis。多台后端只要连同一个 Redis，就能识别同一个 token。
- 案件、上传文件、聊天附件、Agent 记忆/技能、Python 产物都落在**各机器本地磁盘**；`/case/open` 还会把案件数据源注册到当前 JVM 内存。
- 每台 ai-server 需要独立授权（机器码绑定）和独立工作目录，不能共享 DuckDB 文件（跨进程文件锁会失败）。

### 1.3 关键结论

不能做普通的无状态负载均衡。请求落到非用户所属机器时，即使 token 和 `caseId` 都能从 Redis 恢复，本机也没有对应的案件数据源，会直接报“当前案件数据源未打开或已释放”。

因此必须：

- 按用户做粘性路由；
- 用户绑定的节点不可用时明确失败，不自动切到其他机器；
- 用户数据迁移不在本期范围。

---

## 2. 已定型的决策

| 项 | 决策 |
|---|---|
| 工程形态 | 当前仓库新增 `ai-gateway` Maven 模块 |
| 技术栈 | Spring Boot 3.5.16 + Spring Cloud Gateway 2025.0.x（WebFlux/Netty），独立端口 `8080` |
| 用户绑定 | 用户**首次登录成功**时自动绑定到一台机器；管理员可通过接口预先绑定 |
| 用户识别 | `x-token` → sa-token 共享 Redis → userId |
| 配置 | YAML 首次播种 + PostgreSQL 运行时配置 + `/gateway/admin/**` 管理接口 |
| 节点故障 | 返回 HTTP 503 + 明确提示，不自动切换 |
| 前端 | 不改业务代码，只把 API 基地址指向网关 |

> 当前仓库没有注册接口，所以“注册在哪台机器”落地为“首次登录成功在哪台机器”。如果以后新增注册接口，只需在注册成功后调用同一个绑定服务。

---

## 3. 目标架构

```
Electron / Web
      │  http://gateway:8080/js/a/**
      ▼
┌──────────────────────── ai-gateway :8080 ────────────────────────┐
│ 登录请求：username → node（首次成功登录后写映射）                │
│ 普通请求：x-token → userId → node（Redis 缓存 + PostgreSQL 兜底）│
│ 无 token：健康节点轮询；MCP：固定节点                            │
└───────────────┬──────────────────────────┬───────────────────────┘
                │                          │
        ai-server node-1 :8980     ai-server node-2 :8980
        （本地 DuckDB/附件/Agent） （本地 DuckDB/附件/Agent）
                │                          │
                └──────── 共享 PostgreSQL（服务/节点/用户路由）
                └──────── 共享 Redis（sa-token + 网关路由缓存）
```

网关只做转发和粘性决策，不复制后端鉴权逻辑；业务接口仍由 ai-server 校验 token。

### 3.1 请求处理总流程

1. 客户端请求进入网关（默认 `8080`）。
2. 按路径前缀匹配已配置的服务（如 `/js/a/**` → `zsjz-ai`）。
3. 根据登录用户名或 `x-token` 解析出目标节点。
4. 校验节点启用状态和健康状态。
5. 把请求流式转发到目标节点，保留原始路径、查询参数、请求头、请求体。
6. 响应流式返回客户端，并附加 `X-Gateway-Node` 便于排查。

---

## 4. 路由与绑定算法

### 4.1 登录请求

登录请求没有 token，只能靠请求体里的 `username` 定位用户。

1. `LoginRequestFilter` 只对配置的登录路径（`/js/a/auth/login`）生效：
   - 缓存 ≤64KB 请求体；
   - 解析 JSON 中的 `username`；
   - 把 `Accept-Encoding` 改为 `identity`，避免后端压缩导致无法解析响应；
   - 原样转发请求体，不改变业务内容。
2. `StickyRouteFilter` 决定目标节点：
   - 有 `username → node` 映射：走该节点；节点 DOWN 直接 503。
   - 无映射：查 `sys_user` 得到 `userId`，再查 `userId → node`；有则使用并回填 username 缓存。
   - 仍无映射：在所有健康节点中轮询选一个“候选节点”，**此时不写绑定**。
3. `LoginResponseFilter` 缓存 ≤256KB 登录响应，解析：

   ```json
   {
     "code": 200,
     "message": "",
     "data": {
       "token": "...",
       "userId": 1,
       "username": "admin",
       "displayName": "系统管理员",
       "isAdmin": 1
     }
   }
   ```

   - `code == 200` 且 `userId` 非空时，调用 `bindIfAbsent(userId, username, 候选节点)`。
   - 并发首次登录由数据库唯一索引裁决：先插入者生效，后到者读取赢家节点；不会来回漂移。
   - 缓存 `gateway:token:{serviceId}:{token} → userId`，TTL 24h。
   - 无论绑定成功与否，响应原样写回。
4. 登录失败（密码错等）不产生绑定，避免无效映射。

### 4.2 普通请求

1. 从 `x-token` 读 token；先查 `gateway:token:*` 得到 userId。
2. 缓存未命中时用 sa-token `StpUtil.getLoginIdByToken`（共享 Redis）解析，并回填 token 缓存；兼容网关上线前已签发的 token。
3. 查 `userId → node`（Redis 缓存，未命中查 `gateway_user_route` 并回填）。
4. 没有该用户的映射时：
   - 服务配置了 `default-node-id`：绑定到该节点（用于存量用户迁移）；
   - 否则返回 503「用户未绑定节点，请重新登录或联系管理员」。
5. 绑定节点被禁用或健康检查 DOWN：返回 503，不切换。
6. 节点健康时把 `GATEWAY_REQUEST_URL_ATTR` 重写为 `节点 origin + 原始 rawPath + rawQuery`，由 Netty 流式转发；响应头加 `X-Gateway-Node` 便于排查。

### 4.3 无 token 与 MCP

- 登录以外的无 token 请求（`/sys/health`、`/sys/map/**` 等）在健康节点间轮询。
- MCP 路径（`/mcpsse`、`/mcpstreamable`、`/mcp/message`）无 token 且会话有状态，固定转发到服务配置的 `mcp-node-id`；未配置时走首个健康节点。本期不做 MCP 会话级粘性。
- 其他无 token 请求如果后端需要鉴权，由后端返回现有的 `code=401`，网关不重复鉴权。

### 4.4 绑定写入与并发

`bindIfAbsent` 的语义：

1. 先按 `(serviceId, userId)` 和 `(serviceId, lower(username))` 查已有路由；有则直接返回已有节点，不覆盖。
2. 没有则插入一行，同时写 `user_id`、`username`、`node_id`。
3. 使用 `ON CONFLICT DO NOTHING`，再按 userId、username 重新查询，读取并发下的赢家。
4. 写入成功后更新 Redis 的 `user`、`name` 两个缓存键。

数据库唯一索引是最终裁决，保证同一用户/用户名只存在一条路由。

### 4.5 用户路由的 Redis 键

| 键 | 值 | TTL | 用途 |
|---|---|---|---|
| `gateway:token:{serviceId}:{token}` | userId | 24h | 避免每个请求都调 sa-token |
| `gateway:route:user:{serviceId}:{userId}` | nodeId | 无 | 普通请求热路径 |
| `gateway:route:name:{serviceId}:{lower(username)}` | nodeId | 无 | 登录请求热路径 |

- PostgreSQL 是事实来源，Redis 只是缓存。
- Redis 清空后按需求回源数据库，不影响正确性。
- 管理员重绑/解绑时同时更新数据库和 Redis。

### 4.6 健康检查与故障处理

- 每 10 秒对每个节点 `GET {base-url}{health-path}`，2 秒超时。
- 连续 3 次失败标记 DOWN；1 次成功恢复 UP。
- 新用户分配只选健康且启用的节点。
- 已绑定用户的节点 DOWN 时直接 503，不切换。
- 背景节点恢复后自动恢复服务，用户映射不变。
- `/sys/health` 目前只证明进程存活，不检查 PG/Redis/ES；节点级探活够用，深度健康可作为后续增强。

---

## 5. 配置模型

`ai-gateway/src/main/resources/application.yaml`：

```yaml
server:
  port: 8080

spring:
  application:
    name: ai-gateway
  datasource:
    url: jdbc:postgresql://192.168.0.106:5432/zsjz-ai
    username: postgres
    password: postgres
  data:
    redis:
      host: 192.168.0.106
      port: 6379
  sql:
    init:
      mode: always
      schema-locations: classpath:db/gateway.sql

sa-token:
  token-name: x-token
  is-read-header: true
  is-read-cookie: false
  is-read-body: false
  timeout: 2592000
  is-concurrent: true
  is-share: false
  token-style: uuid

gateway:
  admin:
    enabled: true
    ip-whitelist: []          # 支持单 IP / CIDR；空表示不限制
  health-check:
    interval: 10s
    timeout: 2s
    failure-threshold: 3
  cors:
    allowed-origin-patterns: ["*"]
  services:
    - id: zsjz-ai
      name: 智能分析后端
      path-prefix: /js/a
      login-path: /auth/login
      health-path: /js/a/sys/health
      default-node-id: node-1
      mcp-node-id: node-1
      mcp-paths: ["/mcpsse", "/mcpstreamable", "/mcp/message"]
      nodes:
        - id: node-1
          name: 节点1
          base-url: http://192.168.0.101:8980
        - id: node-2
          name: 节点2
          base-url: http://192.168.0.102:8980
```

### 5.1 配置优先级

- **数据库为准**：首次启动若 `gateway_service` 为空，用 YAML 播种；之后 YAML 不再覆盖数据库。
- 节点、服务变更通过管理接口完成。
- 支持多个服务，每个服务一个路径前缀、一组节点；前缀冲突在保存时拒绝。
- 网关的 Redis/sa-token 配置必须与后端一致（同一 Redis、同一 `token-name`、同一 DB index），否则 token 无法解析。

### 5.2 生产配置建议

- 数据库密码、Redis 密码用环境变量注入，不写进仓库。
- `gateway.admin.ip-whitelist` 配置为运维网段。
- 多个网关实例可同时运行，共享 PG/Redis，粘性结果一致。
- 网关本身无本地状态，可放在 VIP/Nginx 后面。

---

## 6. 数据库模型

新增 `sql/gateway.sql`（`CREATE TABLE IF NOT EXISTS`，可重复执行），Maven 把它复制到 classpath 供 `spring.sql.init` 自动建表。

### 6.1 `gateway_service`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | varchar(64) PK | 服务标识，如 `zsjz-ai` |
| `name` | varchar(128) | 服务名称 |
| `path_prefix` | varchar(128) UNIQUE | 对外路径前缀，如 `/js/a` |
| `login_path` | varchar(128) | 相对登录路径，如 `/auth/login`，可空 |
| `health_path` | varchar(255) | 完整健康检查路径，如 `/js/a/sys/health` |
| `default_node_id` | varchar(64) | 存量用户兜底节点，可空 |
| `mcp_node_id` | varchar(64) | MCP 固定节点，可空 |
| `mcp_paths` | varchar(512) | MCP 路径列表，逗号分隔，可空 |
| `enabled` | smallint | 1 启用 0 停用 |
| `create_time` / `update_time` | timestamp | 审计 |

### 6.2 `gateway_node`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | varchar(64) PK | 节点标识，全局唯一，如 `node-1` |
| `service_id` | varchar(64) FK | 所属服务 |
| `name` | varchar(128) | 节点名称 |
| `base_url` | varchar(255) | `http(s)://host:port`，不含路径 |
| `enabled` | smallint | 1 启用 0 停用 |
| `remark` | varchar(512) | 备注 |
| `create_time` / `update_time` | timestamp | 审计 |

`(service_id, base_url)` 唯一。

### 6.3 `gateway_user_route`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigserial PK | 主键 |
| `service_id` | varchar(64) FK | 服务 |
| `user_id` | bigint | `sys_user.id`，可空 |
| `username` | varchar(64) | 登录名，可空 |
| `node_id` | varchar(64) FK | 目标节点 |
| `create_time` / `update_time` | timestamp | 审计 |

约束：

- `(service_id, user_id)` 唯一（user_id 非空时）；
- `(service_id, lower(username))` 唯一（username 非空时）；
- `user_id`、`username` 至少一个非空；
- 所有外键 `ON DELETE RESTRICT`；
- 删除有绑定用户的节点直接拒绝，避免产生无主用户。

### 6.4 与后端表的关系

- 网关只读 `sys_user` 的 `id/username/is_admin/status`，不修改后端表。
- 用户路由放独立表，不侵入 `sys_user`，支持同一用户在不同服务绑定不同节点。

---

## 7. 核心实现设计

### 7.1 模块与依赖

- 根 `pom.xml` 增加 `<module>ai-gateway</module>`。
- `ai-gateway/pom.xml`：
  - 父 POM `com.zsjz:zsjz-ai:1.0`，JDK 25；
  - 导入 Spring Cloud 2025.0.x BOM；
  - 依赖：
    - `spring-cloud-starter-gateway-server-webflux`
    - `spring-boot-starter-webflux`
    - `spring-boot-starter-jdbc`
    - PostgreSQL 驱动
    - `spring-boot-starter-data-redis-reactive`
    - `sa-token-reactor-spring-boot3-starter:1.46.0`
    - `sa-token-redis-jackson:1.46.0`
    - `spring-boot-starter-validation`
  - 测试依赖：Reactor Test、WireMock、Testcontainers（PostgreSQL + Redis 容器）。
- Maven resources 把 `../sql/gateway.sql` 打进 `classpath:db/gateway.sql`，避免 DDL 两份维护。

### 7.2 动态路由

- `GatewayRouteDefinitionRepository` 实现 `RouteDefinitionRepository`：
  - 每个服务生成一条路由；
  - `Path=/js/a/**`；
  - URI 用占位符 `http://gateway.invalid`；
  - metadata 携带 `serviceId`；
  - 按路径前缀长度降序设置 route order，保证更长前缀优先。
- `GatewayRegistry` 从数据库加载服务/节点快照。
- 配置变化后发布 `RefreshRoutesEvent`，清理路由缓存。
- `StickyRouteFilter`（order 10001，排在 `RouteToRequestUrlFilter` 之后）负责把占位 URI 改写成实际节点地址。

### 7.3 过滤器与核心类

| 组件 | 职责 |
|---|---|
| `LoginRequestFilter`（order 9999） | 登录路径请求体缓存、username 解析、`Accept-Encoding: identity` |
| `LoginResponseFilter`（order 10002） | 登录响应缓存解析、首次成功登录绑定、token 缓存 |
| `StickyRouteFilter`（order 10001） | 粘性节点选择、节点健康校验、URL 重写、`X-Gateway-Node` 响应头、503 错误输出 |
| `TokenResolver` | Redis token 缓存 → sa-token Redis 兜底，阻塞调用放 `boundedElastic` |
| `UserRouteService` / `UserRouteRepository` | username/userId 路由查询、`bindIfAbsent`、管理端重绑/解绑、存量用户导入 |
| `NodeSelector` | 轮询选择健康节点，跳过 disabled/DOWN |
| `HealthChecker` + `NodeHealthRegistry` | 定时探测、失败阈值、状态变更日志 |
| `AdminAuthWebFilter` | `x-token` → userId → `sys_user.is_admin=1 && status=1`，叠加 IP 白名单；管理接口关闭时返回 404 |
| `GatewayErrorHandler` | 连接失败/超时统一返回 502，其他异常 500，响应体沿用 `{code,message,data}` |
| `CorsConfig` | `allowedOriginPatterns=*`、暴露 `X-Gateway-Node`；`x-token` 不走 Cookie，允许无凭证跨域 |
| `RequestIdFilter` | 透传/生成 `X-Request-Id`，日志按请求串联 |

### 7.4 流式与请求体

- 除登录外不缓存请求/响应，上传、下载、SSE 全部走 Netty 流式转发。
- `spring.cloud.gateway.httpclient.connect-timeout=3s`，`response-timeout=0s`（SSE 不设总超时），关闭客户端压缩。
- 保留 `Range`、`Content-Type`、`x-token`、Cookie 等端到端头；SCG 自动剔除 hop-by-hop 头。
- 登录体 ≤64KB、登录响应 ≤256KB；超出返回 413/502，避免大响应被缓存。
- 后端返回的 4xx/5xx 状态码、响应头、响应体原样透传。

### 7.5 错误响应

- 用户绑定节点不可用：HTTP 503 + `{code:503,message:"用户绑定的后端节点不可用：node-2，请稍后重试或联系管理员"}`。
- 无健康节点：HTTP 503 + 明确提示。
- 上游连接失败/超时：HTTP 502 + 明确提示。
- 管理接口未登录：HTTP 401；非管理员：HTTP 403。
- 不在错误信息里暴露后端完整地址，只暴露节点 ID。

### 7.6 配置热更新

- 管理接口写库后立即刷新本实例路由。
- 其他网关实例每 10 秒比对 `max(update_time) + count`，有变化则重载服务/节点并刷新路由。
- 用户路由变更直接更新 PostgreSQL 和 Redis，所有网关实例立即生效。
- 健康状态是每个网关实例自己的内存状态，不跨实例同步。

---

## 8. 管理 API（`/gateway/admin/**`）

所有接口要求管理员登录态（`x-token`），可选 IP 白名单。

```text
GET    /gateway/admin/status                       服务、节点、健康状态、绑定用户数
GET    /gateway/admin/services
POST   /gateway/admin/services
PUT    /gateway/admin/services/{serviceId}
DELETE /gateway/admin/services/{serviceId}         （有节点/路由时拒绝）
POST   /gateway/admin/services/{serviceId}/nodes
PUT    /gateway/admin/nodes/{nodeId}               修改地址/启停
DELETE /gateway/admin/nodes/{nodeId}               有绑定用户时拒绝
POST   /gateway/admin/nodes/{nodeId}/check         手动探活
GET    /gateway/admin/routes?serviceId=&keyword=&page=&size=
POST   /gateway/admin/routes/bind                  {serviceId,username|userId,nodeId} 预绑定/重绑
DELETE /gateway/admin/routes/{id}                  解绑并清 Redis 缓存
POST   /gateway/admin/routes/import-existing       {serviceId,nodeId} 把 sys_user 存量用户批量绑到该节点
POST   /gateway/admin/reload                       强制刷新配置
```

### 8.1 校验规则

- 服务 id：`^[a-z][a-z0-9-]{1,63}$`。
- `path-prefix` 必须以 `/` 开头、不能以 `/` 结尾、不能是 `/gateway`，且全局唯一。
- `base-url` 必须是 `http(s)://host[:port]`，不含 path/query/fragment。
- 节点 id 全局唯一。
- 绑定时节点必须属于对应服务且启用。
- 删除服务/节点前检查关联数据，返回 409。

### 8.2 存量用户导入

`POST /gateway/admin/routes/import-existing` 的核心 SQL：

```sql
INSERT INTO gateway_user_route (service_id, user_id, username, node_id)
SELECT :serviceId, u.id, u.username, :nodeId
FROM sys_user u
WHERE NOT EXISTS (
    SELECT 1 FROM gateway_user_route r
    WHERE r.service_id = :serviceId
      AND (r.user_id = u.id OR lower(r.username) = lower(u.username))
)
ON CONFLICT DO NOTHING;
```

用于网关首次上线时把现有用户全部归到当前唯一后端，避免存量用户被分配错机器。

---

## 9. 文件清单

```text
pom.xml                                          + ai-gateway 模块
sql/gateway.sql                                  三张表 DDL
ai-gateway/pom.xml
ai-gateway/src/main/resources/application.yaml
ai-gateway/src/main/resources/application-dev.yaml
ai-gateway/src/main/java/com/zsjz/gateway/
  GatewayApplication.java
  config/GatewayProperties.java
  config/CorsConfig.java
  config/WebClientConfig.java
  registry/GatewayRegistry.java
  registry/GatewayConfigRepository.java
  registry/HealthChecker.java
  registry/NodeHealthRegistry.java
  route/GatewayRouteDefinitionRepository.java
  route/LoginRequestFilter.java
  route/LoginResponseFilter.java
  route/StickyRouteFilter.java
  route/TokenResolver.java
  route/UserRouteService.java
  route/UserRouteRepository.java
  route/NodeSelector.java
  route/GatewayAttributes.java
  admin/AdminController.java
  admin/AdminService.java
  admin/AdminAuthWebFilter.java
  support/ApiResult.java
  support/GatewayErrorHandler.java
  support/RequestIdFilter.java
  support/IpWhitelist.java
ai-gateway/src/test/java/com/zsjz/gateway/...     单元测试 + 集成测试
ai-gateway/README.md                             架构、配置、接口、部署、排障
AI_AGENT.md                                      仓库结构补充 ai-gateway
```

---

## 10. 部署与切换步骤

1. 在现有唯一的 ai-server 上确认工作目录、授权和 `QingJian/` 数据目录。
2. 启动网关，配置 `node-1` 指向现有后端，`default-node-id=node-1`。
3. 调用 `POST /gateway/admin/routes/import-existing {serviceId:"zsjz-ai",nodeId:"node-1"}`，把现有 `sys_user` 全部绑定到 node-1；未导入的用户也会走 default-node 兜底。
4. 把前端 `VITE_GLOB_API_URL`（或打包后的 `_app.config.js`）改为 `http://<gateway>:8080`；开发环境把 `VITE_PROXY` 指向网关。
5. 验证登录、案件打开、附件上传、SSE 聊天都走同一节点。
6. 再部署 node-2，新用户由轮询分配，或管理员预绑定。
7. 防火墙只允许客户端访问网关端口，禁止直接访问 8980；否则用户可以绕过粘性。
8. 每台 ai-server 仍需独立授权和独立数据目录；不要共享 DuckDB 文件。

后端不需要改代码；可选加一行 `server.forward-headers-strategy: framework`，让后端正确识别 `X-Forwarded-*`。

---

## 11. 测试与验收

### 11.1 单元测试

- 登录体解析（正常/空/非法 JSON/超大）。
- 首次登录绑定、并发 `bindIfAbsent` 唯一性、登录失败不绑定。
- token 缓存命中/未命中、sa-token 兜底。
- 节点轮询跳过 DOWN/disabled、绑定节点 DOWN 返回 503。
- 管理接口权限（非管理员 403、停用用户 403、IP 白名单）。

### 11.2 集成测试

使用 Testcontainers PostgreSQL + Redis + WireMock 两个后端：

- 用户 A 首次登录 → node-1；后续带 token 请求始终 node-1；用户 B → node-2。
- node-1 停止探活后，A 的请求返回 503；恢复后继续 node-1，且不切 node-2。
- 管理接口新增/禁用节点后路由即时生效；重绑用户后新请求切到新节点。
- SSE 分块响应不被缓冲；multipart 上传和 Range 下载原样透传。
- 清空 Redis 路由缓存后能从 PostgreSQL 重新加载。
- 存量用户导入后，已有 token 的请求能正确路由。

### 11.3 人工验收

- 两台真实 ai-server（各自独立工作目录和授权）分别登录两个用户。
- 打开案件、上传附件、发起 SSE 研判，确认 `X-Gateway-Node` 始终一致。
- 停掉一台后端，确认 503 提示可读且没有跨节点写入。
- 直接访问后端 8980 被防火墙拒绝，只能经过网关。

### 11.4 验收标准

1. 配置两个后端节点后，`/js/a/**` 的所有请求自动转发，无需逐接口配置。
2. 同一用户首次登录后，后续所有请求（含 SSE、上传、下载）固定到同一节点。
3. 不同用户可分配到不同节点。
4. 绑定节点故障返回明确 503，不自动切换。
5. 管理接口可在不重启网关的情况下增删/启停节点、查看和重绑用户。
6. 现有用户可通过导入接口一次性绑定到当前节点，旧 token 继续可用。
7. 单元测试和集成测试通过。

---

## 12. 不在本期范围

- 用户数据在两台机器之间的自动迁移。
- 节点故障自动切换/共享存储。
- MCP 会话级粘性（本期固定节点）。
- 管理 UI（本期只提供 REST 接口）。
- 限流、TLS 终止、深度健康检查。
- 自助注册页面（当前仓库没有；如有需要，未来在注册成功后调用绑定服务）。
- 按案件粘性（本期按用户；当前案件仅创建者可见，用户级粘性已覆盖）。

---

## 13. 风险与注意事项

| 风险 | 说明 | 应对 |
|---|---|---|
| 网关只读耦合 `sys_user` | 绑定用户和管理员校验需要读 `sys_user.id/username/is_admin/status` | 字段变更时同步网关；只读不写 |
| 健康检查较浅 | `/sys/health` 只证明进程存活，不检查 PG/Redis/ES | 节点级探活够用；后续可加深度健康接口 |
| 登录响应结构变化 | 首次绑定依赖 `Result + LoginVO` 的 `code/data.userId/data.username` | 结构变化时调整解析，或改用管理端预绑定 |
| 多服务鉴权差异 | 网关共用一套 sa-token Redis/token-name | 本期所有服务复用同一套鉴权；未来扩展为按服务配置 |
| 绕过网关 | 用户直连 8980 会落到非绑定节点 | 防火墙限制后端端口只对网关开放 |
| 节点 DOWN 即不可用 | 按设计不自动切换，用户会看到 503 | 运维尽快恢复节点；提供管理端重绑（需人工确认数据位置） |
| MCP 无鉴权 | 现有 `/mcpsse` 等端点本身无 token | 网关固定节点 + 防火墙限制来源 |
| 每机授权 | 多台 ai-server 需要各自机器码授权 | 部署前逐台申请/导入授权 |
| Redis 清空 | 路由缓存和 sa-token 都会丢 | 用户重新登录；路由从 PostgreSQL 恢复 |
| 并发首次登录 | 两个网关同时为同一用户选不同节点 | 数据库唯一索引裁决，后到者读取赢家 |

---

## 14. 一句话总结

新增 `ai-gateway`（Spring Cloud Gateway WebFlux），用“首次登录成功绑定 + `x-token`→userId→node 的 Redis/PG 两级路由”把每个用户固定到一台 ai-server；配置由 YAML 播种、PostgreSQL 持久化、管理接口热更新；节点故障明确返回 503，不做破坏本地数据一致性的自动切换。