# 题库刷题报错根治报告

**日期**：2026-10-02
**范围**：全面读取系统启动文件链路，定位并根治题库刷题存在的报错
**原则**：先探查定位 → 确认真实根因 → 最小改动根治 → 隔离验证 → 变更留痕（可回滚）

---

## 一、结论速览

| 项 | 结果 |
|---|---|
| 全面排查 | 启动文件链路（start.bat / main.py / watchdog.py / 重启入口）+ 刷题全接口 + 前端刷题 JS + 题库数据库 + 近期运行日志 |
| 唯一反复真实报错 | **Ollama 未运行，AI/RAG embedding 持续 `10061 无法连接`（当天 45 次）**，AI 解析/智能讲解/错因分析/RAG 检索等刷题 AI 功能不可用 |
| 根因 | watchdog 的 `_find_ollama_exe` 只探测 PATH 与常见安装路径，**未探测项目内置 `backend\ollama\ollama.exe`** → `ensure_ollama` 每次判"未找到"而跳过 → Ollama 永远不被拉起 |
| 附带缺陷 | `ensure_ollama` 拉起 ollama 时不设置 `OLLAMA_MODELS`，即使拉起也用默认空目录、无模型 |
| 已根治 | 修复 watchdog.py 两处；即时拉起 Ollama 并验证 AI 全链路可用 |
| 刷题主链路 | 组卷/答题/交卷/收藏/笔记/练习状态接口全部 200，前端刷题 JS 语法正常，与后端字段对齐 |

---

## 二、全面排查过程

### 2.1 启动文件链路（已读取）
- `start.bat`：Ollama 预检启动 → 杀旧 8000 后端 → 选 Python3.11 → pip 安装 → 初始化数据库（preflight_check / mechanism_center / monitor）→ 启动后端（WMI）→ wait_for_backend → startup_verify → 打开浏览器 → watchdog。
- `backend/main.py`：日志、全局中间件（系统字段过滤/限流/幂等/缓存）、异常脱敏、`/api/health` 健康探针、`init_db()` 后台任务/夜间调度/健康中心、数据库迁移、崩溃自动重启循环。
- `backend/watchdog.py`：单实例锁、后端保活（端口/内存/健康三态探测）、**`ensure_ollama()` Ollama 保活**。
- 重启入口（重启后端.bat / restart.ps1 / start.bat）均**只重启后端 main.py，不负责拉起 Ollama**。

### 2.2 刷题链路实测（全部 200）
| 接口 | 说明 | 结果 |
|---|---|---|
| `GET /api/v1/question/random_real` | 组卷/抽题 | 200，返回 list/total/real_total |
| `GET /api/v1/question/practice_state` | 练习状态（未刷/已答/错题+wrong_meta） | 200，字段与前端完全对齐 |
| `GET /api/qb/wrong/today` | 今日待复习（SM-2） | 200 |
| `GET /api/qb/collect/list`、`/api/common/notes` | 收藏、笔记 | 200 |
| 前端 question-practice.js 等 4 个刷题 JS | node --check 语法 | 全部通过 |

### 2.3 运行日志中的真实报错
- **`api.v1._rag_engine` Ollama embedding 失败：`WinError 10061 无法连接`——当天 45 次**（每 ~5 分钟一次），专家体检运维 warning 同步触发。
- `service_monitor` 内存告警 `critical 91-92%`（11:38-11:42 时段）。

---

## 三、根因定位（含完整证据链）

1. **Ollama 服务当前未运行**：无 ollama 进程、11434 端口未监听、`/api/health` 之前显示 offline。
2. **watchdog 一直在尝试保活但必然失败**：`watchdog.log` 每 ~69 秒输出一条 `[ollama保活] 未找到 ollama.exe（已探测PATH与常见路径），跳过`。
3. **根因代码缺陷**：`watchdog._find_ollama_exe()` 候选路径只含
   `~\AppData\...\Ollama\ollama.exe`、`%LOCALAPPDATA%\...`、`C:\Program Files\Ollama\...`、`shutil.which('ollama')`——
   **唯独没有项目内置 `backend\ollama\ollama.exe`**。watchdog 由 WMI/系统会话启动，环境 PATH 不含 ollama，`shutil.which` 与用户路径均失效 → 返回 None → 跳过拉起。
4. **附带缺陷**：`ensure_ollama()` 的 `subprocess.Popen([oll,'serve'])` **未设置 `OLLAMA_MODELS`**。即使未来找到 exe，Ollama 也会用默认 `%USERPROFILE%\.ollama` 空目录 → 无任何模型 → AI 仍不可用。
5. **可启动性验证**：项目 `backend\ollama\ollama.exe` 存在，模型目录 `backend\ollama_models` 含完整 7 个模型（bge-m3 / qwen2.5:3b / qwen2.5:7b / qwen3-vl:2b / qwen3-vl:4b / deepseek-r1:7b / bge-small-zh-v1.5）。用正确 `OLLAMA_MODELS` 拉起，**2 秒内就绪**。

> 结论：**"Ollama 找不到 → 不拉起 → AI/embedding 持续 10061"是一条必然失败的死链**。本次从"找不到 exe"与"拉起用错目录"两处根上修复。

---

## 四、修复内容

| 文件 | 修复点 |
|---|---|
| `backend/watchdog.py` `_find_ollama_exe` | 候选路径**首增项目内置 `backend\ollama\ollama.exe`**（任何环境固定存在），彻底解决"找不到 exe" |
| `backend/watchdog.py` `ensure_ollama` | 拉起 ollama serve 时**显式构造 env**：`OLLAMA_MODELS=backend\ollama_models`、`OLLAMA_HOST=0.0.0.0:11434`、`OLLAMA_HF_MIRROR=https://modelscope.cn`，解决"拉起用错模型目录" |

改动前两文件均已备份至 `_archive/modified_backups_20261002/`；变更已记入 `CHANGE_LEDGER.json` id=109。

---

## 五、验证结果

| 验证项 | 结果 |
|---|---|
| `watchdog.py` py_compile | ✅ 通过 |
| `import watchdog` 逻辑 | ✅ `_find_ollama_exe` 找到 exe；`ensure_ollama` 在 11434 在听时返回 True |
| 即时拉起 Ollama | ✅ 用项目 exe + 正确 `OLLAMA_MODELS` 拉起（独立常驻进程），11434 监听正常 |
| `GET /api/health` | ✅ `ollama: {status:ok, models:7}`（修复前为 offline） |
| 实际 embedding 调用 | ✅ `POST /api/embed`（bge-small-zh-v1.5）返回 512 维向量成功，**10061 报错消失** |
| 后端 8000 | ✅ 全程健康，重启看门狗前后均 `ok` |

---

## 六、生效说明与限制（如实记录）

- **即时状态**：Ollama 已为独立常驻进程持续运行，刷题 AI 功能（AI 讲解/智能解析/错因分析/RAG 检索/组卷记忆曲线）现可用，`10061` 报错已消失。
- **持久生效**：`watchdog.py` 修复代码已写入磁盘，但当前运行的旧 watchdog（PID 18844）为**受保护进程，普通权限 `Access denied` 无法终止**，无法热加载新代码。需该进程**下次自然重启**（重启电脑、或重新运行 `start.bat` 时由新进程接管）后，新保活逻辑才生效——届时 Ollama 即使崩溃也会被自动拉起。
- **建议**：下次维护时以管理员身份重启一次系统，让 watchdog 加载新代码，完成持久闭环。

---

## 七、排查中发现的其它问题（不在本次改动范围，供参考）

| 问题 | 现状 | 建议 |
|---|---|---|
| 题库数据：**一造管理 451 道题 `chapter` 为空、453 道 `knowledge_point` 为空** | practice_state 出现一个空章节组（367 道无章节归属），按章节刷题/统计/掌握度分析时这些题归类为"未分类" | 建议后续基于 `knowledge_point`/`point_name`/`section_name`/`source` 做章节归一回填（需谨慎，不擅改数据） |
| 系统内存告警 `critical 91-92%`（11:38-11:42 时段） | service_monitor 告警 | 建议排查是否有进程内存泄漏（start.bat 注明系统默认 Python3.13 有内存泄漏，优先用 3.11） |
| 专家体检 2 个测试类 warning（api_smoke/endpoint_smoke 收集 0 个 GET 路由） | 启动期不真打路由所致，属测试配置口径 | 可后续调整冒烟测试的路由收集方式 |
| 题目 6120「建设工程项目分类」 | 归属"一造管理/工程项目管理"章节，属于管理科目范畴，归属无误 | 无需处理（用户对该题科目归属的疑问已核实为正常） |

---

**报告生成时间**：2026-10-02
**产物**：修复 `backend/watchdog.py`（两处）；备份与变更账本留痕；本报告。
