环境准备与初始化

本文引用的文件

deploy/env.sh
ai-server/src/main/resources/application.yaml
ai-server/src/main/resources/application-dev.yaml
ai-server/src/main/resources/application-pro.yaml
ai-gateway/README.md
sql/gateway.sql
sql/knowledge_base.sql
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

更新摘要

已做变更

明确后端配置已从“静态 YAML 默认值”升级为 ${ENV_NAME:默认值} 环境变量驱动，deploy/env.sh 是 Linux 部署唯一入口。
强化 Spring Profile 切换方式、dev/pro 差异以及环境变量覆盖优先级说明。
补充 systemd EnvironmentFile、chmod 600、端口和 context-path 不可参数化等生产注意事项。
在常见问题中新增“环境变量未生效 / 端口硬编码导致修改无效”的排查路径。

引言

本文面向部署前的环境准备，覆盖 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
ai-gateway/README.md:1-30
ai-server/src/main/resources/application-dev.yaml:5-34

环境变量与部署配置说明

配置覆盖机制

deploy/env.sh 是 Linux 上统一下发和逐项修改后端的入口。ai-server 的 application*.yaml 中所有业务配置项都写成 ${ENV_NAME:默认值}，因此设置操作系统环境变量即可覆盖 YAML 默认值；未设置时行为与 YAML 中的默认值一致。

环境变量生效顺序可以理解为：

Spring Boot 从操作系统环境变量读取值。
将 ${ENV_NAME:默认值} 中的占位符替换为实际环境变量。
如果环境变量不存在，回退到冒号后的 YAML 默认值。
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
ai-server/src/main/resources/application.yaml:1-4

启动方式

临时导入环境变量后启动 jar：

set -a; source deploy/env.sh; set +a
java -jar ai-server.jar

systemd 部署：

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
ai-server/src/main/resources/application.yaml:1-193
ai-server/src/main/resources/application-dev.yaml:1-87
ai-server/src/main/resources/application-pro.yaml:1-87

数据库初始化步骤

PostgreSQL 是平台主库，网关和业务共享同一数据库，但网关表独立于业务表。

1. 启用 pgvector 扩展

pgvector 用于向量存储，包括 Agent RAG、AI 清洗模板索引、知识库文档索引、聊天附件 RAG 等。在目标数据库执行：

CREATE EXTENSION IF NOT EXISTS vector;

如果后续出现 vector(n) 维度不一致错误，需要确认 ZSJZ_EMBEDDING_DIMENSIONS 与实际模型输出维度一致。

2. 初始化网关表

网关表由 sql/gateway.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/ 下脚本，至少包含：

\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
sql/knowledge_base.sql:1-70
ai-server/src/main/resources/application.yaml:120-193

Spring Profile 切换与 dev/pro 差异

切换方式

Spring Profile 由 Spring 原生环境变量 SPRING_PROFILES_ACTIVE 控制：

默认值：dev。

生产可通过环境变量设置为 pro：

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
ai-server/src/main/resources/application-dev.yaml:1-87
ai-server/src/main/resources/application-pro.yaml:1-87
deploy/env.sh:38-41

可选依赖与降级行为

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 分摊，避免多人同时开案造成资源叠加。

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
ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java:216-292
ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java:27-43

Section sources

ai-server/src/main/resources/application-dev.yaml:5-34
ai-server/src/main/resources/application-pro.yaml:5-34
ai-server/src/main/java/com/zsjz/ai/module/aiclean/index/AiCleanTemplateVectorIndex.java:55-78
ai-server/src/main/java/com/zsjz/ai/module/search/service/SearchDocIndexService.java:27-43

常见环境问题排查

1. 端口冲突

现象：

后端启动失败，提示 8980 端口已被占用。
网关启动失败，提示 8080 端口已被占用。
前端访问后端报连接拒绝。

排查：

检查本机是否已有 Java 进程监听 8980：
```
lsof -i :8980
netstat -tlnp | grep 8980
```
检查网关是否已运行：
```
lsof -i :8080
```
检查 Docker 容器是否占用了 5432、6379、9200、7687。

处理：

停止冲突进程，或修改应用端口。
注意：本项目的 server.port 和 context-path 是硬编码在 application.yaml 中的，不能通过 deploy/env.sh 参数化；如需修改需同步前端 API 基础地址。

2. pgvector 未启用

现象：

启动或建向量表时报缺少 vector 类型。
向量索引重建失败。
Agent 选表工具返回向量能力不可用。

排查：

SELECT * FROM pg_extension WHERE extname = 'vector';

如果结果为空，说明未启用。

处理：

CREATE EXTENSION IF NOT EXISTS vector;

随后重新执行业务初始化脚本，确保向量表正确创建。

3. Redis 不可用导致登录异常

现象：

登录后立即失效。
前端获取不到 x-token。
服务端抛出 Redis 连接异常。
网关登录后仍不粘或 token 全部解析失败。

排查：

检查 Redis 是否运行：
```
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 不可用。

排查：

curl http://localhost:9200

检查返回状态是否为 green/yellow。

处理：

启动 ES 并修正 SPRING_ELASTICSEARCH_URIS。
如果开启鉴权，填写 SPRING_ELASTICSEARCH_USERNAME 和 SPRING_ELASTICSEARCH_PASSWORD。
首次写入失败会重试，但若集群一直 red，需修复 ES 集群状态。

5. Neo4j 缺失

现象：

图谱页面空白或报错。
图谱分析工具不可用。

排查：

curl http://localhost:7474

或检查 Bolt 端口：

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
ai-server/src/main/resources/application-dev.yaml:36-87
ai-server/src/main/resources/application-pro.yaml:36-87
ai-gateway/README.md:31-157
deploy/env.sh:43-172

部署检查清单

已安装 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 节点完成冒烟测试，再引入网关和多节点部署。

环境准备与初始化.md 31 KB Historia Czysty

环境准备与初始化

更新摘要

目录

引言

最小可用环境与外部依赖

环境变量与部署配置说明

配置覆盖机制

启动方式

关键变量分组与生产修改建议

1. 跨域与 Spring 基础

2. PostgreSQL 主库连接

3. Redis

4. Elasticsearch

5. 本地文件存储

6. Neo4j

7. Agent RAG

8. AI 研判会话

9. DuckDB 资源预算

10. 非表格文件 AI 识别

11. 向量模型路径

12. AI 清洗向量索引

13. 聊天附件解析

14. 登录安全窗口

数据库初始化步骤

1. 启用 pgvector 扩展

2. 初始化网关表

3. 初始化业务主库表结构

4. 知识库与向量表

Spring Profile 切换与 dev/pro 差异

切换方式

dev 与 pro 主要差异

可选依赖与降级行为

PostgreSQL + pgvector

Redis

Elasticsearch

Neo4j

DuckDB

常见环境问题排查

1. 端口冲突

2. pgvector 未启用

3. Redis 不可用导致登录异常

4. Elasticsearch 不可用

5. Neo4j 缺失

6. 本地文件存储路径问题

7. 向量模型路径不正确

8. 登录安全窗口导致频繁顶号

9. 环境变量未生效或端口无法通过 env.sh 修改

部署检查清单

结论

环境准备与初始化.md 31 KB

Historia Czysty