将 NocoBase 页面嵌入外部系统：Embed 插件完整指南（iframe 集成与 token 用户打通）-创锋一号

将 NocoBase 页面嵌入外部系统：Embed 插件完整指南（iframe 集成与 token 用户打通）

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

导读

NocoBase 提供了官方开源的「嵌入 NocoBase」（Embed）插件，允许把 NocoBase 中的任意页面嵌入到其他网站或应用程序中，使其成为外部系统的一部分。本文基于仓库中的 Embed 插件源码与官方文档 docs/docs/cn/integration/embed/index.md，完整讲解插件的安装、嵌入链接的复制、token 用户打通、访问权限控制以及多应用路径适配等实战要点，读完后你将能独立把 NocoBase 页面以 iframe 方式集成进自己的业务系统。

插件概览：开源可用、随插随用

「嵌入 NocoBase」插件位于 packages/plugins/@nocobase/plugin-embed，其官方描述为：

Embed NocoBase into another system or webpage, integrating it as a part of that system or webpage.（将 NocoBase 嵌入外部系统或页面中，使其成为该系统或页面的一部分。）

从 package.json 可以看到几个关键信息：

插件名@nocobase/plugin-embed，显示名「Embed NocoBase」/「嵌入 NocoBase」；
nocobase.supportedVersions支持 1.x 与 2.x 两个大版本，editionLevel: 0表示该插件在开源（免费）版本中即可使用，无需商业授权；
遵循 Apache-2.0 许可。

服务端实现非常轻量，server/index.ts 中PluginEmbedServer直接继承自 NocoBase 的Plugin基类，并未做额外逻辑——嵌入能力几乎全部由客户端运行时承载。插件内部同时维护了 v1（src/client）与 v2（src/client-v2）两套客户端实现，分别对应 NocoBase 的旧、新前端运行时，本文以 v2 为主展开。

安装与启用

按照官方文档 docs/docs/cn/integration/embed/index.md 的说明：

进入 NocoBase 后台的「插件管理器」；
找到「嵌入 NocoBase」（Embed NocoBase）插件；
启用后即可使用，无需重启服务、无需额外配置。

启用后，插件会在前端注册两件事（见 client-v2/plugin.tsx）：

注册名为embed的布局（Layout）：routePath: '/embed'、authCheck: false，并挂载EmbedSessionProvider；
注册「复制嵌入链接」菜单项（registerCopyEmbedLinkFlow）。

也就是说，所有形如/embed/xxx的路径会被 Embed 布局接管，以“无导航、无侧栏”的裸页面形态渲染，而不是套用 NocoBase 主界面外壳。

复制嵌入链接：把页面变成可独立访问的 URL

插件启用后，在任意页面的设置器（页面右上角）中会多出「复制嵌入链接」菜单项（locale/zh-CN.json 中对应文案为Copy embedded link→ 「复制嵌入链接」）。点击后，链接会被复制到剪贴板，例如：

https://example.com/embed/qs087rz4o2b

这段 URL 本身可以直接单独打开，浏览器会渲染为去掉了 NocoBase 主界面外壳的纯净页面。

「复制嵌入链接」菜单项的实现位于 client-v2/copyEmbedLinkFlow.tsx：

通过RootPageModel.registerExtraMenuItems将菜单注册到common-actions分组；
核心函数buildEmbedLink（第 29-34 行）负责拼链接：取当前路由页面模型的uid（parentId || currentRoute.schemaUid || ...），拼接成/embed/${pageUid}路径，再通过getEmbedRoutePath处理应用前缀，最后用new URL(pathname, window.location.origin)生成完整地址；
复制成功/失败分别弹出「复制成功」「复制失败」的提示。

对应单元测试 client-v2/tests/copyEmbedLinkFlow.test.ts 验证了多种场景：普通应用下链接为origin/v2/embed/page-uid、子应用 basename 下为origin/v2/apps/app1/embed/page-uid，以及菜单项只注册一次（registerExtraMenuItems仅调用 1 次）。

嵌入链接的路由原理：/embed/:pageUid

嵌入链接的路径结构是固定前缀/embed/加页面 UID。路由判定逻辑在 client-v2/route.ts：

isEmbedRoutePathname（第 67-77 行）：先剥离应用basename/publicPath，再判断规范化后的路径是否为/embed或以/embed/开头，命中即为嵌入路由；
getEmbedRoutePath（第 53-65 行）：负责把/embed/${pageUid}拼到应用的router.getBasename()、getRouteUrl()或getPublicPath()之后，保证在多应用（Multi-App）或子路径部署场景下也能生成正确链接。

由于/embed布局在注册时设置了authCheck: false（plugin.tsx），嵌入页面不会走 NocoBase 主界面的默认登录守卫，而是由插件自带的 EmbedAccessGuard 单独做鉴权。

用户打通：将 token 拼接到链接中

如果想要把页面真正嵌入到其他网站或应用程序（例如你自己的 SaaS 系统里用 iframe 引入 NocoBase 页面），官方文档明确要求先完成“用户打通”，并将token拼接到链接中：

https://example.com/embed/qs087rz4o2b?token=xxx

“用户打通”的含义是：外部系统在完成自身登录后，通过 NocoBase 的认证接口换取（或签发）一个合法的 NocoBase 访问令牌，随后携带该令牌访问嵌入链接。NocoBase 的 Embed 会话机制会读取 URL 上的token参数并写入会话存储，从而让嵌入页面“感知”到当前登录用户。

会话激活：URL 参数 → sessionStorage

client-v2/embedSession.tsx 是用户打通的核心实现：

activateEmbedSession（第 134-177 行）：在进入嵌入路由时被调用，它会：
1. 记录当前应用正常的storage/storagePrefix快照（便于退出嵌入时恢复）；
2. 将存储切换到sessionStorage，并生成带作用域前缀的存储键：NOCOBASE_EMBED_<hash>_<hash>_（getEmbedStoragePrefix，第 70-75 行），哈希分别来自应用作用域（basename/publicPath/origin）与window.name标识，实现嵌入会话与主会话的隔离，多个 iframe 之间互不串扰；
3. 从 URL 查询参数读取token和authenticator：token存在则setToken(token)；authenticator存在则setAuthenticator(authenticator)；
EmbedSessionProvider（第 221-231 行）作为全局 Provider 挂载，监听路由变化，在进入/离开嵌入路由时自动调用syncEmbedSessionFromLocation（第 208-219 行）完成会话激活或恢复。

令牌刷新：x-new-token 响应头同步

外部系统签发的 token 可能过期，NocoBase 在刷新令牌时会通过响应头x-new-token下发新令牌。插件通过 axios 响应拦截器（registerEmbedSessionTokenSync，第 117-132 行）捕获该头并写回会话状态（syncEmbedSessionTokenFromHeaders，第 108-115 行），确保嵌入会话长期有效。

401 兜底：未授权用户

client/embedAuth.ts 在 axios 响应层注册了错误拦截器：当嵌入路由下的请求返回 401 时，先尝试restoreEmbedSessionToken恢复会话令牌；若auth:check请求仍返回 401，则构造一个标记了__nocobase_embed_unauthorized__的“未授权用户”（createEmbedUnauthorizedUser），让页面以未登录状态继续渲染，而不是被强制跳转到登录页。

嵌入页面的访问控制与权限

嵌入页面虽然去掉了主界面外壳，但权限控制并不会缺失。client-v2/EmbedAccessGuard.tsx 在渲染页面内容前会执行完整鉴权流程：

校验当前用户（checkCurrentUser，第 135-154 行）：调用/auth:check（skipAuth: true表示即使未携带令牌也要拿到真实的 401 结果），若返回用户 id 为空则视为未登录；
校验页面可达性（canAccessEmbedPage，第 194-201 行）：通过routeRepository.getRouteBySchemaUid(pageUid)确认/embed/:pageUid对应的页面确实存在且对当前用户可达；
加载 ACL（loadAcl，第 156-183 行）：调用roles:check拉取当前用户的角色、权限 snippets，写入ACLContext，并把角色同步到apiClient.auth.setRole；若用户没有ui.*相关权限，还会调用flowEngine.flowSettings.disable()关闭页面设计能力——也就是说，嵌入页面只允许“使用”，不允许“配置”；
渲染守卫（第 333-335 行）：鉴权失败时展示403结果页，文案为「抱歉，您无权访问该页面。」（对应 locale/zh-CN.json 的Sorry, you are not authorized to access this page.）。

鉴权通过后，EmbedAccessGuard会把CurrentUserContext与ACLContext注入子树（第 337-341 行），页面内的数据权限、按钮显隐、操作限制全部按该用户的真实权限生效。相关行为有 EmbedAccessGuard.test.tsx 等测试覆盖。

嵌入页面的渲染形态与响应式

嵌入页面由 client-v2/EmbedLayoutComponent.tsx 渲染：

根容器设置minHeight: '100vh'并将 CSS 变量--nb-header-height置为0px，彻底去掉主界面顶部导航的高度占位；
当路由为根路由或无内容时渲染空态页（EmbedEmptyPage，即 antd 的Empty组件）；
通过Grid.useBreakpoint()与window.innerWidth判断移动端布局（< 768px），并同步给布局模型setIsMobileLayout，保证嵌入到窄屏环境时页面同样能自适应。

多应用 / 子路径部署适配

如果你的 NocoBase 部署在子路径下，或是通过多应用（Multi-App）功能运行多个应用，嵌入链接的生成与识别会自动带上相应前缀：

getEmbedRoutePath优先使用router.getBasename()，其次getRouteUrl，最后回退getPublicPath()（route.ts）；
copyEmbedLinkFlow.test.ts 中给出了典型断言：子应用场景下链接为https://example.com/v2/apps/app1/embed/cd57hg1ja87；
会话存储前缀同样按应用作用域哈希隔离，不同子应用嵌入到同一外部页面时互不影响。

这意味着你可以在外部系统中用 iframe 同时嵌入多个应用的不同页面，而无需为每个页面单独处理前缀。

实战要点与注意事项

token 获取方式：NocoBase 提供标准的认证接口（如/auth:signin等，可参考 plugin-auth 相关认证机制），外部系统应在服务端完成登录换 token 后，再拼接到嵌入链接中，避免在前端暴露长期凭证；
链接时效：token参数在页面加载时被写入sessionStorage，刷新页面、iframe 重新加载时由EmbedSessionProvider重新激活；令牌过期后由x-new-token响应头自动同步，必要时外部系统需重新签发；
权限最小化：嵌入页面只允许“使用”不允许“配置”（flowSettings.disable()），外部用户无法进入配置模式修改页面结构；
开源可用：该插件editionLevel: 0，开源版本即可直接使用，适合将 NocoBase 作为内部系统/门户的一部分嵌入集成；
测试佐证：仓库中提供了完整的单元测试（copyEmbedLinkFlow.test.ts、route.test.ts、EmbedAccessGuard.test.tsx）与端到端测试（popup.test.ts），可作为理解插件行为的参考样例。

总结

「嵌入 NocoBase」插件用一条/embed/:pageUid路由、一个“复制嵌入链接”菜单项和一套基于sessionStorage+ URL token 的会话机制，把 NocoBase 页面的嵌入流程压缩到三步：启用插件 → 复制嵌入链接 → 拼接 token。底层由EmbedAccessGuard保证权限不裸奔，由getEmbedRoutePath保证任意部署形态下链接可用。对于需要把 NocoBase 作为业务系统组成部分嵌入自有门户、SaaS 产品或管理后台的开发者而言，这是官方提供的最直接、可开箱即用的集成方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析