mula
/
nex_docus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_docus/README.md

6.0 KiB
Raw Blame History

NEX Docus 文档管理平台

一个轻量级、高性能的团队协作文档管理平台

License Python React FastAPI

✨ 特性

  • 🚀 高性能: 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          # 应用入口
│
├── forntend/            # 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. 初始化数据库

mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql

2. 启动后端

cd backend
source venv/bin/activate
pip install -r requirements.txt
python main.py

后端将运行在 http://localhost:8000

3. 启动前端

cd forntend
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

🔒 安全特性

  • ✅ 密码加密: bcrypt 加密存储
  • ✅ JWT 认证: 访问令牌机制
  • ✅ 路径安全: 防止路径穿越攻击
  • ✅ 权限校验: 基于角色的访问控制
  • ✅ SQL 注入防护: ORM 自动防护
  • ✅ CORS 配置: 跨域请求控制

📋 API 文档

启动后端后访问：

主要接口

认证

  • 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. 在 forntend/src/api/ 封装 API 请求
  2. 在 forntend/src/pages/ 创建页面组件
  3. 在 forntend/src/App.jsx 添加路由
  4. 使用 Zustand 管理全局状态

📝 文档

🔄 版本历史

v1.0.0 (2023-12-20)

  • ✅ 完整的用户认证系统
  • ✅ 项目管理功能
  • ✅ Markdown 文档编辑
  • ✅ 文件系统管理
  • ✅ 权限控制体系
  • ✅ 团队协作功能

📄 许可证

Copyright © 2023 Mula.liu

🙏 致谢

感谢以下开源项目：

Made with ❤️ by Mula.liu