架构说明

CloudQue API 采用启动编排层、API 层、Service 层、Repository 层和基础设施包分层。核心目标是把 HTTP 接入、业务规则、数据访问、远程 SSH 能力和调度执行拆开，便于后续按模块扩展。

总体链路

cmd/server/main.go
  -> internal/app.App.Initialize
  -> 加载配置、初始化日志、MySQL、Redis
  -> 创建 Repository、Service、Scheduler、SSH SessionManager、WebSocket 连接池
  -> internal/api.Router.Setup
  -> Gin HTTP Server

请求处理链路：

HTTP/WebSocket 请求
  -> Gin Router
  -> Recovery / Logger / CORS / Auth / RequirePermission / OperationLog
  -> Controller
  -> Service
  -> Repository / SSH / Redis / WebSocket Pool
  -> MySQL / Redis / 远程训练服务器
  -> 统一响应或 WebSocket 消息

目录职责

目录	职责
`cmd/server`	程序入口，只负责创建、初始化并运行 `App`
`internal/app`	应用启动与编排层，集中管理配置、日志、数据库、依赖注入、路由、HTTP Server 和优雅关闭
`internal/api`	路由注册和 Controller，负责 HTTP 参数解析、认证上下文读取、调用 Service、返回响应
`internal/middleware`	认证、权限校验、请求日志、操作日志、CORS、异常恢复和原始请求体捕获
`internal/service`	核心业务层，包含认证、用户、权限、任务、队列、GPU、文件、终端、系统信息和调度器
`internal/repository`	数据访问层，封装 MySQL、Redis、队列、进程缓存、系统信息等访问逻辑
`internal/model/entity`	数据库实体，供 GORM 迁移和持久化使用
`internal/model/dto`	请求和响应结构，隔离接口数据与数据库实体
`pkg`	可复用基础设施和工具，如配置、日志、数据库、JWT、响应、错误码、SSH、WebSocket
`configs`	配置文件示例
`scripts`	数据库脚本和构建脚本

启动编排

internal/app/app.go 是应用生命周期的集中入口，主要步骤如下：

initConfig 加载 configs/config.yaml
initLogger 初始化 Zap 日志
initDatabase 初始化 MySQL、执行 GORM AutoMigrate、初始化 Redis、同步 GPU 卡片
initDependencies 创建 Repository、Service、SSH 会话管理器、WebSocket 连接池、任务调度器、磁盘占用定时任务
initRouter 设置 Gin 模式
initServer 创建 HTTP Server 并注册路由
Run 启动任务调度器和 HTTP Server
gracefulShutdown 关闭 WebSocket、终端、调度器、系统信息服务、首页服务、日志、HTTP Server、SSH 会话、数据库连接

API 模块

internal/api/router.go 统一注册 /api/v1 下的业务模块：

auth：注册、登录、登出、邮箱验证码、图形验证码、重置密码、刷新 Token
user：个人资料、头像、密码、用户列表、用户菜单权限
admin：管理员用户维护、角色简表、关机和重启
permissionManage/API：接口权限管理
permissionManage/menus：菜单管理
permissionManage/roles：角色和角色权限管理
terminal：远程终端 WebSocket
operationLogs：用户和管理员操作日志
system：系统实时信息、GPU 进程控制、采集配置
home：首页概览和首页实时 WebSocket
job：训练任务提交、查询、统计、取消、GPU 和 Conda 环境
queue：任务队列查询、重排、移除
files：远程文件和目录操作

业务模块

认证与会话

认证模块负责登录、登出、Token 刷新、权限聚合和 SSH 凭证维护。用户登录后，服务会按配置和用户信息建立或复用 SSH 会话，供文件、终端、任务执行等模块使用。

权限管理

权限由用户、角色、菜单和 API 权限组成。业务接口在路由层使用 Auth 和 RequirePermission 中间件，Controller 不直接处理权限规则。

任务与队列

任务模块负责提交训练任务、查询任务和取消排队任务。队列模块基于 Redis 保存任务顺序，调度器从队列中取任务，检查 GPU 可用状态后通过远程执行服务运行命令，并在运行后监控任务状态和释放资源。

GPU 与系统信息

GPU 服务负责同步显卡卡片、检查可用状态、绑定任务和释放显卡。系统信息服务通过 WebSocket 向前端推送服务器 CPU、GPU、进程等实时信息，并支持终止进程、保留进程和配置采集开关。

文件与终端

文件服务通过 SSH/SFTP 访问远程训练服务器，支持文件列表、上传、下载、删除、解压、大小计算和磁盘占用统计。终端服务通过 WebSocket 转发前端输入和远程 shell 输出，支持窗口大小调整和会话清理。

日志

日志分为应用日志和操作日志。应用日志由 pkg/logger 输出，操作日志由中间件捕获请求并调用用户操作日志服务写入数据库。管理员关机和重启日志通过独立的管理员日志服务保存。

数据模型

当前实体包括：

User：用户信息和状态
Role、UserRole：角色和用户角色关系
Permission、RolePermission：API 权限和角色权限关系
Menu、RoleMenu：菜单和角色菜单关系
Job：训练任务
GpuCard：GPU 卡片
Process：进程信息
UserOperationLog：用户操作日志
AdminOperationLog：管理员操作日志
BaseEntity：通用基础字段

DTO 按 internal/model/dto/request 和 internal/model/dto/response 拆分，Controller 只接收 DTO，Repository 只处理 Entity。

基础设施

pkg/config：读取 YAML 配置
pkg/database：初始化和关闭 MySQL、Redis
pkg/logger：结构化日志和日志轮转
pkg/jwt：Token 生成和解析
pkg/response：统一 JSON 响应
pkg/errors：业务错误码和错误消息
pkg/ssh：SSH 会话管理
pkg/server：远程 SSH 客户端封装
pkg/websocket：WebSocket 连接池
pkg/email：邮箱验证码发送
pkg/captcha：图形验证码
pkg/utils：字符串、时间、GPU、加密等工具

安全边界

敏感配置放在 configs/config.yaml，不要提交真实密码、Token、私钥口令
业务接口默认使用 JWT 认证和权限校验
用户、文件、终端、任务能力依赖 SSH 凭证，服务层统一维护 SSH 会话
响应层使用统一错误码，避免把底层错误直接暴露给前端
WebSocket 连接需要通过用户身份校验后才进入业务处理

运行时资源

MySQL 保存用户、角色、权限、菜单、任务、GPU、日志等持久化数据
Redis 保存队列、用户 SSH 凭证、会话、GPU 缓存、上传进度、磁盘占用缓存、进程缓存
远程训练服务器承载实际用户目录、文件操作、终端会话、训练命令和进程
WebSocket 连接池管理系统监控、首页概览和终端连接

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History