CloudQue API

CloudQue API 是一个面向远程训练服务器的后端服务，基于 Go、Gin、GORM、MySQL、Redis、SSH 和 WebSocket 构建。项目围绕用户认证、权限管理、任务提交与调度、GPU 资源管理、远程文件管理、远程终端、系统实时监控和操作日志提供接口能力。

核心能力

• 用户认证：注册、登录、登出、刷新 Token、邮箱验证码、图形验证码、忘记密码
• 用户与管理员管理：个人资料、头像、密码、用户列表、管理员创建和维护用户
• 权限管理：角色、菜单、API 权限、角色权限分配、接口权限校验
• 训练任务：提交任务、查看任务列表、等待队列、任务统计、取消排队任务
• 队列调度：Redis 队列、队列重排、任务移除、调度器自动执行任务
• GPU 管理：GPU 卡初始化、占用检查、任务显卡绑定、实时 GPU 信息
• 远程执行：基于 SSH 会话执行命令、获取 Conda 环境、维护用户 SSH 凭证
• 文件管理：远程目录浏览、上传、下载、删除、解压、文件大小计算、磁盘占用统计
• 终端连接：通过 WebSocket 建立远程交互式终端
• 系统监控：首页概览、系统实时信息 WebSocket、进程终止、进程保留、采集配置
• 操作日志：用户操作日志、管理员关机重启日志

技术栈

• Web 框架：Gin
• ORM：GORM
• 数据库：MySQL
• 缓存与队列：Redis
• 配置管理：Viper
• 日志：Zap、Lumberjack
• 认证：JWT
• 密码加密：bcrypt
• 远程连接：SSH、SFTP
• 实时通信：WebSocket

项目结构

cloudque/
├── cmd/server/                 # 服务入口
├── configs/                    # 配置文件示例
├── docs/                       # 架构、开发和接口文档
├── internal/
│   ├── app/                    # 应用启动、依赖装配和生命周期管理
│   ├── api/                    # HTTP 路由和 Controller
│   ├── middleware/             # 认证、权限、日志、CORS、恢复中间件
│   ├── model/
│   │   ├── dto/                # 请求和响应结构
│   │   └── entity/             # GORM 实体
│   ├── repository/             # 数据库、Redis、系统信息访问
│   └── service/                # 业务逻辑、调度器、SSH、文件、终端
├── pkg/
│   ├── captcha/                # 图形验证码
│   ├── config/                 # 配置加载
│   ├── database/               # MySQL 和 Redis 初始化
│   ├── email/                  # 邮件发送
│   ├── errors/                 # 业务错误码
│   ├── jwt/                    # JWT 工具
│   ├── logger/                 # 日志系统
│   ├── response/               # 统一响应
│   ├── server/                 # SSH 客户端封装
│   ├── ssh/                    # SSH 会话管理
│   ├── throttle/               # 节流工具
│   ├── utils/                  # 通用工具
│   └── websocket/              # WebSocket 连接池
├── scripts/                    # 数据库脚本和构建脚本
├── Makefile
├── go.mod
└── README.md

快速开始

环境要求

• Go 1.21+
• MySQL
• Redis
• 可访问的远程训练服务器，文件、任务、终端和 GPU 能力依赖 SSH 配置

初始化

go mod tidy
Copy-Item configs/config.yaml.example configs/config.yaml

按本地环境修改 configs/config.yaml，重点配置：

• app：服务名称、版本、运行模式、端口、AES 密钥
• database.mysql：MySQL 连接信息
• database.redis：Redis 连接信息
• jwt：Token 密钥和过期时间
• log：日志级别、输出文件和轮转策略
• cors：跨域策略
• server：远程训练服务器 SSH 连接信息和用户目录根路径
• email：邮箱验证码发送配置
• gpu：是否允许任务自动分配 GPU

初始化数据库：

mysql -u root -p < scripts/cloudque.sql

启动服务：

go run cmd/server/main.go

或使用 Makefile：

make run

健康检查：

curl http://localhost:8080/api/v1/health

接口概览

所有业务接口默认挂载在 /api/v1 下。除注册、登录、验证码、刷新 Token、健康检查外，大部分接口需要 Authorization: Bearer <token>，并会经过权限校验。

模块	路由前缀	说明
健康检查	/api/v1/health	服务存活检查
认证	/api/v1/auth	注册、登录、登出、验证码、密码重置、刷新 Token
用户	/api/v1/user	个人信息、密码、头像、用户菜单权限
管理员	/api/v1/admin	用户维护、角色简表、远程关机重启
权限 API	/api/v1/permissionManage/API	API 权限分页、创建、更新、删除
菜单	/api/v1/permissionManage/menus	菜单分页、创建、更新、删除
角色	/api/v1/permissionManage/roles	角色分页、创建、更新、删除、权限分配
任务	/api/v1/job	任务提交、列表、等待队列、统计、GPU、Conda 环境
队列	/api/v1/queue	队列查询、重排、移除任务
文件	/api/v1/files	远程文件列表、上传、下载、删除、解压、大小计算
用户目录	/api/v1/directories	用户目录列表和磁盘占用
系统	/api/v1/system	系统实时 WebSocket、进程管理、采集配置
首页	/api/v1/home	首页概览和实时概览 WebSocket
终端	/api/v1/terminal/ws	远程交互式终端 WebSocket
操作日志	/api/v1/operationLogs	管理员日志和用户操作日志

完整接口清单见 docs/API.md。

响应格式

普通 JSON 接口统一返回：

{
  "code": 0,
  "msg": "成功",
  "data": {}
}

分页接口通常返回：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10,
    "pages": 0
  }
}

Makefile 命令

make build          # 编译项目
make run            # 运行项目
make test           # 运行测试
make test-coverage  # 生成测试覆盖率报告
make clean          # 清理构建产物
make deps           # 整理并下载依赖
make migrate        # 执行 scripts/migrate.sql
make fmt            # 格式化代码
make vet            # 静态检查
make lint           # 运行 golangci-lint
make help           # 查看命令说明

文档

• 架构说明
• 开发指南
• API 文档
• 终端 WebSocket 协议