43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# 架构概览（Overview）
|
||
|
||
## 系统定位
|
||
|
||
NEX Docus 是**单机可部署**的团队文档平台，后端 FastAPI 单体 + 前端 React SPA + MySQL + Redis + 本地文件系统 + 本地检索/向量引擎，全部由 docker-compose 编排为同网段容器。
|
||
|
||
## 逻辑架构
|
||
|
||
```mermaid
|
||
graph TD
|
||
Client[React SPA] -->|JSON/HTTP| API[FastAPI Backend :8000]
|
||
Agent[External Agent] -->|MCP streamableHttp| API
|
||
API --> DB[(MySQL)]
|
||
API --> RD[(Redis)]
|
||
API --> FS[文件系统 STORAGE_ROOT/projects/<uuid>]
|
||
API --> WH[Whoosh 全文索引 search_index]
|
||
API --> ZV[ZVec 向量库 vector_index/<project_id>]
|
||
API --> LLM[LLM Provider: chat/embedding]
|
||
FS -->|变更同步| SVC[FileVectorSyncService → ZVec / SearchService]
|
||
```
|
||
|
||
## 三层结构（物理/逻辑/应用映射）
|
||
|
||
| 层 | 载体 | 说明 |
|
||
| --- | --- | --- |
|
||
| 应用层 | FastAPI（/api/v1 + /mcp）+ React SPA | 业务 API 与前端 |
|
||
| 数据层 | MySQL（元数据/权限/状态）、Redis（Token/会话）、文件系统（内容）、Whoosh/ZVec（索引） | 结构化 vs 非结构化分离 |
|
||
| 基础设施 | docker-compose（backend/frontend/mysql/redis）、nginx（frontend 内） | 容器化部署 |
|
||
|
||
## 关键子系统
|
||
1. **认证**：JWT Bearer + Redis Token 缓存双校验（见 DV-0001）。
|
||
2. **权限**：RBAC（roles/system_menus/role_menus）+ 项目级角色（admin/editor/viewer）双维度（DV-0002/0004）。
|
||
3. **文件系统**：`StorageService` 统一封装，含路径安全校验（DV-0002）。
|
||
4. **检索**：Whoosh 全文（DV-0005）+ ZVec 语义（DV-0006）双引擎，写路径后台同步（ADR-08）。
|
||
5. **知识库**：RAG 检索 + LLM 生成 + 引用支撑句对齐（DV-0007）。
|
||
6. **开放**：MCP Streamable HTTP（/mcp），bot 凭据映射到用户（DV-0011）。
|
||
|
||
## 系统边界
|
||
- 进程内单后端：REST 与 MCP 同挂一个 service。
|
||
- 存储边界：内容永不进 DB BLOB；DB 只存元数据。
|
||
- 网络边界：前端经 nginx 反代 /api，可同域免跨域；/mcp 不可 301/302 重定向（MCP 客户端要求）。
|
||
|