Yi.Mini

主题

多租户专题 ​

Yi.Mini 的多租户能力以宿主机为管理入口。宿主机负责租户、租户套餐、菜单范围和租户数据库初始化；租户侧只使用分配后的菜单和角色权限。

角色边界 ​

  • 平台超级管理员角色码为 superadmin，只存在于宿主机。
  • 租户管理员角色码为 admin，只存在于租户侧。
  • 租户管理、租户套餐属于平台治理能力，只允许 superadmin 操作。
  • 菜单管理允许 superadmin 和 admin 访问，但租户侧不应拥有平台级菜单。

不要在租户数据库中创建 superadmin 角色。租户能看到哪些菜单，由租户套餐和租户内角色授权共同决定。

租户套餐 ​

租户套餐用于定义租户可用的菜单范围。入口为：

text
系统管理 -> 租户套餐

新增或编辑套餐时，需要填写：

字段说明
套餐名称套餐显示名称
关联菜单该套餐允许同步到租户的菜单范围
备注套餐说明
状态是否启用

关联菜单来自宿主机菜单树。新增套餐时，前端调用 tenantPackageMenuTreeSelect(EMPTY_GUID) 获取可选菜单；编辑套餐时，使用套餐 ID 回显已选菜单。

默认套餐由后端种子数据创建，名称为 标准套餐。默认套餐包含除以下菜单外的基础菜单和权限：

  • 租户管理
  • 租户套餐
  • 接口文档

这几个菜单不应下放给租户，否则租户会获得平台治理入口。

租户创建 ​

入口为：

text
系统管理 -> 租户管理

新增租户时需要选择租户套餐，并配置租户名称、数据库连接信息、联系人、账号数量等基础信息。租户创建后只是登记租户元数据，不等于租户数据库已经完成初始化。

启用 SaaS 多租户后，后端种子数据会创建默认租户：

项默认值
租户名称testTenant
默认套餐标准套餐
联系人租户管理员
账号数量-1，表示不限制

SQLite 场景下，默认租户连接串会使用 tenant-{租户名}.db。

租户初始化 ​

租户列表提供“初始化”操作。初始化会完成以下动作：

  1. 切换到目标租户上下文。
  2. 执行租户数据库 CodeFirst，创建或更新表结构。
  3. 执行租户侧数据种子。
  4. 创建或更新租户管理员账号。
  5. 根据租户绑定的套餐同步菜单。
  6. 将套餐菜单授权给租户管理员角色。

初始化接口为：

http
PUT /tenant/init/{id}

请求体：

json
{
  "username": "admin",
  "password": "123456",
  "isForce": false
}

如果租户数据库已有数据，且 isForce 为 false，接口会返回：

json
{
  "needForce": true
}

页面会二次确认是否强制初始化。强制初始化前需要确认数据风险，避免误清理或覆盖租户已有业务数据。

套餐同步 ​

当租户绑定套餐后，初始化会自动同步套餐菜单。也可以通过后端同步接口主动同步：

http
POST /tenant/sync-package?tenantId={tenantId}&packageId={packageId}

同步规则：

  • 先在租户上下文执行 CodeFirst，确保租户数据库结构存在。
  • 根据套餐关联的宿主菜单，自动补齐父级菜单。
  • 租户管理员 admin 会获得套餐内菜单权限。
  • 其他租户角色会裁剪掉不在套餐范围内的菜单权限。

如果套餐没有配置任何菜单，或宿主菜单已不存在，同步会失败并返回业务错误。

登录与租户上下文 ​

登录页会加载租户下拉数据。选择非默认租户后，前端会在请求头中写入：

http
__tenant: {tenantId}

后端通过 __tenant 识别当前租户上下文。默认租户或宿主机上下文不会附加该请求头。

切换租户后，前端会重新加载用户信息、角色、权限和路由。普通租户用户最终可见菜单来自：

text
租户套餐菜单范围
  + 租户内角色菜单授权
  + /api/account/router 返回的路由树

租户级文件存储 ​

租户可以配置自己的文件存储 Provider 和阿里云 OSS 参数。租户未配置时，文件模块会回退到应用默认的 BlobStoring 配置；租户配置后，上传、下载 URL 解析和删除会按当前租户配置执行。

OSS 配置入口位于文件管理页面的“OSS 存储设置”。具体字段、优先级和本地文件迁移 OSS 规则见 基础能力配置。

推荐操作顺序 ​

首次启用多租户时，建议按以下顺序操作：

  1. 确认 SaaS 多租户配置已启用。
  2. 使用 superadmin 登录宿主机。
  3. 检查默认租户套餐，确认不包含平台治理菜单。
  4. 创建或编辑租户，并绑定租户套餐。
  5. 在租户列表点击“初始化”，填写租户管理员账号和密码。
  6. 使用租户账号登录，验证菜单和按钮权限是否符合套餐范围。

常见问题 ​

租户只显示部分菜单 ​

先检查租户绑定的套餐是否包含目标菜单，再检查租户内角色是否授权该菜单。套餐控制上限，角色授权控制实际可见范围。

租户管理员看不到新增菜单 ​

新增宿主菜单后，需要把菜单加入租户套餐，并重新同步套餐到租户。只改宿主菜单不会自动出现在已有租户数据库中。

租户套餐里看不到租户管理 ​

这是预期行为。默认套餐会排除“租户管理”“租户套餐”“接口文档”，避免租户获得平台治理能力。

初始化提示需要强制初始化 ​

说明目标租户数据库已经存在数据。确认该租户数据可以覆盖或重建后，再执行强制初始化。

贡献者

The avatar of contributor named as wcg wcg

页面历史

基于 MIT 许可发布.

Copyright © 2026 Yi.Mini