# easyDeploy

**Repository Path**: sprouting/easy-deploy

## Basic Information

- **Project Name**: easyDeploy
- **Description**: 易部署平台，解决平台快速部署，可视化问题
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-14
- **Last Updated**: 2026-03-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 易部署平台（easy-deploy）

## 1. 背景与目标

我们的业务应用以 **Spring Boot 3 + Docker** 方式部署，但项目数量多、版本迭代频繁，导致安装部署工作重复、成本高、且对安装人员经验要求较高。

同时存在一个核心约束：

- 开发/打包环境可联网
- 生产环境离线（内网隔离、禁止联网）

本项目的目标是做一个“可视化的一键离线部署工具”：

- 在开发环境中完成离线资源准备（Docker 离线安装包、镜像、Compose 文件、Nginx/前端包、Linux 依赖等），并做统一归档/备份
- 将完整的“离线部署目录”拷贝到生产离线环境
- 安装人员只需启动本工具，在页面通过选择/勾选即可完成安装与部署，并能看到过程进度与错误提示

说明：当前仓库代码仍处于初始化阶段，部署业务（项目定义、打包/安装能力）尚未实现，README 先沉淀整体架构与需求边界，便于后续落地。

---

## 2. 当前项目架构梳理（基于现有代码）

### 2.1 技术栈

- Java 21
- Spring Boot 3.5.4（Web + AOP + Validation）
- Freemarker（页面模板渲染）
- springdoc-openapi（Swagger UI）
- MyBatis-Plus + Druid（持久化框架与连接池）
- H2（当前为文件模式）
- Liquibase（数据库结构变更管理）
- Hutool（工具库）

依赖清单入口：[pom.xml](file:///e:/kaiFa/IDEATest/easy-deploy/pom.xml)

### 2.2 包结构与职责

源码根包：`com.sprouting.deploy`

- 启动入口：`EasyDeployApplication`（调度、异步、事务、Mapper 扫描）
  - [EasyDeployApplication.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/EasyDeployApplication.java)
- `config`：通用基础配置
  - 跨域： [CorsConfig.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/config/CorsConfig.java)
  - MyBatis-Plus：分页拦截器 + 批量插入 + 物理删除注入
    - [MybatisPlusConfig.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/config/MybatisPlusConfig.java)
  - 全局线程池：用于后续“长耗时部署任务”的统一并发执行
    - [ThreadPoolConfig.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/config/ThreadPoolConfig.java)
  - H2 数据库文件自动创建：启动时自动补齐 `.mv.db` 文件
    - [DatabaseAutoCreatorAutoConfiguration.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/config/DatabaseAutoCreatorAutoConfiguration.java)
- `controller`：控制器层（当前仅有基础页面路由）
  - `/` → `home.ftl`，`/404`、`/500` → 对应错误页
  - [HtmlBaseController.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/controller/base/HtmlBaseController.java)
- `common/exception`：控制器层全局异常处理（统一返回 `ResultJson` 或 404）
  - [GlobalExceptionHandler.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/common/exception/GlobalExceptionHandler.java)
- `entity/base`：基础实体与通用返回体
  - [ResultJson.java](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/java/com/sprouting/deploy/entity/base/ResultJson.java)
- `resources`
  - `templates/`：Freemarker 页面（首页 + 404/500）
  - `static/`：静态资源（当前仅放置了 Vue 文件等）
  - `db/changelog/`：Liquibase 脚本（目前为空模板）
  - `mapper/`：MyBatis XML（目前为空模板）

### 2.3 配置与运行入口

主配置文件：[application.properties](file:///e:/kaiFa/IDEATest/easy-deploy/src/main/resources/application.properties)

关键点：

- 服务端口：`server.port=8030`
- 数据源：当前为 H2 文件库（示例为 Windows 路径，后续建议改为相对路径/可配置）
- Liquibase：`spring.liquibase.change-log=classpath:db/changelog/master.xml`
- 上传限制：单文件/总请求 `3072MB`
- 自定义线程池：`customize.thread.pool.*`

Swagger：

- `/swagger-ui.html`
- `/v3/api-docs`

---

## 3. 需求文档：离线一键部署（核心）

### 3.1 角色与场景

- 打包人员（开发环境）：有网络权限，负责准备离线部署物料并输出“离线部署目录/离线包”
- 安装人员（生产离线环境）：无经验或经验有限，只能按页面向导操作完成部署

### 3.2 总体思路（推荐落地形态）

“一键部署”并不意味着完全不用脚本，而是：

- 实际系统操作仍由脚本/命令完成（docker 安装、docker load、docker compose up 等）
- 由本工具统一编排（参数收集、前置检查、执行顺序、进度展示、错误归因与提示、日志留存、可回滚）
- 所有依赖全部离线化（引擎、插件、镜像、配置、系统依赖包）

### 3.3 业务范围（要做什么）

#### A. 开发环境（联网）——离线物料准备/备份

- 镜像与组件归档
  - 按项目/版本选取镜像列表，并执行 `docker save` 输出 tar
  - 归档 docker-compose.yml、.env、nginx 配置、前端包、初始化 SQL/配置等
- 离线安装包准备
  - Docker Engine 离线安装包（按目标 OS 发行版区分：RHEL/CentOS 系、Debian/Ubuntu 系）
  - Docker Compose（建议优先使用 Docker Compose V2 插件方式：`docker compose`）
  - Linux 依赖包（如 iptables、conntrack、ca-certificates、unzip 等，根据目标 OS 列表化）
- 物料一致性与可追溯
  - 生成版本清单（manifest）：每个文件的 sha256、大小、来源版本、构建时间
  - 生成部署说明元数据（项目名、版本、端口、数据卷、健康检查方式）
- 定时备份
  - 对“离线部署目录”做定时快照备份（按日期/版本归档）

#### B. 生产环境（离线）——可视化安装/部署

- 环境检查（安装前）
  - OS 版本识别、CPU/内存/磁盘空间、端口占用
  - 是否具备 root/sudo 权限
  - 目标依赖是否齐全（内核模块、iptables/nft、cgroup、SELinux/防火墙策略提示等）
- 安装 Docker 与 Compose（离线）
  - 检测已安装版本，必要时升级/降级策略（可配置）
  - 安装后自检：`docker version`、`docker info`、`docker compose version`
- 导入镜像与部署
  - `docker load` 导入镜像 tar
  - 写入项目配置（生成 `.env` 或配置文件）
  - 执行 `docker compose up -d` 启动
  - 健康检查与结果展示（容器状态、关键接口探活、日志关键字）
- 维护能力（离线）
  - 停止/启动/重启
  - 查看实时日志、导出诊断包（容器日志 + 本工具日志 + 系统信息摘要）
  - 更新：选择新版本离线包 → 执行滚动升级/停机升级
  - 回滚：回到上一个可用版本（基于备份与镜像留存）

### 3.4 非功能需求（必须明确）

- 安全
  - 严禁联网下载；所有网络访问默认关闭
  - 操作审计：谁在何时对哪个环境执行了什么操作、结果如何
  - 脱敏：页面与日志不可泄露密码/密钥
- 可用性
  - 对“无经验安装人员”友好：向导式流程、明确错误提示与修复建议
  - 长耗时任务要可见：进度、阶段、耗时、可取消（能力可按阶段实现）
- 一致性
  - 开发环境打包产物在离线环境可复现部署结果（同版本同清单）
- 可扩展
  - 支持多项目、多版本共存
  - 支持不同 OS 发行版的离线安装策略

### 3.5 边界与不做的事（建议写死，避免需求膨胀）

- 不承担 CI/CD（构建由现有流水线完成，本工具只负责“离线物料归档与部署编排”）
- 不做 K8s 集群管理（当前范围为 Docker/Compose 单机或少量主机）
- 不负责业务应用的功能健康判定（只做基础探活/可配置的健康检查规则）

---

### 3.6 功能清单（按模块拆解，可直接按此做开发）

#### 3.6.1 离线资源中心（开发环境）

- 维护目标离线环境信息（OS 发行版/版本、架构、是否允许 root、磁盘要求）
- 维护 Docker 离线安装包
  - 上传/导入离线包（rpm/deb/tgz 等）
  - 标记适配范围（发行版、版本、架构）
  - 校验文件完整性（sha256）
- 维护 Compose 组件（优先 V2 插件）
  - 上传 compose 二进制或插件包
  - 校验可执行性与版本
- 维护 Linux 依赖包集合
  - 按发行版维护依赖清单（rpm/deb）
  - 输出“依赖安装计划”（离线安装顺序）
- 维护通用组件包
  - Nginx（镜像或离线安装包）、前端静态包、证书与基础配置模板
- 生成离线交付目录
  - 将上述资源按约定目录结构写入 `easy-deploy-kit/`
  - 生成 `manifest.json`（文件清单、sha256、版本元数据）
  - 生成 `release.json`（项目版本部署定义，供离线环境直接部署）

#### 3.6.2 项目与版本管理（开发环境）

- 项目定义
  - 项目名、部署方式（compose）、端口规划、数据卷规划、基础健康检查
  - 必选组件（nginx/前端包/配置模板/初始化脚本）
- 版本定义（Release）
  - 版本号、镜像列表、compose 文件、环境变量模板、升级策略、回滚策略
  - 版本依赖（必须先装 docker/compose/特定 linux 依赖）
- 版本物料生成
  - 镜像导入：从本机 docker 拉取镜像并登记（离线环境只 load）
  - 镜像归档：按版本执行 `docker save` 输出 tar（多镜像可合并或拆分）
  - compose 归档：固定化 compose 文件与 `.env` 模板
  - 业务附件：nginx 配置、前端包、配置文件、脚本、初始化 SQL 等

#### 3.6.3 环境与主机管理（离线/生产环境）

- 环境（Environment）建档
  - 环境名、用途（测试/预发/生产）、主机列表（单机或多机）、网络说明
- 主机（Host）建档
  - IP/主机名、SSH 端口/认证方式（建议先走本机部署，后续再扩展远程）
  - OS 信息采集（发行版、版本、内核、架构）
- 环境体检
  - 磁盘空间、端口占用、时间同步建议
  - cgroup、iptables/nft、SELinux、firewalld 等风险项提示

#### 3.6.4 安装部署向导（离线/生产环境，面向无经验人员）

- 离线包导入
  - 选择离线交付目录（或上传压缩包并解压）
  - 校验 `manifest.json`（文件缺失/sha256 不一致直接阻断）
  - 解析 `release.json`，生成可部署项目/版本列表
- 一键安装（docker + compose + 依赖）
  - 自动识别发行版并选择对应离线安装方案
  - 安装前后自检（版本、服务状态、group、权限）
- 一键部署（项目）
  - 选择项目 → 选择版本 → 填写必要参数（端口、路径、账号等）
  - 写入 `.env` 或配置文件
  - `docker load` 导入镜像
  - `docker compose up -d` 启动
  - 健康检查与结果页（可复制的失败原因与修复建议）

#### 3.6.5 任务中心（所有环境）

- 统一把“安装、导入、部署、更新、回滚、备份、诊断”抽象成任务
- 任务进度
  - 阶段化步骤（Step），每步都有开始/结束/耗时/结果
  - 页面实时刷新任务状态，支持查看每步日志片段
- 任务控制
  - 防重复：同一环境同一项目的部署任务互斥（锁）
  - 可取消：对可中断步骤提供取消（至少做到“停止后续步骤”）
- 日志留存
  - 任务日志与系统日志分离，可导出

#### 3.6.6 运维与保障（离线/生产环境）

- 应用生命周期
  - 停止/启动/重启项目（compose down/up/restart）
  - 查看容器状态、查看最近 N 行日志、下载完整日志
- 更新与回滚
  - 更新：导入新版本 → 执行升级策略（停机升级/滚动升级，按项目定义）
  - 回滚：选择历史版本 → 恢复 compose/env/数据卷快照（按策略）
- 备份与恢复
  - 备份：镜像、compose/env、nginx/前端、数据卷（可选）、数据库文件（如使用）
  - 恢复：从备份点回灌并重启
- 诊断包
  - 一键导出诊断包（系统信息摘要 + docker 信息 + 容器日志 + 任务日志）

#### 3.6.7 系统设置与安全

- 安装模式
  - 离线模式强制开启（默认不允许任何外部网络访问）
- 权限与账号
  - 最小化权限原则（需要 root 的步骤显式提示）
  - 操作审计（操作人、时间、对象、结果）
- 参数与模板
  - `.env` 模板变量管理与校验规则（必填、格式、范围）

### 3.7 关键流程（把“一键”落到可执行步骤）

#### 3.7.1 开发环境：生成离线交付目录（打包人员）

1. 创建/选择项目
2. 创建版本（Release），录入镜像列表与 compose 文件
3. 生成镜像 tar（docker save），归档 compose/env/nginx/前端/脚本
4. 选择目标离线环境类型（发行版/架构），打入对应 docker/compose/linux-deps 离线包
5. 生成 `manifest.json` 与 `release.json`
6. 输出 `easy-deploy-kit/`，对该目录做定时备份/快照

#### 3.7.2 离线环境：安装与部署（安装人员）

1. 启动本工具（同目录自带 jre 与启动脚本）
2. 在页面导入离线交付目录，完成 manifest 校验
3. 运行环境体检（阻断项必须先修复，提示项可继续）
4. 运行“一键安装基础组件”（docker + compose + linux 依赖）
5. 选择项目与版本，填写参数（端口/路径/账号等）
6. 执行“一键部署”，过程分阶段展示
7. 通过健康检查页确认部署结果，必要时导出诊断包

#### 3.7.3 更新与回滚（维护人员）

- 更新
  1. 导入新版本离线包（或同离线目录新增版本）
  2. 执行更新任务（按项目定义：停机升级或滚动升级）
  3. 执行升级后健康检查，失败则进入“自动回滚/手动回滚”
- 回滚
  1. 选择回滚目标版本与备份点
  2. 恢复 compose/env（必要时恢复数据卷快照）
  3. 重启并做健康检查

### 3.8 页面清单（安装人员可按菜单点击完成）

建议页面按“向导 + 任务中心 + 运维”组织（路径可按实现调整）：

- 首页：入口导航与当前环境状态概览
- 离线包导入：选择目录/上传包、manifest 校验、展示可用项目版本
- 环境体检：一键检测与修复建议（可导出检测报告）
- 基础组件安装：安装 docker/compose/依赖，显示步骤与日志
- 项目部署：选择项目/版本、填写参数、执行部署任务
- 任务中心：任务列表、任务详情（步骤、耗时、日志）
- 项目运维：项目列表、容器状态、日志查看、重启/停止
- 备份与恢复：备份点列表、创建备份、恢复操作
- 诊断导出：选择范围，一键打包下载
- 系统设置：离线目录、默认路径、模板变量、权限与审计

### 3.9 API 清单（页面调用，后端对任务编排提供稳定接口）

API 以“任务驱动”组织，保证页面只负责触发任务与展示状态：

- 离线包
  - 导入离线目录并校验：`POST /api/kit/import`
  - 查询当前已导入离线包信息：`GET /api/kit/current`
- 环境体检
  - 发起体检任务：`POST /api/check/run`
  - 查询体检报告：`GET /api/check/report/{taskId}`
- 基础组件安装
  - 发起安装任务：`POST /api/install/base/run`
- 项目/版本
  - 查询项目列表：`GET /api/projects`
  - 查询项目版本：`GET /api/projects/{projectId}/releases`
- 部署/运维
  - 发起部署任务：`POST /api/deploy/run`
  - 发起更新任务：`POST /api/deploy/upgrade`
  - 发起回滚任务：`POST /api/deploy/rollback`
  - 启停/重启：`POST /api/apps/{appId}/action`
- 任务中心
  - 任务列表：`GET /api/tasks`
  - 任务详情：`GET /api/tasks/{taskId}`
  - 任务取消：`POST /api/tasks/{taskId}/cancel`
- 诊断与备份
  - 发起备份：`POST /api/backup/run`
  - 发起诊断导出：`POST /api/diagnose/export`

### 3.10 数据模型（用 H2 存运行状态，便于断点续跑与审计）

建议先以最小集合落表（字段可按实际增减）：

- `project`：项目定义（name、code、deploy_type、default_env_template）
- `release`：版本定义（project_id、version、compose_path、images、upgrade_policy、rollback_policy）
- `artifact`：离线物料（type、os_family、os_version_range、arch、file_path、sha256、size）
- `environment`：环境（name、type、remark）
- `host`：主机（environment_id、hostname、ip、os_info、arch、status）
- `task`：任务（type、status、target、created_by、started_at、ended_at）
- `task_step`：任务步骤（task_id、step_no、name、status、started_at、ended_at、error_code）
- `task_log`：任务日志（task_id、step_id、level、content、created_at）
- `audit_log`：审计（actor、action、target、result、created_at）

### 3.11 任务编排与执行（怎么做才能稳定）

统一把所有动作拆成“可重放步骤”，每一步都要做到：

- 明确输入与输出（参数、产物路径、状态变更）
- 幂等（重复执行不会造成更坏的结果）
- 可观测（日志与错误码明确）
- 可中断（至少做到中断后续步骤，不再继续破坏）

建议的 Step 类型（实现上就是不同的执行器）：

- `CHECK`：环境检查（端口、磁盘、权限、依赖）
- `FILE`：文件操作（复制、解压、写入 env、计算 sha256）
- `CMD`：执行系统命令（docker/compose/rpm/dpkg 等）
- `DOCKER`：对 docker 的高阶封装（load/save/pull/info）
- `HEALTH`：健康检查（HTTP 探活、容器状态、关键日志关键字）

互斥与资源锁建议以“环境 + 项目”为粒度，避免并发部署互相覆盖。

### 3.12 失败处理与回滚点（避免“失败后更糟”）

把失败拆成可定位的类别，并给到页面可复制的修复建议：

- 离线包类：缺文件、sha256 不一致、版本不匹配（阻断）
- 环境类：磁盘不足、端口冲突、权限不足、系统依赖缺失（部分阻断）
- Docker 类：安装失败、服务未启动、版本不兼容、镜像导入失败（阻断）
- Compose 类：配置错误、变量缺失、启动失败（阻断）
- 应用类：健康检查失败、启动后崩溃（可选自动回滚）

回滚点建议至少具备：

- 部署前：compose/env 备份
- 启动前：数据卷快照（可选，按项目策略）
- 更新前：上一个版本可直接恢复（保留镜像与配置）

### 3.13 离线包规范（让离线环境无需“猜”）

离线交付目录中，以下文件建议作为强约束：

- `manifest.json`：文件清单（sha256、大小、相对路径、生成时间）
- `release.json`：本次交付包含的项目/版本定义（供离线环境直接展示并部署）

`manifest.json` 示例（字段可按实现调整）：

```json
{
  "kitVersion": "1.0",
  "generatedAt": "2026-03-14T12:00:00+08:00",
  "files": [
    { "path": "projects/demo/1.0.0/images/app.tar", "sha256": "xxx", "size": 123456789 },
    { "path": "projects/demo/1.0.0/compose/docker-compose.yml", "sha256": "yyy", "size": 2345 }
  ]
}
```

`release.json` 示例（字段可按实现调整）：

```json
{
  "projects": [
    {
      "code": "demo",
      "name": "示例项目",
      "releases": [
        {
          "version": "1.0.0",
          "images": ["images/app.tar"],
          "compose": "compose/docker-compose.yml",
          "envTemplate": "compose/.env.tpl",
          "health": { "type": "http", "url": "http://127.0.0.1:8080/actuator/health", "timeoutSeconds": 60 }
        }
      ]
    }
  ]
}
```

---

## 4. 离线部署目录（建议的约定结构）

离线拷贝到生产环境的“同级目录”建议具备清晰结构，便于校验与工具编排（名称可调整）：

```text
easy-deploy-kit/
  app/                     # 本工具运行文件（jar/配置/logs）
  jre/                     # 自带 JRE（若采用“自带运行时”的交付方式）
  bin/                     # start.sh / stop.sh（以及 Windows 启动脚本）
  packages/                # 各类离线安装包
    docker/                # docker engine 离线包（按 OS 分类）
    compose/               # compose 插件或二进制
    linux-deps/            # 系统依赖（rpm/deb 等）
  projects/                # 项目定义（每个项目一个目录）
    <project-a>/
      <version>/
        compose/           # docker-compose.yml / .env 模板
        images/            # docker save 输出的 *.tar
        nginx/             # nginx 配置/镜像等（如需要）
        frontend/          # 前端包/静态资源（如需要）
        manifest.json      # 文件清单（sha256/大小/版本信息）
  backups/                 # 备份（按时间或版本归档）
```

---

## 5. 下一步落地建议（从最小可用开始）

为了尽快达成“能用”，建议按阶段推进：

1. 离线包规范与 manifest：先把“离线目录结构”和“版本清单校验”定下来
2. 离线环境检测 + Docker/Compose 离线安装：把最难踩坑的系统差异先覆盖
3. 项目定义模型：把“一个项目需要哪些镜像/compose/env/端口/卷”抽象为可配置
4. 部署编排与进度可视化：把脚本执行过程变成阶段化进度与错误归因
5. 更新/回滚/诊断包：降低维护与故障处理成本