Weblate Docker 镜像中安装自定义 Python 包的解决方案

Weblate Docker 镜像中安装自定义 Python 包的解决方案

在 Weblate 5.5 版本之后，Docker 镜像开始使用 uv 作为 Python 包管理器，并将所有 Python 包安装在 /app/venv 目录下。这一变化导致了一些用户在尝试安装自定义 Python 包（如 elastic-apm 监控工具或自定义 Weblate 模块）时遇到了权限问题。

问题背景

Weblate 是一个开源的本地化平台，其 Docker 镜像为用户提供了快速部署的便利。在 5.5 版本之前，用户可以通过简单的 pip install 命令在 Docker 容器中安装额外的 Python 包。然而，随着 uv 包管理器的引入，安装流程发生了变化。

具体问题表现

当用户尝试使用以下命令安装额外包时：

uv pip install elastic-apm

系统会返回权限错误：

error: failed to create file `/app/venv/.lock`
Caused by: Permission denied (os error 13)

同样的问题也出现在尝试安装自定义 Weblate 模块时。

解决方案

要解决这个问题，用户需要在 Dockerfile 中先切换到 root 用户（UID 0）进行包安装操作，然后再切换回普通用户。这是 Docker 容器中处理权限问题的标准做法。

正确的 Dockerfile 示例如下：

FROM weblate/weblate:latest

# 切换到 root 用户安装包
USER root

# 安装 elastic-apm
RUN uv pip install elastic-apm
RUN echo 'INSTALLED_APPS += ("elasticapm.contrib.django",)' >> "/app/data/settings-override.py"
RUN echo "MIDDLEWARE += ('elasticapm.contrib.django.middleware.Catch404Middleware',)" >> "/app/data/settings-override.py"
RUN echo "ELASTIC_APM = {'DJANGO_TRANSACTION_NAME_FROM_ROUTE': True, 'DEBUG': True}" >> "/app/data/settings-override.py"

# 安装自定义模块
COPY --chown=weblate:weblate weblate_customization/ /usr/lib/python3.12/site-packages/weblate_customization/
RUN uv pip install -e /usr/lib/python3.12/site-packages/weblate_customization/
RUN echo "CHECK_LIST += ('weblate_customization.checks.TranslationSameAsKeyCheck',)" >> "/app/data/settings-override.py"

# 切换回普通用户
USER weblate

技术原理

Weblate Docker 镜像默认使用 UID 1000 的用户运行，这是出于安全考虑的最佳实践。而 uv 包管理器在安装包时需要写入 /app/venv 目录下的锁定文件，这需要更高的权限。通过临时切换到 root 用户，我们可以获得必要的权限来完成包安装操作。

最佳实践建议

1. 始终在安装完所需包后切换回普通用户，以保持容器运行时的安全性
2. 对于自定义模块，确保使用正确的 Python 版本路径（如示例中的 python3.12）
3. 考虑将配置修改集中到一个单独的 settings-override.py 文件中，便于维护
4. 定期检查 Weblate 官方文档，了解最新的安装和配置指南

通过遵循这些步骤，用户可以顺利地在 Weblate Docker 容器中安装所需的额外 Python 包和自定义模块，同时保持系统的安全性和稳定性。