# NEX Docus 文档管理平台
一个轻量级、高性能的团队协作文档管理平台
[](LICENSE)
[](https://www.python.org/)
[](https://reactjs.org/)
[](https://fastapi.tiangolo.com/)
---
## ✨ 特性
- 🚀 **高性能**: FastAPI 异步后端 + React 18 前端
- 📁 **文件存储**: 数据库管理权限 + 文件系统存储内容
- 🔐 **权限控制**: 完整的 RBAC 权限体系
- 📝 **Markdown 编辑**: 实时预览、图片上传
- 👥 **团队协作**: 项目成员管理、角色分配
- 🌲 **目录树**: 无限层级目录支持
- 💾 **数据安全**: 文件即真理、易于备份和迁移
---
## 🏗️ 技术架构
### 后端技术栈
- **框架**: FastAPI (Python 3.9+)
- **ORM**: SQLAlchemy 2.0 (异步)
- **数据库**: MySQL 5.7.5+
- **缓存**: Redis
- **认证**: JWT (PyJWT)
- **文件**: aiofiles (异步 I/O)
### 前端技术栈
- **框架**: React 18
- **构建工具**: Vite
- **UI 组件**: Ant Design 5
- **路由**: React Router v6
- **状态管理**: Zustand
- **Markdown**: @uiw/react-md-editor
- **样式**: Tailwind CSS
---
## 📦 项目结构
```
NEX Docus/
├── backend/ # FastAPI 后端服务
│ ├── app/
│ │ ├── api/v1/ # API 路由（v1）
│ │ ├── core/ # 核心配置
│ │ ├── models/ # 数据库模型
│ │ ├── schemas/ # Pydantic Schemas
│ │ ├── services/ # 业务逻辑服务
│ │ └── middleware/ # 中间件
│ ├── scripts/ # 初始化脚本
│ └── main.py # 应用入口
│
├── frontend/ # React 前端应用
│ ├── src/
│ │ ├── api/ # API 封装
│ │ ├── components/ # 通用组件
│ │ ├── pages/ # 页面组件
│ │ ├── stores/ # 状态管理
│ │ └── utils/ # 工具函数
│ └── package.json
│
├── DATABASE.md # 数据库设计文档
├── PROJECT.md # 技术方案文档
├── QUICKSTART.md # 快速启动指南
└── IMPLEMENTATION_PLAN.md # 实施计划
```
---
## 🚀 快速开始
### 前置要求
- Python 3.9.6+
- Node.js 16+
- MySQL 5.7.5+
- Redis (最新版)
### 1. 初始化数据库
```bash
mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql
```
### 2. 启动后端
```bash
cd backend
source venv/bin/activate
pip install -r requirements.txt
python main.py
```
后端将运行在 http://localhost:8000
### 3. 启动前端
```bash
cd frontend
npm install
npm run dev
```
前端将运行在 http://localhost:5173
### 4. 登录使用
- **用户名**: `admin`
- **密码**: `admin123`
---
## 📖 核心功能
### 用户认证
- ✅ 用户注册/登录
- ✅ JWT Token 认证
- ✅ 密码加密存储
- ✅ 权限角色管理
### 项目管理
- ✅ 创建/编辑/删除项目
- ✅ 项目成员管理
- ✅ 访问权限控制
- ✅ 项目归档
### 文档编辑
- ✅ Markdown 实时预览
- ✅ 无限层级目录
- ✅ 文件/文件夹操作
- ✅ 图片/附件上传
- ✅ 自动保存
---
## 🗂️ 数据库设计
### 核心表结构
- `users` - 用户表
- `roles` - 角色表
- `user_roles` - 用户角色关联
- `system_menus` - 系统菜单
- `role_menus` - 角色菜单授权
- `projects` - 项目表
- `project_members` - 项目成员
- `document_meta` - 文档元数据（可选）
- `operation_logs` - 操作日志
详细设计请查看 [DATABASE.md](DATABASE.md)
---
## 🔒 安全特性
- ✅ **密码加密**: bcrypt 加密存储
- ✅ **JWT 认证**: 访问令牌机制
- ✅ **路径安全**: 防止路径穿越攻击
- ✅ **权限校验**: 基于角色的访问控制
- ✅ **SQL 注入防护**: ORM 自动防护
- ✅ **CORS 配置**: 跨域请求控制
---
## 📋 API 文档
启动后端后访问：
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
### 主要接口
**认证**
- `POST /api/v1/auth/register` - 注册
- `POST /api/v1/auth/login` - 登录
- `GET /api/v1/auth/me` - 获取当前用户
**项目**
- `GET /api/v1/projects/` - 项目列表
- `POST /api/v1/projects/` - 创建项目
- `GET /api/v1/projects/{id}` - 项目详情
- `PUT /api/v1/projects/{id}` - 更新项目
- `DELETE /api/v1/projects/{id}` - 删除项目
**文件**
- `GET /api/v1/files/{project_id}/tree` - 目录树
- `GET /api/v1/files/{project_id}/file` - 文件内容
- `POST /api/v1/files/{project_id}/file` - 保存文件
- `POST /api/v1/files/{project_id}/upload` - 上传文件
---
## 🛠️ 开发指南
### 后端开发
1. 添加新的数据模型到 `backend/app/models/`
2. 定义 Pydantic Schema 到 `backend/app/schemas/`
3. 在 `backend/app/api/v1/` 创建路由
4. 实现业务逻辑到 `backend/app/services/`
### 前端开发
1. 在 `frontend/src/api/` 封装 API 请求
2. 在 `frontend/src/pages/` 创建页面组件
3. 在 `frontend/src/App.jsx` 添加路由
4. 使用 Zustand 管理全局状态
---
## 📝 文档
- [技术方案文档](PROJECT.md) - 完整的技术设计方案
- [数据库设计](DATABASE.md) - 数据库表结构设计
- [快速启动指南](QUICKSTART.md) - 5分钟快速上手
- [实施计划](IMPLEMENTATION_PLAN.md) - 分阶段实施计划
---
## 🔄 版本历史
### v1.0.0 (2023-12-20)
- ✅ 完整的用户认证系统
- ✅ 项目管理功能
- ✅ Markdown 文档编辑
- ✅ 文件系统管理
- ✅ 权限控制体系
- ✅ 团队协作功能
---
## 📄 许可证
Copyright © 2023 Mula.liu
---
## 🙏 致谢
感谢以下开源项目：
- [FastAPI](https://fastapi.tiangolo.com/)
- [React](https://reactjs.org/)
- [Ant Design](https://ant.design/)
- [SQLAlchemy](https://www.sqlalchemy.org/)
- [Vite](https://vitejs.dev/)
---
**Made with ❤️ by Mula.liu**