企业官网建设流程全解析

• CI/CD
• DevOps

本文是 Woodpecker CI/CD 引擎开发入门指南，面向想要参与 Woodpecker 开发或深入理解其架构的开发者。文章将带你完整走通本地开发环境的搭建流程：安装 Go、make、Node.js 与 pnpm 等基础工具，通过.env文件配置本地 Server、Agent 与 Forge 的 OAuth 连接，并掌握 VS Code 断点调试、make测试与代码检查、以及从终端直接运行 Server/Agent/CLI 三大组件的全部方法。读完本文，你将具备一套可复现的 Woodpecker 本地开发工作流，并理解其配置项与源码实现之间的对应关系。

图：在 VS Code 中调试 Woodpecker 应用，可在源码中设置断点进行逐步调试

环境准备：安装基础工具链

Woodpecker 是一个 Go 编写、前端使用 Vue 3 的 CI/CD 引擎，本地开发需要以下工具：

安装 Go

Go 是编译和运行 Woodpecker 的核心语言，按照官方安装指南安装对应平台的 Golang 即可。安装完成后建议确认版本与go.mod中要求的 Go 版本匹配（仓库当前使用go.woodpecker-ci.org/woodpecker/v3作为模块路径）。

安装 make

GNU Make 用于从源码生成可执行文件，Woodpecker 仓库的 Makefile 定义了测试、构建、发布等一系列目标，日常开发几乎离不开它。各平台安装方式：

• Ubuntu：apt install make
• Windows：参考社区指引安装（Makefile 中通过TARGETOS/TARGETARCH及BIN_SUFFIX处理了 Windows 下的.exe后缀，见 Makefile）
• macOS：brew install make

安装 Node.js 与 pnpm

如果你要构建 Woodpecker 的 UI（位于 web/）或文档（位于 docs/），需要安装 Node.js；UI 和文档的依赖（node_modules）统一使用pnpm管理。这也是前端开发章节（docs/docs/92-development/03-ui.md）的前置条件。

安装 pre-commit（可选）

Woodpecker 使用pre-commit在本地开发时自动修复代码格式问题。可选安装，按 pre-commit 官方文档配置后在提交前自动执行。

创建.env开发配置：Server 与 Agent 的环境变量

与生产环境设置环境变量的方式类似，你可以在 Woodpecker 项目根目录创建.env文件，加入任何需要的配置。这个机制有源码级支撑：server、agent、cli三个程序的main入口都会在启动时调用dot_env.Load()（见 cmd/server/main.go、cmd/agent/main.go、cmd/cli/main.go），其实现位于 shared/dot_env/dot_env.go：若项目根目录存在.env文件，就用godotenv将其加载为进程环境变量，之后 urfave/cli 框架通过cli.EnvVars(...)读取。

一个常见的调试配置如下：

WOODPECKER_OPEN=true WOODPECKER_ADMIN=your-username WOODPECKER_HOST=http://localhost:8000 # github (sample for a forge config - see /docs/administration/forge/overview for other forges) WOODPECKER_GITHUB=true WOODPECKER_GITHUB_CLIENT=<redacted> WOODPECKER_GITHUB_SECRET=<redacted> # agent WOODPECKER_SERVER=localhost:9000 WOODPECKER_AGENT_SECRET=a-long-and-secure-password-used-for-the-local-development-system WOODPECKER_MAX_WORKFLOWS=1 # enable if you want to develop the UI # WOODPECKER_DEV_WWW_PROXY=http://localhost:8010 # if you want to test webhooks with an online forge like GitHub this address needs to be set and accessible from public server WOODPECKER_EXPERT_WEBHOOK_HOST=http://your-address.com # disable health-checks while debugging (normally not needed while developing) WOODPECKER_HEALTHCHECK=false # WOODPECKER_LOG_LEVEL=debug # WOODPECKER_LOG_LEVEL=trace

下面对照源码逐一说明每个配置项的作用与取值建议：

配置 Forge OAuth：让本地实例能对接代码托管平台

要在本地跑通完整的 CI 流程，还需要为你的 Forge（代码托管平台）创建一个 OAuth App。请参考 Forges 总览文档 中对应的 Forge 章节（GitHub、Gitea、Forgejo、GitLab、Bitbucket、Bitbucket DataCenter 均有各自的配置文档），把生成的 Client ID 与 Secret 填入.env的WOODPECKER_GITHUB_CLIENT/WOODPECKER_GITHUB_SECRET（或其他 Forge 的对应变量）中。

需要注意的是：目前通过环境变量只能配置一个Forge，启用多个 Forge 驱动并不会创建多个 Forge，其余 Forge 需要由管理员在 UI 的Settings -> Forges中添加（该特性仍处于实验阶段，官方文档明确提示不要在公开或不可信环境使用）。

使用 VS Code 调试 Woodpecker

调试 Woodpecker 应用有多种方式，目前社区推荐使用 VS Code 或 VS Codium（VS Code 的开源二进制发行版），因为多数维护者都在使用，且仓库已内置了所需的调试配置。

一键启动完整开发环境

在 VS Code 中选择"Woodpecker CI"调试配置，它会以调试模式同时启动 UI、Server 和 Agent 三个服务，随后访问http://localhost:8000即可打开界面。首次使用 Go 进行 VS Code 开发可以参考官方的 Go in VS Code 入门视频教程。

单点调试 Server 或 Agent

源码仓库中已包含 Server 与 Agent 的 launch 配置。点击 VS Code 导航栏的调试图标（快捷键ctrl-shift-d），在页面顶部的启动任务列表中选择agent或server，点击播放按钮即可启动调试；在源码文件中设置断点，程序就会在指定位置暂停，方便逐行检查状态。

图：在 VS Code 中直接运行或调试测试文件的内联命令

测试与代码检查：make 目标与单测命令

Woodpecker 在 Makefile 中为不同组件提供了独立的测试与 lint 目标：

make test-server

make test-agent

make test-cli

make test-server-datastore

make lint

make lint-frontend

make test-frontend

对照源码可以看到这些目标的实际行为：

• test-server运行go test -race -cover -timeout 60s覆盖cmd/server与server/...下除store之外的所有包（Makefile）；
• test-agent覆盖cmd/agent与agent/...（Makefile）；
• test-cli覆盖cmd/cli与cli/...（Makefile）；
• test-server-datastore会先以串行方式（-p 1）运行迁移测试TestMigrate（因为迁移测试会重置共享数据库），再跳过迁移测试运行其余 datastore 测试（Makefile）；
• lint使用 golangci-lint（未安装时会自动用go run拉取固定版本v2.12.2，见 Makefile）；
• 前端相关目标（lint-frontend、test-frontend）会先执行pnpm install --frozen-lockfile，再在web/目录下运行 pnpm 的 lint/format/typecheck/test 脚本（Makefile、Makefile）。

测试单个 Go 文件或包

如果只想测试某个具体的 Go 文件，可以直接使用go test指定包路径：

go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v3/<path-to-the-package-or-file-to-test>

也可以在 VS Code 中打开测试文件，点击测试函数上方出现的内联命令直接运行或调试该测试（见上图）。

从终端直接运行三大组件

如果不依赖编辑器调试，也可以从项目根目录直接运行各组件。它们以与调试模式等价的方式启动，只是无法在编辑器中打断点：

go run ./cmd/server

go run ./cmd/agent

go run ./cmd/cli [command]

三个程序的main函数都会先执行dot_env.Load()加载项目根目录的.env，因此前述配置在终端运行时同样生效。从源码结构看，cmd/server、cmd/agent、cmd/cli分别对应 Woodpecker 的三个二进制产物，构建产物由 Makefile 的build-server/build-agent/build-cli目标输出到dist/目录（Makefile），与本地go run是同一套代码入口。

常见问题与调试建议

• UI 热更新：开发 UI 时不必反复pnpm build并重启 Server。在web/目录运行pnpm start启动带热重载的 UI dev server，同时在.env中启用WOODPECKER_DEV_WWW_PROXY=http://localhost:8010，Server 会把非 API 请求代理到该 dev server（原理详见 docs/docs/92-development/03-ui.md）。
• Webhook 无法回调：使用公网 Forge（如 GitHub）测试 Webhook 时，WOODPECKER_EXPERT_WEBHOOK_HOST必须设置为公网可达的地址，本地localhost无法被 Forge 服务器访问。
• 日志定位问题：调试阶段可临时取消注释WOODPECKER_LOG_LEVEL=debug或trace，获取更详细的运行日志；对应 CLI 也存在--log-level与WOODPECKER_LOG_LEVEL的映射（见 cmd/cli/docs.go）。
• Agent 连接问题：确认 Agent 的WOODPECKER_SERVER（默认localhost:9000）与 Server 的 gRPC 监听地址一致，且WOODPECKER_AGENT_SECRET两边相同；需要 TLS 时通过WOODPECKER_GRPC_SECURE开启（cmd/agent/core/flags.go）。

至此，一套完整的 Woodpecker 本地开发环境已经就绪：你可以启动 Server + Agent 跑通端到端流水线，也可以在 VS Code 中打断点调试任意组件，还可以通过make目标对改动进行测试与代码检查，为向 Woodpecker 贡献代码做好了全部准备。

• CI/CD
• DevOps