# kb_system
**Repository Path**: wenwang2000/kb_system
## Basic Information
- **Project Name**: kb_system
- **Description**: kb_system
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-16
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 企业级知识库管理系统 · 操作手册
一套面向企业的文档知识库管理系统:支持常见文档的解析入库、**S/A/B/C/D/E 六级保密等级**管控、
**Elasticsearch + Milvus 混合检索与重排**、检索前置优化、**跨密级检索审批流**与**全链路审计**,
模型统一通过**本地 Ollama** 提供,不依赖任何外部大模型服务。
---
核心解决三件事:
1. **知识沉淀**:把散落在 PDF/Word/Excel/HTML/文本中的资料,统一解析、清洗、分块、向量化后落库;
2. **安全可控**:文档按 S/A/B/C/D/E 六级保密等级管控,检索结果严格不越权,超范围需走审批;
3. **可检索可追溯**:Elasticsearch 全文 + Milvus 向量混合召回并重排,结果给出原文引用;
所有敏感操作全量审计。
**适用版本**:v1.0 **默认访问地址**:http://127.0.0.1:5000
---
## 1. 环境要求
### 1.1 软件依赖
| 组件 | 版本 | 端口 |
| --- |-------------------------| --- |
| Python | 3.10 – 3.13 | — |
| MySQL | 8.0+ | 3306 |
| Elasticsearch | 8.13 ~ 8.19(**必须 8.x**) | 9200 |
| Milvus | 2.4+(Standalone 或嵌入式) | 19530 |
| Ollama | - | 11434 |
> **端口冲突排查**:若 3306/9200/19530/11434/5000 被占用,改组件端口后同步修改 `.env`。
### 1.2 技术栈
架构图
```
┌──────────────────────────── 接入层 ────────────────────────────┐
│ Web 页面(Jinja2 + 原生 JS) REST API(/api/**,Bearer/ Cookie 双鉴权) │
│ 登录 / 文档管理 / 智能检索 / 审批中心 / 审计日志 / 管理后台 │
└───────────────────────────────┬───────────────────────────────┘
│
┌──────────────────────── 应用服务层 ──────────────────────────────┐
│ services/ 文档服务 · 审批服务 · 审计服务 · 用户服务 │
│ pipeline/ 解析 → 清洗降噪 → 分块 → 向量化 → 三写(状态机) │
│ retrieval/ 前置理解 → 多路召回 → RRF 融合 → 重排 → 引用 → 生成 │
└───────────────────────────────┬───────────────────────────────┘
│
┌──────────────────────── 存储与模型层 ────────────────────────────┐
│ MySQL 业务元数据 / 分块原文 / 审批流 / 审计日志 │
│ Elasticsearch kb_chunks 索引(BM25 全文 + 密级过滤) │
│ Milvus kb_chunks 集合(HNSW/COSINE 向量 + 密级过滤) │
│ Ollama 提供大模型服务 │
└───────────────────────────────────────────────────────────────┘
```
分层说明
| 层次 | 选型 |
| --- |--------------------------------------------------------------------------|
| Web 框架 | FastAPI + Uvicorn + Jinja2 模板 + 原生 JS 前端 |
| 关系数据库 | MySQL 8.0(业务元数据 / 审批 / 审计),SQLAlchemy 2.x + PyMySQL |
| 全文检索 | Elasticsearch 8.x(BM25,中文分词 + 密级 filter) |
| 向量检索 | Milvus 2.4(HNSW + COSINE,密级 filter 表达式) |
| 模型服务 | 本地 Ollama 部署,0成本(适合自己学习) |
| 文档解析 | pdfplumber / pypdf、python-docx、openpyxl、BeautifulSoup + lxml、markdownify |
| 中文分词 | Elasticsearch IK 分词插件(ik_max_word 索引 / ik_smart 搜索) |
### 1.3 项目结构
```
enterprise_kb/
├── app/
│ ├── core/ 配置、密级/角色/状态常量、安全、错误、日志
│ ├── db/ SQLAlchemy 模型、会话、建表与内置账号
│ ├── schemas/ Pydantic 请求/响应模型
│ ├── clients/ MySQL(DB) / ES / Milvus / Ollama 客户端
│ ├── pipeline/ 文档解析 → 清洗降噪 → 分块 → 入库流水线
│ ├── retrieval/ 前置理解、多路召回、RRF 融合、重排、检索服务
│ ├── services/ 文档、审批、审计、用户领域服务
│ ├── api/ REST 接口(auth/documents/search/approval/audit/admin/system)
│ ├── web/ Jinja2 模板、静态资源、页面路由
│ └── main.py 应用入口
├── scripts/ 初始化与验证脚本
├── tests/ 单元测试
├── docs/ 文档
├── docker-compose.yml docker部署编排
└── init.sh / start.sh 初始化、启动脚本
```
### 1.4 数据模型
#### MySQL(库 `kb`,utf8mb4)
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `kb_user` | 用户与密级 | `username` `role` `clearance` `department` `is_active` |
| `kb_document` | 文档主表 | `doc_no` `title` `level` `status` `version` `summary` `chunk_count` `created_by_name` `updated_by_name` `created_at` `updated_at` `published_at` `error` |
| `kb_chunk` | 分块原文与元数据 | `chunk_uid` `doc_id` `chunk_index` `section` `char_count` `text` |
| `kb_approval` | 审批单 | `request_no` `action` `target_id` `level_required` `payload` `status` `current_step` `total_steps` `requester_name` `approver_name` `decided_at` |
| `kb_approval_record` | 审批步骤流水 | `approval_id` `step` `actor_name` `action` `comment` `created_at` |
| `kb_audit_log` | 审计日志 | `trace_id` `actor_*` `action` `resource_*` `level` `result` `detail` `ip` `user_agent` `created_at` |
#### Elasticsearch 索引 `kb_chunks`
`chunk_uid(keyword)` `doc_id(integer)` `doc_no(keyword)` `doc_title(text, ik_analyzer)`
`level(keyword)` `section(text + raw.keyword)` `chunk_index(integer)` `tags(keyword)`
`department(keyword)` `status(keyword)` `created_at(date)` `text(text, ik_analyzer)`
自定义分析器 `ik_analyzer` = `ik_max_word` tokenizer + `lowercase` + `cjk_width`(索引时最细粒度切分);
搜索分析器 `ik_search_analyzer` = `ik_smart` tokenizer + `lowercase` + `cjk_width`(检索时智能粗粒度切分)。
密级过滤通过 `terms: {level: [...]}` 实现;`number_of_replicas=0`(单节点部署)。
#### Milvus 集合 `kb_chunks`
`chunk_uid(VARCHAR, 主键)` `doc_id(INT64)` `doc_no(VARCHAR)` `doc_title(VARCHAR)`
`level(VARCHAR)` `section(VARCHAR)` `chunk_index(INT64)` `text(VARCHAR)` `vector(FLOAT_VECTOR, dim=1024)`
索引:`HNSW`,度量 `COSINE`,参数 `{"M":16,"efConstruction":200}`,检索 `ef=128`。
密级过滤通过 `filter` 表达式 `level in ["S","A",...]` 实现,**在库内完成、不落应用层**。
---
---
## 2. 部署
### 2.1 方式一:Docker Compose
```bash
cd kb_system
docker compose up -d # 拉起 MySQL / ES / Milvus(etcd+minio) / Ollama
docker compose ps # 等待各组件 healthy
```
`docker-compose.yml` 已包含 MySQL 8.0、Elasticsearch 8.x、etcd、MinIO、Milvus Standalone、
Ollama 六个服务及数据卷;Milvus 依赖 etcd 与 MinIO 自动编排。
### 2.2 方式二:使用已有组件
若内已有 MySQL / ES / Milvus / Ollama 集群,仅需修改 `.env`:
```ini
MYSQL_HOST=<主机> MYSQL_PORT=3306 MYSQL_USER=<用户> MYSQL_PASSWORD=<密码> MYSQL_DB=<数据库>
ES_HOSTS=http://<主机>:9200 # 集群多节点用逗号分隔
ES_USERNAME=<用户> ES_PASSWORD=<密码> # 无认证留空
MILVUS_HOST=<主机> MILVUS_PORT=19530 MILVUS_URI= # 连接 Standalone/集群时留空
OLLAMA_BASE_URL=http://<主机>:11434
```
**ES 版本要求**:应用依赖的 Python 客户端为 8.x,服务端必须为 ES 8.x。
若使用 ES 9.x,需同步将 `requirements.txt` 中的 `elasticsearch` 升级到 9.x 并调整兼容头。
**Milvus 部署形态选择**:
| `.env` 配置 | 部署形态 | 适用场景 |
| --- | --- | --- |
| `MILVUS_URI=`(留空) | Standalone / 集群(`MILVUS_HOST:MILVUS_PORT`) | 生产 |
| `MILVUS_URI=./data/milvus_kb.db` | 官方嵌入式模式(本地数据文件) | 单机开发 / 无独立 Milvus 服务 |
## 3. 初始化
```bash
# 准备需要的模型
ollama pull qwen3.5:9b
ollama pull qwen3-embedding:latest
# 数据库初始化脚本
./init.sh
```
---
## 4. 启动与停止
### 4.1 启动
```bash
# Linux / macOS 一键启动
./start.sh
```
启动日志出现 `Uvicorn running on http://0.0.0.0:5000` 即成功。
### 4.2 停止
前台 `Ctrl + C`;后台运行用 `pkill -f "uvicorn app.main:app"`。
### 4.3 健康检查
```bash
curl http://127.0.0.1:8000/api/health
```
---
## 5. 内置账号
| 用户名 | 初始密码 | 角色 | 密级 | 部门 |
| --- | --- | --- | --- | --- |
| `admin` | `admin123` | 系统管理员 | S | 系统管理部 |
| `approver` | `approver123` | 审批人 | S | 保密管理部 |
| `editor` | `editor123` | 知识编辑 | B | 研发中心 |
| `viewer` | `viewer123` | 普通用户 | D | 市场部 |
### 角色权限矩阵
| 能力 | admin | approver | editor | viewer |
| --- | --- | --- | --- | --- |
| 检索(≤ 自身密级) | ✅ | ✅ | ✅ | ✅ |
| 上传 / 更新 / 删除文档 | ✅ | — | ✅ | — |
| 发起跨密级授权申请 | ✅ | ✅ | ✅ | ✅ |
| 处理审批 | ✅ | ✅ | — | — |
| 查看全量审计 | ✅ | ✅ | — | — |
| 用户与密级管理 | ✅ | — | — | — |
| 读取任意密级文档 | ✅ | ✅ | — | — |
---
## 6. 系统功能
| 能力 | 说明 |
| --- | --- |
| 文档管理 | 12 类格式解析入库,支持新增、更新(版本递增)、下载、分块查看、删除 |
| 入库流水线 | 可恢复状态机:`received → parsing → chunked → embedded → indexed → published` |
| 密级体系 | S/A/B/C/D/E 六级,文档记录创建人/更新人与时间;B 级及以上发布需审批 |
| 混合检索 | BM25 多查询路 + 向量多查询路,RRF 融合后重排,结果附**原文引用** |
| 前置优化 | 查询改写、子问题拆分、意图识别(6 类)、关键词提取 |
| 密级管控 | 过滤在检索边界内完成(ES terms filter / Milvus filter expr),绝不"先全量后过滤" |
| 审批流 | 5 类审批动作 + 完整审批页面,审批通过后自动续跑被拦截的流程 |
| 审计 | 14 类动作全量留痕(谁/何时/对什么/结果/密级/IP/UA/明细),支持查询统计与 CSV 导出 |
---
### 保密等级体系
| 等级 | 中文名 | 敏感度分值 | 说明 |
| --- | --- | --- | --- |
| S | 绝密 | 5 | 最高 |
| A | 机密 | 4 | |
| B | 秘密 | 3 | |
| C | 内部受限 | 2 | |
| D | 内部 | 1 | |
| E | 公开 | 0 | 默认等级 |
### 检索时序
```
用户提问
└─ 前置理解:改写 / 子问题拆分 / 意图识别 / 关键词(Ollama)
└─ 权限解析:allowed = ≤ 用户密级;blocked = > 用户密级
└─ 跨密级探测:ES count(blocked 密级 且与问题相关) > 0 ?
├─ 是 → 创建「跨密级检索授权」审批单 → 返回 approval_required + 单号
│ 审批通过后携带 approval_no 重新检索 → 放行至授权密级
└─ 否 → 继续
└─ 多路召回(每条查询变体):ES BM25 × N + Milvus 向量 × N
└─ RRF 融合 → 重排(Ollama listwise)→ Top-N
└─ 组装原文引用 citations → 生成答案(每条结论带 [编号])→ 写审计
```
### 6.1 登录/退出
1. 浏览器打开 `http://127.0.0.1:5000`,自动跳转 `/login`;
2. 输入用户名与密码,点击「登录」;
3. 成功后进入工作台,令牌同时写入 `HttpOnly` Cookie(浏览器会话)与前端存储(API 调用)。
登录失败提示「用户名或密码错误」,同时写入审计(`login` / `denied`)。连续失败可结合审计排查。
```
# 核心代码
[routes_auth.py](app/api/routes_auth.py)
```
### 6.2 工作台 `/`
展示当前用户、密级、角色与各功能入口,可快速跳转文档管理、智能检索、审批中心、审计日志、
管理后台。
```
# 核心代码
[dashboard.html](app/web/templates/dashboard.html)
```
### 6.3 文档管理 `/documents`
**上传文档**
1. 点击「上传文档」;
2. 选择本地文件(支持 pdf/docx/xlsx/xlsm/csv/txt/md/markdown/json/log/html/htm);
3. 填写标题、选择**保密等级**(默认 E)、部门、标签;
4. 提交后:
- 等级为 **C/D/E** → 直接进入入库流水线,状态依次推进到 `published`;
- 等级为 **S/A/B** → 状态变为 `pending_approval`,需到审批中心处理后方可检索。
**列表与筛选**
支持按标题/文档号关键词、密级、状态过滤与分页;列表仅显示**当前用户可见密级**的文档
(`admin` / `approver` 可见全部)。
**查看分块**:点击「分块」查看该文档切分后的每个 chunk(序号、章节、字符数、原文),
用于确认解析与切分质量。
**下载**:点击「下载」获取原始文件,操作写入审计(`doc.download`)。
**更新**:选择文档 →「更新」,可替换文件或修改标题/密级/部门/标签;
版本号自增,旧版本索引自动失效;S/A/B 级更新同样进入审批。
**删除**:点击「删除」,MySQL 记录、ES 索引与 Milvus 向量同步清除。
```
# 核心代码
页面操作:[routes_documents.py](app/api/routes_documents.py)
入库操作:[ingest.py](app/pipeline/ingest.py)
```
### 6.4 智能检索 `/search`
1. 在输入框输入自然语言问题(如"差旅报销标准是多少");
2. 可选参数:结果条数、是否生成答案、是否启用前置理解;
3. 点击「检索」,页面展示:
- **前置理解卡片**:改写后的问句、识别到的意图、拆分出的子问题、提取的关键词;
- **答案区**:模型基于资料生成、带 `[编号]` 引用标注的答案;
- **命中列表**:每条显示标题、密级、章节、来源(`bm25` / `vector`)与得分;
- **原文引用**:每条命中对应的原文片段,可对照核对;
- **trace_id 与耗时**:便于与审计日志关联排障。
**跨越密级时的处理**
当检索命中高于自己密级的资料时,系统**不会返回该内容**,而是:
1. 页面提示「命中更高密级资料,需提交跨密级检索审批」并给出**审批单号**(形如 `AP20261031xxxxxx`);
2. 到「审批中心」查看进度;
3. 审批通过后,携带该单号重新检索即可放行至授权密级(在检索框填入审批单号后检索)。
#### 混合检索、多路召回与重排
| 环节 | 实现 |
| --- | --- |
| 多路召回 | 对**每组查询变体**(改写句 + 各子问题)分别执行 ES BM25 召回与 Milvus 向量召回,得到 `bm25#i` / `vector#i` 多条召回路 |
| 融合 | RRF(Reciprocal Rank Fusion,`RRF_K=60`)跨路融合,取候选 `max(top_k*2, 30)` |
| 重排 | `retrieval/rerank.py` 基于本地模型对候选做 listwise 重排,输出 `RERANK_TOP_N=8` |
| 原文引用 | 每条命中生成 `Citation`:`chunk_uid / doc_no / doc_title / level / section / chunk_index / score / text`,可回溯到 MySQL 中的分块原文 |
| 答案生成 | 以引用块(受 `CONTEXT_MAX_CHARS=6000` 预算约束)拼装上下文,要求模型"仅依据资料作答,关键结论标注 [编号],资料不足则明确说明",从机制上抑制幻觉 |
| 检索参数 | `RETRIEVAL_TOP_K=20`(每路召回)、`RERANK_TOP_N=8`(最终条数) |
#### 检索前置优化
| 能力 | 输出字段 | 说明 |
| --- | --- | --- |
| 查询改写 | `rewritten` | 补全省略、消除指代、口语转书面,得到更适合检索的问句 |
| 子问题拆分 | `sub_questions` | 多目标问题拆为 1–4 个可独立检索的子问题 |
| 意图识别 | `intent` / `intent_label` | `fact / summary / compare / process / definition / other` 六类 |
| 关键词提取 | `keywords` | 模型抽取 3–8 个关键词;模型未给出时用 ES IK 分词兜底提取 |
可通过 `understand=false` 关闭前置优化(用于排障或纯关键词检索场景)
### 6.5 审批中心 `/approvals`
- **待办 / 我发起的 / 全部** 三个视图切换;
- 点击某条记录查看详情:申请动作(新建/更新/密级变更/跨密级授权)、目标、申请密级、
申请理由、payload 明细、**审批步骤流水**(谁在何时做了什么);
- 审批人可点击「通过」或「驳回」并填写意见;
- **通过后系统自动续跑流程**:
- 文档类 → 触发对应文档继续入库并推进到 `published`;
- 检索类 → 该单号即成为跨密级检索凭证;
- 若下游流程受阻(例如模型服务未启动),审批结论仍然生效,失败原因记录在审批单的
`payload.flow_error` 字段与文档 `error` 字段中,排障后重新提交该文档即可。
**审批动作(5 类)**:`create`(新建发布)、`update`(文档更新)、`level_change`(密级变更)、
`access_request`(跨密级检索授权)、`delete`(删除)。
**审批状态(4 类)**:`pending` → `approved` / `rejected` / `canceled`。
**审批流机制**:
1. 触发:文档新增/更新且密级 ≥ B,或用户检索命中高于自身密级的资料;
2. 建单:生成单号 `AP{YYYYMMDD}{6位随机}`,记录申请人、目标、申请密级、理由、结构化 payload;
3. 处理:审批人在**审批中心页面**通过/驳回并填写意见,每次操作写入 `kb_approval_record` 步骤流水;
4. **审批通过后流程继续**:
- 文档类审批 → 自动续跑入库流水线,文档状态推进到 `published`;
- 检索类审批 → 用户携带 `approval_no` 重新发起检索,`_resolve_levels` 校验该单已通过后
临时放行至授权密级;
5. **续跑失败的容错**:审批结论先落库生效,若后续流水线失败(如模型服务不可用),
失败原因写入审批单 `payload.flow_error` 并在文档 `error` 字段体现,**不会回滚已生效的审批结论**。
> 跨密级探测使用 `ESClient.count_relevant()`:只返回"相关条数",**不返回任何高密级正文**,
> 因此申请人不会通过审批提示泄露受控内容。
### 6.6 审计日志 `/audit`
- 筛选条件:操作人、动作、资源类型、密级、结果、关键词、时间区间;
- 列表展示时间、操作人(角色/密级)、动作、资源、结果、IP、User-Agent、明细;
- 「统计」区域展示按动作 / 结果 / 密级的分组计数与总量;
- 「导出 CSV」下载全量(BOM 头,Excel 直接可读);
- 普通用户只能看到自己的记录。
`kb_audit_log` 记录字段:`trace_id`、操作人(id/姓名/角色/密级)、动作、资源类型/ID/名称/密级、
结果、明细 JSON、IP、User-Agent、时间。
**审计动作(14 类)**:
| 分类 | 动作 |
| --- | --- |
| 认证 | `login` / `logout` |
| 文档 | `doc.upload` / `doc.update` / `doc.delete` / `doc.publish` / `doc.download` |
| 检索 | `search` / `retrieve.blocked`(越权命中拦截) |
| 审批 | `approval.submit` / `approval.approve` / `approval.reject` |
| 管理 | `user.manage` / `level.manage` |
- 查询:多条件过滤(操作人、动作、资源类型、密级、结果、关键词、时间区间)+ 分页;
- 统计:按动作 / 结果 / 密级分组计数 + 总量;
- 导出:`GET /api/audit/export` 输出带 BOM 的 CSV,便于 Excel 打开;
- **权限**:仅 `admin` / `approver` 可见全量审计,普通用户只能看自己的记录。
### 6.7 管理后台 `/admin`
- **用户管理**:新增用户(用户名、密码、角色、密级、部门);启用/停用、修改角色与密级、
重置密码;
- **运行配置**:查看当前密级定义、角色定义、模型名、分块与检索参数、审批开关;
- **组件健康**:MySQL / ES / Milvus / Ollama 逐项状态与版本明细。
---
## 7、接口清单
所有接口挂载在 `/api` 前缀下,鉴权支持 `Authorization: Bearer ` 与 Cookie 两种方式。
### 7.1 系统与认证
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 全局健康检查(MySQL/ES/Milvus/Ollama 逐项状态) |
| POST | `/api/auth/login` | 登录,返回 JWT 并下发 HttpOnly Cookie |
| POST | `/api/auth/logout` | 登出并清除 Cookie |
| GET | `/api/auth/me` | 当前登录用户信息 |
### 7.2 文档
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/documents/meta` | 可用密级、支持的文件扩展名 |
| POST | `/api/documents/upload` | 上传文档(multipart:file + title + level + department + tags) |
| GET | `/api/documents` | 文档列表(keyword/level/status/分页,按可见密级过滤) |
| GET | `/api/documents/{id}` | 文档详情(越权返回 403) |
| GET | `/api/documents/{id}/chunks` | 分块列表(含原文) |
| PUT | `/api/documents/{id}` | 更新文档(multipart,可换文件 / 改密级,S/A/B 触发审批) |
| DELETE | `/api/documents/{id}` | 删除文档(ES + Milvus + MySQL 同步失效) |
| GET | `/api/documents/{id}/download` | 下载原始文件(写审计) |
### 7.3 检索与审批
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/search` | 混合检索:`{query, top_k?, rerank_top_n?, levels?, understand?, generate?, approval_no?}` → 命中、引用、答案、`approval_required`、`approval_no`、`trace_id`、耗时 |
| POST | `/api/approvals` | 创建审批单 |
| GET | `/api/approvals` | 审批列表(scope/status/分页) |
| GET | `/api/approvals/{id}` | 审批详情(含步骤流水) |
| POST | `/api/approvals/{id}/decision` | 审批处理:`{decision: approve/reject/cancel, comment}` |
### 7.4 审计与管理
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/audit` | 审计查询(多条件 + 分页) |
| GET | `/api/audit/stats` | 审计统计(按动作/结果/密级) |
| GET | `/api/audit/export` | 导出 CSV |
| GET | `/api/admin/users` | 用户列表 |
| POST | `/api/admin/users` | 新建用户(角色 + 密级) |
| PUT | `/api/admin/users/{id}` | 修改用户(角色/密级/启停/重置密码) |
| GET | `/api/admin/config` | 当前运行配置(密级、角色、模型、检索参数) |
| GET | `/api/admin/health` | 组件健康明细 |
### 7.5 Web 页面
| 路径 | 页面 |
| --- | --- |
| `/login` | 登录 |
| `/` | 工作台 |
| `/documents` | 文档管理 |
| `/search` | 智能检索 |
| `/approvals` | 审批中心 |
| `/audit` | 审计日志 |
| `/admin` | 管理后台 |
### 7.6 错误码
| HTTP | code | 触发场景 |
| --- | --- | --- |
| 400 | `BAD_REQUEST` | 参数错误(如非法密级、不支持的文件类型) |
| 401 | `UNAUTHORIZED` | 未登录 / 令牌无效或过期 |
| 403 | `PERMISSION_DENIED` | 越权访问文档、非授权角色操作 |
| 404 | `NOT_FOUND` | 文档 / 审批单不存在 |
| 409 | `CONFLICT` | 状态冲突(如重复审批) |
| 500 | `INTERNAL_ERROR` | 处理失败(流水线异常) |
| 503 | `DEPENDENCY_UNAVAILABLE` | MySQL / ES / Milvus / Ollama 任一不可用 |
---
## 8. 关键参数
| 参数 | 默认值 | 含义 |
| --- | --- | --- |
| `CHUNK_SIZE` / `CHUNK_OVERLAP` | 600 / 80 | 分块长度与重叠字符数 |
| `MIN_CHUNK_CHARS` | 20 | 小于该值的碎片在章节内合并 |
| `MAX_UPLOAD_MB` | 100 | 单文件上传上限 |
| `EMBED_DIM` | 1024 | bge-m3 向量维度 |
| `RETRIEVAL_TOP_K` | 20 | 每路召回的候选数 |
| `RERANK_TOP_N` | 8 | 重排后最终保留条数 |
| `RRF_K` | 60 | RRF 融合平滑常数 |
| `CONTEXT_MAX_CHARS` | 6000 | 送入生成模型的上下文预算 |
| `PUBLISH_APPROVAL_MIN_LEVEL` | `B` | 需发布审批的起始密级(S/A/B 需审批) |
| `APPROVAL_ENABLED` | `true` | 审批流总开关 |
| `MAX_AUTO_LEVEL` | `A` | 自动放行的最高密级上限 |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | 480 | 登录令牌有效期(分钟) |
---
## 9. REST API 使用示例
```bash
# 登录,保存 Cookie
curl -c cookie.txt -X POST http://127.0.0.1:8000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"editor","password":"editor123"}'
# 上传文档(S 级将进入审批)
curl -b cookie.txt -X POST http://127.0.0.1:8000/api/documents/upload \
-F 'file=@差旅制度.pdf' -F 'title=差旅报销制度' -F 'level=B' -F 'department=财务部' -F 'tags=[]'
# 混合检索
curl -b cookie.txt -X POST http://127.0.0.1:8000/api/search \
-H 'Content-Type: application/json' \
-d '{"query":"差旅报销标准","generate":true,"understand":true}'
# 凭审批单号重试跨密级检索
curl -b cookie.txt -X POST http://127.0.0.1:8000/api/search \
-H 'Content-Type: application/json' \
-d '{"query":"差旅报销标准","approval_no":"AP20261031ABCDEF"}'
# 审批通过
curl -b cookie.txt -X POST http://127.0.0.1:8000/api/approvals/1/decision \
-H 'Content-Type: application/json' -d '{"decision":"approve","comment":"同意"}'
```
---