Woodpecker CI 中 Kubernetes 后端挂载卷的最佳实践

在持续集成工具 Woodpecker CI 的 Kubernetes 后端配置中，关于持久化卷(Persistent Volume)的挂载方式存在一些需要特别注意的技术细节。本文将详细介绍正确的配置方法，帮助用户避免常见错误。

传统配置方式的演进

早期版本的 Woodpecker CI 文档中曾建议使用 settings 配置项来声明挂载卷，例如：

settings:
  mount:
    - "woodpecker-cache"

然而，这种配置方式在 Woodpecker CI 2.7.3 及更高版本中已被弃用。当与 commands 指令同时使用时，系统会抛出"Cannot configure both commands and settings"的错误提示。

推荐的标准配置方式

当前推荐的做法是直接使用 volumes 配置项来声明挂载卷，这种方式更加简洁且符合 Kubernetes 的原生设计理念：

volumes:
  - woodpecker-cache:/woodpecker/src/cache

完整的 PVC 配置示例

为了使上述挂载生效，用户需要预先在 Kubernetes 集群中创建 PersistentVolumeClaim (PVC)。以下是一个完整的 PVC 配置示例：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: woodpecker-cache
spec:
  storageClassName: "longhorn"
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 1Gi

实际应用示例

下面是一个完整的 Woodpecker CI 流水线配置示例，展示了如何在构建步骤中使用持久化卷：

build:
  image: debian:bookworm
  volumes:
    - woodpecker-cache-claim:/cache
  commands:
    - ls -al /cache
    - echo "测试内容" > /cache/test.txt

技术背景解析

这种配置变更反映了 Woodpecker CI 向更标准化的 Kubernetes 原生资源管理方式的演进。settings 配置项原本是为特定插件设计的保留字段，而直接使用 volumes 不仅简化了配置，还提供了更好的灵活性和可维护性。

对于初次接触 Kubernetes 持久化存储的用户，建议先了解 Kubernetes 的 PersistentVolume 和 PersistentVolumeClaim 基本概念，这将有助于更好地理解和使用 Woodpecker CI 的卷挂载功能。