mula
/
nex_docus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_docus/docs/sdd/architecture/overview.md

2.0 KiB
Raw Permalink Blame History

架构概览（Overview）

系统定位

NEX Docus 是单机可部署的团队文档平台，后端 FastAPI 单体 + 前端 React SPA + MySQL + Redis + 本地文件系统 + 本地检索/向量引擎，全部由 docker-compose 编排为同网段容器。

逻辑架构

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 客户端要求）。