# 后端服务架构
**本文引用的文件**
- [ai-server/pom.xml](file://ai-server/pom.xml)
- [application.yaml](file://ai-server/src/main/resources/application.yaml)
- [application-dev.yaml](file://ai-server/src/main/resources/application-dev.yaml)
- [application-pro.yaml](file://ai-server/src/main/resources/application-pro.yaml)
- [DataSourceConfig.java](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java)
- [CaseRoutingDataSource.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java)
- [CaseDataSourceReaper.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java)
- [SaTokenWebConfig.java](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java)
- [CorsConfig.java](file://ai-server/src/main/java/com/zsjz/ai/common/config/CorsConfig.java)
- [AuthController.java](file://ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java)
- [SystemController.java](file://ai-server/src/main/java/com/zsjz/ai/module/plat/controller/SystemController.java)
- [SseService.java](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SseService.java)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [新增业务模块标准模板](#新增业务模块标准模板)
8. [性能与可观测性建议](#性能与可观测性建议)
9. [故障排查指南](#故障排查指南)
10. [结论](#结论)
## 简介
本文件聚焦 ai-server 的 Spring Boot 后端服务架构,目标是帮助开发者理解:
- 模块化原则:plat、agent、aiclean、knowledge、graph、person、call、trans、track、govern、search、dm、otg、external 等业务模块的职责边界。
- 分层结构:每个模块通常由 Controller / Service / Mapper(MyBatis-Plus)组成,实体放在 `com.zsjz.ai.common.model..entity` 下。
- 多数据源切换:基于 MyBatis-Plus + Dynamic Datasource,主库 PostgreSQL/pgvector,案件级 DuckDB,通过注解和自定义路由动态切换。
- 横切能力:Sa-Token 认证、跨域、SSE 心跳保活、定时任务、工作空间与案件数据源清理等。
- 扩展方式:给出新增模块的标准步骤,以及性能与可观测性建议。
## 项目结构
ai-server 是一个 Spring Boot 应用,采用“公共基础设施 + 业务模块”的组织方式:
- `common`:跨模块配置、上下文、缓存、异常、统一响应、数据源路由、安全拦截等横切能力。
- `module`:按领域划分的业务模块,每个模块内部再分 controller、service、mapper、entity、vo、dto、config 等包。
- `resources`:Spring Boot 配置文件,包含通用配置、开发环境与生产环境 profile。
- `scripts`:部署脚本;`sql`:数据库初始化与增量脚本。
```mermaid
graph TB
Client["前端或调用方"] --> Web["Spring MVC
Controller 层"]
Web --> Common["横切能力
Sa-Token / CORS / 全局异常"]
Web --> Modules["业务模块
plat / agent / aiclean / knowledge / graph / person / call / trans / track / govern / search / dm / otg / external"]
Modules --> Services["Service 业务逻辑"]
Services --> Mappers["Mapper
MyBatis-Plus"]
Mappers --> DS["数据源路由
CaseRoutingDataSource"]
DS --> PG["PostgreSQL / pgvector"]
DS --> DuckDB["DuckDB 案件库"]
Services --> Redis["Redis"]
Services --> ES["Elasticsearch"]
```
**图示来源**
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
- [application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87)
- [DataSourceConfig.java:1-38](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java#L1-L38)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
**章节来源**
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
- [application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87)
- [application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87)
## 核心组件
- **Spring Boot 基础栈**:web、validation、redis、aop、configuration-processor、Lombok、Slf4j。
- **数据访问**:MyBatis-Plus 3.5.17、Dynamic Datasource 4.5.0、JSqlParser、PostgreSQL 驱动、pgvector Java SDK、DuckDB JDBC。
- **认证授权**:Sa-Token 1.46.0,仅做登录态校验,不引入完整权限体系。
- **AI 生态**:AgentScope 2.0.4、Spring AI BOM、DashScope/Ollama/OpenAI 模型扩展、mem0、RAG simple、Redis 扩展、Tika 文档读取。
- **推理与向量**:DJL HuggingFace tokenizers、ONNX Runtime CPU、本地 bge-m3 嵌入模型(可选)。
- **外部系统**:Neo4j、Elasticsearch、Redis。
这些依赖集中在 ai-server 的 Maven 工程中,并配合 application.yaml 中的环境变量占位符实现可部署化。
**章节来源**
- [ai-server/pom.xml:1-200](file://ai-server/pom.xml#L1-L200)
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
## 架构总览
ai-server 的请求路径如下:
1. 浏览器或桌面客户端发起 HTTP 请求。
2. 先经过 CORS Filter,处理预检请求和跨域头。
3. 进入 Sa-Token Filter,包装会话上下文。
4. 经过 LicenseFilter、SaInterceptor 校验登录。
5. 到达 Controller,再由 Service 执行业务逻辑。
6. 需要数据库时,通过 MyBatis-Plus Mapper 访问数据源。
7. 数据源根据注解或上下文,路由到 PostgreSQL、pgvector 或当前案件的 DuckDB。
8. 长连接场景使用 SSE 推送清洗、治理、研判进度;定时任务负责资源回收与看门狗。
```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant Cors as "CORS Filter"
participant Sa as "Sa-Token Filter"
participant Auth as "SaInterceptor"
participant Ctrl as "Controller"
participant Svc as "Service"
participant Map as "Mapper"
participant DS as "CaseRoutingDataSource"
participant PG as "PostgreSQL/pgvector"
participant Duck as "DuckDB"
Browser->>Cors: "HTTP 请求"
Cors-->>Browser: "跨域响应头"
Browser->>Sa: "带 x-token 的请求"
Sa-->>Auth: "携带会话上下文"
Auth->>Ctrl: "校验通过后转发"
Ctrl->>Svc: "调用业务方法"
Svc->>Map: "执行 SQL"
Map->>DS: "按 @DS 或 slave key 获取数据源"
alt "主库或普通业务"
DS->>PG: "PostgreSQL"
else "案件数据"
DS->>Duck: "DuckDB 案件库"
end
Duck-->>Map: "结果集"
PG-->>Map: "结果集"
Map-->>Svc: "实体或 VO"
Svc-->>Ctrl: "业务结果"
Ctrl-->>Browser: "Result 包装响应"
```
**图示来源**
- [CorsConfig.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/common/config/CorsConfig.java#L1-L70)
- [SaTokenWebConfig.java:1-65](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L1-L65)
- [DataSourceConfig.java:1-38](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java#L1-L38)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
## 详细组件分析
### 模块化原则与职责边界
业务模块按领域划分,典型结构为:
- `module//controller`:对外 REST 接口。
- `module//service`:业务编排与事务边界。
- `module//mapper`:MyBatis-Plus Mapper 接口。
- `common/model//entity`:持久化实体。
- `module//vo` / `dto`:视图对象与入参对象。
各模块主要职责如下:
- **plat**:平台基础能力,包括用户、认证、系统信息、表结构管理、SSE 推送、案例基本信息、塔台监听等。
- **agent**:智能体能力,包括模型管理、聊天会话、消息、意图中间件、提示词加载、工作空间脚手架、RAG 索引状态、专家与工具包等。
- **aiclean**:AI 清洗看门狗、DuckDB 辅助执行、模板元数据向量索引等。
- **knowledge**:知识库相关控制器与服务。
- **graph**:图谱查询、历史关系等图数据能力。
- **person**:人员画像、亲密度、常住人口、分组等。
- **call**:通话记录、夜间通话、连续通话、敏感通话等。
- **trans**:交易流水、大额、频率、资金流向、固定存款、金融类、敏感交易等。
- **track**:轨迹追踪,包括快递、同乘、同住、手机基站、本地轨迹、会面等。
- **govern**:治理任务、治理树、治理配置、结果处理器等。
- **search**:搜索相关控制器与服务。
- **dm**:数据建模、文件识别、清洗错误日志、边配置、人物关系边等。
- **otg**:特殊日期、时间序列、搜索入口等。
- **external**:外部数据,如逃犯、车辆、共同居住、刑事信息等。
这种组织方式使每个模块只关注自身领域对象,并通过 Service 暴露业务能力;Controller 保持薄,只做参数校验与 Result 包装。
**章节来源**
- [AuthController.java:1-82](file://ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java#L1-L82)
- [SystemController.java:1-200](file://ai-server/src/main/java/com/zsjz/ai/module/plat/controller/SystemController.java#L1-L200)
### 多数据源配置与切换机制
ai-server 使用 MyBatis-Plus 与 Dynamic Datasource 组合,实现主库 PostgreSQL/pgvector 与案件级 DuckDB 的动态切换。
关键设计点:
- `spring.datasource.dynamic.primary` 默认指向 master,即 PostgreSQL。
- `spring.datasource.dynamic.strict=true` 保证写错数据源 key 时直接报错,而不是静默回退到主库。
- 业务中大量 Mapper 标注 `@DS(StrConsts.DS_KEY_SLAVE)`,表示走“从库分支”。
- 项目用 `CaseRoutingDataSource` 替换 Dynamic Datasource 自动装配的 `DynamicRoutingDataSource`,把逻辑 key `slave` 映射到物理 key `case{caseId}`。
- 物理 key 不能含下划线,否则会被当成数据源组名,导致随机串库。
- 未打开案件时,路由会返回 400 业务异常,而不是抛 500 服务端异常。
- DuckDB 作为案件库,由 `CaseDataSourceRegistry` 管理生命周期,并由 `CaseDataSourceReaper` 兜底回收。
```mermaid
flowchart TD
Start["业务调用 Mapper"] --> CheckDS{"是否标注 slave?"}
CheckDS -->|否| UseMaster["使用 master:PostgreSQL/pgvector"]
CheckDS -->|是| GetCase["从 CaseContextHolder 取 caseId"]
GetCase --> HasCase{"caseId 是否存在?"}
HasCase -->|否| Error400["返回 400:请先打开案件"]
HasCase -->|是| PhysicalKey["生成物理 key:case{caseId}"]
PhysicalKey --> Exists{"DuckDB 数据源已注册?"}
Exists -->|否| Error400b["返回 400:数据源未打开或已释放"]
Exists -->|是| ReturnDuck["返回 DuckDB 连接"]
```
**图示来源**
- [DataSourceConfig.java:1-38](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java#L1-L38)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
- [application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87)
- [application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87)
**章节来源**
- [DataSourceConfig.java:1-38](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java#L1-L38)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
- [application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87)
- [application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87)
### Sa-Token 认证与会话保活
Sa-Token 在项目中承担“登录态校验”职责,不负责复杂角色权限:
- 所有非白名单接口都会触发 `StpUtil.checkLogin()`。
- 白名单包括 `/auth/login`、`/sys/health`、`/sys/checkAuth`、`/sys/info`、`/sys/code`、`/sys/noNet`、`/sys/map/**`、`/error`。
- 登录后请求会记录一次“活跃”,用于判断账号是否正在被其他设备顶下线。
- 生产默认单端登录,后登录顶掉前登录;联调时可开启多端。
- Redis 是登录态硬依赖,不可用时直接抛异常。
- 前端通过 `x-token` 请求头传递令牌,需与后端 Sa-Token 配置一致。
```mermaid
sequenceDiagram
participant Client as "前端"
participant Sys as "SystemController"
participant Auth as "AuthController"
participant Sa as "Sa-Token"
participant Redis as "Redis"
Client->>Sys: "GET /sys/health"
Sys-->>Client: "健康检查成功"
Client->>Auth: "POST /auth/login"
Auth->>Sa: "创建会话"
Sa->>Redis: "写入 token 与登录映射"
Auth-->>Client: "返回 x-token"
Client->>Client: "后续请求携带 x-token"
Client->>Sys: "业务请求"
Sa->>Redis: "校验 token"
Sys-->>Client: "返回业务数据"
```
**图示来源**
- [SaTokenWebConfig.java:1-65](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L1-L65)
- [AuthController.java:1-82](file://ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java#L1-L82)
- [application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87)
- [application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87)
**章节来源**
- [SaTokenWebConfig.java:1-65](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L1-L65)
- [AuthController.java:1-82](file://ai-server/src/main/java/com/zsjz/ai/module/plat/controller/AuthController.java#L1-L82)
- [application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87)
- [application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87)
### SSE 心跳保活与实时推送
SSE 用于向前端推送清洗、治理、研判等任务的实时进度:
- 每个登录用户维护一个 `SseEmitter`,避免多人使用时互相覆盖。
- 同一用户重复连接会断开旧连接,保留最新连接。
- 建立连接后立即推送一条初始消息,便于前端快速感知连接成功。
- 定时任务每 5 秒向所有活跃连接发送心跳,防止代理或浏览器断开空闲连接。
- 推送失败时关闭对应连接,并记录日志。
- 推送内容会补齐当前 `caseId`,让前端能按案件丢弃上一个任务的残留进度。
```mermaid
sequenceDiagram
participant Frontend as "前端"
participant Sse as "SseService"
participant Scheduler as "调度器"
Frontend->>Sse: "建立 SSE 连接"
Sse-->>Frontend: "返回 SseEmitter"
Sse->>Frontend: "推送连接成功消息"
loop "每 5 秒"
Scheduler->>Sse: "触发 fixedSee()"
Sse->>Frontend: "推送心跳消息"
end
Frontend->>Sse: "断开连接"
Sse-->>Frontend: "移除连接引用"
```
**图示来源**
- [SseService.java:1-172](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SseService.java#L1-L172)
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
**章节来源**
- [SseService.java:1-172](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SseService.java#L1-L172)
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
### 定时任务与工作空间、案件数据源清理
定时任务运行在 Spring 调度线程池中,默认大小为 4,避免单个批量任务拖住 SSE 心跳:
- SSE 心跳:每 5 秒广播心跳。
- 数据源回收:周期性扫描已打开的案件 DuckDB 数据源,若归属 token 失效且无在途任务,则关闭数据源并清理缓存。
- AI 清洗看门狗:标记长时间没有推进的清洗批次为失败,等待用户重新触发。
- 附件孤儿清理:清理长期未发消息对应的聊天附件。
- 工作空间脚手架与 Agent 生命周期:由 agent 模块负责工作空间初始化与清理。
`CaseDataSourceReaper` 的核心策略是“保守回收”:
- 优先按 owner token 判断会话是否存活。
- 若该案件仍有业务模块注册的“在途任务探针”,则跳过回收。
- 查询会话状态失败时,宁可多占内存也不误关正在使用的案件数据源。
```mermaid
flowchart TD
Start["定时触发回收"] --> Empty{"是否有已打开案件?"}
Empty -->|否| End["结束本轮"]
Empty -->|是| Iterate["遍历每个 caseId"]
Iterate --> Owner["获取归属 userId 与 token"]
Owner --> Alive{"归属会话仍有效?"}
Alive -->|是| Next["下一个案件"]
Alive -->|否| Busy{"是否有在途任务?"}
Busy -->|是| Skip["跳过回收"]
Busy -->|否| Close["关闭 DuckDB 数据源并清理缓存"]
Close --> Next
Next --> Iterate
```
**图示来源**
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
**章节来源**
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
## 依赖关系分析
ai-server 的依赖可分为四层:
- **表现层**:Spring MVC Controller,提供 REST API。
- **业务层**:Service 封装领域逻辑,协调多个 Mapper、缓存、外部系统。
- **数据层**:MyBatis-Plus Mapper 与 Dynamic Datasource 路由。
- **外部依赖**:PostgreSQL、pgvector、DuckDB、Redis、Elasticsearch、Neo4j、外部大模型与推理引擎。
```mermaid
graph LR
Controller["Controller"] --> Service["Service"]
Service --> Mapper["Mapper"]
Mapper --> DataSource["CaseRoutingDataSource"]
DataSource --> Postgres["PostgreSQL / pgvector"]
DataSource --> Duck["DuckDB"]
Service --> Cache["Redis"]
Service --> Search["Elasticsearch"]
Service --> Graph["Neo4j"]
```
**图示来源**
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
- [DataSourceConfig.java:1-38](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java#L1-L38)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
**章节来源**
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
- [DataSourceConfig.java:1-38](file://ai-server/src/main/java/com/zsjz/ai/common/config/DataSourceConfig.java#L1-L38)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
## 新增业务模块标准模板
新增业务模块应遵循以下流程:
1. **新建 module 包**
- 在 `com.zsjz.ai.module.` 下创建模块根包。
- 至少包含 `controller`、`service`、`mapper`、`vo`、`dto`。
- 如果模块有实体,将实体放在 `com.zsjz.ai.common.model..entity`。
2. **定义实体与 Mapper**
- 实体使用 Lombok 简化代码。
- Mapper 继承 MyBatis-Plus 的基础接口,必要时编写 XML。
- 如果读主库,不加 `@DS`;如果读案件数据,加 `@DS(StrConsts.DS_KEY_SLAVE)`。
3. **实现 Service**
- Service 封装业务规则、事务边界、缓存操作。
- 如需异步或后台任务,结合 SSE 推送进度。
- 如需访问 DuckDB,确保当前用户已打开案件。
4. **注册 Controller 路由**
- 使用 `@RestController` 与 `@RequestMapping`。
- 返回统一 `Result` 包装。
- 需要登录的方法自动受 Sa-Token 保护;公开接口加入白名单。
5. **维护数据库脚本**
- 在 `sql` 目录下新增或更新建表、索引、初始数据脚本。
- 明确说明所属环境、版本号、是否幂等。
- 如果是案件库表,注意 DuckDB 与 PostgreSQL 的差异。
6. **验证多数据源行为**
- 确认 Mapper 的 `@DS` 注解正确。
- 测试未开案时的 400 错误。
- 测试开案后 DuckDB 数据可读。
- 测试 token 过期后数据源被回收。
```mermaid
flowchart TD
NewModule["新建模块包"] --> Entity["定义 entity"]
Entity --> MapperDef["定义 mapper"]
MapperDef --> ServiceImpl["实现 service"]
ServiceImpl --> ControllerDef["实现 controller"]
ControllerDef --> Route["注册路由"]
Route --> Sql["维护数据库脚本"]
Sql --> Test["验证主库与案件库"]
Test --> Done["完成"]
```
[此图为概念流程,不对应具体源码文件]
## 性能与可观测性建议
### 性能建议
- **控制并发 DuckDB 实例**:通过 `zsjz.duckdb.max-open-cases` 限制同时打开的案件数,避免内存耗尽。
- **分摊 DuckDB 预算**:按 `memory-ratio` 与 `threads-per-instance` 控制每个案件实例的资源占用。
- **限制文件 AI 识别并发**:`zsjz.file-ai.max-concurrent` 与 `max-pending` 防止一次性上传打爆队列。
- **限制向量模型资源**:本地 bge-m3 模型首次加载耗时较长,可通过 `eager-load=false` 懒加载,并结合 `intra-op-threads`、`opt-level` 调整。
- **合理设置 SSE 心跳**:5 秒心跳适合大多数代理与浏览器,但高并发时需评估心跳负载。
- **扩大调度线程池**:默认 4 线程已隔离心跳、数据源回收、AI 清洗看门狗、附件清理,避免相互阻塞。
- **避免跨域滥用**:生产环境收敛 `allowed-origin-patterns`,减少预检请求。
### 可观测性建议
- **日志级别**:数据源路由、SSE 心跳、数据源回收都应保留 debug 日志,用于排查串库、连接泄漏。
- **指标采集**:建议接入 Micrometer 或 Prometheus,采集:
- 已打开 DuckDB 数量。
- SSE 活跃连接数。
- Redis、PostgreSQL、Elasticsearch 探测耗时。
- AI 清洗批次成功率、失败率、超时率。
- **链路追踪**:对长耗时接口增加 traceId,便于前端上报问题后定位后端链路。
- **健康检查增强**:除 `/sys/health` 外,可增加 `/sys/detailedHealth`,暴露各依赖的健康状态。
- **告警规则**:
- DuckDB 打开数接近上限。
- SSE 连接数异常下降。
- Redis 不可用。
- AI 清洗批次大量超时。
**章节来源**
- [application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193)
- [SseService.java:1-172](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SseService.java#L1-L172)
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
## 故障排查指南
### 常见问题
- **前端连不上后端**
- 检查 CORS 是否启用,桌面端 `file://` 必须允许跨域。
- 检查是否因预检请求被 Sa-Token 拦截,CORS Filter 必须排在最前。
- **登录后仍报 401**
- 检查前端是否正确设置 `x-token`。
- 检查 Redis 是否可用,Sa-Token 强依赖 Redis。
- **查不到案件数据**
- 检查是否已打开案件。
- 检查 Mapper 是否标注 `@DS(slave)`。
- 检查 DuckDB 数据源是否已注册。
- **数据串库**
- 检查物理 key 是否含下划线。
- 检查 `strict=true` 是否生效。
- **SSE 断流**
- 检查代理是否支持 SSE。
- 检查心跳是否被防火墙或负载均衡器中断。
- **DuckDB 无法新打开案件**
- 检查 `max-open-cases` 是否已满。
- 检查 `CaseDataSourceReaper` 是否正常回收。
### 排查步骤
1. 查看 `/sys/health` 与 `/sys/serviceHealth`,确认后端与依赖可用性。
2. 查看 Sa-Token 是否创建 token,Redis 中是否有登录映射。
3. 查看数据源路由日志,确认 `slave` 是否路由到 `case{caseId}`。
4. 查看 DuckDB 连接数与内存使用情况。
5. 查看 SSE 连接数与心跳日志。
6. 查看清洗、治理任务的看门狗日志。
**章节来源**
- [CorsConfig.java:1-70](file://ai-server/src/main/java/com/zsjz/ai/common/config/CorsConfig.java#L1-L70)
- [SaTokenWebConfig.java:1-65](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L1-L65)
- [CaseRoutingDataSource.java:1-68](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseRoutingDataSource.java#L1-L68)
- [SseService.java:1-172](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SseService.java#L1-L172)
- [CaseDataSourceReaper.java:1-125](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L1-L125)
## 结论
ai-server 的后端架构以 Spring Boot 为基础,通过模块化拆分业务领域,通过 MyBatis-Plus 与 Dynamic Datasource 实现 PostgreSQL/pgvector 与 DuckDB 的多数据源切换,通过 Sa-Token 实现轻量认证,通过 SSE 与定时任务实现实时推送与资源回收。新增模块时应严格遵循 controller-service-mapper 分层,并在数据库脚本中维护表结构。未来可继续补充指标采集、链路追踪与健康检查增强,以提升系统的可观测性与稳定性。