Woodpecker CI 从 v3.0.0-rc1 升级到 v3.0.1 的数据库权限问题解析

在使用 Woodpecker CI 进行版本升级时，从 v3.0.0-rc1 升级到 v3.0.1 版本可能会遇到数据库迁移失败的问题。本文将详细分析这一问题的原因，并提供完整的解决方案。

问题现象

当用户尝试将 Woodpecker CI 从 v3.0.0-rc1 升级到 v3.0.1 版本时，服务器容器会启动失败，并显示以下错误信息：

error running server error="can't setup store: could not migrate datastore: migration remove-repo-scm failed: attempt to write a readonly database"

随后，连接服务也会因无法连接到服务器而失败。这个问题主要出现在使用 SQLite 作为数据库的部署环境中。

问题根源

这个问题的根本原因在于 Woodpecker CI 从 v3.0.0 版本开始采用了 rootless 容器运行模式。这一安全改进意味着容器不再以 root 用户身份运行，而是使用普通用户权限（UID 1000）。

当从旧版本升级时，原有的 SQLite 数据库文件（位于 /var/lib/woodpecker 目录下）可能仍然保留着 root 用户的权限设置。由于新版本使用非特权用户运行，这个用户没有足够的权限来修改数据库文件，导致数据库迁移失败。

解决方案

要解决这个问题，需要手动调整数据库文件的权限设置。具体步骤如下：

1. 首先定位到 Woodpecker CI 的数据存储目录。在 Docker 部署中，这通常是挂载到容器内 /var/lib/woodpecker 目录的宿主机目录。

2. 执行以下命令修改目录所有权：

   chown -R 1000:1000 <挂载目录路径>
   

3. 重新启动 Woodpecker CI 服务。

技术背景

Woodpecker CI 从 v3.0.0 版本开始采用 rootless 容器设计，这是现代容器安全的最佳实践之一。rootless 容器提供了更好的安全隔离，减少了潜在的攻击面。然而，这种改变也带来了与现有文件系统权限的兼容性问题。

SQLite 数据库需要写入权限才能执行迁移操作。当容器以非 root 用户运行时，必须确保该用户对数据库文件有适当的读写权限。这个问题不仅限于 Woodpecker CI，也是许多从特权容器迁移到非特权容器的应用程序常见的问题。

最佳实践

为了避免类似问题，建议：

1. 在升级前仔细阅读项目的发布说明和迁移指南
2. 对重要数据进行备份
3. 在测试环境中先验证升级过程
4. 了解容器运行时的用户权限模型
5. 定期检查持久化存储的权限设置

通过理解这些底层原理，用户可以更好地管理和维护他们的 Woodpecker CI 实例，确保平滑的升级体验和稳定的运行环境。