nex_docus/backend

NEX Docus Backend

NEX Docus 后端服务 - 基于 FastAPI 构建的高性能文档管理平台。

技术栈

• 框架: FastAPI 0.109+
• 数据库: MySQL 5.7.5+ (通过 SQLAlchemy 2.0 异步 ORM)
• 缓存: Redis
• 认证: JWT (python-jose)
• 密码加密: bcrypt (passlib)
• 文件处理: aiofiles (异步文件 I/O)

项目结构

backend/
├── app/
│   ├── api/
│   │   └── v1/          # API 路由（v1 版本）
│   │       ├── auth.py      # 用户认证
│   │       ├── projects.py  # 项目管理
│   │       └── files.py     # 文件系统
│   ├── core/            # 核心配置
│   │   ├── config.py        # 应用配置
│   │   ├── database.py      # 数据库连接
│   │   ├── security.py      # 安全工具
│   │   └── deps.py          # 依赖注入
│   ├── models/          # 数据库模型
│   ├── schemas/         # Pydantic Schemas
│   ├── services/        # 业务逻辑
│   ├── middleware/      # 中间件
│   └── utils/           # 工具函数
├── scripts/             # 脚本文件
│   ├── init_database.sql    # 数据库初始化 SQL
│   └── init_db.py           # 数据库初始化 Python 脚本
├── tests/               # 测试文件
├── main.py              # 应用入口
├── requirements.txt     # 依赖包
└── .env                 # 环境配置

快速开始

1. 安装依赖

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

2. 配置环境变量

编辑 .env 文件，配置数据库连接等信息。

3. 初始化数据库

# 方式一：使用 SQL 脚本（推荐）
mysql -h10.100.51.51 -uroot -pUnis@321 < scripts/init_database.sql

# 方式二：使用 Python 脚本（仅创建表结构）
python scripts/init_db.py

4. 启动服务

# 开发模式（自动重载）
python main.py

# 或使用 uvicorn
uvicorn main:app --reload --host 0.0.0.0 --port 8000

服务启动后，访问：

• API 文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health

API 接口

认证相关 (/api/v1/auth)

• POST /register - 用户注册
• POST /login - 用户登录
• GET /me - 获取当前用户信息
• POST /change-password - 修改密码

项目管理 (/api/v1/projects)

• GET / - 获取我的项目列表
• POST / - 创建新项目
• GET /{project_id} - 获取项目详情
• PUT /{project_id} - 更新项目信息
• DELETE /{project_id} - 删除项目（归档）
• GET /{project_id}/members - 获取项目成员
• POST /{project_id}/members - 添加项目成员

文件系统 (/api/v1/files)

• GET /{project_id}/tree - 获取项目目录树
• GET /{project_id}/file?path=xxx - 获取文件内容
• POST /{project_id}/file - 保存文件内容
• POST /{project_id}/file/operate - 文件操作（重命名/删除/创建）
• POST /{project_id}/upload - 上传文件（图片/附件）
• GET /{project_id}/assets/{subfolder}/{filename} - 获取资源文件

默认账号

初始化数据库后，会创建默认管理员账号：

• 用户名: admin
• 密码: admin123

⚠️ 生产环境请立即修改默认密码！

开发指南

代码风格

遵循 PEP 8 代码规范。

添加新的 API 端点

1. 在 app/api/v1/ 下创建新的路由文件
2. 在 app/api/v1/__init__.py 中注册路由
3. 在 app/schemas/ 中定义 Pydantic Schema
4. 在 app/services/ 中实现业务逻辑

数据库迁移

使用 Alembic 进行数据库迁移：

# 生成迁移脚本
alembic revision --autogenerate -m "描述"

# 执行迁移
alembic upgrade head

安全说明

1. 路径安全: 所有文件系统操作都经过路径安全检查，防止路径穿越攻击
2. 认证鉴权: 使用 JWT Token 认证，所有需要登录的接口都受保护
3. 权限控制: 实现了项目级别的权限控制（owner/admin/editor/viewer）
4. 密码加密: 使用 bcrypt 加密存储密码
5. SQL 注入: 使用 SQLAlchemy ORM，自动防止 SQL 注入

许可证

Copyright © 2023 Mula.liu