外部 NocoBase

介绍

外部 NocoBase 数据源可以将另一个 NocoBase 应用接入当前应用，并保留远端应用中已配置的数据表、字段界面、标题和关系字段等元数据。

相比外部数据库数据源，接入外部 NocoBase 后通常无需重新配置字段界面或手动建立关系字段。除查看、新增、编辑、删除记录外，也支持文件上传与预览、导入导出、图表查询以及部分工作流场景。

添加数据源

激活插件后，在「数据源管理」中添加外部 NocoBase 数据源，并填写远端应用的访问信息。

配置项	说明
API 地址	远端 NocoBase 应用的完整 API 地址，例如 `https://example.com/api`
Origin	远端 NocoBase 应用的访问源，例如 `https://example.com`，主要用于处理远端应用的本地文件预览地址
API key	当前应用访问远端 NocoBase 时使用的凭证
请求头	需要额外传给远端应用的请求头，例如空间等信息
超时时间	访问远端应用的请求超时时间

启用数据源后，系统会加载远端应用的数据表。

权限说明

外部 NocoBase 数据源同时受当前应用和远端应用的权限影响。

当前应用可以像其他外部数据源一样，配置不同表和字段的访问权限；
远端应用则根据配置的 API key 权限读取和操作对应数据。

外部 NocoBase 数据源不会返回用于前端精细控制按钮显示状态的权限元数据，因此部分按钮可能不会像主数据源一样按权限自动隐藏。无论按钮是否显示，提交操作时仍会经过当前应用的服务端权限判断，未授权的操作会被拒绝。

:::warning{title=注意} 建议为外部 NocoBase 数据源单独准备 API key，并只授予必要的数据表和操作权限。如果当前应用中有权限但操作失败，请检查远端 API key 的权限。 :::

使用数据表

数据表加载成功后，在页面配置、区块配置、图表或工作流中选择这个数据源，即可使用远端应用中的数据表。

远端应用的数据表结构发生变化后，需要在当前应用中重新加载数据表。

功能说明

外部 NocoBase 数据源主要用于在当前应用中使用远端应用的数据表和数据。数据表结构、字段配置和实际数据仍由远端应用维护。

数据表和字段

当前应用会加载远端应用的数据表、字段界面、标题和关系字段等元数据。相比外部数据库数据源，通常不需要在当前应用中重新配置字段界面或手动建立关系字段。

当前应用不支持直接配置外部 NocoBase 数据源的字段。需要新增字段、调整字段类型或修改关系字段时，请在远端应用中完成，再回到当前应用重新加载数据表。

记录和关联数据

外部 NocoBase 数据源支持在页面区块中查看、新增、编辑和删除记录，也支持查看和维护关联数据。操作会由当前应用发起，并通过配置的 API key 请求远端应用。

文件和附件

文件会上传到远端应用使用的存储中。当前应用负责发起上传、预览和下载请求，文件本身不保存到当前应用。

Origin 主要用于处理远端应用本地存储文件的预览地址。如果远端返回的是相对路径，当前应用会使用 Origin 补全文件访问地址。Origin 应填写远端 NocoBase 应用的公开访问地址，例如：

text

https://example.com

不要将 API 地址填写为 Origin。

导入导出

导入、导出属于通过外部文件读写数据源的操作，都会代理到远端应用执行。当前应用负责接收用户操作、转发请求和返回下载结果，实际数据读写由远端应用完成。

导入记录：当前应用接收上传的导入文件，并代理到远端应用执行导入；
导出记录：当前应用代理请求远端应用导出记录。同步模式会将远端返回的记录文件流式返回给浏览器下载；异步模式会创建本地异步任务，在远端应用发起记录导出并同步进度，下载结果时再从远端应用流式获取记录文件。
导出附件：当前应用代理请求远端应用导出附件。同步模式会将远端返回的附件包流式返回给浏览器下载；异步模式会创建本地异步任务，在远端应用发起附件导出并同步进度，下载结果时再从远端应用流式获取附件包。

模板打印

模板打印可以使用外部 NocoBase 数据源中的记录。打印模板和打印动作配置保存在当前应用，打印时当前应用会读取远端记录和关联数据，并在当前应用生成打印文件。

图表

查询面板

外部 NocoBase 数据源可以用于图表查询面板。当前应用会按本地配置的图表、数据源、数据表和字段权限处理查询参数，再请求远端应用返回结果。

远端 API key 也需要具备对应数据的访问权限，否则查询会失败。

SQL 面板

SQL 面板属于图表的 SQL 查询模式，只用于查询。当前应用负责保存 SQL 配置和发起调用，SQL 会代理到远端应用执行。

使用 SQL 面板时，本地用户需要具备当前应用中的 UI 配置权限，远端 API key 也需要在远端应用中具备 UI 配置权限。SQL 不会像查询面板一样按数据表和字段权限拆解查询参数，请谨慎授予本地用户和对应 API key 的 UI 配置权限。

工作流

外部 NocoBase 数据源可能涉及当前应用和远端应用两套工作流。当前应用响应本地页面、按钮和 API 请求链路中的事件；远端应用收到代理请求后，按远端应用自己的工作流配置处理。

需要注意的是，当前应用不会监听远端数据表内部发生的新增、更新、删除事件。远端数据表事件只会在远端应用中触发。

触发器

下表说明对应工作流已启用时，受外部 NocoBase 数据源影响的触发器在当前应用和远端应用中的触发情况。

触发器	当前应用	远端应用	说明
请求前事件	触发	仅全局模式触发	当前应用全局模式触发，局部模式按当前应用按钮绑定触发；远端应用收到代理请求后，仅全局模式触发
请求后事件	触发	仅全局模式触发	当前应用全局模式触发，局部模式按当前应用按钮绑定触发；远端应用收到代理请求后，仅全局模式触发
自定义操作事件	触发	不触发	当前应用绑定的「触发工作流」按钮会触发本地流程；代理 CRUD 请求不会触发远端自定义操作事件
数据表事件	不触发	触发	实际数据在远端变更，当前应用不触发本地数据表事件；远端应用触发自己的数据表事件
日期字段定时触发	不触发	触发	当前应用不会基于远端数据表字段触发；远端应用按自己的日期字段配置触发

不依赖数据源的触发器在当前应用和远端应用中按各自配置触发。

需要在当前应用中编排操作外部 NocoBase 数据的流程，建议使用请求前事件、请求后事件或自定义操作事件。远端应用中已有的工作流由远端应用独立执行。

节点

下表只列出数据源相关节点。条件、计算、循环、JSON 处理等通用节点不依赖数据源类型，按普通工作流使用即可。

节点	是否可用	说明
查询记录	可用	查询远端应用中的记录
创建记录	可用	向远端应用创建记录
更新记录	可用	更新远端应用中的记录
删除记录	可用	删除远端应用中的记录
SQL 节点	不可用	工作流 SQL 节点仅支持数据库数据源
聚合节点	不可用	聚合节点仅支持数据库数据源

常见问题

数据表没有出现

检查数据源是否已启用，以及 API 地址、API key 是否正确。远端应用中也需要允许该 API key 访问对应数据表。

文件上传成功但无法预览

如果当前应用或远端应用使用本地文件存储，检查 Origin 是否填写为对应应用的公开访问地址。Origin 不应填写为 API 地址。

当前应用里有权限，但操作失败

检查远端应用的 API key 权限。外部 NocoBase 数据源会同时受当前应用权限和远端应用权限影响。

远端服务异常后数据表无法使用

如果远端应用出现 502、重启或短暂不可用，当前应用可能暂时无法读取远端数据表元数据。远端服务恢复后，当前应用会在下次访问该数据源的数据表时自动重新加载元数据。

为什么不能在当前应用配置字段

外部 NocoBase 数据源使用远端应用的数据表结构和字段配置。请在远端应用中调整字段，再回到当前应用重新加载数据表。