# knowledge_bank

**Repository Path**: garine615/knowledge_bank

## Basic Information

- **Project Name**: knowledge_bank
- **Description**: 这是我们的题库，也是共同的知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 面馆（Knowledge Bank）

<p align="center">
  <img src="media/logo.png" alt="面馆" width="240" height="240">
</p>

> 一个面向大厂面试题的知识整理与检索平台。

后端基于 **FastAPI**，启动时会一次性加载题库并对外提供 REST API；前端基于 **React + Vite + Tailwind CSS + Framer Motion**，以「公司」和「岗位 / 领域」两条主线组织内容，并提供右下角的留言入口，方便用户提交想看的公司与岗位。

## 特性

- 无需注册或登录，即可浏览题库内容。
- 题库数据为只读依赖，不会修改 `knowledge-base/` 下的原始文件。
- 留言数据会写入 `backend/data/messages.db`，便于本地管理。
- 支持公司、领域、难度、频率和关键词等多维筛选。

## 页面预览

### 首页

![首页](media/index.png)

### 公司浏览

![公司浏览](media/companies.png)

### 岗位浏览

![岗位浏览](media/jobs.png)

### 题目浏览

![题库浏览](media/base.png)
![题目详情](media/problems.png)

### 信箱投稿

![信箱投稿](media/dreams.png)

## 技术栈

- 后端：FastAPI、SQLite、Pydantic 风格的数据规范化处理
- 前端：React、TypeScript、Vite、Tailwind CSS、Framer Motion
- 测试：Pytest

## 目录结构

```text
knowledge_bank/
├── backend/          # FastAPI + SQLite（留言）
├── frontend/         # Vite + React + TypeScript + Tailwind CSS
└── scripts/
    └── start_dev.sh  # 一键启动脚本
```

## 环境要求

- Python 3.10+
- Node.js 18+

## 快速开始

### 1. 安装依赖

```bash
# 后端
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 前端
cd ../frontend
npm install
```

### 2. 启动开发环境

#### 方式一：一键启动

```bash
bash scripts/start_dev.sh
```

启动后可访问：

- 后端：http://localhost:8000
- 前端：http://localhost:5173

`start_dev.sh` 默认会把同级的 `../knowledge-base` 目录作为 `KB_PATH`。如果你的目录结构不同，可以显式指定：

```bash
KB_PATH=/path/to/knowledge-base bash scripts/start_dev.sh
```

#### 方式二：分别启动

```bash
# 终端 1：后端
cd backend
source .venv/bin/activate
KB_PATH=/absolute/path/to/knowledge-base \
  uvicorn app.main:app --reload --port 8000

# 终端 2：前端
cd frontend
npm run dev
```

## API 概览

| 方法 | 路径                                  | 说明                                                                                          |
| ---- | ------------------------------------- | --------------------------------------------------------------------------------------------- |
| GET  | `/api/health`                         | 健康检查                                                                                      |
| GET  | `/api/stats`                          | 返回总题数、公司数、领域数、技术数                                                            |
| GET  | `/api/companies`                      | 公司列表                                                                                      |
| GET  | `/api/domains`                        | 领域列表                                                                                      |
| GET  | `/api/questions`                      | 题目列表，支持 `company` / `domain` / `difficulty` / `frequency` / `q` / `page` / `page_size` |
| GET  | `/api/questions/{id}`                 | 题目详情                                                                                      |
| GET  | `/api/questions/{id}/related?limit=5` | 相关推荐                                                                                      |
| POST | `/api/messages`                       | 提交留言                                                                                      |
| GET  | `/api/messages?limit=50&offset=0`     | 查看留言（管理用途）                                                                          |

OpenAPI 交互文档：<http://localhost:8000/docs>

## 留言管理

留言会以 SQLite 的形式存储在 `backend/data/messages.db`。如需直接查看数据，可以执行：

```bash
sqlite3 backend/data/messages.db 'SELECT id, created_at, target_companies, target_domains, message FROM messages ORDER BY id DESC;'
```

也可以通过 API 获取：

```bash
curl 'http://localhost:8000/api/messages?limit=20'
```

## 生产部署

如果你希望把网站公开上线，推荐使用“CDN/WAF + Nginx 反向代理 + Gunicorn 多进程”的组合：

- CDN/WAF 负责抗流量攻击、TLS 终止、静态资源加速和基础防护规则。
- Nginx 负责接收外部请求、转发 `/api/` 到后端，并为前端静态资源提供缓存与边缘限流。
- Gunicorn 负责在后端起多个 worker，提升多用户并发能力。

### Docker Compose

仓库提供了可直接改造的部署骨架：

- `deploy/Dockerfile.backend`：后端镜像，使用 Gunicorn 多 worker 运行 API。
- `deploy/Dockerfile.frontend`：前端镜像，构建 `frontend/dist` 后由 Nginx 提供静态站点并反代 API。
- `deploy/nginx.conf`：反向代理、连接限制、请求限速和基础安全响应头。
- `deploy/docker-compose.yml`：一键启动 `app` 和 `web` 两个服务。

启动前请先设置环境变量，例如：

```bash
export KB_PATH=/absolute/path/to/knowledge-base
export WORKERS=4
export RATE_LIMIT_PER_MINUTE=120
export RATE_LIMIT_CONCURRENT=20
```

然后在 `deploy/` 目录执行：

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

上线到 CDN/WAF 时，建议把 CDN 回源地址指向 Nginx，开启源站隐藏、IP 白名单和 WAF 规则；Nginx 已经会把 `X-Forwarded-For` 和 `X-Real-IP` 转给后端，后端限流会优先按真实客户端 IP 统计。

### 直接多进程启动

如果你不使用 Docker，也可以直接在服务器上运行：

```bash
KB_PATH=/absolute/path/to/knowledge-base WORKERS=4 bash scripts/start_prod.sh
```

这个脚本会使用 `backend/gunicorn.conf.py` 启动 Gunicorn，并通过 `uvicorn.workers.UvicornWorker` 运行多 worker。

### CDN / WAF 接入建议

- 把域名 CNAME 到 CDN 提供商。
- 把 CDN 的源站配置为 Nginx 地址。
- 开启基础 WAF 规则：限速、Bot 防护、可疑 UA 拦截、POST 频率限制。
- 让 CDN 或 Nginx 统一补 `X-Forwarded-For`，后端按真实客户端 IP 做限流。

### systemd 服务

如果你在云服务器上直接运行后端，仓库提供了 `deploy/knowledge-bank.service` 作为 systemd 模板。把它复制到 `/etc/systemd/system/knowledge-bank.service` 后，按你的实际路径修改下面这些值：

- `WorkingDirectory`
- `KB_PATH`
- `PYTHON_BIN`
- `User` / `Group`

常用命令：

```bash
sudo cp deploy/knowledge-bank.service /etc/systemd/system/knowledge-bank.service
sudo systemctl daemon-reload
sudo systemctl enable --now knowledge-bank.service
sudo systemctl status knowledge-bank.service
sudo journalctl -u knowledge-bank.service -f
```

如果你使用的是反向代理 + 多 worker 部署，这个 service 会调用 `scripts/start_prod.sh`，由 Gunicorn 承载后端并通过 `backend/gunicorn.conf.py` 控制 worker 数量。

## 测试

```bash
cd backend
KB_PATH=$(pwd)/tests/fixtures/mini_kb python -m pytest -q
```

测试覆盖范围包括：

- `test_normalizer.py`：三种 schema 的规范化处理，包括中文 company 和 `dict` answer 场景
- `test_loader.py`：加载、索引、过滤 `*_summary_*.json` / `statistics.json`、多条件查询、相关推荐
- `test_api.py`：各接口的 happy path 以及留言读写闭环

## 数据说明

题库以 JSON 文件形式存储在 `../knowledge-base/companies/{company_id}/unique_id_*.json`。由于原始数据经历过多次 schema 演进，后端会在启动时统一规范化为 `backend/app/models.py::NormalizedQuestion`。

各公司目录下的 `*_summary_*.json` 和 `statistics.json` 并不是题目，加载器会自动跳过。

## 请我喝杯奶茶 ☕

如果这个项目帮你省下了找题、整理、对比的时间，也欢迎给面馆投喂一点点上线基金。每一份打赏，都会变成服务器续费、域名年费、存储空间和小小的开发动力。

<p align="center">
  <img src="media/rewards.jpg" alt="reward" width="240" height="240">
</p>

你可以把它理解成：

- 给项目续一口气，让它继续稳定在线。
- 给更多题库和功能一点生长空间。
- 给作者一杯奶茶，让写代码这件事更快乐一点点。

谢谢你的喜欢，也谢谢你的每一次鼓励~~