故障排除

本文档按类别整理了 Snail AI 使用过程中常见的问题及其解决方案。遇到问题时，请先根据错误类型在对应分类中查找解决方法。

安装与依赖

Java 版本不兼容

现象： 启动时报错 UnsupportedClassVersionError 或 class file has wrong version

原因： Snail AI 要求 Java 17+，当前环境使用了低版本 JDK。

解决：

bash

# 检查 Java 版本
java -version

# 如果低于 17，请安装 JDK 17+
# Ubuntu/Debian
apt install openjdk-17-jdk

# CentOS/RHEL
yum install java-17-openjdk-devel

# macOS
brew install openjdk@17

确认 JAVA_HOME 指向正确版本：

bash

export JAVA_HOME=/path/to/jdk-17
export PATH=$JAVA_HOME/bin:$PATH

Maven 依赖下载失败

现象： mvn spring-boot:run 时报 Could not resolve dependencies 或下载超时。

解决：

检查网络连接，确认能访问 Maven Central
配置国内镜像源（推荐阿里云）：

xml

<!-- ~/.m2/settings.xml -->
<mirrors>
  <mirror>
    <id>aliyun</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/central</url>
  </mirror>
</mirrors>

清除本地缓存重新下载：

bash

mvn dependency:purge-local-repository
mvn clean install -U

前端依赖安装失败

现象： pnpm install 报错或长时间卡住。

解决：

bash

# 检查 Node.js 版本（要求 20+）
node -v

# 检查 pnpm 版本（要求 10+）
pnpm -v

# 清除缓存重试
pnpm store prune
rm -rf node_modules
pnpm install

# 如果网络问题，设置淘宝镜像
pnpm config set registry https://registry.npmmirror.com
pnpm install

达梦 JDBC 驱动找不到

现象： 启动时报 ClassNotFoundException: dm.jdbc.driver.DmDriver

解决： 达梦 JDBC 驱动不在 Maven Central，需手动安装到本地仓库：

bash

mvn install:install-file \
  -DgroupId=com.dameng \
  -DartifactId=DmJdbcDriver \
  -Dversion=8.1.2 \
  -Dpackaging=jar \
  -Dfile=/path/to/DmJdbcDriver.jar

数据库问题

数据库连接失败

现象： 启动时报 Communications link failure 或 Connection refused

排查步骤：

确认数据库服务已启动：

bash

# MySQL
systemctl status mysql
# 或
mysqladmin ping -h localhost -u root -p

# PostgreSQL
systemctl status postgresql
pg_isready

# Docker 环境
docker compose ps

确认连接参数正确：

bash

# 测试数据库连接
mysql -h localhost -P 3306 -u root -p snail_ai
# 或
psql -h localhost -p 5432 -U postgres -d snail_ai

检查防火墙和网络：

bash

# 测试端口连通性
telnet localhost 3306
# 或
nc -zv localhost 3306

检查 application.yml 配置： 确认 url、username、password、driver-class-name 均正确。

数据库初始化脚本执行失败

现象： 导入 SQL 时报语法错误或字段冲突。

解决：

确认使用了正确数据库类型的初始化脚本（docs/sql/ 目录下有各数据库类型对应的脚本）
确认数据库字符集为 utf8mb4（MySQL）或 UTF8（PostgreSQL）
如果是重复导入，先删除数据库再重新创建：

sql

-- MySQL
DROP DATABASE IF EXISTS snail_ai;
CREATE DATABASE snail_ai DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

-- PostgreSQL
DROP DATABASE IF EXISTS snail_ai;
CREATE DATABASE snail_ai WITH ENCODING 'UTF8';

数据库迁移失败

现象： 升级后启动报 Migration checksum mismatch 或 Schema 版本冲突。

解决：

确认迁移脚本未被手动修改
如果使用了 Flyway 自动迁移，检查 flyway_schema_history 表
必要时手动修复：

sql

-- 查看迁移历史
SELECT * FROM flyway_schema_history ORDER BY installed_rank DESC;

-- 删除失败的迁移记录（慎用）
DELETE FROM flyway_schema_history WHERE success = false;

重新启动服务

向量存储问题

PgVector 扩展安装失败

现象： 执行 CREATE EXTENSION vector 报 could not open extension control file

解决：

bash

# Ubuntu/Debian -- 安装 PgVector 扩展
apt install postgresql-16-pgvector

# CentOS/RHEL
yum install pgvector_16

# Docker -- 使用内置 pgvector 的镜像
# 使用 pgvector/pgvector:pg16 镜像，扩展已预装

# 安装后在目标数据库中启用
psql -U postgres -d snail_ai_vector -c "CREATE EXTENSION IF NOT EXISTS vector;"

PgVector 向量维度不匹配

现象： 插入向量时报 expected X dimensions, not Y

原因： 向量表的维度与使用的 Embedding 模型输出维度不一致。

解决：

确认所用 Embedding 模型的输出维度
修改配置中的 dimensions 参数使其匹配
如果已有数据，需要重建向量表或重新嵌入文档

常见 Embedding 模型维度：

模型	维度
text-embedding-3-small	1536
text-embedding-3-large	3072
bge-m3	1024
bge-large-zh	1024

Milvus 连接失败

现象： 报 MilvusClientException 或 connect to Milvus failed

排查步骤：

确认 Milvus 服务及其依赖（etcd、MinIO）均已启动：

bash

docker compose ps
# 确认 milvus、etcd、minio 三个容器均为 running 状态

测试 Milvus 端口连通性：

bash

nc -zv localhost 19530

检查 Milvus 日志：

bash

docker compose logs milvus

确认 application.yml 中的 host 和 port 配置正确。

Elasticsearch 集群状态异常

现象： ES 集群状态为 red 或 yellow，向量检索超时。

排查步骤：

bash

# 检查集群健康状态
curl -X GET "localhost:9200/_cluster/health?pretty"

# 查看未分配的分片
curl -X GET "localhost:9200/_cat/shards?v&h=index,shard,prirep,state,unassigned.reason"

# 检查磁盘空间（ES 在磁盘超过 85% 时会停止分配分片）
curl -X GET "localhost:9200/_cat/allocation?v"

常见原因与解决：

磁盘空间不足：清理日志或扩容磁盘
节点数不足：副本分片需要至少 2 个节点，开发环境可设置 number_of_replicas: 0
内存不足：增大 ES 堆内存（建议为物理内存的 50%，不超过 32 GB）

Agent Client 问题

gRPC 连接失败

现象： Client 启动后无法连接 Server，报 UNAVAILABLE: io exception 或 Connection refused

排查步骤：

确认 Server 已启动并监听 gRPC 端口：

bash

# 查看 Server 日志中是否有 gRPC 端口监听信息
# 应看到类似：gRPC Server started, listening on port 18888

确认网络连通性：

bash

# 从 Client 机器测试连接 Server 的 gRPC 端口
telnet server-host 18888
# 或
nc -zv server-host 18888

检查防火墙规则：

bash

# 确保 Server 的 18888 端口已开放
# CentOS/RHEL
firewall-cmd --list-ports
firewall-cmd --add-port=18888/tcp --permanent
firewall-cmd --reload

# Ubuntu
ufw allow 18888/tcp

检查 Client 配置： 确认 snail-ai.server.host 和 snail-ai.server.port 正确。

心跳超时

现象： 管理后台显示客户端节点状态为"离线"，日志中出现 heartbeat timeout。

原因： Client 与 Server 之间的网络不稳定，或心跳间隔配置不合理。

解决：

yaml

# Client 端 application.yml
snail-ai:
  client:
    heartbeat-interval: 30s      # 适当增大心跳间隔
    reconnect-interval: 5s       # 断线重连间隔
    max-reconnect-attempts: -1   # 无限重试

同时检查网络质量：

bash

# 测试 Client 到 Server 的网络延迟
ping server-host

注册失败

现象： Client 启动后未在管理后台的应用节点列表中出现。

排查步骤：

检查 app-id 和 token 是否与管理后台创建的应用一致
确认 Server 的 gRPC 端口可访问
查看 Client 启动日志中是否有注册相关的错误信息
确认应用状态为"启用"（非禁用状态）

模型调用问题

API Key 无效

现象： 调用大模型时报 401 Unauthorized 或 Invalid API Key

排查步骤：

在管理后台「模型管理」中检查 API Key 是否正确配置
确认 API Key 未过期或被撤销
如果使用代理地址，确认代理 URL 格式正确
检查加密配置（SNAIL_AI_CRYPTO_KEY）是否与存储 Key 时的配置一致

WARNING

如果更换了加密密钥，之前存储的 API Key 将无法解密。需要重新在管理后台录入 API Key。

模型调用超时

现象： 对话时长时间无响应，最终报超时错误。

解决：

增大请求超时时间：

yaml

snail-ai:
  model:
    request-timeout: 300s          # 增大到 5 分钟

检查网络出站连接（Server 或 Client 需能访问模型 API 地址）：

bash

# 测试 OpenAI API 连通性
curl -v https://api.openai.com/v1/models -H "Authorization: Bearer $API_KEY"

如果使用代理，确认代理配置正确：

bash

export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

速率限制 (Rate Limiting)

现象： 频繁对话后报 429 Too Many Requests 或 Rate limit exceeded

解决：

降低并发对话数量
在模型提供商控制台查看并提升速率限制
配置多个 API Key 轮换使用
使用本地部署的模型（如 Ollama）作为备用，避免外部 API 限制

RAG 知识库问题

文档解析失败

现象： 上传文档后状态停留在"解析中"或显示"解析失败"。

排查步骤：

检查文件格式： 确认上传的文件格式在支持列表中（PDF、Word、Excel、PPT、Markdown、TXT、HTML、CSV 等）
检查文件大小： 确认未超过上传限制（默认 100 MB）
检查文件编码： 文本文件建议使用 UTF-8 编码
查看后端日志： 搜索 DocumentParser 或 RAG 相关的错误日志

bash

# Docker 环境
docker compose logs snail-ai-server | grep -i "parse\|document\|rag"

# systemd 环境
journalctl -u snail-ai-server | grep -i "parse\|document\|rag"

常见原因：

PDF 包含扫描图片（非文字内容），需要 OCR 支持
Word 文档加密或损坏
Excel 文件包含复杂公式或嵌入对象

向量嵌入失败

现象： 文档分片成功但向量化失败，报 Embedding 相关错误。

排查步骤：

确认已配置 EMBEDDING 类型的模型并且 API Key 有效
确认 Embedding 模型可正常调用
检查向量数据库连接是否正常
查看文本分片内容是否存在异常字符

检索结果不准确

现象： RAG 检索返回的内容与问题不相关。

优化建议：

调整分片策略： 尝试不同的分片策略（递归字符、语义分片等），调整分片大小和重叠长度
优化 Embedding 模型： 使用更高质量的 Embedding 模型（如 text-embedding-3-large）
启用混合检索： 同时使用向量检索和 BM25 关键词检索，通过 RRF 融合提升召回率
启用重排序： 配置 Reranker 模型对检索结果进行精排
优化分片数量： 增大 Top-K 值（检索返回的分片数量）

性能问题

对话响应缓慢

排查步骤：

检查模型调用耗时： 在可观测性面板的瀑布图中查看 LLM 调用阶段耗时
检查 RAG 检索耗时： 如果 RAG 阶段耗时过长，考虑优化向量索引或减少检索范围
检查网络延迟： 外部模型 API 的网络延迟是否过高
检查 Server 负载： CPU 和内存使用率是否过高

内存溢出 (OOM)

现象： 服务崩溃，日志中出现 OutOfMemoryError

解决：

增大堆内存：

bash

JAVA_OPTS="-Xms2g -Xmx4g"

分析 Heap Dump：

bash

# 开启 OOM 时自动 Dump
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs/heapdump.hprof"

# 使用 MAT 或 VisualVM 分析 Dump 文件

检查大文档处理： 上传超大文档时可能占用大量内存，建议限制单文档大小

GC 停顿过长

现象： 系统偶尔出现数秒无响应（Stop-the-World 暂停）。

解决：

切换到 G1 GC（推荐）：

bash

JAVA_OPTS="-XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:G1HeapRegionSize=8m"

开启 GC 日志分析：

bash

JAVA_OPTS="$JAVA_OPTS -Xlog:gc*:file=/app/logs/gc.log:time,uptime,level,tags:filecount=10,filesize=50m"

减少老年代压力： 如果 Full GC 频繁，适当增大堆内存或优化代码中的大对象分配

数据库慢查询

现象： 部分操作响应缓慢，数据库 CPU 占用高。

排查步骤：

sql

-- MySQL -- 查看慢查询
SHOW VARIABLES LIKE 'slow_query%';
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

-- 查看当前正在执行的查询
SHOW PROCESSLIST;

-- PostgreSQL -- 查看活跃查询
SELECT pid, now() - pg_stat_activity.query_start AS duration, query, state
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;

优化建议：

确认数据库表已建立必要的索引
定期执行 ANALYZE 更新统计信息
大数据量场景考虑分表或读写分离

通用排查工具

日志查看

bash

# Docker 环境
docker compose logs -f snail-ai-server       # 后端日志
docker compose logs -f mysql                  # 数据库日志
docker compose logs -f pgvector               # 向量数据库日志
docker compose logs -f nginx                  # Nginx 日志

# systemd 环境
journalctl -u snail-ai-server -f --since "10 minutes ago"

# 按关键字过滤
docker compose logs snail-ai-server | grep -i "error\|exception\|failed"

健康检查

bash

# 后端健康检查
curl http://localhost:8080/actuator/health

# 数据库连接检查
curl http://localhost:8080/actuator/health/db

# gRPC 服务检查（查看端口监听）
ss -tlnp | grep 18888

系统资源监控

bash

# CPU 和内存
top -p $(pgrep -f snail-ai)

# 磁盘使用
df -h

# 网络连接
ss -tlnp | grep -E "8080|18888|3306|5432"

# Java 进程详情
jps -lv
jstat -gc $(pgrep -f snail-ai) 1000

获取帮助

如果以上排查方法无法解决问题，可以通过以下渠道寻求帮助：

查看常见问题 -- FAQ
搜索已有 Issue -- Gitee Issues
提交新 Issue -- 请附上以下信息：
- Snail AI 版本号
- 操作系统和 Java 版本
- 数据库类型和版本
- 完整的错误日志（脱敏后）
- 复现步骤

下一步

配置参考 -- 检查和优化配置
生产环境部署 -- 生产环境最佳实践
常见问题 -- 更多使用问题解答

故障排除 ​

安装与依赖 ​

Java 版本不兼容 ​

Maven 依赖下载失败 ​

前端依赖安装失败 ​

达梦 JDBC 驱动找不到 ​

数据库问题 ​

数据库连接失败 ​

数据库初始化脚本执行失败 ​

数据库迁移失败 ​

向量存储问题 ​

PgVector 扩展安装失败 ​

PgVector 向量维度不匹配 ​

Milvus 连接失败 ​

Elasticsearch 集群状态异常 ​

Agent Client 问题 ​

gRPC 连接失败 ​

心跳超时 ​

注册失败 ​

模型调用问题 ​

API Key 无效 ​

模型调用超时 ​

速率限制 (Rate Limiting) ​

RAG 知识库问题 ​

文档解析失败 ​

向量嵌入失败 ​

检索结果不准确 ​

性能问题 ​

对话响应缓慢 ​

内存溢出 (OOM) ​

GC 停顿过长 ​

数据库慢查询 ​

通用排查工具 ​

日志查看 ​

健康检查 ​

系统资源监控 ​

获取帮助 ​

下一步 ​

故障排除

安装与依赖

Java 版本不兼容

Maven 依赖下载失败

前端依赖安装失败

达梦 JDBC 驱动找不到

数据库问题

数据库连接失败

数据库初始化脚本执行失败

数据库迁移失败

向量存储问题

PgVector 扩展安装失败

PgVector 向量维度不匹配

Milvus 连接失败

Elasticsearch 集群状态异常

Agent Client 问题

gRPC 连接失败

心跳超时

注册失败

模型调用问题

API Key 无效

模型调用超时

速率限制 (Rate Limiting)

RAG 知识库问题

文档解析失败

向量嵌入失败

检索结果不准确

性能问题

对话响应缓慢

内存溢出 (OOM)

GC 停顿过长

数据库慢查询

通用排查工具

日志查看

健康检查

系统资源监控

获取帮助

下一步