Woodpecker CI 在 Kubernetes 中部署时 SQLite 数据库连接问题解析

问题背景

在 Kubernetes 环境中使用 Helm 部署 Woodpecker CI 时，用户遇到了服务器无法正常连接 SQLite 数据库的问题。具体表现为两种不同的错误场景：

1. 当使用 FreeNAS-NFS CSI 作为持久化存储时，数据库文件能够创建但会立即损坏
2. 当使用 FreeNAS-ISCSI CSI 时，数据库文件则完全无法创建

错误现象分析

服务器日志显示以下关键错误信息：

no sqlite3 file found, will create one at '/var/lib/woodpecker/woodpecker.sqlite'
can't setup store: could not migrate datastore: unable to open database file: no such file or directory

这表明服务器尝试在指定路径创建或访问 SQLite 数据库文件时遇到了问题。

根本原因

经过深入分析，发现问题的根本原因在于：

1. NFS 存储问题：SQLite 数据库对文件系统的原子操作有严格要求，而 NFS 协议在某些情况下无法完全保证这些操作的原子性，导致数据库文件损坏。

2. iSCSI 存储权限问题：当使用 iSCSI 存储时，创建的 PVC 默认由 root 用户拥有，而 Woodpecker 容器以 UID 1000 运行，导致权限不足无法创建或访问数据库文件。

解决方案

针对 NFS 存储问题

建议避免在 NFS 存储上使用 SQLite 数据库，因为这是 SQLite 官方不推荐的做法。可以考虑以下替代方案：

1. 使用其他类型的存储后端，如本地存储或块存储
2. 将数据库迁移到专门的数据库服务，如 PostgreSQL 或 MySQL

针对 iSCSI 存储权限问题

可以通过以下方式解决权限问题：

1. 修改 PVC 权限：在创建 PVC 后，手动修改挂载目录的所有权

   chown -R 1000:1000 /var/lib/woodpecker
   

2. 使用 initContainer：在 Helm chart 中配置 initContainer 来预先设置正确的权限

   initContainers:
     - name: volume-permissions
       image: busybox
       command: ["sh", "-c", "chown -R 1000:1000 /var/lib/woodpecker"]
       volumeMounts:
         - name: woodpecker-data
           mountPath: /var/lib/woodpecker
   

3. 修改安全上下文：为容器配置适当的安全上下文

   securityContext:
     runAsUser: 0  # 以 root 用户运行
     fsGroup: 1000 # 设置文件系统组
   

最佳实践建议

1. 存储选择：对于生产环境，建议使用本地存储或专门的数据库服务，而非 NFS 存储 SQLite 数据库。

2. 权限管理：在 Kubernetes 环境中部署时，应提前规划好存储卷的权限设置，确保容器用户有适当的访问权限。

3. 监控与日志：部署后应密切监控数据库状态，确保没有权限或文件系统相关的问题。

4. 文档查阅：在遇到类似问题时，应仔细查阅 Woodpecker CI 的官方文档和 SQLite 的存储要求说明。

总结

在 Kubernetes 中部署 Woodpecker CI 时，存储后端的正确配置至关重要。特别是当使用 SQLite 作为数据库时，需要特别注意文件系统的选择和权限设置。通过理解这些底层原理和采取适当的配置措施，可以避免类似问题的发生，确保 CI/CD 系统的稳定运行。