配置指令¶
安裝 Weblate¶
根據您的設定和經驗，為您選擇適當的安裝方法：
使用 Docker 安裝, 推薦用於生產安裝。
Virtualenv 安裝，推薦用於產品設定：
從原始碼中安裝 ，推薦於開發。
架構概覽¶
- Web 伺服器
處理傳入 HTTP 請求，靜態檔案服務。
- 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 伺服器
A WSGI server serving web pages to users.
Use dedicated node when scaling Weblate horizontally.
- 資料庫
用於儲存所有內容的 PostgreSQL 資料庫伺服器，請參閱 Weblate 的資料庫設定。
Use dedicated database node for sites with hundreds of millions of hosted words.
- 資料儲存
Key/value datastore such as Valkey or Redis server for cache and tasks queue, see 使用 Celery 的背景工作.
Use dedicated node when scaling Weblate horizontally.
- 檔案系統
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.
- 電子郵件伺服器
用於發送電子郵件的 SMTP 伺服器，請參閱 設定外寄郵件信箱。其可以為外部提供。
提示
使用 Docker 安裝 包含 PostgreSQL 與 Valkey，使安裝過程更輕鬆。
軟體要求¶
作業系統¶
Weblate 已知執行在 Linux 、 FreeBSD 和 macOS 上。其他類 Unix 的系統也很可能支持執行。
Windows 不支援 Weblate。但仍然可能工作，並願意接受修補程式。
也參考
架構概覽 describes overall Weblate architecture and required services.
Python 依賴項¶
Weblate is written in Python and supports Python
3.12 or newer. You can install dependencies using pip or from your
distribution packages, full list is available in requirements.txt.
值得注意的依賴項：
- Django
- Celery
- Translate Toolkit
- translation-finder
- Python Social Auth
- Django REST 框架
可選依賴項指定器 |
Python 套件 |
Weblate 功能 |
|---|---|---|
|
||
|
||
|
||
|
Google Cloud 翻譯進階版 帶有詞彙表支援 |
|
|
||
|
||
|
PostgreSQL，請參閱 Weblate 的資料庫設定 |
|
|
||
|
||
|
整合 SAML 2 IDP 到 Weblate |
|
|
Needed for 更新 POT 檔案（Sphinx） |
|
|
Hosted Weblate 整合 |
|
|
Weblate wsgi 伺服器 |
|
|
當使用 pip 安裝時，您可以直接指定預想的功能：
uv pip install "weblate[Postgres,Amazon,SAML]"
或您可以安裝 Weblate 並包含所有可以選用的功能：
uv pip install "weblate[all]"
或您可以安裝 Weblate 並不包含任何可選用的功能：
uv pip install weblate
pip 安裝疑難排解¶
ERROR: Dependency 'gobject-introspection-2.0' is required but not found.The installed
PyGobjectpackage cannot find a matching GObject Introspection library -gobject-introspection-2.0.Older versions are no longer supported by Weblate.
ffi_prep_closure(): bad user_data (it seems that the version of the libffi library seen at runtime is different from the 'ffi.h' file seen at compile-time)This is caused by incompatibility of binary packages distributed via PyPI with the distribution. To address this, you need to rebuild the package on your system:
uv pip install --force-reinstall --no-binary :all: cffi
error: ‘xmlSecKeyDataFormatEngine’ undeclared (first use in this function); did you mean ‘xmlSecKeyDataFormat’?This is a known issue of the xmlsec package, please see https://github.com/xmlsec/python-xmlsec/issues/314.
lxml & xmlsec libxml2 library version mismatchThe
lxmlandxmlsecpackages have to be built against onelibxml2. You should build them locally to avoid this issue:uv pip install --force-reinstall --no-binary xmlsec --no-binary lxml lxml xmlsec
其他系統要求¶
後面的依賴項必須安裝在系統上：
Git- Pango 、 Cairo 和相關的標頭檔案與 GObject introspection 資料
https://cairographics.org/，https://www.gtk.org/docs/architecture/pango，請參閱 Pango 與 Cairo
git-review（可選用支援 Gerrit）git-svn（可選用支援 Subversion）tesseract(needed only if tesserocr binary wheels are not available for your system)
建置時的依賴項¶
為了建置一些 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 的記憶體
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 使用¶
大量並行使用者會提高需要的 CPU 核心數。
儲存空間使用¶
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 架構概覽) 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 行程需要能夠讀寫它儲存資料的目錄 - DATA_DIR。該目錄下的所有檔案都應該由執行所有 Weblate 行程的使用者擁有和可寫入（通常是 WSGI 和 Celery，見 正在執行伺服器 and 使用 Celery 的背景工作）。
預設的配置放置在 Weblate 來源的相同樹下，然而您會想要將這些移動到更好的位置，如： /var/lib/weblate。
Weblate 試圖自動建立這些資料夾，但當沒有權限去執行時會失敗。
The configured CACHE_DIR also has to be writable by the Weblate
process and has to allow executing generated helper files. Do not mount
CACHE_DIR with the noexec option.
當執行 管理指令 時應該小心，它們應該由 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 13 和更高版本。推薦 PostgreSQL 15 或更新版本。
資料庫連線¶
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資料庫¶
在另一個單獨的資料庫中執行 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",
# 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,
}
}
The database migration performs ALTER ROLE on the database role used
by Weblate. In most cases, the name of the role matches the username. In more
complex setups the role name is different from the username, and you will get an error
about non-existing role during the database migration
(psycopg2.errors.UndefinedObject: role "weblate@hostname" does not exist).
This is known to happen with Azure Database for PostgreSQL, but it's not
limited to this environment. Please set ALTER_ROLE to change the name of the
role Weblate should alter during the database migration.
也參考
其他配置¶
設定外寄郵件信箱¶
Weblate 在各種情況下會發出電子郵件——用於啟動帳號，以及使用者配置的各種通知。對於這些需要存取 SMTP 伺服器。
郵件伺服器使用這些設定進行配置: EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, EMAIL_USE_SSL, EMAIL_HOST_USER and EMAIL_PORT。從名稱就可以大概知道它們的含義，但是您可以在Django說明文件中找到更多資訊。
提示
In case you get error about not supported authentication (for example
SMTP AUTH extension not supported by server), it is most likely caused
by using insecure connection and server refuses to authenticate this way.
Try enabling EMAIL_USE_TLS in such case.
在反向代理後面執行¶
Several features in Weblate rely on correct HTTP headers being passed to Weblate. When using reverse proxy, please make sure that the needed information is correctly passed.
To debug this configuration, you can look at HTTP environment in 效能報告.
- 用戶端 IP 位址
This is needed for 速率限制 or 稽核紀錄.
Weblate parses IP address from the
REMOTE_ADDR, which is set by the WSGI handler. This might be empty (when using socket for WSGI) or contain a reverse proxy address, so Weblate needs an additional HTTP header with a client IP address.Enabling
IP_BEHIND_REVERSE_PROXYshould be sufficient for the most usual setups, but you might need to adjustIP_PROXY_HEADERandIP_PROXY_OFFSETas well (useWEBLATE_IP_PROXY_HEADERandWEBLATE_IP_PROXY_OFFSETin the Docker container).提示
This configuration cannot be turned on by default, because it would allow IP address spoofing on installations that don't have a properly configured reverse proxy.
- 伺服器主機名稱
The Host header should match to whatever is configured as
SITE_DOMAIN. Additional configuration might be needed in your reverse proxy (for example useProxyPreserveHost Onfor Apache orproxy_set_header Host $host;with nginx).提示
CSRF verification failed errors are often caused by a mismatch between the Host header and configured
SITE_DOMAIN.- 用戶端協定
Not passing correct protocol may cause Weblate to end up in redirection loop trying to upgrade client to HTTPS. Make sure it is correctly exposed by the reverse proxy as X-Forwarded-Proto.
This header then needs to be configured in
SECURE_PROXY_SSL_HEADER(settings.py) orWEBLATE_SECURE_PROXY_SSL_HEADER(Docker environment).重要
The header value is case-sensitive in the configuration, so
WEBLATE_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,httpsandWEBLATE_SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,HTTPSare not interchangeable.提示
If you are getting a "Too many redirects" error from the browser, this is most likely caused by mismatch between the actual protocol (HTTPS) and what is observed by Weblate.
在 5.13 版的變更: The protocol proxy headers are automatically handled by gunicorn in the default configuration, but other WSGI servers have more secure configuration and require explicit setting of this.
Since Weblate 5.13 the Docker container is using granian and it now requires the explicit configuration of
WEBLATE_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 錯誤的通知。
Contact form sends e-mail on these as well unless
ADMINS_CONTACTis configured.
ALLOWED_HOSTS
需要設定這個，來列出您的網站支援服務的主機。例如：
ALLOWED_HOSTS = ["demo.weblate.org"]另外可以包括萬用字元：
ALLOWED_HOSTS = ["*"]
SESSION_ENGINE
配置如何儲存工作階段。在保持預設的資料庫後端引擎的情況下，應該安排 weblate clearsessions 從資料庫中刪除舊的工作階段。
If you are using Valkey or Redis as cache (see 配置快取) it is recommended to use it for sessions as well:
SESSION_ENGINE = "django.contrib.sessions.backends.cache"
DATABASES
到資料庫伺服器的連線能力，細節請查看 Django 的說明文件。
DEBUG
DEFAULT_FROM_EMAIL
用於發送電子郵件的電子郵件寄件人地址，例如註冊電子郵箱。
SECRET_KEY
金鑰會被 Django 簽署相同資訊在瀏覽器 cookies 中，請參閱 Django金鑰 了解更多資訊。
也參考
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，它會提示您網站上潛在的非最優的配置。
生產設定¶
對於生產設定，可以進行後面的章節中描述的調整。最嚴格的設定將觸發警告，如果超級使用者登入的話，警告由頂部條的感嘆標記來指示：
同樣也推薦查看由 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。
正確的 HTTPS 設定¶
強烈推薦使用加密的 HTTPS 協定 執行 Weblate。將其允許後，可以在設定中設定 ENABLE_HTTPS ：
ENABLE_HTTPS = True
提示
您還會想要新增 HSTS，更多細節請參閱 SSL/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 Strict Transport Security 標頭。
警告
不正確地設定這項會導致您的網站不可逆地（有時）崩潰。請首先閱讀 HTTP Strict Transport Security 說明文件。
使用強力的資料庫引擎¶
請使用 PostgreSQL 作為生產環境，更多資訊請參閱 Weblate 的資料庫設定。
使用相鄰的區域運作資料庫，網路的效能與可靠性會影響 Weblate 的使用體驗。
確認資料庫的效能或調校其設定檔，例如使用 PGTune 。
配置快取¶
If possible, use Valkey or Redis from Django by adjusting the CACHES
configuration variable, for example:
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",
},
}
}
提示
In case you change settings for the cache, you might need to adjust them for Celery as well, see 使用 Celery 的背景工作.
個人頭像快取¶
除了 Django 的快取， Weblate 還執行頭像快取。推薦使用單獨的、檔案後端快取來用於這個目的：
CACHES = {
"default": {
# Default caching backend setup, see above
"BACKEND": "django_redis.cache.RedisCache",
"LOCATION": "unix:///var/run/redis/redis.sock?db=0",
"OPTIONS": {
"CLIENT_CLASS": "django_redis.client.DefaultClient",
"PARSER_CLASS": "redis.connection.HiredisParser",
},
},
"avatar": {
"BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
"LOCATION": os.path.join(DATA_DIR, "avatar-cache"),
"TIMEOUT": 604800,
"OPTIONS": {
"MAX_ENTRIES": 1000,
},
},
}
郵件外送設定¶
Weblate 需要在幾種情況下發送電子郵件，這些電子郵件應具有正確的發送者地址，請配置 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。
這將禁止 所有 電子郵件的投遞，包括註冊或密碼重設電子郵件。
允許的網域設定¶
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， 來產生新的金鑰。
也參考
執行維護事項¶
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 帶有一組 JavaScript 和 CSS 檔案。由於效能的原因，在將其發送到用戶端前最好進行壓縮。在預設配置中，這透過耗費一點經常資源而在執行中完成。在大型安裝中，推薦允許離線壓縮模式。這需要在配置中完成，並且必須在每次 weblate 升級時觸發壓縮。
配置切換很簡單，通過允許 django.conf.settings.COMPRESS_OFFLINE，並配置 django.conf.settings.COMPRESS_OFFLINE_CONTEXT （後者已經包括在範例的配置中）：
COMPRESS_OFFLINE = True
在每個部署中，您需要壓縮檔案來比對目前版本：
weblate compress
提示
官方 Docker 映像已經允許了這個功能。
正在執行伺服器¶
提示
如果您沒有在下面描述的服務經歷，您可能需要嘗試 使用 Docker 安裝。
需要幾個服務來執行Weblate，推薦的設定包括：
資料庫伺服器（請參閱 Weblate 的資料庫設定）
快取伺服器（請參閱 配置快取 ）
用於靜態檔案和終止 SSL 的前端 web 伺服器（請參閱 靜態檔案服務）
用於動態內容的 WSGI 伺服器（請參閱 NGINX 和 uWSGI 的配置範例 ）
用於執行背景工作的 Celery （請參閱 使用 Celery 的背景工作 ）
備註
這些服務之間由一些依賴項，例如當啟動 Celery 或 uwsgi 行程時，快取和資料庫應該執行。
在多數情況下，需要在單一（虛擬）伺服器上執行所有服務，但在您的安裝是重載的情況下，可以將這些服務拆開。對此的唯一限制是 Celery 和 Wsgi 伺服器需要存取 DATA_DIR。
備註
WSGI 行程和 Celery 行程必須在同一使用者下被執行，否則 DATA_DIR 中的檔案將以混合的所有權來儲存，導致執行期問題。
另請參閱 檔案系統權限 和 使用 Celery 的背景工作。
正在執行網頁伺服器¶
執行 Weblate 與執行其他任何基於 Django 的程式沒什麼不同。 Django 通常作為 WSGI 或 fcgi 執行（請參閱下面不同 web 伺服器的範例）。
備註
The sample configuration files shown below are maintained in the Weblate
source tree under weblate/examples/. They are included in source
distributions and in this documentation, but Python wheels only install
runtime files. When installing Weblate from PyPI, get the matching source
distribution or source checkout before copying these examples.
為了測試目的，您可以在 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:
靜態檔案服務¶
在 5.15.2 版的變更: /media/ is no longer used for serving screenshots.
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)./favicon.ico應該重寫，重寫規則為
/static/favicon.ico提供服務。
內容安全性政策（CSP）¶
The default Weblate configuration enables weblate.middleware.SecurityMiddleware
middleware which sets security related HTTP headers like Content-Security-Policy
or X-XSS-Protection. These are by default set up to work with Weblate and its
configuration, but this might need customization for your environment.
Sample configuration for NGINX and Granian¶
The following configuration runs Weblate using Granian the NGINX webserver:
#
# 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://127.0.0.1:8888;
proxy_read_timeout 3600;
}
}
Sample configuration for NGINX and Gunicorn¶
The following configuration runs Weblate using Gunicorn under the NGINX webserver
(weblate/examples/weblate.nginx.gunicorn.conf in the source tree):
#
# 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;
}
}
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 網頁伺服器下的 uWSGI 來執行。
Configuration for NGINX (weblate/examples/weblate.nginx.conf in the source tree):
#
# 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;
}
}
Configuration for uWSGI (weblate/examples/weblate.uwsgi.ini in the source tree):
#
# 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
Apache 的配置範例¶
推薦當 Weblate 使用 WSGI 時使用 prefork MPM。
The following configuration runs Weblate as WSGI, you need to have enabled
mod_wsgi (weblate/examples/apache.conf in the source tree):
#
# 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。
Use matching Python version to install Weblate.
Apache 和 Gunicorn 的配置範例¶
The following configuration runs Weblate in Gunicorn and Apache 2.4
(weblate/examples/apache.gunicorn.conf in the source tree):
#
# 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>
Sample configuration to start Granian¶
Weblate has wsgi optional dependency (see Python 依賴項) that will install everything you need to run Granian. When installing Weblate you can specify it as:
uv pip install Weblate[all,wsgi]
Once you have Granian installed, you can run it. This is usually done at the system level. The following examples show starting via systemd:
[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
~
Sample configuration to start Gunicorn¶
Gunicorn has to be installed separately:
uv pip install gunicorn
Once you have Gunicorn installed, you can run it. This is usually done at the system level. The following examples show starting via systemd:
[Unit]
Description=gunicorn socket
[Socket]
ListenStream=/run/gunicorn.sock
[Install]
WantedBy=sockets.target
[Unit]
Description=gunicorn daemon
Requires=gunicorn.socket
After=network.target
[Service]
User=weblate
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。
A sample Apache configuration to serve Weblate under /weblate. Again using
mod_wsgi (weblate/examples/apache-path.conf in the source tree):
#
# 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"
使用 Celery 的背景工作¶
Weblate 使用 Celery 來執行常規或是背景的排程工作。您應該執行一組 Celery 服務來執行工作，例如它會負責處理以下的運作（此清單非完整）：
透過 webhooks 接收來自外部的服務中（請參閱 通知掛勾）。
執行規律的維護工作如備份、清理與每日的附加元件或更新。（請參閱 備份和移動 Weblate、
BACKGROUND_TASKS、 附加元件）。執行 自動翻譯。
發送摘要通知。
Offloading expensive operations from the WSGI process.
Committing pending changes (see 簡易提交).
A typical setup using Valkey or Redis as a backend looks like this:
CELERY_TASK_ALWAYS_EAGER = False
CELERY_BROKER_URL = "redis://localhost:6379"
CELERY_RESULT_BACKEND = CELERY_BROKER_URL
You should also start the Celery worker to process the tasks and start scheduled tasks. For debugging or development, this can be done directly on the command-line:
celery --app=weblate.utils worker --beat --queues=celery,notify,memory,translate,backup
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 作為系統服務¶
Most likely you will want to run Celery as a daemon and that is covered by
Daemonization. For the most common Linux setup using
systemd, adapt the example files listed below. These examples are maintained in
the Weblate source tree under weblate/examples/; Python wheels do not
install these deployment samples.
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 beat 的週期性工作¶
Weblate comes with built-in setup for scheduled tasks. The task schedule is stored in the database and tasks are executed by the Celery beat daemon.
提示
You can define additional tasks in settings.py, for example see
簡易提交.
觀察 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
An installation using Docker can be configured to use a single-process Celery setup by setting CELERY_SINGLE_PROCESS.
警告
This will have a noticeable performance impact on Weblate.
監測 Weblate¶
Weblate 提供 /healthz/ URL 作為簡單的健康檢查來使用，例如使用 Kubernetes。 Docker 容器具有使用此 URL 的內建執行狀況檢查。
For monitoring metrics of Weblate you can use GET /api/metrics/ API endpoint.
Collecting error reports and monitoring performance¶
與其他任何軟體一樣，Weblate 可能會失敗。為了收集有用的故障狀態，我們推薦使用第三方服務來收集此類資訊。這在 Celery 工作失敗的情況下尤其有用，否則將只會向紀錄報告錯誤，而您不會收到有關它們的通知。 Weblate 支援以下服務：
郵件信箱¶
The default Weblate configuration instruments Django to send e-mails upon
server errors via django.utils.log.AdminEmailHandler. This
is the least effort setup, but you should consider other options for privacy
reasons, as the error e-mails might include sensitive data. You can read more on
that in Security implications.
To disable this behavior, remove mail_admins from the
LOGGING in Weblate settings, or disable
WEBLATE_ADMIN_NOTIFY_ERROR in the Docker environment.
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",
"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.
Graylog 紀錄管理¶
在 5.9 版被加入.
Weblate can be configured to log using the GELF TCP protocol. This was developed for Graylog integration, but can be used with any compliant logging platform.
The configuration boilerplate is included in 配置的範例, for
Docker this can be configured using 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.
也參考
Migrating between databases described in 從其它資料庫遷移到 PostgreSQL.
遷移 VSC 儲存庫¶
儲存在 DATA_DIR 下的版本控制系統（VCS）同樣需要遷移。您可以簡單地複製它們，或使用 rsync 來更有效地遷移。
其他註釋¶
Don't forget to move other services Weblate might have been using like Valkey, Redis, Cron jobs or custom authentication backends.