升级 Weblate¶

Docker 镜像升级¶

官方 Weblate Docker 镜像（请参见使用 Docker 安装）集成了所有升级步骤。通常无需除拉取最新（或至少较新）版本之外的人工交互。

参见

升级 Docker 容器

一般的升级指示¶

升级前，请始终检查软件要求的新更改。安装或升级所有的必需项后，请确保你的 settings.py 匹配配置中的更改（正确的值请见 settings_example.py）。

升级前，请务必查阅特定版本的操作指南。如果您要跳过某些版本，请按照升级中要跳过的所有版本的说明进行操作。有时最好先升级到某个中间版本，以确保顺利迁移。跨越多个版本的升级应该是可行的，但不像单一版本的升级那样经过良好的测试！

备注

请在升级前始终备份完整数据库，以便你可以在升级失败的情况下回滚数据库，参见备份和迁移 Weblate。

请等待 Celery 队列变空，然后停止 WSGI 和 Celery 进程避免升级时旧进程运行。否则可能发生不兼容的数据库更改。

Celery 任务队列不是跨版本的稳定接口，因此不保证来自旧版本的队列任务在升级后能正常工作。可以在管理界面中监控队列长度或使用 celery_queues 来监控队列长度。

升级 Weblate

对于 pip 安装，可以通过以下命令实现：

uv pip install -U "weblate[all]==version"

或者，如果您只想获取最新发布的版本：

uv pip install -U "weblate[all]"

如果不想安装所有可选依赖项，请执行以下操作：

uv pip install -U weblate

使用 Git checkout，你需要取回新的源代码并更新你的安装：

cd weblate-src
git pull
# Update Weblate inside your Python environment
. ~/weblate-env/bin/uv pip install -e '.[all]'
# Install dependencies directly when not using Python environment
uv pip install --upgrade -e .
# Install optional dependencies directly when not using a Python environment
uv pip install --upgrade -e '.[all]'

新版本 Weblate 可能有新的 Python 依赖项，快来看看有没有你感兴趣的功能。
升级配置文件，所需的步骤请参考 settings_example.py 或特定版本的操作指南。
升级数据库：
```
weblate migrate --noinput
```
收集升级的静态文件（请参见运行服务器和为静态文件提供服务）：
```
weblate collectstatic --noinput --clear
```
压缩 JavaScript 和 CSS 文件（可选步骤，请参见压缩客户端资源）：
```
weblate compress
```
如果你从 Git 运行安装，每次升级时还应该重新生成 locale 文件。可以通过调用下列项目来进行：
```
weblate compilemessages
```
验证您的设置合理（还请参见生产设置）：
```
weblate check --deploy
```
重新启动 Celery 工作进程（请参见使用 Celery 的后台任务）。

特定版本的操作指南¶

在 5.0 版本发生变更: 特定版本的操作指南现在包含在发行日志中，见 Weblate 2026.6。

Upgrade from an older unsupported release¶

Direct upgrades are only supported for releases from the current or previous calendar year. If you need to upgrade across this boundary, upgrade first to an intermediate version as listed below. Upgrades skipping this step are not supported and will break.

如果从 2.x 发布版本升级，请始终先升级到 3.0.1。
如果从 3.x 发布版本升级，请始终首先升级到 4.0.4。
如果从 4.x 发布版本升级，请首先升级到 5.0.2。
If you are upgrading from 5.0.x-5.9.x, always first upgrade to 5.10.4.
Upgrades from 5.10.x and newer are currently directly supported.

参见

从其他数据库迁移到 PostgreSQL¶

警告

Weblate 不再支持 MySQL 和 MariaDB。升级前必须迁移到 PostgreSQL。

如果您目前使用 MySQL 或 MariaDB 运行 Weblate，请考虑执行以下步骤迁移到 PostgreSQL，因为 Weblate 与它搭配性能更好。请记住迁移前要停止 Web 和 Celery 服务器，否则会导致不一致的数据。

创建 PostgreSQL 数据库¶

通常来说，用单独的数据库中和单独的用户账户运行 Weblate 是个好主意：

# If PostgreSQL was not installed before, set the main password
sudo -u postgres psql postgres -c "\password postgres"

# Create a database user called "weblate"
sudo -u postgres createuser -D -P weblate

# Create the database "weblate" owned by "weblate"
sudo -u postgres createdb -E UTF8 -O weblate weblate

使用 pgloader 迁移到 PostgreSQL¶

pgloader 是通用迁移工具，将数据迁移到 PostgreSQL。你可以使用它来迁移你的 Weblate 数据库。

调整 settings.py 文件将 PostgreSQL 用作数据库。

迁移 PostgreSQL 中的模式：

weblate migrate
weblate sqlflush | weblate dbshell

3. Run the pgloader to transfer the data. The following script can be used to migrate the database, but you might want to learn more about pgloader to better understand what it does, and tweak it to match your setup:

LOAD DATABASE
     FROM mysql://weblate:password@localhost/weblate
     INTO postgresql://weblate:password@localhost/weblate

WITH include no drop, truncate, create no tables, create no indexes, no foreign keys, disable triggers, reset sequences, data only

ALTER SCHEMA 'weblate' RENAME TO 'public'
;

从 Pootle 迁移¶

由于 Weblate 最初是作为 Pootle 的替代品而编写的，因此支持从 Pootle 迁移用户账户。你可以从 Pootle 转储用户，并使用 importusers 将其导入。