# 环境准备与初始化 **本文引用的文件** - [deploy/env.sh](file://deploy/env.sh) - [ai-server/src/main/resources/application.yaml](file://ai-server/src/main/resources/application.yaml) - [ai-server/src/main/resources/application-dev.yaml](file://ai-server/src/main/resources/application-dev.yaml) - [ai-server/src/main/resources/application-pro.yaml](file://ai-server/src/main/resources/application-pro.yaml) - [ai-gateway/README.md](file://ai-gateway/README.md) - [sql/gateway.sql](file://sql/gateway.sql) - [sql/knowledge_base.sql](file://sql/knowledge_base.sql) - [ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java) - [ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java) ## 更新摘要 **已做变更** - 明确后端配置已从“静态 YAML 默认值”升级为 `${ENV_NAME:默认值}` 环境变量驱动,`deploy/env.sh` 是 Linux 部署唯一入口。 - 强化 Spring Profile 切换方式、dev/pro 差异以及环境变量覆盖优先级说明。 - 补充 systemd `EnvironmentFile`、`chmod 600`、端口和 context-path 不可参数化等生产注意事项。 - 在常见问题中新增“环境变量未生效 / 端口硬编码导致修改无效”的排查路径。 ## 目录 1. [引言](#引言) 2. [最小可用环境与外部依赖](#最小可用环境与外部依赖) 3. [环境变量与部署配置说明](#环境变量与部署配置说明) 4. [数据库初始化步骤](#数据库初始化步骤) 5. [Spring Profile 切换与 dev/pro 差异](#spring-profile-切换与-devpro-差异) 6. [可选依赖与降级行为](#可选依赖与降级行为) 7. [常见环境问题排查](#常见环境问题排查) 8. [部署检查清单](#部署检查清单) 9. [结论](#结论) ## 引言 本文面向部署前的环境准备,覆盖 PostgreSQL + pgvector、Redis、Elasticsearch、Neo4j、DuckDB 等外部依赖的安装要点、端口和版本注意事项,并给出最小可用环境的安装命令示例。重点解释 `deploy/env.sh` 中数据库、Redis、本地文件存储、Agent RAG、DuckDB 资源预算、向量模型路径、AI 清洗向量索引、聊天附件解析、登录安全窗口等关键变量;补充 gateway_service / gateway_node 表、业务主库表结构以及 pgvector 扩展启用步骤;说明 `SPRING_PROFILES_ACTIVE` 的 Spring Profile 切换方式与 dev/pro 配置差异;最后给出端口冲突、pgvector 未启用、Redis 不可用导致登录异常、ES/Neo4j 缺失时的降级行为排查建议。 **核心变化:** 当前后端所有可配置项均使用 Spring `${ENV_NAME:默认值}` 语法,不再依赖直接修改 YAML 中的业务默认值;Linux 部署应通过 `deploy/env.sh` 统一注入环境变量。 ## 最小可用环境与外部依赖 项目后端服务默认监听 `server.port=8980`,上下文路径为 `/js/a`。网关 `ai-gateway` 默认监听 `8080`,用于按用户粘性路由到多个 ai-server 节点。 | 组件 | 角色 | 默认端口或地址 | 最低要求与兼容性说明 | 最小可用命令示例 | |---|---|---:|---|---| | PostgreSQL | 平台主库:业务表、网关配置、pgvector 向量列 | `5432` | 需要支持 `pgvector` 扩展;当前代码使用 `org.postgresql.Driver` 和 JDBC URL `jdbc:postgresql://host:port/db`。 | `docker run --name zsjz-pg -e POSTGRES_DB=zsjz-ai -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres` | | Redis | Sa-Token 登录态、网关 token 路由缓存 | `6379` | 登录流程是硬依赖;Redis 不可用时 StpUtil 相关调用会抛异常,无降级实现。 | `docker run --name zsjz-redis -p 6379:6379 -d redis` | | Elasticsearch | 全文检索(替代原嵌入式 Lucene),索引名为 `zsjz_search` | `http://host:9200` | 可选依赖;索引创建失败时会在首次写入重试。 | `docker run --name zsjz-es -e discovery.type=single-node -e ES_JAVA_OPTS="-Xms512m -Xmx512m" -p 9200:9200 -d elasticsearch:8` | | Neo4j | 图谱能力 | `bolt://localhost:7687` | 可选依赖;仅图谱功能需要。 | `docker run --name zsjz-neo4j -e NEO4J_AUTH=neo4j/neo4j123 -p 7687:7687 -p 7474:7474 -d neo4j` | | DuckDB | 案件级分析库,每个案件一个实例 | 无固定端口 | 由 ai-server 进程内管理;通过 `ZSJZ_DUCKDB_MAX_OPEN_CASES` 控制同时打开数量。 | 无需单独安装,作为 Java 依赖加载。 | **注意:** - 若只使用基础查询、上传、登录、清洗,而不使用图谱可视化,可不部署 Neo4j。 - 若不需要全文搜索,可暂时不部署 Elasticsearch,但搜索类接口可能返回空结果或走降级逻辑。 - 如果前端通过 Electron 桌面客户端访问,必须允许跨域,因为前端以 `file://` 加载页面而后端独立部署。 - 本项目的 `server.port`、`server.servlet.context-path` 和应用名 `ai-server` 是硬编码在 `application.yaml` 中的,不能通过 `deploy/env.sh` 参数化;如需修改需同步前端 API 基础地址。 **Section sources** - [ai-server/src/main/resources/application.yaml:1-12](file://ai-server/src/main/resources/application.yaml#L1-L12) - [ai-gateway/README.md:1-30](file://ai-gateway/README.md#L1-L30) - [ai-server/src/main/resources/application-dev.yaml:5-34](file://ai-server/src/main/resources/application-dev.yaml#L5-L34) ## 环境变量与部署配置说明 ### 配置覆盖机制 `deploy/env.sh` 是 Linux 上统一下发和逐项修改后端的入口。ai-server 的 `application*.yaml` 中所有业务配置项都写成 `${ENV_NAME:默认值}`,因此设置操作系统环境变量即可覆盖 YAML 默认值;未设置时行为与 YAML 中的默认值一致。 环境变量生效顺序可以理解为: 1. Spring Boot 从操作系统环境变量读取值。 2. 将 `${ENV_NAME:默认值}` 中的占位符替换为实际环境变量。 3. 如果环境变量不存在,回退到冒号后的 YAML 默认值。 4. `SPRING_PROFILES_ACTIVE` 决定加载 `application-dev.yaml` 还是 `application-pro.yaml`,但这些 profile 文件中的值同样可以被环境变量覆盖。 **重要限制:** - `server.port`、`server.servlet.context-path`、`spring.application.name` 不参与参数化,是硬编码在 `application.yaml` 中的。 - sa-token、mybatis-plus 段按约定保持字面值,不在此文件范围。 - 文件内含数据库口令,部署时应执行 `chmod 600 deploy/env.sh`,并按实际环境修改地址与口令。 **Section sources** - [deploy/env.sh:1-36](file://deploy/env.sh#L1-L36) - [ai-server/src/main/resources/application.yaml:1-4](file://ai-server/src/main/resources/application.yaml#L1-L4) ### 启动方式 - 临时导入环境变量后启动 jar: ```bash set -a; source deploy/env.sh; set +a java -jar ai-server.jar ``` - systemd 部署: ```ini EnvironmentFile=/opt/zsjz-ai/deploy/env.sh ``` ### 关键变量分组与生产修改建议 #### 1. 跨域与 Spring 基础 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `APP_CORS_ENABLED` | 是否开启跨域 | 开发保持 `true`;生产应限制为前端域名白名单。 | | `APP_CORS_ALLOWED_ORIGIN_PATTERNS` | 允许的来源模式 | 生产从 `*` 收敛到具体域名。 | | `SPRING_TASK_SCHEDULING_POOL_SIZE` | 调度线程池大小 | 默认 `4`,避免 SSE 心跳、数据源回收、AI 清洗看门狗互相阻塞。 | | `SPRING_HTTP_CODECS_MAX_IN_MEMORY_SIZE` | HTTP 编解码内存上限 | 默认 `10MB`,按需调整。 | | `SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE` | 单文件上传上限 | 默认 `200MB`。 | | `SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE` | 总请求体上限 | 默认 `500MB`。 | #### 2. PostgreSQL 主库连接 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `SPRING_DATASOURCE_DYNAMIC_PRIMARY` | 动态数据源主库标识 | 保持 `master`。 | | `SPRING_DATASOURCE_DYNAMIC_STRICT` | 严格模式 | 保持 `true`,防止写错数据源 key 静默回退主库。 | | `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_URL` | PostgreSQL JDBC URL | 指向真实 PG 地址,例如 `jdbc:postgresql://host:5432/zsjz-ai`。 | | `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_USERNAME` | 数据库用户名 | 生产使用专用账号,不要保留 `postgres`。 | | `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_PASSWORD` | 数据库密码 | 生产必须替换。 | | `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_DRIVER_CLASS_NAME` | PostgreSQL 驱动类 | 保持 `org.postgresql.Driver`。 | #### 3. Redis | 变量 | 含义 | 生产修改建议 | |---|---|---| | `SPRING_DATA_REDIS_HOST` | Redis 主机 | 生产改为实际 Redis 地址。 | | `SPRING_DATA_REDIS_PORT` | Redis 端口 | 默认 `6379`;有认证时还需配合 Redis 侧 ACL 或密码配置。 | Redis 是 Sa-Token 登录态的硬依赖;不可用时登录相关接口全部异常,没有降级实现。 #### 4. Elasticsearch | 变量 | 含义 | 生产修改建议 | |---|---|---| | `SPRING_ELASTICSEARCH_URIS` | ES 节点地址 | 生产指向集群地址,如 `http://es-host:9200`。 | | `SPRING_ELASTICSEARCH_CONNECTION_TIMEOUT` | 连接超时 | 默认 `5s`。 | | `SPRING_ELASTICSEARCH_SOCKET_TIMEOUT` | 套接字超时 | 默认 `60s`。 | | `SPRING_ELASTICSEARCH_USERNAME` | ES 用户名 | 开启鉴权时取消注释并填写。 | | `SPRING_ELASTICSEARCH_PASSWORD` | ES 密码 | 开启鉴权时取消注释并填写。 | ES 是全文检索依赖,不是登录必需依赖。 #### 5. 本地文件存储 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `STORAGE_LOCAL_ROOT_PATH` | 本地文件根目录 | 相对 JVM 工作目录;生产建议使用绝对路径,如 `/opt/zsjz-ai/data/files`。 | | `STORAGE_LOCAL_BASE_URL` | 文件对外访问基础地址 | 必须与 `SERVER_PORT=8980`、`SERVER_SERVLET_CONTEXT_PATH=/js/a` 一致;生产应改为公网可达地址。 | 注意:当前 `/files/**` 与 `/file-download/**` 两个对外端点尚未完全实现,该地址主要用于拼接返回给前端的 URL。 #### 6. Neo4j | 变量 | 含义 | 生产修改建议 | |---|---|---| | `NEO4J_URI` | Neo4j Bolt 地址 | 默认 `bolt://localhost:7687`;生产改为实际地址。 | | `NEO4J_USERNAME` | Neo4j 用户名 | 默认 `neo4j`。 | | `NEO4J_PASSWORD` | Neo4j 密码 | 默认 `neo4j123`;生产必须修改。 | Neo4j 是图谱可选依赖。 #### 7. Agent RAG | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ETL_RAG_ENABLED` | 是否注册 Agent 表结构语义检索工具 | 默认 `true`。 | | `ETL_RAG_TOP_K` | 检索返回条数 | 默认 `5`。 | | `ETL_RAG_SCORE_THRESHOLD` | 相似度阈值 | 默认 `0.3`。 | Agent RAG 基于模板元数据向量化,依赖向量模型可用和 pgvector。 #### 8. AI 研判会话 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_INSIGHT_MAX_SESSIONS_PER_CASE` | 单案最大会话数 | 默认 `500`。 | | `ZSJZ_INSIGHT_RETENTION_DAYS` | 会话留存天数 | `0` 表示不自动清理。 | | `ZSJZ_INSIGHT_MESSAGE_PAGE_SIZE` | 消息分页默认值 | 默认 `20`。 | | `ZSJZ_INSIGHT_MESSAGE_PAGE_SIZE_MAX` | 消息分页上限 | 默认 `100`。 | | `ZSJZ_INSIGHT_SESSION_LOCK_TIMEOUT_MS` | 会话锁等待超时毫秒 | 默认 `3000`。 | | `ZSJZ_INSIGHT_DEFAULT_TOP_N` | 图谱快照默认取前 N | 默认 `100`。 | | `ZSJZ_INSIGHT_MAX_TOP_N` | 图谱快照硬上限 | 默认 `200`。 | #### 9. DuckDB 资源预算 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_DUCKDB_MAX_OPEN_CASES` | 同时打开的案件库数量上限 | 按机器内存/CPU 调整;默认 `8`。 | | `ZSJZ_DUCKDB_MEMORY_RATIO` | 所有案件实例合计物理内存比例 | 默认 `0.6`,取值范围 `0~1`。 | | `ZSJZ_DUCKDB_THREADS_PER_INSTANCE` | 每个案件实例的 DuckDB 线程数 | 默认 `4`。 | | `ZSJZ_DUCKDB_REAPER_INITIAL_DELAY_MS` | 兜底回收器首次扫描延迟毫秒 | 默认 `60000`。 | | `ZSJZ_DUCKDB_REAPER_INTERVAL_MS` | 兜底回收器扫描间隔毫秒 | 默认 `300000`。 | DuckDB 每案件实例按 `SET GLOBAL` 下发配置,因此 `max-open-cases` 很关键,否则多人同时开案会叠加占用资源。 #### 10. 非表格文件 AI 识别 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_FILE_AI_MAX_CONCURRENT` | 并发调模型任务数上限 | 默认 `3`。 | | `ZSJZ_FILE_AI_MAX_PENDING` | 排队积压上限 | 默认 `200`,超过直接标记跳过。 | | `ZSJZ_FILE_AI_TIMEOUT_SECONDS` | 单个文件识别超时秒数 | 默认 `120`。 | #### 11. 向量模型路径 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_EMBEDDING_ENABLED` | 是否启用本地 ONNX 向量模型 | `true` 使用本地 bge-m3,`false` 回退系统“模型管理”中的在线 embedding 模型。 | | `ZSJZ_EMBEDDING_MODEL_PATH` | 模型目录路径 | 必须包含 `tokenizer.json` 与 `onnx/model.onnx`;Linux 生产常用 `/opt/zsjz-ai/bge-m3`。 | | `ZSJZ_EMBEDDING_DIMENSIONS` | 输出维度 | 默认 `1024`,对应 bge-m3。 | | `ZSJZ_EMBEDDING_MAX_SEQ_LEN` | 单文本最大 token 数 | 默认 `8192`。 | | `ZSJZ_EMBEDDING_BATCH_SIZE` | 批量推理批大小 | 默认 `8`。 | | `ZSJZ_EMBEDDING_INTRA_OP_THREADS` | ONNX intra-op 并行线程数 | 默认 `0`,交给运行时策略。 | | `ZSJZ_EMBEDDING_OPT_LEVEL` | ONNX 图优化级别 | 默认 `BASIC_OPT`。 | | `ZSJZ_EMBEDDING_EAGER_LOAD` | 启动时预热模型 | 默认 `false`,懒加载。 | 本地模型权重常驻堆外内存约 `2.5~3GB`,首次加载耗时 `20~60s`;开关打开但模型目录缺失时不会静默回退在线模型,而是按“向量能力不可用”降级。 #### 12. AI 清洗向量索引 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_AI_CLEAN_BATCH_TOKEN_BUDGET` | 单批次 AI 判定 token 预算 | `0` 表示不限。 | | `ZSJZ_AI_CLEAN_STALE_MINUTES` | 批次心跳超时分钟数 | 默认 `30`。 | | `ZSJZ_AI_CLEAN_VECTOR_ENABLED` | 模板向量索引总开关 | 默认 `true`。 | | `ZSJZ_AI_CLEAN_VECTOR_AUTO_INDEX_ON_TEMPLATE_CHANGE` | 模板变更自动增量索引 | 默认 `true`。 | | `ZSJZ_AI_CLEAN_VECTOR_AUTO_REBUILD_ON_STARTUP` | 启动时自动重建空索引 | 默认 `true`。 | | `ZSJZ_AI_CLEAN_VECTOR_TOP_K` | 召回条数上限 | 默认 `12`。 | | `ZSJZ_AI_CLEAN_VECTOR_SCORE_THRESHOLD` | 相似度阈值 | 默认 `0.30`。 | | `ZSJZ_AI_CLEAN_VECTOR_MAX_DOCUMENTS_PER_REBUILD` | 全量重建文档数上限 | 默认 `5000`。 | AI 清洗模板索引只读两套模板元数据,不扫描 DuckDB 案件库;未满足条件时全链路 fail-open,不影响模板识别主链路。 #### 13. 聊天附件解析 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_CHAT_ATTACHMENT_MAX_DOC_MB` | 文档大小上限 MB | 默认 `50`。 | | `ZSJZ_CHAT_ATTACHMENT_MAX_SHEET_MB` | 表格大小上限 MB | 默认 `200`。 | | `ZSJZ_CHAT_ATTACHMENT_INLINE_MAX_CHARS` | 文档内联/RAG 提取字符上限 | 默认 `30000`。 | | `ZSJZ_CHAT_ATTACHMENT_INLINE_MAX_ROWS` | 表格内联行数上限 | 默认 `200`。 | | `ZSJZ_CHAT_ATTACHMENT_CHUNK_SIZE` | RAG 分块大小 | 默认 `1000`。 | | `ZSJZ_CHAT_ATTACHMENT_CHUNK_OVERLAP` | 分块重叠字符数 | 默认 `100`。 | | `ZSJZ_CHAT_ATTACHMENT_MAX_CHUNKS` | 最大分块数 | 默认 `500`。 | | `ZSJZ_CHAT_ATTACHMENT_TOP_K` | RAG 召回条数 | 默认 `8`。 | #### 14. 登录安全窗口 | 变量 | 含义 | 生产修改建议 | |---|---|---| | `ZSJZ_AUTH_IN_USE_WINDOW_MINUTES` | “账号正在使用”判定窗口分钟数 | 默认 `30`;窗口内有活跃会话时再次登录需确认后顶号。 | Sa-Token 默认单端登录,后登录顶掉前登录;联调多端时可额外传 `-DSA_TOKEN_CONCURRENT=true`。 **Section sources** - [deploy/env.sh:38-172](file://deploy/env.sh#L38-L172) - [ai-server/src/main/resources/application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193) - [ai-server/src/main/resources/application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87) - [ai-server/src/main/resources/application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87) ## 数据库初始化步骤 PostgreSQL 是平台主库,网关和业务共享同一数据库,但网关表独立于业务表。 ### 1. 启用 pgvector 扩展 pgvector 用于向量存储,包括 Agent RAG、AI 清洗模板索引、知识库文档索引、聊天附件 RAG 等。在目标数据库执行: ```sql CREATE EXTENSION IF NOT EXISTS vector; ``` 如果后续出现 `vector(n)` 维度不一致错误,需要确认 `ZSJZ_EMBEDDING_DIMENSIONS` 与实际模型输出维度一致。 ### 2. 初始化网关表 网关表由 `sql/gateway.sql` 定义,幂等可重复执行: ```sql \c zsjz-ai \i sql/gateway.sql ``` 该脚本创建: - `gateway_service`:服务定义,包含对外路径前缀、登录路径、健康检查路径、默认兜底节点等。 - `gateway_node`:后端 ai-server 节点,包含 service_id、base_url、enabled、remark 等。 - `gateway_user_route`:用户粘性绑定,支持按 user_id 或 username 绑定到 node_id。 网关启动时会尝试自动执行 `sql/gateway.sql`;如果 `gateway_service` 为空,还会按 YAML 中的 `gateway.services` 播种,之后以数据库为准。 ### 3. 初始化业务主库表结构 业务主库表结构由仓库中的 SQL 脚本维护,常见包括: - 平台基础表、用户表、权限相关表。 - 案件、清洗、洞察、图谱、外部表等业务表。 - 知识库与向量表结构:`knowledge_base`、`knowledge_doc`、`knowledge_doc_download_log`,以及按知识库和嵌入模型动态生成的 pgvector 向量表。 推荐在生产首次初始化时按顺序执行 `sql/` 下脚本,至少包含: ```sql \c zsjz-ai -- 先启用扩展 CREATE EXTENSION IF NOT EXISTS vector; -- 再执行业务脚本 \i sql/plat.sql \i sql/user.sql \i sql/case_table.sql \i sql/ai_clean.sql \i sql/external_tables.sql \i sql/insight_agent_tables.sql \i sql/chat_attachment.sql \i sql/gateway.sql \i sql/knowledge_base.sql ``` 实际执行顺序应以项目发布包附带的初始化清单为准。 ### 4. 知识库与向量表 `sql/knowledge_base.sql` 创建知识库本体、文档元数据和下载日志,并在内置知识库插入固定记录。RAG 检索会按知识库 ID 和嵌入模型标签动态创建 pgvector 向量表,例如 `kb_vec_{kbId}{tag}_d{dims}`。 **Section sources** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/knowledge_base.sql:1-70](file://sql/knowledge_base.sql#L1-L70) - [ai-server/src/main/resources/application.yaml:120-193](file://ai-server/src/main/resources/application.yaml#L120-L193) ## Spring Profile 切换与 dev/pro 差异 ### 切换方式 Spring Profile 由 Spring 原生环境变量 `SPRING_PROFILES_ACTIVE` 控制: - 默认值:`dev`。 - 生产可通过环境变量设置为 `pro`: ```bash export SPRING_PROFILES_ACTIVE=pro java -jar ai-server.jar ``` - `deploy/env.sh` 中也预留了注释行 `SPRING_PROFILES_ACTIVE="pro"`,可直接取消注释启用。 Profile 决定加载 `application-dev.yaml` 还是 `application-pro.yaml`;这些配置文件中的值同样支持 `${ENV_NAME:默认值}` 被环境变量覆盖。 ### dev 与 pro 主要差异 | 配置项 | dev 默认值 | pro 默认值 | 说明 | |---|---|---|---| | `spring.datasource.dynamic.datasource.master.url` | `jdbc:postgresql://192.168.0.106:5432/zsjz-ai` | `jdbc:postgresql://localhost:5432/zsjz-ai` | 开发连局域网 PG,生产默认本机 PG。 | | `spring.data.redis.host` | `192.168.0.106` | `localhost` | 开发连局域网 Redis,生产默认本机 Redis。 | | `spring.elasticsearch.uris` | `http://192.168.0.106:9200` | `http://localhost:9200` | 开发连局域网 ES,生产默认本机 ES。 | | `storage.local.base-url` | `http://localhost:8980/js/a` | `http://10.66.66.66:8980/js/a` | 生产默认使用内部 IP 作为文件访问基础地址。 | | `zsjz.embedding.model-path` | Windows 绝对路径 | Windows 绝对路径 | 两者都保留开发机路径;Linux 生产必须通过 `ZSJZ_EMBEDDING_MODEL_PATH` 覆盖为实际路径。 | 其他字段如 Sa-Token、Neo4j 默认值在 dev/pro 中基本一致,区别主要在数据库、Redis、ES、本地文件 base-url 和向量模型路径。 **Section sources** - [ai-server/src/main/resources/application.yaml:13-24](file://ai-server/src/main/resources/application.yaml#L13-L24) - [ai-server/src/main/resources/application-dev.yaml:1-87](file://ai-server/src/main/resources/application-dev.yaml#L1-L87) - [ai-server/src/main/resources/application-pro.yaml:1-87](file://ai-server/src/main/resources/application-pro.yaml#L1-L87) - [deploy/env.sh:38-41](file://deploy/env.sh#L38-L41) ## 可选依赖与降级行为 ### PostgreSQL + pgvector - 平台主库是必须依赖。 - pgvector 是向量能力依赖;未启用时,模板索引、Agent RAG、知识库文档 RAG、聊天附件大文档 RAG 等无法写入向量列。 - AI 清洗模板索引采用 fail-open:模型未配置、PG 未装 pgvector、表探测失败等情况只记日志,不阻断模板识别主链路。 ### Redis - Sa-Token 登录态是硬依赖。 - Redis 不可用时,所有 StpUtil 相关操作抛异常,没有降级实现。 - 网关也使用 Redis 缓存 `gateway:token:{svc}:{token}` 和用户路由键。 ### Elasticsearch - 全文检索替代原嵌入式 Lucene,索引名为 `zsjz_search`。 - 启动时创建索引失败会记录错误,并在首次写入时重试。 - 健康检查服务会探测 ES 集群状态,green/yellow 视为可用,red 视为异常。 ### Neo4j - 仅图谱能力需要。 - 未部署时图谱相关功能不可用,但不影响登录、清洗、Agent 问答等核心流程。 ### DuckDB - 每个案件一个实例,受 `ZSJZ_DUCKDB_MAX_OPEN_CASES` 限制。 - 超出最大打开数时直接拒绝开案,而不是无限增长。 - 资源按 `memory-ratio` 和 `threads-per-instance` 分摊,避免多人同时开案造成资源叠加。 ```mermaid flowchart TD Start["应用启动"] --> CheckPg["检查 PostgreSQL"] CheckPg --> PgOk{"PostgreSQL 可用?"} PgOk -->|否| Stop["启动失败或数据库功能不可用"] PgOk -->|是| CheckRedis["检查 Redis"] CheckRedis --> RedisOk{"Redis 可用?"} RedisOk -->|否| LoginFail["登录相关接口异常,无降级"] RedisOk -->|是| CheckOptional["检查可选依赖"] CheckOptional --> CheckEs{"Elasticsearch 可用?"} CheckEs -->|否| SearchDegraded["全文搜索降级或首次写入重试"] CheckEs -->|是| SearchOk["全文检索正常"] CheckOptional --> CheckNeo{"Neo4j 可用?"} CheckNeo -->|否| GraphDegraded["图谱功能不可用"] CheckNeo -->|是| GraphOk["图谱功能正常"] SearchDegraded --> Ready["应用可用"] GraphDegraded --> Ready SearchOk --> Ready GraphOk --> Ready ``` **Diagram sources** - [ai-server/src/main/resources/application.yaml:1-193](file://ai-server/src/main/resources/application.yaml#L1-L193) - [ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java:216-292](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java#L216-L292) - [ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java:27-43](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java#L27-L43) **Section sources** - [ai-server/src/main/resources/application-dev.yaml:5-34](file://ai-server/src/main/resources/application-dev.yaml#L5-L34) - [ai-server/src/main/resources/application-pro.yaml:5-34](file://ai-server/src/main/resources/application-pro.yaml#L5-L34) - [ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java:55-78](file://ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java#L55-L78) - [ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java:27-43](file://ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java#L27-L43) ## 常见环境问题排查 ### 1. 端口冲突 **现象:** - 后端启动失败,提示 `8980` 端口已被占用。 - 网关启动失败,提示 `8080` 端口已被占用。 - 前端访问后端报连接拒绝。 **排查:** - 检查本机是否已有 Java 进程监听 `8980`: ```bash lsof -i :8980 netstat -tlnp | grep 8980 ``` - 检查网关是否已运行: ```bash lsof -i :8080 ``` - 检查 Docker 容器是否占用了 `5432`、`6379`、`9200`、`7687`。 **处理:** - 停止冲突进程,或修改应用端口。 - 注意:本项目的 `server.port` 和 `context-path` 是硬编码在 `application.yaml` 中的,不能通过 `deploy/env.sh` 参数化;如需修改需同步前端 API 基础地址。 ### 2. pgvector 未启用 **现象:** - 启动或建向量表时报缺少 `vector` 类型。 - 向量索引重建失败。 - Agent 选表工具返回向量能力不可用。 **排查:** ```sql SELECT * FROM pg_extension WHERE extname = 'vector'; ``` 如果结果为空,说明未启用。 **处理:** ```sql CREATE EXTENSION IF NOT EXISTS vector; ``` 随后重新执行业务初始化脚本,确保向量表正确创建。 ### 3. Redis 不可用导致登录异常 **现象:** - 登录后立即失效。 - 前端获取不到 `x-token`。 - 服务端抛出 Redis 连接异常。 - 网关登录后仍不粘或 token 全部解析失败。 **排查:** - 检查 Redis 是否运行: ```bash redis-cli ping ``` - 检查 `SPRING_DATA_REDIS_HOST`、`SPRING_DATA_REDIS_PORT` 是否与部署一致。 - 如果是多网关+多后端,检查网关与后端是否共享同一个 Redis 和相同 Sa-Token 配置。 **处理:** - 启动 Redis 或修正 host/port。 - 确保网关与后端 Sa-Token 配置一致,尤其是 `token-name`、database、`is-concurrent`。 ### 4. Elasticsearch 不可用 **现象:** - 全文搜索无结果。 - 启动日志中出现索引创建失败。 - 健康检查显示 Elasticsearch 不可用。 **排查:** ```bash curl http://localhost:9200 ``` 检查返回状态是否为 green/yellow。 **处理:** - 启动 ES 并修正 `SPRING_ELASTICSEARCH_URIS`。 - 如果开启鉴权,填写 `SPRING_ELASTICSEARCH_USERNAME` 和 `SPRING_ELASTICSEARCH_PASSWORD`。 - 首次写入失败会重试,但若集群一直 red,需修复 ES 集群状态。 ### 5. Neo4j 缺失 **现象:** - 图谱页面空白或报错。 - 图谱分析工具不可用。 **排查:** ```bash curl http://localhost:7474 ``` 或检查 Bolt 端口: ```bash nc -zv localhost 7687 ``` **处理:** - 部署 Neo4j,或使用 Docker 镜像。 - 修正 `NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`。 - 如果不使用图谱功能,可不部署 Neo4j,但需接受图谱相关能力不可用。 ### 6. 本地文件存储路径问题 **现象:** - 上传成功但前端无法预览。 - 返回的文件 URL 指向错误主机或端口。 - 部署后静态资源访问 404。 **排查:** - 检查 `STORAGE_LOCAL_ROOT_PATH` 是否指向真实目录。 - 检查 `STORAGE_LOCAL_BASE_URL` 是否与 `server.port`、`context-path` 一致。 - 确认当前进程对目录有读写权限。 **处理:** - 将 `STORAGE_LOCAL_ROOT_PATH` 设置为部署根目录下的绝对路径。 - 将 `STORAGE_LOCAL_BASE_URL` 设置为前端可访问的公网或内网地址。 ### 7. 向量模型路径不正确 **现象:** - 向量能力不可用。 - 首次推理时报模型文件缺失。 - 维度不一致导致向量表写入失败。 **排查:** - 检查模型目录是否存在 `tokenizer.json` 和 `onnx/model.onnx`。 - 检查 `ZSJZ_EMBEDDING_MODEL_PATH` 是否指向正确路径。 - 检查 `ZSJZ_EMBEDDING_DIMENSIONS` 是否与模型输出维度一致。 **处理:** - Linux 生产常用 `/opt/zsjz-ai/bge-m3`。 - 如果使用在线 embedding 模型,将 `ZSJZ_EMBEDDING_ENABLED=false`。 ### 8. 登录安全窗口导致频繁顶号 **现象:** - 同一账号在不同设备登录时被顶。 - 旧设备刷新页面报未登录。 **排查:** - 检查 `ZSJZ_AUTH_IN_USE_WINDOW_MINUTES`。 - 检查 Sa-Token 是否开启单端登录。 **处理:** - 联调多端时可传入 `-DSA_TOKEN_CONCURRENT=true`。 - 生产保持单端登录,但合理设置“正在使用”窗口时间。 ### 9. 环境变量未生效或端口无法通过 env.sh 修改 **现象:** - 修改了 `deploy/env.sh` 中某项配置,重启后仍使用旧值。 - 尝试把 `server.port` 放入 `env.sh`,发现不生效。 - systemd 环境下环境变量看起来已注入,但应用仍连开发环境数据库。 **排查:** - 确认是通过 `set -a; source deploy/env.sh; set +a` 导入,或通过 systemd `EnvironmentFile` 加载。 - 确认环境变量名与 `application*.yaml` 中 `${ENV_NAME:默认值}` 完全一致。 - 确认 `SPRING_PROFILES_ACTIVE` 确实是 `dev` 还是 `pro`,不同 profile 默认值不同。 - 检查是否有更高层的系统环境变量覆盖了 `env.sh` 中的值。 - 确认 `server.port`、`server.servlet.context-path`、`spring.application.name` 不在 `env.sh` 中——它们不支持参数化。 **处理:** - 修改 `deploy/env.sh` 后重新加载 shell 或重启 systemd 单元。 - 如需改端口或 context-path,直接修改 `application.yaml` 并同步前端 API 基础地址。 - 使用 `env | grep ZSJZ_`、`env | grep SPRING_` 验证进程实际携带的环境变量。 **Section sources** - [ai-server/src/main/resources/application.yaml:1-12](file://ai-server/src/main/resources/application.yaml#L1-L12) - [ai-server/src/main/resources/application-dev.yaml:36-87](file://ai-server/src/main/resources/application-dev.yaml#L36-L87) - [ai-server/src/main/resources/application-pro.yaml:36-87](file://ai-server/src/main/resources/application-pro.yaml#L36-L87) - [ai-gateway/README.md:31-157](file://ai-gateway/README.md#L31-L157) - [deploy/env.sh:43-172](file://deploy/env.sh#L43-L172) ## 部署检查清单 - [ ] 已安装 PostgreSQL 并启用 `pgvector` 扩展。 - [ ] 已创建数据库 `zsjz-ai` 并配置用户。 - [ ] 已执行 `sql/gateway.sql` 初始化网关表。 - [ ] 已执行业务主库表结构初始化脚本。 - [ ] 已启动 Redis 并验证连通。 - [ ] 已部署 Elasticsearch 并可访问 `http://host:9200`。 - [ ] 如使用图谱功能,已部署 Neo4j 并验证 Bolt 端口。 - [ ] 已在 `deploy/env.sh` 中修正数据库连接、Redis、ES、Neo4j 地址与凭证。 - [ ] 已将 `deploy/env.sh` 权限设为 `600`。 - [ ] 已设置 `STORAGE_LOCAL_ROOT_PATH` 和 `STORAGE_LOCAL_BASE_URL`。 - [ ] 已放置本地向量模型目录,并设置 `ZSJZ_EMBEDDING_MODEL_PATH`。 - [ ] 已根据环境选择 `SPRING_PROFILES_ACTIVE=dev` 或 `pro`。 - [ ] 已确认 `8980`、`8080`、`5432`、`6379`、`9200`、`7687` 无端口冲突。 - [ ] 已测试登录、开案、附件上传、全文搜索、图谱查询等核心流程。 ## 结论 部署前应优先保证 PostgreSQL + pgvector 与 Redis 可用,这是平台主库和登录态的基础;Elasticsearch 和 Neo4j 属于增强能力,缺失时系统会降级或局部不可用。生产部署的核心是把 `deploy/env.sh` 中的数据库、Redis、ES、Neo4j、本地文件路径、向量模型路径和安全窗口替换为真实值,并通过 `SPRING_PROFILES_ACTIVE` 切换到 `pro` profile。由于 `server.port`、`server.servlet.context-path` 和应用名是硬编码配置,不能通过环境变量覆盖,修改这些值时需要同步前端 API 基础地址。最终建议先启动单一 ai-server 节点完成冒烟测试,再引入网关和多节点部署。