Mathesar 自托管部署指南:用 Docker Compose 分钟级搭建 Postgres 数据协作平台
Mathesar 自托管部署指南:用 Docker Compose 分钟级搭建 Postgres 数据协作平台
Mathesar 是一个 100% 开源、完全自托管的 Web 应用,通过电子表格风格的界面让任意技术水平的用户直接查看、编辑、查询和协作管理 PostgreSQL 数据。本文以仓库根目录的 README.md 为主线,完整覆盖项目状态、Docker Compose 安装流程、x-config 环境变量配置、权限模型与核心功能特性,并结合 docker-compose.yml、Caddyfile、Dockerfile 等仓库文件给出部署层面的源码级解析,读完即可在自己的服务器上独立部署并定制一个可接入生产数据库的 Mathesar 实例。
项目定位与当前状态
README 对 Mathesar 的核心描述是:它“empowers users of all technical skill levels to view, edit, query, and collaborate on data with a familiar spreadsheet-like interface, with no code needed”(让任意技术水平的用户以熟悉的电子表格界面,免代码地查看、编辑、查询和协作数据)。其工程定位有几点值得先明确:
- 直接操作 Postgres,无额外抽象层:Mathesar 直接对接 PostgreSQL 的 databases、schemas、tables,UI 中的 “Relationships” 在数据库中就是外键,数据模型与 Postgres 对象一一对应;
- 自托管,数据不出服务器:因为它部署在你的基础设施内,数据始终留在你的机器上,可“在数分钟内完成部署并融入现有基础设施”;
- Postgres 原生访问控制:权限体系完全基于 Postgres 的 roles 与 privileges,不引入额外的权限系统;
- 项目状态:README 中的 Status 一栏显示 Public Alpha 与 Public Beta 均已勾选,当前处于 public beta 阶段——官方原话是 “Stable and feature-rich enough to implement in production”(功能已足够丰富,可用于生产实现),但 “Public: Widely used in production environments” 尚未勾选。
项目由 Mathesar Foundation(一家 501(c)(3) 非营利组织)维护,采用 GPLv3 协议开源(见 LICENSE),同时包含 MIT 许可的第三方模块衍生代码,清单见 THIRDPARTY 与 LICENSES 目录。
技术栈与仓库结构总览
结合 DEVELOPER_GUIDE.md 的 Stack 一节,Mathesar 的完整技术栈为:
| 层 | 技术 | 仓库位置 |
|---|---|---|
| 数据存储 | PostgreSQL | db/(低层数据库交互代码)、db/sql/(PL/pgSQL 应用逻辑) |
| 后端 | Python + Django + SQLAlchemy + DRF | mathesar/(Django 应用与 API,即 “service layer”)、config |
| 前端 | Svelte + TypeScript | mathesar_ui/ |
| 运行时 | Gunicorn + Caddy(反向代理/SSL) | Dockerfile、Caddyfile |
其中有一个从源码结构可以印证的关键事实:相当一部分应用逻辑直接实现于数据库层。db/sql/README.md 明确写道 “A substantial amount of Mathesar's application logic is implemented directly in the PostgreSQL database layer”(大量应用逻辑直接实现在 PostgreSQL 数据库层),以 PL/pgSQL 编写,并安装三个内部 schema:
msar:Mathesar 专属功能的主 schema,存放核心函数;__msar:已弃用的遗留 schema,建议避免使用;mathesar_types:存放用户可在自己表中使用的自定义类型(后文“自定义数据类型”特性的实现基础)。
SQL 层代码通过 db/sql/run_tests.sh 使用 pgTAP 框架测试。理解这一点对于部署者很重要:Mathesar 不是“连上库就结束”,而是在目标库中安装了一套 SQL 扩展层,卸载或升级时都需要考虑这些内部对象。
用 Docker Compose 安装 Mathesar
README 的 “Install Mathesar” 章节将安装指向官方文档站;而仓库内的 docs/docs/administration/install-via-docker-compose.md 与根目录的 docker-compose.yml 给出了可直接执行的完整流程。以下按仓库实际文件内容整理。
前置条件
docker-compose.yml 文件头部的注释明确了环境要求:
- 操作系统:Linux、Mac、Windows(WSL);
- Docker v23 及以上(
docker version查看); - Docker Compose v2.10 及以上(
docker compose version查看); - 部分 Docker 配置下可能需要用
sudo执行命令;目前不支持 rootless 模式运行 Docker。
三步完成安装
第 1 步:获取 compose 文件。 官方建议下载与当前版本对应的 docker-compose.yml;仓库根目录的 docker-compose.yml 本身即可作为生产可用配置(文件头注释称其为 “a viable production setup for Mathesar”)。
第 2 步:配置 x-config 环境变量。 这是 Mathesar 部署的核心配置区,仓库中的实际定义如下(docker-compose.yml 第 32–95 行):
x-config: &config
# (Optional) Replace 'http://localhost' with custom domain(s) e.g.
# 'yourdomain.com, 127.0.0.1' to manage the host(s) at which you want to
# access Mathesar over http or https
DOMAIN_NAME: ${DOMAIN_NAME:-http://localhost}
# (Optional) Replace 'mathesar_django' with any custom name for the internal
# database managed by mathesar web-service
POSTGRES_DB: ${POSTGRES_DB:-mathesar_django}
# (Optional) Replace 'mathesar' with any custom username for the
# aforementioned database
POSTGRES_USER: ${POSTGRES_USER:-mathesar}
# (Optional) Replace 'mathesar' with any custom password
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mathesar}
# (Optional) Replace 'mathesar_db' with the name of the host running postgres
POSTGRES_HOST: ${POSTGRES_HOST:-mathesar_db}
# (Optional) Replace '5432' with the port on which postgres is running
POSTGRES_PORT: ${POSTGRES_PORT:-5432}
各变量语义(依据 compose 文件内嵌的 ADDITIONAL INFO 注释):
| 变量 | 默认值 | 含义 |
|---|---|---|
DOMAIN_NAME |
http://localhost |
允许通过 http(80)/https(443) 访问 Mathesar 的域名列表,并为这些域名自动创建 SSL 证书;多域名用逗号分隔,如 yourdomain.com, *.subdomain.com, 127.0.0.1 |
POSTGRES_DB |
mathesar_django |
Mathesar 内部数据库(存放元数据)的名称 |
POSTGRES_USER |
mathesar |
内部数据库的超级用户 |
POSTGRES_PASSWORD |
mathesar |
上述用户的密码 |
POSTGRES_HOST |
mathesar_db |
Postgres 主机:可以是 compose 服务名、TCP 地址(如 host.docker.internal)或 Unix socket 路径(如 /var/run/postgresql) |
POSTGRES_PORT |
5432 |
Postgres 监听端口 |
需要特别理解的是:这组 POSTGRES_* 变量配置的是 Mathesar 自己的内部元数据库(mathesar_django),而不是你想管理的业务库。业务库是在 Mathesar 的 UI 中通过 “Connect Database” 对话框事后连接的——这也正是 README 特性列表中 “Connect to an existing Postgres database or set one up from scratch”(连接已有 Postgres 库或从零创建一个)的含义。若要使用外部 Postgres 服务器承载内部库,文档 install-via-docker-compose.md 给出了具体步骤,包括先在外部服务器上 psql -c 'create database mathesar_django;',以及关于 Docker 主机网络(host.docker.internal、172.17.0.1)和 Unix Socket 挂载(把 /var/run/postgresql 挂进容器)的注意事项。
第 3 步:启动并初始化账户。
docker compose -f docker-compose.yml up
服务起来后访问 localhost(或你配置的域名),首次打开会提示创建管理员账户,按屏幕指引完成即可。日常启停命令为:
docker compose -f docker-compose.yml up -d # 启动(去掉 -d 可查看容器日志)
docker compose -f docker-compose.yml down # 停止并释放端口
compose 文件中的三个服务与数据卷
docker-compose.yml 定义了三个容器,其架构关系如下:
service(Web 服务):基于官方镜像mathesar/mathesar:latest,加载生产配置DJANGO_SETTINGS_MODULE=config.settings.production;仅expose 8000给容器网络,不向宿主机直接开放(由 Caddy 统一入口);自带基于curl -f http://localhost:8000/healthz/ready/的健康检查;depends_on: db且要求service_healthy,保证数据库就绪后才启动。关键环境变量还包括:ALLOWED_HOSTS:默认*,因为域名访问控制交由 Caddy 负责;DEBUG:默认false;SECRET_KEY:留空时自动生成并持久化到 volume;若运行在 serverless 或临时文件系统环境,必须显式设置以保证跨构建持久;WEB_CONCURRENCY:Gunicorn worker 数,默认 3,官方建议高性能机器上调为2 * $(NUM_CORES) + 1;PER_USER_DATABASES_ENABLED:实验特性,开启后每个新用户会在内部库服务器中获得同名角色并自动创建、连接一个其拥有的数据库。
db(PostgreSQL):使用pgautoupgrade/pgautoupgrade:17-bookworm镜像(PostgreSQL 17,带自动升级能力),数据卷挂载到./msar/pgdata;同样只expose 5432给容器网络。caddy-reverse-proxy(反向代理):基于 Mathesar 定制的 Caddy 镜像mathesar/mathesar-caddy:latest,映射宿主机的 80/443 端口,负责路由请求、服务静态文件与用户上传的数据文件,并为DOMAIN_NAME中列出的域名自动签发 SSL 证书。
运行后会在当前目录自动生成 msar/ 目录持久化关键数据(来自 compose 文件的 VOLUMES 注释):
msar
├── caddy/ # Caddy 的证书、密钥等信息
├── media/ # 用户上传的数据文件(.csv/.tsv)
├── pgdata/ # PostgreSQL 数据
├── secrets/ # SECRET_KEY 等秘密信息
└── static/ # Mathesar 静态文件
自定义域名与 HTTPS
若要让 Mathesar 可经互联网访问,需先确保域名的 DNS 指向安装机器的公网 IP,再把域名加入 DOMAIN_NAME,例如:
DOMAIN_NAME: ${DOMAIN_NAME:-yourdomain.org, yoursubdomain.example.org}
重启容器后生效。这个机制的底层实现在 Caddyfile 中可以看得非常清楚:
{$DOMAIN_NAME} {
log {
output stdout
}
respond /caddy-health-check 200
encode zstd gzip
handle_path /media/* {
@downloads {
query dl=*
}
header @downloads Content-disposition "attachment; filename={query.dl}"
file_server {
precompressed br zstd gzip
root {$MEDIA_ROOT:/code/.media/}
}
}
handle_path /static/* {
file_server {
precompressed br zstd gzip
root {$STATIC_ROOT:/code/static/}
}
}
reverse_proxy mathesar_service:8000
}
可以看到 Caddy 直接以 DOMAIN_NAME 作为站点匹配条件(因此该变量决定哪些域名能进入该站点、并据此自动申请证书),对 /media/*(用户上传文件,支持带 ?dl= 查询参数的下载)和 /static/* 用本地 file_server 提供带 br/zstd/gzip 预压缩的响应,其余请求全部反向代理到 mathesar_service:8000。
此外 compose 文件还预留了若干可选开关,均通过 x-config 注入:FILE_STORAGE_DICT(以环境变量方式配置 S3 兼容文件存储后端,替代 file_storage.yml 文件挂载)、SSO_CONFIG_DICT(以环境变量方式配置单点登录,旧名 OIDC_CONFIG_DICT 仍兼容)、REQUIRE_SSO_LOGIN(设为 true 禁用密码登录、强制 SSO)、MATHESAR_DJANGO_ADMIN_ENABLED(启用 Django 内置 admin,不影响 Mathesar 自己的 /administration/ 页面)、MATHESAR_INSTANCE_NAME / MATHESAR_AUTH_LOGO_URL(登录页品牌定制)以及登录页文案、服务条款/隐私政策链接等。
镜像构建:Dockerfile 做了什么
从 Dockerfile 的多阶段构建可以了解生产镜像的内部构造:
- 基础层为
python:3.14-bookworm,安装 gettext(翻译编译所需)等依赖; build_deps阶段安装开发依赖并执行python manage.py compilemessages编译翻译文件,再安装 Node 18 用于前端构建;pre_production阶段调用build-scripts/package/package.py打包源码;production_base解包并只安装运行时requirements.txt;minimal目标以config.settings.production运行、以非 root 用户(uid 1000)启动;production目标(compose 中使用的latest对应此类完整生产形态)还会在镜像内安装 PostgreSQL 17(PGDATA=/var/lib/postgresql/mathesar),以支持-fnse参数启动——即 Mathesar 容器自身还能兜底运行一个数据库,配合 build-scripts/bin/mathesar.sh 中以 Gunicorn 拉起 Web 服务的逻辑(该脚本select_gunicorn优先使用虚拟环境内的 gunicorn 可执行文件,并支持--no-venv使用系统 gunicorn)。
原生 Postgres 访问控制
README 将 “Postgres-based access control: Use existing Postgres roles within Mathesar's UI, or set up your own” 列为特性之一。docs/docs/user-guide/access-control.md 解释了这套体系的四个组成部分:
- Mathesar Users:每个使用者拥有独立账户与密码,admin 用户拥有连接数据库、管理用户等高层操作权限;
- PostgreSQL roles:数据库内权限授予到 role 级别,Mathesar 遵循这些权限并在 UI 中提供查看与修改能力;
- Stored Roles:Mathesar 代为保管用于向 PostgreSQL 认证的角色的密码;
- Collaborators:admin 将用户添加为某数据库的协作者,并为其指定一个 Postgres role——多个 Mathesar 用户可以共享同一个 role,也可以一人一个专用 role。
这意味着 Mathesar 的权限边界与 PostgreSQL 的权限边界完全重合:你在 Mathesar 界面上为某个 role 在表级配置的 read-only / custom 权限,落到数据库里就是标准的 GRANT/REVOKE 对象。对已有 Postgres 生产库的运维方而言,这是它区别于“带自己权限系统的中间件”类工具的关键点。
核心功能特性
以下特性清单完整继承自 README 的 Features 章节,并逐一给出在仓库中的对应落点:
- Built on Postgres(基于 Postgres 构建):连接已有数据库或从零创建。UI 入口即 “Connect Database” 对话框(见上文第一张截图),可在创建时选择内置示例数据集。
- Install in minutes(分钟级安装):Docker 一键部署,融入现有基础设施——即本文第二节的 compose 流程。
- Postgres-based access control(基于 Postgres 的访问控制):上文已详述。
- Interoperable with other tools(与其他工具互操作):因为它只操作原生 Postgres 对象,与 Postgres 生态的其他工具可以和谐共存。
- Set up your data models(数据建模):在 UI 中创建和更新 Postgres schemas 与 tables。
- Data entry(数据录入):电子表格风格界面进行增删改查。
- Filter, sort, and group(过滤、排序、分组):快速从不同维度切分数据。
- Query builder(查询构建器):用 Data Explorer 在不懂 SQL 和 join 的情况下构建查询;查询在 Mathesar 中称为 Exploration(探索)。
- Forms(表单):构建并通过唯一链接分享表单收集数据,提交内容自动保存为新记录。
- Import and export data(数据导入导出):支持 CSV/TSV 等数据文件进出,compose 卷中的
msar/media/即存放用户上传的数据文件。 - Schema migrations(模式迁移):两步点击即可在表间迁移列(“Transfer columns between tables in two clicks”),对应后端
mathesar/rpc/data_modeling.py等 RPC 接口。 - Uses Postgres features(使用 Postgres 原生特性):Mathesar 直接使用并操作 Postgres 的 schemas、主键、外键、约束与数据类型,UI 中的 “Relationships” 即数据库中的外键。
- Custom data types(自定义数据类型):邮箱、URL 等自定义类型在数据库层面做校验。
其中两条特性可以深入到源码印证:
表单(Forms):仓库中表单体系贯穿前后端——后端模型见 mathesar/migrations/0007_form_formfield.py 与 mathesar/rpc/forms.py,前端在 mathesar_ui/src/systems/data-forms/ 与组件库 mathesar_ui/src/component-library/form-builder/ 中实现;表单页面(构建器、填写页)分别对应 README 截图 09 与 10,公共链接访问路径由 mathesar_ui/src/routes/SharedFormRoute.svelte 承接。
自定义数据类型:README 所称的 “validated at the database level” 正是 mathesar_types schema 的落地。docs/docs/user-guide/data-types.md 说明:mathesar_types.email 是 text 上的 PostgreSQL domain,附带校验输入为合法邮箱的逻辑;mathesar_types.uri 同理用于 URL 校验;mathesar_types.money 是 numeric 上的 domain,用于支持带货币符号的 CSV 导入与“货币符号”元数据字段。这些 domain 由 db/sql/01_msar_types.sql 等在首次连接目标库时安装,类型转换与推断逻辑则见同目录的 45_msar_type_casting.sql、46_msar_type_inference.sql。这正是 “无额外抽象” 设计的典型体现——校验发生在 PostgreSQL 本身,任何直接连库的工具都能受益。
开发者视角:本地开发、测试与故障排查
README 的 “Contribute to Mathesar” 指向 CONTRIBUTING.md,而 DEVELOPER_GUIDE.md 给出了完整的本地开发链路,对希望 fork 部署或提交代码的读者同样实用:
cp .env.example .env
docker compose -f docker-compose.dev.yml up dev-service
启动后以 admin / password 登录 http://localhost:8000/,代码改动会自动热更新。测试体系分三层:
- Python 后端测试(pytest):
docker exec mathesar_service_dev pytest mathesar/ db/,可用-k "test_name"按名称过滤; - SQL 层测试(pgTAP):
docker exec mathesar_dev_db /bin/bash sql/run_tests.sh; - 场景级 API 测试:
./run_api_tests.sh。
前端开发规范见 mathesar_ui/README.md,整体架构(Svelte stores 的不可变类模式、嵌套 store 模式、API 层组织方式)有专门的 mathesar_ui/ARCHITECTURE.md 文档;全栈 lint 可用根目录 ./lint.sh。
故障排查方面,README 指向 TROUBLESHOOTING.md,DEVELOPER_GUIDE 中另有两个高频问题值得部署者留意:
- 宿主机 5432 端口被占用:报错
listen tcp4 0.0.0.0:5432: bind: address in use时,先停掉宿主机的 Postgres(如sudo service postgresql stop)再启动 Mathesar; psycopg.errors.InvalidFunctionDefinition:开发分支修改了函数参数名导致旧函数无法更新,需要从目标库中删除msar与__msar两个 schema 后重启服务。
许可与第三方依赖
Mathesar 以 GPLv3 协议开源(LICENSE),同时包含基于 MIT 许可的第三方开源模块衍生代码,具体清单及各自许可证见 THIRDPARTY 文件与 LICENSES 目录(当前收录了 javascript-detect-element-resize、react-virtualized-auto-sizer、react-window、svelte-toast 四组许可证副本)。自托管部署时应留意 GPL 协议对分发的约束,以及这些 MIT 衍生模块的归属说明。
小结:Mathesar 的部署路径可以概括为——一个 docker-compose.yml 起三个容器(Gunicorn Web 服务、PostgreSQL 17、Caddy 反向代理),一组 x-config 环境变量完成域名、内部库与可选特性的配置,msar/ 卷持久化全部关键状态;而它区别于同类产品的设计内核是“无额外抽象”:权限是 Postgres roles,关系是外键,自定义类型是 mathesar_types 下的 domain,应用核心逻辑是库内的 PL/pgSQL 函数。理解这两层,就理解了如何正确地部署、定制和向社区贡献 Mathesar。




