159 lines
4.3 KiB
Markdown
159 lines
4.3 KiB
Markdown
# 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. 安装依赖
|
||
|
||
```bash
|
||
# 激活虚拟环境
|
||
source venv/bin/activate # macOS/Linux
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
编辑 `.env` 文件，配置数据库连接等信息。
|
||
|
||
### 3. 初始化数据库
|
||
|
||
```bash
|
||
# 方式一：使用 SQL 脚本（推荐）
|
||
mysql -h10.100.51.51 -uroot -pUnis@321 < scripts/init_database.sql
|
||
|
||
# 方式二：使用 Python 脚本（仅创建表结构）
|
||
python scripts/init_db.py
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（自动重载）
|
||
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 进行数据库迁移：
|
||
|
||
```bash
|
||
# 生成迁移脚本
|
||
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
|