Strapi Admin 管理面板企业版（EE）特性机制与 CE 项目中的 EE 功能推广实现

本文围绕 Strapi 官方文档《Admin Enterprise Edition》（原文档）展开，结合当前仓库源码，深入讲解 Strapi 管理面板中 Enterprise Edition（企业版）特性的整体架构，以及社区版（CE）项目里 EE 功能"自我推广"机制的完整实现链路：从 window.strapi 全局许可状态的初始化，到设置菜单中推广条目的条件注入、licenseOnly 标记渲染与权限过滤。读完后，你将能够理解 Strapi 如何在同一份代码库中同时支撑 CE 与 EE 两种发行形态，并在 CE 项目中安全地展示 EE 功能的购买入口。

1. Admin Enterprise Edition 文档定位

官方文档中，Admin Enterprise Edition 章节是对管理面板所有企业版特性的总览入口（原文通过 Docusaurus 的 DocCardList 渲染该分类下的全部子文档卡片，即 SSO、审计日志、内容历史等各类 EE 特性的说明页）。除此之外，该文档还专门阐述了一个面向 Strapi 贡献者的工程约定：每当 Strapi 新增一个 EE 特性时，应当让它在 CE 项目的设置菜单中自动"自我推广"，从而让社区版用户感知到企业版能力的存在。

这个约定在当前仓库中有完整、可验证的实现。下面按"许可状态来源 → 推广条件模式 → 菜单合并与权限过滤"的顺序逐层解析。

2. 许可状态的唯一事实来源：window.strapi

EE 推广逻辑的所有判断都依赖一个前端全局对象 window.strapi。它的初始化与"水合"（hydrate）过程发生在管理面板的渲染入口 render.ts 中。

2.1 默认值：按"无许可"处理

在 render.ts 中，renderAdmin 首先向 window.strapi 写入一组保守的默认值：

window.strapi = {
  backendURL: createAbsoluteUrl(process.env.STRAPI_ADMIN_BACKEND_URL),
  isEE: false,
  isTrial: false,
  telemetryDisabled: process.env.STRAPI_TELEMETRY_DISABLED === 'true',
  future: {
    isEnabled: (name) => features?.future?.[name] === true,
  },
  features: {
    SSO: 'sso',
    AUDIT_LOGS: 'audit-logs',
    REVIEW_WORKFLOWS: 'review-workflows',
    /**
     * If we don't get the license then we know it's not EE
     * so no feature is enabled.
     */
    isEnabled: () => false,
  },
  projectType: 'Community',
  flags: {
    nps: false,
    promoteEE: true,
    docLinks: true,
  },
  ai: { enabled: true },
};

从源码结构看，这里有两个关键设计：

1. 特性名常量表：SSO: 'sso'、AUDIT_LOGS: 'audit-logs'、REVIEW_WORKFLOWS: 'review-workflows' 把驼峰命名的常量与后端许可系统中使用的特性字符串绑定在一起。业务代码通过 window.strapi.features.SSO 取到字符串 'sso' 后再交给 isEnabled 判断，避免在多处硬编码特性名。
2. 默认 isEnabled: () => false：源码注释明确指出"拿不到 license 就说明不是 EE，因此没有任何特性被启用"。也就是说，在许可接口返回之前，前端一律按社区版行为降级运行。

其中 flags.promoteEE 默认值为 true，这正是第 3 节推广逻辑的总开关。

2.2 通过 /admin/project-type 接口水合真实许可状态

随后，render.ts 会请求后端接口获取真实许可状态并覆盖默认值：

const {
  data: {
    data: { isEE, isTrial, features, flags, ai, planPriceId },
  },
} = await get<{ data: ProjectType }>('/admin/project-type');

window.strapi.isEE = isEE;
window.strapi.isTrialLicense = isTrial;
window.strapi.flags = flags;
window.strapi.features = {
  ...window.strapi.features,
  isEnabled: (featureName: string | undefined) =>
    features.some((feature) => feature.name === featureName),
};
window.strapi.projectType = getProjectType({ isEE, planPriceId });

可以看到，isEnabled 被替换为一个真正的谓词：判断后端返回的 features 列表中是否包含该特性名。若该请求失败，源码中的注释给出了明确策略——"简单地不激活任何 EE 特性"（console.error(err) 后继续以默认值运行），保证管理面板在许可服务异常时仍然可用。

接口响应中的 planPriceId 用于区分 Growth 计划与其他企业计划（源码注释写明它是 license registry 在 EE 中发送的"licensed plan price id"），getProjectType 据此将 projectType 从 'Community' 更新为对应的 EE 计划类型。

3. CE 项目中的 EE 功能推广：条件注入模式

文档给出的核心约定是：每当新增一个 EE 特性，就应在设置菜单中加入如下条件判断，确保该特性在 CE 项目中"自我推广"（原文示例指向设置菜单钩子，其对应实现路径当前为 useSettingsMenu.ts，而具体的推广条目集中在 constants.ts）：

...(!window.strapi.features.isEnabled(window.strapi.features.NEW_EE_FEATURE) &&
   window.strapi?.flags?.promoteEE
  ? [
      {
        intlLabel: {
          id: 'Settings.new-ee-feature.page.title',
          defaultMessage: 'NEW EE FEATURE',
        },
        to: '/settings/purchase-new-ee-feature',
        id: 'new-ee-feature',
        licenseOnly: true,
      },
    ]
  : []),

拆解这个模式，它由三个条件与三个字段组成：

• !window.strapi.features.isEnabled(...)：仅当该 EE 特性"未"被许可时，才注入推广条目。已购买该特性的用户会直接看到功能本体（由 EE 链接提供），菜单中不再出现购买页。
• window.strapi?.flags?.promoteEE：总开关。constants.ts 中的源码注释明确说明：在项目的 ./config/admin.js 中加入 "promoteEE: false" 即可关闭推广行为，即运营上不希望向用户展示 EE 购买入口的项目可整体禁用。
• licenseOnly: true：标记该链接"需要企业许可"。前端菜单组件会据此渲染专属徽标——例如 SettingsNav.tsx 在渲染链接时对 link?.licenseOnly 做判断并附加闪电（Lightning）图标徽标，MainNavLinks.tsx 中同样有 link?.licenseOnly ? <Lightning fill="primary600" /> : undefined 的逻辑，让用户一眼识别出这是企业版功能。
• to: '/settings/purchase-...'：推广条目的跳转目标是专门设置的购买页路由，而非功能页本身。
• intlLabel：与其他菜单项一致，走 i18n 文案系统，id 用于翻译文件检索，defaultMessage 作为缺省文案。

3.1 仓库中已落地的三个真实推广条目

当前仓库的 constants.ts 中 SETTINGS_LINKS_CE() 函数完整实现了上述模式。以下按实际代码逐一说明。

SSO（单点登录）——位于全局设置区（global 链接数组）：

// If the Enterprise/Cloud feature is not enabled and if the config doesn't disable it,
// we promote the Enterprise/Cloud feature by displaying them in the settings menu.
// Disable this by adding "promoteEE: false" to your `./config/admin.js` file
...(!window.strapi.features.isEnabled(window.strapi.features.SSO) &&
window.strapi?.flags?.promoteEE
  ? [
      {
        intlLabel: { id: 'Settings.sso.title', defaultMessage: 'Single Sign-On' },
        to: '/settings/purchase-single-sign-on',
        id: 'sso-purchase-page',
        licenseOnly: true,
      },
    ]
  : []),

Content History（内容历史）——同样位于 global 区，注意此处特性名直接使用字符串字面量 'cms-content-history'（constants.ts）：

...(!window.strapi.features.isEnabled('cms-content-history') && window.strapi?.flags?.promoteEE
  ? [
      {
        intlLabel: { id: 'Settings.content-history.title', defaultMessage: 'Content History' },
        to: '/settings/purchase-content-history',
        id: 'content-history-purchase-page',
        licenseOnly: true,
      },
    ]
  : []),

Audit Logs（审计日志）——位于管理面板设置区（admin 链接数组），特性常量来自 window.strapi.features.AUDIT_LOGS（对应字符串 'audit-logs'）：

...(!window.strapi.features.isEnabled(window.strapi.features.AUDIT_LOGS) &&
window.strapi?.flags?.promoteEE
  ? [
      {
        intlLabel: { id: 'global.auditLogs', defaultMessage: 'Audit Logs' },
        to: '/settings/purchase-audit-logs',
        id: 'auditLogs-purchase-page',
        licenseOnly: true,
      },
    ]
  : []),

这三个条目的结构完全一致：id 以 *-purchase-page 结尾、to 指向 /settings/purchase-* 购买页路由、licenseOnly: true。这正是文档中"NEW_EE_FEATURE"模板的实例化，也是后续新增 EE 特性时应当遵循的复制范式。

3.2 类型层面的约束

推广链接的 TypeScript 类型在 constants.ts 中定义：

export interface SettingsMenuLink
  extends Omit<StrapiAppSettingLink, 'Component' | 'permissions' | 'licenseOnly'> {
  licenseOnly?: boolean;
}

而在 useSettingsMenu.ts 中，来自 Strapi App（注册机制）的链接类型被显式约束为 licenseOnly?: never——即**licenseOnly 标记是 CE 侧推广条目的专属属性**，插件/应用注册的链接不允许携带该标记。这种类型隔离从编译期保证了推广条目的语义不被外部扩展污染。

4. CE 与 EE 菜单的合并：useSettingsMenu 钩子

推广条目最终如何进入用户可见的菜单，由设置页钩子 useSettingsMenu.ts 控制。

4.1 CE 链接与 EE 链接的组合

钩子内部以 SETTINGS_LINKS_CE() 为基线，再通过 useEnterprise 钩子动态加载 EE 侧的链接常量（useSettingsMenu.ts）：

const ceLinks = React.useMemo(() => SETTINGS_LINKS_CE(), []);

const { admin: adminLinks, global: globalLinks } = useEnterprise(
  ceLinks,
  async () => (await import('../../../ee/admin/src/constants')).SETTINGS_LINKS_EE(),
  {
    combine(ceLinks, eeLinks) {
      return {
        admin: [...eeLinks.admin, ...ceLinks.admin],
        global: [...ceLinks.global, ...eeLinks.global],
      };
    },
    defaultValue: { admin: [], global: [] },
  }
);

几个值得注意的细节：

• EE 常量位于 packages/core/admin/ee/admin/ 目录下，与 CE 代码物理隔离（EE 目录整体在 packages/core/admin/ee，含 admin 与 server 两部分）。这正是 Strapi "CE/EE 分开发行"的仓库组织方式：构建社区版产物时不包含 EE 代码，构建企业版产物时通过动态 import 注入。
• useEnterprise 的第二个参数是异步工厂函数（返回 Promise），因此 EE 代码可以按动态 chunk 的形式按需加载；defaultValue 保证在 EE 不可用时钩子不会阻塞。
• 组合顺序上，admin 区 EE 链接排在 CE 链接之前，global 区 CE 链接排在 EE 链接之前——EE 与 CE 条目在最终菜单中是并列呈现、而非互相覆盖的。

4.2 权限过滤与 isDisplayed

合并后的每个链接会被附加权限要求（permissions.settings[link.id]），然后在 useEffect 中通过 checkUserHasPermission 逐个异步判定当前用户是否拥有至少一项对应权限，并据此为每个链接计算 isDisplayed（useSettingsMenu.ts）。最终返回时，菜单会过滤掉未显示的链接：

return {
  isLoading,
  menu: menu.map((menuItem) => ({
    ...menuItem,
    links: menuItem.links.filter((link) => link.isDisplayed),
  })),
};

此外，钩子还会对后端下发的设置数据做防御性归一化（normalizeSettings / normalizeSettingsLink），丢弃缺少 id、to、intlLabel 等必备字段的非法链接——这与第 3.1 节中推广条目"必须带 id 且 intlLabel 完整"的约定相呼应：钩子中的 addPermissions 在链接缺少 id 时甚至会直接抛出错误（"The settings menu item must have an id attribute."）。

5. 完整链路与新增 EE 特性的操作清单

把各部分串起来，一条 EE 功能在 CE 项目中的完整展示链路为：

1. 启动：renderAdmin 写入 window.strapi 默认值（isEE: false、isEnabled: () => false、flags.promoteEE: true）——render.ts；
2. 水合：请求 /admin/project-type，用后端返回的 features 列表替换 isEnabled，决定哪些 EE 特性已启用——render.ts；
3. 注入推广条目：SETTINGS_LINKS_CE() 依据 !isEnabled(feature) && flags.promoteEE 条件，把购买页链接注入 global / admin 链接数组——constants.ts；
4. 合并 CE/EE 链接：useSettingsMenu 通过 useEnterprise 动态加载 SETTINGS_LINKS_EE 并与 CE 链接组合——useSettingsMenu.ts；
5. 权限过滤：逐项检查权限，未通过的链接被 isDisplayed: false 过滤掉；
6. 渲染徽标：设置导航对 licenseOnly: true 的链接附加闪电徽标，指向 /settings/purchase-* 购买页——SettingsNav.tsx。

对于 Strapi 贡献者，新增一个 EE 特性时的落地清单也随之明确：

• 在 window.strapi.features 常量表中登记特性字符串（如 SSO: 'sso'）；
• 在 SETTINGS_LINKS_CE() 对应分区中，按文档模板追加 !isEnabled && promoteEE ? [{ intlLabel, to, id, licenseOnly: true }] : [] 推广条目，to 指向新的 /settings/purchase-<feature> 购买页路由；
• 为 intlLabel.id 补充各语言的翻译条目；
• 确保该特性链接已纳入管理端权限映射（permissions.settings[link.id]），否则即使具备许可，菜单项也会因无权限而被隐藏。

6. 小结

Strapi Admin 的 Enterprise Edition 体系建立在两条清晰的原则之上：许可状态以"后端接口水合 + 前端默认降级"的方式集中承载于 window.strapi，而 CE 项目中的 EE 推广则是一套可复制的条件注入模式——特性未启用且 promoteEE 开关允许时注入 licenseOnly 购买页链接，由 useSettingsMenu 完成 CE/EE 合并与权限过滤，最终由设置导航以徽标形式呈现。理解这条链路，不仅能读懂现有 SSO、Content History、Audit Logs 三个推广条目的行为，也为在 Strapi 中新增 EE 特性提供了从类型定义、菜单注入到权限映射的完整参照。