我需要在 Windows 上编译 flutter 应用，因此需要在 Windows 系统上部署 Woodpecker agent 。
下面是我花了一整天的时间，探索出的方案，可以完美运行。
前置准备
- 在 Windows 上安装 git
- 把这个路径加入环境变量里系统的 PATH
C:\Program Files\Git\usr\bin，这里面提供了 cat 等工具 - 在 Woodpecker 网页上注册一个 agent token ，参考 https://woodpecker-ci.org/docs/administration/configuration/agent#using-agent-token
- 建议安装 curl ，下载网址 https://curl.se/windows/ ，下载后就是一个可执行文件，将之放到任意文件夹，然后将其所在目录添加到环境变量里
- 建议安装 Woodpecker 的 git 插件 https://woodpecker-ci.org/plugins/git-clone ，clone 仓库需要它，也是一个单纯的可执行文件，下载后，推荐放到 C:\woodpecker_plugin ，然后把这个路径添加到环境变量里
安装
- 创建 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 的命令。
使用 ssh 克隆仓库
我猜测 git plugin 是通过 Git Credential Manager 进行校验，这样经常失败 remote: Failed to authenticate user，更可靠的方案是直接用用户名和密码登录，但是这个 plugin 不支持，另外这样也不安全。
要使用 ssh 校验，同样稳定，不过步骤稍微繁琐。
首先，需要在 Gitea 添加公钥，流程可看 https://yanh.tech/2025/04/deployment-process-of-gitea/#ssh 。
然后，替换默认的 clone 步骤，如下：
clone:
git:
image: woodpeckerci/plugin-git
settings:
use-ssh: true
remote-ssh: ssh://[email protected]:2222/vfly2/plantodo.git
ssh-key: C:/Users/Administrator/.ssh/id_ed25519
这样之后，就不会再发生 Failed to authenticate user
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) 。
Select Language