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 支持三种主流数据库引擎：

1. SQLite（默认）：嵌入式数据库，零配置开箱即用
2. MySQL/MariaDB：适用于生产环境的关系型数据库
3. PostgreSQL：功能强大的开源关系型数据库

SQLite 配置详解

基本特性

SQLite 是 Woodpecker CI 的默认数据库引擎，具有以下特点：

• 无需单独安装数据库服务
• 所有数据存储在单个文件中
• 适合小型部署和测试环境

持久化配置

在容器化部署时，必须通过数据卷实现持久化存储：

version: '3'

services:
  woodpecker-server:
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker/

适用场景

• 开发测试环境
• 小型团队使用
• 资源受限的环境

MySQL/MariaDB 配置指南

版本要求

Woodpecker CI 对 MySQL/MariaDB 的版本要求取决于所使用的 Go 驱动，建议使用较新的稳定版本以确保兼容性。

配置示例

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

关键参数说明

• parseTime=true：确保正确处理时间类型
• 连接格式：用户名:密码@协议(地址:端口)/数据库名

生产建议

• 为 Woodpecker CI 创建专用数据库用户
• 配置适当的连接池参数
• 启用 SSL 加密连接

PostgreSQL 配置指南

版本要求

Woodpecker CI 要求 PostgreSQL 11 或更高版本。

配置示例

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

关键参数说明

• 标准连接字符串格式
• sslmode=disable 仅限测试环境使用
• 支持所有标准 PostgreSQL 连接参数

性能优化建议

• 根据负载调整连接池大小
• 考虑配置适当的索引
• 定期执行 VACUUM 操作

数据库初始化

重要注意事项

Woodpecker CI 不会自动创建数据库实例，使用 MySQL 或 PostgreSQL 时需要：

1. 预先创建数据库实例
2. 确保连接用户有足够权限
3. 执行标准的 CREATE DATABASE 语句

数据库迁移机制

自动迁移特性

Woodpecker CI 内置数据库迁移功能，包括：

• 首次启动时的表结构创建
• 版本升级时的自动结构变更
• 索引的创建与更新

迁移注意事项

• 大版本升级前建议备份数据
• 迁移过程通常不可逆
• 生产环境建议先在测试环境验证迁移

数据库运维建议

备份策略

Woodpecker CI 不提供内置备份功能，建议：

• MySQL: 使用 mysqldump 或 Percona XtraBackup
• PostgreSQL: 使用 pg_dump 或 WAL 归档
• SQLite: 直接备份数据库文件

数据归档

虽然 Woodpecker CI 设计上较为保守地存储数据，但随着时间推移：

• 构建日志会显著增加数据库大小
• 建议定期清理历史数据
• 可考虑将旧数据导出到归档存储

总结

选择合适的数据库引擎对 Woodpecker CI 的性能和稳定性至关重要。SQLite 适合轻量级使用，而 MySQL 和 PostgreSQL 则更适合生产环境。无论选择哪种数据库，都应确保有适当的备份和监控策略，以保障持续集成流程的可靠性。

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