zsjz-ai/.qoder/repowiki/zh/content/部署与运维/日志、监控与故障排查.md

日志、监控与故障排查

本文引用的文件

• deploy/env.sh
• ai-gateway/src/main/resources/application.yaml
• ai-gateway/src/main/resources/application-dev.yaml
• ai-gateway/src/main/resources/application-pro.yaml
• ai-server/src/main/resources/application.yaml
• ai-server/src/main/resources/application-dev.yaml
• ai-server/src/main/resources/logback-spring.xml
• ai-electron/electron/config/config.default.ts
• ai-electron/electron/main.ts
• ai-electron/electron/config/windowOptions.ts
• ai-electron/frontend/src/core/utils/http/axios/Axios.ts
• ai-electron/frontend/src/core/settings/serverSetting.ts
• ai-electron/frontend/src/ai/api/sse.ts
• ai-electron/frontend/src/core/utils/map/offlineMap.ts
• ai-electron/cmd/builder.json
• ai-electron/package.json

目录

1. 简介
2. 项目结构与日志位置总览
3. 标准日志规范
4. 关键监控指标
5. 架构与调用链概览
6. 详细组件分析
7. 依赖关系分析
8. 性能注意事项
9. 常见故障排查清单
10. 备份与恢复建议
11. 结论

简介

本手册面向部署后的运维与技术支持人员，覆盖 ai-gateway、ai-server、Electron 客户端三端的日志收集、监控指标采集和故障排查方法。文档同时给出 PostgreSQL/pgvector、Redis、Elasticsearch、Neo4j、DuckDB、向量模型、Agent SSE、文件上传、登录成功率等关键指标的观测方式，并补充常见问题的定位步骤及 deploy/env.sh 相关配置项。

项目结构与日志位置总览

系统由三层组成：

• 前端 Electron 客户端：负责用户界面、服务地址绑定、SSE 对话、离线地图加载、自动更新。
• 网关 ai-gateway：统一入口、Sa-Token 共享 Redis、节点健康检查、跨域去重。

• 后端 ai-server：业务服务、PostgreSQL/pgvector、Redis、Elasticsearch、Neo4j、DuckDB、本地文件存储、向量模型、Agent 会话与清洗能力。

  graph TB
  Client["Electron 客户端<br/>主进程 + 渲染进程"] --> Gateway["ai-gateway<br/>Spring Cloud Gateway"]
  Gateway --> Server["ai-server<br/>Spring Boot 应用"]
  Server --> PG["PostgreSQL/pgvector"]
  Server --> Redis["Redis<br/>sa-token / 缓存"]
  Server --> ES["Elasticsearch<br/>全文检索索引 zsjz_search"]
  Server --> Neo4j["Neo4j<br/>可选图谱"]
  Server --> DuckDB["DuckDB<br/>案件库"]
  Server --> Files["本地文件存储<br/>./data/files"]
  Client --> Map["离线 PMTiles<br/>china.pmtiles"]
  

图表来源

• ai-gateway/src/main/resources/application.yaml:1-81
• ai-server/src/main/resources/application.yaml:1-193
• ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200

章节来源

• ai-gateway/src/main/resources/application.yaml:1-81
• ai-server/src/main/resources/application.yaml:1-193
• deploy/env.sh:1-172

标准日志规范

ai-server 日志

• 日志框架：Logback（通过 Spring Boot 默认集成）。
• 当前根日志级别为 debug，仅输出到控制台。
• 部署后应把根日志级别调整为 info 或 warn，避免调试日志污染生产输出；若需要落盘，应扩展 logback-spring.xml，增加按日期滚动的文件 appender，并把 root 指向该文件 appender。
• 建议按模块分类输出，例如：
  • com.zsjz.ai.module.plat：平台、登录、用户、许可证。
  • com.zsjz.ai.module.agent：Agent、SSE、Insight。
  • com.zsjz.ai.module.aiclean：AI 清洗、模板匹配、向量索引。
  • com.zsjz.ai.module.knowledge：知识库、文档索引。
  • com.zsjz.ai.common：异常处理、缓存、数据源、认证。
  • org.springframework：框架层错误单独输出，便于快速发现启动或调度问题。

当前配置文件只启用控制台输出，没有独立文件路径，因此生产环境必须额外配置日志文件，否则无法通过常规日志文件收集。

章节来源

• ai-server/src/main/resources/logback-spring.xml:1-10
• ai-server/src/main/resources/application.yaml:1-193

ai-gateway 日志

• ai-gateway 是 Spring Cloud Gateway 应用，默认使用 Spring Boot 的 Logback。
• 其 application.yaml 主要暴露端口、Profile、Sa-Token、Gateway 跨域去重、服务播种和健康检查间隔，未显式定义独立日志格式或文件路径。
• 建议与 ai-server 一致，将 root 日志级别设为 info/warn，并按 gateway 路由、过滤器、健康检查、Sa-Token 解析等模块拆分日志文件。
• 如果网关只是透传请求，很多业务日志会集中在 ai-server；但网关侧仍需记录：
  • 路由命中与转发目标。
  • 跨域响应头去重结果。
  • Sa-Token 读取失败或 Redis 不可用时的拒绝原因。
  • 节点健康检查失败次数。

章节来源

• ai-gateway/src/main/resources/application.yaml:1-81
• ai-gateway/src/main/resources/application-dev.yaml:1-14
• ai-gateway/src/main/resources/application-pro.yaml:1-14

Electron 客户端日志

主进程日志

• 主进程基于 ee-core/ElectronEgg 启动，main.ts 注册 ready、window-ready、before-close 生命周期。
• 默认配置 logger.level=info，rotator=daily，appLogName=ee.log，coreLogName=ee-core.log，errorLogName=ee-error.log，按日滚动，单文件最大约 100MB。
• 日志目录位于 Electron 应用目录下 logs 子目录；构建产物中 logs 被排除在 asar 之外，便于运维直接查看。

建议：

• 开发时开启 debug/trace 以捕获 IPC、窗口创建、preload 初始化问题。
• 生产保持 info，仅在复现问题时临时提升到 debug。
• 结合 systemd 或桌面任务计划程序归档旧日志。

章节来源

• ai-electron/electron/config/config.default.ts:1-50
• ai-electron/electron/main.ts:1-19
• ai-electron/cmd/builder.json:1-57

渲染进程控制台

• 渲染进程运行前端 Vue 应用，默认关闭 DevTools。
• 前端网络请求通过自定义 Axios 封装，支持拦截器、取消重复请求、FormData 上传。
• 诊断渲染进程问题时，可在打包前临时启用 openDevTools=true，或在开发模式通过 Vite 代理观察浏览器控制台。
• 前端不直接写文件日志，需依靠浏览器控制台、Axios 拦截器日志、SSE 事件回调日志以及服务端日志共同定位。

章节来源

• ai-electron/electron/config/config.default.ts:1-50
• ai-electron/frontend/src/core/utils/http/axios/Axios.ts:1-200

electron-updater 日志

• package.json 依赖 electron-updater，builder.json 中 publish.provider=generic，publish.url 为空字符串。
• 这意味着自动更新功能已引入，但未配置真实更新服务器地址。
• electron-updater 通常会在主进程上下文打印更新检查、下载、解压等日志；具体文件名取决于 ee-core/ElectronEgg 对 electron-updater 的包装。
• 排障时应关注：
  • latest.yml 是否可达。
  • generic provider 的 URL 是否正确。
  • 安装包签名或权限问题。
  • 客户端版本与服务端发布版本不一致导致的静默失败。

章节来源

• ai-electron/package.json:1-42
• ai-electron/cmd/builder.json:1-57

关键监控指标

类别	指标	说明	采集方式	关联配置
PostgreSQL/pgvector	连接数	监控 active、idle、idle_in_transaction 连接数，防止连接泄漏	pg_stat_activity、Prometheus JMX Exporter、数据库自带监控	SPRING_DATASOURCEDYNAMIC*
PostgreSQL/pgvector	慢查询	超过阈值的 SQL 执行时间	pg_stat_statements 或数据库慢查询日志	MyBatis 日志实现为 Slf4jImpl
Redis	命中率	key 命中/未命中比率	INFO stats、Redis 监控面板	SPRING_DATA_REDIS_HOST/PORT
Redis	内存使用	used_memory、evicted_keys、connected_clients	INFO memory、监控工具	SPRING_DATAREDIS*
Elasticsearch	索引状态	zsjz_search 索引 health、shard、doc_count	_cat/indices、Kibana、APM	SPRING_ELASTICSEARCH_URIS
Neo4j	连接数与延迟	活跃连接、查询耗时	Neo4j 监控 API、驱动指标	NEO4J_URI/USERNAME/PASSWORD
DuckDB	打开案件数	同时打开的 DuckDB 实例数量	应用层统计、进程资源监控	ZSJZ_DUCKDB_MAX_OPEN_CASES
向量模型	加载时间	bge-m3 ONNX 模型首次加载耗时	应用日志、JVM 外部内存监控	ZSJZ_EMBEDDING_MODEL_PATH
Agent SSE	心跳	heartbeat 事件是否持续到达	前端 SSE 解析器、后端调度线程池	SPRING_TASK_SCHEDULING_POOL_SIZE
文件上传	文件大小	单次上传大小、队列积压	网关/后端 multipart 配置、应用日志	SPRING_SERVLETMULTIPART*
登录成功率	登录成功/失败比例	401、403、503 占比	网关访问日志、后端异常日志、前端错误上报	Sa-Token、Redis、CORS

章节来源

• deploy/env.sh:1-172
• ai-server/src/main/resources/application.yaml:1-193
• ai-server/src/main/resources/application-dev.yaml:1-87

架构与调用链概览

sequenceDiagram
    participant User as "用户"
    participant Client as "Electron 客户端"
    participant Gateway as "ai-gateway"
    participant Server as "ai-server"
    participant Redis as "Redis"
    participant PG as "PostgreSQL/pgvector"
    participant ES as "Elasticsearch"
    participant DuckDB as "DuckDB"
    participant Model as "向量模型"

    User->>Client: "打开应用并绑定服务地址"
    Client->>Gateway: "GET /js/a/admin/sys/health"
    Gateway->>Server: "转发健康检查"
    Server-->>Gateway: "健康响应"
    Gateway-->>Client: "健康响应"

    User->>Client: "发起登录"
    Client->>Gateway: "POST /js/a/auth/login"
    Gateway->>Server: "转发登录请求"
    Server->>Redis: "写入 sa-token 登录态"
    Server->>PG: "校验用户信息"
    Server-->>Gateway: "返回 x-token"
    Gateway-->>Client: "携带 token 响应"

    User->>Client: "发送 Agent 消息"
    Client->>Gateway: "POST /js/a/agent/stream"
    Gateway->>Server: "转发 SSE 流"
    Server->>PG: "RAG 表结构语义检索"
    Server->>Model: "生成向量或调用在线 embedding"
    Server->>ES: "全文检索辅助"
    Server->>DuckDB: "按需打开案件库"
    Server-->>Client: "SSE token/heartbeat/done/error"

图表来源

• ai-gateway/src/main/resources/application.yaml:1-81
• ai-server/src/main/resources/application.yaml:1-193
• ai-electron/frontend/src/ai/api/sse.ts:1-200
• ai-electron/frontend/src/core/settings/serverSetting.ts:1-200

详细组件分析

ai-gateway 日志与监控要点

• 网关监听 8080 端口，application.yaml 中明确 connect-timeout=3000ms，且注释说明“不设全局响应超时，因为 SSE 研判会长时间保持连接”。
• Sa-Token 配置必须与 ai-server 保持一致，否则共享 Redis 中的登录态无法被网关正确解析。
• 网关默认关闭自身 CORS，避免与后端 CorsFilter 产生重复 Access-Control-Allow-Origin；必要时可打开并配合 DedupeResponseHeader 去重。
• 健康检查 interval=10s、timeout=2s、failure-threshold=3，适合用于上游负载均衡或容器编排的健康探测。

建议采集：

• HTTP 入站 QPS、5xx 比例、平均响应时间。
• 后端节点健康状态变化。
• Sa-Token 解析失败次数。
• Redis 连接失败重试。

章节来源

• ai-gateway/src/main/resources/application.yaml:1-81
• ai-gateway/src/main/resources/application-dev.yaml:1-14
• ai-gateway/src/main/resources/application-pro.yaml:1-14

ai-server 日志与监控要点

• 应用端口 8980，context-path=/js/a。
• 调度线程池默认大小为 4，用于 SSE 心跳、数据源回收、AI 清洗看门狗、附件孤儿清理等定时任务；任何批量任务变慢都会拖住心跳，导致空闲 SSE 连接被代理断开。
• 多部分上传默认最大请求 500MB，单个文件最大 200MB。
• MyBatis 日志实现为 Slf4jImpl，可通过 Slf4j 接入日志系统。
• 向量模型开关控制本地 bge-m3 与在线 embedding 模型切换；本地模型权重常驻堆外内存，首次加载可能较慢。
• DuckDB 打开案件数受 max-open-cases 限制，超出直接拒绝开案。

建议采集：

• JVM CPU、堆外内存、GC 停顿。
• 线程池活跃线程数和队列长度。
• PostgreSQL 连接池使用率。
• Elasticsearch 查询超时次数。
• DuckDB 打开案件数与内存占用。
• 向量模型加载耗时与失败次数。

章节来源

• ai-server/src/main/resources/application.yaml:1-193
• ai-server/src/main/resources/application-dev.yaml:1-87
• ai-server/src/main/resources/logback-spring.xml:1-10

Electron 客户端日志与监控要点

• 主进程默认 info 级别，按日滚动，包含 ee.log、ee-core.log、ee-error.log。
• 渲染进程通过 Axios 封装访问后端，上传走 FormData，相对接口路径会自动拼接 apiUrl。
• SSE 使用原生 fetch 和 ReadableStream，支持 token、thinking、tool_call、heartbeat、done、error 等事件；非事件流响应会被识别为 JSON 错误。
• 离线地图优先使用本机绝对路径 PMTiles，回退到内置静态资源 china.pmtiles。

建议采集：

• 主进程日志中的 IPC 错误、窗口异常。
• 渲染进程控制台中的网络错误、SSE 解析错误。
• 离线地图路径是否有效、PMTiles 是否能按 Range 读取。
• 自动更新检查失败时的 provider URL 和版本差异。

章节来源

• ai-electron/electron/config/config.default.ts:1-50
• ai-electron/frontend/src/core/utils/http/axios/Axios.ts:1-200
• ai-electron/frontend/src/ai/api/sse.ts:1-200
• ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200

依赖关系分析

graph LR
    Env["deploy/env.sh"] --> AppYaml["ai-server application.yaml"]
    DevYaml["ai-server application-dev.yaml"] --> AppYaml
    ProdYaml["ai-gateway application-pro.yaml"] --> GWYaml["ai-gateway application.yaml"]
    AppYaml --> PG["PostgreSQL/pgvector"]
    AppYaml --> Redis["Redis"]
    AppYaml --> ES["Elasticsearch"]
    AppYaml --> Neo4j["Neo4j"]
    AppYaml --> DuckDB["DuckDB"]
    AppYaml --> Files["本地文件存储"]
    Client["Electron 客户端"] --> GWYaml
    GWYaml --> AppYaml

图表来源

• deploy/env.sh:1-172
• ai-server/src/main/resources/application.yaml:1-193
• ai-gateway/src/main/resources/application.yaml:1-81

章节来源

• deploy/env.sh:1-172
• ai-server/src/main/resources/application.yaml:1-193
• ai-gateway/src/main/resources/application.yaml:1-81

性能注意事项

• 不要在生产环境长期保留 ai-server 的 debug 日志，否则会显著增加 I/O 和磁盘占用。
• SSE 心跳依赖调度线程池，批量任务过长会导致心跳延迟，表现为前端连接被代理或浏览器断开。
• 向量模型首次加载可能较慢，且占用较大堆外内存；建议根据机器内存调整 batch size、intra-op threads 和优化级别。
• DuckDB 每个案件实例都会分配线程和内存预算，打开案件过多会导致资源叠加，应按 ZSJZ_DUCKDB_MAX_OPEN_CASES 限制并发。
• 大文件上传受 multipart 上限限制，过大文件或大量小文件堆积可能造成队列积压和 GC 压力。
• 网关连接后端超时较短，但 SSE 长连接不能设置全局响应超时，需要区分短请求与流式请求的超时策略。

[本节为通用性能指导，不直接分析具体代码行]

常见故障排查清单

登录后返回 503 或登录失败

• 现象：客户端登录后立即失败，或后续请求返回 401/503。
• 可能原因：
  • Redis 不可用，sa-token 无法读写登录态。
  • ai-gateway 与 ai-server 的 Sa-Token 配置不一致。
  • 数据库连接失败导致登录流程异常。
  • 网关健康检查失败，节点被标记不可用。
• 定位步骤：
  1. 检查 Redis 是否可连接，确认 SPRING_DATA_REDIS_HOST 与 SPRING_DATA_REDIS_PORT。
  2. 对比 ai-gateway 与 ai-server 的 Sa-Token 配置，尤其是 token-name、token-style、is-read-header。
  3. 查看 ai-server 控制台或日志是否有 Redis 连接异常。
  4. 检查网关健康检查是否频繁失败。
• 修复建议：
  • 修正 Redis 地址、端口、密码。
  • 使网关与后端 Sa-Token 配置完全一致。
  • 修复数据库连接或账号权限。
  • 调整 failure-threshold 或修复后端健康端点。
• 关联配置：
  • SPRING_DATA_REDIS_HOST、SPRING_DATA_REDIS_PORT。
  • Sa-Token 相关配置。
  • gateway.health-check.*。

章节来源

• deploy/env.sh:1-172
• ai-gateway/src/main/resources/application.yaml:1-81
• ai-server/src/main/resources/application-dev.yaml:1-87

跨域失败

• 现象：Electron 客户端从 file:// 加载前端时，请求后端被浏览器拒绝。
• 可能原因：
  • 后端 CORS 被关闭或 allowed-origin-patterns 不包含 file://。
  • 网关又加了一层 CORS，造成 Access-Control-Allow-Origin 重复。
• 定位步骤：
  1. 确认 APP_CORS_ENABLED 是否为 true。
  2. 确认 APP_CORS_ALLOWED_ORIGIN_PATTERNS 是否允许 file:// 或实际前端来源。
  3. 检查网关是否启用了 cors.enabled。
• 修复建议：
  • 保持后端 CORS 打开，并允许 file://。
  • 除非确实需要网关收口跨域，否则保持网关 cors.enabled=false。
  • 如开启网关 CORS，确保 default-filters 中的 DedupeResponseHeader 生效。
• 关联配置：
  • APP_CORS_ENABLED、APP_CORS_ALLOWED_ORIGIN_PATTERNS。
  • gateway.cors.enabled。

章节来源

• deploy/env.sh:1-172
• ai-server/src/main/resources/application.yaml:1-193
• ai-gateway/src/main/resources/application.yaml:1-81

Agent 对话无响应

• 现象：SSE 连接建立后长时间无 token、无 heartbeat、无 done。
• 可能原因：
  • 后端调度线程池被其他任务阻塞。
  • 向量模型加载缓慢或失败。
  • RAG 向量检索或 LLM 调用卡死。
  • 网关或代理断开了长连接。
• 定位步骤：
  1. 检查前端 SSE 是否收到 heartbeat。
  2. 查看 ai-server 调度线程池是否繁忙。
  3. 检查向量模型是否可用、模型路径是否正确。
  4. 检查 PostgreSQL/pgvector 向量表是否存在。
  5. 查看 Agent 相关日志是否有 LLM 或工具调用异常。
• 修复建议：
  • 合理配置 SPRING_TASK_SCHEDULING_POOL_SIZE。
  • 预热向量模型或降低首次加载影响。
  • 优化 RAG top-k、score-threshold。
  • 调整网关/代理的长连接超时。
• 关联配置：
  • SPRING_TASK_SCHEDULING_POOL_SIZE。
  • ZSJZ_EMBEDDING_ENABLED、ZSJZ_EMBEDDING_MODEL_PATH。
  • ETL_RAG_ENABLED、ETL_RAG_TOP_K、ETL_RAG_SCORE_THRESHOLD。

章节来源

• ai-server/src/main/resources/application.yaml:1-193
• ai-electron/frontend/src/ai/api/sse.ts:1-200
• deploy/env.sh:1-172

RAG 向量检索为空

• 现象：Agent 搜索表结构或 AI 模板匹配时召回为空。
• 可能原因：
  • 向量模型未启用或模型路径不存在。
  • pgvector 扩展未安装或向量表未重建。
  • score-threshold 过高。
  • 模板元数据未同步到向量索引。
• 定位步骤：
  1. 检查 ZSJZ_AI_CLEAN_VECTOR_ENABLED。
  2. 检查向量模型是否可用。
  3. 检查 PostgreSQL 是否安装 pgvector。
  4. 检查模板索引是否重建。
  5. 调低 score-threshold 验证是否召回更多候选。
• 修复建议：
  • 启用向量能力并修正模型路径。
  • 安装 pgvector 并重建索引。
  • 调整向量召回阈值。
• 关联配置：
  • ZSJZ_AI_CLEAN_VECTOR_ENABLED。
  • ZSJZ_AI_CLEAN_VECTOR_SCORE_THRESHOLD。
  • ZSJZ_AI_CLEAN_VECTOR_AUTO_REBUILD_ON_STARTUP。
  • ZSJZ_EMBEDDING_ENABLED、ZSJZ_EMBEDDING_MODEL_PATH。

章节来源

• ai-server/src/main/resources/application.yaml:1-193
• deploy/env.sh:1-172

清洗模板匹配失败

• 现象：AI 清洗无法匹配模板，或匹配结果不稳定。
• 可能原因：
  • 模板元数据缺失或字段标签不正确。
  • 向量召回 top-k 太小。
  • 相似度阈值过高。
  • 向量索引未重建。
• 定位步骤：
  1. 检查模板是否已入库。
  2. 检查向量索引是否自动重建。
  3. 调整 ZSJZ_AI_CLEAN_VECTOR_TOP_K。
  4. 调整 ZSJZ_AI_CLEAN_VECTOR_SCORE_THRESHOLD。
• 修复建议：
  • 补全模板元数据。
  • 重建向量索引。
  • 调高 top-k 或降低阈值。
• 关联配置：
  • ZSJZ_AI_CLEAN_VECTOR_TOP_K。
  • ZSJZ_AI_CLEAN_VECTOR_SCORE_THRESHOLD。
  • ZSJZ_AI_CLEAN_VECTOR_AUTO_INDEX_ON_TEMPLATE_CHANGE。

章节来源

• ai-server/src/main/resources/application.yaml:1-193
• deploy/env.sh:1-172

离线地图 PMTiles 加载失败

• 现象：行为时空图等离线地图无法加载，或只显示空白。
• 可能原因：
  • 本机离线地图目录未配置或路径无效。
  • china.pmtiles 文件不存在。
  • 主进程无法通过 IPC 读取二进制范围。
  • 回退到 HTTP Range 时服务器不支持 Range。
• 定位步骤：
  1. 检查前端是否设置了本机离线地图目录。
  2. 确认 china.pmtiles 存在且可读。
  3. 检查主进程日志中 IPC readBinaryFileRange 是否报错。
  4. 若使用内置静态资源，检查 HTTP Range 是否返回 206。
• 修复建议：
  • 重新选择有效的本机 PMTiles 目录。
  • 放入正确的 china.pmtiles 和样式文件。
  • 修复 Electron 主进程文件读取权限。
• 关联配置：
  • 前端离线地图目录保存在本地存储键 OFFLINE_MAP_DIR__。
  • 内置静态资源 china.pmtiles。

章节来源

• ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200

许可证校验失败

• 现象：服务端提示 license.xlts 不存在、激活超时或机器码不匹配。
• 可能原因：
  • 授权文件 license.xlts 未放置到运行目录下的 license 文件夹。
  • Linux 下 license 目录缺少执行权限。
  • 激活工具 regInfo/regInfo.exe 不可执行。
  • 机器码变更导致授权失效。
• 定位步骤：
  1. 检查 PathConst.LICENSE_PATH_FILE 对应路径是否存在。
  2. 查看 LicenseUtil 日志中的错误码。
  3. 在 Linux 上确认 license 目录可执行。
  4. 重新获取 machinecode 并更新授权。
• 修复建议：
  • 部署 license.xlts 到 RUN_QINGJIAN_PATH/license。
  • 赋予执行权限。
  • 重新激活或更换匹配的授权文件。
• 关联配置：
  • PathConst.LICENSE_PATH、LICENSE_PATH_FILE。
  • LicenseUtil 激活命令。

章节来源

• ai-server/src/main/resources/application.yaml:1-193

自动更新失败

• 现象：客户端启动后无法检查更新，或下载失败。
• 可能原因：
  • builder.json 中 publish.url 为空。
  • generic provider 的 latest.yml 不可达。
  • 客户端版本与服务端发布版本不一致。
  • 网络或签名问题。
• 定位步骤：
  1. 检查 builder.json 的 publish.provider 和 url。
  2. 确认 latest.yml 可从客户端访问。
  3. 查看主进程日志中 electron-updater 的输出。
  4. 检查客户端版本号是否与预期一致。
• 修复建议：
  • 配置有效的 generic 更新服务器地址。
  • 发布正确的 latest.yml 和安装包。
  • 确保证书和签名正确。
• 关联配置：
  • builder.json publish.provider、publish.url。
  • package.json electron-updater 依赖。

章节来源

• ai-electron/cmd/builder.json:1-57
• ai-electron/package.json:1-42

进程卡死

• 现象：应用启动缓慢、SSE 心跳停止、后台任务不再推进。
• 可能原因：
  • 调度线程池被长时间任务占满。
  • 向量模型加载阻塞。
  • 数据库连接耗尽。
  • DuckDB 打开案件过多。
  • 文件 AI 识别队列积压。
• 定位步骤：
  1. 检查 JVM 线程 dump，确认哪些线程卡住。
  2. 查看调度线程池是否饱和。
  3. 检查 PostgreSQL/Redis/Elasticsearch 连接状态。
  4. 检查 DuckDB 打开案件数。
  5. 查看文件 AI 识别队列 pending 数。
• 修复建议：
  • 增大或隔离调度线程池。
  • 预热向量模型。
  • 限制并发案件数。
  • 调整文件 AI 并发与队列上限。
• 关联配置：
  • SPRING_TASK_SCHEDULING_POOL_SIZE。
  • ZSJZ_DUCKDB_MAX_OPEN_CASES。
  • ZSJZ_FILE_AI_MAX_CONCURRENT、ZSJZ_FILE_AI_MAX_PENDING。

章节来源

• ai-server/src/main/resources/application.yaml:1-193
• deploy/env.sh:1-172

备份与恢复建议

PostgreSQL/pgvector 全量与增量备份

• 全量备份：使用 pg_dump 对 zsjz-ai 数据库进行逻辑备份，确保包含 pgvector 向量列。
• 增量备份：可使用 WAL 归档配合 pg_basebackup，或使用云厂商提供的连续备份能力。
• 恢复时先还原 schema，再导入数据；若使用 pgvector，需确保目标库也安装了相同版本的 pgvector。
• 建议定期验证备份可恢复，并记录 pg_dump 版本与数据库版本一致性。

Redis 持久化

• 启用 AOF 或 RDB 持久化，根据数据重要性选择每秒或每事务写入策略。
• 定期备份 appendonly.aof 或 rdb 文件。
• 注意 Redis 是 sa-token 登录态硬依赖，不可用时登录相关接口会全部异常。

本地文件存储归档

• 默认根目录为 ./data/files。
• 归档前应停止写入或切换到只读，避免文件不一致。
• 注意 STORAGE_LOCAL_BASE_URL 必须与 server.port 和 context-path 一致，否则前端拿到的文件 URL 不可访问。

客户端用户数据目录迁移

• Electron 主进程日志位于 logs 目录。
• 前端服务地址绑定保存在 localStorage 原始键 SERVER_BASE_URL__ 中。
• 离线地图目录保存在 OFFLINE_MAP_DIR__。
• 迁移时应连同 logs、用户数据目录、离线地图目录一起迁移，避免升级后丢失历史日志和本地配置。

章节来源

• deploy/env.sh:1-172
• ai-electron/electron/config/config.default.ts:1-50
• ai-electron/frontend/src/core/utils/map/offlineMap.ts:1-200

结论

• ai-server 是当前系统的核心，日志、监控、故障排查应首先围绕它展开。
• ai-gateway 主要承担路由、跨域去重和节点健康检查，应与 ai-server 的 Sa-Token、CORS、健康端点保持一致。
• Electron 客户端是问题复现的第一入口，主进程日志、渲染进程控制台、SSE 事件和离线地图路径是排障重点。
• 生产环境应完善日志落盘、指标采集、备份策略，并结合外部 APM 或数据库监控工具形成闭环。
• 常见故障大多与 Redis、PostgreSQL/pgvector、向量模型、CORS、SSE 心跳和自动更新配置有关，按本手册的定位步骤逐步缩小范围即可高效恢复。