uv pip install --force-reinstall --no-binary :all: cffi
error: ‘xmlSecKeyDataFormatEngine’ undeclared (first use in this function); did you mean ‘xmlSecKeyDataFormat’?
这是 xmlsec 包的已知问题，请参阅 https://github.com/xmlsec/python-xmlsec/issues/314 。
lxml & xmlsec libxml2 library version mismatch
lxml 和 xmlsec 包必须基于同一个 libxml2 构建。您应该在本地构建它们以避免此问题：
uv pip install --force-reinstall --no-binary xmlsec --no-binary lxml lxml xmlsec
Git
https://git-scm.com/
Pango、Cairo 及相关的头文件和 GObject 内省数据
https://cairographics.org/, https://www.gtk.org/docs/architecture/pango, 见 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
构建时的依赖项¶
为了构建一些 Python 依赖项，你可能需要安装其依赖项。这取决于你如何安装它们，因此请查阅各个包的文档。如果你使用预构建的 Wheels 并使用 pip 安装或使用分发包时，则不需要那些依赖项。
Pango 和 Cairo¶
Weblate 使用 Pango 和 Cairo 来生成位图小挂件（请参见 构建翻译社区）并提供检查（请参见 管理字型）。要正确地安装 Python 绑定，需要首先安装系统库——Cairo 和 Pango 都是需要的，而它们又需要 GLib。所有这些都应该与开发文件和 GObject 内省数据一起安装。
在 Debian 和 Ubuntu 上安装
在 SUSE 和 openSUSE 上安装
在 Redhat、Fedora 和 CentOS 上安装
在 macOS 上安装
验证发布签名¶
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 13 及更高版本。推荐 PostgreSQL 15 及更高版本。
使用强力的数据库引擎
从其它数据库迁移到 PostgreSQL
数据库连接¶
默认配置中，每个 Weblate 今晨保持到数据库的持久性连接。持久性连接改善 Weblate 响应水平，但可能需要给数据服务器提供更多资源。更多信息请参考 CONN_MAX_AGE 和 持久连接。
Weblate 需要至少下列连接数：
Celery 进程的 \((4 \times \mathit{nCPUs}) + 2\)
WSGI workers 的 \(\mathit{nCPUs} + 1\)
这应用到 Docker 容器默认值及此文档中提供的示例配置，不过一旦你自定义 WSGI worker 数目或调整 Celery 并行数，相关数字就会变化。
考虑下列情况，数据库连接数的实际限制需要较高：
管理命令 也需要它们的连接。
如果进程被杀（比如被 OOM killer 干掉），可能造成现有连接被拦截，导致超时。
使用 Celery 的后台任务,
NGINX 和 uWSGI 的配置示例,
WEBLATE_WORKERS
PostgreSQL¶
PostgreSQL 通常是基于 Django 的网站的最好选择。它是实现 Django 数据库层而使用的参考数据库。
Weblate 使用三字母的扩展名，在某些情况下需要单独安装。查找 postgresql-contrib 或类似命名的包。
PostgreSQL 注意事项
创建 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;
        # Database user
        "USER": "weblate",
        # Configures name of the PostgreSQL role to alter during the database migration
        # "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)。已知这会在 PostgreSQL 的 Azure 数据库发生，但并不仅限于这种环境。请设置 ALTER_ROLE 来更改 Weblate 应在数据库迁移期间改动的角色名。
数据库连接
配置电子邮件发件箱¶
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 的电子邮件
Configuring outgoing e-mail in Docker container
在反向代理之后运行¶
Weblate 中的几个功能依赖于传递给 Weblate 的正确 HTTP 标头。使用反向代理时，请确保所需信息被正确传递。
要调试该配置，可以看一看 性能报告 中的 HTTP environment。
客户端 IP 地址
频次限制 或 审计日志 需要这个。
Weblate 从 WGSI 处理程序设置的 REMOTE_ADDR 解析 IP 地址。这可能是空的（当对 WGSI 使用 socket 时）或者包括反向代理地址，因此 Weblate 需要带客户端 IP 地址的附加 HTTP 标头。
启用 IP_BEHIND_REVERSE_PROXY 对多数通常配置应该够了，但你可能也需要调整 IP_PROXY_HEADER 和 IP_PROXY_OFFSET（使用 Docker 容器内的 WEBLATE_IP_PROXY_HEADER 和 WEBLATE_IP_PROXY_OFFSET）。
此配置默认无法启用，因其会在没有正确配置反向代理的安装上允许 IP 地址伪造。
服务器主机名
Host 标头应该与 SITE_DOMAIN 中的内容一致。在反向代理中可能需要其他配置（例如，在 Apache 使用 ProxyPreserveHost On，或在 nginx 中使用 proxy_set_header Host $host;）。
CSRF 验证失败错误常由 Host 标头和配置的 SITE_DOMAIN 不匹配所导致。
客户端协议
未传递正确的协议可能导致 Weblate 最后陷入试图升级客户端到 HTTPS 的重定向循环中。确保反向代理正确地将它暴露为 X-Forwarded-Proto。
然后需要在 SECURE_PROXY_SSL_HEADER (settings.py) 或 WEBLATE_SECURE_PROXY_SSL_HEADER (Docker 环境) 中配置这个标头。
标头值在配置中区分大小写，因此 WEBLATE_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https 和 WEBLATE_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,HTTPS 不可互换。
如果浏览器显示“太多重定向”错误，最有可能的原因是实际协议(HTTPS) 和 Weblate 观察到的协议不匹配。
在 5.13 版本发生变更: 默认配置中协议代理标头由 gunicorn 自动处理，但其他 WSGI 服务器有更安全的配置并明确要求设置这个。
自 Weblate 5.13 起，Docker 容器使用 granian，它现在要求明确配置 WEBLATE_SECURE_PROXY_SSL_HEADER。
配置如何存储会话。在保持默认的数据库后端引擎的情况下，应该安排 weblate clearsessions 从数据库中删除旧的会话。
如果使用 Valkey 或 Redis 作为缓存（请参见 配置缓存），推荐也使用它作为会话：
SESSION_ENGINE = "django.contrib.sessions.backends.cache"
配置会话引擎
SESSION_ENGINE
DATABASES
连接到数据库服务器，请查阅 Django 的文档了解详情。
Weblate 的数据库设置
DATABASES
DEBUG
对于任何生产服务器禁止这项。允许调试模式时，Django 会在出错的情况下向用户显示回溯信息，当禁止时，错误将每封电子邮件发送到 ADMINS（请参见上面）。
调试模式还使 Weblate 变慢，因为在这种情况下 Django 内部存储了非常多的信息。
DEBUG
禁止调试模式
DEFAULT_FROM_EMAIL
用于发送电子邮件的电子邮件发件人地址，例如注册电子邮箱。
DEFAULT_FROM_EMAIL
SECRET_KEY
Django 使用的密钥，用于在 cookie 中登录一些信息，更多信息请参见 Django 密钥。
SECRET_KEY
SERVER_EMAIL
用作向管理员发送电子邮件的发送者地址的电子邮箱，例如通知失败的合并。
SERVER_EMAIL
填满数据库¶
在配置准备好之后，可以运行 migrate 来建立数据库结构。现在你将能够使用管理界面建立翻译项目。
完成后，你还应该在管理界面查看 Performance report，它会提示你站点上可能存在的非最佳配置。
对于生产设置，你应该进行以下部分中所述的调整。最关键的设置将触发警告：如果以超级用户身份登录，则会在顶部栏中显示一个叹号：
同样也推荐查看由 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
SITE_DOMAIN
WEBLATE_SITE_DOMAIN
ENABLE_HTTPS
适当设置 SECURE_HSTS_SECONDS¶
如果你的网站基于 SSL 上提供服务，那么必须考虑 settings.py 中 SECURE_HSTS_SECONDS 的设置值，来允许 HTTP Strict Transport Security（HTTP 脚本传输安全）。默认设置为 0，如下所示。
SECURE_HSTS_SECONDS = 0
如果设置为非 0 整数，那么在所有还不曾具有它的响应时，django.middleware.security.SecurityMiddleware 设置 HTTP 严格传输安全 标头。
不正确的设置这项会导致你的网站不可逆地（在一段时间内）崩溃。请首先阅读 HTTP 严格传输安全 文档。
使用强力的数据库引擎¶
请使用 PostgreSQL 作为生产环境，更多信息请参见 Weblate 的数据库设置。
请在邻近的位置部署数据库服务器，否则网络性能或可靠性问题可能会破坏你的Weblate体验。
检查数据库服务器性能或调整其配置，例如使用 PGTune。
Weblate 的数据库设置
从其它数据库迁移到 PostgreSQL




    

    "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",
如更改缓存设置，可能也需要为 Celery 调整它们，请参见 使用 Celery 的后台任务。
Django 缓存框架
    "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,
ENABLE_AVATARS
AVATAR_URL_PREFIX
Django 缓存框架
配置电子邮件发送的设置¶
Weblate 需要在几种情况下发送电子邮件，这些电子邮件应具有正确的发送者地址，请配置 SERVER_EMAIL 和 DEFAULT_FROM_EMAIL 来匹配你的环境，例如：
SERVER_EMAIL = "admin@example.org"
DEFAULT_FROM_EMAIL = "weblate@example.org"
为了禁止 Weblate 发送电子邮件，将 EMAIL_BACKEND 设置为 django.core.mail.backends.dummy.EmailBackend。
这将禁止 所有 电子邮件的投递，包括注册或密码重置电子邮件。
配置电子邮件发件箱
EMAIL_BACKEND
DEFAULT_FROM_EMAIL
SERVER_EMAIL
允许主机设置¶
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。
ALLOWED_HOSTS
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（或 /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 来完成）。
Weblate 容器不将它包括在搜索路径内，你需要指定完整路径来执行它。比如：
docker compose exec -u root weblate /usr/sbin/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 镜像已经允许了这个特性。
Common Deployment Scenarios
为静态文件提供服务
缓存服务器（请参见 配置缓存）
用于静态文件和终结 SSL 的前端 web 服务器（请参见 为静态文件提供服务）
用于动态内容的 WSGI 服务器（请参见 NGINX 和 uWSGI 的配置示例）
用于执行后台任务的 Celery（请参见 使用 Celery 的后台任务）
这些服务之间由一些依赖项，例如当启动 Celery 或 uwsgi 进程时，缓存和数据库应该运行。
在多数情况下，需要在单一（虚拟）服务器上运行所有服务，但在您的安装是重载的情况下，可以将这些服务拆开。对此的唯一限制是 Celery 和 Wsgi 服务器需要访问 DATA_DIR。
WSGI 进程和 Celery 进程必须在同一用户下被执行，否则 DATA_DIR 中的文件将以混合的所有权来存储，导致运行问题。
还请参见 文件系统权限 和 使用 Celery 的后台任务。
运行 web 服务器¶
运行 Weblate 与运行其他任何基于 Django 的程序没什么不同。Django通常作为 WSGI 或 fcgi 执行（请参见下面不同 web 服务器的示例）。
为了检测的目的，您可以在 Django 中使用内建的 web 服务器：
weblate runserver
不要使用在生产设置中这个服务器。它还没有通过安全审查或性能检测。请参见 Django 文档中的 runserver。
Django 内建服务只通过允许 DEBUG 来为静态文件提供服务，因为它只用于开发的目的。对于生产使用，请见 WGSI 设置:
NGINX 和 Granian 的配置示例
NGINX 和 Gunicorn 的配置示例
NGINX 和 uWSGI 的配置示例
Apache 的配置示例
Apache 和 Gunicorn 的配置示例
为静态文件提供服务
在 5.15.2 版本发生变更: /media/ 不再用于提供截屏。
Django 需要将其静态文件收集在一个单一文件夹中。为此，执行 weblate collectstatic --noinput。这会将静态文件复制到 STATIC_ROOT 设置指定的文件夹中（这默认为 CACHE_DIR 内的 static 文件夹）。
推荐直接从你的 web 服务器为静态文件提供服务，对于后面的路径应该使用它：
/static/
给 Weblate 和管理界面提供静态文件（文件源由 STATIC_ROOT 定义）。
/favicon.ico
应该重写，重写规则为 /static/favicon.ico 提供服务。
NGINX 和 Granian 的配置示例
NGINX 和 Gunicorn 的配置示例
NGINX 和 uWSGI 的配置示例




    

Apache 的配置示例
Apache 和 Gunicorn 的配置示例
压缩客户端资源
如何部署 Django
如何部署静态文件
内容安全政策¶
默认的 Weblate 配置允许 weblate.middleware.SecurityMiddleware 中间件，它设置与 HTTP 标头相关的安全，如 Content-Security-Policy 或 X-XSS-Protection。这些被默认新建，与 Weblate 及其配置一起工作，但这对你的环境需要定制化。
CSP_SCRIPT_SRC
CSP_IMG_SRC
CSP_CONNECT_SRC
CSP_STYLE_SRC
CSP_FONT_SRC
CSP_FORM_SRC
# - server_name
# - change /home/weblate/weblate-env to location where Weblate Python environment 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 / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_pass http://127.0.0.1:8888;
        proxy_read_timeout 3600;
NGINX 和 Gunicorn 的配置示例¶
下列配置在 NGINX web服务器下使用 Gunicorn 运行 Weblate (同样作为 weblate/examples/weblate.nginx.gunicorn.conf 文件可用)：
# nginx configuration for Weblate
# You will want to change:
# - server_name
# - change /home/weblate/weblate-env to location where Weblate Python environment 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 / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_pass http://unix:/run/gunicorn.sock;
        proxy_read_timeout 3600;
启动 Gunicorn 的配置示例
如何使用 Gunicorn 托管 Django
NGINX 和 uWSGI 的配置示例¶
To run production webserver, use the WSGI wrapper installed with Weblate (when
using a Python environment it is installed as
~/weblate-env/lib/python3.14/site-packages/weblate/wsgi.py). Don't
forget to set the Python search path to your Python environment as well (for
example using virtualenv = /home/user/weblate-env in uWSGI).
后面的配置将 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 Python environment 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 / {
        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 Python environment 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
# Path to the Python environment
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
如何用 uWSGI 托管 Django
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 Python environment 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>
    # Path to your Weblate Python environment
    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 和 mod_wsgi 托管 Django
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 Python environment 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>
    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/https_cert.cert
    SSLCertificateKeyFile /etc/apache2/ssl/https_key.pem
    SSLProxyEngine On
    ProxyPass /favicon.ico !
    ProxyPass /static/ !
    ProxyPass / http://localhost:8000/
    ProxyPassReverse / http://localhost:8000/
    ProxyPreserveHost On
</VirtualHost>
启动 Gunicorn 的配置示例
如何使用 Gunicorn 托管 Django
启动 Granian 的配置示例¶
Weblate 有 wsgi 可选依赖（见 Python 依赖项），此依赖会安装运行 Granian 所需的一切。安装 Weblate 时，你可以将它指定为：
uv pip install Weblate[all,wsgi]
安装了 Granian 后你可以运行它。这通常在系统层级完成。下列示例显示通过 systemd 的启动：
/etc/systemd/system/granian.service¶
[Unit]
Description=granian daemon
After=network.target
[Service]
User=weblate
Group=weblate
WorkingDirectory=/home/weblate/weblate-env/
Environment="DJANGO_SETTINGS_MODULE=weblate.settings"
RuntimeDirectory=granian
ExecStart=/home/weblate/weblate-env/bin/granian \
    --no-ws \
    --workers-max-rss 350 \
    --interface wsgi \
    --workers 2 \
    --backpressure 16 \
    --runtime-threads 8 \
    --runtime-mode mt \
    --port 8888 \
    weblate.wsgi:application
[Install]
WantedBy=multi-user.target
一旦安装了 Gunicorn，你可以运行它。这通常在系统层级完成。下列示例显示通过 systemd 的启动：
/etc/systemd/system/gunicorn.socket¶
[Unit]
Description=gunicorn socket
[Socket]
ListenStream=/run/gunicorn.sock
[Install]
WantedBy=sockets.target
Group=weblate
WorkingDirectory=/home/weblate/weblate-env/
Environment="DJANGO_SETTINGS_MODULE=weblate.settings"
ExecStart=/home/weblate/weblate-env/bin/gunicorn \
    --preload \
    --timeout 3600 \
    --graceful-timeout 3600 \
    --worker-class=gthread \
    --workers=2 \
    --threads=16 \
    --bind unix:/run/gunicorn.sock \
    weblate.wsgi:application
[Install]
WantedBy=multi-user.target
在路径下运行 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 Python environment 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>
    # Path to your Weblate Python environment
    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"
Weblate使用Celery来执行常规和后台任务。你应该运行一个Celery服务来执行这些任务。例如，它负责处理以下操作（此列表并不完整）：
接收来自外部服务的webhooks（请见 通知钩子）。
运行定期的维护任务，如备份、清理、日常附加组件或更新（请见 备份和移动 Weblate, BACKGROUND_TASKS, 附加组件）。
运行 自动翻译。
发送摘要通知。
从 WSGI 进程中卸载高负载操作。
提交待处理更改（参见 惰性提交）。
使用 Valkey 或 Redis 作为后端的典型安装看上去是这样的：
CELERY_TASK_ALWAYS_EAGER = False
CELERY_BROKER_URL = "redis://localhost:6379"
CELERY_RESULT_BACKEND = CELERY_BROKER_URL
Redis broker configuration in Celery
您应该启动 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. You might need to customize
# concurrency depending on the available resources and Weblate usage. Increase
# the concurrency if you get weblate.E019 error, decrease it if you are on a
# low-resource system.
CELERYD_OPTS="--beat:celery --queues:celery=celery --concurrency:celery=2 --prefetch-multiplier:celery=4 \
    --queues:notify=notify --concurrency:notify=2 --prefetch-multiplier:notify=10 \
    --queues:memory=memory --concurrency:memory=2 --prefetch-multiplier:memory=10 \
    --queues:translate=translate --concurrency:translate=4 --prefetch-multiplier:translate=4 \
    --queues:backup=backup  --concurrency:backup=1 --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 状态¶
你可以在 管理界面 中找到 Celery 任务队列的当前长度，或者你可以使用在命令中使用 celery_queues。如果队列太长，你也会在管理界面中得到配置错误。
Celery 错误默认之存储在 Celery 日志中，并且用户不可见。在您想要了解故障概况的情况下，推荐配置 收集错误报告并监控性能。
监测 Weblate
如何检查 Weblate 是否被正确地设置？
Configuration and defaults
Workers Guide
Daemonization
Monitoring and Management Guide
后台任务间隔
celery_queues
单进程 Celery 设置¶
如果你的内存有限，你或许会想要减少 Weblate 进程数。使用以下命令可以在单进程中执行所有 Celery 任务：
celery --app=weblate.utils worker --beat --queues=celery,notify,memory,translate,backup --pool=solo
通过设置 CELERY_SINGLE_PROCESS，可使用 Docker 的安装配置为使用单进程 Celery 设置。
这会对 Weblate 性能产生显著影响。
监测 Weblate¶
Weblate 提供了 /healthz/ URL，可用于简单的健康检查，例如使用 Kubernetes。Docker 容器内置了使用此 URL 的健康检查。
为了检测Weblate的各项指标，你可以使用 GET /api/metrics/ API端点。
如何检查 Weblate 是否被正确地设置？
监测 Celery 状态
Weblate 的 Munin 插件
收集错误报告并监控性能¶
与其他任何软件一样，Weblate 可能会失败。为了收集有用的故障状态，我们推荐使用第三方服务来收集此类信息。这在 Celery 任务失败的情况下尤其有用，否则将只会向日志报告错误，而您不会收到有关它们的通知。Weblate 支持以下服务：
电子邮件地址¶
默认的 Weblate 配置指示 Django 通过 django.utils.log.AdminEmailHandler 在遇到服务器错误时发送电子邮件。这是最省事的设置，但应该出于隐私原因考虑其他选项，因为错误邮件可能包含敏感数据。关于此内容的更多信息，可阅读 安全性考虑。
要禁用此行为，从 Weblate 设置中的 LOGGING 删除 mail_admins，或在 Docker 环境中禁用 WEBLATE_ADMIN_NOTIFY_ERROR。
Sentry¶
Weblate 内置了对 Sentry 的支持。要使用它，只需在 settings.py 中设置 SENTRY_DSN：
SENTRY_DSN = "https://id@your.sentry.example.com/"
Sentry 也可以监控 Weblate 性能，方法是收集已定义百分比操作的痕迹和画像。可以使用 SENTRY_TRACES_SAMPLE_RATE 和 SENTRY_PROFILES_SAMPLE_RATE 进行配置。
Sentry 性能监控
Sentry Profiling
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",
    "environment": "development" if DEBUG else "production",
    "branch": "main",
    "root": "/absolute/path/to/code/root",
其他所有内容都是自动集成的，您现在将同时收集服务器和客户端错误。
错误日志记录还包括已正常处理但可能指示存在问题的异常，例如上传文件的解析失败。
Graylog 日志管理¶
Added in version 5.9.
Weblate 可以被配置为使用 GELF TCP 协议记录日志。这是为 Graylog 集成开发的，但可被用于任何合规的日志记录平台。
配置的样本文件包含在 配置的示例 中；对于 Docker，可使用 WEBLATE_LOG_GELF_HOST 配置。
将 Weblate 迁移到其他服务其中¶
将 Weblate 迁移到其他服务器应该非常简单，然而它将数据存储在几个位置，您应该小心迁移。最佳的方式时停止 Weblate 再迁移。
迁移数据库¶
The most straightforward approach is to use database native tools, as they are
usually the most effective (e.g. pg_dump). Alternatively you can use
replication if your database supports it.
在数据库之间进行迁移的内容，见 从其它数据库迁移到 PostgreSQL。
迁移版本控制系统仓库¶
存储在 DATA_DIR 下的版本控制系统同样需要迁移。您可以简单地复制它们，或使用 rsync 来更有效地迁移。
其他注意事项¶
不要忘记移动 Weblate 可能一直在使用的其他服务，如 Valkey、Redis、Cron 任务或自定义的身份认证后端。