# pyi-easy-deploy

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

## Basic Information

- **Project Name**: pyi-easy-deploy
- **Description**: 专为开发者打造的极简 DevOps 部署工具 | 只做部署，拒绝臃肿 | 极致轻量 | 部署超简单 |  体验拉满
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pyi-easy-deploy

🔥 专为开发者打造的极简 DevOps 部署工具 | 只做部署，拒绝臃肿

---

**开发者**：PYI开源团队


## 为什么放弃宝塔/Jenkins 选择 EasyDeploy？

| 工具       | 定位                | 痛点                          | EasyDeploy 解决方案          |
|------------|---------------------|-------------------------------|------------------------------|
| 宝塔面板   | 服务器全能管理      | 功能冗余、占资源、部署流程复杂 | 仅聚焦部署、轻量无冗余、一键搞定 |
| Jenkins    | 企业级复杂 CI/CD    | 配置成本高、学习曲线陡        | 0 学习成本、5 分钟上手、开箱即用 |


## 核心优势

✅ **零依赖启动**：一条 `java -jar easydeploy.jar` 直接跑，使用 H2 内嵌数据库，无需安装 MySQL/Redis/Docker/K8s

✅ **极致轻量**：安装包小，内存占用 < 100MB，低配云服务器也能轻松运行

✅ **全场景适配**：支持 SpringBoot Jar / Vue 前端 / Uniapp / 静态网站，覆盖开发者日常所有项目类型

✅ **部署超简单**：仅需填写 Git 仓库地址、部署路径、启动命令，1 分钟完成配置

✅ **实时日志推送**：基于 WebSocket 的实时日志展示，部署过程一目了然

✅ **智能进程守护**：每 30 秒自动检测进程状态，进程意外退出自动重启

✅ **一键版本回滚**：自动备份历史版本，支持一键回滚到任意版本

✅ **环境自动检测**：自动检测 Java / Maven / NPM / Nginx / Git 等运行环境，智能提示缺失依赖

✅ **资源实时监控**：实时显示项目进程的 CPU / 内存占用，系统资源一目了然

✅ **多重自动化触发**：
  - WebHook 自动触发（Gitee/GitHub 推送代码自动部署）
  - 定时自动部署（Cron 表达式，灵活设置部署时间）
  - 邮件通知（部署成功/失败自动推送通知）

✅ **健康检查保障**：部署完成后自动验证服务是否正常启动，失败时自动回滚

✅ **多环境管理**：支持同一项目配置 dev/test/prod 多个部署环境

✅ **安全防护体系**：
  - 命令白名单机制（仅允许预定义的安全命令）
  - 危险字符过滤（防止命令注入攻击）
  - 路径遍历防护（阻止目录穿越攻击）
  - 网络访问控制（白名单机制，可一键禁止外网访问）

✅ **增量部署优化**：基于 Git commit hash 智能判断代码是否变更，避免重复部署

✅ **灵活变量替换**：支持在部署命令中使用 `${PROJECT_NAME}`、`${BRANCH}` 等变量

✅ **插件扩展能力**：支持通过配置扩展通知渠道（钉钉、企业微信等）

✅ **跨平台兼容**：完美支持 Windows、Linux、macOS 三大主流操作系统


## 谁适合用

- 个人开发者 / 独立开发者（不想折腾复杂运维，专注写代码）
- 小团队 / 外包团队（快速部署项目，无需专职运维人员）
- 学生 / 毕设（快速搭建部署流程，不用花时间学 Jenkins）
- 中小企业（低成本实现自动化部署，降低运维成本）


## 支持的项目类型

| 项目类型       | 核心能力                          |
|----------------|-----------------------------------|
| SpringBoot Jar | 拉代码→打包→备份→启动→进程守护    |
| Vue 前端       | 拉代码→npm build→Nginx 自动部署   |
| Uniapp         | 拉代码→打包H5/小程序→自动上传     |
| 静态网站       | 拉代码→直接部署到 Nginx 目录      |


## 快速开始（5 分钟上手）

### 1. 下载安装包

前往 `https://gitee.com/cnpyi/easy-deploy/releases` 下载最新版 `easydeploy.jar`


### 2. 启动项目

```bash
# 无需任何前置配置，直接启动
java -jar easydeploy.jar
```

### 3. 访问系统

打开浏览器访问 `http://localhost:18988`

**默认账号**：admin  
**默认密码**：admin123

### 4. 开始部署

1. 登录系统后，点击「新增项目」
2. 填写项目信息，选择项目类型
3. 点击「保存」创建项目
4. 在项目列表页面点击「部署」按钮
5. 等待部署完成，查看部署状态


## 功能特性

### 系统基础
- 账号密码登录（默认 admin/admin123）
- 密码修改
- 系统基础配置（端口/日志路径）
- **系统配置管理**：WebHook、邮件服务器、定时任务等全局配置

### 项目管理
- 新增/编辑/删除项目
- 项目列表展示（名称/类型/状态/部署时间）
- 项目配置模板（SpringBoot/Vue 自动填充默认命令）
- **定时部署配置**：支持Cron表达式配置自动化部署

### 一键部署
- Git 拉取代码（支持 HTTPS/SSH）
- 自动执行构建命令
- 旧版本备份（压缩到 backup 目录）
- 执行启动命令
- **详细进度显示**：实时展示每个部署步骤的状态

### 进程管理
- 查看项目运行状态（运行/停止）
- 启动/停止/重启项目
- 进程守护（检测 PID，挂了自动重启）
- **跨平台兼容**：Windows/Linux 系统进程管理

### 日志查看
- 实时滚动查看部署/运行日志
- **日志级别筛选**：INFO/ERROR/WARN/DEBUG 级别过滤
- **时间范围筛选**：按日期筛选日志
- **日志自动清理**：保留7天日志，自动清理过期日志
- 日志搜索/清空
- 历史日志下载

### 版本回滚
- 展示所有部署版本记录
- 一键回滚到指定版本
- 回滚日志记录

### 自动化触发
- **WebHook 触发**：支持 Gitee/GitHub WebHook 自动触发部署
- **定时部署**：基于 Cron 表达式的定时自动化部署
- **邮件通知**：部署成功/失败时发送邮件通知

### 安全特性
- **命令执行安全**：严格的命令白名单和危险字符过滤
- **路径遍历防护**：防止目录穿越攻击
- **异常处理优化**：详细的错误信息和堆栈跟踪
- **CSRF 防护**：防止跨站请求伪造攻击


## 技术栈

- **后端**：Spring Boot 2.7.15 + Spring Security + JPA + H2 Database
- **前端**：原生 HTML5 + CSS3 + JavaScript
- **Git 操作**：JGit 5.13.0
- **邮件服务**：Spring Mail + Jakarta Mail
- **构建工具**：Maven 3.8+
- **WebSocket**：实时日志推送


## 系统要求

- Java 8 或更高版本
- 至少 100MB 内存
- 至少 100MB 磁盘空间


## 配置说明

### 邮件通知配置
在系统配置页面中配置：
- SMTP 服务器地址和端口
- 邮箱用户名和密码
- 发件人邮箱地址
- 默认收件人邮箱地址

### WebHook 配置
在系统配置页面中配置：
- WebHook 安全令牌（用于验证请求来源）
- 默认部署分支

### 定时部署配置
在项目编辑页面中配置：
- Cron 表达式（例如：`0 0 2 * * ?` 表示每天凌晨2点执行）
- 定时部署开关


## 常见问题

### Q: 部署失败怎么办？
A: 查看部署日志，根据错误信息排查问题。常见原因包括：Git 仓库地址错误、构建命令失败、端口被占用等。

### Q: 如何修改默认端口？
A: 修改 `application.yml` 文件中的 `server.port` 配置，或在启动时指定：`java -jar easydeploy.jar --server.port=8080`

### Q: 如何配置邮件通知？
A: 在系统设置页面中配置邮件服务器信息，包括SMTP服务器、端口、用户名、密码等。

### Q: WebHook 如何使用？
A: 在系统配置中获取 WebHook URL，然后在 Gitee/GitHub 仓库的 WebHook 设置中添加该 URL 即可。

### Q: 定时部署的 Cron 表达式格式是什么？
A: 使用标准的 Quartz Cron 表达式格式，例如：
- `0 0 2 * * ?` - 每天凌晨2点
- `0 0/30 * * * ?` - 每30分钟
- `0 0 9-18 * * MON-FRI` - 工作日9-18点每小时

### Q: 支持多服务器部署吗？
A: v2.0 版本已支持集群部署功能，可通过系统配置进行多服务器管理。


## 社区贡献

我们非常欢迎社区成员踊跃贡献代码、提出建议和报告问题！

### 贡献方式
- **代码贡献**：Fork 仓库，提交 Pull Request
- **问题反馈**：在 GitHub/Gitee 上提交 Issue
- **功能建议**：通过 Issue 提出
- **文档完善**：帮助改进文档和使用指南

### 贡献流程
1. Fork 项目仓库
2. 创建功能分支
3. 提交代码变更
4. 运行测试确保代码质量
5. 提交 Pull Request


## 🔒 网络安全说明

### 安全设计理念

本工具从安装开始，将自动设为**禁止访问外网**状态，最大程度保护您的数据安全。部分功能（如拉取代码、安装依赖等）需要访问外网时，您可以通过配置**白名单**来精确控制允许访问的地址。

### 为什么需要白名单？

- 默认禁止所有外网访问，确保数据不泄露
- 通过白名单机制，您可以精确控制工具能访问的地址
- 新建项目时自动将 Git 仓库地址加入白名单，方便快捷
- 如有安全顾虑，可手动删除白名单，删除后相关功能自动失效

### 默认白名单

工具默认包含以下白名单，确保基础功能可用：

| 类型 | 地址示例 | 用途 |
|------|----------|------|
| Maven 仓库 | `maven.aliyun.com`、`repo.maven.apache.org` | 自动下载 Java 依赖 |
| NPM 仓库 | `registry.npmjs.org`、`npm.taobao.org` | 自动下载 Node.js 依赖 |
| Git 仓库 | 您配置的所有 Git 地址 | 拉取代码 |

> **注意**：如果您将某个 Git 仓库地址从白名单删除，该项目将无法自动拉取代码，可能导致自动部署失败。

### 一键关闭/开通外网访问

在系统设置页面的「网络安全」模块中，您可以：

- **一键关闭外网访问**：阻止本工具所有外网通信（除白名单外）
- **一键开通外网访问**：允许本工具访问所有地址
- **管理白名单**：自定义允许访问的地址列表

> ⚠️ **注意**：一键开关功能需要管理员/root 权限，部分系统可能需要您确认授权。

### 手动配置（高级用户）

如需更精细的控制，您可以手动配置系统防火墙：

#### Windows 系统

使用 Windows 防火墙：
1. 打开「控制面板」→「Windows Defender 防火墙」→「高级设置」
2. 创建入站/出站规则，程序选择 `java.exe`
3. 选择「阻止连接」

#### Linux 系统

```bash
# 使用 iptables（需要 root）
sudo iptables -A OUTPUT -m owner --cmd-owner java -j DROP
```

#### macOS 系统

推荐使用 Murus、Little Snitch 等图形化防火墙工具进行配置。

### 如何验证配置生效？

1. 查看网络安全页面的防火墙状态
2. 尝试部署项目，观察是否能正常拉取代码
3. 检查系统防火墙规则确认已生效

### 更高的安全建议

#### 自主编译安装（推荐）

若您仍有安全顾虑，可以：

1. **下载源码**：从 GitHub/Gitee 获取完整源代码
2. **手动编译**：使用 Maven 编译生成 JAR 包
3. **自行部署**：在您信任的环境中运行

```bash
# 克隆源码
git clone https://gitee.com/cnpyi/easy-deploy.git

# 编译打包
cd easy-deploy
mvn clean package -DskipTests

# 运行
java -jar target/easydeploy.jar
```

项目完全开源，内部逻辑透明，完全自主可控。您可以：
- 审查所有源代码
- 自定义安全策略
- 移除不需要的功能

#### 网络隔离建议

为了安全考虑，**建议您不要将本工具的端口或访问地址面向公网开放**。

- 本工具设计为**内网/本地使用**
- 如需远程访问，建议使用 VPN 或内网穿透
- 确保防火墙仅允许受信任的 IP 段访问


## 开源协议

### MIT License

MIT 许可证是一种 permissive 许可证，允许您：

- ✅ 自由使用、修改、复制和分发软件
- ✅ 免费用于商业目的
- ✅ 修改软件并闭源分发
- ✅ 建议但不强制将修改贡献回上游

只需在软件的所有副本或重要部分中包含原始版权声明和许可证声明即可。

---

<p align="center">
  Made with ❤️ by <a href="https://pyigroup.cn">PYI 鹏奕科技开源团队</a>
</p>

<p align="center">
  ⭐ Star 本仓库，支持我们持续更新！
</p>