xinli/Archive/RAG-DEPLOYMENT-CHECKLIST.md

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

## 📋 部署前检查

### 1. 环境准备

- [ ] Java JDK 8+ 已安装
  ```bash
  java -version
  ```

- [ ] Ollama 已安装并运行
  ```bash
  ollama serve
  curl http://localhost:11434/api/tags
  ```

- [ ] Python 3.8+ 已安装
  ```bash
  python --version
  ```

- [ ] ChromaDB 已安装
  ```bash
  pip install chromadb
  ```

### 2. 模型准备

- [ ] nomic-embed-text 模型已下载
  ```bash
  ollama pull nomic-embed-text
  ```

- [ ] deepseek-r1:32b 模型已下载（或其他生成模型）
  ```bash
  ollama pull deepseek-r1:32b
  # 或使用更小的模型
  ollama pull qwen2.5:7b
  ```

- [ ] 验证模型列表
  ```bash
  ollama list
  ```

### 3. 目录结构

- [ ] 创建数据目录
  ```bash
  mkdir D:\wwwroot\RAG\data\chroma_db
  ```

- [ ] 创建上传目录
  ```bash
  mkdir D:\wwwroot\RAG\uploads
  ```

- [ ] 创建日志目录
  ```bash
  mkdir D:\wwwroot\RAG\logs
  ```

- [ ] 创建备份目录（可选）
  ```bash
  mkdir D:\wwwroot\RAG\backups
  ```

### 4. 配置文件

- [ ] 检查 `application.yml` 配置
  - Ollama URL: `http://localhost:11434`
  - ChromaDB URL: `http://localhost:8000`
  - 文件路径正确
  - 模型名称正确

- [ ] 检查数据库配置
  - MySQL连接正常
  - 数据库表已创建

### 5. 依赖检查

- [ ] Maven依赖已下载
  ```bash
  mvn dependency:resolve
  ```

- [ ] 编译无错误
  ```bash
  mvn clean compile
  ```

## 🚀 部署步骤

### 步骤1: 启动ChromaDB

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

- [ ] ChromaDB启动成功
- [ ] 端口8000可访问
- [ ] 心跳检查通过
  ```bash
  curl http://localhost:8000/api/v1/heartbeat
  ```

### 步骤2: 启动Ollama

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

- [ ] Ollama启动成功
- [ ] 端口11434可访问
- [ ] API可访问
  ```bash
  curl http://localhost:11434/api/tags
  ```

### 步骤3: 编译应用

```bash
mvn clean package -DskipTests
```

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

### 步骤4: 启动应用

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

- [ ] 应用启动成功
- [ ] 端口8080可访问
- [ ] 无启动错误

### 步骤5: 健康检查

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

- [ ] 返回200状态码
- [ ] `ollama: "OK"`
- [ ] `chromadb: "OK"`
- [ ] `overall_status: "HEALTHY"`

## ✅ 功能验证

### 基础功能测试

- [ ] **向量化测试**
  ```bash
  curl -X POST "http://localhost:8080/psychology/rag-test/test-embedding" \
    -d "text=测试文本"
  ```
  预期: 返回768维向量

- [ ] **生成测试**
  ```bash
  curl -X POST "http://localhost:8080/psychology/rag-test/test-generation" \
    -d "prompt=什么是心理学？"
  ```
  预期: 返回生成的文本

- [ ] **ChromaDB测试**
  ```bash
  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上传成功（上限）

## 📊 监控检查

### 日志

- [ ] 应用日志正常写入
  ```bash
  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版本: _______________
- 应用版本: _______________

**测试结果**:
- 基础功能: □ 通过 □ 失败
- 核心功能: □ 通过 □ 失败
- 性能测试: □ 通过 □ 失败
- 安全检查: □ 通过 □ 失败

**备注**: 
_______________________________________________
_______________________________________________
_______________________________________________

**签字**: _______________