# Simple Knowledge Base - 系统概览

# Simple Knowledge Base

全栈 RAG 问答系统 — 基于 React 19 + NestJS 的检索增强生成技术

React 19 NestJS RAG 系统 TypeScript

### 多模型支持

兼容 OpenAI API（OpenAI、DeepSeek、Claude 等）+ Google Gemini 原生 SDK，可配置 LLM、Embedding 和 Rerank 模型。

⚡

### 双处理模式

快速模式通过 Apache Tika 提取文本，高精度模式通过视觉管线处理图文混合文档。

### 混合检索

基于 Elasticsearch 的向量 + 关键词混合搜索，支持来源引用、相似度评分，可配置分块大小与重叠。

### 用户隔离

JWT 认证 + 每用户独立知识库，数据与配置完全隔离，保障隐私安全。

### 流式响应

基于 Server-Sent Events (SSE) 的实时流式输出，提供流畅低延迟的对话体验。

### 多语言支持

界面支持日语、中文和英文，错误信息和 API 响应消息全面国际化。

## 1 系统架构概览

前端层
React 19 + Vite
端口 13001（开发）/ 80（生产）
↕
后端层
NestJS API
端口 3001
JWT 认证
对话 / RAG
视觉管线
↕
AI 与数据层
OpenAI / Gemini
LLM + 向量嵌入
Elasticsearch
端口 9200
Apache Tika
端口 9998
LibreOffice
端口 8100
SQLite
元数据存储

#### 双处理管线

#### 快速模式（Tika）

上传
→
Tika 提取
→
向量化
→
存储

快速文本提取，无 API 调用成本

#### 高精度模式（视觉管线）

上传
→
LibreOffice
→
PDF 转图片
→
视觉模型

保留原始排版、图表和图片信息

## 2 项目结构

simple-kb/
├── web/ # React 前端（Vite）
│ ├── components/ # UI 组件（ChatInterface, ConfigPanel 等）
│ ├── contexts/ # React Context 提供者
│ ├── services/ # API 客户端服务
│ └── utils/ # 工具函数
├── server/ # NestJS 后端
│ ├── src/
│ │ ├── ai/ # AI 服务（向量嵌入等）
│ │ ├── api/ # API 模块
│ │ ├── auth/ # JWT 认证
│ │ ├── chat/ # 对话 / RAG 模块
│ │ ├── elasticsearch/ # Elasticsearch 集成
│ │ ├── import-task/ # 导入任务管理
│ │ ├── knowledge-base/ # 知识库管理
│ │ ├── libreoffice/ # LibreOffice 集成
│ │ ├── model-config/ # 模型配置管理
│ │ ├── vision/ # 视觉模型集成
│ │ └── vision-pipeline/ # 视觉管线编排
│ ├── data/ # SQLite 数据库存储
│ ├── uploads/ # 上传文件存储
│ └── temp/ # 临时文件
├── docs/ # 项目文档
├── nginx/ # Nginx 配置
├── libreoffice-server/ # LibreOffice 转换服务（Python/FastAPI）
└── docker-compose.yml # Docker 编排配置

## 3 开发环境搭建

#### 前置条件

- Node.js 18+
- Yarn 包管理器
- Docker & Docker Compose

#### 快速启动

# 安装依赖
yarn install
# 启动基础设施服务
docker-compose up -d elasticsearch tika libreoffice
# 配置环境变量
cp server/.env.sample server/.env
# 同时启动前后端
yarn dev

#### 开发命令

# 仅启动前端（端口 13001）
cd web && yarn dev
# 仅启动后端（端口 3001）
cd server && yarn start:dev
# 运行测试
cd server && yarn test
cd server && yarn test:e2e
# 代码检查和格式化
cd server && yarn lint
cd server && yarn format

## 4 Docker 服务与端口

服务 | 端口 | 用途
--- | --- | ---
Elasticsearch | 9200 | 向量存储与混合检索
Apache Tika | 9998 | 文档文本提取
LibreOffice Server | 8100 | 文档格式转换
后端 API | 3001 | NestJS REST API
前端（开发） | 13001 | Vite 开发服务器
前端（生产） | 80 / 443 | Nginx 反向代理

## 5 环境配置

关键环境变量，配置于 `server/.env`

变量名 | 默认值 | 说明
--- | --- | ---
OPENAI_API_KEY | — | OpenAI 兼容 API 密钥
GEMINI_API_KEY | — | Google Gemini API 密钥
ELASTICSEARCH_HOST | http://localhost:9200 | Elasticsearch 地址
TIKA_HOST | http://localhost:9998 | Apache Tika 地址
LIBREOFFICE_URL | http://localhost:8100 | LibreOffice 服务器地址
JWT_SECRET | — | JWT 签名密钥

## 6 代码规范

#### 语言要求

- 代码注释必须使用英文
- 日志消息必须使用英文
- 错误消息必须支持国际化
- API 响应消息必须支持国际化
- 界面支持日语、中文和英文

#### 代码质量

- 后端使用 Jest 进行单元测试和端到端测试
- 后端已配置 ESLint 和 Prettier
- 格式化：`cd server && yarn format`
- 检查：`cd server && yarn lint`

## 7 常见开发任务

#### 添加新的 API 端点

1. 在 `server/src/` 对应模块下创建 Controller
2. 添加 Service 方法，使用英文注释
3. 更新 DTO 和参数校验
4. 在 `*.spec.ts` 文件中添加测试

#### 添加新的前端组件

1. 在 `web/components/` 下创建组件
2. 在 `web/types.ts` 中添加 TypeScript 接口
3. 使用 Tailwind CSS 进行样式开发
4. 在 `web/services/` 中连接后端服务

## 8 部署

#### 开发环境

docker-compose up -d elasticsearch tika libreoffice
yarn dev

#### 生产环境

# 构建并启动所有服务
docker-compose up -d

## 9 故障排查

Elasticsearch 无法启动

检查 docker-compose.yml 中的内存限制配置

文件上传失败

确保 `uploads/` 和 `temp/` 目录存在且具有正确的读写权限

视觉管线报错

确认 LibreOffice 服务正在运行且 8100 端口可访问

API 密钥错误

检查 `server/.env` 中的环境变量配置

数据库重置

删除 `server/data/metadata.db` 及 Elasticsearch 数据卷

## 10 调试与健康检查

# 检查 Elasticsearch 状态
curl http://localhost:9200/_cat/indices
# 检查 Tika 状态
curl http://localhost:9998/tika
# 检查 LibreOffice 状态
curl http://localhost:8100/health