Woodpecker CI 服务器配置完全指南

Woodpecker CI 服务器配置完全指南

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

前言

Woodpecker CI 是一款轻量级、现代化的持续集成工具，其服务器配置灵活多样。本文将全面介绍 Woodpecker CI 服务器的各项配置要点，帮助管理员根据实际需求进行定制化部署。

用户与权限配置

Woodpecker CI 采用 OAuth2 协议与代码托管平台集成，自身不提供用户注册功能。系统提供多种用户管理策略：

1. 封闭式注册（默认）

   • 设置 WOODPECKER_OPEN=false
   • 通过 CLI 工具 woodpecker-cli user 手动管理用户

2. 开放式注册+管理员指定

   WOODPECKER_OPEN=true
   WOODPECKER_ADMIN=john.smith,jane_doe
   

3. 组织过滤注册

   WOODPECKER_OPEN=true
   WOODPECKER_ORGS=dolores,dog-patch
   

最佳实践建议：生产环境推荐采用封闭式注册，通过 CLI 精确控制用户权限。

仓库同步配置

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

WOODPECKER_REPO_OWNERS=my_company,my_company_oss_github_user

此配置特别适合企业环境，可确保只同步公司组织下的仓库。

数据库配置

数据库选型

1. SQLite（默认）

   • 零配置，数据存储在 /var/lib/woodpecker/
   • 容器部署时需挂载数据卷持久化

2. MySQL/MariaDB

   WOODPECKER_DATABASE_DRIVER=mysql
   WOODPECKER_DATABASE_DATASOURCE=root:password@tcp(1.2.3.4:3306)/woodpecker?parseTime=true
   

3. PostgreSQL

   WOODPECKER_DATABASE_DRIVER=postgres
   WOODPECKER_DATABASE_DATASOURCE=postgres://root:password@1.2.3.4:5432/postgres?sslmode=disable
   

重要注意事项：

• 需手动创建数据库
• 系统不提供数据归档功能
• 自动处理数据库迁移
• 需自行配置备份策略

安全配置

TLS 加密

WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key

容器部署时需：

1. 暴露 443 端口
2. 挂载证书文件
3. 配置环境变量

反向代理配置

Nginx 示例

server {
    listen 80;
    server_name woodpecker.example.com;

    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;

        proxy_pass http://127.0.0.1:8000;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_buffering off;

        chunked_transfer_encoding off;
    }
}

Traefik 高级配置

services:
  server:
    deploy:
      labels:
        - traefik.http.services.woodpecker-service.loadbalancer.server.port=8000
        - traefik.http.routers.woodpecker-secure.rule=Host(`ci.example.com`)
        - traefik.http.routers.woodpecker-secure.tls=true
        - traefik.http.routers.woodpecker-secure.tls.certresolver=letsencrypt

监控指标

Woodpecker 提供 Prometheus 兼容的 /metrics 端点：

scrape_configs:
  - job_name: 'woodpecker'
    bearer_token: dummyToken...
    static_configs:
      - targets: ['woodpecker.domain.com']

关键指标包括：

• 流水线计数（woodpecker_pipeline_count）
• 构建时间（woodpecker_pipeline_time）
• 待处理步骤数（woodpecker_pending_steps）
• 运行中步骤数（woodpecker_running_steps）

高级功能

外部配置 API

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

WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig

安全警告：需完全信任配置服务，因其可修改流水线执行逻辑。

UI 自定义

支持注入自定义 CSS 和 JS：

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

示例：添加顶部横幅

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

总结

Woodpecker CI 提供了灵活的服务器配置选项，从基础的用户权限管理到高级的监控和UI定制。管理员应根据实际业务需求和安全要求，选择合适的配置方案。对于生产环境，特别建议：

1. 使用封闭式用户注册
2. 配置数据库持久化和备份
3. 启用TLS加密
4. 设置适当的监控指标

通过合理配置，Woodpecker CI 能够为企业提供稳定可靠的持续集成服务。

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