VelaSim（velasim）产品架构方案¶
版本：v1.0 日期：2026-09-03 定位：面向制造业仿真场景的产品级仿真云平台，覆盖云超算 / 云桌面 / 云数据 / 云应用全链路。
1. 项目背景与目标¶
五套历史代码是同一产品线在不同时期/客户（华为云、阿里云、SimCloud 基准、内蒙古、浪潮）的定制分支，技术栈为 Spring Boot 2.x + JSP/Bootstrap + Shiro，服务按部署形态硬拆、硬编码 IP 互调、明文凭据、无容器化、无测试。新项目 velasim 在保留全部业务功能的前提下，采用当前主流技术栈全新设计实现，达到产品级可交付标准。
目标 - 前后端分离，后端为单体应用（单一部署单元，内部模块化），前端为现代 SPA - 功能取五版本并集（需求已对齐确认，见第 2 节） - 私有化部署友好：本地文件存储、内存缓存、MySQL 单库 - 云厂商能力（ECS 云桌面、短信）做成可插拔、可配置开关 - 仿真行业风格 UI（深色科技风 + 浅色主题切换），仅中文（i18n 框架预留；2026-09-08 产品决策仅中文） - 产品级：代码规范、测试、接口文档、审计、部署脚本、备份策略齐备
2. 需求范围（已与需求方确认）¶
| 域 | 范围 |
|---|---|
| 核心平台 | 门户/认证、用户/租户/RBAC、集群管理、作业管理、求解器模板化、核时计量、云网盘、远程桌面、集群监控、资讯公告 —— 全部保留 |
| 作业调度 | SGE + Slurm 双支持（抽象调度接口，部署时按集群配置切换）。两种部署拓扑均为一等支持：① 平台部署于集群控制/登录节点（local 本地直调）；② 平台独立部署（vela-agent/SSH 通道）。多集群为可选扩展能力 |
| 商业化 | ~~预付费余额计费、商品化 SKU 售卖、试用申请~~（2026-09-07 产品决策 V36 下线删表）；Windows 软件计时管控（桌面 agent）保留 |
| 云厂商集成 | 华为云 + 阿里云 ECS 云桌面自动开通（双 SDK 可切换）、双云短信可配置、邮件通知—— 全部可配置开关，不配置即纯私有化运行。华为云商店 ISV 联营已明确去掉（IsvProduceController 仅保留回调台账留痕，业务联动不接线，受 vela.cloud.isv.enabled 门控默认关闭） |
| 运营 | 活动报名 enlist、视频课堂（本地存储 + FFmpeg 转码）、应用市场、资讯/客服/工单 —— 全部保留 |
| 明确去掉 | 浪潮云 API、FastDFS、truelicense、RabbitMQ（集群监控改 HTTP 心跳）、Spring Boot Admin（用自研监控中心 + actuator）、独立 Guacamole webapp（内嵌协议）、独立通知服务（并入单体）、华为云商店 ISV 联营、License 台账（license_file）与专家管理/专家评论（cms_expert/cms_expert_comment）—— 2026-09-07 产品决策下线删表，快捷帮助（FAQ）保留 |
| 消息中心 | 站内信：收件箱（系统/业务消息分类、已读未读、批量操作）、业务事件自动通知（作业完成、余额提醒、审批结果、活动通知、报表生成）、通知订阅偏好设置、导航栏未读角标 |
| 平台运维 | 监控中心（服务器/应用服务/MySQL/缓存）、登录日志、操作日志、数据备份、日志归档、报表中心、门户功能区块可配置、CentOS/Ubuntu 部署脚本、域名证书配置与自动更新 |
| 前端 | 深色科技风 + 浅色主题切换，仅中文（vue-i18n 框架预留；2026-09-08 产品决策仅中文） |
2.1 产品化提升原则¶
历史功能按"能跑通"实现，多处流程不达产品级。整合不是平移代码，而是功能语义保留 + 业务流程重设计，以下为已识别的升级点（实现时持续发现持续优化）：
| # | 旧版问题 | 新版设计 |
|---|---|---|
| 1 | 作业状态码 0/1/2/4/8，前端靠 .err 日志"猜"失败/警告；每作业一个 Quartz 触发器 | 明确状态枚举 + 失败分类（排队超时/资源不足/求解器崩溃/用户取消）；批量轮询 + 实时状态推送（SSE），排队位置与预计等待可展示 |
| 2 | 核时扣费在轮询里非事务、可能重复扣费 | 扣费与状态回写同事务、幂等（作业完成事件恰好消费一次）、月末对账报表 |
| 3 | 余额阈值、欠费处置（100 元提醒/30 天清空）硬编码 | 阈值/渠道/处置策略全部可配置，欠费流程可视化倒计时 |
| 4 | 网盘 base64 路径直传、物理路径拼接，存在穿越风险 | 虚拟目录 + 授权模型 + 回收站；上传下载全程流式 + 分片校验 |
| 5 | 桌面凭据 Hex 编码明文入库，Guacamole 表直写 | 凭据加密存储、会话审计、空闲超时断开、连接水印（桌面标签显示账号） |
| 6 | 报名一次性提交，无状态流转；试用/租户入驻申请无审批闭环 | 申请-审核-开通-通知全流程状态机，人数上限实时校验、重复报名拦截、报名成功消息通知 |
| 7 | 视频转码定时读 txt 进度文件，失败无重试 | 转码任务队列 + 进度上报 + 失败重试/告警 |
| 8 | 登录无验证码限流，会话不轮换 | JWT + 刷新轮换、验证码、登录失败限流锁定、异地登录提醒 |
| 9 | 集群监控只有 60s 快照，无告警 | 快照 + 趋势 + 告警规则（CPU/磁盘阈值、agent 离线、队列积压），告警走通知中心 |
| 10 | 管理后台表格堆功能、无操作反馈 | 统一数据表格规范（搜索/筛选/批量操作/导入导出/行内反馈），操作结果明确提示 |
| 11 | 门户内容与功能页混排、无导航体系 | 门户/工作台/管理后台三套布局分层，主导航 + 面包屑 + 全局搜索 |
| 12 | 无接口幂等/无审计 | 危险操作二次确认 + 审计日志；接口幂等键；全局错误码手册 |
| 13 | 门户首页区块硬编码，五版本各不相同 | 门户功能区块可配置：区块（云超算/云桌面/云数据/云应用/资讯/活动/视频等）开关、排序、内容源由管理员在后台可视化配置，版本/客户差异靠配置实现，代码一份 |
| 14 | 无业务监控：运营看不到作业成功率、排队时长、扣费异常等业务健康度 | 业务监控：业务大盘（作业提交/完成/失败率、队列积压、平均排队时长、核时消耗、计费收入、活跃/在线用户、余额不足用户数）+ 业务告警（失败率超阈、队列积压、扣费异常、余额不足批量、转码/导入任务堆积），与基础设施监控同属监控中心，统一告警规则引擎与通知渠道 |
| 15 | 无隐私协议/备案配置/注册不可配置/无二次验证 | 合规与安全：页脚 ICP/公安备案可配置、注册强制勾选用户协议与隐私政策（版本管理）、注册开关与审核模式可配置、管理员邮箱 OTP 二次验证（开关可配置），详见关键域设计第 10 条 |
| 16 | 旧机理模型表图片存 BLOB（logo_binary/introduce_binary），数据库膨胀、备份慢、无法走缩略图管线 | 图片/安装包一律本地文件存储 + 路径入库，走图片压缩与缩略图管线；分类值改字典码可配置（工业品类/专业学科/运行方式）；"全部"为筛选项而非分类值 |
2.2 批量导入/导出设计¶
统一"导入框架"与"导出框架"，各业务域按需接入，产品级体验一致：
导入框架（模板下载 → 逐行校验 → 预览确认 → 执行导入 → 结果报告） - 各业务提供标准 Excel 模板（可下载，含字段说明与示例行） - 逐行校验（格式/重复/外键/业务规则），错误行带原因回执，可下载错误明细修正后重导 - 大文件导入异步执行，进度可查 - 支持更新导入（按唯一键覆盖）与新增导入两种模式
导出框架（当前查询条件即导出范围 → 异步任务 → 下载中心） - 大数据量导出走异步任务，完成后经站内消息/通知提醒，下载中心统一取件（带有效期与审计） - 小数据量（≤1 万行）同步导出
| 域 | 导入 | 导出 |
|---|---|---|
| 系统 | 用户（含租户/角色/核时）、租户 | 用户、租户、审计日志、登录日志 |
| 作业 | 求解器参数模板 | 作业历史、作业统计（按租户/求解器/时间段）、核时明细 |
| ~~计费~~ | ~~商品/规格/价格目录~~（2026-09-07 下线） | ~~充值记录、消费明细、对账单~~ |
| 报名 | 线下报名名单 | 报名名单（含问卷答案）、活动统计 |
| 内容 | 资讯批量导入（可选） | —— |
| 集群 | —— | 监控快照 CSV、集群资源统计 |
| 视频 | 批量上传（含转码排队） | —— |
| 应用 | 应用批量导入（应用信息 Excel + 安装包文件包，异步解析入库）、批量上下架 | 应用使用统计 |
| 机理模型 | 模型批量导入（元数据 Excel：名称/排序/工业品类/专业学科/运行方式/版本/文字介绍 + logo/介绍图/安装包文件按名称匹配，异步导入任务；兼容现有 tb_mechanism 存量数据（约 1100+ 条）按模板迁入） | 模型清单、使用统计 |
技术：EasyExcel（流式读写）；统一 ImportContext/ExportContext 抽象，各模块实现校验器与行映射。
2.3 代码设计原则（强制要求）¶
结构清晰、低耦合、可扩展是代码级验收标准，具体落地规则：
- 分层与分包：每业务模块内部固定分层
controller → service(接口+impl) → mapper → entity/dto/vo；跨模块共享对象进vela-common；杜绝 controller 直调 mapper、模块间绕 service 互调。 - 依赖方向单向：业务模块只允许依赖
vela-common/vela-framework；模块之间禁止直接依赖（唯一声明例外：vela-module-cloud依赖vela-module-desktop的订单释放联动，已在 pom 显式声明）。跨域协作经 Spring 事件（事件类进 framework：system 域发布、业务域@TransactionalEventListener(AFTER_COMMIT)监听——首例UserPasswordChangedEvent，改密三层同步闭环，2026-09-13）。 - 可插拔点全部接口化（SPI + 策略 + 工厂，运行期按配置装配）：
- 调度引擎：
SchedulerProvider（SGE/Slurm） - 执行通道：
JobExecutor（Local/Agent/SSH） - 云主机：
CloudProvider（华为/阿里/none） - 短信：
SmsSender（华为/阿里/none） - 存储后端：
StorageService（本地为主，接口预留对象存储） - 通知渠道：
Notifier（邮件/短信/站内信） - 认证：Security Filter 链 + 认证提供者接口（预留 SSO/统一登录扩展）
- 导入/导出：模板方法框架 + 每域校验器 （计费规则 2026-09-07 随商品化下线移除，核时用量统计保留）
- 设计模式约束：策略（调度/存储）、模板方法（导入/导出/转码任务）、工厂（Provider 装配）、建造者（复杂作业提交对象）。新增一种调度器/云厂商 = 新增一个实现类 + 一行配置，不改既有代码。
- 质量门禁：Spotless/Checkstyle + ESLint/Prettier 在 CI 强制；单元测试覆盖接口契约（对每个可插拔接口，核心实现必须有用例）；架构约束用 ArchUnit 测试锁定（依赖方向、分层规则防腐化）。
2.4 命名规范¶
本平台建立统一命名体系，代码标识符一律英文，注释与文档中文：
| 类别 | 规则 | 示例 |
|---|---|---|
| 项目/仓库 | 全小写连字符：主仓库 velasim；后端 velasim-server、前端 velasim-web、agent velasim-agent、脚本 velasim-deploy |
|
| 后端包名 | com.velasim 根包 + 模块名：com.velasim.job、com.velasim.billing |
|
| Maven 模块 | vela-common、vela-framework、vela-module-*、vela-boot |
|
| 数据库 | 库名 velasim；表名小写蛇形、业务域前缀：sys_ job_ netdisk_ desktop_ cloud_ billing_ app_ enlist_ video_ cms_ msg_ monitor_ report_；列名小写蛇形，布尔 is_ 前缀、时间 _time 后缀、外键 {实体}_id；索引 idx_/uk_ |
sys_user、job_info、billing_account、core_hours_used |
| REST API | /api/v1/{模块}/{资源复数} + HTTP 动词语义，响应统一 Result<T> |
POST /api/v1/jobs、GET /api/v1/jobs/{id}/logs |
| 前端 | 目录/路由 kebab-case、组件 PascalCase、变量 camelCase、常量 UPPER_SNAKE | workspace/job-submit.vue、JobStatusTag.vue |
| 业务术语 | 采用行业标准术语：核时=core_hours、作业=job、工作区=workspace、连接=connection、充值/扣费=recharge/consume | |
| 配置/密钥 | application-{dev,test,prod}.yml；密钥 Jasypt 加密、配置文件无明文 |
3. 总体架构¶
┌─────────────────────────────────────────────┐
│ Nginx（静态托管 + 反代） │
└──────────────┬──────────────────────────────┘
│ / /api
┌──────────────▼──────────────────────────────┐
│ vela-boot 后端单体（Java 21 + SB3） │
│ ┌────────────────────────────────────────┐ │
│ │ 业务模块：system / cluster / job / │ │
│ │ netdisk / desktop / cloud / billing / │ │
│ │ app / enlist / video / cms / notify │ │
│ ├────────────────────────────────────────┤ │
│ │ framework：security(JWT) / cache / web / │ │
│ │ mybatis-plus / scheduler / storage │ │
│ └────────────────────────────────────────┘ │
└───┬─────────┬─────────┬─────────┬───────────┘
│ │ │ │
┌─────────▼──┐ ┌────▼────┐ ┌──▼──────┐ ┌▼──────────────┐
│ MySQL 8 │ │ 本地磁盘 │ │ guacd │ │ FFmpeg 转码机 │
│ (单库) │ │(文件/视频)│ │ (4822) │ │ (可选/本机) │
└────────────┘ └─────────┘ └─────────┘ └───────────────┘
集群侧（每 HPC 集群登录节点） 桌面机侧
┌─────────────────────────────┐ ┌──────────────────────────┐
│ vela-agent（新版 joblet） │ │ vela-host-agent（Windows） │
│ 无数据库 · HTTP API · 心跳上报 │ │ 软件黑白名单/计时管控 │
│ 本地执行 qsub/sbatch │ └──────────────────────────┘
└─────────────────────────────┘
核心架构决策
- 单体 + 模块化：后端一个可执行 jar（单部署单元），内部按业务域拆分 Maven 模块，避免"硬拆服务 + 硬编码 IP 互调"的架构反模式。
- 作业执行三通道（
JobExecutor可插拔，按集群配置，多集群只是加台账配置、不改代码）： - local：平台部署在集群控制/登录节点，本地直接调用 qsub/sbatch，零网络开销
- agent：平台独立部署时，集群登录节点部署 vela-agent 代理执行（HTTP + 心跳上报）
- ssh：平台独立部署且无 agent 时，SSH 直连登录节点（Apache MINA SSHD） 三种通道完整实现、按现场部署条件配置选择，无优先级之分
- 调度器抽象：
SchedulerProvider接口，SgeProvider（qsub/qstat/qacct/qdel）与SlurmProvider（sbatch/sacct/sinfo/scancel/sacctmgr）两个实现，集群台账逐集群配置调度器类型（一个集群一种调度器）。两种调度器的外部状态（SGE qw/r…、Slurm PENDING/RUNNING…）统一映射到平台作业状态机，核时计费与监控采集逻辑对两种调度器完全一致；同一平台可同时纳管一个 SGE 集群与一个 Slurm 集群（多集群场景）。调度器类型与执行通道（local/agent/ssh）、部署拓扑、网盘模式四个维度相互独立、按配置组合。 - 状态轮询收敛：单体统一
@Scheduled批量轮询运行中作业（10s），状态机收敛、可审计、无每作业独立触发器（避免触发器泄漏与不可控并发）。 - 集群监控：local 模式下平台每 60s 本地采集（qstat/sinfo + df，无外部依赖）；agent 模式下由 vela-agent 心跳上报，平台落库（无消息中间件依赖）。节点列表动态采集——集群计算节点扩容/下线自动反映到监控大屏与资源统计，无需平台侧配置变更。
- 远程桌面：内嵌
guacamole-common（Java WebSocket 隧道直连 guacd 4822），自建桌面连接/权限表——单端口交付、免独立部署组件、隧道与平台权限体系一体化。 - 云桌面/云应用双模式：手动配置与云平台自动开通并存——管理员可手动登记既有主机（IP、RDP/VNC 协议、端口、账号）或纳管已有云主机实例；也可按商品规格经云 SDK 自动创建/启停 ECS。两类资源统一进入桌面/应用列表，对用户无感知差异；纯私有化部署（
provider=none）时手动配置即为唯一方式。 - 文件存储：本地磁盘根目录可配置（
storage.root），路径规范化 + 防目录穿越校验；视频经 FFmpeg 转码 720p/1080p + 截图后存本地。 - 缓存：Caffeine 本地内存缓存（Spring Cache 抽象），缓存用户/集群/求解器/字典等热数据；集群监控快照存库不存缓存。
- 云能力开关：
vela.cloud.provider=huawei|aliyun|none，none 时云相关模块自动降级为手动管理；短信vela.sms.provider=huawei|aliyun|none。
4. 技术选型（原则：成熟生态 + LTS 基线 + 可维护性优先）¶
选型原则（面向未来 5 年维护周期）：
- LTS 优先：语言/运行时/数据库均取 LTS 版本线（Java 21、MySQL 8.0 LTS 线），升级路径写入文档
- 主流生态优先：社区活跃、资料丰富、人员招聘与上手成本低（Spring Boot / Vue / Element Plus 等）
- 按规模选复杂度：默认单体 + 可插拔接口；不为未发生的规模引入微服务/分布式复杂度（集群化路径见 10.4）
4.1 后端¶
| 项 | 选型 | 说明 |
|---|---|---|
| 语言/运行时 | Java 21 LTS | 现代语法、虚拟线程可用 |
| 框架 | Spring Boot 3.5.x | 主流单体框架；内置虚拟线程开关 |
| 安全 | Spring Security 6 + JWT（jjwt 0.12） | 生态最成熟、与 Boot 深度集成；Access + Refresh 双 token，BCrypt 密码 |
| ORM | MyBatis-Plus 3.5.x | 团队有 MyBatis 积累，Plus 提升效率；HikariCP 连接池 |
| 数据库 | MySQL 8.0（单库） | 用户指定 |
| 缓存 | Caffeine（本地内存缓存） | 用户指定；Spring Cache 抽象，未来可平滑换 Redis |
| 接口文档 | Springdoc OpenAPI + Swagger UI | 开发期可视化调试 |
| SSH | Apache MINA SSHD | 现代 SSH 协议库（SSH 直连通道），维护活跃 |
| 定时任务 | Spring @Scheduled + 应用内任务注册表 |
单体单实例无需 Quartz/分布式锁 |
| 对象映射 | MapStruct + Lombok | |
| 工具 | Hutool | 团队熟悉 |
| 视频 | FFmpeg CLI（转码 720p/1080p + 截图） | 进程外执行最稳（避免转码库与 JVM 生命周期耦合） |
| 云 SDK | huaweicloud-sdk-ecs / aliyun-sdk-ecs（ess 新版） | 可插拔，编译期均引入，运行期按开关加载 |
| 短信 | huaweicloud-sdk-sms / aliyun-dysmsapi | 抽象 SmsSender 接口 |
| 监控中心 | 自研：Oshi 服务器指标 + actuator 应用指标 + MySQL 指标（连接池/慢查询）+ Caffeine 缓存命中统计，告警规则联动通知中心；预留 Micrometer/Prometheus 导出 | 取代 Spring Boot Admin |
| 报表 | CSV/Excel 导出（当前）；PDF/模板/定时生成/订阅通知（规划中） | 报表中心 |
4.2 前端¶
| 项 | 选型 | 说明 |
|---|---|---|
| 框架 | Vue 3.5 + TypeScript 5 + Vite 7 | 当前主流 |
| 状态/路由 | Pinia + Vue Router 4 | |
| UI 组件库 | Element Plus 2.x | 国内主流、维护活跃；原生支持暗黑模式 |
| 图表 | ECharts 5 | 集群监控大屏、核时用量趋势 |
| 国际化 | ~~vue-i18n 中英双语~~（2026-09-08 产品决策：仅中文，界面文案硬编码中文；i18n 框架预留，如需双语另行立项） | |
| 主题 | CSS 变量设计 token + EP dark 模式，深色科技风/浅色商务风一键切换 | |
| 富文本 | wangEditor 5 | 资讯/活动编辑 |
| 大文件上传 | 自研分片上传（断点续传、秒传校验 MD5） | 网盘/视频场景 |
4.3 工程质量¶
- 构建：Maven 多模块 + 前端 pnpm monorepo（可选）；Git 工作流 + 提交规范
- 接口工具链：Springdoc OpenAPI 3 规范（
/v3/api-docs）+ Swagger UI 可视化调试（/swagger-ui/index.html）；Apifox 支持——规范一键导入 Apifox，同步调试、团队协作、Apifox Mock 服务生成前端 mock 数据；契约 code-first（注解为准、规范自动生成），前端 TS 类型由规范生成，双端校验规则同源 - 环境仿真：H2 mock 档位——dev/demo profile 以 H2（MySQL 兼容模式）内存库运行，前端联调与演示环境无需安装 MySQL；Flyway 迁移脚本按厂商分目录（
db/migration/mysql、db/migration/h2），MySQL 专有 DDL 放 mysql 目录、H2 用兼容写法；集成测试用 Testcontainers 起真实 MySQL 保证与生产一致；交付/生产一律 MySQL - 数据库生命周期：Flyway 版本化迁移（空库一键建全量结构 + 种子数据）；数据库重建工具
vela-db rebuild——重建前强制备份 + 显式二次确认，支持"仅结构重建"与"结构+种子重建"两种模式（种子含初始管理员、字典、默认参数、协议模板）；备份恢复脚本 + 恢复演练文档（灾难恢复路径）；H2 档位内存库重启即重置，演示环境天然支持快速重建 - 域名策略：默认单域名部署（SPA + WebSocket/SSE 同域，证书与 SSO 均简单）；多域名/子域（视频站、桌面站独立域名）为可配置项
- 测试：JUnit 5 + Spring Boot Test + Mockito；核心域（调度引擎、计费、作业状态机）单测覆盖率 ≥ 80%；接口级自动化冒烟脚本
- 规范：Checkstyle / Spotless + ESLint + Prettier；统一错误码与
Result<T>响应；全局异常处理；操作审计日志 - 部署：单体 jar 部署（默认）或 Docker 容器部署（镜像可选）——vela-boot 打单可执行 jar，
systemd托管；提供 Dockerfile 与 docker-compose 模板；Nginx 前置（静态资源托管 +/api反代 + WebSocket/SSE 升级）；部署拓扑（两种均完整支持）：① 部署于集群控制/登录节点——能执行 qsub/sbatch 的提交/登录节点即可，不必是调度器管理节点；与调度器命令同机，local 直调、网盘直连共享盘、监控本地采集，无需 vela-agent。部署前提：平台节点挂载集群共享盘（NFS/Lustre）、平台主机运行 Samba（Windows 桌面挂载出口），部署脚本自动检查；② 独立服务器部署——经 agent/ssh 通道、网盘走平台存储模式；部署脚本与配置模板覆盖两种场景；CentOS 与 Ubuntu 双平台一键部署脚本（依赖安装、服务注册、目录初始化、升级回滚）；域名证书：acme.sh 自动签发（Let's Encrypt）+ cron 自动续期，脚本内置；数据备份：MySQL 每日全量 + binlog 增量、保留策略、恢复脚本 + 恢复演练文档；日志归档：logback 按天滚动 + logrotate 压缩归档、保留周期可配置
4.4 文档体系与质量标准¶
交付文档清单（全部随代码进 git、版本同步、随里程碑交付，纳入验收清单）：
| 阶段 | 文档 | 形态与标准 |
|---|---|---|
| 产品介绍 | 产品介绍（项目简介、功能总览、架构与亮点、界面截图）、产品白皮书（可选） | 品牌级排版（与产品 UI 同主题），对外可发布 |
| 研发 | 架构方案（本文件）、接口文档（OpenAPI 自动生成 + Apifox 协作）、数据库设计文档（表/字段注释即文档 + Flyway 生成）、开发者文档（本地开发/H2 档位/代码规范/可插拔扩展指南）、二次开发指南（前后端环境与技术栈版本清单、模块依赖关系、扩展点接入 step-by-step，保证他人可顺利接管项目） | 随代码进 git、与实现同步；扩展指南 step-by-step |
| 部署 | 部署手册（CentOS / Ubuntu / Docker 三分册）、快速开始（一页、10 分钟跑通） | 命令可直接复制执行；每步带预期结果 |
| 运维 | 运维手册（备份恢复 / 告警处置 / 日志归档 / 故障排查 FAQ） | 条目按"现象→原因→处置"模板 |
| 用户 | 用户手册分册：普通用户 / 租户管理员 / 平台管理员（中文）、操作手册（高频场景 step-by-step + 截图）、常见问题 | 按角色分册，每人只读自己一册 |
| 交付验收 | 交付文档包：交付清单、验收测试报告、验收演示脚本、培训材料（PPT/视频可选） | 与验收流程绑定，逐项确认签署 |
全部文档的产品级标准（简洁 / 美观 / 清晰，适用每一类）：
- 简洁：接口文档自动生成、杜绝重复手写；手册按角色分册；一页一主题、目录 ≤3 级、每篇开头 TL;DR；操作步骤编号化，冗余段落一律删除
- 美观：统一 Markdown 排版，MkDocs 静态站点发布（与产品 UI 同色系主题）；架构图/流程图统一图规范（mermaid 源文件进 git，可渲染、可改、可版本比对）；截图统一规范（窗口尺寸、标注框样式、导出清晰度）；产品介绍类按品牌级排版
- 清晰：文档结构模板固定（概述 → 概念/术语 → 操作 → FAQ）；全局术语表（glossary）与 UI 文案一致；故障排查按"现象→原因→处置"；每步操作带预期结果描述
- 保障：文档随对应功能一同走查评审、随里程碑交付；发布前"新手验证"——由未接触过项目的人按快速开始完整跑通一遍；交付文档纳入验收清单，不达标不验收
4.5 测试体系（分层 + 门禁）¶
| 层 | 范围 | 门禁 |
|---|---|---|
| 单元测试 | 核心域覆盖率 ≥80%（调度引擎、计费、状态机、权限、文件路径安全），其余模块关键逻辑覆盖 | CI 提交即跑 |
| 集成测试 | Testcontainers 真实 MySQL + Spring Boot Test；模块间事件链路（作业完成→扣费→通知）端到端集成用例 | CI 合并即跑 |
| 接口测试 | OpenAPI 契约测试（响应结构与错误码）、写接口幂等验证 | CI 合并即跑 |
| E2E | Playwright 高频动线（登录→提交作业→查看状态、网盘上传下载、报名流程） | CI 夜间全量 |
| 性能测试 | JMeter 专项场景（10.2 节：并发扣费/提交/大文件并发传输） | P7 达标验证 |
| 安全测试 | 依赖漏洞扫描（OWASP dependency-check）、静态扫描（SpotBugs/SonarQube）、渗透测试 | P7 交付前 |
5. 后端模块划分（Maven 多模块单体）¶
velasim/backend
├── vela-common # 通用：常量/枚举/异常/Result/工具
├── vela-framework # 横切：security(JWT/RBAC)、cache、web 配置、
│ # mybatis-plus 配置、storage 抽象、云/短信抽象接口
├── vela-module-system # 认证、用户/租户、角色/菜单/资源(RBAC)、参数、审计日志、在线用户
├── vela-module-cluster # 集群台账、求解器注册表、集群-企业绑定、监控快照、监控大屏数据
├── vela-module-job # 作业管理、调度引擎(SGE/Slurm)、作业状态机、核时计量、输入输出文件
├── vela-module-netdisk # 网盘：目录树、上传下载、打包解压、分片断点续传
├── vela-module-desktop # 远程桌面：连接管理（手动登记主机/纳管云主机/自动开通）、Guacamole 隧道、VNC 端口池、桌面生命周期
├── vela-module-cloud # 云主机(华为/阿里 ECS 双厂商)、云短信、云订单/到期/释放管理
├── ~~vela-module-billing~~ # ~~预付费账户、商品/试用~~（2026-09-07 V36 下线删模块，核时用量统计并入 job 域）
├── vela-module-app # 应用市场：软件上架/详情/收藏/评论/试用
├── vela-module-model # 机理模型库：模型上传/分类标签/检索/版本/复用（新增能力）
├── vela-module-enlist # 活动报名：活动/问卷/报名/导出/视频回放关联
├── vela-module-video # 视频课堂：上传/转码任务/点播/评论/收藏/观看记录
├── vela-module-cms # 资讯、技能服务/客服、求助工单、快捷帮助(FAQ)、通知(邮件/短信调度)
├── ~~vela-module-monitor~~ # 监控中心（2026-09 实现并入 system 域：基础设施指标 + 业务大盘 + 告警）
├── ~~vela-module-report~~ # 报表中心（2026-09 实现并入 system 域）
└── vela-boot # 启动模块：聚合依赖，打包单 jar，application.yml
跨模块依赖只允许依赖 vela-common / vela-framework；模块之间禁止直接依赖（唯一声明例外：vela-module-cloud → vela-module-desktop 订单释放联动，pom 已显式声明）。跨域协作经 Spring 事件（事件类进 framework，事务内发布 + AFTER_COMMIT 监听，保证回滚不同步；首例 UserPasswordChangedEvent，2026-09-13）。
关键域设计
- 作业状态机：
DRAFT → QUEUED → RUNNING → FINISHED / FAILED / STOPPED。提交时落库 QUEUED，调度轮询将 QUEUED 作业按集群可用核与配额提交到 SGE/Slurm，回填外部作业 ID；统一轮询任务每 10s 拉取运行中作业状态；完成时事务内：回写起止时间 → 计算核时扣减 → 发布完成事件。支持作业模板：提交参数另存为模板、从模板一键创建（CAE 高频重复提交场景），模板按用户/租户共享范围管理。 - ~~计费~~（2026-09-07 V36 下线删表）：核时用量统计（
job_info.core_hours秒级 scale、core_hours_used用量流水）保留，供仪表盘与报表使用。 - 权限模型（四层，详见第 10 节）：认证（JWT）→ 功能权限（RBAC 用户-角色-菜单-操作点，按钮级双端校验）→ 数据权限（租户数据范围隔离，MyBatis-Plus 拦截器强制注入过滤，管理员可跨租户）→ 资源权限（求解器组/软件粒度授权、桌面/集群与租户绑定）。前端路由守卫 + 后端 Security 双重校验。
- 网盘双模式（
StorageService可插拔，按部署形态选择；网盘元数据——目录树/回收站/配额/分享——统一存 MySQL，两种模式业务逻辑与界面一致）： - 共享存储直连模式（平台与控制节点同机且共享盘已挂载时采用）：文件本体直接服务挂载路径（NFS/Lustre），零拷贝、零同步延迟——保留旧方案"文件就在集群上"的优点，作业直接读写
- 平台存储模式（平台独立部署时采用）：文件存平台本地磁盘；提交作业时增量同步 staging 到集群工作区——内容寻址缓存（同文件二次提交跳过拷贝）+ 块级 delta + 提交前预传输（向导选完文件即开始后台同步）+ 与排队时间重叠 + 并行分块断点续传；结果异步回传网盘，并支持"暂不回传"（保留期内作业详情页直接浏览/下载工作区文件，适合 TB 级输出）
- 作业工作区（
/home/{user}/.vela/jobs/{jobId}）生命周期由平台显式管理（保留期可配置，超期自动清理）；Linux 账户保留用于作业执行与桌面访问，但不再是网盘本体，个人文件与作业数据解耦 - Windows 挂载出口（SMB 网关）：Windows Server 无法直挂 NFS，云桌面/云应用的网盘访问统一经 SMB——平台主机运行 Samba，导出平台网盘命名空间（用户虚拟目录与授权），而非裸家目录；Windows 主机初始化时
net use持久挂载。直连模式下 Samba 服务共享盘路径（存储复用、零拷贝），平台存储模式下服务平台本地磁盘。网盘无需绑定 Linux 家目录，命名空间由平台定义 - SMB 生命周期闭环（2026-09-13，V49）：账号创建/挂载/卸载/删除全部事件驱动——绑定/订单开通自动建三层账号并挂载（首连前就绪）；解绑/释放/删除自动断会话→卸盘→删账号→撤共享；平台改密自动三层联动（Samba/Linux → Windows 账号 → 重挂，
UserPasswordChangedEventAFTER_COMMIT 监听）。执行经desktop_host_op落库待办（密码 AES 密文存储、终态清空）+ 扫掠器退避重试 + 超限站内信告警；主机离线不阻塞生命周期 API。Samba 侧执行：平台非 root 服务经 sudoers 钉死调用samba_account.sh（密码只经 stdin）；SSH 传输备选（指纹钉死 + 私钥认证 fail closed）。会话 0 提示：host-agent 服务会话执行net use，盘符对交互用户会话的可见性取决于部署形态（agent 响应 sessionNote + ops-manual 部署选项） - 安全：虚拟路径 → 物理路径白名单映射，杜绝
../穿越 - 媒体处理管线（视频/图片）：
- 视频转码：上传完成 → 转码任务 → FFmpeg 异步执行，输出多码率阶梯（1080p/720p，H.264；480p 预留）+
-movflags +faststart（moov 前置，保证流式播放与拖动秒回）+ 封面截帧（缩略图）+ 可选进度条雪碧图（规划中）；转码进度落库可查、失败重试告警；原片保留策略可配置（保留原片或转码完成后删除以省空间） - 流式播放（性能关键）：默认 HLS 分片流（m3u8 + ts 分片 + hls.js 播放器）——多码率自适应、拖动秒开、按需加载分片，国内网络环境下体验最佳；简单场景兼容 mp4 + HTTP Range 渐进式播放；预加载 metadata、首帧优化
- 图片：上传即压缩并生成多尺寸缩略图（WebP，体积降 30%+），列表/详情加载缩略图，原图按需下载
- 转码资源约束：转码并发数可配置 + 进程低优先级，避免与业务抢 CPU；部署脚本支持独立转码工作机（推荐，视频量大时）
- 桌面/应用主机初始化配置（云桌面与云应用宿主均为 Windows Server；Linux 桌面走 VNC 为次级路径）：平台统一管理每台主机的初始化配置——Windows 账户创建、RDP 开启与防火墙、SMB 网盘持久挂载、应用列表（云应用"打开即应用"：登录脚本自动拉起指定软件；RemoteApp 窗口化模式为可配置项，需 RD 会话主机 + RDS CAL）、host-agent 安装与策略。配置下发双通道：云主机走云助手 RunCommand（开通时自动执行）；手动登记主机由管理员执行平台生成的一次性初始化脚本，之后 host-agent 定期拉取增量配置。初始化脚本模板化、幂等（可重复执行），凭据加密存储。
- 通知中心（短信/邮件/站内信三渠道，全部可配置）：
- 渠道抽象：
Notifier接口；短信SmsSender双实现（华为云/阿里云，vela.sms.provider配置切换，none 即关闭短信）；邮件 Spring Mail（SMTP 服务器/账号/SSL 全部配置化）；站内信走消息中心 - 事件 → 渠道映射可配置：注册验证码、密码找回、作业完成/失败、审批结果、报名成功、报表生成、告警、云主机到期提醒、异地登录提醒——每类事件独立配置启用渠道（邮件/短信/站内信任意组合）与启用开关（余额/欠费/试用事件随商业化下线）
- 模板化：
msg_template模板后台可编辑（变量占位符、短信签名配置化；仅中文） - 异步发送 + 失败重试 + 发送记录（
sms_log）；验证码防刷（同号 60s 间隔 + 每日上限 + IP 限流） - 用户级订阅偏好：用户在消息中心设置每类通知收不收、走哪个渠道（受平台开关约束）
- 统一大文件上传：网盘、作业输入文件、视频上传共用同一上传组件——分片上传（5~10MB/片、多片并发）、断点续传（分片状态落库，刷新/中断后可续）、秒传（MD5 校验，已存在内容跳过传输）、暂停/恢复与实时进度；服务端分片状态表管理、合并时哈希校验；100GB+ 大文件为验证目标
- 大文件下载与失败恢复：
- 单文件：HTTP Range 断点续传（浏览器/下载工具断点续下）+ ETag/Last-Modified 校验 + 下载完成 MD5 校验
- 多文件/目录打包：异步打包任务 → 下载中心取件（有效期 + 审计），打包中断可重试，避免同步阻塞与内存膨胀
- 前端下载组件：分片 Range 请求 + 流式写盘，支持暂停/恢复与进度显示，刷新页面后可续
- 超大结果集（TB 级）：提供分片下载 API 与多线程下载指引；工作区保留期与下载联动，杜绝"下载失败但文件已被清理"
- 合规与认证安全：
- ICP/公安备案：门户页脚备案号可配置（ICP 备案号、公安备案号及链接，配置为空即不显示——私有化部署无需备案）
- 隐私协议：注册强制勾选《用户协议》《隐私政策》（内容后台可编辑、带版本记录），登录页/门户页脚均有入口；协议更新需用户重新确认
- 注册可配置：开放/关闭注册开关、注册方式（用户名/手机/邮箱组合）、验证码要求、注册后模式（直接开通 / 管理员审核）、默认角色与租户
- 管理员二次验证：平台管理员登录支持邮箱 OTP 二次验证（验证码 5 分钟有效、错误次数锁定、新设备/异地触发策略可配置），整体开关可配置，可扩展适用角色范围；认证因子接口化——邮箱 OTP 为默认实现，TOTP（Authenticator）可插拔扩展
5.1 本地文件存储目录规划¶
单一存储根 storage.root（可配置，如 /opt/velasim/storage），按业务域分子目录，全部由平台账户持有（700/750 权限，不对外直接暴露）：
{storage.root}/
├── jobs/{year}/{month}/{jobId}/ # 作业输入快照、输出回传中转（保留期联动工作区策略）
├── netdisk/{tenantId}/{userId}/... # 平台存储模式网盘（直连模式配置指向集群共享盘，不落此目录）
├── app/package/{sha256前2}/{sha256} # 应用安装包（内容寻址，相同文件只存一份）
├── app/image/{appId}/ # 应用 logo/截图（原图 + 缩略图）
├── model/package/{modelId}/{version}/ # 机理模型安装包（版本化）
├── model/image/{modelId}/ # 模型 logo/介绍图（原图 + 缩略图）
├── video/source/{videoId}/ # 视频原片（保留策略可配置）
├── video/transcode/{videoId}/{quality}/ # 转码产物（1080p/720p；HLS 分片预留）
├── video/poster/{videoId}/ # 封面/进度雪碧图
├── cms/image/{year}/{month}/ # 资讯/活动/内容图片
├── enlist/{activityId}/ # 活动附件/海报
├── upload/chunk/{uploadId}/part-* # 分片上传暂存（合并后移入目标域，孤儿分片定时清理）
├── import-export/{taskId}/ # 导入模板/错误回执/打包下载（有效期，定期清理）
├── report/{taskId}/ # 报表生成文件（下载中心取件）
└── temp/ # 全局临时区（合并/解压中转，每日清理）
规划原则：
- 文件命名：物理文件名用雪花 ID/内容哈希 + 扩展名，原始文件名只存数据库元数据——杜绝中文/乱码/路径穿越问题；
{year}/{month}或哈希前缀分桶，防单目录文件爆炸 - 原子发布：上传/转码/打包一律先写
temp或域内tmp，完成后同卷rename原子移入正式目录（同卷 rename 保证原子性） - 内容寻址去重：应用包/大文件按 sha256 寻址，相同内容一份存储（配合秒传）
- 备份分级：只备份不可重建数据——netdisk、jobs、app/model 包、video 原片、cms 原图 + 数据库；可重建产物（缩略图、转码分片、temp、import-export、report）不备份，重建即可
- 生命周期：每域保留期可配置（jobs 联动工作区策略、upload 孤儿分片、temp、import-export/report 有效期），每日清理任务执行，磁盘水位监控告警
- 可迁移：storage.root 支持迁移/扩容（同结构挂新卷 + 路径重指），部署文档提供迁移步骤
6. 数据库设计（MySQL 8，单库 velasim）¶
单库设计：全部业务域统一单库、统一命名、全部 InnoDB + utf8mb4。租户以 tenant_id 列隔离，不按租户分库分表——面向目标规模（单租户数百用户级）以事务一致性、运维简单性、备份完整性为优先；规模化路径见 10.4（读扩展走主从/缓存，写扩展走应用层优化，而非分库分表）。
| 域 | 核心表 |
|---|---|
| 系统 | sys_user（含核时三列）、sys_tenant、sys_cluster（含调度器类型、连接参数）、sys_role、sys_menu、sys_role_user、sys_param（注册/二次验证/备案等全量开关配置）、sys_dict/sys_dict_item（字典管理：机理模型工业品类/专业学科/运行方式等分类可配置）、sys_agreement（用户协议/隐私政策版本）、sys_login_log、sys_operate_log |
| 消息 | msg_message、msg_message_read、msg_template |
| 求解器 | job_solver_group、job_solver_name、job_solver_attribute、job_solver_data、job_solver_jurisdiction、cluster_solver_version |
| 作业 | job_info（统一作业表：状态、外部 jobId、核数、起止时间、求解器快照）、job_queue、job_file、job_workspace（工作区台账：集群、路径、清理期限）、job_statistics_day/month、job_cost_rule |
| 监控 | cluster_monitor_snapshot、agent_heartbeat |
| 网盘 | netdisk_dir、netdisk_file（元数据 + 物理路径）、netdisk_transfer（分片传输状态） |
| 桌面 | desktop_host（含初始化配置：账户、SMB 挂载点、应用列表、agent 凭证）、desktop_connection（协议 RDP/VNC、端口）、desktop_session、desktop_init_log、tenant_vnc_port |
| 云 | cloud_instance、cloud_order、cloud_expire、sms_log |
| 门户/监控/报表 | portal_block_config、monitor_alert_rule、monitor_alert_record、monitor_metric_snapshot（业务/基础设施指标快照）、report_task、report_download |
| ~~计费~~ | ~~billing_account、billing_recharge_record、billing_consume_record、product、product_sku、trial_application~~（2026-09-07 V36 删表；核时用量 job_info.core_hours + core_hours_used 保留） |
| 应用 | app_info、app_type、app_comment、app_collection、app_use |
| 机理模型 | model_info（模型名称/排序/logo/介绍图/文字介绍/工业品类/专业学科/运行方式/安装包/版本/状态/审计字段——参考原 tb_mechanism 结构，logo 与介绍图、安装包一律本地文件存储 + 路径入库，不存 BLOB）、model_tag、model_collection、model_use |
| 报名 | enlist_activity、enlist_activity_type/subtype/market、enlist_record、enlist_questionnaire |
| 视频 | video_info、video_type、video_comment、video_collection、video_view_record、video_transcode_task |
| 内容 | cms_news、cms_skill、cms_skill_reply、cms_help、cms_industry、cms_plate、cms_paper（cms_expert/cms_expert_comment 已删表下线；cms_quick_help 快捷帮助保留） |
索引按查询模式设计（作业：tenant+state+create_time；监控：cluster+snapshot_time；流水：account+create_time）。表结构变更用 Flyway 管理版本化迁移。
7. 前端设计¶
7.1 工程¶
velasim/frontend
├── src/
│ ├── api/ # 接口层（自动生成类型）
│ ├── assets/ # 设计 token（主题变量）
│ ├── components/ # 通用组件（分片上传、作业状态标签、求解器表单、监控卡片…）
│ ├── layouts/ # 门户布局 / 工作台布局 / 管理后台布局
│ ├── locales/ # zh-CN / en-US
│ ├── router/ stores/ utils/
│ └── views/
│ ├── portal/ # 登录注册、门户首页、资讯、行业（对外展示，免登录浏览）
│ ├── workspace/ # 作业工作台、网盘、远程桌面、配额用量、我的租户（登录用户）
│ ├── tenant/ # 租户管理台（租户管理员：本租户用户/作业/配额/资源自助管理）
│ ├── mall/ # 应用市场、商品订购
│ ├── activity/ # 活动报名（含 H5 报名页）
│ ├── classroom/ # 视频课堂
│ └── admin/ # 平台管理后台（用户/租户/集群/求解器/内容/监控/报表/审计/系统参数；计费/商品已下线）
前台/后台分区设计：单一 SPA 内四个逻辑区，菜单与路由由 RBAC 动态生成（前端路由守卫 + 后端接口双重校验，缺一不可）：
- 门户（portal）：免登录对外展示——首页、资讯、行业、活动、视频、应用市场浏览，登录/注册入口
- 工作台（workspace）：登录用户自助服务——云超算（提交/查看作业）、网盘、云桌面、配额用量、消息中心、个人中心
- 租户管理台（tenant）：租户管理员对本租户自助管理——成员管理、作业概览与配额、资源绑定（集群/桌面）、租户统计报表
- 平台管理后台（admin）：平台管理员全量管理——系统/集群/求解器/内容运营/审计/监控/报表/系统参数/门户配置（计费/商品已下线）
四个区共享同一套布局模板与业务组件，管理员与用户操作体验一致。
7.2 页面清单（主要）¶
- 门户：登录（账号/验证码，预留统一登录扩展点）、注册、首页（品牌形象 + 云超算/云桌面/云数据/云应用四大入口 + 资讯/活动/推荐模型固定区块）、资讯列表/详情
- 作业工作台：作业提交向导（选求解器 → 版本 → 动态参数表单 → 文件上传 → 核数/队列）、活跃作业（实时状态）、作业历史（筛选/分页/批量删除）、作业详情（状态时间线、日志 tail、输入输出文件、核时消耗）、作业模板
- 网盘：目录树 + 文件列表（列表/图标视图）、上传（分片/断点续传/秒传）、下载打包、预览（文本/图片）、重命名/移动/删除/解压
- 远程桌面：桌面列表（主机、协议、状态，手动登记与云开通资源统一呈现）、一键连接（内嵌 HTML5 客户端）、桌面启停、连接历史、VNC 端口池管理（管理员）、主机手动登记/纳管（管理员）
- 集群监控：集群卡片（CPU/内存/磁盘占用、队列状态）、监控大屏（ECharts 趋势图 + 节点状态）
- ~~计费中心~~：已下线（V36）；现为「配额用量」页（作业核时用量与仪表盘统计保留）
- 应用市场：应用列表/详情/收藏/评论、批量导入（信息 + 包文件）（试用申请已下线）
- 机理模型库：二维分类筛选——工业品类（土木建筑/机械/机械(压力容器)/电气电子/通用技术/其他）+ 专业学科（结构/流体/电磁/热/通用/材料/其他），"全部"为筛选项，分类字典后台可配置；检索（关键字/标签）、详情（logo/介绍图/文字介绍/运行方式/安装包）、收藏、下载复用、批量导入
- 活动报名：活动列表/详情/报名（问卷）、报名成功页、H5 版、后台活动管理 + Excel 导出
- 视频课堂：视频列表/搜索、播放页（流式播放、清晰度切换、封面预览；雪碧图规划中）、个人中心（收藏/观看记录）、后台管理（上传/转码进度/原片策略）
- 租户管理台：本租户成员管理、作业概览与配额、资源绑定（集群/桌面）、租户统计
- 管理后台：用户管理、租户管理、集群管理（调度器/执行通道/求解器关联）、求解器管理（组/属性/权限）、商品与规格、审计日志（登录/操作）、系统参数、通知模板、云主机订单、监控中心（基础设施 + 业务大盘 + 告警规则）、报表中心（报表生成/订阅/下载）
- 消息中心：站内信收件箱（系统/业务分类、已读未读、批量操作）、通知订阅偏好
- 个人中心：资料、改密、账户安全
7.3 视觉规范（Design Token）¶
- 色彩：主色科技蓝
#2563EB系 + 语义色（成功/警告/危险/信息）+ 中性色阶；深色主题深空底#0B1220系、浅色主题白底蓝灰。状态色语义固定：排队=灰蓝、运行=主蓝、完成=绿、失败=红、停止=橙 - 字体：中文 PingFang/微软雅黑体系；数字与指标用等宽数字（tabular-nums），作业时长/核时等对齐美观
- 字号阶梯 12/13/14/16/20/24/32；间距 4pt 基准（4/8/12/16/24/32）；圆角 4/8/12；阴影 3 级；动效 150–300ms 过渡，尊重系统减弱动效设置
- 全部 CSS 变量化，深浅主题各一套 token，切换一处生效；Element Plus 主题深度定制对齐 token
7.4 布局模板体系（跨页面统一的工程保障）¶
所有页面必须从 7 类标准布局模板出发，同类功能必然同布局，不套模板的页面走查不通过：
| 模板 | 适用页面 | 固化的统一细节 |
|---|---|---|
| ListPage 列表页 | 作业/用户/租户/视频/报名/工单/日志… | 筛选区（可折叠）在上；工具栏按钮顺序规范（主操作最左，批量/导出/列设置最右）；表格 + 分页位置固定；行内操作 >3 个收进"更多"；批量操作条随选择浮现；空态插画 + 引导按钮 |
| DetailPage 详情页 | 作业/活动/应用详情 | 顶部概要卡（状态标签 + 关键指标 + 主操作按钮）+ 标签页内容区；页签记忆 |
| WizardPage 向导页 | 提交作业、活动报名 | 步骤条 + 内容区 + 底部固定操作（上一步/保存草稿/下一步），每步可回退，草稿自动保存 |
| DashboardPage 看板页 | 集群监控、报表、计费中心 | KPI 卡行（数值 + 环比）+ 12 栅格图表网格，图表风格统一（ECharts 主题绑定 token） |
| FormPage 表单页 | 系统参数、长表单 | 分节卡片 + 双列响应式栅格 + 即时校验 + 帮助提示 |
| DialogForm 弹窗表单 | 新增/编辑 | 双列布局；字段 ≤6 个用弹窗，超过转独立表单页；校验失败就地显示 |
| PortalPage 门户页 | 首页、资讯、行业 | 顶部导航 + 区块化内容，区块开关/排序后台配置（见 2.1-13） |
7.5 交互与体验规范（操作便捷性）¶
- 高频动线最短化：提交作业 ≤3 步、连接桌面 1 键（桌面卡片直接"连接"）、文件拖拽上传、结果回传后站内信直达
- 反馈体系：表单即时校验、操作成功/失败 toast、危险操作二次确认、防重复提交、骨架屏加载、长任务（转码/导入/导出）进度 + 完成通知
- 导航：面包屑、页签记忆、Ctrl+K 全局搜索（作业/文件/功能）、导航未读角标
- 表格：列自定义、密度切换、排序、行内操作收敛
- 响应式：≥1440px 标准布局；1366px 压缩侧栏；门户与报名适配平板/手机（H5）
- 无障碍：文本对比度 AA、键盘可达、焦点态可见
7.6 关键页面布局规格（页面级，交付前逐页评审）¶
| 页面 | 布局规格 |
|---|---|
| 登录/注册 | 品牌区（左，深色科技视觉）+ 表单卡（右）；账号/验证码登录、注册引导；忘记密码流程 |
| 门户首页 | 顶部导航 + 品牌 Banner + 四大入口卡（云超算/云桌面/云数据/云应用）+ 可配置区块（资讯/活动/视频/行业） |
| 作业列表 | 见 7.4 ListPage：状态彩色标签、核时/核数等宽数字列、批量删除/导出 |
| 提交向导 | 见 7.4 WizardPage：左侧求解器树（搜索+分组）、右侧动态参数表单、文件上传带进度 |
| 作业详情 | 概要卡（状态时间线 + 停止操作）+ 标签页（概览/日志 tail/输入输出文件/核时与费用） |
| 网盘 | 左侧目录树 + 右侧文件区（图标/列表双视图）、拖拽上传、多选批量操作、回收站入口 |
| 远程桌面 | 桌面卡片网格（主机名/协议/状态）+ 一键连接 + 主机配置入口；连接中全屏加载态 |
| 集群监控 | KPI 卡行（CPU/内存/磁盘/队列）+ 趋势图 + 节点表格（DashboardPage） |
| 管理后台 | 侧边栏 + ListPage CRUD；用户/租户/集群/求解器/计费/内容等各域同构 |
7.7 UI 质量保障（四层统一 + 验收走查）¶
- 设计 token → 样式统一（色彩/间距/字号全站一致）
- 布局模板组件 → 结构统一（同类页面同骨架，强制约束）
- 业务组件库 → 交互统一（JobStatusTag、ClusterMonitorCard、FileUploader、SolverForm 等复用组件，组件文档 Storybook）
- UX 走查清单 → 验收统一，每阶段交付前逐页核对：布局一致性 / 高频操作 ≤3 步可达 / 加载-空态-错误态全覆盖 / 响应式与对比度达标 / 文案完整
工具链：ESLint + Prettier + Stylelint 提交门禁；ECharts 主题绑定 token；视觉回归（Playwright 截图对比）可选。
7.8 品牌资产与素材来源¶
- 素材来源：首页/登录页图片与文字素材、资讯种子内容参考原五个项目（品牌 logo、Banner、行业场景图、文案；资讯/行业/应用种子数据取自原项目 static 目录与 SQL 种子脚本），实施时提取 → 筛选 → 按新 UI 规范适配（重新裁切/导出/文案精修）。历史素材为 JSP 时代分辨率与风格，装饰性素材不直接搬用；对外素材做来源与授权核对
- 浏览器页签标识：页签标题（如"VelaSim 仿真云"，仅中文）与 favicon 均可配置——
sys_param支持站点标题、logo、favicon 文件上传，不同客户/部署可更换品牌标识，无需改代码 - 品牌资产统一管理于前端 assets/brand 目录，token 化的品牌色与站点配置联动
8. 集群侧与桌面侧 Agent（重写为轻量进程）¶
| 构件 | 说明 |
|---|---|
| vela-agent（集群代理，仅分离部署时需要） | Java 21 轻量服务（Spring Boot 3 最小配置或原生镜像可选），部署于每集群登录节点：/job（本地执行 qsub/sbatch 等，白名单命令集）、/netdisk（受限路径文件操作）、/account（Linux/NIS/Samba 账户）、/common（心跳 + 监控快照上传 60s）。无数据库、无状态、可横向多实例。鉴权：平台签发的 agent token。平台部署于控制节点的默认形态下无需部署 |
| vela-host-agent（Windows 桌面/应用主机） | 保留历史 gz/exe 职责：软件黑白名单（tasklist/taskkill）、使用时长统计、超时告警；并承担主机增量配置执行（SMB 挂载刷新、账户与应用策略变更）。策略由平台下发（HTTP 拉取），每 60s 上报使用数据。重写为现代轻量实现 |
原生变体（2026-09 新增）：
velasim-agent-go（Go 单静态二进制 ≈5.5MB）与velasim-host-agent-cs（.NET 10 自包含单文件 ≈48MB），HTTP 契约与 Java 版本完全一致（同一验收脚本devtools/verify-agent-native.mjs验证），面向小体积/零运行时依赖/简化部署；Java 版本维持默认实现。
9. 云桌面/云应用自动开通（独立模块，开关控制）¶
CloudProvider接口（createInstance/start/stop/reboot/delete/describe），HuaweiCloudProvider（huaweicloud-sdk-ecs）与AliyunCloudProvider（阿里云 ECS SDK）双实现，按vela.cloud.provider运行期装配（第 2.3 节可插拔点之一）- 开通流程：选商品规格 → 下单 → 异步创建实例 → 初始化脚本（建账号/加管理员组/挂网盘/改密；Windows 走云助手 RunCommand，Linux 走脚本注入）→ 自动登记桌面连接 → 站内信/短信通知用户可用
- 订单管理：云订单/到期/释放
/cloud/**管理页；到期前提醒（通知中心） - 与手动登记/纳管模式并存（第 3 节决策 7）：
vela.cloud.provider=none时不注册任何云路由，纯手动模式运行
10. 非功能性要求¶
| 维度 | 要求 |
|---|---|
| 安全 | 传输：HTTPS 全站 + JWT（access 30min + refresh 7d，刷新轮换）；存储：BCrypt 密码、桌面/云/SSH 凭据 AES 加密入库、配置文件密钥 Jasypt 加密（历史版本明文密码问题彻底移除）；访问：防 SQL 注入（预编译）、XSS 输出编码、上传类型白名单、下载路径穿越校验、登录限流 + 验证码 + 失败锁定；审计：登录/操作/数据变更日志；P7 安全扫描与渗透测试 |
| 权限控制 | 四层模型：① 认证（JWT + 刷新轮换）；② 功能权限：RBAC 用户-角色-菜单-操作点，按钮级双端（前端 v-permission 指令 + 后端注解）；③ 数据权限：租户数据范围隔离，MyBatis-Plus 拦截器强制注入过滤，管理员可跨租户；④ 资源权限：求解器组/软件粒度授权、桌面/集群与租户绑定。前端路由守卫 + 后端 Security 双重校验，任一单层被绕过不影响安全。会话版本比对库回源经 Caffeine 短缓存（秒级窗口）：吊销事件（停用/删除/改密/改角色）bump 版本即全端生效，缓存仅为防击穿，不构成权限残留窗口；"*" 通配仅 platform:admin 登录时授予；管理面端点缺 @RequiresPerm 拒绝启动（守卫），业务域写端点依赖服务层自校验——清单由 devtools/verify-perm-audit.mjs 审计（基线比对，纳入 CI） |
| 参数校验 | 前端校验仅体验层（即时反馈），后端校验是唯一安全边界：jakarta Bean Validation 统一参数校验（分组/嵌套）、业务规则在 service 层校验、全局异常映射统一错误码、请求体大小限制、写接口幂等键；OpenAPI 契约生成前端 TS 类型，两端校验规则同源 |
| 部署便捷性 | 单 jar + systemd 一条命令部署；CentOS/Ubuntu 一键脚本（环境检查→依赖安装→Flyway 自动建表→配置向导→启动→健康检查）；升级 = 替换 jar + 自动备份 + 一键回滚；全站配置收敛于 application-prod.yml + 部署脚本参数，环境差异零代码改动；Docker 镜像可选 |
| 资源利用率 | 内存：Caffeine 容量上限 + TTL、HikariCP 按规格调优、JVM 堆由部署脚本按服务器内存自动配置、异步队列有界、大文件与导入导出全程流式（防 OOM）；磁盘：文件内容寻址去重（同文件一份）、作业工作区按保留期自动清理、转码/临时产物定期清理、日志滚动 + 压缩归档、备份 30 天轮转、磁盘水位监控 + 告警 |
| 性能/高并发 | 虚拟线程（Java 21 开启）承载高并发 I/O 请求；导入/导出/转码/报表走独立异步线程池（容量可配置）；作业轮询批量化并按集群并发查询；热数据 Caffeine（TTL + 容量上限）；登录/敏感接口令牌桶限流；列表全部分页 + 索引；大文件流式传输；前端路由懒加载 + 按需引入。性能指标目标：单机支撑 ≥500 在线用户；作业列表分页 P95 < 300ms；作业提交接口 P95 < 500ms；监控/报表查询 P95 < 500ms；P7 用 JMeter 压测验证并调优 |
| 可靠性 | 事务边界清晰（计费/核时扣减强一致）；轮询任务幂等；作业完成事件失败重试（本地事件表兜底）；数据备份：MySQL 每日全量 + binlog 增量、保留 30 天、备份恢复脚本 + 恢复演练文档、文件存储目录 rsync 可选；日志归档：logback 按天滚动 + logrotate 压缩归档、保留周期可配置；存储根目录磁盘水位告警 |
| 可观测 | 结构化日志（JSON，traceId 贯穿）；actuator 健康检查；自研运维页（服务器状态 Oshi + 服务指标 + 登录/操作日志查询） |
| 兼容 | 兼容主流浏览器（Chrome/Edge/Firefox 近两年版本）；移动端门户/报名 H5 适配 |
10.1 大数据量治理¶
量级预估与策略（按 500 在线用户、多租户、3 年运营估算）：
| 数据 | 量级预估 | 策略 |
|---|---|---|
| 作业记录 | 百万级 | 覆盖索引（tenant+state+create_time）；深分页用游标（keyset）分页替代大 offset；历史数据按时间归档（月分区/归档表）；统计走 job_statistics_day/month 聚合表，不扫明细 |
| 监控快照 | 千万级（60s/集群） | 原始快照保留 90 天，小时/天粒度聚合长期保留；每日清理任务自动执行 |
| 登录/操作日志 | 千万级 | 保留期可配置 + 按月归档 + 异步导出；界面查询限近期，归档数据按需加载 |
| 网盘/作业文件 | TB 级 | 磁盘容量规划公式（按租户配额估算）；内容寻址去重；工作区保留期清理；用户/租户磁盘配额；水位监控告警 |
| 消费流水 | 百万级 | append-only 不可变；月度对账走 billing_consume_total 聚合表；明细按时间索引 |
| 视频/内容 | GB~TB 级 | 本地存储 + 转码产物独立目录 + 清理策略 |
通用机制：
- 统一数据生命周期管理：每类数据可配置保留期，@Scheduled 每日清理/归档任务，监控中心可视化数据增长趋势
- 查询规范：全部服务端分页；聚合统计预计算（日/月表）；SQL 审查 + 慢查询接入监控中心告警
- 主键雪花 ID（防 UUID 索引膨胀）；批量写分批提交防长事务
- 大文件流式上传/下载 + 分片断点续传（100GB+ 为验证目标）
单机容量边界与演进路径（如实声明边界）：单体 + 内存缓存 + 单库满足上述量级；若未来突破单机容量，预留演进路线且不改业务代码——① 无状态后端多实例 + Nginx 负载均衡（JWT 天然无状态，定时任务预留选主机制）；② MySQL 读写分离；③ 监控快照/日志可转时序库或列存。
10.2 并发一致性设计（应用层 + 数据库层）¶
应用层： - Java 21 虚拟线程承载高并发请求；线程池隔离——业务请求、文件 IO、定时任务、异步任务（导入/导出/转码/报表）分池且均有界，互不拖垮 - 无状态服务 + JWT，可水平扩展；令牌桶限流（登录、敏感接口、上传/下载带宽） - 幂等键：提交作业、报名、充值等写接口携带幂等键，防重复提交
数据库层：
- HikariCP 连接池按规格调优，池状态接入监控中心
- 事务：默认 RC 隔离；边界清晰，杜绝长事务（批量操作分批提交）
- 并发扣费/核时扣减：原子 UPDATE（amount = amount - x WHERE amount >= x）+ 余额不足自然拒绝，行级锁兜底，绝不"读-改-写"裸奔
- 作业状态机：乐观锁（版本号）防并发状态覆盖；作业完成事件消费幂等（恰好一次扣费）
- 防重复：唯一约束（幂等键、分片状态、报名去重）
- 死锁/锁等待：慢查询与锁等待接入监控中心告警
- P7 压测场景专项：并发扣费、并发提交作业、并发上传/下载大文件、报表高峰查询
10.3 MySQL 优化与配置管理¶
- 部署配置模板（随部署脚本交付）：按服务器规格提供三档 my.cnf 模板（8G/32G/128G 内存档），脚本按物理内存自动选择——InnoDB buffer pool 取内存 50~70%、redo log 按写入量设定、
max_connections与 HikariCP 池大小联动、utf8mb4 + 严格sql_mode（防脏数据）、ROW 格式 binlog + 保留期、慢查询日志开启（>1s）、时区与排序规则全站统一 - Schema 与 SQL 规范（编码期执行）：全表 InnoDB + utf8mb4；雪花主键；索引按查询模式设计（联合索引列序、覆盖索引、idx/uk 命名规范）；禁止 SELECT *、禁止无 LIMIT 大查询；大字段已全部迁出（无 BLOB）；核心 SQL
EXPLAIN评审纳入 Code Review 门禁 - 运行时监控与调优：慢查询、锁等待、连接池饱和度接入监控中心告警；季度按监控数据回顾调优（buffer pool 命中率、慢查询 Top、未使用索引）
- 例行维护：每周
ANALYZE更新统计信息（定时任务）；数据生命周期清理与归档（见 10.1）；大表碎片整理策略 - 版本策略：MySQL 8.0.x 基线（兼容 8.4 LTS），版本升级路径写入运维手册
10.4 可用性分级与集群设计（P8）¶
定位声明：VelaSim 以「单实例默认开箱即用、多实例能力可选开启」为交付原则。单实例 + 自愈 + 备份 + 自动化部署是私有化交付的 1.0 形态（可交付产品）；多实例集群是 SaaS 化/大型集团场景的扩展能力（P8 里程碑）。四级可用性，交付时在部署报告中明确当前档位与承诺边界。
分级总览¶
| 级别 | 能力 | 状态 | 承诺基线 |
|---|---|---|---|
| L1 进程级自愈 | systemd Restart=on-failure 5s 拉起；升级自动备份 + 健康检查回滚 |
✅ 已有 | 进程故障自愈秒级 |
| L2 数据级备份 | 每日 2:30 全量备份（MySQL + 网盘文件）、保留策略、备份恢复演练（P7 已含） | ✅ 已有 | RPO = 24h；换机 RTO = 小时级 |
| L3 冷备双机 | 备机同版本部署 + 每日备份同步 + 切换手册 | ⬜ P8 前置任务（文档 + 脚本） | 机器故障 RTO ≤ 2h（人工切换） |
| L4 多实例集群 | 后端水平扩展 + 状态外置 + DB 高可用 | ⬜ P8 | 单实例故障零中断（依赖外部 LB/DB 配置） |
客户规模分级指引（写入售前/交付文档）：单企业 ≤ 数百用户 → L1-L3 足够；多租户 SaaS 化或大型集团（跨地域、数千用户）→ L4。
L3 冷备双机（P8 前置，文档 + 脚本即可交付）¶
- 备机用同版本 deploy.sh 部署（不接流量）
- 每日备份产物同步到备机（rsync/scp + cron；备份目录结构见运维手册）
- 切换流程（运维手册新增「故障切换」章）：停止主站写入（可选）→ 备机恢复最新备份 → nginx/域名指向备机 → 冒烟验证（健康检查/登录/作业提交）
- 演练要求：交付验收包含一次冷备切换演练（P7 备份恢复演练的扩展）
L4 多实例集群设计（P8）¶
设计原则：单实例默认零依赖（一个 jar 交付不变）；集群能力全部开关化（vela.redis.enabled、vela.cluster.scheduler-lock 等），开启后引入对应依赖与配置。
已有基础：无状态 JWT（无 HTTP session，认证不依赖实例）；存储双模式（网盘平台存储 / NFS-Lustre 共享存储直连，P3 已实现）；7 类可插拔接口（缓存/存储/通知等抽象已存在）。
阻塞点与方案（现状 → 改造）：
| # | 阻塞点 | 现状 | 方案 |
|---|---|---|---|
| 1 | 定时任务重复执行 | @Scheduled：作业轮询/监控采集/到期提醒/备份/统计 |
引入 ShedLock（基于 MySQL 表锁，零新依赖）；全部定时任务加 @SchedulerLock；备选：独立 worker 实例 |
| 2 | WS 隧道粘性 | Guacamole/终端隧道注册表为实例内存（LiveTunnelRegistry），重连必须回原实例 | 部署文档化：LB 按 /api/v1/desktop/ 路径 ip_hash 粘性路由；后端无需改动 |
| 3 | 内存态跨实例不可见 | 登出黑名单（TokenBlacklist）/在线用户表（OnlineUserRegistry）/登录限流/OTP 尝试限流 | 抽象为接口 + Redis 实现（vela.redis.enabled 开启）；内存实现保留为单实例默认 |
| 4 | 本地缓存不一致 | Caffeine 每实例一份 | 单实例默认保留；集群档开启 Redis 缓存实现（缓存抽象已可插拔）；容忍秒级不一致的缓存（如集群台账）维持本地 |
| 5 | MySQL 单点 | 单库 | 部署级：主从 + 半同步复制 + keepalived VIP（部署手册新增附录）；或客户侧云 RDS 托管 |
| 6 | 前端/LB | nginx 单点 | 部署级：云 SLB 或 keepalived 双机 VIP |
验收标准（P8）：
- 双实例部署后：作业轮询/到期提醒无重复执行（ShedLock 生效）
- 实例 A 登出后，令牌在实例 B 同样失效（黑名单 Redis 共享）
- WS 隧道经 LB 重连粘性命中原实例（ip_hash 验证）
- 登录限流跨实例计数一致（Redis）
- 压测基线：双实例吞吐 ≥ 单实例 1.8 倍（JMeter 复用 P7 压测脚本）
- 部署手册/运维手册补齐集群形态章节（含回退到单实例的操作路径）
11. 里程碑计划¶
| 阶段 | 内容 | 交付物 |
|---|---|---|
| P0 工程基座 | 前后端工程搭建、CI 构建、Flyway、统一响应/错误码/异常、Caffeine、结构化日志（含归档策略）、登录/操作日志、站内信框架、部署脚本骨架、前端设计 token + 7 类布局模板组件 + 深/浅主题框架 | 可运行空框架 |
| P1 认证与系统域 | JWT 认证、用户/租户/角色/菜单 RBAC、参数、审计、门户登录注册（首页/登录页素材自原项目提取与适配）+ 布局/主题/i18n 框架 | 可登录可管理 |
| P2 作业域 | 集群台账、求解器注册表、调度引擎抽象 + SGE/Slurm 实现、local/agent/ssh 三执行通道完整实现、作业状态机、核时计量、作业模板、作业工作台前端 | 可提交可跑作业 |
| P3 网盘 + 桌面 + 监控 | 网盘（分片上传）、Guacamole 内嵌隧道、桌面生命周期（手动登记/纳管为主，云开通在 P6）、集群监控心跳 + 大屏 | 核心三件套齐 |
| P4 商业化 | 预付费计费、商品 SKU、试用申请、计费中心前端 | 可计费可售卖 |
| P5 运营内容 | 应用市场、机理模型库（新增）、活动报名（含 H5）、视频课堂（FFmpeg 转码）、资讯/专家/客服/工单（资讯种子素材自原项目提取迁移） | 门户完整 |
| P6 云集成 | 云抽象接口 + 华为/阿里 ECS 自动开通、双云短信、云订单管理页 | 可接云 |
| P7 运维与交付 | vela-host-agent、监控中心（服务器/应用/MySQL/缓存 + 告警）、报表中心、主题打磨、双语完整性、性能压测与调优（JMeter）、安全测试、CentOS/Ubuntu 一键部署脚本 + 域名证书自动签发/续期 + 备份恢复演练 + 日志归档验证、文档（部署/运维/接口/用户手册，按 4.4 质量标准评审） | 产品级交付包 |
| P8 可用性与集群 | 冷备双机（备机部署 + 备份同步脚本 + 故障切换手册 + 切换演练）→ 多实例集群（ShedLock 定时任务协调、WS 隧道粘性路由文档化、Redis 可插拔外置内存态、DB 主从部署附录、LB 高可用附录）→ 集群形态验收（见 10.4 验收标准） | 高可用交付包（可选档位） |
实施方式（已确认）：不设团队排期，按里程碑顺序连续实施，每阶段完成交付验收。工作量量级仅供预期参考：P0 ≈ 1-2 人月；P1 ≈ 2-3；P2 ≈ 4-6（调度器双实现 + 三执行通道为核心攻坚）；P3 ≈ 3-4；P4 ≈ 2-3；P5 ≈ 3-4；P6 ≈ 2-3；P7 ≈ 2-3。核心域 P0-P4 先行，运营与云集成随后。
12. 风险与依赖（需要需求方提供）¶
| # | 事项 | 说明 |
|---|---|---|
| 1 | 云厂商凭证 | 华为云/阿里云 ECS、短信的 AK/SK 与已备案短信签名（P6 联调前提供） |
| 2 | 测试集群 | 至少各一台 SGE 与 Slurm 集群（含求解器 license）用于 P2 联调；一台 Windows 桌面机用于桌面与 host-agent 联调 |
| 3 | 基础环境 | guacd、FFmpeg、Samba 安装（部署脚本包含）；MySQL 8 服务器 |
| 4 | 域名与证书 | 证书自动化（acme.sh + Let's Encrypt）需域名解析控制权且公网 80/443 可达；正式域名清单（主站/视频/桌面等子域）需确认 |
| 5 | 视觉确认 | 主题色彩/门户首页品牌稿需需求方确认（P1 前提供方向即可，先行用设计 token 实现） |
| 6 | 旧数据迁移 | 已确认范围：机理模型存量数据（约 1100+ 条，导入模板迁入 + 旧库导出转换脚本）+ 内容素材（资讯/活动/应用等种子数据）。用户/租户/作业历史不迁移。需提供旧库访问权限或数据导出文件 |