PPGo_Job 定时任务管理系统
====

一款轻量级定时任务管理系统，基于 **GoFrame v2** 重构。支持 **本机执行** 和 **SSH 远程执行**，部署简单，资源消耗少。

## 技术栈

- **后端框架：** GoFrame v2
- **数据库：** SQLite（纯 Go 驱动 `modernc.org/sqlite`，无需 CGO）
- **定时任务：** GoFrame `gcron`
- **前端：** Vue 3 + Element Plus + TypeScript（`frontend/` 目录）
- **旧前端（兼容）：** LayUI 模板（`resource/template/`）
- **远程执行：** SSH（`golang.org/x/crypto/ssh`）

## 快速开始

```bash
# 方式一：一键构建（前端 + 后端）
build_frontend.cmd

# 方式二：分步构建
# 1. 构建前端（首次或修改前端后需要）
cd frontend
npm install
npm run build
cd ..

# 2. 编译（纯 Go，不需要 gcc/MinGW）
CGO_ENABLED=0 go build -o ppgo_job.exe .

# 3. 运行
./ppgo_job.exe
```

> 首次启动自动在 `./data/ppgo_job.db` 创建 SQLite 数据库、表和默认管理员。

**访问地址：** http://localhost:8082
**新前端：** http://localhost:8082/app/（Vue 3 + Element Plus）
**旧前端：** http://localhost:8082/（LayUI，兼容保留）
**默认账号：** admin / **密码：** 123456

## 运行测试

```bash
# 运行所有测试
CGO_ENABLED=0 go test -count=1 ./...

# 运行单元测试（libs、consts、dao，无需启动服务器）
CGO_ENABLED=0 go test -count=1 ./libs/ ./consts/ ./dao/

# 运行集成测试（自动启动测试服务器，端口 18082）
CGO_ENABLED=0 go test -count=1 -timeout=120s -run "TestLogin|TestAuth|TestHome|TestTask|TestServer|TestGroup|TestBan|TestTemplate|TestStatic|TestDatabase|TestCORS" .

# 运行特定包测试
CGO_ENABLED=0 go test -v -count=1 ./libs/
```

> 集成测试覆盖登录、认证拦截、CRUD 操作、模板渲染、静态文件、CORS 头、数据库种子数据等功能。
> 测试使用独立的端口 `:18082`，不会干扰正在运行的开发实例。

---

## 📖 使用指南

### 1. 登录

打开浏览器访问 `http://localhost:8082`，输入默认账号 `admin` / `123456` 登录。

> 💡 如果访问时遇到"重定向次数过多"，清除浏览器 Cookie 后刷新即可。

---

### 2. 首页仪表盘

登录后进入系统首页，展示：
- **任务概览** — 总任务数、运行中、待审核
- **近期执行统计** — 过去 7 天的成功/失败/超时柱状图
- **即将执行的任务** — 最近将要触发的定时任务
- **系统信息** — 运行时间、内存使用、goroutine 数量

---

### 3. 任务管理

#### 3.1 新增任务

左侧菜单「任务管理 → 任务列表」→ 点击「新增」按钮。

必填字段：
| 字段 | 说明 | 示例 |
|------|------|------|
| 任务名称 | 有意义的名称 | `数据库备份` |
| Cron 表达式 | **6 段格式（含秒）** | `0 0 3 * * *`（每天凌晨 3 点） |
| 执行命令 | 要执行的 shell 命令 | `mysqldump -u root db1 > /backup.sql` |
| 超时时间 | 超时后自动终止（秒） | `300`（5 分钟） |

> ⚠️ **Cron 表达式注意事项：**
> 本项目使用 GoFrame `gcron`，Cron 表达式为 **6 段格式**（比标准多一位秒）：
>
> ```
> 秒 分 时 日 月 周
> ```
>
> 常用示例：
> - `0 */5 * * * *` — 每 5 分钟
> - `0 0 3 * * *` — 每天凌晨 3 点
> - `0 30 9 * * 1-5` — 工作日 9:30
> - `0 0 0 1 * *` — 每月 1 号零点
>
> 如果误填了标准 5 段表达式，系统会提示 `invalid pattern` 错误。

可选字段：
- **任务分组** — 归类管理
- **执行服务器** — 选择远程服务器（留空 = 本机执行）
- **执行方式** — 同时执行（所有服务器一起跑） / 轮询执行（逐台跑）
- **允许并发** — 默认不允许（上一个未执行完，下一个不会触发）
- **失败通知** — 勾选后可选择通知模板和接收人

#### 3.2 任务列表

列表展示了所有任务，支持：
- **按状态筛选** — 下拉框选择运行中/已暂停/待审核/审核失败
- **按分组筛选** — 下拉框选择任务分组
- **按名称搜索** — 输入关键字后点查询
- **表头排序** — 点击 ID 列头切换正序/倒序
- **表格操作按钮：**

| 按钮 | 功能 |
|------|------|
| 🔍 详细 | 查看任务完整信息 |
| ✏️ 编辑 | 修改任务参数 |
| ▶️ 启动 | 将暂停的任务加入调度 |
| ⏸️ 暂停 | 从调度中移除（暂不执行） |
| ▶️ 测试 | **立即执行一次**（不依赖 Cron 触发） |
| 📋 日志 | 查看该任务的执行记录 |
| 📝 复制 | 基于现有任务创建新任务 |
| 🗑️ 删除 | 软删除（可在数据库恢复） |

#### 3.3 任务审核

超级管理员 `admin` 创建的任务自动进入暂停状态；普通账号创建的任务进入「待审核」状态，需要管理员在「任务管理 → 任务审核」中通过后才能启动。

---

### 4. 服务器管理

#### 4.1 新增服务器

「服务器管理 → 服务器列表」→ 点击「新增」。

| 字段 | 说明 | 示例 |
|------|------|------|
| 服务器名称 | 标识名称 | `Web 服务器 01` |
| 连接方式 | SSH / Telnet / Agent | SSH |
| IP 地址 | 连接 IP | `192.168.1.100` |
| 端口 | SSH 默认 22 | `22` |
| 账号 | 登录用户名 | `root` |
| 密码/密钥 | 密码或私钥内容 | — |

> SSH 远程执行已实现，支持密码和密钥认证。创建任务时选择配置好的服务器即可远程执行。

#### 4.2 资源分组

将服务器归类管理。多个服务器可以属于同一个资源组，方便在创建任务时批量选择。

---

### 5. 系统设置

#### 5.1 任务分组

对任务进行分类，例如：`数据备份`、`日志清理`、`监控脚本`。

#### 5.2 禁用命令

设置禁止执行的关键词。创建/编辑任务时，如果命令包含禁用词（如 `rm -rf`），系统会拒绝保存。

#### 5.3 通知模板

配置任务执行失败时的通知内容。支持变量占位符：`{{task_name}}`、`{{status}}`。

> 邮件通知已实现（`net/smtp`），任务失败时自动发送邮件到通知人。

---

### 6. 执行日志

「日志管理 → 执行日志」查看所有任务的执行记录。

| 字段 | 说明 |
|------|------|
| 状态 | ✅ 成功 / ❌ 失败 / ⏰ 超时 |
| 耗时 | 执行耗时（毫秒） |
| 执行时间 | 触发时间 |
| 输出 | 命令的标准输出 |
| 错误 | 错误信息（如果有） |

支持按任务 ID 筛选、分页浏览、查看详情和删除。

---

### 7. 权限管理

#### 7.1 权限因子

系统内置的菜单和功能权限，支持新增/编辑/删除。每个权限对应一个侧边栏菜单项。

权限结构为两级：
- **一级菜单** — 如「任务管理」「服务器管理」
- **二级菜单** — 如「任务列表」「任务审核」

#### 7.2 角色管理

创建角色并绑定权限，支持数据权限控制（限制可查看的服务器组和任务组）。

例如创建一个「运维人员」角色，只赋予任务管理和日志查看权限。

#### 7.3 管理员管理

创建系统用户，可关联角色。新增的管理员默认密码 `123456`。

> `admin` 是超级管理员，**不能被禁用**，拥有全部权限。

---

### 8. 个人资料

右上角用户头像 → 可修改个人资料（姓名、电话、邮箱、钉钉/微信等）及修改密码。

---

## 注意事项

### ⚡ Cron 表达式格式

本项目使用 **6 段格式**（含秒），不要使用标准 5 段格式：

```
✅ 正确: 0 0 3 * * *    (每天凌晨 3 点)
❌ 错误: 0 3 * * *      (缺少秒字段 → 报错)
✅ 正确: 0 */5 * * * *  (每 5 分钟)
```

### 🔒 端口冲突

如果启动提示 `bind: Only one usage of each socket address`，说明端口 8082 已被占用：

```bash
# 查看谁占了端口
netstat -ano | findstr 8082

# 杀掉进程（PID 替换为实际值）
taskkill //PID 进程号 //F

# 或者修改 config.yml 换个端口
```

### 💾 数据库

SQLite 数据库文件在 `./data/ppgo_job.db`，直接复制即可备份。如需重置，删除该文件后重启服务即可自动重建。

---

## 项目结构

```
├── main.go              # 入口
├── config.yml           # 配置文件
├── boot/                # 启动初始化
│   ├── db.go            # 数据库目录初始化
│   ├── router.go        # 路由注册 + 路由表
│   ├── tplfunc.go       # 模板函数（urlfor/date/substr）
│   └── init.go          # 自动建表 + 种子数据 + 加载调度任务
├── frontend/            # Vue 3 前端工程
│   ├── src/             # 源码（api/router/stores/views/layout）
│   ├── dist/            # 构建产物（Go 静态文件服务）
│   ├── vite.config.ts
│   └── package.json
├── controller/          # HTTP 控制器
│   ├── base.go          # display/ajaxMsg/ajaxList 辅助函数
│   ├── response.go      # 统一 JSON 响应格式
│   ├── api.go           # Vue 前端专用 API 端点
│   ├── login.go         # 登录/登出（Cookie+JWT 双认证）
│   ├── home.go          # 首页仪表盘
│   ├── task.go          # 任务/服务器/分组/日志/CRUD
│   ├── admin.go         # 服务器/分组/禁用命令/通知模板 CRUD
│   ├── system.go        # 权限因子/角色/管理员/个人资料 CRUD
│   └── spa.go           # SPA 静态文件服务
├── service/
│   └── scheduler/       # 任务调度 + 执行引擎
│       ├── scheduler.go # gcron 调度管理
│       ├── task_runner.go # 命令执行器（本地/远程）
│       ├── ssh.go       # SSH 远程连接器
│       └── notify.go    # 邮件通知实现
├── dao/                 # 数据访问层
├── model/entity/        # 数据库实体（含字段常量）
├── middleware/           # 认证中间件（Cookie + JWT 双认证）
├── libs/                # 工具函数（密码哈希/JWT/加密）
├── consts/              # 常量定义
└── resource/
    ├── template/        # LayUI 模板（旧前端）
    └── static/          # JS/CSS/字体（旧前端）
```

## 配置文件（`config.yml`）

```yaml
server:
  address: ":8082"             # 监听端口
  name: "ppgo_job"
  logStdout: true              # 日志输出到控制台

database:
  default:
    type: sqlite               # 数据库类型（仅支持 sqlite）
    name: "./data/ppgo_job.db"

jobs:
  pool: 1000                   # 任务并发池大小

site:
  name: "定时任务管理器"        # 站点标题
```

## API 接口

### 新前端 API（`/api/*`，JWT 认证）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/login_in` | POST | 登录（返回 JWT token） |
| `/api/user_info` | GET | 当前用户信息 + 菜单树 |
| `/api/dashboard` | GET | 仪表盘统计数据（含 7 天图表） |
| `/api/task/table` | GET | 任务列表（支持 status/group_id/task_name 筛选，field/order 排序） |
| `/api/task/save` | POST | 新增/编辑任务 |
| `/api/task/start` | POST | 启动任务 |
| `/api/task/pause` | POST | 暂停任务 |
| `/api/task/del` | POST | 删除任务 |
| `/api/task/run` | POST | 立即执行 |
| `/api/task/audit` | POST | 审核通过 |
| `/api/task/nopass` | POST | 审核不通过 |
| `/api/task/add_data` | GET | 新增任务的关联数据（分组/服务器/通知人） |
| `/api/task/edit_data` | GET | 编辑任务的数据 |
| `/api/task/detail_data` | GET | 任务详情 |
| `/api/server/table` | GET | 服务器列表 |
| `/api/server/save` | POST | 新增/编辑服务器 |
| `/api/server/del` | POST | 删除服务器 |
| `/api/group/table` | GET | 任务分组列表 |
| `/api/server_group/table` | GET | 资源分组列表 |
| `/api/ban/table` | GET | 禁用命令列表 |
| `/api/notify_tpl/table` | GET | 通知模板列表 |
| `/api/auth/nodes` | GET | 权限树 |
| `/api/role/table` | GET | 角色列表 |
| `/api/admin/table` | GET | 管理员列表 |
| `/api/task_log/table` | GET | 执行日志列表（支持 status/task_id 筛选） |
| `/api/profile` | GET | 个人资料 |
| `/api/user/save` | POST | 修改个人资料 |

### 旧前端 API（Cookie 认证，兼容保留）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/login_in` | POST | 登录 |
| `/task/ajax_save` | POST | 新增/编辑任务 |
| `/task/ajax_del` | POST | 删除任务 |
| ... | ... | 其他 `ajax_*` 端点同旧版 |

完整路由见 `boot/router.go`。

## 编译部署

```bash
# 本地运行（含前端构建）
build_frontend.cmd

# 或分步运行
cd frontend && npm install && npm run build && cd ..
CGO_ENABLED=0 go build -o ppgo_job.exe . && ./ppgo_job.exe

# 仅编译后端
CGO_ENABLED=0 go build -o ppgo_job.exe .

# Linux 交叉编译
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ppgo_job .

# Windows 交叉编译
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o ppgo_job.exe .

# Mac 交叉编译
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o ppgo_job .
```

## 已知限制

- **Telnet/Agent 远程执行** — 已实现 SSH，Telnet 和 Agent 模式尚未支持
- **钉钉/微信通知** — 已实现邮件通知，钉钉和微信待补充
- **Agent API** — 远程 Agent 注册和管理暂未实现
- **旧前端兼容** — LayUI 前端保留但不再维护，新功能仅添加到 Vue 前端

## License

MIT