# hfut-knowledge-backend

**Repository Path**: three2one_xu/hfut-knowledge-backend

## Basic Information

- **Project Name**: hfut-knowledge-backend
- **Description**: 驷马山灌区知识库后台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HFUT-Know

基于大模型的智能知识库与知识图谱平台（LangGraph + Vue + FastAPI + LightRAG + Milvus）。

## 环境要求

| 组件 | 版本/说明 |
|------|-----------|
| Python | ≥ 3.11（推荐用 [uv](https://github.com/astral-sh/uv) 管理依赖） |
| Node.js | ≥ 20（前端源码开发时需要，推荐 pnpm 10.x） |
| Docker / Docker Compose | 运行中间件或全量容器部署 |
| GPU（可选） | `bge-m3-vllm`、`mineru-api` 等能力需要 NVIDIA 驱动 |

## 配置

```bash
cp .env.template .env
```

按实际环境修改 `.env`，至少关注：

- `DB_*`、`MILVUS_URI`、`MINIO_URI` — 与部署方式（本机 / Docker）一致
- `SILICONFLOW_API_KEY` 等模型密钥
- `MAIN_AUTH_*` — 对接主系统（B）鉴权时启用

---

## Docker 启动（推荐生产 / 一键联调）

### 1. 准备

```bash
cp .env.template .env
# 编辑 .env，填写 API Key、密码等
```

### 2. 启动全部服务

```bash
docker compose up -d --build
```

首次构建较慢，需等待 `api` 健康检查通过（`start_period` 最长约 3 分钟）。

### 3. 访问地址

| 服务 | 地址 |
|------|------|
| 前端 Web | http://localhost:8888（`WEB_PORT` 可改） |
| 后端 API | http://localhost:5050 |
| API 健康检查 | http://localhost:5050/api/system/health |
| PostgreSQL | `localhost:5434`（映射容器 5432） |
| Milvus | `localhost:19530` |
| MinIO API / 控制台 | `localhost:9010` / `localhost:9011` |

### 4. 常用命令

```bash
# 查看状态
docker compose ps

# 查看 API 日志
docker compose logs -f api

# 停止
docker compose down

# 仅启动中间件（本机跑 API 时用）
docker compose up -d postgres etcd minio milvus
```

### 5. 可选组件

**MinerU OCR**（profile `mineru`）：

```bash
docker compose --profile mineru up -d mineru-api
```

**BGE-M3 嵌入 vLLM**（需 GPU，默认会随 `docker compose up` 拉起 `bge-m3-vllm`）：

- 模型目录：`.env` 中 `BGE_VLLM_MODEL_HOST_PATH` 或 `BGE_SPARSE_MODEL_HOST_PATH`（默认 `./models/bge-m3`）
- 端口：`VLLM_EMBED_PORT`（默认 `9998`）


```bash
docker compose up -d bge-m3-vllm
```

---

## 源码启动（本地开发）

适合改后端/前端代码。中间件建议仍用 Docker，API 在本机跑。

### 1. 启动依赖服务

```bash
docker compose up -d postgres etcd minio milvus
```

确认 `.env` 中为本机地址，例如：

```env
DB_HOST=localhost
DB_PORT=5434
MILVUS_URI=http://localhost:19530
MINIO_URI=http://localhost:9010
```

### 2. 安装并启动后端

```bash
# 安装 Python 依赖（首次）
uv sync

# 前台运行（开发调试）
uv run uvicorn server.main:app --host 0.0.0.0 --port 5050 --reload

# 或后台运行
./scripts/start_app.sh
# 停止: ./scripts/stop_app.sh
```

API 文档：http://localhost:5050/docs

### 3. 启动前端（可选）

```bash
cd web
pnpm install

# 代理到本机 API（默认 5050）
VITE_API_URL=http://localhost:5050 pnpm dev
```

浏览器访问 Vite 提示的地址（一般为 http://localhost:5173）。  
`vite.config.js` 会把 `/api` 代理到 `VITE_API_URL`。

也可不启前端 dev，仅用 Docker 里的 `web` 服务访问已构建的静态页。

### 4. 代码检查（后端）

```bash
uv run python -m ruff check .
uv run ruff format .
```

---

## 首次使用

1. 打开 Web 登录页。
2. 若系统未初始化，按页面提示创建超级管理员。
3. 若已启用 `MAIN_AUTH_ENABLED=true`，登录页可出现「主系统登录(B)」用于对接测试。

---

## 目录速览

```
server/          # FastAPI 路由与中间件
src/             # 核心业务（RAG、存储、模型等）
web/             # Vue 3 前端
docker/          # Dockerfile 与卷初始化
scripts/         # start_app.sh 等辅助脚本
documents/       # 接口与联调文档
```

## 相关文档

- `documents/接口鉴权_姜恒_ding.md` — 主系统 Token 鉴权说明
- `documents/模拟登陆.md` — 主系统登录示例
- `AGENTS.md` — 项目开发约定