配置手册

安装 Weblate

根据你的设置和经验,为你选择适当的安装方法:

软件要求

操作系统

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

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

其他服务

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

Python 依赖性

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

最重要的依赖性:

Django

https://www.djangoproject.com/

Celery

https://docs.celeryproject.org/

Translate Toolkit (翻译工具包)

https://toolkit.translatehouse.org/

translation-finder

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

Python Social Auth

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

Django REST 框架

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

可选依赖性

后面的模块对 Weblate的一些特性是必须的。可以在 requirements-optional.txt 中找到。

Mercurial (optional for Mercurial repositories support)

https://www.mercurial-scm.org/

phply (optional for PHP 字符串)

https://github.com/viraptor/phply

tesserocr (optional for OCR in 字符串的可见语境)

https://github.com/sirfz/tesserocr

akismet (optional for 针对垃圾邮件的保护)

https://github.com/ubernostrum/akismet

ruamel.yaml (对 YAML files 是可选的)

https://pypi.org/project/ruamel.yaml/

Zeep (对 微软术语服务 是可选的)

https://docs.python-zeep.org/

aeidon (对 Subtitle files 是可选的)

https://pypi.org/project/aeidon/

fluent.syntax (optional for Fluent 格式)

https://projectfluent.org/

提示

When installing using pip, you can directly specify desired features when installing:

pip install "Weblate[PHP,Fluent]"

Or you can install Weblate will all optional features:

pip install "Weblate[all]"

Or you can install Weblate without any optional features:

pip install Weblate

数据库后端依赖性

Weblate 支持 PostgreSQL 、 MySQL 和 MariaDB 数据库,更多细节请参见 Weblate 的数据库设置 和后端文件。

其他系统要求

后面的依赖性必须安装在系统上:

Git

https://git-scm.com/

Pango 、 Cairo 和相关的头文件与 gir introspection 数据

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 及其数据(对截屏 OCR 是可选的)

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

licensee (当新建组件时可选用与删除许可)

https://github.com/licensee/licensee

构建时的依赖

为了构建一些 Python 依赖性 ,你可能需要安装其依赖库。这取决于你如何安装它们,因此请参考单独包的文档。如果你使用预编译 Wheels 并使用 pip 安装或使用分发包时,你不会需要那些。

Pango 和 Cairo

在 3.7 版更改.

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

验证发布签名

Weblate 的发布由发布开发者通过密码签发。当前是 Michal Čihař 。他的 PGP 密钥指纹是:

63CB 1DF1 EF12 CF2A C0EE 5A32 9C27 B313 42B7 511D

并且可以从 <https://keybase.io/nijel> 得到更多识别信息。

应该验证签名与下载的压缩档案匹配。这种方式可以确保你使用发布的相同编码。还应该核实签名的日期,确定下载了最新的版本。

每个压缩档案伴随 .asc 文件在一起,它包含了需要使用的 PGP 签名。一旦它们处于相同的文件夹内,就可以验证签名了:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Ne 3. března 2019, 16:43:15 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Can't check signature: public key not found

正如你所看到的,GPG抱怨它不知道公钥。此时应该执行以下步骤之一:

  • 使用 wkd 来下载密钥:

$ gpg --auto-key-locate wkd --locate-keys michal@cihar.com
pub   rsa4096 2009-06-17 [SC]
      63CB1DF1EF12CF2AC0EE5A329C27B31342B7511D
uid           [ultimate] Michal Čihař <michal@cihar.com>
uid           [ultimate] Michal Čihař <nijel@debian.org>
uid           [ultimate] [jpeg image of size 8848]
uid           [ultimate] Michal Čihař (Braiins) <michal.cihar@braiins.cz>
sub   rsa4096 2009-06-17 [E]
sub   rsa4096 2015-09-09 [S]
$ gpg --import wmxth3chu9jfxdxywj1skpmhsj311mzm
  • 从一个密钥服务器下载并导入密钥:

$ gpg --keyserver hkp://pgp.mit.edu --recv-keys 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: key 9C27B31342B7511D: "Michal Čihař <michal@cihar.com>" imported
gpg: Total number processed: 1
gpg:              unchanged: 1

这会将情况改善一点——在这点上可以验证给定密钥的签名是正确的,但仍然不能相信密钥中使用的名称:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Ne 3. března 2019, 16:43:15 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Good signature from "Michal Čihař <michal@cihar.com>" [ultimate]
gpg:                 aka "Michal Čihař <nijel@debian.org>" [ultimate]
gpg:                 aka "[jpeg image of size 8848]" [ultimate]
gpg:                 aka "Michal Čihař (Braiins) <michal.cihar@braiins.cz>" [ultimate]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 63CB 1DF1 EF12 CF2A C0EE  5A32 9C27 B313 42B7 511D

这里的问题是任何人可以以这个名称发布密钥。需要确定密钥实际由提到的人所有。GNU 隐私手册在 Validating other keys on your public keyring (‘在你的公共钥匙链上验证其它密钥’)章节涵盖了这个题目。最可靠的方法是与开发者的真人真实交流,并交换密钥指纹,然后还可以依赖于可信任的 Web 。这种方式你可以信任通过其他签名的密钥,而其他人必须接触开发者真人。

一旦信任了密钥,警告就不会发生:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: assuming signed data in 'Weblate-3.5.tar.xz'
gpg: Signature made Sun Mar  3 16:43:15 2019 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: Good signature from "Michal Čihař <michal@cihar.com>" [ultimate]
gpg:                 aka "Michal Čihař <nijel@debian.org>" [ultimate]
gpg:                 aka "[jpeg image of size 8848]" [ultimate]
gpg:                 aka "Michal Čihař (Braiins) <michal.cihar@braiins.cz>" [ultimate]

如果签名非法(压缩的档案被更改),那么会得到清晰的错误,而无论密钥是否可信:

$ gpg --verify Weblate-3.5.tar.xz.asc
gpg: Signature made Sun Mar  3 16:43:15 2019 CET
gpg:                using RSA key 87E673AF83F6C3A0C344C8C3F4AA229D4D58C245
gpg: BAD signature from "Michal Čihař <michal@cihar.com>" [ultimate]

文件系统权限

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

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

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

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

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

Weblate 的数据库设置

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

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 WITH SCHEMA weblate;

配置 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": "",
    }
}

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

MySQL 和 MariaDB

提示

一些 Weblate 特性使用 PostgreSQL 会执行得更好。这包括搜索与翻译记忆库,它们都使用了数据库中的全文本特性,而 PostgreSQL 的实施更胜一筹。

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

Weblate 需要至少 5.7.8 版的或至少 10.2.7 版的 MariaDB。

推荐 Weblate 使用后面的设置:

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

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

  • 设置隔离级别为 READ COMMITTED

  • SQL 模式应该设置为 STRICT_TRANS_TABLES

MySQL 8.x, MariaDB 10.5.x or newer have reasonable default configuration so that no server tweaking should be necessary and all what is needed can be configured on the client side.

下面是用于 8GB 内存服务器的 /:file:`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

HTTP 代理

Weblate 执行版本控制系统(VCS)命令,这些命令接受来自环境的代理配置。推荐在 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 错误的通知。

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

填满数据库

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

在想要非交互式地运行安装的情况下,可以使用 weblate migrate --noinput ,然后使用 createadmin 命令来建立管理用户。

一旦完成,你将可以在管理界面检查 Performance report ,它会提示你网站上潜在的非最优的配置。

生产设置

对于生产设置,可以进行后面的章节中描述的调整。最严格的设置将触发警告,如果超级用户登录的话,警告由顶部条的感叹标记来指示:

../_images/admin-wrench.png

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

weblate check --deploy

还可以复查来自 管理界面 的每个检查表。

参见

部署清单

禁止调试模式

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

DEBUG = False

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

参见

调整配置

是当地配置管理设置

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

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

参见

调整配置

设置正确的网站域名

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

在 4.2 版更改: 在 4.2 版本之前,替代使用了 Django 网站框架,请参见 “站点”框架

正确配置 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 严格传输安全 标头。

警告

不正确地设置这项会导致你的网站不可逆地(有时)崩溃。请首先阅读 HTTP 严格传输安全 文件。

使用强力的数据库引擎

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

  • Use adjacent location for running the database server, otherwise the networking performance or reliability might ruin your Weblate experience.

  • Check the database server performance or tweak its configuration, for example using 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/examples/generate-secret-key, 来产生新的密钥。

参见

SECRET_KEY

Home 目录

在 2.1 版更改: 这不再需要了, Weblate现在将所有数据存储在 DATA_DIR

给用户运行 Weblate 的主目录应该存在,并且可以被这个用户写入。如果想要使用 SSH 来访问私有仓库,这是特别重要的,但 Git 也会需要访问这个目录(依赖于你使用的 Git 版本)。

可以在 settings.py 中更改 Weblate 使用的目录,例如,将其设置到 Weblate 树下面的 configuration 目录中:

os.environ["HOME"] = os.path.join(BASE_DIR, "configuration")

注解

在 Linux 和其他类似 UNIX 系统上,到用户主目录的路径在 /etc/passwd 中确定。很多发布默认用户使用不可写入目录来提供 Web 内容服务(如 apachewww-datawwwrun )。

模板加载

对于 Django 推荐使用缓存模板的加载程序。它将已分析的模板装入,并避免对每个单独的请求多进行分析。可以使用后面的模板来配置它(这里 loaders 设置很重要):

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            os.path.join(BASE_DIR, "templates"),
        ],
        "OPTIONS": {
            "context_processors": [
                "django.contrib.auth.context_processors.auth",
                "django.template.context_processors.debug",
                "django.template.context_processors.i18n",
                "django.template.context_processors.request",
                "django.template.context_processors.csrf",
                "django.contrib.messages.context_processors.messages",
                "weblate.trans.context_processors.weblate_context",
            ],
            "loaders": [
                (
                    "django.template.loaders.cached.Loader",
                    [
                        "django.template.loaders.filesystem.Loader",
                        "django.template.loaders.app_directories.Loader",
                    ],
                ),
            ],
        },
    },
]

运行维护任务

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

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

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

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

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

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

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

在 3.2 版更改: 从 3.2 版本开始,执行这些任务的默认方式是使用 Celery ,并且 Weblate 已经具有一些适当的配置,请参见 使用 Celery 的后台任务

系统的地区与编码

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

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

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

Apache on Ubuntu uses /etc/apache2/envvars:

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

Apache on CentOS uses /etc/sysconfig/httpd (or /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 镜像已经允许了这个特性。

运行服务器

提示

In case you are not experienced with services described below, you might want to try 使用 Docker 安装.

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

注解

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

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

注解

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

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

运行 web 服务器

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

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

weblate runserver

警告

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

提示

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

为静态文件提供服务

在 2.4 版更改: 在 2.4 版本之前, Weblate 不能正常使用 Django 静态文件框架,并且设置更复杂。

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

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

/static/

为 Weblate 的静态文件和 管理界面(由 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.7/site-packages/weblate/wsgi.py )。别忘了将 Python 的搜索路径同样设置为 您的虚拟 env (例如在 uWSGI 中使用 virtualenv = /home/user/weblate-env )。

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

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

# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
server {
    listen 80;
    server_name weblate;
    # Not used
    root /var/www/html;

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

    location /static/ {
        # DATA_DIR/static/
        alias /home/weblate/data/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 来获得):

# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
[uwsgi]
plugins       = python3
master        = true
protocol      = uwsgi
socket        = 127.0.0.1:8080
wsgi-file     = /home/weblate/weblate-env/lib/python3.9/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
#
# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/static/favicon.ico

    # DATA_DIR/static/
    Alias /static/ /home/weblate/data/static/
    <Directory /home/weblate/data/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
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias / /home/weblate/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py process-group=weblate request-timeout=600
    WSGIPassAuthorization On

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

</VirtualHost>

注解

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

Apache 和 Gunicorn 的配置例子

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

#
# VirtualHost for Weblate using gunicorn on localhost:8000
#
# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
#
<VirtualHost *:443>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/favicon.ico
    Alias /favicon.ico /home/weblate/data/static/favicon.ico

    # DATA_DIR/static/
    Alias /static/ /home/weblate/data/static/
    <Directory /home/weblate/data/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

1.3 新版功能.

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

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

#
# VirtualHost for Weblate, running under /weblate path
#
# This example assumes Weblate is installed in virtualenv in /home/weblate/weblate-env
# and DATA_DIR is set to /home/weblate/data, please adjust paths to match your setup.
#
<VirtualHost *:80>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

    # DATA_DIR/static/favicon.ico
    Alias /weblate/favicon.ico /home/weblate/data/static/favicon.ico

    # DATA_DIR/static/
    Alias /weblate/static/ /home/weblate/data/static/
    <Directory /home/weblate/data/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
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

    WSGIScriptAlias /weblate /home/weblate/weblate-env/lib/python3.7/site-packages/weblate/wsgi.py process-group=weblate request-timeout=600
    WSGIPassAuthorization On

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

</VirtualHost>

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

URL_PREFIX = "/weblate"

使用 Celery 的后台任务

3.2 新版功能.

Weblate uses Celery to execute regular and background tasks. You are supposed to run a Celery service that will execute these. For example, it is responsible for handling following operations (this list is not complete):

A typical setup using Redis as a backend looks like this:

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

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

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

注解

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

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

Executing Celery tasks in the wsgi using eager mode

注解

This will have severe performance impact on the web interface, and will break features depending on regullar trigger (for example commiting pending changes, digest notifications, or backups).

For development, you might want to use eager configuration, which does process all tasks in place:

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 concurency 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:

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

使用 Celery beat 的周期性任务

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

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

监测 Celery 状态

可以使用 celery_queues 来查看当前 Celery 任务队列的长度。在队列太长的情况下,会在管理界面得到配置错误。

警告

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

监测 Weblate

Weblate 提供 /healthz/ URL 作为简单的健康检查来使用,例如使用 Kubernetes 。Docker 容器具有使用此 URL 的内置运行状况检查。

For monitoring metrics of Weblate you can use GET /api/metrics/ API endpoint.

收集错误报告

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

Sentry

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

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

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 )。如果您想要在不同的数据库之间迁移,唯一的选项恐怕是使用 Django 管理来转储并导入数据库:

# Export current data
weblate dumpdata > /tmp/weblate.dump
# Import dump
weblate loaddata /tmp/weblate.dump

迁移版本控制系统(VCS)仓库

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

其他注释

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