# auto-deploy

**Repository Path**: loock/auto-deploy

## Basic Information

- **Project Name**: auto-deploy
- **Description**: 支持gitee 仓库通过 webhook 进行自动部署
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-10
- **Last Updated**: 2025-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Auto-Deploy Webhook Server

这是一个基于 Node.js 的 Gitee Webhook 服务器，用于自动部署代码更新。当配置的 Gitee 仓库收到推送事件时，服务器会自动拉取最新代码并运行部署脚本。

## 功能特点

- 支持 Gitee Webhook 签名验证
- 支持多个仓库配置
- 自动拉取指定分支的最新代码
- 自动执行自定义部署脚本
- 自动发送部署结果邮件通知
- 使用 PM2 进行进程管理和监控

## 配置说明

### 配置文件结构

本项目使用以下文件进行配置：

1. **config.yaml**: 主配置文件，包含服务器设置、邮箱配置和仓库信息
2. **ecosystem.config.js**: PM2 配置文件，用于进程管理

### 配置文件设置

项目提供了一个示例配置文件 `config.example.yaml`。首次使用时，需要复制该文件并重命名为 `config.yaml`，然后根据您的需求进行修改：

```bash
# 复制示例配置文件
cp config.example.yaml config.yaml

# 编辑配置文件
nano config.yaml  # 或使用其他编辑器
```

`config.yaml` 文件包含以下主要配置部分：

#### 服务器配置

```yaml
# 服务器配置
server:
  # 服务器监听端口
  port: 3000
  # Gitee webhook 密钥，用于验证请求的合法性
  # 在 Gitee 仓库的 WebHook 设置中配置相同的密钥
  secret: 'your-gitee-webhook-secret'
```

- `port`: Webhook 服务器监听端口
- `secret`: Gitee Webhook 密钥，需要与 Gitee 平台上配置的密钥一致

#### 邮箱配置

```yaml
# 邮箱配置
email:
  # 邮箱服务提供商，例如：'163'、'gmail'、'qq' 等
  service: '163'
  # 发送邮件的邮箱账号
  user: 'your-email@163.com'
  # 邮箱授权码，不是登录密码
  pass: 'your-email-authorization-code'
  # 接收通知的邮箱地址，可以是多个邮箱，用逗号分隔
  to: 'receiver@example.com'
```

- `service`: 邮件服务提供商，如"163"、"qq"、"gmail"等
- `user`: 发送邮件的邮箱账号
- `pass`: 邮箱密码或授权码（对于大多数邮箱服务，需要使用授权码而非登录密码）
- `to`: 接收通知的邮箱地址

### 邮箱通知配置

系统支持在自动部署完成后发送邮件通知，通知内容包括执行结果和执行过程中的日志。以下是不同邮箱服务的配置说明：

#### 163 邮箱配置

1. **开启 SMTP 服务**：

   - 登录您的 163 邮箱网页版
   - 点击右上角的"设置" -> "POP3/SMTP/IMAP"
   - 开启"POP3/SMTP 服务"
   - 系统会要求您设置一个授权码，这个授权码将用于第三方客户端登录

2. **获取授权码**：

   - 在开启 SMTP 服务的过程中，系统会让您设置一个授权码
   - 请记住这个授权码，它将用于配置自动部署系统
   - 注意：授权码不是您的邮箱登录密码

3. **配置 config.yaml**：
   ```yaml
   email:
     service: '163'
     user: 'your-username@163.com'
     pass: 'your-authorization-code'
     to: 'recipient@example.com'
   ```

#### QQ 邮箱配置

1. **开启 SMTP 服务**：

   - 登录您的 QQ 邮箱网页版
   - 点击"设置" -> "账户" -> "POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务"
   - 开启"POP3/SMTP 服务"
   - 获取授权码

2. **配置 config.yaml**：
   ```yaml
   email:
     service: 'qq'
     user: 'your-qq-number@qq.com'
     pass: 'your-authorization-code'
     to: 'recipient@example.com'
   ```

#### Gmail 配置

1. **开启安全性较低的应用访问权限**：

   - 登录您的 Google 账户
   - 进入"安全性" -> "安全性较低的应用的访问权限"
   - 开启"允许安全性较低的应用"

2. **配置 config.yaml**：
   ```yaml
   email:
     service: 'gmail'
     user: 'your-username@gmail.com'
     pass: 'your-gmail-password'
     to: 'recipient@example.com'
   ```

> **注意**：不同邮箱服务可能有不同的安全策略和配置要求。如果遇到发送失败的情况，请检查邮箱服务的安全设置和 SMTP 配置。

### 仓库配置

在 `config.yaml` 文件中配置需要自动部署的仓库：

```yaml
# 仓库配置
repositories:
  # 示例仓库1
  owner/repo1:
    # 要监听的分支名称
    branch: 'master'
    # 仓库在服务器上的本地路径
    repoPath: '/absolute/path/to/repo1'
    # 部署脚本的路径，当检测到推送时会执行此脚本
    scriptPath: '/absolute/path/to/repo1/deploy.sh'

  # 示例仓库2
  owner/repo2:
    branch: 'main'
    repoPath: '/absolute/path/to/repo2'
    scriptPath: '/absolute/path/to/repo2/scripts/deploy.sh'
```

每个仓库配置包含：

- 键名为 Gitee 仓库的 full_name 格式（`owner/repo-name`）
- `branch`: 触发部署的分支名
- `repoPath`: 本地仓库的绝对路径（例如：`/home/user/projects/repo`）
- `scriptPath`: 部署脚本的绝对路径（例如：`/home/user/projects/repo/deploy.sh`）

> **重要提示**：
>
> - `repoPath` 和 `scriptPath` 必须使用绝对路径，不能使用相对路径
> - `config.yaml` 文件应该被添加到 .gitignore 中，不要提交到版本控制系统

### Gitee Webhook 配置

1. 进入 Gitee 仓库设置 -> Webhooks
2. 添加 Webhook，URL 为 `http://your-server-ip:3000`（端口应与 config.yaml 中的 port 一致）
3. 设置密钥，与 config.yaml 中的 `server.secret` 配置一致
4. 选择触发事件（推荐选择"Push"事件）
5. 保存配置

## 使用方法

本项目提供了多种启动方式，可以通过 npm 脚本或直接使用 PM2 命令启动。

### 使用 npm 脚本

项目中已配置了多个 npm 脚本，可以通过以下命令使用：

```bash
# 直接使用Node.js启动服务
npm start

# 使用PM2启动服务
npm run start:pm2

# 停止PM2服务
npm run stop:pm2

# 重启PM2服务
npm run restart:pm2

# 查看PM2日志
npm run logs:pm2

# 查看PM2状态
npm run status:pm2
```

### 使用 PM2 直接管理

也可以直接使用 PM2 命令管理服务：

```bash
# 安装PM2
npm install -g pm2

# 启动服务
pm2 start ecosystem.config.js

# 停止服务
pm2 stop auto-deploy

# 重启服务
pm2 restart auto-deploy

# 查看日志
pm2 logs auto-deploy

# 监控服务
pm2 monit

# 设置开机自启
pm2 startup
pm2 save
```

### PM2 配置说明

PM2 配置文件`ecosystem.config.js`主要参数：

- `name`: 应用名称
- `script`: 启动脚本路径
- `instances`: 实例数量
- `max_memory_restart`: 内存限制
- `error_file`/`out_file`: 日志文件路径

完整配置可查看`ecosystem.config.js`文件。

## 邮件通知功能

系统在自动部署完成后会发送邮件通知，提供部署结果的实时反馈：

### 通知内容

- **仓库信息**：包括仓库名称和分支名称
- **部署状态**：清晰显示部署是成功还是失败（成功以绿色标记，失败以红色标记）
- **部署时间**：显示部署完成的具体时间
- **详细日志**：包含完整的部署过程日志，便于排查问题

### 通知示例

邮件通知的 HTML 格式如下：

```
自动部署通知
仓库: owner/repo-name
分支: master
状态: 成功
时间: 2025/5/10 23:30:45

部署日志:
[2025/5/10 23:30:40] 检测到 master 分支的更新
[2025/5/10 23:30:41] Git fetch 结果: Already up to date.
[2025/5/10 23:30:43] Git reset 结果: HEAD is now at a1b2c3d Latest commit
[2025/5/10 23:30:45] 部署脚本执行结果: Deployment completed successfully.
```

### 配置多个接收邮箱

如果需要多人接收部署通知，可以在配置中设置多个接收邮箱，用逗号分隔：

```yaml
email:
  # 其他配置...
  to: 'admin@example.com,developer@example.com,manager@example.com'
```

### 邮件发送失败处理

系统会记录邮件发送的结果，如果发送失败，错误信息会记录在日志中。即使邮件发送失败，也不会影响部署过程的正常执行。

## 注意事项

- 确保服务器对仓库路径和脚本路径有足够的权限
- 确保部署脚本(deploy.sh)有执行权限(`chmod +x deploy.sh`)
- PM2 日志默认保存在`logs`目录下，如需查看可使用`pm2 logs`命令
- 建议将服务器防火墙配置为只允许 Gitee IP 访问 webhook 端口