将 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基类并未做额外逻辑——嵌入能力几乎全部由客户端运行时承载。插件内部同时维护了 v1src/client与 v2src/client-v2两套客户端实现分别对应 NocoBase 的旧、新前端运行时本文以 v2 为主展开。安装与启用按照官方文档 docs/docs/cn/integration/embed/index.md 的说明进入 NocoBase 后台的「插件管理器」找到「嵌入 NocoBase」Embed NocoBase插件启用后即可使用无需重启服务、无需额外配置。启用后插件会在前端注册两件事见 client-v2/plugin.tsx注册名为embed的布局LayoutroutePath: /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 行负责拼链接取当前路由页面模型的uidparentId || 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.tsisEmbedRoutePathname第 67-77 行先剥离应用basename/publicPath再判断规范化后的路径是否为/embed或以/embed/开头命中即为嵌入路由getEmbedRoutePath第 53-65 行负责把/embed/${pageUid}拼到应用的router.getBasename()、getRouteUrl()或getPublicPath()之后保证在多应用Multi-App或子路径部署场景下也能生成正确链接。由于/embed布局在注册时设置了authCheck: falseplugin.tsx嵌入页面不会走 NocoBase 主界面的默认登录守卫而是由插件自带的 EmbedAccessGuard 单独做鉴权。用户打通将 token 拼接到链接中如果想要把页面真正嵌入到其他网站或应用程序例如你自己的 SaaS 系统里用 iframe 引入 NocoBase 页面官方文档明确要求先完成“用户打通”并将token拼接到链接中https://example.com/embed/qs087rz4o2b?tokenxxx“用户打通”的含义是外部系统在完成自身登录后通过 NocoBase 的认证接口换取或签发一个合法的 NocoBase 访问令牌随后携带该令牌访问嵌入链接。NocoBase 的 Embed 会话机制会读取 URL 上的token参数并写入会话存储从而让嵌入页面“感知”到当前登录用户。会话激活URL 参数 → sessionStorageclient-v2/embedSession.tsx 是用户打通的核心实现activateEmbedSession第 134-177 行在进入嵌入路由时被调用它会记录当前应用正常的storage/storagePrefix快照便于退出嵌入时恢复将存储切换到sessionStorage并生成带作用域前缀的存储键NOCOBASE_EMBED_hash_hash_getEmbedStoragePrefix第 70-75 行哈希分别来自应用作用域basename/publicPath/origin与window.name标识实现嵌入会话与主会话的隔离多个 iframe 之间互不串扰从 URL 查询参数读取token和authenticatortoken存在则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:checkskipAuth: true表示即使未携带令牌也要拿到真实的 401 结果若返回用户 id 为空则视为未登录校验页面可达性canAccessEmbedPage第 194-201 行通过routeRepository.getRouteBySchemaUid(pageUid)确认/embed/:pageUid对应的页面确实存在且对当前用户可达加载 ACLloadAcl第 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.tscopyEmbedLinkFlow.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 产品或管理后台的开发者而言这是官方提供的最直接、可开箱即用的集成方案。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考