配置手冊

安裝 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.celeryq.dev/

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 (可選用支援 Mercurial

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

phply (可選用支援 PHP 字串

https://github.com/viraptor/phply

tesserocr (可選用 字串的可見語境 OCR)

https://github.com/sirfz/tesserocr

akismet (可選用 針對垃圾郵件的保護

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

ruamel.yaml (可選用 YAML files

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

Zeep (可選用 ms-terminology

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

aeidon (可選用 Subtitle files

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

ruamel.yaml (可選用 YAML files

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 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 來提供位圖 widget(請參參見 推動翻譯 )並提供檢查(請參見 管理字型 )。為了適當地安裝 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

The problem here is that anybody could issue the key with this name. You need to ensure that the key is actually owned by the mentioned person. The GNU Privacy Handbook covers this topic in the chapter Validating other keys on your public keyring. The most reliable method is to meet the developer in person and exchange key fingerprints, however you can also rely on the web of trust. This way you can trust the key transitively through signatures of others, who have met the developer in person.

一旦信任了密鑰,警告就不會發生:

$ 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 自己運行的相同用戶來運行,否則一些文件的權限會是錯誤的。

In the Docker container, all files in the /app/data volume have to be owned by the weblate user inside the container (UID 1000).

Weblate 的數據庫設置

推薦使用 PostgreSQL 數據庫服務器來運行 Weblate。

PostgreSQL

PostgreSQL 通常是基於 Django 的網站的最好選擇。它是實現 Django 數據庫層而使用的參考數據庫。

備註

Weblate 使用三字母的擴展名,在某些情況下需要單獨安裝。查找 postgresql-contrib 或類似命名的包。

也參考

PostgreSQL notes

建立 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;
CREATE EXTENSION IF NOT EXISTS btree_gin 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 and MariaDB

提示

一些 Weblate 特性使用 PostgreSQL 會執行得更好。這包括搜索與翻譯記憶庫,它們都使用了數據庫中的全文本特性,而 PostgreSQL 的實施更勝一籌。

Weblate 還可以使用 MySQL 或 MariaDB,使用與兩個數據庫相關的 Django 而導致的警告,請參見 MySQL notesMariaDB notes。由於這些限制,我們建議對新安裝使用 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或較新具有合理的預設配置,以便不需要使用服務器調整,並且可以在客戶端配置所有所需的服務器。

下面是用於 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 可能會有幫助。

Configuring Weblate to use 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;

其他配置

Configuring outgoing e-mail

Weblate 在各種情況下會發出電子郵件——用於激活賬戶,以及用戶配置的各種通知。對於這些需要訪問 SMTP 服務器。

郵件服務器使用這些設置進行配置: EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, EMAIL_USE_SSL, django: EMAIL_HOST_USER and EMAIL_PORT。從名稱就可以大概知道它們的含義,但是你可以在Django 文檔中找到更多信息。

提示

在得到有關不支持的認證的情況下(例如 SMTP AUTH extension not supported by server),這最可能因為使用不安全的鏈接並且服務器拒絕以這種方式認證而導致。在這種情況下嘗試啟動 EMAIL_USE_TLS

也參考

:ref:“調試郵件”,:ref:“在Docker容器中配置傳出電子郵件<docker-mail>`

在反向代理後面運行

Weblate 的幾個特性依賴於能夠得到客戶端 IP 地址。這包括 頻次限制針對垃圾郵件的保護稽核記錄

在預設設置中, Weblate 從 WSGI 句柄設置的 REMOTE_ADDR 中解析 IP 地址。

在運行反向代理的情況下,這個字段很可能包含其地址。需要配置 Weblate 來信任附加的 HTTP 標頭,並從中解析 IP 地址。這不能預設允許,因為在不使用反向代理的安裝時,這會允許 IP 地址欺騙。允許 IP_BEHIND_REVERSE_PROXY 對多數常見設置就足夠了,但你還必須調整 IP_PROXY_HEADERIP_PROXY_OFFSET

Another thing to take care of is the Host header. It should match to whatever is configured as SITE_DOMAIN. Additional configuration might be needed in your reverse proxy (for example use ProxyPreserveHost On for Apache or proxy_set_header Host $host; with nginx).

也參考

:ref:Ref:“垃圾郵件保護”,:ref:“速率限制”,:ref:“審計日誌”,:“IP_BEHIND_REVERSE_PROXY`”:django:secure_proxy_ssl_header

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

用於發送電子郵件的電子郵件發件人地址,例如註冊電子郵箱。

也參考

DEFAULT_FROM_EMAIL

SECRET_KEY

金鑰會被 Django 簽署相同資訊在瀏覽器 cookies 中,參閱 Django secret key 瞭解更多資訊。

也參考

SECRET_KEY

SERVER_EMAIL

用作向管理員發送電子郵件的發送者地址的郵箱,例如通知失敗的合併。

也參考

SERVER_EMAIL

填滿數據庫

在配置準備好之後,可以運行 weblate migrate 來建立數據庫結構。現在你將能夠使用管理界面建立翻譯項目。

在想要非交互式地運行安裝的情況下,可以使用 weblate migrate --noinput,然後使用 createadmin 命令來建立管理用戶。

一旦完成,你將可以在管理界面檢查 Performance report,它會提示你網站上潛在的非最優的配置。

生產設置

對於生產設置,可以進行後面的章節中描述的調整。最嚴格的設置將觸發警告,如果超級用戶登錄的話,警告由頂部條的感嘆標記來指示:

../_images/admin-wrench.png

同樣也推薦查看由 Django 觸發的檢查(儘管可能不需要修復所有的檢查):

weblate check --deploy

還可以復查來自 管理介面 的每個檢查表。

Disable debug mode

禁止 Django 的調試模式( DEBUG ):

DEBUG = False

在調試模式打開時,Django 存儲所有執行的查詢,並將錯誤的回溯顯示給用戶,這在生產設置中是不需要的。

也參考

調整配置

Properly configure admins

將正確的管理地址設置到 ADMINS 設置中,來確定服務器出現一些故障時誰接收電子郵件,例如:

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

也參考

調整配置

設置正確的網站域名

在管理界面調整網站名稱和域名,否則 RSS 中的鏈接或註冊電子郵件地址將不工作。這使用 SITE_DOMAIN 來配置,它應該包含網站域名。

在 4.2 版本變更: 在 4.2 版本之前,替代使用了 Django 網站框架,請參見 The “sites” framework

也參考

:參考:ref:“生產 - 主機”,:ref:“生產-SSL`:設置:Site_Domain,:envvar:weblate_site_domain,:設置:enable_https

Correctly configure HTTPS

強烈推薦使用加密的 HTTPS 協議 運行 Weblate。將其允許後,可以在設置中設置 ENABLE_HTTPS

ENABLE_HTTPS = True

提示

你還會想要新建 HSTS,更多細節請參見 SSL/HTTPS

Set properly 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 的數據庫設置

  • 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,
        },
    },
}

也參考

:設置:enabent_avatars,:設置:avatar_url_prefixAvatars,:ref:spections-cache`,django:主題/緩存

Configure e-mail sending

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

這將禁止 所有 電子郵件的投遞,包括註冊或密碼重置電子郵件。

也參考

:ref:“配置”,:ref:“外郵件”,:STD:設置:Django:Email_Backend,:std:設置:django:default_mail,:std:設置:django:server_email

Allowed hosts setup

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

SECRET_KEY 設置由 Django 使用來進行 cookies 簽名,應該真正產生自己的值,而不是使用來自舉例的設置的值。

可以使用與 Weblate 一起上市的 weblate-generate-secret-key, 來產生新的密鑰。

也參考

SECRET_KEY

Running maintenance tasks

為了優化性能,在後台運行一些維護任務是個好方法。現在這由 使用 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"

In some cases the individual services have separate configuration for locales. This varies between distribution and web servers, so check documentation of your web server packages for that.

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 證書放置在:file:/usr/local/share/ca-certificates/,並運行:command:update-ca-certificates 來完成)。

一旦完成,系統工具就會信任證書,這包括 Git。

對於 Python 代碼,需要配置請求來使用系統 CA bundle,而不是與它一起上市的那個。這可以通過將後面的模板放到 settings.py 來實現(路徑是 Debian 特有的):

import os

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

Compressing client assets

Weblate 帶有一組 JavaScript 和 CSS 文件。由於性能的原因,在將其發送到客戶端前最好進行壓縮。在預設配置中,這通過耗費一點經常資源而在運行中完成。在大型安裝中,推薦允許離線壓縮模式。這需要在配置中完成,並且必須在每次 weblate 升級時觸發壓縮。

配置切換很簡單,通過允許 django.conf.settings.COMPRESS_OFFLINE,並配置 django.conf.settings.COMPRESS_OFFLINE_CONTEXT (後者已經包括在例子的配置中):

COMPRESS_OFFLINE = True

在每個部署中,您需要壓縮文件來匹配當前的版本:

weblate compress

提示

官方 Docker 鏡像已經允許了這個特性。

運行服務器

提示

如果您沒有在下面描述的服務經歷,您可能需要嘗試:doc:安裝/ docker

需要幾個服務來運行Weblate,推薦的設置包括:

備註

這些服務之間由一些依賴性,例如當啟動 Celery 或 uwsgi 進程時,緩存和數據庫應該運行。

在多數情況下,需要在單一(虛擬)服務器上運行所有服務,但在您的安裝是重載的情況下,可以將這些服務拆開。對此的唯一限制是 Celery 和 Wsgi 服務器需要訪問 DATA_DIR

備註

WSGI 進程和 Celery 進程必須在同一用戶下被執行,否則 DATA_DIR 中的文件將以混合的所有權來存儲,導致運行問題。

還請參見 文件系統權限使用 Celery 的後台任務

Running web server

運行 Weblate 與運行其他任何基於 Django 的程序沒什麼不同。 Django通常作為 uWSGI 或 fcgi 執行(請參見下面不同 web 服務器的例子)。

為了檢測的目的,您可以在 Django 中使用內建的 web 服務器:

weblate runserver

警告

在生產設置中不要使用這個服務器。它還沒有通過安全審查或性能檢測。還請參見 runserver 上的 Django 文件。

提示

Django 內建服務只通過允許 DEBUG 來為靜態文件提供服務,因為它只用於開發的目的。對於生產使用,請參見 NGINX 和 uWSGI 的配置例子Apache 的配置例子 Apache 和 Gunicorn 的配置例子Serving static files 中的wsgi 設置。

Serving static files

在 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 提供服務。

Content security policy

預設的 Weblate 配置允許 weblate.middleware.SecurityMiddleware 中間件,它設置與 HTTP 標頭相關的安全,如 Content-Security-PolicyX-XSS-Protection。這些被預設新建,與 Weblate 及其配置一起工作,但這對你的環境需要定制化。

也參考

:設置:csp_script_src,:設置:csp_img_src,:設置:csp_connect_src,:設置:csp_style_src,:設置:csp_font_src

NGINX 和 uWSGI 的配置例子

為了運行生產web 服務器,使用與Weblate 一起安裝的wsgi 封裝(在虛擬env 的情況下,它安裝為:file:~/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 your Python version
# - 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

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 python3.9 to match your Python version
# - 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

在 1.3 版本新加入.

推薦當 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 your Python version
# - 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 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

也參考

:ref:芹菜<芹菜:Broker-Redis-Configuration>“redis broker配置>`

您應該啟動 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 regular trigger (for example committing 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 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 啟動日誌,來找出根本原因。

Monitoring Celery status

You can find current length of the Celery task queues in the 管理介面 or you can use 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 日誌中,並且用戶不可見。在您想要了解故障概況的情況下,推薦配置 Collecting error reports

監測 Weblate

Weblate 提供 /healthz/ URL 作為簡單的健康檢查來使用,例如使用 Kubernetes。 Docker 容器具有使用此 URL 的內置運行狀況檢查。

用於監視Weberate的指標,您可以使用:http:get:`/ api / metrics /`api端點。

Collecting error reports

與其他任何軟件一樣,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 再遷移。

遷移數據庫

Depending on your database backend, you might have several options to migrate the database. The most straightforward approach is to use database native tools, as they are usually the most effective (e.g. mysqldump or pg_dump). Alternatively you can use replication in case your database supports it.

也參考

Migrating between databases described in 從其它數據庫遷移到 PostgreSQL.

Migrating VCS repositories

存儲在 DATA_DIR 下的版本控制系統(VCS)同樣需要遷移。您可以簡單地複制它們,或使用 rsync 來更有效地遷移。

其他註釋

不要忘記移動 Weblate 會使用的其他服務,如 Redis 、 Cron 任務或定制的身份驗證後端。