Woodpecker 的安装与 Windows agent 的部署

Woodpecker 是一个简单又强大的 CI/CD 引擎，支持 Linux、macOS 和 Windows 系统。

之前我尝试使用 Jenkins 自建管道，但是，完全看不懂，不管是 Jenkins 的后台还是文档，一头雾水。我虽然很早就想部署自己的管道，但苦于不会操作，直到我遇见了 Woodpecker。

管道本身是比较简单的概念：

利用 Docker 镜像保证构建、测试的环境一致
通过 git 获取源码
然后是一串 shell 指令，进行构建、测试和部署的执行，利用返回码判断是否失败

另外，通过声明式配置，让项目完全可复现、可审计，避免了经验丢失和恶意引入外部依赖，对于正规企业项目必不可少。

Woodpecker 让这一切就跟管道本身的含义一致：安装 → 关联 Gitea/GitHub → 在项目里添加 YAML 配置文件。上手容易，学习曲线平缓。另外，Woodpecker 本身也很稳定。

GitHub： woodpecker-ci/woodpecker: Woodpecker is a simple, yet powerful CI/CD engine with great extensibility.

指标	描述
适用系统	服务端适用于 Debian 系发行版，包括 Ubuntu，其他发行版稍改命令一般也可；agent 支持 Linux、macOS 和 Windows。
服务端 + Linux agent 时间	25 分钟

I might have made some mistakes, please let me know if I’ve gotten anything wrong!

前置准备

Woodpecker 需要关联 GitHub 这类代码托管平台，这样才能在推送代码时，自动执行流水线。下面以 Gitea 为例，其他平台可以查看官方文档。

在 Gitea，进入用户的【设置】-【应用】，然后【创建 OAuth2 应用程序】，拿到 Client ID 和 Client Secret。

也可参考文档 https://woodpecker-ci.org/docs/administration/configuration/forges/gitea 。

安装

文档： https://woodpecker-ci.org/docs/administration/installation/docker-compose

创建工作目录

myserve="woodpecker"
mkdir -p ~/myserve/$myserve && cd ~/myserve/$myserve && mkdir -p ./{server/data,agent/config}

vim ~/myserve/woodpecker/docker-compose.yml

需要修改 woodpecker-server 的 environment 中的很多值：

WOODPECKER_HOST 该 Woodpecker 的网址，不能带最后的斜线，如 https://woodpecker.your.domain
WOODPECKER_ADMIN 对应 Gitea 实例上允许授权的用户名
WOODPECKER_GITEA_URL 填写 Gitea 实例 URL，如 https://git.your.domain
WOODPECKER_GITEA_CLIENT 是 Gitea OAuth2 应用的 Client ID
WOODPECKER_GITEA_SECRET 是 Gitea OAuth2 应用的 Client Secret
WOODPECKER_AGENT_SECRET 随机值机密，使用 openssl rand -base64 32 生成

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3.14
    container_name: woodpecker-server
    restart: unless-stopped
    ports:
      - 127.0.0.1:8000:8000  # 网页
      - 9000:9000  # agent 连接服务端的端口
    volumes:
      - ./server/data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=false # disable registration
      - WOODPECKER_HOST=https://woodpecker.vfly2.com
      - WOODPECKER_ADMIN=vfly2
      - WOODPECKER_AGENT_SECRET=y2NXx6AbalTE8lEQ9vz6qAMJ3Lsj/PoPQvtyvwZcCmU=
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=https://git.vfly2.com/
      - WOODPECKER_GITEA_SKIP_VERIFY=false
      - WOODPECKER_GITEA_CLIENT=uuidxxxxx-1684-46x5-1626-233977d1a97f
      - WOODPECKER_GITEA_SECRET=gto_bdvlkasjdvnlKKLVNlalscjdsvkalsjdksvlnvfjdk

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3.14
    container_name: woodpecker-agent
    restart: always
    command: agent
    depends_on:
      - woodpecker-server
    volumes:
      - ./agent/config:/etc/woodpecker
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=y2NXx6AbalTE8lEQ9vz6qAMJ3Lsj/PoPQvtyvwZcCmU= # 需要和上面的一样
      - WOODPECKER_MAX_WORKFLOWS=2 # 同时运行的工作者数量，根据实际情况修改

拉取镜像

docker compose pull

启动

docker compose up -d

下线

docker compose down

反代

获取证书：使用 acme.sh 申请和自动更新证书的完整指南 – 技焉洲 [[02acme.sh]]

在 root 下获取证书

sudo -i

记得修改域名

acme.sh --issue -d woodpecker.vfly2.com --webroot /var/www/html

acme.sh --install-cert -d woodpecker.vfly2.com \
--key-file       /etc/ssl/private/woodpecker.vfly2.com.key \
--fullchain-file /etc/ssl/certs/woodpecker.vfly2.com.cer \
--reloadcmd "systemctl reload nginx"

添加 Nginx 配置文件

sudo vim /etc/nginx/sites-available/woodpecker

server {
    listen 80;
    listen [::]:80;
    server_name woodpecker.vfly2.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$server_name$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name woodpecker.vfly2.com;

    ssl_certificate /etc/ssl/certs/woodpecker.vfly2.com.cer;
    ssl_certificate_key /etc/ssl/private/woodpecker.vfly2.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ecdh_curve X25519:P-256:P-384;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-CHACHA20-POLY1305:ECDHE+AES128:RSA+AES128:ECDHE+AES256:RSA+AES256';
    ssl_prefer_server_ciphers off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    access_log /var/log/nginx/woodpecker.access.log;
    error_log /var/log/nginx/woodpecker.error.log;

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_redirect off;
        proxy_buffering off;
        chunked_transfer_encoding off;
    }
}

sudo ln -s /etc/nginx/sites-available/woodpecker /etc/nginx/sites-enabled/woodpecker

检查配置以及重启生效

sudo nginx -t && sudo systemctl reload nginx

更新

先更新 docker-compose.yml 文件里的版本号。

拉取新镜像

cd ~/myserve/woodpecker/ && docker compose pull

下线、重启

docker compose down && docker compose up -d

清理旧镜像

docker image prune

Windows agent

我需要在 Windows 上编译 flutter 应用，因此需要在 Windows 系统上部署 Woodpecker agent。

下面是我花了一整天的时间，探索出的方案，目前仅有一个问题无法解决：git 校验经常失败，4 次里会成功 1 次，如果有人知道怎么解决，还请告知。

前置准备

在 Windows 上安装 git
在 Woodpecker 网页上注册一个 agent token，参考 https://woodpecker-ci.org/docs/administration/configuration/agent#using-agent-token
建议安装 curl，下载网址 https://curl.se/windows/ ，下载后就是一个可执行文件，将之放到任意文件夹，然后将其所在目录添加到环境变量里
建议安装 Woodpecker 的插件 https://woodpecker-ci.org/plugins/git-clone ，clone 仓库需要它，也是一个单纯的可执行文件，下载后，推荐放到 C:\woodpecker_plugin ，然后把这个路径添加到环境变量里

最后，为了减少 git clone 时因权限不足而失败的概率（感觉没什么用）

git config --global credential.helper manager

安装

创建 C:\tmp 作为工作目录。因为 Windows 对路径名称有长度限制，而 agent 默认的工作目录路径很长，对于 flutter 项目，很容易触发长度限制导致编译失败
在 https://github.com/woodpecker-ci/woodpecker/releases 里下载对应的 agent，需要和服务端的版本号一样

推荐开启 Windows 长路径支持。通过 win + R 打开”运行“，然后输入 gpedit.msc 确定，按路径寻找：计算机配置 → 管理模板 → 系统 → 文件系统 → 启用 Win32 长路径，右键编辑，设置为：已启用。

运行

务必在 PowerShell 里运行

先配置环境变量，需要填入 WOODPECKER_SERVER 和 WOODPECKER_AGENT_SECRET。

$env:WOODPECKER_SERVER="1.2.3.4:9000"
$env:WOODPECKER_AGENT_SECRET="LK34BX5XDXNHADFBFGFAM5ENGM44FBSZBDNGFZSVDCDWOGA===="
$env:WOODPECKER_MAX_WORKFLOWS="1"
$env:WOODPECKER_BACKEND="local"
$env:WOODPECKER_PLATFORM="windows/amd64"
$env:WOODPECKER_BACKEND_LOCAL_TEMP_DIR="C:\tmp"

由于 Windows 本身不支持 docker，这里是在本机上执行的，为了避免多个工作者干扰，最好把 WOODPECKER_MAX_WORKFLOWS 设置为 1

运行

.\woodpecker-agent.exe

测试是否能正常运行

可以在一个实验的仓库，使用下面的配置进行测试。如果正常运行，会打开 C:\Users\ 文件夹。

when:
  - event: push
    branch: main

labels:
  platform: windows/amd64
  backend: local

steps:
  - name: test-exprorer
    image: powershell
    commands:
      - explorer C:\Users\

到这里就结束了，需要注意的是，commands 里必须用 powershell 的命令。

Windows Service

但是，我想实现开机自启、失败自动重启，有办法吗？

使用 Windows Service 。查看以 Windows 服务运行程序并开机自启 – 技焉洲了解步骤，下面是针对 woodpecker 提供的具体命令。

确保原程序在命令行下能正常启动。
到 https://github.com/mtkennerly/shawl/releases 下载压缩包，解压后有一个 shawl。
以管理员权限打开 powershell，使用 shawl 添加服务，在原命令前加点内容就行，以及使用绝对路径：

.\shawl.exe add --name woodpecker_agent `
  --env WOODPECKER_SERVER="1.2.3.4:9000" `
  --env WOODPECKER_AGENT_SECRET="LK34BX5XDXNHADFBFGFAM5ENGM44FBSZBDNGFZSVDCDWOGA====" `
  --env WOODPECKER_MAX_WORKFLOWS="1" `
  --env WOODPECKER_BACKEND="local" `
  --env WOODPECKER_PLATFORM="windows/amd64" `
  --env WOODPECKER_BACKEND_LOCAL_TEMP_DIR="C:\tmp" `
  -- C:/Users/Administrator/Downloads/woodpecker-agent/woodpecker-agent.exe

打开命令行，注意不是 powershell，sc 命令只能在命令行里运行才能看到结果，不明白原因
查看服务是否添加成功： sc qc woodpecker_agent
指定运行服务的用户： sc config woodpecker_agent obj=".\Administrator" password="456"。（必做，因为默认的运行用户是 local system，这和我们直接在 PowerShell 启动的用户不一样，可能会有奇奇怪怪的错误）
先试一下启动服务： sc start woodpecker_agent
设置开机自启： sc config woodpecker_agent start=auto

参考资料（省略了官方文档）：

原文链接： https://yanh.tech/2026/05/woodpecker-installation-and-usage/

版权声明：本博客所有文章除特別声明外，均为 AhFei 原创，采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源技焉洲 (yanh.tech) 。

保持更新 ٩(•̤̀ᵕ•̤́๑)ᵒᵏᵎᵎᵎᵎ 清晰恒益的实用技能，欢迎使用 RSS 订阅，如果能留言互动就更好了。

可在 Telegram 群组 https://t.me/vfly2 交流依文章步骤遇到的问题。

前置准备

安装

反代

更新

Windows agent

前置准备

安装

运行

测试是否能正常运行

Windows Service

评论

发送评论编辑评论

前置准备

安装

反代

更新

Windows agent

前置准备

安装

运行

测试是否能正常运行

Windows Service

评论

发送评论 编辑评论

推荐文章

发送评论编辑评论