配置说明#

安装 Weblate#

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

软件要求#

操作系统#

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

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

其他服务#

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

Python 依赖项#

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

最重要的依赖项:

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/

可选依赖项#

以下模块是某些 Weblate 功能所必需的。你可以在 requirements-optional.txt 中找到所有这些模块。

Mercurial (可选的 Mercurial 仓库支持)

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

phply (可选的 PHP 字符串

https://github.com/viraptor/phply

tesserocr (可选的 字符串的可视化上下文 OCR)

https://github.com/sirfz/tesserocr

python-akismet (可选的 针对垃圾电子邮件的保护

https://github.com/Nekmo/python-akismet

ruamel.yaml (可选的 YAML 文件

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

Zeep (可选的 微软术语服务

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

aeidon (可选的 字幕文件

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

fluent.syntax (可选的 Fluent 格式

https://projectfluent.org/

提示

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

pip install "Weblate[PHP,Fluent]"

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

pip install "Weblate[all]"

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

pip install Weblate

数据库后端依赖项#

Weblate 支持 PostgreSQL、MySQL 和 MariaDB,更多细节请参见 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 及其数据(可选的截屏 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 隐私手册在 验证公共密钥环上的其他密钥 一章中介绍了这个主题。最可靠的方法是与开发者面对面交换密钥指纹,不过你也可以依靠信任网络。这样您就可以信任通过与开发者见过面的其他人的签名传递的密钥。

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

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

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

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

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

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

Weblate 的数据库设置#

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

PostgreSQL 12 and higher is supported.

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

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

MySQL 和 MariaDB#

警告

While MySQL and MariaDB support is still maintained in Weblate, our primary focus is PostgreSQL. It is recommended to use PostgreSQL for new installs, and to migrate existing installs to PostgreSQL, see 从其它数据库迁移到 PostgreSQL.

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

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

Weblate requires MySQL at least 8 or MariaDB at least 10.4.

推荐 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 执行版本控制系统(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

填满数据库#

After your configuration is ready, you can run weblate migrate to create the database structure. Now you should be able to create translation projects using the admin interface.

完成后,你还应该在管理界面查看 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 的数据库设置

  • 请在邻近的位置部署数据库服务器,否则网络性能或可靠性问题可能会破坏你的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 的后台任务 自动进行,并且包括后面的任务:

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

系统的地区与编码#

系统的地区应该设置为兼容 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 设置指定的文件夹中(这默认为 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.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 python3.9 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$ {
        # 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 来获得):

#
# 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.9 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.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
#
# 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 python3.9 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

    # 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 request-timeout=600
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

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

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

</VirtualHost>

备注

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

Use matching Python version to install 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 weblate user to match your Weblate user
#
<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#

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

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

#
# 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 python3.9 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

    # 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 request-timeout=600
    WSGIProcessGroup weblate
    WSGIApplicationGroup %{GLOBAL}

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

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

</VirtualHost>

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

URL_PREFIX = "/weblate"

使用 Celery 的后台任务#

在 3.2 版本加入.

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

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

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 中的文件将以混合的所有权来存储,导致运行问题。

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

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

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

使用 Celery beat 的周期性任务#

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

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

监测 Celery 状态#

You can find current length of the Celery task queues in the 管理界面 or you can use weblate celery_queues on the command-line. In case the queue will get too long, you will also get configuration error in the admin interface.

警告

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

监测 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/"

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

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

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

其他注意事项#

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