From 513188525aa1f5920999263247bfaf1fb3d1670f Mon Sep 17 00:00:00 2001 From: xiaji Date: Fri, 5 Dec 2025 13:55:24 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9B=E5=BB=BAreadme=E7=9A=84=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 245 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ece5bf6 --- /dev/null +++ b/README.md @@ -0,0 +1,245 @@ +# 任务中心管理系统 + +一个基于Django的任务管理系统，支持客户端任务认领、执行和结果上传，适用于分布式任务处理场景。 + +## 功能特点 + +### 1. 任务管理 +- 创建、查看、更新和删除任务 +- 设置任务执行客户端（指定或自动分配） +- 配置任务超时时间 +- 支持任务脚本存储 + +### 2. 客户端管理 +- 客户端注册和身份验证 +- 自动生成API Token +- 客户端活跃状态跟踪 + +### 3. 任务执行流程 +- **原子任务认领**：避免竞态条件 +- 任务状态跟踪：待分配、已分配、执行中、成功、失败、重试中、超时 +- 任务结果上传和下载 + +### 4. 系统管理 +- 完整的后台管理界面 +- 任务超时自动回收 +- 结果文件管理 + +## 技术栈 + +- **后端框架**：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 +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 +``` + +#### 3.2 主要API端点 + +| 端点 | 方法 | 功能 | +|------|------|------| +| `/api/clients/` | GET | 获取客户端列表 | +| `/api/clients/` | POST | 创建客户端 | +| `/api/tasks/` | GET | 获取任务列表 | +| `/api/tasks/` | POST | 创建任务 | +| `/api/tasks/claim/` | POST | 客户端认领任务 | +| `/api/tasks//start/` | POST | 开始执行任务 | +| `/api/tasks//complete/` | POST | 完成任务 | +| `/api/task_results/` | POST | 上传任务结果 | +| `/api/task_results//download/` | GET | 下载结果文件 | + +#### 3.3 API使用示例 + +##### 创建任务 +```bash +curl -X POST http://127.0.0.1:8000/api/tasks/ \ + -H "Authorization: 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 " \ + -H "Content-Type: application/json" \ + -d '{"client_name":"client1"}' +``` + +##### 上传任务结果 +```bash +curl -X POST http://127.0.0.1:8000/api/task_results/ \ + -H "Authorization: Token " \ + -F "task=1" \ + -F "client=1" \ + -F "status=success" \ + -F "message=任务执行成功" \ + -F "result_file=@result.txt" +``` + +## 项目结构 + +``` +task_center/ +├── task_center/ # 项目配置 +│ ├── settings.py # 项目设置 +│ └── urls.py # 主URL配置 +├── tasks/ # 任务应用 +│ ├── models.py # 数据库模型 +│ ├── serializers.py # API序列化器 +│ ├── views.py # API视图 +│ ├── views_frontend.py # 前端视图 +│ ├── urls.py # 应用URL配置 +│ ├── templates/ # 前端模板 +│ ├── tests/ # 测试用例 +│ └── management/ # 管理命令 +└── manage.py # 项目入口 +``` + +## 管理命令 + +### 任务超时检查 +定期检查并处理超时任务： +```bash +python manage.py check_task_timeouts +``` + +建议将此命令添加到系统定时任务中，例如每小时执行一次。 + +## 注意事项 + +1. **文件存储**：结果文件存储在 `media/task_results/` 目录下，请确保该目录有写入权限 +2. **API Token安全**：请妥善保管客户端API Token，避免泄露 +3. **生产环境配置**： + - 建议使用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.0.0 +- 初始版本发布 +- 完成任务管理核心功能 +- 实现客户端认证和任务认领 +- 支持结果文件上传下载 +- 完成前端界面开发 + +## 联系方式 + +如有问题或建议，请联系项目维护人员。 \ No newline at end of file