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 服务器端的各项功能，包括用户管理、数据库配置、TLS 设置、反向代理集成等关键环节。

用户与权限配置

Woodpecker 采用 OAuth2 协议与代码托管平台（如 GitLab、Gitea 等）集成，自身不提供用户注册功能。系统提供灵活的权限控制机制：

注册模式控制
- 默认关闭注册（WOODPECKER_OPEN=false）
- 可通过 CLI 工具 woodpecker-cli user 手动管理用户
管理员指定
```
WOODPECKER_ADMIN=john.smith,jane_doe
```

组织过滤

WOODPECKER_OPEN=true
WOODPECKER_ORGS=dolores,dog-patch

仓库同步配置

Woodpecker 会根据用户的 OAuth 权限同步仓库，可通过以下配置限制同步范围：

WOODPECKER_REPO_OWNERS=my_company,my_company_oss_github_user

数据库配置

数据库类型选择

SQLite（默认）
- 零配置嵌入式数据库
- 数据存储在 /var/lib/woodpecker/
- 容器部署时需挂载数据卷

MySQL/MariaDB

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

PostgreSQL

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

数据库管理须知

需手动创建数据库
系统自动处理表结构和索引创建
版本升级时自动执行数据库迁移
建议使用第三方工具进行定期备份

TLS 安全配置

通过挂载证书文件启用 HTTPS：

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

容器部署时需要：

暴露 443 端口
挂载证书文件
设置环境变量

反向代理配置

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 兼容的监控端点：

启用监控

WOODPECKER_PROMETHEUS_AUTH_TOKEN=dummyToken...

Prometheus 配置示例

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

关键监控指标
- 构建次数统计
- 构建耗时
- 待处理/运行中任务数
- 仓库/用户/工作节点数量

外部配置 API

Woodpecker 支持通过 HTTP API 调用外部配置服务：

WOODPECKER_CONFIG_SERVICE_ENDPOINT=https://example.com/ciconfig

请求包含仓库和构建信息，响应可返回修改后的流水线配置。所有请求使用 ed25519 算法签名，公钥可从 /api/signature/public-key 获取。

UI 自定义

支持通过自定义 CSS 和 JS 文件修改界面：

WOODPECKER_CUSTOM_CSS_FILE=/usr/local/www/woodpecker.css
WOODPECKER_CUSTOM_JS_FILE=/usr/local/www/woodpecker.js

示例：添加顶部横幅

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

通过以上配置，您可以全面掌控 Woodpecker CI 服务器的各项功能，构建安全、高效的持续集成环境。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考