184 lines
8.7 KiB
Markdown
184 lines
8.7 KiB
Markdown
# NEX Docus 文档管理平台
|
||
|
||
<div align="center">
|
||
|
||
轻量、可自托管的团队文档中心：文件系统存储内容，数据库管理权限，内置 AI 知识库问答。
|
||
|
||
v1.0.0 · FastAPI + React 18 + MySQL 8 + Redis
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## ✨ 核心特性
|
||
|
||
- 📁 **文件即真理**：文档正文以 Markdown 文件形式存放在磁盘（`storage/projects/<uuid>/…`），数据库只保存权限与元数据，备份/迁移只需拷目录。
|
||
- 📝 **Markdown 编辑**：基于 ByteMD 的编辑器，支持 **编辑 / 分栏 / 预览** 三态切换，右侧悬浮目录（TOC）在纯编辑模式下同样可用；支持 GFM、代码高亮、Frontmatter、emoji、图片上传。
|
||
- 🌲 **无限层级目录树**：文件/文件夹创建、重命名、拖拽移动、排序。
|
||
- 👥 **团队协作**：项目成员与项目内角色（admin / editor / viewer），公开项目与「参与项目」列表。
|
||
- 🔎 **双引擎检索**：本地全文检索（Whoosh + jieba 中文分词）＋ 向量检索（ZVec / 远程 Embedding）。
|
||
- 🤖 **AI 知识库问答**：基于项目文档的 RAG 对话，返回引用文件与命中片段，可中断、可回看思考过程与耗时。
|
||
- 🧩 **模型配置中心**：在系统管理里维护 Chat / Embedding 模型（OpenAI 兼容接口、本地 sentence-transformers），运行时热切换。
|
||
- 🔗 **分享与预览**：项目/单文件分享链接（可带访问密码）、Markdown / PDF / 图片预览，PDF 支持服务端导出。
|
||
- 🔐 **RBAC**：用户 / 角色 / 菜单与按钮级权限点，侧边栏按授权动态生成。
|
||
- 📄 **通知与审计**：站内通知中心、全量操作日志检索。
|
||
- 🔄 **Git 双向同步**：项目可绑定 Git 仓库，按目录同步文档。
|
||
- 🛰️ **MCP 接入**：为 MCP Bot 提供凭证与文档读写能力。
|
||
- 🌗 **明暗双主题**：全站统一设计令牌（`styles/design-tokens.css` + antd 主题），跟随系统或手动切换。
|
||
|
||
## 🏗️ 技术栈
|
||
|
||
### 后端
|
||
| 组件 | 选型 |
|
||
| --- | --- |
|
||
| Web 框架 | FastAPI 0.109 + Uvicorn（全异步） |
|
||
| ORM | SQLAlchemy 2.0（asyncio + aiomysql） |
|
||
| 数据库 | MySQL 8.0（utf8mb4） |
|
||
| 缓存/队列 | Redis 7 |
|
||
| 认证 | JWT（python-jose）＋ bcrypt 密码哈希 |
|
||
| 检索 | Whoosh3 + jieba（全文）、ZVec + sentence-transformers / 远程 Embedding（向量） |
|
||
| 文档处理 | markdown、weasyprint（PDF）、python-magic |
|
||
| 集成 | OpenAI 兼容 LLM 接口、系统 `git` 命令（subprocess 调用）、MCP SDK |
|
||
|
||
### 前端
|
||
| 组件 | 选型 |
|
||
| --- | --- |
|
||
| 框架 | React 18 + React Router v6 |
|
||
| 构建 | Vite 5（`manualChunks` 分包、全部路由 lazy 加载） |
|
||
| UI | Ant Design 5 ＋ 自研设计令牌（无 Tailwind / postcss） |
|
||
| 状态 | Zustand ＋ Axios 统一封装 |
|
||
| Markdown | ByteMD（`@bytemd/react` + gfm/highlight/frontmatter/breaks/gemoji）＋ react-markdown 渲染 |
|
||
| 其它 | react-pdf / pdfjs-dist、react-virtuoso、antd-img-crop |
|
||
|
||
## 📦 项目结构
|
||
|
||
```
|
||
NexDocus/
|
||
├── backend/ # FastAPI 后端
|
||
│ ├── app/
|
||
│ │ ├── api/v1/ # API 路由（认证/项目/文件/检索/对话/分享/系统…）
|
||
│ │ ├── core/ # 配置、数据库、安全、依赖注入、幂等迁移
|
||
│ │ ├── models/ # SQLAlchemy 模型（18 张表）
|
||
│ │ ├── schemas/ # Pydantic Schema
|
||
│ │ ├── services/ # 业务逻辑（存储、检索、向量化、RAG、Git、导出…）
|
||
│ │ └── mcp/ # MCP Streamable HTTP 接入（凭证鉴权 + 工具注册）
|
||
│ ├── scripts/ # 数据库初始化脚本（随代码走，Docker 构建上下文需要）
|
||
│ ├── tests/ # pytest 用例
|
||
│ └── main.py # 应用入口
|
||
│
|
||
├── frontend/ # React 前端
|
||
│ └── src/
|
||
│ ├── api/ # 接口封装
|
||
│ ├── components/ # 通用组件（Feedback 统一提示、MainLayout…）
|
||
│ ├── data/ # 静态配置数据
|
||
│ ├── pages/ # 页面（全部 lazy 加载）
|
||
│ ├── stores/ # Zustand
|
||
│ ├── styles/ # design-tokens.css 等全局样式
|
||
│ ├── theme/ # antd 主题（明/暗）
|
||
│ └── utils/
|
||
│
|
||
├── scripts/ # 运维/开发脚本（start / stop / deploy）
|
||
├── docs/ # 全部文档（见 docs/README.md）
|
||
├── storage/ # 运行期文件存储（已 gitignore）
|
||
├── backup/ # 数据库备份产物（已 gitignore）
|
||
├── .run/ # 本地 pid / 日志（已 gitignore）
|
||
├── docker-compose.yml # 容器编排
|
||
└── .env.example # Docker 部署环境变量模板
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
- Python **3.10+**（推荐 3.12）
|
||
- Node.js **18+**
|
||
- MySQL **8.0**、Redis **7**（已有实例亦可，Docker 部署会自动拉起）
|
||
- 启用 Git 同步时需要本机存在 `git` 可执行文件（后端镜像已内置）
|
||
|
||
### 方式一：一键启动（本地开发，推荐）
|
||
|
||
```bash
|
||
./scripts/start.sh
|
||
```
|
||
|
||
首次运行会：创建 `backend/venv` → 生成 `backend/.env` 模板（**此时会停下**，请填好 MySQL/Redis 连接信息后重新执行）→ 安装前后端依赖 → 真实校验 MySQL/Redis 连通性 → 幂等初始化数据库 → 拉起后端与前端。
|
||
|
||
```bash
|
||
./scripts/start.sh --backend # 只启动后端
|
||
./scripts/start.sh --frontend # 只启动前端
|
||
./scripts/start.sh --install # 只准备环境，不启动服务
|
||
./scripts/start.sh --init-db # 强制重跑数据库初始化
|
||
./scripts/start.sh --port 8001 # 换端口（环境变量优先，不改 .env）
|
||
./scripts/start.sh --daemon # 启动后立即返回（后台常驻）
|
||
./scripts/stop.sh # 停止
|
||
```
|
||
|
||
启动完成后：前端 http://localhost:5173 · 后端 http://localhost:8000 · 接口文档 http://localhost:8000/docs
|
||
|
||
### 方式二：Docker Compose（服务器部署）
|
||
|
||
```bash
|
||
cp .env.example .env # 按注释修改密码/端口/存储路径
|
||
./scripts/deploy.sh init # 生成配置、构建镜像、初始化数据库
|
||
./scripts/deploy.sh start
|
||
./scripts/deploy.sh status
|
||
```
|
||
|
||
细节见 [docs/deploy/README.md](docs/deploy/README.md)。
|
||
|
||
### 默认账号
|
||
|
||
| 场景 | 用户名 | 密码 |
|
||
| --- | --- | --- |
|
||
| `scripts/start.sh` / `backend/scripts/init_db.py` | `admin` | `admin@123` |
|
||
| Docker 部署（`.env.example` 默认值） | `admin` | `Admin@123456` |
|
||
|
||
可用 `ADMIN_USERNAME` / `ADMIN_PASSWORD` / `ADMIN_EMAIL` / `ADMIN_NICKNAME` 覆盖；**首次登录后请立即修改密码**。
|
||
|
||
## 📖 文档索引
|
||
|
||
| 文档 | 内容 |
|
||
| --- | --- |
|
||
| [docs/README.md](docs/README.md) | 文档地图（从这里开始） |
|
||
| [docs/quickstart.md](docs/quickstart.md) | 开发环境快速上手、常见启动问题 |
|
||
| [docs/deploy/README.md](docs/deploy/README.md) | Docker 部署、升级、备份与恢复 |
|
||
| [docs/database.md](docs/database.md) | 数据库 18 张表结构与初始化链路 |
|
||
| [docs/manual/user-guide.md](docs/manual/user-guide.md) | 面向使用者的功能手册 |
|
||
| [docs/sdd/](docs/sdd/) | 规格驱动开发文档：愿景、架构、ADR、DV 规格、发布记录 |
|
||
| [scripts/README.md](scripts/README.md) | 脚本清单与约定 |
|
||
|
||
## 🧪 开发与质量
|
||
|
||
```bash
|
||
# 前端：静态检查与构建
|
||
cd frontend && npm run lint && npm run build
|
||
|
||
# 后端：pytest（用例较少，见发布报告 OI 清单）
|
||
cd backend && ./venv/bin/pip install -r requirements-dev.txt
|
||
cd backend && ./venv/bin/python -m pytest
|
||
```
|
||
|
||
- 前端统一使用 `@/` 别名指向 `frontend/src`；新页面必须在 `App.jsx` 用 `lazy()` 注册。
|
||
- 交互提示统一走 `components/Feedback` 的 `Toast`（`Toast.confirm` 替代 `Modal.confirm`）。
|
||
- 颜色/圆角/间距一律取 `styles/design-tokens.css` 与 antd token，禁止硬编码色值。
|
||
- 数据库结构变更：改 `app/models/`，并在 `app/core/migrations.py` 增加幂等补列逻辑；**不要**再往仓库里追加一次性 `.sql`。
|
||
|
||
## 🔒 安全要点
|
||
|
||
- 密码 bcrypt 存储；JWT 过期时间由 `ACCESS_TOKEN_EXPIRE_MINUTES` 控制。
|
||
- 文件路径全部经过规范化校验，拒绝路径穿越；上传大小与类型受限。
|
||
- `DEBUG=True` 会打印全量 SQL，**生产必须关闭**。
|
||
- `SECRET_KEY`、数据库/Redis 密码、Git Token 必须由环境注入，禁止提交到仓库；`backend/.env`、`.env` 已在 `.gitignore` 中。
|
||
- 分享链接的访问密码当前为明文存储于 `share_links.access_pass`，见发布报告 P2 项。
|
||
|
||
## 📄 许可证
|
||
|
||
Copyright © 2026 Mula.liu
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Made with ❤️ by Mula.liu**
|
||
|
||
</div>
|