181 lines
8.5 KiB
Markdown
181 lines
8.5 KiB
Markdown
## RAG-Agent 代码审查报告（精简版）
|
||
|
||
审查日期：2026-06-05
|
||
|
||
排除说明：storage 模块尚未启用（暂不纳入）；用户认证/权限由后端服务负责（生产环境 RAG 服务为无状态接口，不做鉴权）。
|
||
|
||
---
|
||
|
||
### 一、高危问题（6 项）
|
||
|
||
**H1. SSE 错误事件泄露完整堆栈信息**
|
||
- 文件：`api/chat_routes.py:1955`
|
||
- `/rag` 接口 SSE 生成器在异常时将 `traceback.format_exc()` 完整堆栈直接发给客户端，暴露调用栈、文件路径、代码行号、内部变量。
|
||
- 修复：移除 traceback 字段，仅在服务端日志记录，客户端返回通用错误消息。
|
||
|
||
**H2. 文档更新/删除接口存在路径遍历风险**
|
||
- 文件：`api/document_routes.py:652,714`
|
||
- `update_document` 和 `delete_document` 直接将 URL 中的 `doc_path` 拼接到文件路径，未做安全校验。可构造 `../../` 路径遍历载荷。
|
||
- 修复：使用 `os.path.realpath()` 解析最终路径，验证是否在 DOCUMENTS_PATH 目录下。
|
||
|
||
**H3. `serve_document_file` 路径遍历风险**
|
||
- 文件：`api/document_routes.py:139`
|
||
- 文件服务接口同样存在路径遍历风险。虽然有 DEV_MODE 开关，但默认值为 `'true'`。
|
||
- 修复：添加 realpath 校验。
|
||
|
||
**H4. 文档更新接口缺少文件类型和大小校验**
|
||
- 文件：`api/document_routes.py:621`
|
||
- `update_document` (PUT) 未验证文件类型和大小，直接 `file.save(filepath)`。与之对比，`upload_document` 有完整校验。
|
||
- 修复：添加与 upload 一致的 ALLOWED_EXTENSIONS 和 MAX_FILE_SIZE 校验。
|
||
|
||
**H5. 批量上传接口缺少文件大小校验**
|
||
- 文件：`api/document_routes.py:350`
|
||
- `batch_upload_documents` 对每个文件只检查了扩展名，未检查文件大小。可批量上传超大文件导致磁盘耗尽。
|
||
- 修复：在循环内添加 MAX_FILE_SIZE 校验。
|
||
|
||
**H6. `main.py` debug 模式默认开启 + 监听 0.0.0.0**
|
||
- 文件：`main.py:29-31`
|
||
- `--debug` 默认 `True`，`--host` 默认 `0.0.0.0`。Flask 调试模式启用 Werkzeug 交互式 debugger，可通过触发异常执行任意代码。
|
||
- 修复：`--debug` 默认值改为 `False`。
|
||
|
||
---
|
||
|
||
### 二、中危问题（13 项）
|
||
|
||
**M1. 多处异常响应直接暴露内部错误信息**
|
||
- 文件：`document_routes.py:332,467,733`；`kb_routes.py:523,636`；`feedback_routes.py:98,116`；`sync_routes.py:119`；`audit_routes.py:100` 等。
|
||
- 大量 `except` 块直接 `str(e)` 返回给客户端，可能包含数据库路径、SQL 片段、文件系统结构。
|
||
- 修复：统一使用通用错误消息，原始异常仅记录到服务端日志。
|
||
|
||
**M2. `/search` 接口缺少输入安全验证**
|
||
- 文件：`api/chat_routes.py:1974`
|
||
- 未调用 `validate_query()` 做注入检测和长度限制，与 `/chat`、`/rag` 不一致。
|
||
- 修复：添加 `validate_query(query)` 调用。
|
||
|
||
**M3. `/search` 的 `top_k` 参数未校验范围**
|
||
- 文件：`api/chat_routes.py:1989`
|
||
- 可传 `top_k=999999` 导致内存溢出。
|
||
- 修复：`top_k = max(1, min(int(top_k), 50))`。
|
||
|
||
**M4. `context_count` 参数未校验范围**
|
||
- 文件：`api/document_routes.py:821`
|
||
- 未限制范围且非整数字符串会 ValueError 导致 500。
|
||
- 修复：try/except + `max(0, min(n, 10))`。
|
||
|
||
**M5. CORS 配置允许所有来源**
|
||
- 文件：`api/__init__.py:70`
|
||
- `CORS(app)` 默认允许 `*` 跨域。生产环境应限制为已知前端域名。
|
||
- 修复：根据 APP_ENV 条件配置 origins。
|
||
|
||
**M6. LIKE 通配符注入风险**
|
||
- 文件：`api/kb_routes.py:503`
|
||
- `kb_name` 含 `%` 或 `_` 时会导致非预期的 LIKE 匹配行为。
|
||
- 修复：对 LIKE 特殊字符转义后再拼入模式。
|
||
|
||
**M7. SESSION_MANAGER 为 None 时未处理**
|
||
- 文件：`api/session_routes.py:35,64,83,102`
|
||
- 初始化失败时 SESSION_MANAGER 为 None，调用方法会触发 AttributeError 导致 500。
|
||
- 修复：使用前检查 None，返回 503。
|
||
|
||
**M8. LLM 调用缺少统一的超时和重试机制**
|
||
- 文件：`core/llm_utils.py`
|
||
- 部分 LLM 调用无超时控制，长时间阻塞会耗尽 worker。`@retry` 装饰器只在部分方法上使用。
|
||
- 修复：在 `_call_llm` 层面统一超时和重试。
|
||
|
||
**M9. LLM 输出 JSON 解析不够健壮**
|
||
- 文件：`core/agentic.py`、`core/agentic_answer.py`、`core/agentic_quality.py` 等
|
||
- 多处 LLM 返回的 JSON 解析缺少多策略提取和重试，仅靠 prompt 约束。exam_pkg 已修复但 core 模块尚未统一。
|
||
- 修复：提取 exam_pkg 的 `_extract_json` 为公共工具，core 模块统一使用。
|
||
|
||
**M10. Prompt 注入风险**
|
||
- 文件：`core/engine.py:2017`、`core/agentic_answer.py:83`
|
||
- 用户输入直接拼入 prompt，未做净化。恶意输入可操控 LLM 输出。
|
||
- 修复：对用户输入做基本的 prompt 注入检测（如检测 "ignore previous instructions" 等模式）。
|
||
|
||
**M11. `subprocess.run` 命令参数注入风险**
|
||
- 文件：`parsers/mineru_parser.py:632`
|
||
- file_path 中特殊字符（如以 `-` 开头的文件名）可能被命令行工具解释为选项。
|
||
- 修复：在文件路径前插入 `--` 分隔符；对 backend、lang 参数做白名单校验。
|
||
|
||
**M12. Excel/文本解析器无文件大小限制**
|
||
- 文件：`parsers/excel_parser.py:81`、`parsers/txt_parser.py:15`
|
||
- 一次性加载全文件到内存，超大文件导致 OOM。
|
||
- 修复：解析前检查文件大小，设定上限（如 50MB）。
|
||
|
||
**M13. 全局变量缓存竞态条件**
|
||
- 文件：`api/document_routes.py:100`、`api/kb_routes.py:46`
|
||
- 模块级全局变量 `_kb_manager` 等在多线程 gunicorn 下存在竞态。
|
||
- 修复：使用 `threading.Lock` 保护或改用 `flask.current_app.config`。
|
||
|
||
---
|
||
|
||
### 三、低危问题（12 项）
|
||
|
||
**L1.** `config.py` 硬编码第三方 API 端点 `xiaomimimo.com` 作为默认值（第 20 行）— 改为空字符串，要求环境变量显式配置。
|
||
|
||
**L2.** `python-dotenv` 未安装时静默跳过，服务可能 fail-open 启动（`config.py:11`）— 生产环境缺失时抛异常。
|
||
|
||
**L3.** `assert` 校验可被 `python -O` 跳过（`api/__init__.py:236`）— 改为 `raise ValueError`。
|
||
|
||
**L4.** `/chat` 的 `history` 未限长度（`chat_routes.py:1247`）— 可消耗大量 token。
|
||
|
||
**L5.** `history` 元素结构未验证（`chat_routes.py:1117`）— 缺少字段时 KeyError 导致 500。
|
||
|
||
**L6.** `safe_filename` 运算符优先级不明确（`document_routes.py:94`）— 加括号明确。
|
||
|
||
**L7.** DocStore glob 模式未转义特殊字符（`document_routes.py:267`）— 用 `glob.escape()`。
|
||
|
||
**L8.** 相对路径 `.data/images` 因工作目录不同可能解析错误（`chat_routes.py:59`）— 改用 PROJECT_ROOT 绝对路径。
|
||
|
||
**L9.** `asyncio.run()` 在 Flask 请求上下文中兼容性问题（`chat_routes.py:1744`）。
|
||
|
||
**L10.** Excel 同一文件被重复读取多次（`excel_parser.py:81,89`）— 应复用 ExcelFile 对象。
|
||
|
||
**L11.** PDF 图片提取 `doc` 对象异常时未关闭（`image_extractor.py:78`）— 改用 `with` 语句。
|
||
|
||
**L12.** TXT 解析器异常用 `print` 而非 `logger`（`txt_parser.py:26`）。
|
||
|
||
---
|
||
|
||
### 四、修复优先级
|
||
|
||
按修复成本从低到高排序：
|
||
|
||
**第一批：快速修复（半天，改几行代码）**
|
||
|
||
| 编号 | 问题 | 改动量 |
|
||
|:---:|---|:---:|
|
||
| H6 | main.py debug 默认开启 | 1 行 |
|
||
| M3 | /search top_k 范围校验 | 2 行 |
|
||
| M2 | /search 加 validate_query | 2 行 |
|
||
| M4 | context_count 范围校验 | 3 行 |
|
||
| L3 | assert 改 raise | 3 行 |
|
||
| H1 | SSE 移除 traceback 字段 | 5 行 |
|
||
|
||
**第二批：安全加固（1-2 天）**
|
||
|
||
| 编号 | 问题 | 改动量 |
|
||
|:---:|---|:---:|
|
||
| H2+H3 | 文档接口路径遍历 realpath 校验 | ~30 行 |
|
||
| H4+H5 | 文档更新/批量上传加文件校验 | ~30 行 |
|
||
| M6 | LIKE 通配符转义 | ~10 行 |
|
||
| M1 | 异常信息统一脱敏 | 多文件，每处 2-3 行 |
|
||
| M5 | CORS 生产环境限制来源 | ~5 行 |
|
||
| M7 | SESSION_MANAGER None 保护 | ~10 行 |
|
||
| M11 | subprocess 参数注入防护 | ~5 行 |
|
||
|
||
**第三批：架构改进（1-2 周）**
|
||
|
||
| 编号 | 问题 | 说明 |
|
||
|:---:|---|---|
|
||
| M8+M9 | LLM 调用统一超时/重试/解析 | 提取 exam_pkg 经验为公共工具 |
|
||
| M10 | Prompt 注入防御 | 需设计检测规则 |
|
||
| M13 | 全局变量竞态修复 | threading.Lock |
|
||
| M12 | 解析器文件大小限制 | 统一加前置校验 |
|
||
|
||
---
|
||
|
||
### 五、做得好的方面
|
||
|
||
SQL 查询全部使用参数化查询，无注入风险；`validate_query()` 对聊天输入做了注入检测和违禁词过滤；`safe_filename` 对上传文件做了基本防护；`filter_response()` 能过滤 API 密钥等敏感信息；exam_pkg 的输入校验体系完整（已在本轮开发中加固）；`.gitignore` 正确排除了 `.env` 等敏感文件。
|