# Ticket-Knowledge-System

**Repository Path**: developCat/ticket-knowledge-system

## Basic Information

- **Project Name**: Ticket-Knowledge-System
- **Description**: 基于Ruo-Yi,langchain的智能工单分配系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 车辆工单智能管理系统（Ticket-Knowledge-System）

> 一个包含 **工单管理系统（若依 RuoYi + Spring Boot）** 与 **车辆问题知识库助手（Python FastAPI + Milvus）** 两大子项目的完整系统。
> 工单系统负责业务流转与人机交互，知识库服务负责 AI 智能诊断（检索增强生成 + Agent 多轮会话），两者通过 REST API 异步协同，实现"提交工单 → AI 自动诊断 → 人工审批闭环"的智能化故障处理流程。

---

## 目录

- [一、项目简介](#一项目简介)
- [二、系统架构](#二系统架构)
- [三、项目结构](#三项目结构)
- [四、子项目一：工单管理系统](#四子项目一工单管理系统 )
- [五、子项目二：车辆问题知识库助手](#五子项目二车辆问题知识库助手)
- [六、核心业务流程](#六核心业务流程)
- [七、快速开始](#七快速开始)
- [八、环境依赖](#八环境依赖)
- [九、配置文件速查](#九配置文件速查)
- [十、接口文档汇总](#十接口文档汇总)
- [十一、测试](#十一测试)
- [十二、部署与运维](#十二部署与运维)
- [十三、常见问题](#十三常见问题)

---

## 一、项目简介

本项目面向**车辆（智驾）问题管理**场景，由两个子项目组成：

| 子项目 | 目录 | 技术栈 | 职责 |
| --- | --- | --- | --- |
| **工单管理系统** | `Ticket-Management-System/` | Java 17 + Spring Boot + Vue 3 | 工单生命周期管理（创建/提交/诊断/评审/关闭）、用户角色权限、事件审计流水、看板统计 |
| **车辆问题知识库助手** | `zhishiku/` | Python 3.10 + FastAPI + Milvus + LLM | AI 智能诊断：向量检索相似历史问题，结合分级策略/标签体系/责任映射，输出结构化诊断结果；支持 Agent 多轮会话与邮件补充 |

**系统能力概览：**

- 📋 **工单全流程管理**：草稿 → 提交 → AI 诊断 → 人工审批 → 处理 → 关闭/重开，全程事件流水可追溯
- 🤖 **AI 智能诊断**：基于 Milvus 向量库检索相似历史问题，由大模型（DeepSeek / Qwen）输出问题分级（A/B/C）、三级标签、责任领域与责任工程师
- 🔄 **Agent 多轮会话**：描述不完整时自动发送澄清邮件，支持多轮补充与管理员审批/驳回
- ⚙️ **策略配置中心**：分级策略、责任映射、完整性规范支持 MySQL 入库与版本管理、定时生效
- 🔐 **双系统鉴权互通**：若依 JWT 与 FastAPI 兼容（HS256/HS512），工单系统可直接透传 token 调用知识库接口

---

## 二、系统架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                        工单管理系统（前端）                           │
│          ruoyi-ui (Vue 3 + Vite + Element Plus)                     │
│          http://localhost:80                                        │
└───────────────────────────────┬─────────────────────────────────────┘
                                │  /dev-api 代理
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    工单管理系统（后端）                              │
│     ruoyi-admin (Spring Boot, :8080)                                │
│     工单状态机 · 角色权限 · 事件流水 · 异步诊断调用                    │
├─────────────────────────────────────────────────────────────────────┤
│  MySQL (ry 主库 + ry_ticket 业务库)    Redis 缓存    Quartz 定时任务  │
└───────────────────────────────┬─────────────────────────────────────┘
                                │  /fast-api 代理 · JWT 透传
                                │  POST /agent/diagnose（异步 @Async）
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    车辆问题知识库助手（zhishiku）                     │
│        FastAPI (:8000) · Agent 会话编排 · 邮件通知                    │
├──────────────┬──────────────┬──────────────┬────────────────────────┤
│  Milvus 向量库 │  LLM (DeepSeek│  DashScope   │  MySQL (可选)          │
│  vehicle_kb  │  / Qwen)     │  Embedding   │  配置版本管理           │
│  相似问题检索  │  分级/标签生成 │  qwen3.7     │  config_* 五张表        │
└──────────────┴──────────────┴──────────────┴────────────────────────┘
```

**协同流程要点：**

1. 申报人在工单系统创建工单并提交诊断；
2. 后端异步（`@Async` 线程池）携带若依 JWT 调用 FastAPI `POST /agent/diagnose`；
3. FastAPI 完成向量检索 + LLM 推理 + 规则映射，返回会话结果；
4. 若描述不完整 → 邮件通知申报人补充 → `POST /agent/continue` 继续会话；
5. 诊断完成 → 管理员审批/驳回 → 结果写回工单字段，工单进入处理或关闭。

---

## 三、项目结构

```
Ticket-Knowledge-System/
├── README.md                       # 本文档
├── Ticket-Management-System/       # 子项目一：工单管理系统（若依 RuoYi）
│   ├── bin/                        # 后端 jar 部署脚本（clean/package/run）
│   ├── doc/                        # 接口与需求文档（含知识库对接参考）
│   ├── sql/                        # 数据库初始化脚本
│   ├── ruoyi-admin/                # 启动模块（SpringBoot 入口）
│   ├── ruoyi-common/               # 通用工具模块
│   ├── ruoyi-framework/            # 核心框架（安全、缓存、Web）
│   ├── ruoyi-system/               # 系统业务模块（用户、角色、工单等）
│   ├── ruoyi-generator/            # 代码生成模块
│   ├── ruoyi-quartz/               # 定时任务模块
│   ├── ruoyi-ui/                   # 前端工程（Vue3 + Vite + Element Plus）
│   ├── pom.xml                     # 父 Maven 工程
│   ├── ry.bat / ry.sh              # jar 启停脚本
│   └── API.md                      # 工单系统接口文档
└── zhishiku/                       # 子项目二：车辆问题知识库助手（FastAPI）
    ├── docker-compose.yml          # 应用编排（仅 app 服务）
    ├── Dockerfile                  # 应用镜像（python:3.10-slim）
    ├── requirements.txt            # Python 依赖
    ├── .env.example                # 环境变量模板
    ├── config/                     # 知识库/策略配置（YAML）
    │   ├── schema.yaml             # 字段映射 + Milvus 集合定义
    │   ├── grading_policy.yaml     # 问题分级策略（A/B/C）
    │   ├── mapping.yaml            # 责任领域/工程师映射
    │   └── clarity_spec.yaml       # 描述完整性规范
    ├── data/                       # 知识库数据（sample_kb.csv 等）
    ├── docs/                       # 项目文档（学习指南、API 对接契约）
    ├── scripts/                    # 辅助脚本
    ├── tests/                      # 单元/契约测试
    └── src/
        ├── app.py                  # FastAPI 入口
        ├── core/                   # 配置、日志、JWT 安全
        ├── config/                 # MySQL 配置库（版本管理）
        ├── milvus/                 # Milvus 连接与向量读写
        ├── embedding/              # DashScope 向量化
        ├── llm/                    # LLM 封装（OpenAI 兼容）
        ├── ingestion/              # Excel/CSV 导入
        ├── agent/                  # Agent 会话编排（状态机）
        ├── notification/           # SMTP 邮件通知
        ├── service/                # 检索 + 生成 + 映射编排
        ├── persistence/            # 结果落库抽象
        ├── prompts/                # 系统提示词模板
        └── api/                    # 路由与 Pydantic 模型
```

---

## 四、子项目一：工单管理系统

详细文档见 [`Ticket-Management-System/README.md`](Ticket-Management-System/README.md)。

### 4.1 技术栈

| 层次 | 技术 |
| --- | --- |
| 后端 | JDK 17、Spring Boot 4.0.6、若依 3.9.2、MyBatis、Druid 连接池、PageHelper 分页 |
| 安全 | Spring Security + JWT（Token 鉴权） |
| 任务 | Quartz 定时任务、SpringDoc（OpenAPI 3） |
| 前端 | Vue 3、Vite 6、Element Plus、Pinia |
| 数据 | MySQL 8（主库 `ry` + 业务库 `ry_ticket`）、Redis 5+ |

### 4.2 核心业务

- **工单主状态机**：`DRAFT（草稿）→ PENDING（待处理）→ IN_PROGRESS（处理中）→ PENDING_REVIEW（待复核）→ CLOSED（已关闭）`，已关闭工单可 `REOPENED` 回到待处理
- **智能诊断子状态机**：`PENDING → RUNNING → DONE / FAILED / SKIPPED`（由 FastAPI Agent 异步写回）
- **Agent 会话状态**：`WAITING_FOR_SUPPLEMENT / WAITING_FOR_REVIEW / COMPLETED / EXPIRED / ESCALATED / FAILED`
- **事件流水**：每次流转落 `ticket_event` 表（`CREATED / SUBMITTED / REVIEWED / PROGRESS / SUBMITTED_REVIEW / CLOSED / REOPENED / DIAGNOSED / AGENT_APPROVED / AGENT_SUPPLEMENTED`，其中 `DIAGNOSED` 为手动重新诊断、`AGENT_APPROVED`/`AGENT_SUPPLEMENTED` 为 Agent 流程写入）
- **角色权限**：`admin`（管理员，全部动作）、`engineer`（工程师，更新进度/提交复核）、`reporter`（申报人，创建/提交/补充）、`viewer`（只读）

### 4.3 默认账号

| 用户名 | 密码 | 角色 | 说明 |
| --- | --- | --- | --- |
| `admin` | `admin123` | 超级管理员 | 全部权限，含 Agent 审批、关闭/重开/重新诊断 |
| `ry` | `admin123` | 测试员（common） | 默认普通角色；需在若依「角色管理」为其绑定「填报人(reporter)」后方可创建/提交工单 |

---

## 五、子项目二：车辆问题知识库助手

详细文档见 [`zhishiku/README.md`](zhishiku/README.md)。

### 5.1 技术栈

- **服务框架**：Python 3.10、FastAPI、Uvicorn
- **向量库**：Milvus `v2.4.13-hotfix`（etcd + MinIO 基础设施独立部署）
- **LLM**：OpenAI 兼容模式，默认 DeepSeek `deepseek-v4-flash`，可切换 Qwen `qwen3.7-max` 等
- **Embedding**：DashScope `qwen3.7-text-embedding`（1024 维，COSINE 度量）
- **数据持久化**：MySQL 8（配置版本管理）、JSONL（诊断结果落库）

### 5.2 核心功能

- **语义检索诊断**：`POST /diagnose` 接收问题描述，检索相似历史问题，输出 `grade（A/B/C）`、`tag_level1/2/3`、`responsible_domain`、`responsible_engineer`、`matched`
- **完整性检查**：`POST /check-clarity` 依据 `clarity_spec` 判定描述是否完整
- **Agent 会话诊断**：`POST /agent/diagnose` 多轮补充 + 澄清邮件 + 人工审批/驳回
- **配置中心**：`grading_policy` / `mapping` / `clarity_spec` 三类配置的 MySQL 入库、版本管理与定时生效
- **知识库导入**：支持 CSV / Excel（`.csv` / `.xlsx` / `.xls`，单文件 ≤50MB），表头映射由 `config/schema.yaml` 配置

### 5.3 诊断结果示例

```json
{
  "grade": "A",
  "tag_level1": "智驾系统",
  "tag_level2": "NOA",
  "tag_level3": "功能异常",
  "responsible_domain": "智能驾驶域",
  "responsible_engineer": "张伟",
  "matched": true,
  "references": [
    { "content": "NOA 高速路段自动退出无提示", "score": 0.92 }
  ],
  "record_id": null
}
```

---

## 六、核心业务流程

### 6.1 端到端流程

```
[申报人 reporter]
   ① 创建工单 (POST /ticket, status=DRAFT)
        │  必填: description, vin, problemId, probability, adLevel, notifyEmail
        ▼
   ② 编辑/补充草稿 (PUT /ticket)
        │
        ▼
   ③ 提交诊断 (POST /ticket/{id}/submit, 校验 notifyEmail 非空)
        │   status → PENDING, diagnoseStatus → RUNNING
        │   ── 异步调用 FastAPI /agent/diagnose（透传 JWT）──┐
        ▼                                                    │
[知识库助手 Agent 后台]                                          │
   ④ 解析描述 → 返回会话响应 (conversation_id / agent_status / diagnosis) ◄┘
        │
        ├─ WAITING_FOR_SUPPLEMENT → 邮件补充 / POST /agent/continue（最多 3 轮）
        │
        ├─ WAITING_FOR_REVIEW / COMPLETED → 管理员审批 POST /agent/sessions/{conversation_id}/approve
        │       ├─ 驳回 → 回退补充
        │       └─ 通过 → 写回 grade/tag/responsible 等诊断字段（diagnoseStatus=DONE）
        │
        └─ EXPIRED / ESCALATED / FAILED → diagnoseStatus=FAILED，可重新诊断
[后续流转（正常业务闭环）]
   ⑤ 管理员复核 (POST /ticket/{id}/review, PENDING → IN_PROGRESS)
   ⑥ 工程师更新进度 (POST /ticket/{id}/progress) / 提交复核 (PENDING_REVIEW)
   ⑦ 关闭 (POST /ticket/{id}/close) / 重开 (CLOSED → PENDING) / 删除
```

### 6.2 关键约束

- **邮箱必填**：无 `notifyEmail` 无法提交诊断（Agent 接口强制要求）
- **异步解耦**：诊断在独立线程执行，提交接口立即返回，避免 LLM 慢调用阻塞前端
- **失败可重入**：`FAILED` 工单可通过"重新诊断"重跑
- **重开即重诊**：重开（reopen）会同时将诊断状态重置为 `PENDING` 并重新触发 AI 诊断
- **补充仅限本人**：补充描述（supplement）仅工单创建者本人（或 admin）可操作
- **权限隔离**：流转动作按角色鉴权，非 admin 不可关闭/重开/删除

---

## 七、快速开始

### 7.1 顺序启动（推荐）

> 总启动顺序：**Milvus → zhishiku（FastAPI）→ 数据库初始化 → 工单后端 → 工单前端**

#### 第 1 步：启动 Milvus 基础设施

```powershell
# 进入你的 Milvus compose 目录（etcd + minio + milvus，独立于本项目）
cd D:\developTools\Milvus
.\start-milvus.ps1        # 按序启动 etcd -> minio -> milvus
```

> ⚠️ **重要**：`milvus` 服务为 `restart: "no"`，必须通过脚本按序启动，等待依赖健康后再拉起 milvus，否则元数据可能损坏、collection 丢失。镜像须为 `v2.4.13-hotfix` 或更高版本。

#### 第 2 步：启动知识库助手（zhishiku）

```powershell
cd d:\projects\Ticket-Knowledge-System\zhishiku
conda activate zhishiku
copy .env.example .env     # 填写 LLM_API_KEY / DASHSCOPE_API_KEY 等
# 首次需导入知识库
python -m src.ingestion.import_kb --file data/sample_kb.csv --clear
# 启动服务
uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload
# 验证: http://localhost:8000/docs
```

#### 第 3 步：初始化工单系统数据库

```powershell
cd d:\projects\Ticket-Knowledge-System\Ticket-Management-System
# 创建 MySQL 库 ry 与 ry_ticket（utf8mb4），按顺序执行 sql/ 目录脚本：
#   ry_20260417.sql → ry_ticket.sql / ry_ticket_*.sql → quartz.sql
```

#### 第 4 步：启动工单系统后端

```powershell
mvn -pl ruoyi-admin -am spring-boot:run
# 或打包运行: mvn clean package -DskipTests && java -jar ruoyi-admin/target/ruoyi-admin.jar
# 接口文档: http://localhost:8080/swagger-ui.html
```

#### 第 5 步：启动工单系统前端

```powershell
cd ruoyi-ui
npm install
npm run dev                # 默认 http://localhost:80
```

#### 第 6 步：登录验证

- 工单系统：`admin / admin123`（管理员）或 `ry / admin123`（测试员）
- 知识库助手：`POST /auth/login`，账号见 `ADMIN_USERNAME` / `ADMIN_PASSWORD`

---

## 八、环境依赖

### 8.1 工单管理系统

| 依赖 | 版本/要求 | 说明 |
| --- | --- | --- |
| JDK | 17 | `JAVA_HOME` 必须指向 JDK 17 |
| Maven | 3.6+ | 后端构建 |
| Node.js | 18+ | 前端 `ruoyi-ui` |
| MySQL | 8.x | `ry`、`ry_ticket` 两个库 |
| Redis | 5+ | 本地 6379，无密码 |

### 8.2 知识库助手

| 依赖 | 版本/要求 | 说明 |
| --- | --- | --- |
| Python | 3.10 | 建议 conda 虚拟环境 `zhishiku` |
| Milvus | v2.4.13-hotfix+ | 独立 compose 部署（etcd + MinIO + Milvus） |
| LLM API | — | DeepSeek 等 OpenAI 兼容服务（`LLM_API_KEY`） |
| DashScope API | — | 通义千问向量化（`DASHSCOPE_API_KEY`） |
| MySQL | 8.x（可选） | 配置版本管理（不配置则回退 YAML） |

---

## 九、配置文件速查

### 9.1 工单管理系统

| 配置项 | 位置 | 默认值 |
| --- | --- | --- |
| 后端端口 | `ruoyi-admin/src/main/resources/application.yml` | 8080 |
| 前端端口 | `ruoyi-ui/vite.config.js` | 80 |
| MySQL 主库 | `application-druid.yml` | `ry` / `root/123456` |
| MySQL 业务库 | `application-druid.yml` | `ry_ticket` / `root/123456` |
| Redis | `application.yml` | `localhost:6379` |
| FastAPI 地址 | `application.yml`（`ruoyi.fastapi.base-url`） | `http://localhost:8000` |
| 文件上传路径 | `application.yml`（`ruoyi.profile`） | `D:/ruoyi/uploadPath` |

### 9.2 知识库助手（`.env`，模板见 `.env.example`）

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `LLM_API_KEY` / `LLM_BASE_URL` | — | 大模型服务（OpenAI 兼容） |
| `DASHSCOPE_API_KEY` | — | Embedding 专用（DeepSeek 无 embedding，勿替换） |
| `MILVUS_HOST` | `host.docker.internal` | 本地开发用 `localhost` |
| `EMBEDDING_MODEL` | `qwen3.7-text-embedding` | 向量模型 |
| `LLM_MODEL` | `deepseek-v4-flash` | 生成模型 |
| `COLLECTION_NAME` | `vehicle_kb` | Milvus 集合名 |
| `JWT_SECRET_KEY` | `change-me` | 生产必须替换为随机强密钥 |
| `ADMIN_USERNAME` / `ADMIN_PASSWORD_HASH` | `admin` / — | 管理界面鉴权 |
| `AGENT_ENABLED` | `false` | 启用 Agent 诊断流程 |
| `EMAIL_ENABLED` / `SMTP_*` | — | SMTP 邮件通知 |
| `MYSQL_*` | — | 配置入库（可选） |

---

## 十、接口文档汇总

| 项目 | 在线文档 | 说明 |
| --- | --- | --- |
| 工单系统 | `http://localhost:8080/swagger-ui.html` | SpringDoc（OpenAPI 3） |
| 知识库助手 | `http://localhost:8000/docs` | Swagger UI |
| 工单系统接口说明 | `Ticket-Management-System/API.md` | 前后端接口对照 |
| 知识库对接参考 | `Ticket-Management-System/doc/zhishiku-ruoyi-api-reference.md` | 若依对接契约 |
| 知识库 API 契约 | `zhishiku/docs/` | 详细接口文档 |

### 10.1 工单系统核心接口

| 方法 | 路径 | 说明 | 权限 |
| --- | --- | --- | --- |
| POST | `/login` | 登录 | 公开 |
| GET | `/ticket/list` | 工单列表（分页/过滤） | 登录 |
| GET | `/ticket/{id}` | 工单详情 | 登录 |
| POST | `/ticket` | 新增工单（`submit=true` 直接提交，否则保存草稿） | reporter/admin/engineer |
| PUT | `/ticket` | 修改工单（仅草稿可改） | reporter/admin/engineer |
| POST | `/ticket/{id}/submit` | 提交草稿并触发 AI 诊断 | reporter/admin/engineer |
| POST | `/ticket/{id}/review` | 管理员复核（待处理 → 处理中） | admin |
| POST | `/ticket/{id}/progress` | 更新处理进度 | engineer/admin |
| POST | `/ticket/{id}/submit-review` | 提交复核（处理中 → 待复核） | engineer/admin |
| POST | `/ticket/{id}/close` | 关闭工单 | admin |
| POST | `/ticket/{id}/reopen` | 重开工单（已关闭 → 待处理） | admin |
| POST | `/ticket/{id}/rediagnose` | 重新触发 AI 诊断 | admin |
| POST | `/ticket/{id}/agent-approve` | Agent 诊断结果审批 | admin |
| POST | `/ticket/{id}/supplement` | 补充问题描述（触发再次诊断） | ticket:edit |
| DELETE | `/ticket/{ids}` | 批量删除工单 | admin |
| GET | `/ticket/dashboard` | 看板统计 | admin/viewer/reporter/engineer |

### 10.2 知识库助手核心接口

| 方法 | 路径 | 说明 | 鉴权 |
| --- | --- | --- | --- |
| GET | `/health` | 健康检查（Milvus 状态 + 知识库条数） | 公开 |
| POST | `/auth/login` | 管理员登录签发 JWT | 公开（限流） |
| GET | `/auth/me` | 当前管理员信息 | Bearer token |
| POST | `/diagnose` | 单次智能诊断 | Bearer token |
| POST | `/check-clarity` | 描述完整性检查 | Bearer token |
| POST | `/ingest` | 知识库导入（服务端路径） | 管理员 |
| POST | `/ingest/upload` | 知识库导入（文件上传，≤50MB） | 管理员 |
| POST | `/agent/diagnose` | Agent 会话诊断 | Bearer token |
| POST | `/agent/continue` | 补充描述继续会话 | 公开 |
| GET | `/agent/sessions/{conversation_id}` | 查询会话详情 | Bearer token |
| POST | `/agent/sessions/{conversation_id}/approve` | 审批/驳回诊断结果 | Bearer token |
| GET | `/config/{type}` | 查询配置当前生效版本 | 管理员 |
| GET | `/config/{type}/versions` | 配置版本列表 | 管理员 |
| GET | `/config/{type}/versions/{version}` | 指定版本详情 | 管理员 |
| POST | `/config/{type}` | 新增配置版本（入库 + 版本管理） | 管理员 |
| PUT | `/config/{type}/{version}/activate` | 激活指定版本（定时生效） | 管理员 |
| DELETE | `/config/{type}/versions/{version}` | 删除配置版本 | 管理员 |

> `type` 取值：`grading_policy`（分级策略）、`mapping`（责任映射）、`clarity_spec`（完整性规范）。
> JWT 兼容若依（HS256/HS512），配置相同 `JWT_SECRET_KEY` 并注入 `sub` claim 后，若依登录态可直接调用。

---

## 十一、测试

### 11.1 知识库助手（pytest）

```powershell
cd zhishiku
conda activate zhishiku
pytest tests/ -v
```

覆盖：Agent 流程与契约、完整性检查、邮件内容、配置入库、管理接口、知识库条数等。

### 11.2 工单系统

工单系统暂未内置单元测试，建议通过以下方式验证：

1. 启动后端后访问 `http://localhost:8080/swagger-ui.html`，在线调试核心接口（工单 CRUD、状态流转、Agent 审批等）；
2. 参考 [`API.md`](Ticket-Management-System/API.md) 使用 Postman / Apifox 进行接口级联调；
3. 完整功能以 `ruoyi-ui` 前端页面为准进行端到端验证。

---

## 十二、部署与运维

### 12.1 知识库助手（Docker 部署）

```powershell
cd zhishiku
copy .env.example .env        # 填写密钥，设置 MILVUS_HOST
# 先启动 Milvus 基础设施（独立 compose，按序启动 etcd -> minio -> milvus）
# 再构建并启动应用
docker compose --env-file .env build
docker compose --env-file .env up -d
# 容器内导入知识库
docker compose exec app python -m src.ingestion.import_kb --file data/sample_kb.csv --clear
```

- 配置（`config/`）与知识库（`data/`）通过 volume 挂载，替换规则或知识库**无需重建镜像**
- 升级：`docker compose pull/build && docker compose up -d`；回滚：`docker compose down` 后切回旧镜像标签
- 生产建议配置 Nginx 反代 + HTTPS（示例见 `zhishiku/README.md`）

### 12.2 工单系统（jar 部署）

```bash
mvn clean package -DskipTests
# Windows: ry.bat start | stop | restart | status
# Linux:   ./ry.sh  start | stop | restart | status
```

### 12.3 运维注意事项

- **Milvus 启动顺序**：必须 `etcd → minio → milvus` 按序启动，禁止 `restart: unless-stopped` 自动拉起
- **镜像版本**：Milvus 必须 `v2.4.13-hotfix+`，禁止回退 `v2.4.13`（存在快照 GC 缺陷导致 collection 丢失）
- **生产安全**：替换 `JWT_SECRET_KEY`、使用 bcrypt 密码哈希、配置 CORS 白名单
- **LLM 费用**：`/diagnose` 会产生 LLM 调用费用，必须鉴权防止匿名滥用

---

## 十三、常见问题

| 问题 | 排查建议 |
| --- | --- |
| 工单后端启动失败（`APPLICATION FAILED TO START`） | 检查 8080 端口占用、MySQL/Redis 是否启动、JDK 是否 17 |
| 知识库 `collection` 消失 | Milvus 未按序启动或版本 < `v2.4.13-hotfix`，检查 `milvus_collection_loss_investigation.md` |
| 提交诊断后无结果 | 确认 zhishiku 已启动（`GET /health` 返回 `milvus_connected: true`）、`ruoyi.fastapi.base-url` 正确 |
| 诊断接口报 401 | 确认 `JWT_SECRET_KEY` 两系统配置一致，且若依签发 token 注入了 `sub` claim |
| 管理界面无法登录 | 确认已配置 `ADMIN_PASSWORD_HASH` 或 `ADMIN_PASSWORD` |
| Agent 会话一直待补充 | 检查 SMTP 配置（`SMTP_LOG_ONLY=true` 时只打印日志不发信） |

---

## 附：项目文档索引

| 文档 | 位置 |
| --- | --- |
| 工单系统主 README | `Ticket-Management-System/README.md` |
| 工单系统接口文档 | `Ticket-Management-System/API.md` |
| 知识库助手主 README | `zhishiku/README.md` |
| 知识库接口对接契约（若依参考） | `Ticket-Management-System/doc/zhishiku-ruoyi-api-reference.md` |
| 知识库学习指南与 API 文档 | `zhishiku/docs/` |
| Milvus collection 丢失排查 | `zhishiku/milvus_collection_loss_investigation.md` |

*本文档最后修改时间：2026-08-16*