組態指令

安裝 Weblate

根據您的設定和經驗,為您選擇適當的安裝方法:

Architecture overview

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

網頁伺服器

Handling incoming HTTP requests, 靜態檔案服務.

Celery workers

使用 Celery 的後台任務 are executed here.

Depending on your workload, you might want to customize the number of workers.

Use dedicated node when scaling Weblate horizontally.

WSGI server

A WSGI server serving web pages to users.

Use dedicated node when scaling Weblate horizontally.

資料庫

PostgreSQL database server for storing all the content, see Weblate 的資料庫設定.

Use dedicated database node for sites with hundreds of millions of hosted words.

Redis

Redis 伺服器,用於快取和任務隊列,請參見 使用 Celery 的後台任務

Use dedicated node when scaling Weblate horizontally.

File system

File system storage for storing VCS repositories and uploaded user data. This is shared by all the processes.

Use networked storage when scaling Weblate horizontally.

E-mail server

SMTP server for outgoing e-mail, see 設定外寄郵件信箱. It can be provided externally.

提示

使用 Docker 安裝 includes PostgreSQL and Redis, making the installation easier.

軟體要求

操作系統

Weblate 已知執行在 Linux 、 FreeBSD 和 macOS 上。其他類 Unix 的系統也很可能支持執行。

Windows 不支援 Weblate。但仍然可能工作,並願意接受補丁。

也參考

Architecture overview describes overall Weblate architecture and required services.

Python 相依性

Weblate is written in Python and supports Python 3.10 or newer. You can install dependencies using pip or from your distribution packages, full list is available in 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/

當使用 pip 安裝時,您可以直接指定預想的功能:

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

或您可以安裝 Weblate 並包含所有可以選用的功能:

pip install "Weblate[all]"

或您可以安裝 Weblate 並不包含任何可選用的功能:

pip install 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 (needed only if tesserocr binary wheels are not available for your system)

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

licensee (當建立元件並發現授權條款時可選用)

https://github.com/licensee/licensee

建置時的相依項

為了建置一些 Python 相依性,您可能需要安裝其相依項。這取決於您如何安裝它們,因此請參考單獨軟體包的文件。如果您使用預編譯 Wheels 並使用 pip 安裝或使用散步版軟體包時,您不會需要那些。

Pango 與 Cairo

Weblate 使用 Pango 和 Cairo 來提供位圖 widget(請參參見 推動翻譯 )並提供檢查(請參見 管理字型 )。為了適當地安裝 Python 綁定需要首先安裝系統庫的那些—— Cairo 和 Pango 都是需要的,由此需要 Glib。所有那些需要與開發文件和 GObject 內省資料一起安裝。

硬體要求

Weblate should run on any contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and web server):

  • 3 GB of RAM

  • 2 CPU 核心

  • 1 GB 的儲存空間

備註

根據 Weblate 中管理的翻譯大小,安裝 Weblate 的實際要求差異很大。

記憶體使用情況

The more memory the better - it is used for caching on all levels (file system, database and Weblate). For hundreds of translation components, at least 4 GB of RAM is recommended.

提示

For systems with less memory than recommended, Single-process Celery setup is recommended.

CPU usage

Many concurrent users increase the amount of needed CPU cores.

Storage usage

The typical database storage usage is around 300 MB per 1 million hosted words.

Storage space needed for cloned repositories varies, but Weblate tries to keep their size minimal by doing shallow clones.

Nodes

For small and medium-sized sites (millions of hosted words), all Weblate components (see Architecture overview) can be run on a single node.

When you grow to hundreds of millions of hosted words, it is recommended to have a dedicated node for database (see Weblate 的資料庫設定).

驗證發行簽名

Weblate release are cryptographically signed using Sigstore signatures. The signatures are attached to the GitHub release.

The verification can be performed using sigstore package. The following example verifies signature of the 5.4 release:

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 進程需要能夠讀寫它保存資料的目錄 - 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 12 and higher is supported. PostgreSQL 15 or newer is recommended.

MySQL 與 MariaDB is supported, but not recommended for new installs.

備註

No other database servers are currently supported, but support for other Django supported databases should be possible to implement.

Database connections

In the default configuration, each Weblate process keeps a persistent connection to the database. Persistent connections improve Weblate responsiveness, but might require more resources for the database server. Please consult CONN_MAX_AGE and Persistent connections for more info.

Weblate needs at least the following number of connections:

  • \((4 \times \mathit{nCPUs}) + 2\) for Celery processes

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

This applies to Docker container defaults and example configurations provided in this documentation, but the numbers will change once you customize the amount of WSGI workers or adjust parallelism of Celery.

The actual limit for the number of database connections needs to be higher to account following situations:

  • 管理命令 need their connection as well.

  • If case process is killed (for example by OOM killer), it might block the existing connection until timeout.

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;
CREATE EXTENSION IF NOT EXISTS btree_gin;

組態 Weblate 來使用 PostgreSQL

PostgreSQL 的 settings.py 片段:

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

資料庫的合併執行了Weblate 使用的 ALTER ROLE 資料庫角色。在多數情況下,角色的名稱與使用者名匹配。在更富在的設定中,角色的名稱與使用者名不同,而在資料庫合併過程中會得到不存在的角色的錯誤資訊(psycopg2.errors.UndefinedObject: role "weblate@hostname" does not exist` `,角色“weblate@hostname”不存在)。已知這會在 PostgreSQL Azure 資料庫時發生,但並不僅限於這種環境。請將 ``ALTER_ROLE 設定為資料庫合併過程中 Weblate 應該更改的角色的名稱。

MySQL 與 MariaDB

警告

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 notesMariaDB notes。由於這些限制,我們建議對新安裝使用 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 內存伺服器的 /: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, 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

另一個需要被注意的事項是 Host 。它應該要與 SITE_DOMAIN 相符合。反向代理伺服器可能需要額外的設定(例如使用 ProxyPreserveHost On 於 Apache 或 proxy_set_header Host $host; 於 nginx 中)。

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 錯誤的通知。

Contact form sends e-mail on these as well unless ADMINS_CONTACT is configured.

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

SERVER_EMAIL

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

也參考

SERVER_EMAIL

填滿資料庫

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

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

也參考

組態, 特權列表

生產設定

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

../_images/admin-wrench.webp

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

weblate check --deploy

You can also review the very same checklist at 效能報告 in the 管理介面.

停用除錯模式

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

DEBUG = False

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

也參考

調整組態

合適的管理參數設定

將正確的管理地址設定到 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

正確的 HTTPS 設定

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

ENABLE_HTTPS = True

提示

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

設定合適的 SECURE_HSTS_SECONDS

如果您的網站基於 SSL 上提供服務,那麼必須考慮 settings.pySECURE_HSTS_SECONDS 的設定值,來允許 HTTP Strict Transport Security ( HTTP 腳本傳輸安全)。預設設定為 0,如下所示。

SECURE_HSTS_SECONDS = 0

如果設定為非 0 整數,那麼在所有還不曾具有它的響應時, django.middleware.security.SecurityMiddleware 設定 HTTP Strict Transport Security 標頭。

警告

不正確地設定這項會導致您的網站不可逆地(有時)崩潰。請首先閱讀 HTTP Strict Transport Security 文件。

使用強力的資料庫引擎

  • 請使用 PostgreSQL 作為生產環境,更多資訊請參見 Weblate 的資料庫設定

  • 使用相鄰的區域運作資料庫,網路的效能與可靠性會影響 Weblate 的使用體驗。

  • 確認資料庫的效能或調校其設定檔,例如使用 PGTune

允許快取

如果可能,通過調整 CACHES 組態變量來使用來自 Django 的 Redis,例如:

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

提示

在為快取更改 Redis 設定的情況下,也會需要為 Celery 來調整,請參見 使用 Celery 的後台任務

個人頭像快取

除了 Django 的快取, Weblate 還執行頭像快取。推薦使用單獨的、文件後端快取來用於這個目的:

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

也參考

:設定:enabent_avatars,:設定:avatar_url_prefix頭像,:ref:spections-cache`,django:主題/快取

郵件外送設定

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

允許的網域設定

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

執行維護事項

For optimal performance, it is good idea to run some maintenance tasks in the background. This is automatically done by 使用 Celery 的後台任務 and covers following tasks:

  • 組態健康性的檢查(每小時)。

  • Committing pending changes (hourly), see 簡易送交 and commit_pending.

  • 更新組件警告(每天)。

  • 更新遠端分支(每晚),請參見 AUTO_UPDATE

  • Translation memory backup to JSON (daily), see dump_memory.

  • Fulltext and database maintenance tasks (daily and weekly tasks), see cleanuptrans.

系統的地區與編碼

系統的地區應該設定為相容 UTF-8 的。在多數 Linux 發佈中這是預設的設定。在您的系統不能相容的情況下,請將地區更改為 UTF-8 變體。

例如通過編輯 /etc/default/locale 並設定 LANG="C.UTF-8"

在一些情況下,個別獨立的伺服器設定檔會分別在其本地端。在發行版與網站伺服器版本間的差異,請針對您的網頁伺服器套件狀況確認文件。

在 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 證書放置在: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"

壓縮客戶端素材

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 的後台任務

正在執行網頁伺服器

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

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

weblate runserver

警告

在生產設定中不要使用這個伺服器。它還沒有通過安全稽核或效能測試。另請參見 runserver 上的 Django 文件。

提示

The Django built-in server serves static files only with DEBUG enabled as it is intended for development only. For production use, please see WSGI setups in NGINX 和 uWSGI 的組態例子, Apache 的組態例子, Apache 和 Gunicorn 的組態例子, and 靜態檔案服務.

靜態檔案服務

Django needs to collect its static files in a single directory. To do so, execute weblate collectstatic --noinput. This will copy the static files into a directory specified by the STATIC_ROOT setting (this defaults to a static directory inside CACHE_DIR).

推薦直接從您的 web 伺服器為靜態檔案提供服務,對於後面的路徑應該使用它:

/static/

Serves static files for Weblate and the admin interface (from defined by STATIC_ROOT).

/media/

用於上傳使用者媒體(例如:螢幕擷圖)。

/favicon.ico

應該重寫,重寫規則為 /static/favicon.ico 提供服務。

內容安全性政策(CSP)

預設的 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 的組態例子

To run production webserver, use the WSGI wrapper installed with Weblate (in virtual env case it is installed as ~/weblate-env/lib/python3.9/site-packages/weblate/wsgi.py). Don’t forget to set the Python search path to your virtualenv as well (for example using virtualenv = /home/user/weblate-env in uWSGI).

後面的組態將 Weblate 作為 NGINX 網頁伺服器下的 uWSGI 來執行。

NGINX 的組態(還作為 weblate/examples/weblate.nginx.conf 來獲得):

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

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

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

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

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

uWSGI 的組態(還作為 weblate/examples/weblate.uwsgi.ini 來獲得):

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

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

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

# Needed for OAuth/OpenID
buffer-size   = 8192

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

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

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

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

# Avoid default 0000 umask
umask = 0022

# Run as weblate user
uid = weblate
gid = weblate

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

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

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

Apache 的組態例子

推薦當 Weblate 使用 WSGI 時使用 prefork MPM。

後面的組態將 Weblate 作為 WSGI 來執行,您需要啟用 ``mod_wsgi``(作為 weblate/examples/apache.conf 來獲得):

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

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

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

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

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

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

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

</VirtualHost>

備註

Weblate 需要 Python 3,所以請確認您執行 modwsgi 的 Python 3 變體。它通常作為獨立的軟體包來獲得,例如 libapache2-mod-wsgi-py3

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 /home/weblate/data/cache to match your CACHE_DIR
# - change weblate user to match your Weblate user
#
<VirtualHost *:443>
    ServerAdmin admin@weblate.example.org
    ServerName weblate.example.org

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

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

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

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

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

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

在路徑下執行 Weblate

推薦當 Weblate 使用 WSGI 時使用 prefork MPM。

為``/weblate`` 下的 Weblate 提供服務的 Apache 組態的例子。再次使用 mod_wsgi (還作為 weblate/examples/apache-path.conf 獲得):

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

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

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

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

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

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

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

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

</VirtualHost>

此外,您必須調整 weblate/settings.py

URL_PREFIX = "/weblate"

使用 Celery 的後台任務

Weblate 使用 Celery 來執行常規或是背景的排程任務。您應該執行一組 Celery 服務來執行任務,例如它會負責處理以下的運作(此列表非完整):

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

備註

這將會在網頁介面中造成效能的衝擊影響,也會造成常規的觸發功能失效(例如送交暫緩的修正、摘要通知或備份)。

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:

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

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

使用 Celery beat 的週期性任務

Weblate 帶有內建的定時任務設定。然而您可以在 settings.py 中定義另外的任務,例如請參見 簡易送交

任務應該由 Celery beats 守護進程執行。在不能正常工作的情況下,它可能不會運行,或者其資料庫崩潰。在這樣的情況下檢查 Celery 啟動日誌,來找出根本原因。

觀察 Celery 狀態

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 and monitoring performance

Single-process Celery setup

In case you have very limited memory, you might want to reduce number of Weblate processes. All Celery tasks can be executed in a single process using:

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

警告

This will have a noticeable performance impact on Weblate.

監測 Weblate

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

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

Collecting error reports and monitoring performance

與其他任何軟件一樣,Weblate 可能會失敗。為了收集有用的故障狀態,我們推薦使用第三方服務來收集此類資訊。這在 Celery 任務失敗的情況下尤其有用,否則將只會向日誌報告錯誤,而您不會收到有關它們的通知。 Weblate 支援以下服務:

Sentry

Weblate 內建了對 Sentry 的支援。要使用它,只需在 settings.py 中設定 SENTRY_DSN

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

Sentry can be also used to monitor performance of Weblate by collecting traces and profiles for defined percentage of operations. This can be configured using SENTRY_TRACES_SAMPLE_RATE and SENTRY_PROFILES_SAMPLE_RATE.

Rollbar

Weblate 具有對 Rollbar 的內建支援。要使用它,只需遵循 Rollbar notifier for Python 的說明即可。

簡而言之,您需要調整 settings.py

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

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

將會自動整合所有必要的設定,您將會蒐集到來自伺服器或是使用端的錯誤訊息。

備註

Error logging also includes exceptions that were gracefully handled, but might indicate a problem - such as failed parsing of an uploaded file.

將 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.

遷移 VSC 儲存庫

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

其他註釋

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