300 lines
8.5 KiB
Markdown
300 lines
8.5 KiB
Markdown
# 任务中心管理系统
|
||
|
||
一个基于Django的任务管理系统，支持客户端任务认领、执行和结果上传，适用于分布式任务处理场景。
|
||
|
||
## 功能特点
|
||
|
||
### 1. 任务管理
|
||
- 创建、查看、更新和删除任务
|
||
- 设置任务执行客户端（指定或自动分配）
|
||
- 配置任务超时时间
|
||
- 支持任务脚本存储
|
||
- 完整的任务生命周期管理
|
||
|
||
### 2. 客户端管理
|
||
- 客户端注册和身份验证
|
||
- 自动生成安全的API Token
|
||
- 客户端活跃状态跟踪
|
||
|
||
### 3. 任务执行流程
|
||
- **原子任务认领**：使用数据库事务确保并发安全，避免竞态条件
|
||
- 任务状态跟踪：待分配、已分配、执行中、成功、失败、重试中、超时
|
||
- 任务结果上传和下载
|
||
- 完整的任务执行API：认领、开始、完成
|
||
|
||
### 4. 系统管理
|
||
- 完整的后台管理界面
|
||
- 任务超时自动回收
|
||
- 结果文件管理
|
||
- API权限控制：所有API端点均需要认证
|
||
|
||
### 5. 前端界面
|
||
- 响应式设计，基于Bootstrap 5
|
||
- 任务管理：列表、创建、详情
|
||
- 客户端管理：列表、创建
|
||
- 结果查看和下载
|
||
|
||
## 技术栈
|
||
|
||
- **后端框架**：Django 5.0.6
|
||
- **API框架**：Django REST Framework
|
||
- **前端框架**：Bootstrap 5
|
||
- **数据库**：SQLite
|
||
- **文件存储**：本地文件系统
|
||
- **测试框架**：pytest + factory_boy
|
||
|
||
## 安装步骤
|
||
|
||
### 1. 环境要求
|
||
- Python 3.8+
|
||
- pip 20.0+
|
||
|
||
### 2. 克隆项目
|
||
```bash
|
||
git clone <repository-url>
|
||
cd 任务中心
|
||
```
|
||
|
||
### 3. 安装依赖
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
如果没有requirements.txt文件，请手动安装：
|
||
```bash
|
||
pip install djangorestframework pytest pytest-django factory_boy
|
||
```
|
||
|
||
### 4. 初始化数据库
|
||
```bash
|
||
python manage.py makemigrations
|
||
python manage.py migrate
|
||
```
|
||
|
||
### 5. 创建超级用户（用于后台管理）
|
||
```bash
|
||
python manage.py createsuperuser
|
||
```
|
||
|
||
## 启动和运行
|
||
|
||
### 1. 启动开发服务器
|
||
```bash
|
||
python manage.py runserver
|
||
```
|
||
|
||
服务器将在 `http://127.0.0.1:8000/` 运行
|
||
|
||
### 2. 访问系统
|
||
- **首页**：http://127.0.0.1:8000/
|
||
- **后台管理**：http://127.0.0.1:8000/admin/（使用超级用户登录）
|
||
- **API根路径**：http://127.0.0.1:8000/api/
|
||
|
||
## 使用方法
|
||
|
||
### 1. 后台管理
|
||
|
||
#### 1.1 登录后台
|
||
访问 `http://127.0.0.1:8000/admin/`，使用超级用户账号登录。
|
||
|
||
#### 1.2 管理客户端
|
||
- 在左侧菜单栏点击 "客户端"
|
||
- 点击 "添加客户端" 创建新客户端
|
||
- 系统会自动生成安全的API Token
|
||
|
||
#### 1.3 管理任务
|
||
- 在左侧菜单栏点击 "任务"
|
||
- 点击 "添加任务" 创建新任务
|
||
- 设置任务名称、指定客户端、脚本和超时时间
|
||
|
||
#### 1.4 查看任务结果
|
||
- 在任务详情页面可以查看关联的执行结果
|
||
- 可以直接下载结果文件
|
||
|
||
### 2. 前端界面
|
||
|
||
#### 2.1 首页
|
||
- 访问 `http://127.0.0.1:8000/`
|
||
- 查看系统功能概述
|
||
- 快速导航到各功能模块
|
||
|
||
#### 2.2 任务管理
|
||
- **任务列表**：查看所有任务，支持查看详情
|
||
- **创建任务**：表单创建新任务
|
||
- **任务详情**：查看任务执行历史和结果
|
||
|
||
#### 2.3 客户端管理
|
||
- 查看所有客户端列表
|
||
- 创建新客户端
|
||
- 获取客户端API Token
|
||
|
||
### 3. API使用
|
||
|
||
#### 3.1 认证方式
|
||
所有API请求需要在请求头中包含Token：
|
||
```
|
||
Authorization: Token <your-token>
|
||
```
|
||
|
||
**注意**：所有API端点均需要认证，使用 `IsAuthenticated` 权限类控制。
|
||
|
||
#### 3.2 主要API端点
|
||
|
||
| 端点 | 方法 | 功能 | 权限 |
|
||
|------|------|------|------|
|
||
| `/api/clients/` | GET | 获取客户端列表 | 需要认证 |
|
||
| `/api/clients/` | POST | 创建客户端 | 需要认证 |
|
||
| `/api/clients/<id>/` | GET | 获取客户端详情 | 需要认证 |
|
||
| `/api/clients/<id>/` | PUT | 更新客户端 | 需要认证 |
|
||
| `/api/clients/<id>/` | DELETE | 删除客户端 | 需要认证 |
|
||
| `/api/tasks/` | GET | 获取任务列表 | 需要认证 |
|
||
| `/api/tasks/` | POST | 创建任务 | 需要认证 |
|
||
| `/api/tasks/<id>/` | GET | 获取任务详情 | 需要认证 |
|
||
| `/api/tasks/<id>/` | PUT | 更新任务 | 需要认证 |
|
||
| `/api/tasks/<id>/` | DELETE | 删除任务 | 需要认证 |
|
||
| `/api/tasks/claim/` | POST | 客户端认领任务 | 需要认证 |
|
||
| `/api/tasks/<id>/start/` | POST | 开始执行任务 | 需要认证 |
|
||
| `/api/tasks/<id>/complete/` | POST | 完成任务 | 需要认证 |
|
||
| `/api/task_results/` | GET | 获取任务结果列表 | 需要认证 |
|
||
| `/api/task_results/` | POST | 上传任务结果 | 需要认证 |
|
||
| `/api/task_results/<id>/` | GET | 获取任务结果详情 | 需要认证 |
|
||
| `/api/task_results/<id>/` | DELETE | 删除任务结果 | 需要认证 |
|
||
| `/api/task_results/<id>/download/` | GET | 下载结果文件 | 需要认证 |
|
||
|
||
#### 3.3 API使用示例
|
||
|
||
##### 创建任务
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/tasks/ \
|
||
-H "Authorization: Token <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name":"测试任务","client_name":"client1","script":"echo \"Hello World\"","timeout_seconds":3600}'
|
||
```
|
||
|
||
##### 客户端认领任务
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/tasks/claim/ \
|
||
-H "Authorization: Token <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"client_name":"client1"}'
|
||
```
|
||
|
||
##### 开始执行任务
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/tasks/1/start/ \
|
||
-H "Authorization: Token <token>"
|
||
```
|
||
|
||
##### 完成任务
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/tasks/1/complete/ \
|
||
-H "Authorization: Token <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"status":"success","message":"任务执行成功"}'
|
||
```
|
||
|
||
##### 上传任务结果
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/task_results/ \
|
||
-H "Authorization: Token <token>" \
|
||
-F "task=1" \
|
||
-F "client=1" \
|
||
-F "status=success" \
|
||
-F "message=任务执行成功" \
|
||
-F "result_file=@result.txt"
|
||
```
|
||
|
||
##### 下载任务结果文件
|
||
```bash
|
||
curl -X GET http://127.0.0.1:8000/api/task_results/1/download/ \
|
||
-H "Authorization: Token <token>" \
|
||
-o result.txt
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
任务中心/
|
||
├── task_center/ # 项目配置
|
||
│ ├── settings.py # 项目设置
|
||
│ └── urls.py # 主URL配置
|
||
├── tasks/ # 任务应用
|
||
│ ├── models.py # 数据库模型
|
||
│ ├── serializers.py # API序列化器
|
||
│ ├── views.py # API视图（使用IsAuthenticated权限）
|
||
│ ├── views_frontend.py # 前端视图
|
||
│ ├── urls.py # 应用URL配置
|
||
│ ├── templates/ # 前端模板
|
||
│ ├── tests/ # 测试用例
|
||
│ └── management/ # 管理命令
|
||
├── media/ # 媒体文件存储
|
||
│ └── task_results/ # 任务结果文件
|
||
└── manage.py # 项目入口
|
||
```
|
||
|
||
## 管理命令
|
||
|
||
### 任务超时检查
|
||
定期检查并处理超时任务：
|
||
```bash
|
||
python manage.py check_task_timeouts
|
||
```
|
||
|
||
建议将此命令添加到系统定时任务中，例如每小时执行一次。
|
||
|
||
### 命令功能说明
|
||
- **check_task_timeouts**：检查所有执行中任务，将超过超时时间的任务标记为超时状态，使其可以被重新分配执行。
|
||
|
||
## 注意事项
|
||
|
||
1. **文件存储**：结果文件存储在 `media/task_results/` 目录下，请确保该目录有写入权限
|
||
2. **API Token安全**：请妥善保管客户端API Token，避免泄露
|
||
3. **API权限控制**：所有API端点均需要认证，使用 `IsAuthenticated` 权限类控制
|
||
4. **生产环境配置**：
|
||
- 建议使用PostgreSQL或MySQL数据库
|
||
- 配置合适的文件存储后端（如S3）
|
||
- 启用HTTPS
|
||
- 配置适当的日志记录
|
||
- 实现更细粒度的权限控制（如基于角色的权限）
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 开发和测试
|
||
|
||
### 运行测试
|
||
```bash
|
||
python manage.py test tasks
|
||
```
|
||
|
||
或使用pytest：
|
||
```bash
|
||
python -m pytest --ds=task_center.settings
|
||
```
|
||
|
||
### 代码结构
|
||
- 模型定义：`tasks/models.py`
|
||
- API视图：`tasks/views.py`
|
||
- 前端视图：`tasks/views_frontend.py`
|
||
- 模板文件：`tasks/templates/`
|
||
|
||
## 更新日志
|
||
|
||
### v1.1.0
|
||
- 增强API权限控制：所有API端点均使用 `IsAuthenticated` 权限类
|
||
- 完善API文档：更新API端点描述和使用示例
|
||
- 优化前端界面：改进任务和客户端管理功能
|
||
- 增强任务执行流程：完善认领、开始、完成的API实现
|
||
- 改进项目结构文档：添加媒体文件存储目录说明
|
||
|
||
### v1.0.0
|
||
- 初始版本发布
|
||
- 完成任务管理核心功能
|
||
- 实现客户端认证和任务认领
|
||
- 支持结果文件上传下载
|
||
- 完成前端界面开发
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请联系项目维护人员。 |