Mathesar 0.12.0 配置参数详解

目标：把 Mathesar 0.12.0 的全部配置入口讲透——环境变量的读取机制、每个参数的默认值/取值格式/生效方式，以及生产环境推荐配置。所有映射关系逐条核对自 0.12.0 镜像内 Django settings 源码（config/settings/common_settings.py、production.py），所有默认值取自运行实例的 printenv 全量导出，改名生效过程做了真实的修改-验证-回滚实验。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Mathesar：0.12.0（mathesar/mathesar:0.12.0，经 Caddy 反代提供 Web 服务，宿主入口 http://localhost:8128）
• 应用运行时：Python 3.14.6 + Django 4.2.29 + Gunicorn（WEB_CONCURRENCY=3，实测进程 1 主 + 3 worker）
• settings 模块：config.settings.production（继承 config.settings.common_settings.py，共 357 行；production.py 仅 20 行覆盖项）
• 元数据库：PostgreSQL 17.6（mathesar_django）
• 部署形态：官方 docker compose 三服务（参数注入点为 compose environment）

二、前置条件

• 一个已部署并可访问的 Mathesar 0.12.0 实例（部署过程见《Mathesar 0.12.0 Docker Compose 部署指南》，下文验证命令以该部署的 8128 端口为例）；
• 能对部署目录执行编辑与 docker compose 命令（参数修改的最小权限要求）；
• 管理员账号一个（本文演示用 admin / q1w2e3r4，用于在 Web 端核对部分运行时状态）。

三、参数查看与修改方式

3.1 查看生效参数的三条途径

途径一：直接读运行实例的环境变量（最权威，含 compose 默认值展开后的结果）：

cd /opt/mathesar && docker compose exec service printenv | sort

实测回显（本实例全量，已剔除 PATH 等无关项）：

ALLOWED_HOSTS=*
DEBUG=false
DJANGO_SETTINGS_MODULE=config.settings.production
DOMAIN_NAME=http://localhost
FILE_STORAGE_DICT={}
MATHESAR_AUTH_LOGO_URL=
MATHESAR_DJANGO_ADMIN_ENABLED=false
MATHESAR_DOCKER_IMAGE=true
MATHESAR_INSTANCE_NAME=Mathesar
MATHESAR_LANDING_PAGE_URL=
MATHESAR_LOGIN_PAGE_BACKGROUND=
MATHESAR_LOGIN_PAGE_TEXT_DICT={}
MATHESAR_PRIVACY_POLICY_URL=
MATHESAR_TERMS_OF_SERVICE_URL=
OIDC_CONFIG_DICT={}
PER_USER_DATABASES_ENABLED=false
PGDATA=/var/lib/postgresql/mathesar
PG_MAJOR=17
POSTGRES_DB=mathesar_django
POSTGRES_HOST=mathesar_db
POSTGRES_PASSWORD=mathesar
POSTGRES_PORT=5432
POSTGRES_USER=mathesar
REQUIRE_SSO_LOGIN=false
SECRET_KEY=
SSO_CONFIG_DICT={}
WEB_CONCURRENCY=3

注意两处「看着空、实则有值」的参数：SECRET_KEY= 为空是因为走自动生成文件机制（见 4.3 节）；PGDATA/PG_MAJOR/MATHESAR_DOCKER_IMAGE 是镜像内置变量（标记镜像身份与 PG 目录约定），不属于用户可调参数。

途径二：读 settings 解析结果（验证环境变量是否被正确解析成 Django 配置）：

docker compose exec service python -c "
import os, django
os.environ.setdefault('DJANGO_SETTINGS_MODULE','config.settings.production')
django.setup()
from django.conf import settings
print('ALLOWED_HOSTS =', settings.ALLOWED_HOSTS)
print('DEBUG =', settings.DEBUG)
print('SECRET_KEY len =', len(settings.SECRET_KEY))
print('REQUIRE_SSO_LOGIN =', settings.REQUIRE_SSO_LOGIN)
print('PER_USER_DATABASES_ENABLED =', settings.PER_USER_DATABASES_ENABLED)
"

实测回显：

ALLOWED_HOSTS = ['.localhost', '127.0.0.1', '[::1]', '*']
DEBUG = False
SECRET_KEY len = 50
REQUIRE_SSO_LOGIN = False
PER_USER_DATABASES_ENABLED = False

（ALLOWED_HOSTS 列表里前三个元素是代码内拼接的默认值，第四个 * 来自环境变量；SECRET_KEY 长度 50 即自动生成的文件内容。）

途径三：健康检查与页面层验证——/healthz/ready/ 返回 {"status": "ok"}（实测）说明应用配置链路完好；登录页 HTML 中可见 MATHESAR_INSTANCE_NAME 的实际效果（见 3.3 实验）。

3.2 修改方式

Mathesar 0.12.0 的用户可调参数全部通过环境变量注入，标准改法是改 compose 的 environment（或宿主 .env 文件，compose 变量插值会读取），然后重建服务：

cd /opt/mathesar
vi docker-compose.yml          # 修改 service 服务 environment 下的目标变量
docker compose up -d service   # 配置变更需要重建实例才能生效

⚠️ 注意：Django settings 在进程启动时读取一次环境变量，改完必须 up -d 重建（而非 restart 语义上的软重载）；up -d 检测到 environment 变化会自动重建容器。

3.3 修改-生效-回滚实验（实测）

以 MATHESAR_INSTANCE_NAME（站点显示名）为例做一次完整闭环。第一步，用环境变量覆盖默认值并重建：

cd /opt/mathesar
MATHESAR_INSTANCE_NAME=数据工作台 docker compose up -d service

实测回显（重建过程）：

 Container mathesar_db Healthy
 Container mathesar_service Starting
 Container mathesar_service Started

第二步，验证生效——登录页 Logo 的 alt 文本会带上实例名：

curl -s http://localhost:8128/auth/login/ | grep -oE 'alt="[^"]*Logo"'

实测回显：

alt="数据工作台 Logo"

（对比修改前同一命令的回显为 alt="Mathesar Logo"；页面 <title> 固定为 Mathesar - Login，不受该参数影响。）第三步，回滚默认值：

docker compose up -d service   # 不再注入变量，回落 compose 默认 Mathesar
curl -s http://localhost:8128/auth/login/ | grep -oE 'alt="[^"]*Logo"'
# 实测回显：alt="Mathesar Logo"

四、参数总览与核心参数分类详解

4.1 参数总览

0.12.0 用户可调参数按域分四类：

4.2 站点身份与展示类

DOMAIN_NAME（compose 默认 http://localhost）——最重要的站点参数。它同时喂给两个组件：Caddy 把它当作站点名（Caddyfile 首行实测为 {$DOMAIN_NAME} {，整个反代与静态文件路由都挂在这个站点块内）；Django 侧用于构造绝对链接。带协议书写（http:// 或 https://）；若用 HTTPS 反代，必须写 https:// 形式并保持 Caddy 到应用的 X-Forwarded-Proto 传递（production.py 实测含 SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')，即应用信任反代传来的该头判断 https）。

MATHESAR_INSTANCE_NAME（默认 Mathesar）——界面显示名，settings 映射 os.environ.get('MATHESAR_INSTANCE_NAME') or 'Mathesar'；生效验证见 3.3 实验。

MATHESAR_LANDING_PAGE_URL（默认空）——设置后，未登录用户访问根路径直接重定向到该 URL 而非登录页（views 源码实测：if settings.MATHESAR_LANDING_PAGE_URL: return redirect(...)）。适合「Mathesar 作为内部门户一个子功能」的集成场景。

MATHESAR_LOGIN_PAGE_TEXT_DICT / MATHESAR_LOGIN_PAGE_BACKGROUND / MATHESAR_AUTH_LOGO_URL——登录页文案（JSON dict，也支持挂载 /code/login_page.yml 文件，settings 经 load_login_page_text_config(env_value, config_file=BASE_DIR/'login_page.yml') 双通道读取）、背景图与 Logo 地址。

MATHESAR_TERMS_OF_SERVICE_URL / MATHESAR_PRIVACY_POLICY_URL（默认空）——注册/登录页底部条款链接，面向对外服务场景。

4.3 应用安全与运行类

SECRET_KEY（compose 默认空）——Django 会话/CSRF 签名密钥。留空不报错：common_settings.py 实测逻辑为「环境变量没有值时，向 /code/.secrets/ 目录写 secret_key.txt（写入模式 'x'，文件已存在则复用）」，密钥来源 get_random_secret_key()。本实例实测：文件存在、50 字节、settings 读回长度 50。同时 SALT_KEY 直接取 SECRET_KEY（源码 SALT_KEY = SECRET_KEY），改密钥会使现有会话与下载链接签名失效——更换时机应安排在低峰并通知用户重新登录。

ALLOWED_HOSTS（compose 默认 *）——Django Host 头白名单。解析实测：按英文逗号切分、逐项去空格（[i.strip() for i in os.environ.get('ALLOWED_HOSTS', default=".localhost, 127.0.0.1, [::1]").split(',')]），应用侧再把代码内默认三项拼在列表头。生产建议从 * 收敛为具体域名：ALLOWED_HOSTS=mathesar.example.com。

DEBUG（compose 默认 false）——解析实测只认 t/true/True 三个值（os.environ.get('DEBUG') in ['t', 'true', 'True']），其余一律 False。生产必须保持 false：DEBUG=True 会暴露配置与错误页细节。

WEB_CONCURRENCY（compose 默认 3）——Gunicorn worker 数。实测进程树：1 个主进程 gunicorn config.wsgi -b 0.0.0.0:8000 --chdir /code --timeout 180 + 3 个 worker（RSS 各约 114 MB，空载总内存约 285 MiB）。调大按「每 worker 约 115 MB 起步」估算内存。

MATHESAR_DJANGO_ADMIN_ENABLED（compose 默认 false）——是否挂载 Django 原生 /admin/ 后台。解析同样只认 t/true/True；settings 源码实测该开关同时控制 INSTALLED_APPS 是否插入 django.contrib.admin 与 config/urls.py 是否注册 admin/ 路由。开启后访问 http://<站点>/admin/ 进入原生后台，可作为忘记密码时的应急通道（见部署篇 FAQ Q6），日常建议关闭。

4.4 数据库连接类

POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_HOST / POSTGRES_PORT（默认 mathesar_django / mathesar / mathesar / mathesar_db / 5432）——元数据库连接。common_settings.py 实测：前三者与 HOST 齐备时才构造 DATABASES['default']，且校验 ENGINE 必须以 django.db.backends.postgresql 开头（否则启动即抛 ValueError）——这从代码层面保证了「元数据库只能是 PostgreSQL」。连接串附带 application_name: "Mathesar Django"（源码实测），在 PG 侧 pg_stat_activity 可按此识别 Mathesar 的元数据连接。

POSTGRES_SSLMODE（代码默认 prefer，官方 compose 未显式暴露）——元数据库 TLS 策略，prefer 即「能加密则加密、不强制」。需要强制 TLS 时在 service 环境显式加 POSTGRES_SSLMODE=require。

💡 技术拓展：PG 的 sslmode 常用取值对比——

取值	行为	适用
disable	不加密	内网可信环境
prefer	优先加密，失败则明文	默认折中（Mathesar 默认值）
require	强制加密但不验证书	有加密需求、无 CA
verify-ca / verify-full	强制加密且验证证书链/主机名	跨网段生产

Mathesar 默认 prefer，与 libpq 习惯一致；本实测实例元数据库走内网，保持默认即可。

边界澄清：以上变量只管「元数据库」。Mathesar 管理的业务库连接不走环境变量，而是运行时通过 Web UI 或 RPC databases.setup.connect_existing / databases.setup.create_new 动态配置（存于元数据库，见部署篇 4.5 与 API 篇）。

4.5 认证与多租户类

SSO_CONFIG_DICT（默认 {}）——0.12.0 的 SSO 规范入口，JSON 格式，同时支持挂载 /code/sso.yml（settings 经 load_sso_config(env_value, config_file=BASE_DIR/'sso.yml') 双通道读取，实测源码）。配置的 OIDC App 注入 allauth 的 SOCIALACCOUNT_PROVIDERS['openid_connect'].APPS，GitHub App 注入 github provider（scope 实测为 user:email、read:user）。settings 还开了 SOCIALACCOUNT_EMAIL_AUTHENTICATION 与 AUTO_CONNECT（同名邮箱自动合并登录），GH provider 配置 SOCIALACCOUNT_QUERY_EMAIL=True 以拉取邮箱。

OIDC_CONFIG_DICT（默认 {}）——旧版入口，读取顺位在 SSO_CONFIG_DICT 之后（源码：os.environ.get('SSO_CONFIG_DICT') or os.environ.get('OIDC_CONFIG_DICT')），官方 compose 注释明确 "deprecated, use SSO_CONFIG_DICT"。存量部署无需急于迁移，两者同时存在时新入口优先。

REQUIRE_SSO_LOGIN（默认 false）——true 时强制 SSO（本地用户名口令登录被关闭）。解析经 resolve_require_sso_login(env_value, sso_config) 统一裁决（环境变量与 SSO 配置共同决定）；该值还会出现在登录页 common-data 的 is_sso_login_required 字段里，前端据此隐藏口令登录表单。

PER_USER_DATABASES_ENABLED（默认 false）——「每用户独立数据库」模式开关（解析只认 t/true/True）。开启后登录页 common-data 的 per_user_databases_enabled 变 true（实测 JSON 字段存在），适合给每个用户发独立库的托管型用法；常规团队共享场景保持 false。

4.6 文件存储类

FILE_STORAGE_DICT（默认 {}）——下载链接（表格导出、表单附件等）的文件存储后端配置。实测源码（mathesar/utils/download_links.py）：读取顺位为 file_storage.yml 文件 → FILE_STORAGE_DICT 环境变量（JSON），基于 fsspec URI 寻址（如 file:///、s3://），默认后端键为 default。

MEDIA_ROOT（代码默认 /code/.media/，compose 未显式暴露但 Caddyfile 消费同一变量）——用户上传/导入文件的根目录；Caddyfile 实测 /media/* 路径用 {$MEDIA_ROOT:/code/.media/} 直出文件，因此改这个变量时 caddy 与 service 两个服务要挂同一个宿主目录。

DATA_FILES_STORAGE_BACKEND（代码默认 local，可选 azure）——CSV/TSV 导入文件（data files）的存储后端。settings 源码实测：azure 时切换到 Azure Blob（storages.backends.azure_storage.AzureStorage），凭据走 DefaultAzureCredential，配套变量 DATA_FILES_AZURE_ACCOUNT_NAME、DATA_FILES_AZURE_CONTAINER（默认容器名 mathesar-datafiles）；local 时为 FileSystemStorage。注意这三个变量官方 compose 的 x-config 未默认暴露，需要 Azure 后端时自行加进 service 环境。

4.7 其他

MODE（代码默认 PRODUCTION）——映射为 settings 的 MATHESAR_MODE；DEVELOPMENT 时 STATICFILES_DIRS 切到 UI 源码目录（配合 Vite 热更，MATHESAR_CLIENT_DEV_PORT 默认 3000）。生产部署不要设置。

MATHESAR_ANALYTICS_URL / MATHESAR_INIT_REPORT_URL / MATHESAR_FEEDBACK_URL——匿名使用统计、首次启动报告、用户反馈的上报地址。common_settings 的占位默认值为 https://example.com/*，production.py 实测覆盖为 https://analytics.mathesar.dev/collect-analytics-reports、.../collect-initial-report、.../collect-feedback-message。内网隔离部署可在 service 环境覆盖为自建收集端或无效地址，并用 RPC analytics.disable 关闭上报（见 API 篇方法清单）。

五、生产配置模板

适用场景：8 GB 内存、SSD、几十人团队内网共享一套 Mathesar（元数据库与业务库同机）。在官方 compose 基础上，service 服务的 environment 推荐如下（改动处加注释）：

services:
  service:
    environment:
      <<: *config
      DJANGO_SETTINGS_MODULE: config.settings.production
      DOMAIN_NAME: http://mathesar.internal.example.com   # 对外访问地址，与反代/证书一致
      ALLOWED_HOSTS: mathesar.internal.example.com        # 收敛 Host 白名单
      DEBUG: 'false'
      SECRET_KEY: ${SECRET_KEY}                           # 宿主 .env 注入，避免依赖自动生成文件
      WEB_CONCURRENCY: '4'                                # 4 worker ≈ 460MB 内存预算
      MATHESAR_INSTANCE_NAME: 数据工作台
      POSTGRES_SSLMODE: require                           # 元数据库强制加密
      REQUIRE_SSO_LOGIN: 'false'                          # 接入 OIDC 后改 true

配套建议：宿主 .env 写入 SECRET_KEY=<python3 -c "import secrets;print(secrets.token_urlsafe(50))"> 生成的随机值；msar/ 目录纳入每日备份；内存预算按「service ≈ 115MB × WEB_CONCURRENCY + db ≈ 100MB」估算（本实测空载：service 285.5MiB@3worker、db 83.64MiB、caddy 10.82MiB）。

六、常见问题（FAQ）

Q1：改了环境变量为什么没生效？ settings 只在进程启动时读环境。确认两点：① 用的是 docker compose up -d service（重建）而不是 restart；② 变量确实写进了 compose 的 environment 或宿主 .env（compose 插值只读 .env 与 shell 环境）。验证最终生效值用 3.1 途径二的 settings 读回法，比看进程环境更可靠。

Q2：布尔变量写 True/1/yes 为什么行为不一致？ 实测解析逻辑只有 t/true/True 三个字符串算 true（DEBUG、MATHESAR_DJANGO_ADMIN_ENABLED、PER_USER_DATABASES_ENABLED 同一套逻辑），1/yes 都算 false。建议统一写小写 true/false。

Q3：SECRET_KEY 自动生成文件会丢吗？ 文件在 ./msar/secrets/secret_key.txt（bind mount 到 /code/.secrets/），docker compose down 不会删它；只有手动清空 msar/secrets/ 才会触发重新生成。要跨环境搬迁部署，把这个文件带走即可保持会话有效。

Q4：SSO 配置写 JSON 太长怎么办？ 挂载 /code/sso.yml 文件（service 的 volumes 加一行 - ./sso.yml:/code/sso.yml:ro），settings 会自动读取；环境变量留空不影响文件生效。新旧入口同时配置时 SSO_CONFIG_DICT/sso.yml 通道优先于 OIDC_CONFIG_DICT。

Q5：如何确认当前版本加载的是 production settings？ docker compose exec service printenv DJANGO_SETTINGS_MODULE 实测返回 config.settings.production；该模块在 common_settings 之上覆盖了 MATHESAR_MODE='PRODUCTION' 与三个 analytics 上报地址（production.py 实测全文 20 行），并信任反代的 X-Forwarded-Proto。

七、参考链接

• settings 源码（0.12.0）：https://github.com/mathesar-foundation/mathesar/blob/0.12.0/config/settings/common_settings.py
• production settings：https://github.com/mathesar-foundation/mathesar/blob/0.12.0/config/settings/production.py
• 官方 docker-compose.yml（变量默认值出处）：https://github.com/mathesar-foundation/mathesar/blob/0.12.0/docker-compose.yml
• 本专栏相关：《Mathesar 0.12.0 介绍与选型指南》（架构总览）、《Mathesar 0.12.0 Docker Compose 部署指南》（部署与变量注入实操）、《Mathesar 0.12.0 API 使用详解》（RPC 接口与 analytics.disable 用法）