企业官网建设流程全解析

• 数据库
• 后端
• 前端
• 协作

本文基于 Mathesar 官方文档 try-mathesar-locally.md，介绍如何用一条docker run命令在本机临时拉起 Mathesar 实例进行体验：从启动、访问、创建管理员账号与数据库连接，到进入容器内置的 PostgreSQL 执行 psql、停止/重启容器、删除容器，再到结合仓库源码（Dockerfile、mathesar.sh）理解镜像默认内置的数据库回退机制与启动参数。

一、适用场景与前提

Mathesar 提供了一体化 Docker 镜像mathesar/mathesar，可以在你的机器上直接运行，用于快速试用产品功能。官方文档明确指出，如果只是想在本地玩玩，本文介绍的docker run方式即可；若需要一套更完整、可用于长期运行的自托管部署（含 Caddy 反向代理、独立 db 服务、数据卷持久化），应改用 Docker Compose 安装指南。

前提条件只有一个：已安装 Docker。文档原文标注了一个重要限制：

不适合生产使用。这是一种在本地快速体验 Mathesar 的方式，不适用于保存你在意的数据，也不适合搭建长期安装。

原因可以在 Dockerfile 中得到印证：生产镜像的production阶段通过VOLUME /etc/postgresql/与VOLUME /var/lib/postgresql/声明了匿名数据卷来存放内置数据库数据。没有像 Docker Compose 方案那样显式挂载具名卷（见 docker-compose.yml 中./msar/pgdata等挂载），数据落在 Docker 管理的匿名卷里，容器一删（docker rm配合卷清理或卷随容器移除）数据即不可恢复。

二、启动 Mathesar

1. 在已安装 Docker 的机器上执行：

docker run -it --name mathesar -p 8000:8000 mathesar/mathesar:latest

参数说明：

• -it：交互模式并分配伪终端，日志直接打到当前 shell，方便观察启动过程；
• --name mathesar：为容器命名，后续docker exec/docker start命令都依赖这个名称；
• -p 8000:8000：将容器内 8000 端口（Mathesar Web 服务端口）映射到宿主机 8000 端口。这一点与 Dockerfile 中EXPOSE 8000保持一致；
• mathesar/mathesar:latest：Docker Hub 上的官方镜像，latest标签对应当前发布版本。

2. 浏览器访问http://localhost:8000/，页面会引导你完成两件事：

• 设置管理员用户账号（admin user account）；
• 创建一个数据库连接（connect a Postgres database）。

关于“首次访问引导设置管理员”这一步，源码中有清晰的实现对应关系：路由 mathesar/urls.py 中complete_installation/被 decorators.py 的installation_incomplete装饰器包裹——只要内部数据库中尚不存在任何is_superuser=True的账号，所有未登录请求都会被导向该安装页；表单提交由 complete_installation.py 的CompleteInstallationFormView处理，它会创建一个is_superuser = True的用户并立即执行login()。换言之，“是否已存在超级用户”就是 Mathesar 判断安装是否完成的唯一依据（源码注释原文：“We're currently only identifying if an installation is complete based on if or not a superuser account is present”）。

排障提示：如果本地启动后行为异常，可参考 调试文档，在docker run前加上DEBUG=true环境变量获得更详细的日志与浏览器内错误信息，例如：

DEBUG=true docker run -it --name mathesar -p 8000:8000 mathesar/mathesar:latest

生产环境请勿开启 DEBUG。

三、进入容器内置的 PostgreSQL

文档提供的“本地有用 Docker 命令”第一条是访问数据库：

docker exec -it mathesar sudo -u postgres psql

• 在名为mathesar的容器内以交互方式执行sudo -u postgres psql；
• sudo -u postgres以 PostgreSQL 的postgres系统身份连接（容器内安装了sudo，见 Dockerfile base 阶段的apt-get install列表），因此无需密码即可进入 psql shell。

进入 psql 后，你可以用\l查看数据库、\c mathesar_django连接到 Mathesar 的内部数据库等。之所以能确定存在mathesar_django这个库，是因为容器启动脚本会在初始化内置数据库时显式创建它（详见下一节CREATE DATABASE mathesar_django;）。

镜像里到底装了什么：为什么单容器就能跑

从 Dockerfile 的结构看，镜像采用多阶段构建，默认入口是最后的production阶段：

1. base 阶段：python:3.14-bookworm基础上安装sudo、curl、gnupg、gettext、locales等，并设置MATHESAR_DOCKER_IMAGE='true'与en_US.utf8locale；
2. production_base 阶段：解包打包后的源码，仅安装运行时依赖requirements.txt，EXPOSE 8000；
3. production 阶段（默认 CMD 所在阶段）：额外通过 apt.postgresql.org 安装PostgreSQL 17（ARG BUILD_PG_MAJOR=17），设置PGDATA=/var/lib/postgresql/mathesar，EXPOSE 5432，默认命令为：

CMD ["bash", "./bin/mathesar", "run", "-fnse"]

也就是说，官方镜像是一个“Web 服务 + 内置 PostgreSQL”的单容器一体化部署。这与 Dockerfile 中的minimal阶段（CMD ... run -ne，注释写明“不包含 Django setup 和内置数据库回退的 flag”）形成对照——minimal是纯 Web 服务镜像，而production是带数据库回退能力的一体化镜像。

四、启动脚本源码级解读：mathesar run -fnse在做什么

docker run后容器实际执行的是 build-scripts/bin/mathesar.sh（打包后位于<install_root>/bin/mathesar）。生产镜像传入的组合短选项-fnse含义如下（对照脚本 usage 说明）：

关键调用链在run_mathesar()函数中：

1. 检查必需环境变量：check_required_postgres_env_vars()要求POSTGRES_USER、POSTGRES_HOST、POSTGRES_DB三个变量必须存在。纯docker run场景下没有提供这些变量，因此触发-f的回退分支；
2. 初始化内置数据库：initialize_inbuilt_db()先通过verify_docker_setup()确认MATHESAR_DOCKER_IMAGE与PGDATA已设置，再以PGDATA/PG_VERSION是否非空判断数据库是否已初始化过。若是全新数据目录，则执行：

pg_createcluster -d "${PGDATA}" -p 5432 -u "postgres" "${PG_MAJOR}" mathesar # 临时启动集群后： ALTER USER postgres PASSWORD 'mathesar'; CREATE DATABASE mathesar_django;

最后pg_ctlcluster "${PG_MAJOR}" mathesar start常驻启动内置 PostgreSQL，并导出POSTGRES_USER=postgres、POSTGRES_PASSWORD=mathesar、POSTGRES_HOST=localhost、POSTGRES_PORT=5432、POSTGRES_DB=mathesar_django作为本次会话的连接参数。这解释了为什么容器内sudo -u postgres psql无需密码、以及 psql 中会看到mathesar_django库； 3.Django 安装：-s触发python -m mathesar.install，其实现 mathesar/install.py 会执行migrate建立 Mathesar 自身的 Django 数据表，并在SKIP_STATIC_COLLECTION未开启时执行collectstatic； 4.启动 Gunicorn：最终exec gunicorn config.wsgi -b 0.0.0.0:8000 --chdir <BASE_DIR> --timeout 180。绑定地址与端口在脚本头部固定为MATHESAR_PORT=8000、MATHESAR_ADDR="0.0.0.0"，这也正是-p 8000:8000端口映射的由来；若设置了DEBUG=true，还会追加--log-level=debug。

此外，Mathesar 内置健康检查中间件（mathesar/middleware.py）提供/healthz/live与/healthz/ready端点，Docker Compose 部署中正是用它做健康检查（docker-compose.yml中test: curl -f http://localhost:8000/healthz/ready/）；在单容器试用场景下，你也可以用curl http://localhost:8000/healthz/ready/验证服务是否就绪。

五、停止与再次启动

• 停止：在运行 Mathesar 的 shell 中按Ctrl+C。由于启动脚本最终exec gunicorn（PID 1 即 Gunicorn 进程），中断信号直接终止 Web 服务，容器随之退出。
• 再次启动：

docker start mathesar

容器退出后其文件系统状态（包括PGDATA内置数据库数据）仍然保留，docker start会重新执行容器原生命令，mathesar.sh检测到PGDATA/PG_VERSION已存在（DATABASE_ALREADY_EXISTS='true'），跳过数据库初始化，直接启动已有的 PostgreSQL 与 Web 服务。因此试用期间在 Mathesar 里做的修改在停止/重启后依然可见——但仅限同一容器生命周期内。

六、删除容器（数据一并删除）

文档对此明确警告：

警告：删除容器会同时删除你在 Mathesar 中保存的数据。

删除命令：

docker rm mathesar

执行前请确保容器已停止（docker rm不能删除运行中的容器，需先Ctrl+C或docker stop mathesar）。删除后，之前docker start mathesar也不再可用，如需继续体验需重新docker run。

如果你希望在删除后保留数据库数据，可以在初次docker run时显式命名数据卷并挂载，例如（基于 Dockerfile 中PGDATA=/var/lib/postgresql/mathesar的定义）：

docker run -it --name mathesar -p 8000:8000 -v mathesar_pgdata:/var/lib/postgresql/mathesar mathesar/mathesar:latest

这样即使容器被删除，具名卷mathesar_pgdata仍保留 Postgres 数据目录，可再次docker run时挂回（前提是mathesar_django与 Mathesar 元数据的一致性可接受）。需要说明的是，这是基于源码结构（PGDATA环境变量与内置集群目录）推导的用法，官方文档仅承诺“容器删除即数据删除”的默认行为。

七、与 Docker Compose 部署的关系

八、本地试用操作速查

# 1. 启动 docker run -it --name mathesar -p 8000:8000 mathesar/mathesar:latest # 2. 浏览器访问 http://localhost:8000/ 创建管理员账号并连接数据库 # 3. 进入容器内置 psql docker exec -it mathesar sudo -u postgres psql # 4. 停止（在运行 shell 按 Ctrl+C），再次启动 docker start mathesar # 5. 删除容器（同时删除数据！） docker rm mathesar

总结

• 一条docker run即可体验 Mathesar，镜像默认阶段自带 PostgreSQL 17 与 Web 服务，-fnse启动参数实现了“无外部配置 → 自动初始化内置数据库 → 迁移 Django 表 → Gunicorn 监听 0.0.0.0:8000”的完整自举链路（build-scripts/bin/mathesar.sh）。
• 首次访问http://localhost:8000/会因“尚无超级用户”而进入安装页，创建 admin 后即完成安装（mathesar/views/installation/decorators.py）。
• docker exec -it mathesar sudo -u postgres psql可直达容器内置数据库；docker start mathesar复用既有数据重启；docker rm mathesar会连同数据一并删除。
• 该方式明确不面向生产：需要持久化、域名/HTTPS 与独立数据库服务时，请切换到官方 Docker Compose 部署方案。

• 数据库
• 后端
• 前端
• 协作