# 白虎面板 (Baihu Panel)

<p align="center">
  <strong>轻量级定时任务管理系统</strong>
</p>

<p align="center">
  基于 Go + Vue 3 构建，单文件部署，开箱即用
</p>

<p align="center">
  <a href="#功能特性">功能特性</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#配置说明">配置说明</a> •
  <a href="#开发指南">开发指南</a>
</p>

---

## ✨ 功能特性

### 📋 定时任务管理
- 支持标准 Cron 表达式调度
- 常用时间规则快捷选择
- 任务启用/禁用状态切换
- 手动触发执行
- 任务超时控制

### 📝 脚本文件管理
- 在线代码编辑器
- 文件树形结构展示
- 支持创建、重命名、删除文件/文件夹
- 支持压缩包上传解压
- 支持多文件批量上传

### 🖥️ 在线终端
- WebSocket 实时终端
- 支持常用 Shell 命令
- 命令执行结果实时输出

### 📊 执行日志
- 任务执行历史记录
- 执行状态追踪（成功/失败/超时）
- 执行耗时统计
- 日志内容压缩存储
- 支持按任务名称搜索
- 日志自动清理

### 🔐 环境变量
- 安全存储敏感配置
- 变量值脱敏显示
- 任务执行时自动注入

### ⚙️ 系统设置
- 站点标题、标语自定义
- 站点图标自定义（SVG）
- 分页大小配置
- Cookie 有效期配置
- 密码修改
- 系统信息查看

### 🎨 界面特性
- 响应式设计
- 深色/浅色主题切换
- 现代化 UI 组件

### 🔒 安全特性
- JWT Token 认证
- 密码加盐哈希存储
- 启动时自动生成随机密钥
- Cookie HttpOnly 保护

---

## 🚀 快速开始

### 方式一：Docker 部署（推荐）

**使用预构建镜像：**

```bash
docker run -d \
  --name baihu \
  -p 8052:8052 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/configs:/app/configs \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  ghcr.io/engigu/baihu:main
```

**使用 Docker Compose：**

创建 `docker-compose.yml`：

```yaml
version: '3.8'

services:
  baihu:
    image: ghcr.io/engigu/baihu:main
    container_name: baihu
    ports:
      - "8052:8052"
    volumes:
      - ./data:/app/data
      - ./configs:/app/configs
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped
```

启动服务：

```bash
docker-compose up -d
```

### 方式二：本地构建运行

**环境要求：**
- Go 1.21+
- Node.js 18+
- Make

**构建步骤：**

```bash
# 克隆项目
git clone https://github.com/engigu/baihu.git
cd baihu

# 安装依赖
make deps
cd web && npm install && cd ..

# 构建前端 + 后端
make build-all

# 运行
./baihu
```

### 访问面板

启动后访问：http://localhost:8052

**默认账号：**
- 用户名：`admin`
- 密码：`123456`

> ⚠️ **安全提示**：首次登录后请立即修改默认密码

---

## 📁 目录结构

```
./
├── baihu                 # 可执行文件
├── data/                 # 数据目录（自动创建）
│   ├── ql.db             # SQLite 数据库
│   └── scripts/          # 脚本文件存储
└── configs/
    └── config.ini        # 配置文件（自动创建）
```

---

## ⚙️ 配置说明

配置文件路径：`configs/config.ini`

```ini
[server]
port = 8052
host = 0.0.0.0

[database]
type = sqlite
host = localhost
port = 3306
user = root
password = 
dbname = ql_panel
table_prefix = baihu_
```

### 配置项说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `server.port` | 服务端口 | 8052 |
| `server.host` | 监听地址 | 0.0.0.0 |
| `database.type` | 数据库类型 | sqlite |
| `database.table_prefix` | 表前缀 | baihu_ |

### 站点设置

以下设置可在管理面板「系统设置 > 站点设置」中配置：

| 设置项 | 说明 | 默认值 |
|--------|------|--------|
| 站点标题 | 显示在浏览器标签和侧边栏 | 白虎面板 |
| 站点标语 | 显示在登录页 | 轻量级定时任务管理系统 |
| 站点图标 | SVG 格式，用于 favicon 和登录页 | 内置图标 |
| 分页大小 | 列表每页显示条数 | 10 |
| Cookie 有效期 | 登录状态保持天数 | 7 |

### 调度设置

以下设置可在管理面板「系统设置 > 调度设置」中配置，用于优化任务执行性能：

| 设置项 | 说明 | 默认值 |
|--------|------|--------|
| Worker 数量 | 并发执行任务的 worker 数量 | 4 |
| 队列大小 | 任务队列缓冲区大小 | 100 |
| 速率间隔 | 任务启动间隔（毫秒），200ms = 每秒最多 5 个任务 | 200 |

**调度机制说明：**

系统采用 Worker Pool + 任务队列的架构来控制任务执行：

1. **Worker Pool**：固定数量的 worker 从队列中取任务执行，避免 cron 触发时无限并发
2. **任务队列**：cron 调度器触发的任务先入队，由 worker 按顺序执行
3. **速率限制**：控制任务启动频率，防止秒级 cron 同时触发多个进程导致 CPU 峰值
4. **热重载**：修改调度设置后立即生效，无需重启服务

---

## 🛠️ 技术栈

### 后端
- **Go 1.21+** - 编程语言
- **Gin** - Web 框架
- **GORM** - ORM 框架
- **SQLite** - 嵌入式数据库
- **JWT** - 身份认证
- **Cron** - 定时任务调度
- **WebSocket** - 实时通信

### 前端
- **Vue 3** - 前端框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Tailwind CSS** - 样式框架
- **Shadcn/ui** - UI 组件库
- **Xterm.js** - 终端模拟器

### 部署
- **Docker** - 容器化部署
- **GitHub Actions** - CI/CD
- **Multi-arch** - 支持 amd64/arm64

---

## 📖 开发指南

### 项目结构

```
├── main.go                    # 入口文件
├── internal/
│   ├── bootstrap/             # 应用启动
│   ├── constant/              # 常量定义
│   ├── controllers/           # 控制器层
│   ├── database/              # 数据库初始化
│   ├── middleware/            # 中间件
│   ├── models/                # 数据模型
│   ├── router/                # 路由注册
│   ├── services/              # 业务逻辑层
│   ├── static/                # 静态文件嵌入
│   └── utils/                 # 工具函数
├── web/                       # 前端项目
│   ├── src/
│   │   ├── api/               # API 接口
│   │   ├── components/        # 公共组件
│   │   ├── composables/       # 组合式函数
│   │   ├── layouts/           # 布局组件
│   │   ├── router/            # 路由配置
│   │   └── views/             # 页面视图
│   └── ...
├── configs/                   # 配置文件
├── data/                      # 数据目录
├── Dockerfile                 # Docker 构建
├── Makefile                   # 构建脚本
└── README.md
```

### 开发命令

```bash
# 安装 Go 依赖
make deps

# 安装前端依赖
cd web && npm install

# 前端开发模式（热重载）
cd web && npm run dev

# 构建前端
make build-web

# 构建后端
make build

# 构建全部（前端 + 后端）
make build-all

# 清理构建产物
make clean

# Docker 构建
make docker-build

# Docker Compose 启动
make docker-up

# Docker Compose 停止
make docker-down
```

### API 接口

#### 认证相关
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 用户登录 |
| POST | `/api/auth/logout` | 用户登出 |
| GET | `/api/auth/me` | 获取当前用户 |

#### 任务管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/tasks` | 获取任务列表 |
| POST | `/api/tasks` | 创建任务 |
| GET | `/api/tasks/:id` | 获取任务详情 |
| PUT | `/api/tasks/:id` | 更新任务 |
| DELETE | `/api/tasks/:id` | 删除任务 |
| POST | `/api/execute/task/:id` | 执行任务 |

#### 环境变量
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/env` | 获取变量列表 |
| POST | `/api/env` | 创建变量 |
| PUT | `/api/env/:id` | 更新变量 |
| DELETE | `/api/env/:id` | 删除变量 |

#### 脚本文件
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/files/tree` | 获取文件树 |
| GET | `/api/files/content` | 获取文件内容 |
| POST | `/api/files/content` | 保存文件内容 |
| POST | `/api/files/create` | 创建文件/文件夹 |
| POST | `/api/files/delete` | 删除文件/文件夹 |
| POST | `/api/files/upload` | 上传压缩包 |

#### 执行日志
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/logs` | 获取日志列表 |
| GET | `/api/logs/:id` | 获取日志详情 |

#### 系统设置
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/settings/site` | 获取站点设置 |
| PUT | `/api/settings/site` | 更新站点设置 |
| POST | `/api/settings/password` | 修改密码 |
| GET | `/api/settings/about` | 获取系统信息 |

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 📄 License

[MIT License](LICENSE)