Drone 分支版镜像技术文档

一、镜像概述

1.1 主要用途

本镜像为 Drone 的分支版本（Fork），基于 Drone 核心功能开发，补充了原版 Drone 中缺失的部分小功能。主要用于自动化软件开发生命周期中的持续集成/持续部署（CI/CD）流程，支持代码仓库集成、自动化构建、测试、部署等任务，适用于需要在 Drone 基础上扩展功能的开发团队。

二、核心功能与特性

2.1 Drone 原生功能

继承 Drone 核心能力，包括：

• 代码仓库集成：支持 GitHub、GitLab、Bitbucket 等主流代码托管平台，通过 WebHook 触发 CI/CD 流程；
• 自动化流程编排：通过 .drone.yml 文件定义构建、测试、部署等多阶段任务，支持并行执行、依赖管理；
• 插件生态：兼容 Drone 官方插件市场（如 Docker 构建、Kubernetes 部署、通知工具等），支持自定义插件；
• 分布式架构：支持多 Runner 节点部署，满足大规模构建任务需求；
• 权限控制：基于仓库角色的细粒度权限管理，支持 OAuth2、LDAP 等认证方式。

2.2 新增功能（分支特有）

在原生功能基础上补充以下小功能（具体功能需参考镜像官方说明，以下为常见扩展方向示例）：

• 增强日志系统：支持结构化日志输出，便于日志聚合与问题排查；
• 自定义触发条件：新增基于代码标签、提交信息关键词的构建触发规则；
• 多阶段构建优化：优化任务缓存机制，减少重复依赖拉取时间；
• UI 体验改进：新增构建进度实时展示、历史任务对比视图；
• 环境变量管理：支持从外部配置文件导入全局环境变量，避免敏感信息硬编码。

三、使用场景与适用范围

3.1 适用场景

• 中大型开发团队：需要更灵活的 CI/CD 流程定制（如复杂触发规则、优化的资源利用）；
• 多语言/多框架项目：需通过新增功能简化跨语言项目的构建配置（如统一环境变量管理）；
• 对稳定性有高要求的场景：通过增强日志和监控功能提升流程可观测性；
• Drone 现有用户：希望在不迁移工具的前提下扩展功能，降低学***成本。

3.2 不适用场景

• 对 CI/CD 工具无定制化需求的小型项目（建议直接使用官方 Drone 镜像）；
• 依赖 Drone 官方未公开 API 或插件的场景（需确认分支版本兼容性）。

四、使用方法与配置说明

4.1 前提条件

• Docker 19.03+ 或 Docker Compose 2.0+；
• 可访问的代码仓库（GitHub/GitLab/Bitbucket 等），并获取 OAuth 应用凭证（Client ID/Secret）；
• 持久化存储（如数据库：PostgreSQL/MySQL，用于存储任务 metadata）。

4.2 基本部署（Docker Run）

通过 docker run 快速启动单节点服务（需替换下方占位符为实际配置）：

docker run -d \
  --name drone-server \
  --restart always \
  -p 80:80 \
  -p 443:443 \
  -v /var/lib/drone:/data \
  -e DRONE_AGENTS_ENABLED=true \
  -e DRONE_GITHUB_CLIENT_ID=<your-github-client-id> \
  -e DRONE_GITHUB_CLIENT_SECRET=<your-github-client-secret> \
  -e DRONE_RPC_SECRET=<your-rpc-secret> \  # 与 Runner 通信的密钥（自定义随机字符串）
  -e DRONE_SERVER_HOST=<your-server-domain> \  # 服务访问域名/IP
  -e DRONE_SERVER_PROTO=https \  # 协议（http/https）
  -e DRONE_LOGS_STRUCTURED=true \  # 启用新增功能：结构化日志（分支特有）
  -e DRONE_TRIGGER_KEYWORD=RELEASE \  # 启用新增功能：基于提交信息关键词触发（分支特有）
  <镜像名称:版本>  # 替换为实际镜像标签（如 username/drone-fork:latest）

4.3 Docker Compose 部署

通过 docker-compose.yml 配置服务（含数据库和 Runner 示例）：

version: '3.8'

services:
  # Drone 服务端
  drone-server:
    image: <镜像名称:版本>  # 替换为分支版镜像标签
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - drone-data:/data
      - ./certs:/certs  # 如需 HTTPS，挂载证书目录
    environment:
      # 基础配置（同 Drone 原生）
      - DRONE_AGENTS_ENABLED=true
      - DRONE_GITHUB_CLIENT_ID=<your-github-client-id>
      - DRONE_GITHUB_CLIENT_SECRET=<your-github-client-secret>
      - DRONE_RPC_SECRET=<your-rpc-secret>
      - DRONE_SERVER_HOST=<your-server-domain>
      - DRONE_SERVER_PROTO=https
      - DRONE_DATABASE_DRIVER=postgres
      - DRONE_DATABASE_DATASOURCE=postgresql://user:pass@db:5432/drone?sslmode=disable
      
      # 新增功能配置（分支特有）
      - DRONE_LOGS_STRUCTURED=true  # 启用结构化日志
      - DRONE_TRIGGER_KEYWORD=RELEASE  # 提交信息含 "RELEASE" 时触发构建
      - DRONE_CACHE_TTL=24h  # 任务缓存有效期（默认 12h）

  # 数据库（PostgreSQL 示例）
  db:
    image: postgres:14
    restart: always
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=drone

  # Runner 节点
  runner:
    image: drone/drone-runner-docker:latest  # 兼容官方 Runner
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DRONE_RPC_PROTO=https
      - DRONE_RPC_HOST=<your-server-domain>
      - DRONE_RPC_SECRET=<your-rpc-secret>  # 与服务端保持一致
      - DRONE_RUNNER_CAPACITY=4  # 最大并行任务数

volumes:
  drone-data:
  postgres-data:

4.4 环境变量配置

4.4.1 基础配置参数（同 Drone 原生）

4.4.2 新增功能配置参数（分支特有）

4.5 配置文件说明

若需自定义全局配置（如插件默认参数、构建资源限制），可通过挂载配置文件 /etc/drone/drone.env 实现，格式为 KEY=VALUE，优先级低于环境变量。

五、注意事项

1. 兼容性：本镜像基于 Drone 分支开发，需确认与官方 Runner、插件的兼容性；
2. 数据迁移：从官方 Drone 迁移时，需备份数据库并检查新增功能是否影响历史数据；
3. 安全配置：敏感信息（如 DRONE_RPC_SECRET）建议通过环境变量注入，避免硬编码；
4. 新增功能细节：具体新增功能的使用方法、参数说明请参考镜像官方文档或源码注释。