Woodpecker CI 服务端配置完全指南

Woodpecker CI 服务端配置完全指南

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker

前言

Woodpecker CI 是一个轻量级、现代化的持续集成系统，采用 Go 语言开发。本文将详细介绍 Woodpecker 服务端的各项配置选项，帮助管理员正确部署和管理 CI 系统。

用户与权限配置

Woodpecker 采用独特的用户管理模式，不内置用户注册系统，而是通过集成代码托管平台（如 GitLab、Gitea 等）的 OAuth2 认证来管理用户。

注册模式配置

系统提供三种注册控制方式：

1. 完全关闭注册（默认模式）

   WOODPECKER_OPEN=false
   

   在此模式下，必须通过命令行工具 woodpecker-cli user 手动添加用户。

2. 开放注册但限制管理员

   WOODPECKER_OPEN=true
   WOODPECKER_ADMIN=john.smith,jane_doe
   

   指定特定用户为管理员。

3. 组织过滤注册

   WOODPECKER_OPEN=true
   WOODPECKER_ORGS=dolores,dog-patch
   

   只允许特定组织的成员注册。

管理员设置

无论采用何种注册模式，都应明确指定管理员：

WOODPECKER_ADMIN=admin1,admin2

仓库同步配置

Woodpecker 会同步用户有权限访问的所有仓库。可通过以下配置限制同步范围：

WOODPECKER_REPO_OWNERS=company_name,org_name

这通常设置为公司或组织的名称，避免同步个人仓库。

数据库配置

数据库选项

Woodpecker 支持三种数据库引擎：

1. SQLite（默认）

   WOODPECKER_DATABASE_DRIVER=sqlite3
   WOODPECKER_DATABASE_DATASOURCE=/var/lib/woodpecker/woodpecker.db
   

   适合小型部署，零配置即可使用。

2. MySQL/MariaDB

   WOODPECKER_DATABASE_DRIVER=mysql
   WOODPECKER_DATABASE_DATASOURCE=user:password@tcp(host:3306)/dbname?parseTime=true
   

   需要 MySQL 5.7+ 或 MariaDB 10.2+。

3. PostgreSQL

   WOODPECKER_DATABASE_DRIVER=postgres
   WOODPECKER_DATABASE_DATASOURCE=postgres://user:password@host:5432/dbname?sslmode=disable
   

   需要 PostgreSQL 11+。

数据库管理注意事项

• 需手动创建数据库（SQLite 除外）
• 不提供数据归档功能
• 自动处理数据库迁移
• 需自行设置备份策略

安全配置

TLS 加密

配置 HTTPS 访问：

WOODPECKER_SERVER_CERT=/path/to/cert.pem
WOODPECKER_SERVER_KEY=/path/to/key.pem

反向代理配置

Nginx 示例

server {
    listen 80;
    server_name ci.example.com;
    
    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
    }
}

Apache 示例

ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass / http://localhost:8000/
ProxyPassReverse / http://localhost:8000/

监控与指标

Woodpecker 提供 Prometheus 兼容的监控端点：

WOODPECKER_PROMETHEUS_AUTH_TOKEN=your_token

监控指标包括：

• 构建次数和时长
• 待处理/运行中的任务数
• 仓库和用户数量
• 工作节点数量

高级功能

外部配置 API

允许通过 HTTP API 动态修改流水线配置：

WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://config-service.example.com

请求使用 Ed25519 签名验证，公钥可从 /api/signature/public-key 获取。

界面定制

支持自定义 CSS 和 JavaScript：

WOODPECKER_CUSTOM_CSS_FILE=/path/to/custom.css
WOODPECKER_CUSTOM_JS_FILE=/path/to/custom.js

示例：添加顶部横幅

.banner-message {
  position: absolute;
  width: 280px;
  background: red;
  text-align: center;
}

总结

Woodpecker CI 提供了灵活的配置选项，从简单的单机部署到复杂的企业级配置都能满足。通过合理配置用户权限、数据库和安全选项，可以构建出稳定可靠的 CI/CD 环境。监控和定制化功能则让系统更加透明和符合企业需求。

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker