配置说明#

安装 Weblate#

根据你的设置和经验,选择一个适合你的安装方法:

架构概览#

digraph architecture { graph [fontname="sans-serif", fontsize=10, newrank=true, rankdir=LR, splines=ortho ]; node [fontname="sans-serif", fontsize=10, height=0, margin=.15, shape=box ]; edge [fontname="sans-serif", fontsize=10 ]; subgraph cluster_thirdparty { graph [color=lightgrey, label="Third-party services", style=filled ]; mt [label="Machine translation", style=dotted]; sentry [label="Sentry\nError collection", style=dotted]; mail [label="E-mail server"]; auth [label="SSO\nAuthentication provider", style=dotted]; } subgraph cluster_ingress { graph [color=lightgrey, label=Ingress, style=filled ]; web [label="Web server", shape=hexagon]; } subgraph cluster_weblate { graph [color=lightgrey, label="Weblate code-base", style=filled ]; celery [fillcolor="#144d3f", fontcolor=white, label="Celery workers", style=filled]; wsgi [fillcolor="#144d3f", fontcolor=white, label="WSGI server", style=filled]; } subgraph cluster_services { graph [color=lightgrey, label=Services, style=filled ]; redis [label="Redis\nTask queue\nCache", shape=cylinder]; db [label="PostgreSQL\nDatabase", shape=cylinder]; fs [label=Filesystem, shape=cylinder]; } web -> wsgi; web -> fs; celery -> mt [style=dotted]; celery -> sentry [style=dotted]; celery -> mail; celery -> redis; celery -> db; celery -> fs; wsgi -> mt [style=dotted]; wsgi -> sentry [style=dotted]; wsgi -> auth [style=dotted]; wsgi -> redis; wsgi -> db; wsgi -> fs; }

软件要求#

操作系统#

目前已知 Weblate 可运行在 Linux、FreeBSD 和 macOS 上。其他类 Unix 的系统也很可能支持运行。

Windows 不支持 Weblate。但 Weblate 可能仍然可以工作,并且很乐意接受补丁。

其他服务#

Weblate 为其操作使用其他服务。至少需要后面的服务运行:

提示

使用 Docker 安装 包括 PostgreSQL 和 Redis,让安装更加容易。

Python 依赖项#

Weblate 是用 Python 编写的,并且支持 Python 3.9 或更新版本。可以使用 pip 或你的分发包来安装依赖项,完整列表可在 requirements.txt 中找到。

警告

虽然 Weblate 本身没有任何阻止使用 Python 3.12 的东西,但有几个突出的问题需要注意:

最重要的依赖项:

Django

https://www.djangoproject.com/

Celery

https://docs.celeryq.dev/

Translate Toolkit(翻译工具包)

https://toolkit.translatehouse.org/

translation-finder

https://github.com/WeblateOrg/translation-finder

Python 社交认证

https://python-social-auth.readthedocs.io/

Django REST 框架

https://www.django-rest-framework.org/

使用 pip 进行安装时,您可以在安装时直接指定所需的功能:

pip install "Weblate[Postgres,Amazon,SAML]"

或者你可以安装具有所有可选功能的 Weblate:

pip install "Weblate[all]"

或者你可以安装没有任何可选功能的 Weblate:

pip install Weblate

其他系统要求#

必须在系统上安装以下依赖项:

Git

https://git-scm.com/

Pango、Cairo 及相关的头文件和 GObject 内省数据

https://cairographics.org/https://pango.gnome.org/,请参见 Pango 和 Cairo

git-review (可选的 Gerrit 支持)

https://pypi.org/project/git-review/

git-svn (可选的 Subversion 支持)

https://git-scm.com/docs/git-svn

``tesseract``(只有在你的系统没有 tesserocr 二进制 wheels 文件时才需要)

https://github.com/tesseract-ocr/tesseract

licensee (可选,用于创建部件时检测许可证)

https://github.com/licensee/licensee

构建时的依赖项#

为了构建一些 Python 依赖项,你可能需要安装其依赖项。这取决于你如何安装它们,因此请查阅各个包的文档。如果你使用预构建的 Wheels 并使用 pip 安装或使用分发包时,则不需要那些依赖项。

Pango 和 Cairo#

Weblate 使用 Pango 和 Cairo 来生成位图小挂件(请参见 推广翻译 )并提供检查(请参见 管理字型 )。要正确地安装 Python 绑定,需要首先安装系统库——Cairo 和 Pango 都是需要的,而它们又需要 GLib。所有这些都应该与开发文件和 GObject 内省数据一起安装。

验证发布签名#

Weblate 发行文件使用 Sigstore 证书 进行密码学签名。这些签名被附加到 GitHub 发布中。

可使用 sigstore 包 执行验证。下列示例验证 5.4 发行版的签名:

sigstore verify github  \
   --cert-identity https://github.com/WeblateOrg/weblate/.github/workflows/setup.yml@refs/tags/weblate-5.4 \
   --bundle Weblate-5.4-py3-none-any.whl.sigstore \
   Weblate-5.4-py3-none-any.whl

文件系统权限#

Weblate 进程需要能够读写它保存数据的目录—— DATA_DIR。该目录下的所有文件都应该由运行所有 Weblate 进程的用户拥有和可写入(通常是 WSGI 和 Celery,请参见 运行服务器使用 Celery 的后台任务)。

默认的配置放置在 Weblate 源的相同树下,然而你会想要将这些移动到更好的位置,如: /var/lib/weblate

Weblate 试图自动建立这些文件夹,但当没有权限去执行时会失败。

当运行 管理命令 时应该小心,它们应该由 Weblate 自己运行的相同用户来运行,否则一些文件的权限会是错误的。

在 Docker 容器中,/app/data 卷中的所有文件必须由容器内的 weblate 用户(UID 1000)拥有。

Weblate 的数据库设置#

推荐使用 PostgreSQL 数据库服务器来运行 Weblate。

支持 PostgreSQL 12 及更高版本。

MySQL 和 MariaDB 受支持,但不推荐新安装使用它。

不支持其他数据库服务器。

数据库连接#

默认配置中,每个 Weblate 今晨保持到数据库的持久性连接。持久性连接改善 Weblate 响应水平,但可能需要给数据服务器提供更多资源。更多信息请参考 CONN_MAX_AGEPersistent connections

Weblate 需要至少下列连接数:

  • Celery 进程的 \((4 \times \mathit{nCPUs}) + 2\)

  • WSGI workers 的 \(\mathit{nCPUs} + 1\)

这应用到 Docker 容器默认值及此文档中提供的示例配置,不过一旦你自定义 WSGI worker 数目或调整 Celery 并行数,相关数字就会变化。

考虑下列情况,数据库连接数的实际限制需要较高:

  • 管理命令 也需要它们的连接。

  • 如果进程被杀(比如被 OOM killer 干掉),可能造成现有连接被拦截,导致超时。

PostgreSQL#

PostgreSQL 通常是基于 Django 的网站的最好选择。它是实现 Django 数据库层而使用的参考数据库。

备注

Weblate 使用三字母的扩展名,在某些情况下需要单独安装。查找 postgresql-contrib 或类似命名的包。

创建 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 --superuser --pwprompt weblate

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

提示

如果不想 Weblate 在 PostgreSQL 中使用超级用户,可以省略掉。在模式中必须作为 PostgreSQL 超级用户,来手动执行一些迁移步骤的情况下,Weblate 将使用:

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS btree_gin;

配置 Weblate 来使用 PostgreSQL#

PostgreSQL 的 settings.py 片段:

DATABASES = {
    "default": {
        # Database engine
        "ENGINE": "django.db.backends.postgresql",
        # Database name
        "NAME": "weblate",
        # Database user
        "USER": "weblate",
        # Name of role to alter to set parameters in PostgreSQL,
        # use in case role name is different than user used for authentication.
        # "ALTER_ROLE": "weblate",
        # Database password
        "PASSWORD": "password",
        # Set to empty string for localhost
        "HOST": "database.example.com",
        # Set to empty string for default
        "PORT": "",
        # Persistent connections
        "CONN_MAX_AGE": None,
        "CONN_HEALTH_CHECKS": True,
    }
}

数据库的合并执行了Weblate 使用的 ALTER ROLE 数据库角色。在多数情况下,角色的名称与用户名匹配。在更富在的设置中,角色的名称与用户名不同,而在数据库合并过程中会得到不存在的角色的错误信息(psycopg2.errors.UndefinedObject: role "weblate@hostname" does not exist,角色“weblate@hostname”不存在)。已知这会在 PostgreSQL 的 Azure 数据库时发生,但并不仅限于这种环境。请将 ALTER_ROLE 设置为数据库合并过程中 Weblate 应该更改的角色的名称。

MySQL 和 MariaDB#

警告

虽然 Weblate 仍继续支持 MySQL 和 MariaDB,我们的主要精力已经在 PostgreSQL 上。新安装推荐使用 PostgreSQL,要迁移现有安装到 PostgreSQL,请见 从其它数据库迁移到 PostgreSQL

一些 Weblate 功能使用 PostgreSQL 会表现得更好。这包括搜索与翻译记忆库,它们都利用了数据库中的全文特性,而且 PostgreSQL 的实现更胜一筹。

Weblate 还可以使用 MySQL 或 MariaDB,使用与两个数据库相关的 Django 而导致的警告,请参见 MySQL notesMariaDB notes。由于这些限制,我们建议对新安装使用 PostgreSQL

Weblate 需要至少 8.0 版的 MySQL 或至少 10.4 版的 MariaDB。

推荐 Weblate 使用后面的设置:

  • 使用 utf8mb4 字符集来允许表示更高的 Unicode 平面(例如 emojis 表情符号)。

  • innodb_large_prefix 配置服务器,以允许在文本字段上有更长的索引。

  • 设置隔离级别为 READ COMMITTED

  • SQL 模式应该设置为 STRICT_TRANS_TABLES

MySQL 8.x、MariaDB 10.5.x 或更新版本具有合理的默认配置,因此无需调整服务器,所有需要的都可以在客户端进行配置。

下面是用于 8GB 内存服务器的 /etc/my.cnf.d/server.cnf 的示例。这些设置应该足以用于多数安装。MySQL 和 MariaDB 具有来提高服务器性能的可调整部分,除非计划有大量并发用户访问系统,否则这些可调整部分被认为是不必要的。这些细节请查看各厂商的文档。

在运行您的 Weblate 前设置好 innodb_file_per_table 设置并重启 MySQL/MariaDB,这对减少安装时的问题绝对重要。

[mysqld]
character-set-server = utf8mb4
character-set-client = utf8mb4
collation-server = utf8mb4_unicode_ci

datadir=/var/lib/mysql

log-error=/var/log/mariadb/mariadb.log

innodb_large_prefix=1
innodb_file_format=Barracuda
innodb_file_per_table=1
innodb_buffer_pool_size=2G
sql_mode=STRICT_TRANS_TABLES

提示

如遇 #1071 - Specified key was too long; max key length is 767 bytes 错误, 请更新你的配置以包含上方的 innodb 设置并重新启动你的安装。

提示

在得到错误信息 #2006 - MySQL server has gone away 的形况下,配置 CONN_MAX_AGE 可能会有帮助。

配置 Weblate 来使用 MySQL/MariaDB#

MySQL 和 MariaDB 的 settings.py 片段:

DATABASES = {
    "default": {
        # Database engine
        "ENGINE": "django.db.backends.mysql",
        # Database name
        "NAME": "weblate",
        # Database user
        "USER": "weblate",
        # Database password
        "PASSWORD": "password",
        # Set to empty string for localhost
        "HOST": "127.0.0.1",
        # Set to empty string for default
        "PORT": "3306",
        # In case you wish to use additional
        # connection options
        "OPTIONS": {},
    }
}

开始安装前还应该在 MySQL 或 MariaDB 中创建 weblate 用户账户。使用下面的命令来实现:

GRANT ALL ON weblate.* to 'weblate'@'localhost' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

其他配置#

配置电子邮件发件箱#

Weblate 在各种情况下会发出电子邮件——用于激活账户,以及用户配置的各种通知。对于这些需要访问 SMTP 服务器。

电子邮件服务器使用这些设置进行配置: EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, EMAIL_USE_SSL, EMAIL_HOST_USER and EMAIL_PORT。从名称就可以大概知道它们的含义,但是你可以在Django 文档中找到更多信息。

提示

在得到有关不支持的认证的情况下(例如 SMTP AUTH extension not supported by server),这最可能因为使用不安全的链接并且服务器拒绝以这种方式认证而导致。在这种情况下尝试启动 EMAIL_USE_TLS

在反向代理之后运行#

Weblate 的几个特性依赖于能够得到客户端 IP 地址。这包括 频次限制针对垃圾电子邮件的保护审计日志

在默认设置中,Weblate 从 WSGI 句柄设置的 REMOTE_ADDR 中解析 IP 地址。

在运行反向代理的情况下,这个字段很可能包含其地址。需要配置 Weblate 来信任附加的 HTTP 标头,并从中解析 IP 地址。这不能默认允许,因为在不使用反向代理的安装时,这会允许 IP 地址欺骗。允许 IP_BEHIND_REVERSE_PROXY 对多数常见设置就足够了,但你还必须调整 IP_PROXY_HEADERIP_PROXY_OFFSET

另一件需要注意的事情是 Host header。它应该与 SITE_DOMAIN 中的内容一致。在反向代理中可能需要其他配置(例如,在 Apache 使用``ProxyPreserveHost On``,或在 nginx 中使用 proxy_set_header Host $host;)。

HTTP 代理#

Weblate 执行版本控制系统命令,这些命令接受来自环境的代理配置。推荐在 settings.py 中定义代理设置:

import os

os.environ["http_proxy"] = "http://proxy.example.com:8080"
os.environ["HTTPS_PROXY"] = "http://proxy.example.com:8080"

调整配置#

weblate/settings_example.py 复制到 weblate/settings.py,并且调整它与你的设置匹配。你可能想要调整后面的选项:

ADMINS

出现问题时接收通知站点管理员名单,例如合并失败或 Django 错误的通知。

联络表单也会在这些情况下发送电子邮件,除非你对 ADMINS_CONTACT 进行了配置。

ALLOWED_HOSTS

需要设置这个,来列出你的网站支持服务的主机。例如:

ALLOWED_HOSTS = ["demo.weblate.org"]

另外可以包括通配符:

ALLOWED_HOSTS = ["*"]

SESSION_ENGINE

配置如何存储会话。在保持默认的数据库后端引擎的情况下,应该安排 weblate clearsessions 从数据库中删除旧的会话。

如果使用 Redis 作为缓存(请参见 允许缓存 ),推荐也使用它作为会话:

SESSION_ENGINE = "django.contrib.sessions.backends.cache"

DATABASES

连接到数据库服务器,请查阅 Django 的文档了解详情。

DEBUG

对于任何生产服务器禁止这项。允许调试模式时,Django 会在出错的情况下向用户显示回溯信息,当禁止时,错误将每封电子邮件发送到 ADMINS (请参见上面)。

调试模式还使 Weblate 变慢,因为在这种情况下 Django 内部存储了非常多的信息。

DEFAULT_FROM_EMAIL

用于发送电子邮件的电子邮件发件人地址,例如注册电子邮箱。

SECRET_KEY

Django 使用的密钥,用于在 cookie 中登录一些信息,更多信息请参见 Django 密钥

参见

SECRET_KEY

SERVER_EMAIL

用作向管理员发送电子邮件的发送者地址的电子邮箱,例如通知失败的合并。

参见

SERVER_EMAIL

填满数据库#

在配置准备好之后,可以运行 migrate 来建立数据库结构。现在你将能够使用管理界面建立翻译项目。

完成后,你还应该在管理界面查看 Performance report,它会提示你站点上可能存在的非最佳配置。

生产设置#

对于生产设置,你应该进行以下部分中所述的调整。最关键的设置将触发警告:如果以超级用户身份登录,则会在顶部栏中显示一个叹号:

../_images/admin-wrench.webp

同样也推荐查看由 Django 触发的检查(尽管可能不需要修复所有的检查):

weblate check --deploy

你也可以检视 管理性能`中的相同检查清单,“管理性能”部分位于 :ref:`管理界面

禁止调试模式#

禁止 Django 的调试模式( DEBUG ):

DEBUG = False

在调试模式打开时,Django 存储所有执行的查询,并将错误的回溯显示给用户,这在生产设置中是不需要的。

参见

调整配置

是当地配置管理设置#

将正确的管理地址设置到 ADMINS 设置中,来确定服务器出现一些故障时谁接收电子邮件,例如:

ADMINS = (("Your Name", "your_email@example.com"),)

参见

调整配置

设置正确的网站域名#

在管理界面调整网站名称和域名,否则 RSS 中的链接或注册电子邮箱地址将不工作。这使用 SITE_DOMAIN 来配置,它应该包含网站域名。

在 4.2 版本发生变更: 在 4.2 版本之前,替代使用了 Django 网站框架,请参见 The “sites” framework

正确配置 HTTPS#

强烈推荐使用加密的 HTTPS 协议 运行 Weblate。将其允许后,可以在设置中设置 ENABLE_HTTPS

ENABLE_HTTPS = True

提示

你还会想要新建 HSTS,更多细节请参见 SSL/HTTPS

适当设置 SECURE_HSTS_SECONDS#

如果你的网站基于 SSL 上提供服务,那么必须考虑 settings.pySECURE_HSTS_SECONDS 的设置值,来允许 HTTP Strict Transport Security ( HTTP 脚本传输安全)。默认设置为 0,如下所示。

SECURE_HSTS_SECONDS = 0

如果设置为非 0 整数,那么在所有还不曾具有它的响应时,django.middleware.security.SecurityMiddleware 设置 HTTP Strict Transport Security 标头。

警告

不正确的设置这项会导致你的网站不可逆地(在一段时间内)崩溃。请首先阅读 HTTP Strict Transport Security 文档。

使用强力的数据库引擎#

  • 请使用 PostgreSQL 作为生产环境,更多信息请参见 Weblate 的数据库设置

  • 请在邻近的位置部署数据库服务器,否则网络性能或可靠性问题可能会破坏你的Weblate体验。

  • 检查数据库服务器性能或调整其配置,例如使用 PGTune.。

允许缓存#

如果可能,通过调整 CACHES 配置变量来使用来自 Django 的 Redis,例如:

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/0",
        # If redis is running on same host as Weblate, you might
        # want to use unix sockets instead:
        # 'LOCATION': 'unix:///var/run/redis/redis.sock?db=0',
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "PARSER_CLASS": "redis.connection.HiredisParser",
        },
    }
}

提示

在为缓存更改 Redis 设置的情况下,也会需要为 Celery 来调整,请参见 使用 Celery 的后台任务

头像缓存#

除了 Django 的缓存,Weblate 还执行头像缓存。推荐使用单独的、文件后端缓存来用于这个目的:

CACHES = {
    "default": {
        # Default caching backend setup, see above
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "unix:///var/run/redis/redis.sock?db=0",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "PARSER_CLASS": "redis.connection.HiredisParser",
        },
    },
    "avatar": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": os.path.join(DATA_DIR, "avatar-cache"),
        "TIMEOUT": 604800,
        "OPTIONS": {
            "MAX_ENTRIES": 1000,
        },
    },
}

配置电子邮件发送的设置#

Weblate 需要在几种情况下发送电子邮件,这些电子邮件应具有正确的发送者地址,请配置:setting:SERVER_EMAILDEFAULT_FROM_EMAIL,与你的环境匹配,例如:

SERVER_EMAIL = "admin@example.org"
DEFAULT_FROM_EMAIL = "weblate@example.org"

备注

为了禁止 Weblate 发送电子邮件,将 EMAIL_BACKEND 设置为 django.core.mail.backends.dummy.EmailBackend

这将禁止 所有 电子邮件的投递,包括注册或密码重置电子邮件。

允许主机设置#

Django 需要 ALLOWED_HOSTS 保存你的网站允许服务的域名列表,将其保持空置会屏蔽任何请求。

在没有配置来匹配 HTTP 服务器的情况下,会得到错误信息,如 Invalid HTTP_HOST header: '1.1.1.1'. You may need to add '1.1.1.1' to ALLOWED_HOSTS.

提示

在 Docker 容器上,这可以使用,为 WEBLATE_ALLOWED_HOSTS

Django 密钥#

SECRET_KEY 设置由 Django 使用来进行 cookies 签名,应该真正产生自己的值,而不是使用来自举例的设置的值。

可以使用与 Weblate 一起上市的 weblate-generate-secret-key,来产生新的密钥。

参见

SECRET_KEY

运行维护任务#

为了优化性能,在后台运行一些维护任务是个好方法。这由 使用 Celery 的后台任务 自动进行,并且包括下列任务:

  • 配置健康性的检查(每小时)。

  • 提交待处理的更改(每小时),请参见 惰性提交commit_pending

  • 更新部件警报(每天)。

  • 更新远程分支(每晚),请参见 AUTO_UPDATE

  • 翻译记忆库备份到 JSON (每天),请参见 dump_memory

  • 全文本和数据库维护任务(每天和每周任务),请参见 cleanuptrans

系统的地区与编码#

系统的地区应该设置为兼容 UTF-8 的。在多数 Linux 发行版中这是默认设置。在你的系统不能兼容的情况下,请将地区更改为 UTF-8 变体。

例如通过编辑 /etc/default/locale 并设置 LANG="C.UTF-8"

某些情况下,各个服务具有不同的区域设置配置。这在不同发行版和 web 服务器之间是不同的,所以请查阅你的 web 服务器包的文档。

Ubuntu系统下的Apache使用 /etc/apache2/envvars:

export LANG='en_US.UTF-8'
export LC_ALL='en_US.UTF-8'

CentOS系统下的Apache使用 /etc/sysconfig/httpd`(或 :file:/opt/rh/httpd24/root/etc/sysconfig/httpd`):

LANG='en_US.UTF-8'

使用定制的证书授权#

Weblate 在 HTTP 请求时验证 SSL 证书。在使用 定制的证书授权的情况下,这样定制的证书授权在默认 bundles 的中不被信任,你必须将其证书添加为可信任。

首选方法是在系统层面上进行,请查看你的发行版文档了解详情(例如在 debian 中,这可以通过将 CA 证书放置在 /usr/local/share/ca-certificates/,并运行 update-ca-certificates 来完成)。

一旦完成,系统工具就会信任证书,这包括 Git。

对于 Python 代码,需要配置请求来使用系统 CA bundle,而不是与它一起上市的那个。这可以通过将后面的模板放到 settings.py 来实现(路径是 Debian 特有的):

import os

os.environ["REQUESTS_CA_BUNDLE"] = "/etc/ssl/certs/ca-certificates.crt"

压缩客户端资源#

Weblate 带有一组 JavaScript 和 CSS 文件。由于性能的原因,在将其发送到客户端前最好进行压缩。在默认配置中,这通过耗费一点经常资源而在运行中完成。在大型安装中,推荐允许离线压缩模式。这需要在配置中完成,并且必须在每次 weblate 升级时触发压缩。

配置切换很简单,通过允许 django.conf.settings.COMPRESS_OFFLINE,并配置 django.conf.settings.COMPRESS_OFFLINE_CONTEXT (后者已经包括在示例的配置中):

COMPRESS_OFFLINE = True

在每个部署中,您需要压缩文件来匹配当前的版本:

weblate compress

提示

官方 Docker 镜像已经允许了这个特性。

运行服务器#

提示

如果你对下面描述的服务没有经验,你可以尝试 使用 Docker 安装

需要几个服务来运行Weblate,推荐的设置包括:

备注

这些服务之间由一些依赖项,例如当启动 Celery 或 uwsgi 进程时,缓存和数据库应该运行。

在多数情况下,需要在单一(虚拟)服务器上运行所有服务,但在您的安装是重载的情况下,可以将这些服务拆开。对此的唯一限制是 Celery 和 Wsgi 服务器需要访问 DATA_DIR

备注

WSGI 进程和 Celery 进程必须在同一用户下被执行,否则 DATA_DIR 中的文件将以混合的所有权来存储,导致运行问题。

还请参见 文件系统权限使用 Celery 的后台任务

运行 web 服务器#

运行 Weblate 与运行其他任何基于 Django 的程序没什么不同。Django通常作为 uWSGI 或 fcgi 执行(请参见下面不同 web 服务器的示例)。

为了检测的目的,您可以在 Django 中使用内建的 web 服务器:

weblate runserver

警告

不要使用在生产设置中这个服务器。它还没有通过安全审查或性能检测。请参见 Django 文档中的 runserver

提示

Django 内建服务只通过允许 DEBUG 来为静态文件提供服务,因为它只用于开发的目的。对于生产使用,请参见 NGINX 和 uWSGI 的配置示例Apache 的配置示例Apache 和 Gunicorn 的配置示例为静态文件提供服务 中的 WSGI 设置。

为静态文件提供服务#

Django 需要将其静态文件收集在一个单一文件夹中。为此,执行 weblate collectstatic --noinput。这会将静态文件复制到 STATIC_ROOT 设置指定的文件夹中(这默认为 CACHE_DIR`内的 ``static` 文件夹)。

推荐直接从你的 web 服务器为静态文件提供服务,对于后面的路径应该使用它:

/static/

给 Weblate 和管理界面提供静态文件(文件源由 :setting:`django:STATIC_ROOT`定义)。

/media/

用于上传用户媒体(例如截屏)。

/favicon.ico

应该重写,重写规则为 /static/favicon.ico 提供服务。

内容安全政策#

默认的 Weblate 配置允许 weblate.middleware.SecurityMiddleware 中间件,它设置与 HTTP 标头相关的安全,如 Content-Security-PolicyX-XSS-Protection。这些被默认新建,与 Weblate 及其配置一起工作,但这对你的环境需要定制化。

NGINX 和 uWSGI 的配置示例#

为了运行生产 web 服务器,使用与 Weblate 一起安装的 WSGI 封装(在虚拟 env 的情况下,它安装为 ~/weblate-env/lib/python3.9/site-packages/weblate/wsgi.py )。别忘了将 Python 的搜索路径同样设置为 您的虚拟 env (例如在 uWSGI 中使用 virtualenv = /home/user/weblate-env )。

后面的配置将 Weblate 作为 NGINX web 服务器下的 uWSGI 来运行。

NGINX 的配置(还作为 weblate/examples/weblate.nginx.conf 来获得):

#
# nginx configuration for Weblate
#
# You will want to change:
#
# - server_name
# - change /home/weblate/weblate-env to location where Weblate virtualenv is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match your Python version
# - change weblate user to match your Weblate user
#
server {
    listen 80;
    server_name weblate;
    # Not used
    root /var/www/html;

    location ~ ^/favicon.ico$ {
        # CACHE_DIR/static/favicon.ico
        alias /home/weblate/data/cache/static/favicon.ico;
        expires 30d;
    }

    location /static/ {
        # CACHE_DIR/static/
        alias /home/weblate/data/cache/static/;
        expires 30d;
    }

    location /media/ {
        # DATA_DIR/media/
        alias /home/weblate/data/media/;
        expires 30d;
    }

    location / {
        include uwsgi_params;
        # Needed for long running operations in admin interface
        uwsgi_read_timeout 3600;
        # Adjust based to uwsgi configuration:
        uwsgi_pass unix:///run/uwsgi/app/weblate/socket;
        # uwsgi_pass 127.0.0.1:8080;
    }
}

uWSGI 的配置(还作为 weblate/examples/weblate.uwsgi.ini 来获得):

#
# uWSGI configuration for Weblate
#
# You will want to change:
#
# - change /home/weblate/weblate-env to location where Weblate virtualenv is placed
# - change /home/weblate/data to match your DATA_DIR
# - change python3.12 to match your Python version
# - change weblate user to match your Weblate user
#
[uwsgi]
plugins       = python3
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/wsgi.py

# Add path to Weblate checkout if you did not install
# Weblate by pip
# python-path   = /path/to/weblate

# In case you're using virtualenv uncomment this:
virtualenv = /home/weblate/weblate-env

# Needed for OAuth/OpenID
buffer-size   = 8192

# Reload when consuming too much of memory
reload-on-rss = 250

# Increase number of workers for heavily loaded sites
workers       = 8

# Enable threads for Sentry error submission
enable-threads = true

# Child processes do not need file descriptors
close-on-exec = true

# Avoid default 0000 umask
umask = 0022

# Run as weblate user
uid = weblate
gid = weblate

# Enable harakiri mode (kill requests after some time)
# harakiri = 3600
# harakiri-verbose = true

# Enable uWSGI stats server
# stats = :1717
# stats-http = true

# Do not log some errors caused by client disconnects
ignore-sigpipe = true
ignore-write-errors = true
disable-write-exception = true

Apache 的配置示例#

推荐当 Weblate 使用 WSGI 时使用 prefork MPM。

后面的配置将 Weblate 作为 WSGI 来运行,您需要允许 ``mod_wsgi``(作为 weblate/examples/apache.conf 来获得):

#
# VirtualHost for Weblate
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate virtualenv is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match Python version mod-wsgi is compiled for
# - change weblate user to match your Weblate user
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # CACHE_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/cache/static/favicon.ico

    # CACHE_DIR/static/
    Alias /static/ /home/weblate/data/cache/static/
    <Directory /home/weblate/data/cache/static/>
        Require all granted
    </Directory>

    # DATA_DIR/media/
    Alias /media/ /home/weblate/data/media/
    <Directory /home/weblate/data/media/>
        Require all granted
    </Directory>

    # Path to your Weblate virtualenv
    WSGIDaemonProcess weblate python-home=/home/weblate/weblate-env user=weblate request-timeout=600
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias / /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/wsgi.py process-group=weblate
    WSGIPassAuthorization On

    <Directory /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/>
        <Files wsgi.py>
        Require all granted
        </Files>
    </Directory>

</VirtualHost>

备注

Weblate 需要 Python 3,所以请确认您运行 modwsgi 的 Python 3 变体。它通常作为独立的包来获得,例如 libapache2-mod-wsgi-py3

使用匹配的 Python 版本来安装 Weblate。

Apache 和 Gunicorn 的配置示例#

后面的配置在 Gunicorn 和 Apache 2.4 中运行 Weblate (作为 weblate/examples/apache.gunicorn.conf 获得):

#
# VirtualHost for Weblate using gunicorn on localhost:8000
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate virtualenv is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change weblate user to match your Weblate user
#
<VirtualHost *:443>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # CACHE_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/cache/static/favicon.ico

    # CACHE_DIR/static/
    Alias /static/ /home/weblate/data/cache/static/
    <Directory /home/weblate/data/cache/static/>
        Require all granted
    </Directory>

    # DATA_DIR/media/
    Alias /media/ /home/weblate/data/media/
    <Directory /home/weblate/data/media/>
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/https_cert.cert
    SSLCertificateKeyFile /etc/apache2/ssl/https_key.pem
    SSLProxyEngine On

    ProxyPass /favicon.ico !
    ProxyPass /static/ !
    ProxyPass /media/ !

    ProxyPass / http://localhost:8000/
    ProxyPassReverse / http://localhost:8000/
    ProxyPreserveHost On
</VirtualHost>

在路径下运行 Weblate#

推荐当 Weblate 使用 WSGI 时使用 prefork MPM。

为``/weblate`` 下的 Weblate 提供服务的 Apache 配置的示例。再次使用 mod_wsgi (还作为 weblate/examples/apache-path.conf 获得):

# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later

#
# VirtualHost for Weblate, running under /weblate path
#
# You will want to change:
#
# - ServerAdmin and ServerName
# - change /home/weblate/weblate-env to location where Weblate virtualenv is placed
# - change /home/weblate/data to match your DATA_DIR
# - change /home/weblate/data/cache to match your CACHE_DIR
# - change python3.12 to match Python version mod-wsgi is compiled for
# - change weblate user to match your Weblate user
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # CACHE_DIR/static/favicon.ico
    Alias /weblate/favicon.ico /home/weblate/data/cache/static/favicon.ico

    # CACHE_DIR/static/
    Alias /weblate/static/ /home/weblate/data/cache/static/
    <Directory /home/weblate/data/cache/static/>
        Require all granted
    </Directory>

    # DATA_DIR/media/
    Alias /weblate/media/ /home/weblate/data/media/
    <Directory /home/weblate/data/media/>
        Require all granted
    </Directory>

    # Path to your Weblate virtualenv
    WSGIDaemonProcess weblate python-home=/home/weblate/weblate-env user=weblate request-timeout=600
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias /weblate /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/wsgi.py process-group=weblate
    WSGIPassAuthorization On

    <Directory /home/weblate/weblate-env/lib/python3.12/site-packages/weblate/>
        <Files wsgi.py>
        Require all granted
        </Files>
    </Directory>

</VirtualHost>

此外,您必须调整 weblate/settings.py

URL_PREFIX = "/weblate"

使用 Celery 的后台任务#

Weblate使用Celery来执行常规和后台任务。你应该运行一个Celery服务来执行这些任务。例如,它负责处理以下操作(此列表并不完整):

使用 Redis 作为后端的典型安装看上去是这样的:

CELERY_TASK_ALWAYS_EAGER = False
CELERY_BROKER_URL = "redis://localhost:6379"
CELERY_RESULT_BACKEND = CELERY_BROKER_URL

您应该启动 Celery 工作进程来处理任务,并且定时任务,这可以直接在命令行完成(调试和开发时最有用):

./weblate/examples/celery start
./weblate/examples/celery stop

备注

Celery 进程和 WSGI 进程必须在同一用户下被执行,否则 DATA_DIR 中的文件将以混合的所有权来存储,导致运行问题。

还请参见 文件系统权限运行服务器

在WSGI中使用eager模式执行Celery任务#

备注

这将对web界面的性能产生严重影响,并会破坏依赖于常规触发器的功能(例如提交挂起的更改、摘要通知或备份)。

对于开发,你可能希望使用 eager configuration,它可以适当地处理所有任务:

CELERY_TASK_ALWAYS_EAGER = True
CELERY_BROKER_URL = "memory://"
CELERY_TASK_EAGER_PROPAGATES = True

运行 Celery 作为系统服务#

您更可能想要运行 Celery 作为守护进程,这由 Daemonization 来涵盖。对于使用 systemd 的最通常的 Linux 设置,您可以使用与下面列出的 examples 文件夹一起上市的示例文件。

Systemd 单元作为 /etc/systemd/system/celery-weblate.service 放置:

[Unit]
Description=Celery Service (Weblate)
After=network.target

[Service]
Type=forking
User=weblate
Group=weblate
EnvironmentFile=/etc/default/celery-weblate
WorkingDirectory=/home/weblate
RuntimeDirectory=celery
RuntimeDirectoryPreserve=restart
LogsDirectory=celery
ExecStart=/bin/sh -c '${CELERY_BIN} multi start ${CELERYD_NODES} \
  -A ${CELERY_APP} --pidfile=${CELERYD_PID_FILE} \
  --logfile=${CELERYD_LOG_FILE} --loglevel=${CELERYD_LOG_LEVEL} ${CELERYD_OPTS}'
ExecStop=/bin/sh -c '${CELERY_BIN} multi stopwait ${CELERYD_NODES} \
  --pidfile=${CELERYD_PID_FILE}'
ExecReload=/bin/sh -c '${CELERY_BIN} multi restart ${CELERYD_NODES} \
  -A ${CELERY_APP} --pidfile=${CELERYD_PID_FILE} \
  --logfile=${CELERYD_LOG_FILE} --loglevel=${CELERYD_LOG_LEVEL} ${CELERYD_OPTS}'

[Install]
WantedBy=multi-user.target

环境配置作为 /etc/default/celery-weblate 放置:

# Name of nodes to start
CELERYD_NODES="celery notify memory backup translate"

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/home/weblate/weblate-env/bin/celery"

# App instance to use
# comment out this line if you don't use an app
CELERY_APP="weblate.utils"

# Extra command-line arguments to the worker,
# increase concurrency if you get weblate.E019
CELERYD_OPTS="--beat:celery --queues:celery=celery --prefetch-multiplier:celery=4 \
    --queues:notify=notify --prefetch-multiplier:notify=10 \
    --queues:memory=memory --prefetch-multiplier:memory=10 \
    --queues:translate=translate --prefetch-multiplier:translate=4 \
    --concurrency:backup=1 --queues:backup=backup  --prefetch-multiplier:backup=2"

# Logging configuration
# - %n will be replaced with the first part of the nodename.
# - %I will be replaced with the current child process index
#   and is important when using the prefork pool to avoid race conditions.
CELERYD_PID_FILE="/run/celery/weblate-%n.pid"
CELERYD_LOG_FILE="/var/log/celery/weblate-%n%I.log"
CELERYD_LOG_LEVEL="INFO"

使用 logrotate 来旋转 Celery 记录的额外配置将被放置为 /etc/logrotate.d/celery:

# Copyright © Michal Čihař <michal@weblate.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later

/var/log/celery/*.log {
        weekly
        missingok
        rotate 12
        compress
        notifempty
}

使用 Celery beat 的周期性任务#

Weblate 带有内建的定时任务设置。然而您可以在 settings.py 中定义另外的任务,例如请参见 惰性提交

任务应该由 Celery beats 守护进程执行。在不能正常工作的情况下,它可能不会运行,或者其数据库崩溃。在这样的情况下检查 Celery 启动日志,来找出根本原因。

监测 Celery 状态#

你可以在 管理界面 中找到 Celery 任务队列的当前长度,或者你可以使用在命令中使用 celery_queues。如果队列太长,你也会在管理界面中得到配置错误。

警告

Celery 错误默认之存储在 Celery 日志中,并且用户不可见。在您想要了解故障概况的情况下,推荐配置 收集错误报告并监控性能

单进程 Celery 设置#

如果你的内存有限,你或许会想要减少 Weblate 进程数。使用以下命令可以在单进程中执行所有 Celery 任务:

celery --app=weblate.utils worker --beat --queues=celery,notify,memory,translate,backup --pool=solo

警告

这会对 Weblate 性能产生显著影响。

监测 Weblate#

Weblate 提供了 /healthz/ URL,可用于简单的健康检查,例如使用 Kubernetes。Docker 容器内置了使用此 URL 的健康检查。

为了检测Weblate的各项指标,你可以使用 GET /api/metrics/ API端点。

收集错误报告并监控性能#

与其他任何软件一样,Weblate 可能会失败。为了收集有用的故障状态,我们推荐使用第三方服务来收集此类信息。这在 Celery 任务失败的情况下尤其有用,否则将只会向日志报告错误,而您不会收到有关它们的通知。Weblate 支持以下服务:

Sentry#

Weblate 内置了对 Sentry 的支持。要使用它,只需在 settings.py 中设置 SENTRY_DSN

SENTRY_DSN = "https://id@your.sentry.example.com/"

Sentry 也可以监控 Weblate 性能,方法是收集已定义百分比操作的痕迹和画像。可以使用 SENTRY_TRACES_SAMPLE_RATE 和 :setting:`SENTRY_PROFILES_SAMPLE_RATE`进行配置。

Rollbar#

Weblate 具有对 Rollbar 的内置支持。要使用它,只需遵循 Rollbar notifier for Python 的说明即可。

简而言之,您需要调整 settings.py

# Add rollbar as last middleware:
MIDDLEWARE = [
    # … other middleware classes …
    "rollbar.contrib.django.middleware.RollbarNotifierMiddleware",
]

# Configure client access
ROLLBAR = {
    "access_token": "POST_SERVER_ITEM_ACCESS_TOKEN",
    "client_token": "POST_CLIENT_ITEM_ACCESS_TOKEN",
    "environment": "development" if DEBUG else "production",
    "branch": "main",
    "root": "/absolute/path/to/code/root",
}

其他所有内容都是自动集成的,您现在将同时收集服务器和客户端错误。

备注

错误日志记录还包括已正常处理但可能指示存在问题的异常,例如上传文件的解析失败。

将 Weblate 迁移到其他服务其中#

将 Weblate 迁移到其他服务器应该非常简单,然而它将数据存储在几个位置,您应该小心迁移。最佳的方式时停止 Weblate 再迁移。

迁移数据库#

根据你的数据库后端,你可能有几个选项来迁移数据库。最直接的方法是使用数据库原生工具,因它们通常最有效(如 mysqldumppg_dump)。如果你的数据库支持的话,你也可以使用复制。

参见

在数据库之间进行迁移的内容,见 从其它数据库迁移到 PostgreSQL

迁移版本控制系统仓库#

存储在 DATA_DIR 下的版本控制系统同样需要迁移。您可以简单地复制它们,或使用 rsync 来更有效地迁移。

其他注意事项#

不要忘记移动 Weblate 会使用的其他服务,如 Redis、Cron 任务或自定义的身份验证后端。