企业官网建设流程全解析

• CI/CD
• DevOps

Forgejo 是一款开源的轻量级 Git 代码托管服务，Woodpecker 内置了对它的原生驱动支持（built-in Forgejo driver），可以让你的 CI/CD 流水线直接对接自托管的 Forgejo 实例。本文以 Forgejo 官方配置文档 为核心骨架，结合 Woodpecker 源码深入讲解：如何通过环境变量启用 Forgejo 驱动、如何在同一主机上打通容器网络、如何注册用户级与系统级 OAuth 应用、以及全部 FORGEJO 配置项的含义与默认值。读完本文，你将能独立完成 Woodpecker Server 与 Forgejo 的完整对接，并理解驱动底层的工作原理与常见坑点。

快速启用：四个环境变量

Woodpecker 对 Forgejo 的支持是内置的，无需安装任何额外插件。在启动 Woodpecker Server 容器时，只需配置下面四个环境变量即可启用：

WOODPECKER_FORGEJO=true WOODPECKER_FORGEJO_URL=YOUR_FORGEJO_URL WOODPECKER_FORGEJO_CLIENT=YOUR_FORGEJO_CLIENT WOODPECKER_FORGEJO_SECRET=YOUR_FORGEJO_CLIENT_SECRET

• WOODPECKER_FORGEJO=true：启用 Forgejo 驱动。对应源码中的forgejoCLI 开关（见 cmd/server/flags.go），该开关的 Sources 绑定环境变量WOODPECKER_FORGEJO。
• WOODPECKER_FORGEJO_URL：你的 Forgejo 服务器地址。
• WOODPECKER_FORGEJO_CLIENT/WOODPECKER_FORGEJO_SECRET：在 Forgejo 中注册 OAuth 应用后得到的 Client ID 与 Client Secret。

从源码看，Forgejo 驱动与其他 forge（GitHub、GitLab、Gitea 等）共用一套通用的 oauth 配置解析链。在 cmd/server/flags.go 中，forge-url、forge-oauth-client、forge-oauth-secret、forge-skip-verify等 Flag 都同时接受多个 forge 的环境变量来源，其中就包括WOODPECKER_FORGEJO_*系列，因此你也可以直接使用通用的WOODPECKER_FORGE_URL/WOODPECKER_FORGE_CLIENT/WOODPECKER_FORGE_SECRET。

在服务端装配时，server/forge/setup/setup.go的Forge()函数会依据模型中的ForgeTypeForgejo分支调用setupForgejo()（见 setup.go）：它会解析forge.URL、去掉末尾多余的/，并依次把 OAuth Client ID、Client Secret、SkipVerify与 OAuth Host 传入forgejo.Opts（见 setup.go）。其中OAuth2URL（对应WOODPECKER_EXPERT_FORGE_OAUTH_HOST）用于指定面向用户的 OAuth 地址；若未设置，驱动会自动回退到URL本身（见 forgejo.go）。

如果WOODPECKER_FORGEJO_URL为空，setupForgejo会直接返回错误WOODPECKER_FORGEJO_URL must be set，对应测试见 setup_test.go。

Forgejo 与 Woodpecker 容器同主机部署的网络联通

如果你把 Forgejo 和 Woodpecker 都跑在同一台主机的容器里，必须保证 Agent 能访问到 Forgejo。Agent 在克隆代码时，使用的是 Forgejo 通过 API 上报的克隆 URL，因此网络不通会导致克隆失败。

官方推荐的两种做法：

1. 把 Woodpecker Agent 加入 Forgejo 所在的 Docker 网络（最稳妥）。
2. 让通信走docker0网关（通常为172.17.0.1）。

假设 Docker 网络名为forgejo，在 docker-compose 中给 agent 增加网络配置：

services: [...] woodpecker-agent: [...] environment: - [...] + - WOODPECKER_BACKEND_DOCKER_NETWORK=forgejo

WOODPECKER_BACKEND_DOCKER_NETWORK是 Agent 侧 Docker 后端（pipeline/backend/docker）使用的网络配置，让 Agent 启动的流水线容器与 Forgejo 处于同一网络，从而能解析并访问 Forgejo 容器，这是容器化 CI 场景下最常见的联通方式。

OAuth 应用注册

用户级 OAuth 应用（User OAuth Application）

在 Forgejo 中注册应用以获取 Client ID 与 Secret：

1. 打开https://forgejo.<host>/user/settings/（你的 Forgejo 实例的用户设置页），进入 OAuth 应用管理。
2. 创建新的 OAuth 应用，授权回调地址（authorization callback URL）必须与你的 http(s) 协议和主机名完全一致，路径固定为/authorize，即形如https://<host>/authorize。

回调路径/authorize不是随意约定的：驱动在构造 OAuth2 配置时，RedirectURL被硬编码为fmt.Sprintf("%s/authorize", server.Config.Server.OAuthHost)（见 forgejo.go），同时授权端点与令牌端点分别由%s/login/oauth/authorize和%s/login/oauth/access_token拼装（见 forgejo.go）。回调地址写错（例如混用 http/https、漏写主机名）是集成失败的最常见原因。

系统级 OAuth 应用（System-wide OAuth Application）

如果你同时是 Forgejo 和 Woodpecker 的管理员，可以优先考虑注册系统级（站点级）OAuth 应用，而不是用户级应用。系统级应用在 Forgejo 站点管理员层面统一管理，对所有用户可见。

创建步骤：

1. 打开站点管理设置：https://forgejo.<host>/admin/settings/applications
2. 在 "OAuth2 Applications" 区域新建一个 OAuth2 应用
3. 配置方式与用户级应用一致（回调地址等）
4. 将生成的 Client ID 与 Secret 填入 Woodpecker 配置

系统级应用特别适合以下场景：

• 共享 CI/CD 环境：多个用户都需要访问同一个 Woodpecker；
• 需要集中管控 OAuth 应用的组织：由管理员统一创建与吊销，避免依赖某个个人账号；
• 规避用户级应用配额：防止个人账号的应用数量配额影响 CI/CD 正常运行。

本地连接（Local Connections）

如果 Woodpecker CI Server 与 Forgejo 实例运行在同一台主机上，你可能还需要允许 Forgejo 的本地连接，否则webhook 会失败。在 Forgejo 配置文件（通常位于/etc/forgejo/conf/app.ini）中加入：

[webhook] ALLOWED_HOST_LIST=external,loopback

这里external允许外部主机，loopback允许回环地址——当 Woodpecker Server 通过本地地址接收 Forgejo 推送的 webhook 时，这一配置必不可少。

⚠️API 分页大小警告：请确保你的 Forgejo 配置允许以固定的每页 50 条记录请求 API。Forgejo 默认的最大页大小就是 50，但如果你把该值调到了 50 以下，Woodpecker 的部分功能将无法正常工作。

这个警告在源码中有直接体现：驱动内置常量defaultPageSize = 50，并在perPage()方法中通过GetGlobalAPISettings()读取 Forgejo 的MaxResponseItems作为实际分页大小（见 forgejo.go）；在Teams、Repos、Org等列表接口中，分页参数均以PageSize: c.perPage(ctx)的形式传入（见 forgejo.go）。一旦 Forgejo 服务端把最大页大小压到 50 以下，列表类功能（仓库列表、团队列表等）就会因请求页大小超过服务端上限而失效。

FORGEJO 配置项全集

以下为 Woodpecker Server 中与 Forgejo 相关的全部配置选项。大多数选项都有合理的默认值，适用于绝大多数安装场景；带_FILE后缀的选项用于从文件中读取敏感值，便于配合 Docker Secret 或 Kubernetes Secret 挂载。

FORGEJO

• 环境变量名：WOODPECKER_FORGEJO
• 默认值：false

启用 Forgejo 驱动。对应源码中forgejoCLI Flag，仅监听WOODPECKER_FORGEJO这一个环境变量来源（见 cmd/server/flags.go）。

FORGEJO_URL

• 环境变量名：WOODPECKER_FORGEJO_URL
• 默认值：https://next.forgejo.org

配置 Forgejo 服务器地址。该值经 URL 解析并去除末尾斜杠后，作为驱动内部url字段使用；同时被用于拼装授权端点与令牌端点（见 forgejo.go）。若未设置，setupForgejo会直接报错WOODPECKER_FORGEJO_URL must be set。

FORGEJO_CLIENT

• 环境变量名：WOODPECKER_FORGEJO_CLIENT
• 默认值：无

配置 Forgejo OAuth Client ID，用于授权访问。源码中它属于forge-oauth-client的值来源链之一：优先从WOODPECKER_FORGEJO_CLIENT_FILE指定文件读取，其次取各 forge 的_CLIENT环境变量，再回退到通用的WOODPECKER_FORGE_CLIENT（见 cmd/server/flags.go）。

FORGEJO_CLIENT_FILE

• 环境变量名：WOODPECKER_FORGEJO_CLIENT_FILE
• 默认值：无

从指定文件路径读取WOODPECKER_FORGEJO_CLIENT的值。适合用 Docker Secret / K8s Secret 挂载方式注入凭证，避免把敏感信息直接写进环境变量或 docker-compose 文件。

FORGEJO_SECRET

• 环境变量名：WOODPECKER_FORGEJO_SECRET
• 默认值：无

配置 Forgejo OAuth Client Secret，用于授权访问。解析优先级与 Client 类似：WOODPECKER_FORGEJO_SECRET_FILE文件优先，其次各 forge 的_SECRET，再回退到通用WOODPECKER_FORGE_SECRET（见 cmd/server/flags.go）。

FORGEJO_SECRET_FILE

• 环境变量名：WOODPECKER_FORGEJO_SECRET_FILE
• 默认值：无

从指定文件路径读取WOODPECKER_FORGEJO_SECRET的值，用途同FORGEJO_CLIENT_FILE。

FORGEJO_SKIP_VERIFY

• 环境变量名：WOODPECKER_FORGEJO_SKIP_VERIFY
• 默认值：false

配置是否跳过 SSL 证书校验。在驱动实现中，该值被传入 OAuth2 HTTP Client 的tls.Config{InsecureSkipVerify: ...}（见 forgejo.go）。仅当你的 Forgejo 使用自签名证书、且你清楚跳过校验的风险时才建议开启；生产环境应保持false。

源码级的驱动工作方式（补充说明）

除了文档明示的配置项外，从源码可以进一步确认 Forgejo 驱动的几个关键实现事实，帮助你理解整套对接链路：

• 驱动实体：server/forge/forgejo/forgejo.go中定义了Forgejo结构体（持有 url、oauth2URL、client id/secret、skipVerify、pageSize 等字段）与Opts配置结构体，New()负责实例化，Name()返回驱动标识"forgejo"（见 forgejo.go）。
• OAuth 登录流程：Login()先通过AuthCodeURL生成跳转地址，收到回调后Exchange换取访问令牌，再调用GetMyUserInfo拉取用户信息并组装model.User（登录名、邮箱、头像等）（见 forgejo.go）；Refresh()负责令牌续期。
• 令牌刷新：Refresh使用 oauth2 配置刷新 access token，刷新成功后同步更新用户记录，保证长周期流水线任务不会因令牌过期而中断（见 forgejo.go）。
• 克隆凭据（netrc）：测试用例Test_forgejo验证了 netrc 行为——使用用户令牌时生成包含登录名与访问令牌的凭据，使用机器账号（machine account）时则不带用户名密码（见 forgejo_test.go），这与文档中“Agent 按 Forgejo API 上报的 URL 克隆”的描述相互印证。

结语

对接 Woodpecker 与 Forgejo 的核心就三件事：配好四个环境变量、注册回调路径为/authorize的 OAuth 应用、保证 Agent 与 Forgejo 网络互通。在此基础上，善用_FILE系列环境变量注入凭证、保持 Forgejo API 最大页大小不低于 50、按需开启系统级 OAuth 应用，即可获得稳定、可扩展的自托管 CI/CD 体验。若在配置过程中遇到驱动行为疑问，可直接查阅 server/forge/forgejo/forgejo.go 及其测试文件 forgejo_test.go，所有配置项均有对应的解析与装配逻辑可循。

• CI/CD
• DevOps