gangyan/.harness/architecture.md

# 系统架构与运行配置

## 服务拓扑

```
Vue前端(:3000/metalinfo)
    │  proxy /chat_web_backend
    ▼
Java后端(:8099/chat_web_backend)  ──→  Python RAG(:7861)
    │                                      │
    ├── MySQL(:33306/chat_gpt_yj)          ├── Milvus(:19530)
    ├── Redis(:6379)                       ├── Embedding API(10.102.24.75:3000)
    └── 科协SSO(kxsso.cast.org.cn)        └── LLM API(10.102.24.75:3000 + DeepSeek/阿里云)
```

---

## Java 后端 `chat_web_backend/`

### 运行配置（Profile: yj）

| 配置项 | 值 |
|--------|-----|
| 主类 | `com.inspur.llm.ChatApplication` |
| 端口 | 8099，上下文 `/chat_web_backend` |
| 数据库 | `jdbc:mysql://127.0.0.1:33306/chat_gpt_yj`，root / 1234567890 |
| 连接池 | Druid，初始5，最小10，最大20 |
| Redis | `127.0.0.1:6379`，无密码，database 0 |
| LangChain | `http://localhost:7861` |
| 默认 LLM | deepseek-v3 |
| 前端地址 | `http://localhost:3000` |
| SSO | 科协 `https://kxsso.cast.org.cn/` |
| 文件上传限制 | 50MB |

### 包结构 `com.inspur.llm.chat`

- **`base/`** — 框架层
  - `config/` `security/` `filter/` `interceptor/` `aspect/` — Spring 配置与安全
  - `util/` `constant/` `enums/` `exception/` — 工具与异常
  - `mybatis/` — MyBatis-Plus 配置
  - `xss/` — XSS 防护过滤器

- **`gpt/`** — 业务层
  - `controller/`
    - `app/` — 前端公开接口：ChatController、LoginController、UserController
    - `gpt/` — 核心业务（15个）：ChatController、ChatMessageController、FileController、KnowledgeBaseController、AgentController、AssistantController、MetallurgyChatController、OutlinesController、SmartChatController、ConfigController、CommonController、FileNoteController、FileTranslateController、AssistantTypeController、UserController
    - `writterassitant/` — 文档撰写：DocController、WriterAssistantController
    - `personal/` — 个人知识库：ChatPersonalController
    - `sys/` — 系统管理：SysLogController、SysUserController
  - `service/` — 业务服务接口（IChatService、IGptService、IDocService、IKnowledgeBaseConfigService、IUploadFileService、IOutlinesService、TranslateFileService 等）
  - `mapper/` — MyBatis 数据访问
  - `pojo/` — entity / dto / vo / command

### 配置文件

| 文件 | 用途 |
|------|------|
| `application.yml` | 公共配置（mybatis-plus、xss、tomcat） |
| `application-yj.yml` | **当前在用**：本机 MySQL/Redis/LangChain |
| `application-dev.yml` | 开发环境（历史） |
| `application-test.yml` | 测试环境 |
| `application-prod.yml` | 生产环境（ENC 加密） |

---

## Python RAG `langchain-chat/`

### 模型配置（configs/model_config.py）

| 配置项 | 值 |
|--------|-----|
| Embedding | `bge-m3-api` → `http://10.102.24.75:3000/v1` |
| 默认 LLM | deepseek-v3 |
| LLM 列表 | deepseek-v3、deepseek-r1、deepseek-chat、qwen-max、Qwen2-72B-Instruct |
| LLM 设备 | cuda |
| Embedding 设备 | cpu |
| 历史长度 | 20 |
| 温度 | 0.7 |

**LLM API 来源：**
- 内网网关：`http://10.102.24.75:3000/v1` — deepseek-v3、deepseek-r1、Qwen2-72B-Instruct、bge-m3
- 阿里云：`https://dashscope.aliyuncs.com/compatible-mode/v1` — qwen-max
- DeepSeek 官方：`https://api.deepseek.com/v1` — deepseek-chat、deepseek-reasoner

### 知识库配置（configs/kb_config.py）

| 配置项 | 值 |
|--------|-----|
| 向量库类型 | Milvus |
| Milvus 地址 | `127.0.0.1:19530` |
| 默认知识库 | `t_policy_total_bge_new_v2` |
| MySQL | `127.0.0.1:33306/chat_gpt_yj`，root/1234567890 |
| 文本切分 | ChineseRecursiveTextSplitter，chunk_size=250，overlap=50 |
| 向量检索 Top K | 5 |
| 搜索引擎 | duckduckgo |
| PDF 转换服务 | `http://127.0.0.1:6006/convert/` |

**知识库分类：**

| 知识库 | Collection 名 | 说明 |
|--------|---------------|------|
| 政策库 | t_policy_total_bge_new_v2 | 默认主库 |
| 报告库 | gydemo_report_v2 | 冶金行业报告 |
| 期刊论文库 | t_journal_article_bge_v1 | 学术期刊 |
| 冶金新闻库 | yj_news_bge_v1_recover | 2024年及之前 |
| 冶金中文期刊库 | yj_ch_journal_bge_v1_recover | - |
| 冶金外文期刊库 | yj_for_journal_bge_v1_recover | - |
| 冶金OA期刊库 | yj_oa_journal_bge_v2_recover | - |
| 冶金政策库 | yj_policys_bge_v1_recover | - |
| 钢铁行业动态库 | steel_kb_token_chunk | - |

> 注意：当前所有知识库常量都被统一指向 `DEFAULT_KNOWLEDGE_BASE = t_policy_total_bge_new_v2`，注释中保留了原始 collection 名。

### 服务配置（configs/server_config.py）

| 服务 | Host | Port |
|------|------|------|
| API Server | 0.0.0.0 | 7861 |
| WebUI | 0.0.0.0 | 8501 |
| FastChat OpenAI API | 0.0.0.0 | 20000 |
| FastChat Controller | 0.0.0.0 | 20101 |

### 源码结构

- `server/api.py` — 主 API 路由
- `server/llm_api.py` — LLM 调用
- `server/utils.py` — 工具函数
- `server/knowledge_base/` — 知识库 CRUD、文件转换、向量化
- `server/custom/` — 定制功能（章节速览、文章综述、摘要检索、论文翻译）
- `server/model_workers/` — 各模型 Worker（OpenAI、智谱、百川等）
- `server/reranker/` — 重排序
- `configs/` — 所有配置文件

---

## Vue 前端 `chat_web_front/`

### 运行配置（.env）

| 配置项 | 值 |
|--------|-----|
| 前端上下文 | `/metalinfo` |
| 后端代理 | `/chat_web_backend` → `http://localhost:8099` |
| 端口 | 3000 |
| 路由模式 | Hash |

### 页面路由

| 路径 | 页面 | 说明 |
|------|------|------|
| `/chat` | 智能对话 | 主对话页（默认首页） |
| `/writing` | 文档撰写 | 文档列表 |
| `/writing/edit` | 文档编辑 | 大纲→正文撰写 |
| `/knowledgeBase` | 知识库 | 个人知识库管理 |
| `/knowledgeBase/fileList` | 文件列表 | 知识库内文件 |
| `/knowledgeBase/fileDetail` | 文件详情 | 文件阅读/对话 |
| `/applications` | 应用广场 | 工具集合 |
| `/translate` | 翻译 | 文档翻译 |
| `/login` | 登录 | 科协SSO/本地登录 |

### 前端 API 分组（src/api/index.ts）

| 分组 | 核心接口 | 对应后端 |
|------|----------|----------|
| 对话 | fetchChatAPI、fetchConversationId、fetchChatAPIProcess（流式）、LiteratureChat | app/ChatController + gpt/ChatController |
| 文档撰写 | createOutLine、sessionFlow、expandKnow、docSave、getDoc | WriterAssistantController + DocController + OutlinesController |
| 知识库 | getKnowledgeBaseList、uploadFile、getFileContent、streamDocumentOverview、streamChapterOverview | KnowledgeBaseController + FileController |
| 翻译 | fileTranslate、translateString、checkTextLanguage | FileTranslateController |
| 智慧场景 | fetchSmartPrompt、searchPrompt | SmartChatController + AssistantController |
| 用户 | fetchSession、updateUser、fetchCASLogin | UserController + LoginController |

### 源码结构

- `src/views/` — 页面组件（chat、writing、reading、applications、translate、login）
- `src/components/` — 通用组件（Message、AIbox、AIcreate、AIrewrite、KnowledgeBox、WritingGuide、Literatures、Translate 等）
- `src/api/index.ts` — 所有 API 请求
- `src/store/index.ts` — Pinia 状态管理
- `src/router/` — 路由与权限守卫
- `src/utils/` — 工具函数（request 封装、copy）
- `src/locales/` — 多语言（中/英/韩/俄/越/繁）
- `src/config/properties.ts` — 前端配置

---

## Docker 基础设施

### MySQL

- Compose 文件：`mysql/docker-compose.yml`
- 容器：`mysql-server`，镜像 `mysql:8.4.4`
- 端口：33306 → 3306
- 数据卷：`mysql/mysql-8.4.4/mysql_bind`
- 初始库：`chat_LLM`（实际使用 `chat_gpt_yj`）

### Milvus

- Compose 文件：`milvus/docker-compose.yml`
- 容器：`milvus-standalone`，镜像 `milvusdb/milvus:v2.6.4`
- 端口：19530(gRPC)、9091(健康检查)
- 依赖：etcd(v3.5.18) + MinIO(2024-12-18)
- 数据卷：`milvus/volumes/`

### Redis

- 非 Docker 部署（宿主机直接运行或 `docker start redis-server`）
- 端口：6379，无密码