NocoBase 数据源管理：主数据库、外部数据库、REST API 与外部 NocoBase 的统一接入与管理指南

NocoBase 数据源管理主数据库、外部数据库、REST API 与外部 NocoBase 的统一接入与管理指南【免费下载链接】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 一切业务能力的根基——无论是页面区块、权限控制、工作流还是 API 调用都需要先接入可用的数据源。本文围绕 NocoBase 的「数据源管理」插件nocobase/plugin-data-source-manager系统讲解数据源管理界面的定位、主数据库与外部数据源的区别、支持的数据源类型清单、安装与使用方式并结合仓库源码剖析数据源接入、表结构同步、字段映射背后的实现机制帮助你在实际项目中快速规划、接入并管理多数据源架构。数据源管理插件的定位统一管理界面而非接入能力NocoBase 的数据源管理插件plugin-data-source-manager是整个多数据源体系的「门户」它只提供所有数据源的管理界面本身并不具备接入数据源的能力需要与各种数据源插件搭配使用。从源码结构看这一分工非常清晰。插件服务端入口 server/plugin.ts 中维护了每个数据源的运行状态与错误信息export class PluginDataSourceManagerServer extends Plugin { public dataSourceErrors: { [dataSourceKey: string]: Error; } {}; public dataSourceStatus: { [dataSourceKey: string]: DataSourceState; } {}; }其中DataSourceState定义了数据源完整的生命周期状态loading加载中、loaded已加载、loading-failed加载失败、reloading重新加载中、reloading-failed重新加载失败。这些状态会被注入到dataSources:list接口的返回结果中前端管理界面据此展示每个数据源的健康状况当状态为loading-failed或reloading-failed时还会附带具体的errorMessage供排障见 server/plugin.ts。数据源本身的注册信息由系统集合 server/collections/data-sources.ts 定义核心字段包括字段类型说明keystring主键数据源唯一标识创建后不可修改用于页面区块、权限、工作流和 API 中引用displayNamestring数据源在界面中的显示名称typestring数据源类型对应已注册的数据源插件类型optionsjson连接配置如数据库连接串、REST API 地址等enabledboolean是否启用默认true关闭后配置保留但无法读取数据fixedboolean是否固定主数据源为true列表默认按fixed降序排列collectionshasMany该数据源下的数据表集合dataSourcesCollections插件在beforeLoad阶段做了大量绑定工作注册数据源模型、在创建/保存数据源时校验并测试连接、数据源删除后从运行中的dataSourceManager移除实例、应用启动afterStart后统一加载所有启用状态的数据源server/plugin.ts。此外还通过sendSyncMessage把数据源的增删改、字段加载等事件广播到集群其他节点保证多节点环境下数据源元数据的一致性。支持的数据源类型一览目前数据源管理插件支持接入以下数据源每个类型都由独立的数据源插件提供接入能力主数据库Main DatabaseNocoBase 主数据库支持 MySQL、PostgreSQL、MariaDB、KingbaseES、OceanBase外部 PostgreSQL使用外部的 PostgreSQL 数据库作为数据源外部 MySQL使用外部的 MySQL 数据库作为数据源外部 MariaDB使用外部的 MariaDB 数据库作为数据源外部 MSSQL使用外部的 MSSQLSQL Server数据库作为数据源外部 KingbaseES使用外部的 KingbaseES 数据库作为数据源外部 OceanBase使用外部的 OceanBase 数据库作为数据源外部 Oracle使用外部的 Oracle 数据库作为数据源外部 ClickHouse使用外部的 ClickHouse 数据库作为数据源通常用于查询、统计和报表展示外部 Doris使用外部的 Doris 数据库作为数据源通常用于查询、统计和报表展示REST API 数据源将 REST API 来源的数据接入 NocoBase外部 NocoBase通过远端 NocoBase API 将另一个 NocoBase 应用作为外部数据源。除此之外NocoBase 采用插件化的数据源工厂DataSourceManager与factory设计可以通过插件扩展更多数据源类型——既可以是常见的各类数据库也可以是提供 APISDK的平台。任何新类型只要实现并注册到数据源工厂即可出现在「数据源管理」的 Add new 菜单中。主数据库与外部数据源的本质区别理解两类数据源的边界是正确规划架构的前提主数据库key 固定为main是应用初始化时默认创建、用于存储 NocoBase 自身数据的数据库。部署 NocoBase 时配置的数据库即为主数据库详见 主数据库文档它既存放系统表数据也支持存放用户业务表数据且允许在 NocoBase 内直接创建、修改、删除数据表结构外部数据源是接入的既有业务数据库或 API 服务。外部数据库的表结构由原系统、数据库客户端或迁移脚本维护NocoBase 只负责读取表结构和视图不会修改外部数据库的真实表结构也不会接管其备份、还原和迁移。主数据库与外部数据源在支持版本、商业授权等级上也存在差异。例如外部 PostgreSQL 要求 9.5、外部 MySQL 要求 5.7而作为主数据库时 MySQL 要求 8.0.17、PostgreSQL 要求 10KingbaseES 只支持 PostgreSQL 兼容模式OceanBase、ClickHouse、Doris 只支持 MySQL 兼容模式。具体版本与授权要求以各数据源文档为准。安装数据源管理插件是NocoBase 内置插件无需单独安装随应用初始化自动可用。需要注意它只是管理界面接入具体数据源的能力由对应数据源插件提供其中部分数据源插件如外部数据库系列、REST API、外部 NocoBase属于商业插件安装并启用后才会出现在「Add new」下拉菜单中。如果「Add new」菜单里没有目标数据库类型通常需要依次确认对应插件是否已经安装插件是否已经启用当前商业授权是否包含该插件当前用户是否具有数据源管理权限。使用说明主数据库Main Data Source应用初始化安装时会自动创建一个用于存储 NocoBase 数据的数据源即主数据库。通过系统功能中的数据源菜单进入数据源主页选择列表中的Main数据源并点击「配置」即可进入主数据库管理界面。主数据库提供完整的数据表管理能力详见 主数据库文档筛选检索主数据库管理的数据表创建数据表新增业务数据表编辑 / 删除变更、删除业务数据表从数据库同步将数据库中已存在的表同步到 NocoBase 进行管理配置字段数据表字段的创建、变更、删除分类管理通过 tab 页的「」对数据表进行分类管理。主数据库支持创建多种表结构类型普通表、继承表父表派生子表并继承结构、树表邻接表设计、日历表、文件表、SQL 表将 SQL 查询结构化展示不产生真实表、视图表连接已有数据库视图。值得一提的是「从数据库加载」能力浏览数据库中所有表 → 选择需要同步的表 → 自动识别表结构和字段类型 → 一键导入管理。这既保护了已有业务表的投资也支持渐进式迁移。同时 NocoBase 支持字段级别的精细同步——当数据库表结构变化时可以随时同步新增字段也可以选择性同步部分字段同步过程不影响已有数据。外部数据源外部数据源用于把已经存在的业务数据库接入 NocoBase读取其中的数据表、字段和视图使其可以在页面区块、权限、工作流和 API 中使用。典型适用场景包括连接已有业务系统老 ERP、MES、WMS 等的数据库在不改动原表结构的前提下快速搭建管理界面、权限控制、工作流和报表为已有系统补充轻量应用能力审批、数据修正、异常处理、运营看板等对已有数据库做只读查询、统计分析或 BI 展示分阶段迁移历史系统——先接入旧库继续使用再逐步把新业务数据迁入主数据库。外部数据库数据源的管理流程分为四步详见 外部数据库文档添加外部数据库激活对应数据源插件后在「数据源管理」的 Add new 菜单中选择目标数据库类型填写连接信息数据表同步建立连接后直接读取数据源中的所有数据表。外部数据库不支持直接在 NocoBase 中修改表结构如需变更应通过数据库客户端操作再在界面点击「刷新」同步配置字段自动读取已有数据表的字段并展示可快速配置字段标题、数据类型Field type和 UI 类型Field interface。因为外部数据库不支持修改表结构新增字段时可选类型只有关系字段——关系字段并非真实数据库字段而是用于建立表和表之间的连接记录唯一标识作为区块展示的数据表需要「记录唯一标识」Record unique key通常选择主键或唯一字段。视图、无主键表或联合主键表需要在数据表配置中手动设置否则页面区块可能无法正确创建、查看或编辑记录。以外部 PostgreSQL 为例常见连接配置项如下详见 外部 PostgreSQL 文档配置项说明Data source name数据源标识名称用于页面区块、权限、工作流和 API 中引用创建后不能修改Data source display name界面显示名称建议使用业务人员能理解的名称Host / Port主机地址和端口PostgreSQL 默认端口通常为5432Database要连接的数据库名称Username / Password连接账号和密码NocoBase 只能读取该账号有权限访问的对象Schema要读取的 PostgreSQL schema如public多 schema 场景建议只填当前业务需要的Table prefix表名前缀配置后只读取匹配该前缀的表和视图并在 NocoBase 中生成不带前缀的名称Collections / Add all collections控制接入范围启用时接入当前范围内全部表和视图关闭后按勾选接入Enabled the data source是否启用数据源关闭后配置保留但页面区块、权限、工作流和 API 无法读取数据SSL optionsSSL 连接配置包括 SSL mode、证书校验、CA 证书与客户端证书路径等配置提示如果数据库中对象很多优先通过Schema、Table prefix和「Collections」收窄范围只接入当前应用会用到的表和视图后续的权限配置、页面搭建与同步维护都会更轻量。单个外部数据源一次最多接入 500 张数据表或视图。字段类型自动映射NocoBase 会根据外部数据库字段类型自动映射出对应的数据类型Field type与 UI 类型Field interface数据类型Field type定义字段可以存储的数据种类、格式和结构UI 类型Field interface用户界面中用于显示和输入字段值的控件类型。以 PostgreSQL / MySQL 为例的常见映射完整映射表见 外部数据库文档PostgreSQLMySQL/MariaDBNocoBase Data TypeNocoBase Interface TypeBOOLEANBOOLEAN / TINYINT(1)booleancheckbox / switchSMALLINT / INTEGER / SERIAL / SMALLSERIALTINYINT / SMALLINT / MEDIUMINT / INTEGERinteger / boolean / sortinteger / sort / checkbox / switch / select / radioGroupBIGINT / BIGSERIALBIGINTbigInt / sortinteger / sort / checkbox / switch / select / radioGroup / unixTimestamp / createdAt / updatedAtREALFLOATfloatnumber / percentDOUBLE PRECISIONDOUBLE PRECISIONdoublenumber / percentDECIMAL / NUMERICDECIMALdecimalnumber / percent / currencyVARCHAR / CHARVARCHAR / CHARstring / password / uuid / nanoidinput / email / phone / password / color / icon / select / radioGroup / uuid / nanoidTEXTTEXT / TINYTEXT / MEDIUMTEXT / LONGTEXTtext / jsontextarea / markdown / vditor / richText / url / jsonUUID-uuiduuidJSON / JSONBJSONjsonjsonTIMESTAMPDATETIME / TIMESTAMPdatedate / time / createdAt / updatedAtDATEDATEdateOnlydatetimePOINT / LINESTRING / POLYGON / CIRCLEPOINT / LINESTRING / POLYGONpoint / lineString / polygon / circlejson / point / lineString / polygon / circleARRAY-arraymultipleSelect / checkboxGroup不支持的字段类型如 BLOB 映射之外的二进制类型、BIT、RANGE、SET、GEOMETRY 等会在字段配置中单独展示需要开发适配之后才能作为普通字段使用。从源码看字段类型映射与关系字段的应用由服务层 services/type-interface-map.ts 与 services/external-field-apply.ts 承载字段元数据则持久化在dataSourcesCollections与dataSourcesFields两个系统集合中server/collections/data-sources-collections.ts、server/collections/data-sources-fields.ts。底层同步机制数据表与字段的同步在服务端有完整的调用链支撑。在 server/actions/data-sources.ts 中可以看到几个关键动作dataSources:readTables读取数据源中可用的数据表。如果传入dbOptions会先通过工厂临时创建数据源实例再读取否则直接读取已注册数据源的表清单dataSources:loadTables将选中的表加载进数据源同步表结构元数据dataSources:testConnection保存连接配置前先调用对应数据源类型的testConnection校验连通性失败则抛出「Test connection failed」错误阻止无效配置入库dataSources:refresh数据源状态处于loaded/loading-failed/reloading-failed时允许重新加载并通过syncMessageManager.publish同步到集群其他节点。字段与数据表在dataSourcesFields/dataSourcesCollections集合上的afterSaveWithAssociations、afterDestroy事件中会被加载或卸载到运行中的应用实例同时广播集群同步消息见 server/plugin.ts。中间件 server/middlewares/load-tables.ts 则被挂载到全局 resource manager负责在请求数据表前确保外部表结构已同步进 collection manager。REST API 数据源REST API 数据源用于接入 REST API 来源的数据详见 REST API 数据源文档激活商业插件后在 Add new 菜单中选择 REST API 即可配置。其核心思想是将 RESTful 资源映射为 NocoBase 的 Collection。例如Users资源的标准 REST 接口GET /users POST /users GET /users/1 PUT /users/1 DELETE /users/1映射到 NocoBase API 中的配置为GET /users:list POST /users:create POST /users:get?filterByTk1 POST /users:update?filterByTk1 POST /users:destroy?filterByTk1其中List 和 Get 是必须配置的两个接口Create / Update / Destroy 可按需配置。每个接口都需要配置请求参数对接通过变量将第三方 API 参数与 NocoBase 参数对接。例如为 List 接口配置分页参数page对应{{request.params.page}}limit对应{{request.params.pageSize}}。只有已在接口中添加的变量才会生效配置后可点击 Try it out 调试响应格式转换第三方 API 的响应格式可能不符合 NocoBase 标准需要配置转换规则使其符合 NocoBase 输出标准异常信息转换第三方 API 异常时可将响应中的异常信息转换为 NocoBase 标准格式以便前端正确展示未配置时默认转换为包含 HTTP 状态码的异常信息。REST API 数据源提供三类变量用于接口对接数据源自定义变量由使用者自定义的变量NocoBase 请求包括ParamsURL 查询参数各接口不同、HeadersNocoBase 自定义 X- 信息、Body请求体、Token当前 NocoBase 请求的 API token第三方响应目前只提供响应的 Body。各接口可用的请求参数如下接口可用参数Listrequest.params.page当前页数、request.params.pageSize每页数量、request.params.filterNocoBase Filter 格式过滤条件、request.params.sortNocoBase Sort 格式排序、request.params.appends关系字段按需加载、request.params.fields输出白名单、request.params.except排除黑名单Getrequest.params.filterByTk必填一般为数据 ID、filter、appends、fields、exceptCreaterequest.params.whiteList白名单、request.params.blacklist黑名单、request.body创建的初始化数据Updaterequest.params.filterByTk必填、filter、whiteList、blacklist、request.body更新的数据Destroyrequest.params.filterByTk必填、filter配置好接口映射后可从 CRUD 接口返回的数据中提取字段元数据作为 Collection 字段并可像其他数据源一样编辑字段、添加页面区块。外部 NocoBase 数据源外部 NocoBase 数据源可以将另一个 NocoBase 应用作为外部数据源接入当前应用详见 外部 NocoBase 文档。其最大特点是会保留远端应用中已配置的数据表、字段界面、标题和关系字段等元数据相比外部数据库数据源通常无需重新配置字段界面或手动建立关系字段除增删改查记录外还支持文件上传与预览、导入导出、图表查询以及部分工作流场景。添加数据源时需要填写以下配置配置项说明API 地址远端 NocoBase 应用的完整 API 地址如https://example.com/apiOrigin远端 NocoBase 应用的访问源如https://example.com主要用于处理远端应用的本地文件预览地址不要将 API 地址填写为 OriginAPI key当前应用访问远端 NocoBase 时使用的凭证请求头需要额外传给远端应用的请求头如空间等信息超时时间访问远端应用的请求超时时间权限模型外部 NocoBase 数据源同时受当前应用和远端应用两层权限影响当前应用可以像其他外部数据源一样配置不同表和字段的访问权限远端应用则根据配置的 API key 权限读取和操作对应数据。该类型数据源不会返回用于前端精细控制按钮显示状态的权限元数据部分按钮可能不会像主数据源一样按权限自动隐藏但提交操作时仍会经过当前应用的服务端权限判断未授权操作会被拒绝。官方建议为外部 NocoBase 数据源单独准备 API key只授予必要的数据表和操作权限。数据表、记录与文件数据表和字段当前应用加载远端的数据表、字段界面、标题和关系字段等元数据但不支持直接配置字段——新增字段、调整类型或修改关系字段需在远端应用完成再回到当前应用重新加载数据表记录和关联数据支持在页面区块中查看、新增、编辑、删除记录及维护关联数据操作由当前应用发起并通过 API key 请求远端应用文件和附件文件上传到远端应用使用的存储当前应用负责发起上传、预览和下载请求文件本身不保存到当前应用Origin 用于补全远端返回的相对路径文件访问地址导入导出导入、导出都会代理到远端应用执行当前应用负责接收用户操作、转发请求和返回下载结果。导出支持同步模式流式返回文件与异步模式创建本地异步任务并同步进度模板打印打印模板和动作配置保存在当前应用打印时读取远端记录和关联数据并在当前应用生成打印文件图表查询面板由当前应用按本地配置的图表、数据源、数据表和字段权限处理查询参数后请求远端应用SQL 面板的 SQL 会代理到远端应用执行需要本地用户和远端 API key 均具备 UI 配置权限。工作流限制外部 NocoBase 数据源涉及两套工作流当前应用响应本地页面、按钮和 API 请求链路中的事件远端应用收到代理请求后按自己的工作流配置处理。需要注意当前应用不会监听远端数据表内部发生的新增、更新、删除事件远端数据表事件只会在远端应用中触发。各类触发器在两个应用中的触发情况触发器当前应用远端应用说明请求前事件触发仅全局模式触发当前应用全局模式触发局部模式按按钮绑定触发远端应用收到代理请求后仅全局模式触发请求后事件触发仅全局模式触发同上自定义操作事件触发不触发当前应用绑定的「触发工作流」按钮触发本地流程代理 CRUD 请求不触发远端自定义操作事件数据表事件不触发触发实际数据在远端变更当前应用不触发本地数据表事件日期字段定时触发不触发触发当前应用不基于远端数据表字段触发数据源相关的工作流节点可用性查询记录、创建记录、更新记录、删除记录均可用操作远端应用中的记录SQL 节点与聚合节点不可用仅支持数据库数据源。条件、计算、循环、JSON 处理等通用节点不依赖数据源类型按普通工作流使用即可。常见问题速查数据表没有出现检查数据源是否启用、API 地址与 API key 是否正确远端应用是否允许该 API key 访问对应数据表文件上传成功但无法预览本地文件存储场景下检查 Origin 是否为对应应用的公开访问地址非 API 地址当前应用有权限但操作失败检查远端应用的 API key 权限远端服务异常后数据表无法使用远端 502、重启或短暂不可用时当前应用可能暂时无法读取元数据恢复后会在下次访问时自动重新加载为什么不能在当前应用配置字段外部 NocoBase 数据源使用远端的数据表结构和字段配置请在远端调整后重新加载。数据源权限与集群同步数据源管理插件将数据源的访问控制纳入 NocoBase 的 ACL 体系。服务端为dataSources、dataSourcesCollections.fields、roles.dataSourceResources等资源注册了权限片段snippetpm.data-source-manager并允许登录用户执行listEnabled与get见 server/plugin.ts。同时主数据库main受到固定参数保护dataSources:destroy动作会强制添加key.$ne: main过滤条件防止误删系统数据源。在集群部署场景下插件通过app.syncMessageManager广播数据源相关事件loadDataSource、loadDataSourceField、removeDataSourceCollection、removeDataSourceField、removeDataSource、syncRole、syncRoleResource并提供了对应的handleSyncMessage处理逻辑server/plugin.ts保证每个节点的运行态数据源与 ACL 保持一致。相关集群行为也有测试覆盖见 server/tests/cluster.test.ts。小结与选型建议统一管理、插件接入数据源管理插件只提供统一的管理界面与运行时编排接入能力由各数据源插件按类型注册提供架构上保持了极高的可扩展性主数据库适合承载 NocoBase 自身系统数据与需要由 NocoBase 直接维护结构的业务表外部数据库适合接入既有业务库做只读查询、管理界面与渐进式迁移不触碰真实表结构REST API 数据源适合对接第三方 HTTP 服务通过 List / Get / Create / Update / Destroy 五类接口映射实现 CRUD配合变量与响应转换规则完成协议适配外部 NocoBase适合多应用间共享数据表与元数据天然复用远端字段界面与关系配置但要注意双层权限与工作流触发范围限制。规划多数据源架构时建议遵循「按需接入、收窄范围」的原则充分利用Schema、Table prefix、Collections勾选等机制控制接入范围为每个外部数据源尤其是外部 NocoBase单独准备最小权限凭证并提前梳理数据表主键/唯一标识确保页面区块与记录操作可用。【免费下载链接】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），仅供参考