Simple Knowledge Base - 系统概览

多模型支持

兼容 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 端点

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

添加新的前端组件

在 web/components/ 下创建组件
在 web/types.ts 中添加 TypeScript 接口
使用 Tailwind CSS 进行样式开发
在 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