Mathesar 从零开始原生安装指南：Linux / macOS / WSL 上的内部数据库配置、systemd 服务化与 Caddy HTTPS 部署

数据库后端前端协作【免费下载链接】mathesarAn intuitive spreadsheet-like interface that lets users of all technical skill levels view, edit, query, and collaborate on Postgres data directly. 100% open source and self hosted, with native Postgres access control.项目地址https://gitcode.com/gh_mirrors/ma/mathesar点击查看免费下载本文基于 Mathesar 官方安装文档 install-from-scratch.md系统讲解如何在 Linux、macOS或 Windows 的 WSL 2上不借助 Docker直接在操作系统上完成 Mathesar 的原生安装从 PostgreSQL 内部数据库的初始化、安装目录准备、安装脚本执行到 systemd 常驻服务化与 Caddy HTTPS 反向代理部署。读完本文你可以独立完成一套可 7×24 对外服务的 Mathesar 部署并理解每个配置项在源码层面的实际作用。适用人群本文假定你熟悉命令行、包管理和基本的数据库管理。如遇无法解决的问题可以通过项目社区渠道反馈或在仓库中提交 issue / PR。一、适用前提与环境要求在开始之前请确认系统满足以下条件摘自官方文档的 Requirements 一节类别要求硬件磁盘 ≥ 60 GB内存 ≥ 4 GB推荐操作系统大多数现代 Linux 发行版与 macOS 均可已在Debian 12、Ubuntu 22.04、macOS 14上验证Windows请在WSL 2Ubuntu 或 Debian中安装软件PostgreSQL 13 或更新版本需要特别理解的一个概念是 Mathesar 的内部数据库。Mathesar 会把你的业务数据尽量存放在你连接的 PostgreSQL 数据库中表、行、关系、角色与权限都在其中但应用自身还需要一个独立的内部数据库来保存用户账户、数据库连接凭据含加密保存的角色密码、表单等应用级元数据详见 databases.md 中 Mathesars internal database 一节。安装的第一步就是为它做好准备。二、创建 Mathesar 的内部数据库这一步在 PostgreSQL 中创建 Mathesar 专用的数据库与用户Mathesar 后续所有应用级元数据都落在这个库里。1. 打开 psql 交互式终端sudo -u postgres psql请根据你的 Postgres 安装方式调整例如使用psql直接以超级用户登录。2. 创建 Mathesar 专用数据库用户CREATE USER mathesar WITH ENCRYPTED PASSWORD strong‑pw‑here CREATEDB;请务必将strong‑pw‑here替换为强密码并记录保存后文安装脚本中会用到。关于这条语句中的可选权限属性CREATEDB允许该 Postgres 用户创建新数据库。如果你希望 Mathesar 的管理员能从 Web 界面直接创建数据库就保留它不需要该能力则直接删掉CREATEDB其余功能不受影响。CREATEROLE允许该 Postgres 用户创建和管理其他 Postgres 角色。如果你希望 Mathesar 管理员能在 Web 界面完成角色管理创建、删除、修改角色则加上该属性CREATE USER mathesar WITH ENCRYPTED PASSWORD strong-pw-here CREATEDB CREATEROLE;两个属性都是可选的按需取舍即可。3. 创建存放元数据的数据库CREATE DATABASE mathesar_django OWNER mathesar;该数据库的OWNER必须是上一步创建的 Postgres 用户本例为mathesar。4. 退出 psql按CtrlD退出psql终端。三、准备安装目录选定一个用于安装 Mathesar 的目录例如/home/your_user_name/mathesar或/etc/mathesar。不要在路径末尾加斜杠不要使用$HOME等变量后续步骤要求使用字面绝对路径。创建目录并赋予正确的属主mkdir -p /home/your_user_name/mathesar chown $(id -u):$(id -g) /home/your_user_name/mathesar如果在主目录之外如/etc/mathesar、/opt/mathesar安装本步骤需要提权sudo mkdir -p /etc/mathesar sudo chown desired-owner:desired-group /etc/mathesar属主选择建议root仅管理员会触碰这些文件你自己的用户所有操作都由你执行专用的mathesar用户适合共享或生产服务器。后续步骤要求你在安装目录内拥有完全的文件操作权限。进入安装目录cd /home/your_user_name/mathesar四、运行安装脚本1. 下载并授权安装脚本以下命令从当前版本对应的 Release 资产中下载install.sh{{mathesar_version}}替换为你要安装的版本号curl -sSfL https://github.com/mathesar-foundation/mathesar/releases/download/{{mathesar_version}}/install.sh -o install.sh chmod x install.sh2. 执行安装脚本并传入数据库连接串./install.sh . \ -c postgres://mathesar:strong‑pw‑herelocalhost:5432/mathesar_django-c接受任意合法的 PostgreSQL 连接串URI 形式或参数形式均可文档给出的几种等价示例postgres://mathesar:strong‑pw‑herelocalhost:5432/mathesar_django # 以参数形式 postgres:///mathesar_django/?hostlocalhostport5432usermathesarpasswordstrong‑pw‑here # 通过 Unix 域套接字 postgres://mathesar:strong‑pw‑here/mathesar_django?host/var/run/postgresql # 非标准端口的 Unix 域套接字 postgres://mathesar:strong‑pw‑here%2Fvar%2Flib%2Fpostgresql:5455/mathesar_django3. 安装脚本选项一览选项作用-h/--help显示帮助-c/--connection-string非交互式配置数据库连接-n/--no-prompt遇到需要交互的项时直接失败而不提示用于 CI-f/--force-download-python即使系统 Python 可用也强制下载独立 Python 发行版4. 安装成功的标志脚本成功时会输出Mathesars installed successfully!并尝试把mathesar可执行文件加入你当前用户的PATH。若成功还会看到Everythings ready, you can now start Mathesar by executing mathesar run.可能需要打开新终端或重新加载 shell profile后 PATH 才生效若脚本无法修改你的PATH它会打印手动添加的说明。想让系统内所有用户都能运行 Mathesar出于安全考虑安装器只为运行它的用户配置命令与权限。要将其变为系统级可用在/usr/local/bin创建符号链接sudo ln -s /home/your_user_name/mathesar/bin/mathesar /usr/local/bin/mathesar授予所有用户对安装目录及其内容的读权限sudo chmod -R arX /home/your_user_name/mathesar授予所有用户对.media目录的写权限用户上传的文件会落在这里sudo chmod -R arwX /home/your_user_name/mathesar/.media源码视角安装过程在底层做了什么安装脚本会把数据库连接串拆解并写入安装目录下的.env文件。这一过程的实现见 setup/process_env.py它从标准输入读取.env内容用psycopg.conninfo.conninfo_to_dict()把连接串解析为POSTGRES_HOST、POSTGRES_PORT、POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD五个变量并通过validate_pg_env_variables()实际建立一次数据库连接来验证连通性失败即退出同时若.env中没有WEB_CONCURRENCY会默认补上3见该文件main()中updates[WEB_CONCURRENCY] 3。其解析行为由 setup/tests/test_process_env.py 中的用例覆盖包括连接串解析、.env行更新等场景。Django 侧的“落库”步骤由 mathesar/install.py 完成设置DJANGO_SETTINGS_MODULEconfig.settings.production、调用migrate应用全部迁移模型迁移见 mathesar/migrations/随后执行collectstatic --noinput --clear收集静态文件可用环境变量SKIP_STATIC_COLLECTION跳过。应用启动时如何消费这些变量见 config/settings/common_settings.py只有POSTGRES_DB、POSTGRES_USER、POSTGRES_HOST三者齐备时才会通过PostgresConfig定义于 config/database_config.py构建DATABASES[default]并把sslmode注入连接OPTIONS默认preferSECRET_KEY若未设置则自动随机生成并持久化到安装目录的.secrets/secret_key.txt。五、验证并启动 Mathesar# 新终端中验证安装应打印版本号 mathesar version # 启动 Mathesar mathesar run启动后访问http://localhost:8000即可打开 Mathesar。源码视角mathesar命令实际是安装目录bin/下的 shell 脚本其源码为 build-scripts/bin/mathesar.sh。从源码可以确认几个关键行为默认监听地址与端口为0.0.0.0:8000mathesar.sh#L13-L14可用--port/-p、--addr/-a覆盖启动时会逐行加载安装目录下的.env并导出为环境变量set_env_vars_from_file且要求POSTGRES_USER、POSTGRES_HOST、POSTGRES_DB三者必须已设置否则报错退出Docker 镜像内另有--fallback-to-inbuilt-db回退到内建数据库原生安装不涉及最终通过exec gunicorn config.wsgi -b 0.0.0.0:8000 --chdir 安装目录 --timeout 180启动 WSGI 应用mathesar.sh#L221-L240Worker 数量由WEB_CONCURRENCY控制另有--setup-django/-s选项可在启动前执行python -m mathesar.install即上一节所述的迁移与静态收集--no-venv/-n使用系统 gunicorn--prefer-exported-env/-e优先使用已导出的环境变量CI 场景。六、生产部署以 systemd 服务常驻运行Linux本节仅针对使用systemd的 Linux 服务器macOS 可将服务部分改写为launchd。多数命令需要 root 或sudo权限。 默认情况下 Mathesar 使用3 个 Gunicorn 同步 Worker若机器 vCPU 更多可参考 environment-variables.md 中WEB_CONCURRENCY的说明调整推荐公式2 * CPU 核心数 1写入安装目录的.env即可。操作步骤先把正在前台运行的mathesar run停掉1. 创建专用运行用户sudo groupadd mathesar \ sudo useradd mathesar -g mathesar2. 将.media目录属主改为该用户上传文件CSV 等默认落在安装目录的.media/下对应 common_settings.py 中MEDIA_ROOT的默认值BASE_DIR/.media/可用MEDIA_ROOT环境变量覆盖sudo chown -R mathesar:mathesar /home/your_user_name/mathesar/.media/3. 编写 systemd 服务单元cat EOF | sudo tee /etc/systemd/system/mathesar.service /dev/null [Unit] Descriptionmathesar daemon Afternetwork.target network-online.target Requiresnetwork-online.target [Service] Typenotify Usermathesar Groupmathesar RuntimeDirectorymathesar WorkingDirectory/home/your_user_name/mathesar ExecStart/bin/bash -c /home/your_user_name/mathesar/bin/mathesar run EnvironmentFile/home/your_user_name/mathesar/.env Restarton-failure RestartSec5s [Install] WantedBymulti-user.target EOF示例中的路径请按你的安装目录替换EnvironmentFile指向安装目录下的.env即安装脚本生成、setup/process_env.py校验过的那份配置。4. 加载并启动服务sudo systemctl daemon-reload sudo systemctl start mathesar.service sudo systemctl enable mathesar.service5. 检查日志确认无错误journalctl --unitmathesar.service七、使用 Caddy 以域名提供 HTTPS 服务这一步在 Mathesar 前置一层 Caddy 反向代理自动申请并续期 Lets Encrypt 证书。仅当你计划通过域名访问时需要本节只在localhost使用可跳过。仓库根目录自带的 CaddyfileDocker Compose 部署所用与下述配置结构一致可作为对照参考。1. 配置域名 DNS确保域名的A/AAAA记录解析到你的服务器 IP。多个域名/子域用英文逗号分隔且不含空格如localhost,example.com,subdomain.example.com域名前不要带http:///https://末尾不要带斜杠。2. 配置ALLOWED_HOSTS将域名追加到安装目录的.env文件安装目录/.env末尾ALLOWED_HOSTSexample.com多个值用逗号分隔、中间无空格。其余可用环境变量WEB_CONCURRENCY、SSO_CONFIG_DICT、文件存储、登录页定制等可完整查阅 environment-variables.md。修改后重启服务sudo systemctl restart mathesar.service源码依据common_settings.py 中ALLOWED_HOSTS的解析方式为逗号分隔、逐项去除首尾空格默认值为.localhost, 127.0.0.1, [::1]。生产设置 config/settings/production.py 还配置了SECURE_PROXY_SSL_HEADER (HTTP_X_FORWARDED_PROTO, https)即信任 Caddy 转发的协议头保证 Django 能识别原始请求为 HTTPS。3. 安装并配置 Caddy按 Caddy 官方文档安装 Caddy。创建/修改/etc/caddy/Caddyfile内容如下替换为你的域名与安装目录# 下面一行指定你的域名 example.com { 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 /home/your_user_name/mathesar/.media/ } } handle_path /static/* { file_server { precompressed br zstd gzip root /home/your_user_name/mathesar/static/ } } # Mathesar 应用监听的地址 reverse_proxy localhost:8000 }配置要点respond /caddy-health-check 200供健康检查探针使用/media/*与/static/*由 Caddy 直接以file_server提供对应 Django 的MEDIA_ROOT/STATIC_ROOT见 common_settings.py并支持 br/zstd/gzip 预压缩?dl查询参数会转换为Content-disposition: attachment触发浏览器下载其余请求reverse_proxy到localhost:8000的 MathesarGunicorn 默认端口。确认 Caddy 服务存在多数安装方式已自动创建 systemd 单元systemctl status caddy.service重启 Caddysudo systemctl restart caddy.service检查日志确认无错误journalctl --unitcaddy.service若你偏好 nginx 等其他代理请参照其自身文档调整配置。八、创建首个管理员账户浏览器访问你的 Mathesar 地址已配置域名https://你的域名未配置域名http://localhost:8000按屏幕向导创建第一个管理员账户即可开始使用 Mathesar。至此一条完整的从零到生产链路即Postgres 内部库初始化 → 安装目录 → install.sh → mathesar run → systemd → Caddy HTTPS → 管理员账户。九、故障排查安装或运行中遇到问题时可对照以下排查清单继承自官方文档 Troubleshooting 一节安装器报 “Permission denied” / mkdir 失败可能原因在无权限的情况下向 root 属主的目录安装。解决用sudo重跑命令或安装到你有写权限的目录。安装器在构建 Python 依赖时失败可能原因环境中缺少构建工具/头文件。解决给安装脚本加-f强制下载自包含 Python或安装构建工具链Debian/Ubuntu 系build-essential python3-dev libpq-dev。路径含空格导致服务异常可能原因命令与 unit 文件中的空格未转义。解决systemd unit 中务必转义空格例如WorkingDirectory/etc/mathesar\ install\ dir。Caddy 返回空白页 / 502可能原因Caddy 无权限读取static目录或 Mathesar 未运行/已崩溃。解决确保 Caddy 服务用户对安装目录下static目录及其内容可读若 Mathesar 崩溃查日志定位错误。上传 CSV 失败500 错误可能原因.media目录对 Mathesar 服务用户或系统其他用户不可写。解决确认 Mathesar 服务用户对安装目录下.media目录及其内容有写权限若是系统级安装还需保证其他用户同样有写权限。浏览器显示 “Not Secure” / HTTP 锁标志可能原因走的是明文 HTTP或 Caddyfile 里写的是 IP 地址而非域名。解决使用 Caddy 以 HTTPS 提供服务Caddyfile 中必须是合法域名核对 A/AAAA 记录使域名正确解析到服务器 IP。十、延伸阅读环境变量全集SECRET_KEY、WEB_CONCURRENCY、SSO、文件存储、登录页定制等environment-variables.md单点登录SSO / OIDC GitHub配置single-sign-on.md文件后端启用文件数据列配置file-backend-config.md内部数据库与业务数据库的数据边界databases.mdDocker Compose 安装方式的对照install-via-docker-compose.md其他安装路径DigitalOcean、Railway 等与卸载、升级administration 目录赞分享数据库后端前端协作【免费下载链接】mathesarAn intuitive spreadsheet-like interface that lets users of all technical skill levels view, edit, query, and collaborate on Postgres data directly. 100% open source and self hosted, with native Postgres access control.项目地址https://gitcode.com/gh_mirrors/ma/mathesar点击查看免费下载相关推荐从零开始Cloudreve系统服务化部署指南Systemd配置全解析从零开始Cloudreve系统服务化部署指南Systemd配置全解析 引言解决Cloudreve自启动痛点 你是否还在为服务器重启后手动启动Cloudr后端对象存储LEANN安装部署跨平台配置指南macOS、Linux、WSLLEANN是全球最小的向量索引系统能够在个人设备上运行快速、准确且100%私有的RAG应用同时节省97%的存储空间。无论你使用macOS、Linux还是WS人工智能大模型数据库向量数据库RAG本地部署MCP 服务告别配置噩梦Caddy容器化部署指南让HTTPS服务秒级上线告别配置噩梦Caddy容器化部署指南让HTTPS服务秒级上线 你还在为SSL证书配置焦头烂额还在为服务器迁移时的环境依赖发愁本文将带你通过Docker容器后端API网关网络上一篇Easydict Agent 规则职责拆分与 planning 边界实战指南下一篇PredictionIO 监督学习实战指南从特征理解到分类与回归模型的训练创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考