内容
# person_rag
轻量级个人/团队知识库 RAG 服务：**BM25 关键词检索 + DeepSeek 生成回答**，无需向量数据库。
[](LICENSE)
## 特性
- **BM25 检索**：基于 `jieba` 分词，适合中文运维文档
- **DeepSeek 问答**：检索命中则基于知识库回答，未命中则通用知识兜底
- **Web UI**：流式输出、Markdown 渲染、参考来源溯源
- **MCP 服务**：供 Cursor / Claude Desktop 等客户端调用知识库
- **API 访问日志**：可选 MySQL 记录 IP、入参、出参、耗时
- **限流与安全**：IP 限流、可选 API Key、Redis 计数
## 快速开始
### 1. 克隆与依赖
```bash
git clone https://github.com/your-username/person_rag.git
cd person_rag
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 2. 配置环境变量
```bash
cp .env.example .env
```
编辑 `.env`，至少设置：
```env
DEEPSEEK_API_KEY=sk-your-key-here
```
可选：MySQL 日志、Redis 限流、站点域名、ICP 备案号等（见 `.env.example`）。
### 3. 准备知识库
将 Markdown 文档放入 `docs/` 目录（仓库已附带运维示例文档）。
### 4. 启动服务
```bash
# 开发模式
python -m app.main
# 或后台运行（Linux）
chmod +x start_person_rag.sh stop_person_rag.sh
./start_person_rag.sh
```
浏览器访问：`http://localhost:8000/`
## 项目结构
```
person_rag/
├── app/
│ ├── main.py # FastAPI 入口
│ ├── rag.py # RAG 检索与生成
│ ├── indexer.py # BM25 索引
│ ├── mcp_server.py # MCP 工具定义
│ ├── api_log.py # 访问日志中间件
│ └── db.py # MySQL 日志存储
├── docs/ # 知识库 Markdown 文档
├── static/ # Web 前端
├── start_person_rag.sh
└── .env.example
```
## API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查与索引统计 |
| POST | `/api/chat` | 问答（JSON） |
| POST | `/api/chat/stream` | 流式问答（SSE） |
| POST | `/api/rebuild` | 重建 BM25 索引 |
## MCP 接入
HTTP 方式（服务启动后）：
```json
{
"mcpServers": {
"person-rag": {
"url": "https://your-domain.com/mcp"
}
}
}
```
本地 stdio 方式见 `mcp.config.example.json`。
可用工具：`search_knowledge`、`ask_knowledge`、`list_documents`、`rebuild_index`、`knowledge_health`。
## 环境变量说明
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 | 必填 |
| `SITE_URL` | 对外域名（SEO / sitemap） | 自动推断 |
| `ICP_BEIAN_NUMBER` | ICP 备案号（页脚） | 空 |
| `MCP_ENABLED` | 启用 MCP 服务 | `true` |
| `MCP_MOUNT_PATH` | MCP 挂载路径 | `/mcp` |
| `API_LOG_ENABLED` | MySQL 访问日志 | `true` |
| `RATE_LIMIT_ENABLED` | IP 限流 | `true` |
完整列表见 [`.env.example`](.env.example)。
## 生产部署建议
1. 使用 Nginx 反向代理并配置 HTTPS
2. 设置 `SITE_URL`、`ICP_BEIAN_NUMBER`（如需备案展示）
3. 配置 `RAG_API_KEYS` 保护敏感接口
4. MySQL / Redis 不对公网暴露
5. 详见 [SECURITY.md](SECURITY.md)
## 知识库文档
`docs/` 目录包含 Linux、Nginx、MySQL、Jenkins、Git 等运维笔记（示例内容已脱敏，域名/IP 均为占位符）。
## License
[MIT](LICENSE)
