Weblate 2026.10.1 配置参数详解

目标：系统梳理 Weblate 2026.10.1 的全部常用配置参数——官方 Docker 环境变量（WEBLATE_* / POSTGRES_* / REDIS_* / 邮件参数）与 /app/data/settings-override.py 深度覆盖机制，逐项给出含义、官方默认值与生效方式，参数行为均经真实部署实测或官方文档实查（查询日期 2026-10-21），帮助读者一次配准生产实例。部署过程见《Weblate Docker Compose 部署指南》。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Weblate：2026.10.1（weblate/weblate:2026.10.1.1，2026-10-21 GitHub Releases 最新稳定标签）
• 部署形态：官方 Docker Compose 三服务（主服务 + PostgreSQL 18 + Valkey 9.1.2），环境变量统一注入
• 参数来源：官方编排仓库 environment 样例文件、官方 Docker 部署文档（docs.weblate.org/en/latest/admin/install/docker.html，2026-10-21 实查）、部署实例内实际生效值核对
• 标注约定：【实测】= 本文部署环境中验证过实际行为；【实查】= 官方文档/样例文件实查（2026-10-21）

二、前置条件

1. 已按《Weblate Docker Compose 部署指南》完成一次成功部署（curl http://localhost:8143/healthz/ 返回 ok）；
2. 能编辑部署目录下的 docker-compose.yml 并执行 docker compose up -d 重建；
3. 理解两条基本原则：Weblate 配置面收敛在「环境变量 + 数据盘覆盖文件」两处；环境变量改动必须重建服务（up -d）才生效，单纯 restart 不重读编排。

三、参数查看与修改方式

3.1 查看当前生效的环境变量

进入主服务打印进程环境（实测）：

cd /opt/weblate
docker compose exec weblate env | grep -E '^(WEBLATE_|POSTGRES_|REDIS_)' | sort

实测输出：

POSTGRES_DATABASE=weblate
POSTGRES_HOST=database
POSTGRES_PASSWORD=weblate
POSTGRES_PORT=5432
POSTGRES_USER=weblate
REDIS_DB=1
REDIS_HOST=cache
REDIS_PORT=6379
WEBLATE_ADMIN_EMAIL=root@example.com
WEBLATE_ADMIN_NAME=root
WEBLATE_ADMIN_PASSWORD=q1w2e3r4
WEBLATE_ALLOWED_HOSTS=*
WEBLATE_DEBUG=0
WEBLATE_DEFAULT_FROM_EMAIL=root@example.com
WEBLATE_DOCKER_CONTAINER=1
WEBLATE_EMAIL_HOST=127.0.0.1
WEBLATE_LOGLEVEL=INFO
WEBLATE_REGISTRATION_OPEN=1
WEBLATE_SERVER_EMAIL=root@example.com
WEBLATE_SITE_DOMAIN=localhost:8143
WEBLATE_SITE_TITLE=Weblate
WEBLATE_TIME_ZONE=Asia/Shanghai
WEBLATE_VERSION=2026.10.1

关键解读：WEBLATE_DOCKER_CONTAINER=1 与 WEBLATE_VERSION 是官方入口脚本自动注入的标记变量，不在编排里声明；其余变量与编排文件一一对应。

3.2 查看最终生效的 Django 设置

环境变量是「输入」，Django 设置才是「生效值」，二者不等价（如 WEBLATE_TIME_ZONE 会被转成 Django 的 TIME_ZONE，还可能被覆盖文件再改写）。用内置 shell 直接读生效值（实测）：

docker compose exec weblate weblate shell -c "from django.conf import settings; print('TIME_ZONE:', settings.TIME_ZONE, '| DEBUG:', settings.DEBUG)"

实测输出：

TIME_ZONE: Asia/Shanghai | DEBUG: False

3.3 修改方式与生效规则

三种修改入口，优先级从低到高：

环境变量重建生效（实测）：改 docker-compose.yml 后执行 docker compose up -d，Compose 检测到配置变化会自动重建该服务（输出 Recreate/Recreated），入口脚本重读变量并应用。

数据盘覆盖文件生效闭环（实测）：官方文档明确支持在数据卷根目录创建 /app/data/settings-override.py 来扩展/覆盖环境变量生成的设置。实测验证全流程——部署时 WEBLATE_TIME_ZONE=Asia/Shanghai（3.1/3.2 实测生效值），随后在数据盘写入覆盖文件：

cat > /opt/weblate/data/weblate/settings-override.py <<'PY'
# settings-override: 覆盖环境变量生成的设置
TIME_ZONE = "Europe/Prague"
PY
chown 1000:1000 /opt/weblate/data/weblate/settings-override.py
cd /opt/weblate && docker compose restart weblate

重启完成后再次打印生效值（实测输出）：

TIME_ZONE: Europe/Prague

关键解读：覆盖文件在环境变量之后加载，同名字段以覆盖文件为准；文件属主必须是 1000:1000（主服务以 uid 1000 运行），且写入前用 python3 -m py_compile 校验语法——语法错误会导致服务启动失败。

💡 技术拓展：Django 设置覆盖的同类方案对比——

方案	原理	适用场景
环境变量	入口脚本按变量名映射到 settings 字段	官方封装的常用项，首选
settings-override.py	数据盘 Python 文件在 settings 末尾追加/覆盖	未封装字段、临时调参
扩展镜像	自建 settings 模块替换 DJANGO_SETTINGS_MODULE	团队级深度定制、需进版本控制
数据库配置	管理后台「接口/配置」页动态改 SOCIALAUTH 等少数项	运行时可调项，无需重启

本文实测采用「环境变量 + settings-override.py」组合：常用项走环境变量保持编排可迁移，未封装项走覆盖文件避免自建镜像。

四、参数总览

按功能域分组（默认值除标注外均为【实查】官方样例/文档，2026-10-21）：

关键解读：官方样例 environment 文件只给 10 余个变量兜底，其余 200+ 变量全部按需启用； 生产最易踩坑的是站点域名、邮件通道与 HTTPS 反代三组。

五、核心参数分类详解

5.1 站点基础参数

WEBLATE_SITE_DOMAIN（必配）【实测】：站点对外地址，不带协议头，格式 地址[:端口]。本文实测值 localhost:8143；生产写 weblate.example.com。它决定页面内绝对链接（API 返回的 web_url/translate_url 全部基于它，3.1 实测中 /api/projects/demo/ 返回体可见）与 CSRF 校验域——值与实际访问地址不一致时，登录/提交表单会报 CSRF 校验失败。

WEBLATE_DEBUG【实测】：Django 调试开关，默认 0。本文设 0 后实测 settings.DEBUG 打印 False。生产必须 0——调试模式会泄露配置细节且性能显著下降；排障期临时改 1 重建即可。

WEBLATE_TIME_ZONE【实测】：站点时区，官方默认 UTC。本文实测 Asia/Shanghai 生效（3.2），并被 settings-override.py 成功覆盖为 Europe/Prague（3.3 闭环），证明其转换为 Django TIME_ZONE 的路径可用覆盖文件改写。

WEBLATE_LOGLEVEL【实查】：日志级别，默认 INFO，排障期可改 DEBUG 配合 WEBLATE_DEBUG 使用。

WEBLATE_ALLOWED_HOSTS【实查】：Django ALLOWED_HOSTS 白名单，官方样例示例 weblate.example.com,example.com（逗号分隔）。本文用 * 放行所有 Host（实测页面与 API 正常）；生产收敛为具体域名，防止 Host 头伪造。放在反代后面时还可配合 WEBLATE_IP_PROXY_HEADER 传递真实客户端 IP。

WEBLATE_HIDE_VERSION【实查】：隐藏页面底部的版本号（对应 HIDE_VERSION 设置），面向公网的实例建议开启，减少版本指纹。

5.2 管理员与注册参数

WEBLATE_ADMIN_NAME / WEBLATE_ADMIN_EMAIL / WEBLATE_ADMIN_PASSWORD【实测】：首启管理员注入三件套。实测结论（重要）：登录用户名固定为 admin，WEBLATE_ADMIN_NAME 只是显示全名（官方样例值为 Weblate Admin 也可佐证其语义）；邮箱取 WEBLATE_ADMIN_EMAIL；密码取 WEBLATE_ADMIN_PASSWORD。官方样例默认密码为空——为空时不自动设密，管理员改用 weblate createadmin --password <密码> 或 changepassword 命令初始化。

WEBLATE_ADMIN_PASSWORD 的每次重启重置行为【实测】：只要该变量存在，每次主服务启动都会执行首启日志里可见的 Updating admin user password (unset WEBLATE_ADMIN_PASSWORD to disable)...，把 admin 密码重置回变量值。管理员自行改密后，需把该变量从编排移除再 up -d，否则改密无效。

WEBLATE_REGISTRATION_OPEN【实测】：自助注册开关，默认 1（开放）。本文设 1 后实测注册页 GET /accounts/register/ 返回 200；封闭团队/内网实例改 0 关闭注册页。

WEBLATE_REQUIRE_LOGIN【实查】：设为 1 后整站强制登录（私有化部署常用），官方样例中给出 WEBLATE_REQUIRE_LOGIN=1 的注释形态。

5.3 数据库参数（POSTGRES_*）

【实测】本文 POSTGRES_HOST=database、库名/账号 weblate 全链路可用：首启迁移完成、list_versions 正常执行、Celery 连接日志 Connected to redis://cache:6379/1 之外的数据库操作全部正常。两处库名变量（POSTGRES_DATABASE 与 POSTGRES_DB）值必须一致，否则首启迁移找不到库。

⚠️ Weblate 仅支持 PostgreSQL，勿尝试 MySQL/MariaDB（官方文档明确不保证支持质量）。数据库侧的数据目录挂载点自 PostgreSQL 18 镜像起为 /var/lib/postgresql（排障实录见《Weblate Docker Compose 部署指南》FAQ Q1）。

5.4 缓存与队列参数（REDIS_*）

【实测】本文 REDIS_HOST=cache、REDIS_DB=1 下 Celery worker 正常连上队列（主服务日志实测行：Connected to redis://cache:6379/1），后台任务（提交、通知）与页面缓存工作正常。官方文档明确：容器化运行时 Valkey/Redis 为必需组件，必须提供连接参数。

5.5 邮件参数（EMAIL_*）

【实测】邮件未配置时的真实故障形态——本文 WEBLATE_EMAIL_HOST=127.0.0.1（容器内无 SMTP），执行测试发信命令：

docker compose exec weblate weblate sendtestemail root@example.com

实测输出（尾部）：

  File "/opt/python/cpython-3.14.8-linux-x86_64-gnu/lib/python3.14/socket.py", line 874, in create_connection
    raise exceptions[0]
  File "/opt/python/cpython-3.14.8-linux-x86_64-gnu/lib/python3.14/socket.py", line 859, in sock.connect(sa)
ConnectionRefusedError: [Errno 111] Connection refused

定位：Connection refused 即 SMTP 地址/端口不可达（本文是有意不配 SMTP 的预期现象）。生产配置企业 SMTP 后，用同一条 sendtestemail 命令即可验证通道；若服务器要求 TLS 而你未开 WEBLATE_EMAIL_USE_TLS，会得到超时或握手类错误，按此排查。

5.6 HTTPS 与反向代理参数

【实查】以上四项为官方文档「SSL configuration should match your SSL termination setup」一节的标准组合：反代终结 TLS 时四项配套使用；直连 HTTPS（无反代）时只设 WEBLATE_ENABLE_HTTPS=1。实测部署走 HTTP 8143 未启用该组，值与组合以官方文档为准（2026-10-21 实查）。

5.7 行为与限额参数

WEBLATE_COMMIT_PENDING_HOURS【实查】：新建组件的「待提交译文多久后自动提交」默认小时数（对应组件设置 COMMIT_PENDING_HOURS）。未设置时组件按各自默认（24 小时）执行；对要求翻译及时入库的团队可调小。

WEBLATE_AUTO_UPDATE【实查】：仓库自动更新策略。官方文档实测级描述：默认 false 时每天拉取远程变更但不合并进工作副本（注意并非完全关闭每日更新）；设 true 才会把远程变更合并进工作副本。配合 webhook（GitHub/GitLab 推送钩子）可实现近实时同步。

WEBLATE_API_RATELIMIT_ANON / WEBLATE_API_RATELIMIT_USER【实查】：REST API 限流，官方默认匿名 100/day、认证用户 5000/hour；CI 大量调用 API 时留意匿名限额（应携带 API key 走认证通道）。另有 *_OVERRIDES 变体可按视图覆盖。

WEBLATE_DATABASE_BACKUP【实查】：每日数据库备份格式，默认 plain（SQL 文本）。内置备份会写入数据盘，需保证 /app/data 磁盘余量充足。

WEBLATE_DEFAULT_COMMITER_NAME / WEBLATE_DEFAULT_COMMITER_EMAIL【实查】：翻译提交写入 Git 仓库时的默认提交者身份，未设时用 Weblate <noreply@weblate.org>。

六、生产配置模板

适用场景：8 GB 内存、SSD、50 人以内翻译团队、反代终结 TLS 的公网实例。在官方编排 environment: 基础上叠放：

      WEBLATE_DEBUG: "0"
      WEBLATE_SITE_DOMAIN: weblate.example.com
      WEBLATE_ALLOWED_HOSTS: weblate.example.com
      WEBLATE_TIME_ZONE: Asia/Shanghai
      WEBLATE_REGISTRATION_OPEN: "0"
      WEBLATE_ENABLE_HTTPS: "1"
      WEBLATE_IP_PROXY_HEADER: HTTP_X_FORWARDED_FOR
      WEBLATE_SECURE_PROXY_SSL_HEADER: HTTP_X_FORWARDED_PROTO,https
      WEBLATE_SERVER_EMAIL: weblate@example.com
      WEBLATE_DEFAULT_FROM_EMAIL: weblate@example.com
      WEBLATE_EMAIL_HOST: smtp.example.com
      WEBLATE_EMAIL_PORT: "587"
      WEBLATE_EMAIL_HOST_USER: weblate@example.com
      WEBLATE_EMAIL_HOST_PASSWORD: 请改为你的SMTP口令
      WEBLATE_EMAIL_USE_TLS: "1"
      WEBLATE_ADMIN_PASSWORD: ""
      WEBLATE_HIDE_VERSION: "1"
      POSTGRES_PASSWORD: 请改为强口令
      REDIS_DB: "1"

配套说明：WEBLATE_ADMIN_PASSWORD 置空以停用「每次重启重置密码」；POSTGRES_PASSWORD 与数据库侧 POSTGRES_PASSWORD 同步改；WEBLATE_EMAIL_HOST_PASSWORD 按官方样例要求不加引号；改完执行 docker compose up -d 重建生效，sendtestemail 验证邮件通道。

七、常见问题（FAQ）

Q1：改了环境变量为什么没生效？

restart 不重读编排配置。环境变量改动必须 docker compose up -d（Compose 检测到 environment 变化会 Recreate 服务）；数据盘 settings-override.py 的改动才用 restart。生效后用 3.1 的 env 与 3.2 的 shell 打印核对两层值。

Q2：settings-override.py 写错导致服务起不来怎么办？

入口脚本加载覆盖文件遇语法错误会中断启动。先用宿主机 Python 校验语法：python3 -m py_compile /opt/weblate/data/weblate/settings-override.py，修正后 docker compose restart weblate。

Q3：管理员改密后又被改回去了？

WEBLATE_ADMIN_PASSWORD 存在期间每次重启都会重置 admin 密码（首启日志实测行见《Weblate Docker Compose 部署指南》4.3）。把该变量从编排移除或置空后重建，再走 weblate changepassword 类命令自助改密。

Q4：注册页想让部分人注册、又不想全公开？

WEBLATE_REGISTRATION_OPEN=0 关闭自助注册后，管理员可在管理后台为用户手工开户或配置 GitHub/GitLab 等第三方认证登录（WEBLATE_SOCIAL_AUTH_GITHUB_KEY/SECRET 等变量，官方样例已列出占位）。

Q5：API 调用被限流（429）？

默认匿名 100/天、认证用户 5000/小时。CI 场景务必携带 API key（认证通道），或用 WEBLATE_API_RATELIMIT_ANON/USER 调高限额。

八、参考链接

• 官方 Docker 环境变量总表：https://docs.weblate.org/en/latest/admin/install/docker.html#generic-settings
• 官方编排样例 environment 文件：https://github.com/WeblateOrg/docker-compose
• Django 设置说明：https://docs.weblate.org/en/latest/admin/settings.html
• API 限流说明：https://docs.weblate.org/en/latest/admin/authentication.html#api-rate-limiting
• 部署过程：《Weblate Docker Compose 部署指南》
• 平台认知：《Weblate 介绍与选型指南》
• CLI 与管理命令：《Weblate 2026.10.1 常用 CLI 命令与工具详解》