xinli/RAG-DEPLOYMENT-CHECKLIST.md

RAG知识库系统 - 部署检查清单

📋 部署前检查

1. 环境准备

• Java JDK 8+ 已安装

  java -version
  

• Ollama 已安装并运行

  ollama serve
  curl http://localhost:11434/api/tags
  

• Python 3.8+ 已安装

  python --version
  

• ChromaDB 已安装

  pip install chromadb
  

2. 模型准备

• nomic-embed-text 模型已下载

  ollama pull nomic-embed-text
  

• deepseek-r1:32b 模型已下载（或其他生成模型）

  ollama pull deepseek-r1:32b
  # 或使用更小的模型
  ollama pull qwen2.5:7b
  

• 验证模型列表

  ollama list
  

3. 目录结构

• 创建数据目录

  mkdir D:\wwwroot\RAG\data\chroma_db
  

• 创建上传目录

  mkdir D:\wwwroot\RAG\uploads
  

• 创建日志目录

  mkdir D:\wwwroot\RAG\logs
  

• 创建备份目录（可选）

  mkdir D:\wwwroot\RAG\backups
  

4. 配置文件

• 检查 application.yml 配置

  • Ollama URL: http://localhost:11434
  • ChromaDB URL: http://localhost:8000
  • 文件路径正确
  • 模型名称正确

• 检查数据库配置

  • MySQL连接正常
  • 数据库表已创建

5. 依赖检查

• Maven依赖已下载

  mvn dependency:resolve
  

• 编译无错误

  mvn clean compile
  

🚀 部署步骤

步骤1: 启动ChromaDB

# 在单独的命令行窗口运行
chroma run --path D:\wwwroot\RAG\data\chroma_db --port 8000

• ChromaDB启动成功
• 端口8000可访问
• 心跳检查通过

  curl http://localhost:8000/api/v1/heartbeat
  

步骤2: 启动Ollama

# 在单独的命令行窗口运行
ollama serve

• Ollama启动成功
• 端口11434可访问
• API可访问

  curl http://localhost:11434/api/tags
  

步骤3: 编译应用

mvn clean package -DskipTests

• 编译成功
• JAR包已生成: ry-xinli-admin/target/xinli-admin.jar

步骤4: 启动应用

java -jar ry-xinli-admin/target/xinli-admin.jar

• 应用启动成功
• 端口8080可访问
• 无启动错误

步骤5: 健康检查

curl http://localhost:8080/psychology/rag-test/health

• 返回200状态码
• ollama: "OK"
• chromadb: "OK"
• overall_status: "HEALTHY"

✅ 功能验证

基础功能测试

• 向量化测试

  curl -X POST "http://localhost:8080/psychology/rag-test/test-embedding" \
    -d "text=测试文本"
  

  预期: 返回768维向量

• 生成测试

  curl -X POST "http://localhost:8080/psychology/rag-test/test-generation" \
    -d "prompt=什么是心理学？"
  

  预期: 返回生成的文本

• ChromaDB测试

  curl -X POST "http://localhost:8080/psychology/rag-test/test-chromadb"
  

  预期: 成功存储和查询

核心功能测试

• 文档上传

  • 准备测试文档（PDF/Word/TXT）
  • 上传成功
  • 返回文档ID
  • 向量化完成

• 文档列表

  • 查询文档列表
  • 分页正常
  • 显示文档信息

• 文档搜索

  • 按文件名搜索
  • 返回匹配结果

• 文档删除

  • 删除测试文档
  • 向量同步删除

• 智能问答

  • 提问成功
  • 返回答案
  • 包含来源引用

• 报告生成

  • 生成综合报告
  • 包含知识库内容
  • 包含来源引用

• 文件监听

  • 放文件到uploads目录
  • 自动检测并处理
  • 日志记录正常

🔍 性能测试

响应时间

• 向量化: < 200ms
• 语义检索: < 100ms
• 报告生成: < 30秒
• 文档上传: < 5秒/MB

并发测试

• 5个并发用户正常
• 10个并发用户正常
• 无内存泄漏
• 无连接池耗尽

大文件测试

• 10MB PDF上传成功
• 30MB PDF上传成功
• 50MB PDF上传成功（上限）

📊 监控检查

日志

• 应用日志正常写入

  tail -f D:\wwwroot\RAG\logs\xinli-admin.log
  

• 无ERROR级别日志（除预期错误）

• 日志格式正确

• 日志轮转配置正确

系统状态

• CPU使用率正常（< 80%）
• 内存使用率正常（< 80%）
• 磁盘空间充足（> 10GB）
• 网络连接正常

数据库

• MySQL连接正常
• 表结构正确
• 数据写入正常
• 查询性能正常

🔒 安全检查

• 文件上传大小限制生效（50MB）
• 文件格式白名单生效
• API权限控制正常
• 敏感信息已脱敏
• HTTPS配置（生产环境）

📚 文档检查

• README.md 完整
• 快速启动指南完整
• API文档完整
• 故障排除指南完整
• 用户手册完整

🎯 生产环境额外检查

高可用

• 数据库主从复制配置
• 应用多实例部署
• 负载均衡配置
• 故障转移测试

备份

• 数据库自动备份
• ChromaDB数据备份
• 上传文件备份
• 备份恢复测试

监控告警

• 服务监控配置
• 告警规则配置
• 告警通知测试
• 日志聚合配置

✨ 最终确认

• 所有测试通过
• 性能满足要求
• 文档齐全
• 用户培训完成
• 技术支持就绪

📝 部署记录

部署日期: _______________

部署人员: _______________

环境信息:

• Java版本: _______________
• Ollama版本: _______________
• ChromaDB版本: _______________
• 应用版本: _______________

测试结果:

• 基础功能: □ 通过 □ 失败
• 核心功能: □ 通过 □ 失败
• 性能测试: □ 通过 □ 失败
• 安全检查: □ 通过 □ 失败

备注:

---

---

---

签字: _______________