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 本身不提供用户注册系统，而是通过 OAuth2 协议与代码托管平台（如 GitHub、GitLab 等）集成获取用户信息。

注册模式配置

默认情况下，用户注册是关闭的（WOODPECKER_OPEN=false）。如需开放注册：

WOODPECKER_OPEN=true

高级注册控制

1. 仅限管理员添加用户（推荐生产环境使用）：

   WOODPECKER_OPEN=false
   WOODPECKER_ADMIN=admin1,admin2
   

   然后通过 CLI 添加用户：woodpecker-cli user add

2. 限制特定组织成员注册：

   WOODPECKER_OPEN=true
   WOODPECKER_ORGS=org1,org2
   

管理员配置

管理员账户需要在配置中明确指定：

WOODPECKER_ADMIN=admin1,admin2

仓库过滤机制

为避免同步过多仓库，可通过以下配置限制：

WOODPECKER_REPO_OWNERS=company1,team2

私有镜像仓库配置

为所有流水线提供统一的私有 Docker 仓库认证：

WOODPECKER_DOCKER_CONFIG=/path/to/docker/config.json

敏感数据安全处理

Docker Compose 环境

推荐使用 Docker Secrets 管理敏感信息：

services:
  woodpecker-server:
    environment:
      - WOODPECKER_AGENT_SECRET_FILE=/run/secrets/woodpecker-secret
    secrets:
      - woodpecker-secret

secrets:
  woodpecker-secret:
    external: true

创建 secret：

openssl rand -hex 32 | docker secret create woodpecker-secret -

界面自定义

支持通过 CSS 和 JavaScript 自定义界面：

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

示例 CSS（添加顶部横幅）：

.banner-message {
  position: absolute;
  width: 280px;
  margin-left: 240px;
  font-weight: bold;
  text-align: center;
}

核心配置参数详解

基础设置

• WOODPECKER_HOST：服务公开访问地址
• WOODPECKER_SERVER_ADDR：HTTP 监听端口（默认 :8000）
• WOODPECKER_SERVER_ADDR_TLS：HTTPS 监听端口（默认 :443）

安全配置

• WOODPECKER_AGENT_SECRET：服务端与 Agent 的共享密钥
• WOODPECKER_SESSION_EXPIRES：会话有效期（默认 72h）

资源限制

• WOODPECKER_LIMIT_MEM：容器内存限制（字节）
• WOODPECKER_LIMIT_CPU_SET：限制使用的 CPU 核心

数据库配置

• WOODPECKER_DATABASE_DRIVER：数据库类型（sqlite3/mysql/postgres）
• WOODPECKER_DATABASE_DATASOURCE：数据库连接字符串

最佳实践建议

1. 生产环境安全：

   • 始终使用 HTTPS
   • 限制注册为管理员手动添加
   • 定期轮换 AGENT_SECRET

2. 性能优化：

   • 对高负载环境使用 MySQL/PostgreSQL
   • 合理设置资源限制防止单个流水线占用过多资源

3. 监控：

   • 启用 Prometheus 指标端点
   • 设置适当的日志级别

通过本文的详细配置指南，您可以根据实际需求灵活调整 Woodpecker CI 服务器，构建安全、高效的持续集成环境。

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