# Woodpecker CI 流水线说明

## 概述

[Woodpecker CI](https://woodpecker-ci.org/) 是一款轻量级、开源的持续集成/持续部署(CI/CD)工具，本项目使用它来实现代码的自动化构建、Docker 镜像打包及远程部署。

项目中有 **两套流水线配置方案**，二者互斥，可根据实际需求选用其中一套：

| 方案 | 配置文件 | 适用场景 |
|------|---------|---------|
| 单文件流水线 | `.woodpecker.yaml`（项目根目录） | 单节点部署，快速上手 |
| 多文件流水线 | `.woodpecker/` 目录 | 多节点集群部署，流水线拆分与复用 |

---

## 一、外部依赖

流水线正常运行需要以下前置条件：

| 依赖项 | 用途 | 说明 |
|--------|------|------|
| Woodpecker Server + Agent | CI 引擎 | 需要在服务器上部署 Woodpecker 服务端和至少一个 Agent |
| Docker | 镜像构建与运行 | Agent 所在机器需安装 Docker，用于构建镜像和运行容器 |
| 阿里云 ACR（容器镜像仓库） | 存储 Docker 镜像 | `registry.cn-zhangjiakou.aliyuncs.com/abhors/demo` |
| Maven 缓存卷 | 加速构建 | `/tmp/maven-cache:/root/.m2`，避免每次下载依赖 |
| SSH 免密/密码登录 | 远程部署 | 目标服务器需开放 22 端口并具备 Docker 环境 |
| Woodpecker Secrets | 凭据管理 | 在 Woodpecker 面板中配置密钥 |

### 必需的 Secrets

| Secret 名称 | 说明         |
|-------------|------------|
| `aliyun_acr_username` | 阿里云容器镜像仓库用户名 |
| `aliyun_acr_password` | 阿里云容器镜像仓库密码 |
| `nexus_docker_username` | nexus容器镜像仓库用户名 |
| `nexus_docker_password` | nexus容器镜像仓库密码 |
| `ssh_host` | 服务器 IP 地址  |
| `ssh_user` | 服务器 SSH 用户名 |
| `ssh_password` | 服务器 SSH 密码 |


---

## 二、`.woodpecker.yaml` — 单文件流水线（根目录）

### 作用

定义一条完整的 CI/CD 流水线，包含 **构建 → 镜像打包推送 → 远程部署** 三个阶段，每次向 `master` 分支推送代码时自动触发。

### 执行流程

```
Git Push (master 分支)
       │
       ▼
┌──────────────────────────────┐
│  Step 1: Java 构建            │
│  Maven 3.9.6 + JDK 17        │
│  mvn clean package -DskipTests│
│  挂载 /tmp/maven-cache 缓存   │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│  Step 2: 镜像构建与推送       │
│  使用 plugin-docker-buildx   │
│  构建 Docker 镜像并推送至     │
│  阿里云 ACR 镜像仓库          │
│  触发条件: push 事件          │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│  Step 3: 远程终端部署         │
│  SSH 连接到服务器             │
│  docker login → stop → rm    │
│  → pull → run                │
│  触发条件: push 事件          │
└──────────────────────────────┘
```

### 触发条件

| Step | 事件 | 分支 |
|------|------|------|
| Java 构建 | `push`, `pull_request` | `master` |
| 镜像构建与推送 | `push` | `master` |
| 远程终端部署 | `push` | `master` |

> **注意**：`pull_request` 事件仅触发构建步骤，不会执行镜像推送和部署，确保 PR 的安全性。

---

## 三、`.woodpecker/` 目录 — 多文件流水线

### 作用

将流水线拆分为 **构建** 和 **部署** 两个独立文件，借助 Woodpecker 的 `depends_on` 机制实现流水线编排。部署阶段使用 `matrix` 矩阵策略，支持同时向多台服务器（136 和 114）批量部署。

### 文件结构

```
.woodpecker/
├── build.yaml    # 构建流水线：Maven 编译 + Docker 镜像构建推送
└── deploy.yaml   # 部署流水线：SSH 连接集群节点，拉取镜像并启动容器
```

### 3.1 `build.yaml` — 构建流水线

包含两个步骤，负责代码编译和镜像制作：

```
┌──────────────────────────────┐
│  Step 1: Java 构建            │
│  Maven 3.9.6 + JDK 17        │
│  mvn clean package -DskipTests│
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│  Step 2: 镜像构建与推送       │
│  构建 Docker 镜像 → 推送 ACR  │
│  触发: push/pull_request/manual│
└──────────────────────────────┘
```

#### 依赖关系

`deploy.yaml` 依赖 `build.yaml`：通过 `depends_on: [build]` 声明，确保只有构建成功后才会触发部署。

### 3.2 `deploy.yaml` — 集群部署流水线

使用 **Matrix 矩阵策略**，对两台服务器并行执行部署：

```
          build.yaml 构建成功
                 │
                 ▼
    ┌─────────────────────────┐
    │  Matrix 矩阵并行执行     │
    ├─────────────────────────┤
    │  节点A:    服务器        │
    │  SSH → login → pull     │
    │  → stop → rm → run      │
    ├─────────────────────────┤
    │  节点B:     服务器       │
    │  SSH → login → pull     │
    │  → stop → rm → run      │
    └─────────────────────────┘
```

每个节点的 Secret 通过 `${SECRET_NODE_IP}` 等变量动态注入，实现配置复用。

### 3.3 执行流程总览

```
┌──────────────────────────────────────────────────────┐
│  触发条件: push / pull_request / manual → master 分支  │
└──────────────────────┬───────────────────────────────┘
                       │
                       ▼
              ┌────────────────┐
              │  build.yaml    │
              │  Step 1: 构建  │
              │  Step 2: 推送  │
              └───────┬────────┘
                      │ depends_on
                      ▼
              ┌────────────────┐
              │  deploy.yaml   │
              │  Matrix 并行:  │
              │    A ← → B     │
              └────────────────┘
```

### 3.4 与单文件方案的区别

| 特性 | `.woodpecker.yaml` | `.woodpecker1/` |
|------|-------------------|-----------------|
| 文件数量 | 1 个 | 2 个（build + deploy） |
| 部署节点 | 单节点 | 多节点集群 |
| 流水线复用 | 否 | 是（build 可被多条流水线依赖） |
| 并行部署 | 否 | 是（Matrix 并行） |
| 手动触发 | 不支持 | 支持（`manual` 事件） |

---

## 四、关键镜像说明

流水线中使用了以下 Docker 镜像，均通过国内镜像加速拉取：

| 镜像 | 用途                            |
|------|-------------------------------|
| `library/maven:3.9.6-eclipse-temurin-17` | Maven 编译环境（JDK 17）            |
| `woodpeckerci/plugin-docker-buildx:latest` | Docker Buildx 构建插件 (会缓存并一直运行) |
| `appleboy/drone-ssh` | SSH 远程执行插件                    |
| `abhors/demo:latest` | 最终产出的应用镜像                     |
| `ibm-semeru-runtimes:open-17-jre` | 运行时基础镜像（Dockerfile 中定义）       |

---

## 五、常见问题

**Q: 为什么有两套流水线配置？**

A: `.woodpecker.yaml` 是早期单节点方案，`.woodpecker/` 是升级后的多文件集群方案。两者不会同时生效（Woodpecker 会优先读取根目录的 `.woodpecker/`，若不存在则扫描子目录中的流水线文件）。

**Q: Maven 缓存卷的作用？**

A: 将宿主机 `/tmp/maven-cache` 挂载到容器的 `/root/.m2`，确保每次构建复用已下载的 Maven 依赖，大幅缩短构建时间。

**Q: 如何添加新的集群节点？**

A: 在 `deploy.yaml` 的 `matrix.include` 中添加新的节点配置，并在 Woodpecker Secrets 中创建对应的 `{name}_ssh_host`、`{name}_ssh_user`、`{name}_ssh_password` 密钥即可。


![Build Status](https://woodpecker.lovestory.cyou/api/badges/1/status.svg)

![Build Status](https://woodpecker.lovestory.cyou/api/badges/1/status.svg?branch=master)

[![Build Status](https://woodpecker.lovestory.cyou/api/badges/1/status.svg)](https://woodpecker.lovestory.cyou/repos/1)