# RAG 后端上线清单

适用范围：
- 仓库：`leaudit-platform`
- 本次上线内容：自有 RAG 聊天后端、`/api/v3/rag/*` 接口、`rag_*` 表结构、`rag:*` 权限

## 1. 上线前确认

- 代码已包含以下变更：
  - `fastapi_modules/fastapi_leaudit/controllers/ragChatController.py`
  - `fastapi_modules/fastapi_leaudit/services/impl/ragChatServiceImpl.py`
  - `fastapi_modules/fastapi_leaudit/services/impl/ragDatasetServiceImpl.py`
  - `scripts/创建sql/schema_add_rag_chat.sql`
  - `scripts/创建sql/user_rbac_seed.sql`
  - `pyproject.toml` 已加入 `chromadb`
- 发布分支已经合并到目标部署分支。
- 数据库备份已完成，至少备份：
  - `permissions`
  - `role_permissions`
  - `role_route`
  - `sys_routes`
  - 全部 `rag_*` 表

## 2. 配置优先级

后端配置加载顺序见 `fastapi_admin/config/_loader.py`：

1. `app.toml`
2. `app.{APP_ENV}.toml`
3. `app.ai.toml`
4. 已存在的环境变量

结论：
- 生产环境如果通过环境变量注入，优先级最高。
- 如果继续使用 TOML，建议把生产密钥放到 `app.ai.toml` 或外部环境变量，不要直接把敏感值写死在默认 `app.toml`。

## 3. 必备环境变量 / 配置项

### 3.1 基础服务配置

来自 `fastapi_admin/config/_settings.py`：

- `APP_HOST`
- `APP_PORT`
- `JWT_SECRET_KEY`
- `DB_HOST`
- `DB_PORT`
- `DB_NAME`
- `DB_USER`
- `DB_PASSWORD`
- `REDIS_HOST`
- `REDIS_PORT`
- `REDIS_DB`
- `REDIS_PASSWORD`
- `OSS_ENDPOINT`
- `OSS_BASE_URL`
- `OSS_ACCESS_KEY`
- `OSS_SECRET_KEY`
- `OSS_BUCKET`

### 3.2 RAG / LLM 配置

来自 `fastapi_modules/fastapi_leaudit/rag_engine/config.py`：

- `LLM_BASE_URL`
- `LLM_MODEL`
- `LLM_API_KEY`
- `RAG_LLM_TEMPERATURE`
- `RAG_LLM_MAX_TOKENS`
- `RAG_LLM_TIMEOUT`

### 3.3 Chroma 配置

二选一：

- 远程 Chroma：
  - `RAG_CHROMA_HOST`
  - `RAG_CHROMA_PORT`
  - `RAG_CHROMA_TOKEN`（如有鉴权）
  - `RAG_CHROMA_AUTH_HEADER`（默认 `X-Chroma-Token`）
- 本地持久化 Chroma：
  - `RAG_CHROMA_PERSIST_DIR`

说明：
- 如果不配置 `RAG_CHROMA_HOST`，代码会走本地 `PersistentClient`。
- 如果 Chroma 依赖缺失或不可用，服务能启动，但检索会退化成“无上下文回答”。

### 3.4 可选检索参数

- `RAG_VECTOR_TOP_K`
- `RAG_RERANK_TOP_K`
- `RAG_BM25_TOP_K`
- `RAG_RRF_K`
- `RAG_QUERY_REWRITING`
- `RAG_HYBRID_SEARCH`
- `RAG_RERANKING`
- `RAG_EMBED_URL`
- `RAG_EMBED_KEY`
- `RAG_EMBED_MODEL`
- `RAG_EMBED_DIM`
- `RAG_EMBED_BATCH_SIZE`
- `RAG_RERANKER_URL`
- `RAG_RERANKER_KEY`
- `RAG_RERANKER_MODEL`

说明：
- 当前聊天主流程已经能工作；即使没有完整 embedding/reranker 配置，只要现有 Chroma 集合可用，也可以先上线基础聊天。
- 更细的召回参数也可以放在 `rag_dataset.retrieval_model` 里按知识库配置。

## 4. 依赖安装

### 4.1 Python 依赖

本次新增依赖：

- `chromadb>=0.5.23`

如果线上使用虚拟环境：

```bash
source .venv/bin/activate
pip install -e .
```

如果只补增量依赖：

```bash
source .venv/bin/activate
pip install chromadb
```

建议最终仍执行一次完整依赖同步，避免环境漂移。

## 5. 数据库执行顺序

### 5.1 先执行结构脚本

```bash
psql -v ON_ERROR_STOP=1 \
  -h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME> \
  -f scripts/创建sql/schema_add_rag_chat.sql
```

作用：
- 创建 `rag_dataset / rag_document / rag_chat_app / rag_conversation / rag_message`
- 对已存在表补字段、补索引、补 `updated_at` 触发器

### 5.2 再执行权限种子

```bash
psql -v ON_ERROR_STOP=1 \
  -h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME> \
  -f scripts/创建sql/user_rbac_seed.sql
```

作用：
- 补 `rag:*` 权限
- 补角色授权
- 同步需要的菜单/路由元数据

### 5.3 当前已验证结果

本地已在目标库执行并验证：

- 已存在 5 张 `rag_*` 表
- 已存在 7 条 `rag:*` 权限
- `super_admin / provincial_admin / admin / common` 均已获得这 7 条权限

## 6. 重启顺序

推荐顺序如下。

### 步骤 1：停 Celery worker

如果当前有 worker 在跑，先停掉，避免旧代码消费任务：

```bash
pkill -f "celery.*fastapi_admin.celery_app:celery_app" || true
```

如果你们线上是用进程管理器托管 worker，则用对应管理命令停止。

### 步骤 2：更新代码并安装依赖

```bash
git pull
source .venv/bin/activate
pip install -e .
```

### 步骤 3：执行数据库脚本

按“第 5 节”的先后顺序执行：

1. `scripts/创建sql/schema_add_rag_chat.sql`
2. `scripts/创建sql/user_rbac_seed.sql`

### 步骤 4：重启 FastAPI 主服务

如果用 `uvicorn` 直接启动，参考 `run.py`：

```bash
source .venv/bin/activate
python run.py
```

如果线上不是 `reload=True` 的开发模式，建议使用你们现有的生产启动命令重启主进程，不要直接照抄开发命令。

### 步骤 5：重启 Celery worker

仓库已提供脚本 `scripts/start_worker.sh`：

```bash
./scripts/start_worker.sh
```

它会自动读取：
- `LEAUDIT_WORKER_CONCURRENCY`
- `LEAUDIT_WORKER_QUEUE_URGENT`
- `LEAUDIT_WORKER_QUEUE_NORMAL`

### 步骤 6：如有反向代理，再做一次健康检查

- Nginx / 网关 upstream 是否恢复
- 80/443 -> FastAPI upstream 是否正常

## 7. 上线后验证

### 7.1 代码级快速检查

```bash
python -m compileall fastapi_modules/fastapi_leaudit
```

### 7.2 路由检查

已知应存在 10 条 `/v3/rag` 路由：

- `GET /api/v3/rag/apps`
- `GET /api/v3/rag/apps/default`
- `GET /api/v3/rag/datasets/my`
- `GET /api/v3/rag/chat/parameters`
- `POST /api/v3/rag/chat/messages`
- `GET /api/v3/rag/chat/conversations`
- `GET /api/v3/rag/chat/conversations/{ConversationId}/messages`
- `PATCH /api/v3/rag/chat/conversations/{ConversationId}`
- `DELETE /api/v3/rag/chat/conversations/{ConversationId}`
- `POST /api/v3/rag/chat/messages/{MessageId}/feedback`

### 7.3 数据库检查

```sql
SELECT tablename
FROM pg_tables
WHERE schemaname = 'public' AND tablename LIKE 'rag_%'
ORDER BY tablename;
```

```sql
SELECT count(*)
FROM permissions
WHERE permission_key LIKE 'rag:%';
```

```sql
SELECT r.role_key, count(*)
FROM role_permissions rp
JOIN roles r ON r.id = rp.role_id
JOIN permissions p ON p.id = rp.permission_id
WHERE p.permission_key LIKE 'rag:%'
GROUP BY r.role_key
ORDER BY r.role_key;
```

### 7.4 接口联通检查

至少验证这 4 个接口：

1. `GET /api/v3/rag/apps`
2. `GET /api/v3/rag/apps/default`
3. `GET /api/v3/rag/chat/parameters`
4. `POST /api/v3/rag/chat/messages`

关注点：
- 401：JWT 或登录态异常
- 403：`rag:*` 权限未生效
- 404：控制器未注册 / 网关路径未转发
- 500：LLM、Chroma、数据库连接或 JSON 字段异常

## 8. 常见风险

- `chromadb` 未安装：服务启动不一定报错，但首次检索时会退化
- Chroma 集合为空：可以聊天，但没有知识库上下文
- `LLM_BASE_URL / LLM_API_KEY / LLM_MODEL` 配错：流式对话会直接失败
- 只执行权限脚本、不执行结构脚本：接口可能启动，但落库时报错
- 只重启 API、不重启 worker：后台异步任务仍可能跑旧代码

## 9. 建议的最短上线动作

按最快可落地顺序：

1. 备份数据库
2. `git pull`
3. `source .venv/bin/activate && pip install -e .`
4. 执行 `scripts/创建sql/schema_add_rag_chat.sql`
5. 执行 `scripts/创建sql/user_rbac_seed.sql`
6. 重启 FastAPI 主服务
7. 重启 `scripts/start_worker.sh`
8. 验证 `/api/v3/rag/apps` 和 `/api/v3/rag/chat/messages`