企业官网建设流程全解析

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

本文以 Mathesar 0.11.0 官方发布说明（仓库内 docs/docs/releases/0.11.0.md）为骨架，结合当前仓库源码，系统解读本次版本在管理员侧的核心改进：新增 GitHub 作为 SSO 身份提供商、推出 SSO-only 登录模式（REQUIRE_SSO_LOGIN）、实验性的按用户自动开通 PostgreSQL 角色与数据库（PER_USER_DATABASES_ENABLED），以及用户信息权限收紧、跨 Schema 关系支持等。读完本文，你将掌握 0.11.0 新增配置项的确切语义与生效条件、源码级实现原理，并能按官方流程完成从 0.11.0 之前的版本升级。

版本概览

0.11.0 是一版以管理员体验和访问控制为主的迭代，核心变化可归纳为四类：

• SSO 增强：新增 GitHub（OAuth2）身份提供商，与既有 OIDC 提供商并列；推出REQUIRE_SSO_LOGIN开关，可强制所有用户只能通过 SSO 登录。
• 权限收紧：users.list与users.get两个 RPC 方法改为仅超级管理员可调用；User 数据类型列只展示当前数据库的协作者。
• 跨 Schema 关系：同一数据库内、位于不同 Schema 的表之间已有的外键关系，现在可以在界面上正确导航与展示。
• 实验性功能：PER_USER_DATABASES_ENABLED开启后，每个新用户自动获得以其用户名为名的 PostgreSQL 角色与数据库。

此外，本版本包含若干 Bug 修复与维护升级，并移除了通过 URL 创建数据文件导入的能力。

新增 GitHub 单点登录支持

两种身份提供商、两种配置 Schema

0.11.0 之前，Mathesar 的 SSO 仅支持 OIDC 提供商（Okta、Google、Microsoft 等）。本版本起，配置支持两种 Schema 版本（配置入口为sso.yml文件或同名环境变量）：

• Version 1：仅 OIDC，配置在oidc_providers:键下。旧安装无需改动，继续可用。
• Version 2（推荐）：在providers:键下为每个提供商显式声明type:字段（oidc或github），可同时混配 OIDC 与 GitHub 提供商。

省略version:字段时默认按 Version 1 解析。仓库根目录的 sso.yml.example 给出了完整示例，Version 2 的形态如下：

# version: 2 example (recommended for new setups) version: 2 providers: provider1: # (REQUIRED) For OIDC providers (Okta, Google, Microsoft, etc.). type: oidc provider_name: google client_id: # your_client_id secret: # your_secret_key server_url: https://accounts.google.com # (OPTIONAL) # Restrict logins to the specified email domains. # Default (allow all domains): [] allowed_email_domains: [] # (OPTIONAL) # Default postgres roles provisioned to users on their first login. default_pg_role: db1: name: # your_db_name host: # your_db_host port: # your_db_port role: # your_db_role provider2: # (REQUIRED) For github.com type: github client_id: # your_github_client_id secret: # your_github_client_secret # (OPTIONAL) Same semantics as the OIDC provider above. allowed_email_domains: [] default_pg_role: db1: name: # your_db_name host: # your_db_host port: # your_db_port role: # your_db_role

GitHub 提供商只有client_id与secret两个必填项（GitHub OAuth App 与 GitHub App 在sso.yml中的配置形态完全相同），回调地址统一为https://[YOUR MATHESAR DOMAIN]/auth/github/login/callback/。详细的注册步骤（OAuth App / GitHub App 两种路径、Email 权限要求、重新授权注意事项）参见仓库内 docs/docs/administration/single-sign-on.md。

环境变量：SSO_CONFIG_DICT 与 OIDC_CONFIG_DICT 别名

对于无法使用本地文件系统的部署（如 DigitalOcean、Railway），可用环境变量替代sso.yml。0.11.0 将原OIDC_CONFIG_DICT更名为SSO_CONFIG_DICT，并要求变量内容为sso.yml的 JSON 序列化形式，例如：

SSO_CONFIG_DICT="{\"version\": 2,\"providers\": {\"provider1\": {\"type\": \"oidc\",\"provider_name\": \"okta\",\"client_id\": \"client-id\",\"secret\": \"client-secret\",\"server_url\": \"https://trial-2872264-admin.okta.com\"}}}"

OIDC_CONFIG_DICT继续作为向后兼容别名保留；两者同时设置时SSO_CONFIG_DICT优先。这一逻辑可以在 config/settings/common_settings.py 中直接看到：

SSO_CONFIG = load_sso_config( env_value=os.environ.get('SSO_CONFIG_DICT') or os.environ.get('OIDC_CONFIG_DICT'), config_file=BASE_DIR.joinpath('sso.yml'), )

源码级解析规则

SSO 配置的解析集中在 config/sso_config.py，核心规则如下：

• _provider_entries（L74-L92）依据version分发：Version 1 遍历oidc_providers，Version 2 遍历providers并读取每项的type；未知版本直接返回空配置并记录警告。
• _oidc_entry要求provider_name、client_id、secret、server_url四个字段齐全，缺一即丢弃该提供商；provider_name会统一转小写作为provider_id。
• _github_entry（L127-L143）仅要求client_id与secret，其provider_id固定为github。
• allowed_email_domains兼容字符串与列表两种写法（L146-L152）。
• 解析结果被装配为SSOConfigdataclass（oidc_apps、github_apps、allowed_email_domains、default_pg_role_map），随后注入 DjangoSOCIALACCOUNT_PROVIDERS（见 common_settings.py），GitHub 提供商默认申请user:email与read:user两个 scope。

配置解析行为由 config/tests/test_sso_config.py 覆盖：v1/v2 混合提供商解析、未知type跳过、必填字段缺失时丢弃、allowed_email_domains归一化、default_pg_role字段校验、环境变量优先于 YAML 文件等场景均有参数化用例。

登录时的邮箱校验与默认角色开通

GitHub 登录在运行期还有两道关卡，实现在 mathesar/sso.py 的SocialAccountAdapter中：

1. 邮箱校验：pre_social_login（L16-L39）要求用户必须有已验证的主邮箱——GitHub 用户若无已验证主邮箱会被拒绝登录并提示先去 IdP 补充；若配置了allowed_email_domains，邮箱域名不在白名单内同样拒绝。
2. 默认角色开通：save_user（L58-L92）在首次登录创建账号时，读取SSO_CONFIG.default_pg_role_map中该提供商对应的配置，为Database/ConfiguredRole建关联（UserDatabaseRoleMap）；开通失败会回滚并向用户提示错误。

SSO-only 登录模式（REQUIRE_SSO_LOGIN）

配置方式与防锁死保护

在 SSO 已配置的前提下，管理员设置环境变量即可禁用密码登录：

REQUIRE_SSO_LOGIN=true

取值约定为true/false，默认false（docs/docs/administration/environment-variables.md）。开启后，登录页只展示 SSO 选项，密码登录入口消失。

关键的防锁死逻辑在 config/sso_config.py 的resolve_require_sso_login：

def resolve_require_sso_login(env_value, sso_config): requested = env_value in ['t', 'true', 'True'] if not requested: return False if not (sso_config.oidc_apps or sso_config.github_apps): logger.warning( "REQUIRE_SSO_LOGIN is set but no SSO provider is configured; " "password login remains active." ) return False return True

即：若开启该开关但未配置任何 SSO 提供商，Mathesar 会记录警告并继续保留密码登录，避免管理员把自己锁在门外。该保护有对应测试用例（test_resolve_require_sso_login_false_when_no_provider_configured），并在 SSO 官方文档中也有明确提示。

对用户能力的影响（RPC 层）

REQUIRE_SSO_LOGIN生效后，用户不能自行修改密码和邮箱。对应限制在 mathesar/rpc/users.py 中：

• users.password.replace_own（L204-L223）：直接抛出Password authentication is disabled when SSO-only login is enabled.；
• users.patch_self（L132-L163）：当请求中的email与当前用户邮箱不一致时抛出Email cannot be changed when SSO-only login is enabled.。

前端层面，用户资料页与用户编辑表单也依据预加载的is_sso_login_required标志隐藏相应控件（见 mathesar_ui/src/pages/user-profile/ProfilePage.svelte、mathesar_ui/src/systems/users/UserDetailsForm.svelte）。

管理员的兜底能力

作为"break-glass"机制，超级管理员依然可以通过users.password.revoke重置任意用户的密码（设置password_change_needed=True强制下次登录改密），并可通过users.patch_other修改其他用户的邮箱。换言之，收紧的是普通用户的自我编辑能力，而非管理员的干预能力。

实验性功能：按用户自动开通 PostgreSQL 角色与数据库

PER_USER_DATABASES_ENABLED

0.11.0 引入实验性开关PER_USER_DATABASES_ENABLED（布尔值，true/false，默认false），在 config/settings/common_settings.py 中解析，并在 docker-compose.yml 中开放为可配置项（PER_USER_DATABASES_ENABLED: ${PER_USER_DATABASES_ENABLED-false}）。

开启后，每个新创建的 Mathesar 用户都会在 Mathesar 内部数据库服务器上获得一个以其用户名为名的 PostgreSQL 角色和一个同名数据库。触发点有两处：

• 管理员通过 RPC 创建用户时：mathesar/utils/users.py 的add_user在settings.PER_USER_DATABASES_ENABLED is True时调用set_up_home_role_and_db_for_user(user)；
• 用户首次通过 SSO 登录自动建号时：mathesar/sso.py 的save_user末尾同样调用该函数。

开通流程的源码实现

set_up_home_role_and_db_for_user定义在 mathesar/utils/permissions.py，其流程是：

1. 生成 16 位随机密码；
2. 通过_setup_connection_models在 Django 模型中登记Server/Database/ConfiguredRole/UserDatabaseRoleMap；
3. 以内部服务器根连接创建同名登录角色（create_init_login_role）；
4. 创建同名数据库并将所有权授予该角色（create_database(..., owner=...)）；
5. 显式执行GRANT CREATE ON SCHEMA public（兼容 Azure PostgreSQL 对 public schema 所有权策略的偏离）；
6. 在该数据库上安装 Mathesar 所需 SQL 函数，并可选加载示例数据集。

该函数同时包含一个安全护栏：若目标用户名恰好等于内部数据库名，会抛出BadInstallationTarget，拒绝在 Mathesar 内部数据库上安装。

界面与权限的联动收窄

开启该模式后，非管理员用户将不再看到数据库权限与数据库设置相关控件。前端判断逻辑在 mathesar_ui/src/utils/preloadData.ts：

export function canViewDbPermissionsAndSettings(): boolean { const commonData = preloadCommonData(); if (commonData.routing_context !== 'normal') return false; if (commonData.user.is_superuser) return true; return !commonData.per_user_databases_enabled; }

对应的per_user_databases_enabled与is_sso_login_required等标志，由后端get_base_common_data注入页面（见 mathesar/views/init.py）。

注意：该功能为实验性，其行为可能在后续版本中发生变化，生产环境启用前需自行评估。

用户信息权限收紧：User 类型列只显示数据库协作者

users.list / users.get 收归管理员权限

此前任何已登录用户都可以通过users.list枚举全部 Mathesar 用户、通过users.get查询任意用户信息。0.11.0 起这两个方法默认要求超级管理员权限。RPC 装饰器 mathesar/rpc/decorators.py 的默认auth="superuser"直接作用于 mathesar/rpc/users.py 中的users.get与users.list（两者未显式指定auth，即落回默认值）；对比之下，users.patch_self、users.password.replace_own则显式声明为auth="login"。

界面联动与告警

界面层面对应调整是：User 数据类型列现在只展示、只允许选择当前数据库的协作者（UserDatabaseRoleMap中与该数据库关联的用户，参见 mathesar/rpc/collaborators.py 的协作者模型）。若已有单元格引用了非协作者用户，会显示警告，直到该用户被添加为协作者或单元格值被修改。

跨 Schema 外键关系的原生支持

在同一数据库内，若已有外键关系所关联的两张表位于不同 Schema，0.11.0 之前无法在界面中正确呈现。本版本起，这类"跨 Schema 关系"得到了原生处理，改进了以下场景：

• 关联记录的导航与展示；
• 关系卡片（relationship cards）；
• 外键约束详情；
• 相关表小部件（related-table widgets）。

从仓库结构看，外键的创建与解析集中在 db/links.py（如add_foreign_key_column通过exec_msar_func调用 SQL 函数），而 SQL 层（db/sql/05_msar.sql）中的msar函数族以表 OID 而非 Schema 限定名为操作维度，这为跨 Schema 元数据解析提供了基础能力。

Bug 修复与维护项

修复：导出已保存探索（Exploration）失败

此前在所选数据库内解析已保存的 Data Explorer 探索时可能失败。修复路径贯穿两层：

• mathesar/views/export.py 的export_exploration_csv_in_chunks将database_id透传给exploration_chunker；
• mathesar/utils/explorations.py 的exploration_chunker现在调用get_exploration(exploration_id, database_id)，而get_exploration的查询条件为Explorations.objects.get(id=exploration_id, database__id=database_id)（L34-L35），从而确保在正确的数据库上下文内解析探索定义。

修复：表元数据列排序不确定

Mathesar 数据库函数返回的表元数据此前存在列顺序不确定的问题，影响前端展示的稳定性。修复后的msar.get_column_info在聚合时显式按列 ID 排序：

SELECT coalesce(jsonb_agg(column_data ORDER BY column_data.id ASC), '[]'::jsonb) FROM msar.column_info_table(tab_id) AS column_data;

（见 db/sql/05_msar.sql，其中column_info_table以attnum作为id，即按 PostgreSQL 系统列号attnum升序排列。）

维护项

• 将 0.10.0 发布分支合并回 develop（对应 PR #5255）；
• 开始为导入数据文件支持Azure Blob Storage做铺垫：设置层已增加DATA_FILES_STORAGE_BACKEND=azure分支，配合DATA_FILES_AZURE_ACCOUNT_NAME、DATA_FILES_AZURE_CONTAINER环境变量，并通过DefaultAzureCredential完成认证（见 config/settings/common_settings.py）。本版本仅完成配置基础，完整能力以后续版本为准。

移除的功能：基于 URL 的数据文件导入

0.11.0 不再支持"向数据文件 API 传入 URL 来创建导入数据文件"。从 mathesar/views/data_files.py 可以看到，DataFileForm的合法来源字段只剩file与paste两个（source_fields = ['file', 'paste']，同时传入多个来源或一个都不传都会校验失败）；后端创建逻辑 mathesar/utils/datafiles.py 也只处理paste（粘贴表格数据）与file（上传文件）两种分支，url分支已移除。文件中残留的clean_url/URLDownloadError属于遗留代码，不应视为可用功能。

升级到 Mathesar 0.11.0

升级前置条件

升级前需确认两点：

1. PostgreSQL 13 与 Python 3.9 已不再受支持（官方支持自 0.8.0 起终止）。请先升级到 PostgreSQL 14+ 与 Python 3.10+，再升级 Mathesar。
2. 用户名长度限制为 63 字符。0.11.0 通过迁移 mathesar/migrations/0012_alter_user_username.py 将User.username字段约束为CharField(max_length=63, unique=True)。升级前请确保现有用户中没有超过 63 字符的用户名。

Docker Compose 安装升级

在安装目录（默认/etc/mathesar/，若安装到其他目录请相应调整路径）下执行：

docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d

直接安装（Linux / macOS / WSL）升级

Mathesar 提供安装脚本，可同时覆盖全新安装与升级场景。步骤：

1. 进入你的 Mathesar 安装目录（不要带尾部斜杠，不要使用$HOME之类的变量）：

   cd <你的安装目录>

2. 下载并运行 0.11.0 的安装脚本：

   curl -sSfL https://github.com/mathesar-foundation/mathesar/releases/download/0.11.0/install.sh -o install.sh chmod +x install.sh ./install.sh .

3. 将 gunicorn systemd 服务替换为 Mathesar systemd 服务：
   • 先禁用并停止旧的 gunicorn 服务：

     systemctl disable gunicorn.service systemctl stop gunicorn.service

   • 再按安装指南中的 Run Mathesar as a systemd service 一节配置 Mathesar 服务；
   • 最后删除旧的 gunicorn 服务文件：

     sudo rm /lib/systemd/system/gunicorn.service

4. 更新 Caddyfile：
   • 按安装指南中的 Install and configure Caddy 一节更新配置；
   • 确保你的域名直接写在 Caddyfile 的第一行；
   • 重启 Caddy 服务：

     systemctl restart caddy.service

仅本机运行、不需要常驻服务的情况：可以移除 gunicorn 与 caddy 服务，直接手动启动：

mathesar run

小结

Mathesar 0.11.0 的核心价值在于把 SSO 从"可选的 OIDC 单点"扩展为"可强制执行的统一身份入口"：GitHub 加入提供商阵营、REQUIRE_SSO_LOGIN提供纯 SSO 模式、PER_USER_DATABASES_ENABLED探索多租户式的自动化开通路径；同时通过收紧users.list/users.get权限与 User 类型列的协作者过滤，进一步收敛了用户信息的暴露面。对于升级用户，务必先满足 PostgreSQL 14+ / Python 3.10+ 与用户名 63 字符的前置条件，再按 Docker Compose 或直接安装流程操作。

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