NocoBase 外部数据源接入 MariaDB 完整指南：插件、连接配置、字段映射与权限实践

NocoBase 外部数据源接入 MariaDB 完整指南插件、连接配置、字段映射与权限实践【免费下载链接】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/nocobaseMariaDB 是 NocoBase 外部数据源体系中的重要成员。本篇指南基于仓库文档 docs/docs/cn/data-sources/external/mariadb.md完整讲解如何将已有 MariaDB 数据库接入 NocoBase从插件安装、连接参数、数据表选择范围到字段类型映射、主键与记录唯一标识的配置要点并结合data-source-manager与database核心包的源码解释底层读取与映射机制。读完本文你将能够独立完成一个外部 MariaDB 数据源的接入、收窄接入范围、同步字段并正确配置记录唯一标识使其在页面区块、权限、工作流和 API 中正常工作。介绍MariaDB 可以作为外部数据库接入 NocoBase。接入后NocoBase 会读取 MariaDB 中的数据表、字段和视图并把它们作为外部数据源中的数据表使用。与主数据库不同外部 MariaDB 的真实表结构仍由原业务系统、数据库客户端或迁移脚本维护。NocoBase 只负责读取表结构与字段元数据保存字段元数据与类型映射配置页面区块、权限、工作流和 API。因此整个接入过程对 MariaDB 侧是只读感知、可写操作的——NocoBase 不会在外部 MariaDB 中创建字段、修改字段类型或删除真实字段但可以在已有表之上构建完整的管理界面与业务逻辑。配置项说明支持版本MariaDB 10.3商业版本标准版、专业版、企业版支持对应插件nocobase/plugin-data-source-external-mariadb兼容协议使用 MySQL 协议连接字段映射整体沿用 MySQL 兼容逻辑从源码结构看MariaDB 与 MySQL 的兼容是显式实现的核心包 field-type-map.ts 中直接定义了const fieldTypeMap { postgres, mysql, sqlite, mariadb: mysql }即 MariaDB 的字段类型映射表完全复用 MySQL 的映射逻辑同时 mariadb-dialect.ts 为 MariaDB 设置了独立的方言实现包括multipleStatements: true、supportBigNumbers: true、bigNumberStrings: true等连接选项并对版本号做了守卫校验版本要求10.9与文档标注的10.3均属官方支持口径实际以安装环境为准。适合使用外部 MariaDB 的场景接入已有 ERP、MES、WMS、CRM 等业务系统的 MariaDB 数据库在不迁移历史数据的情况下用 NocoBase 搭建管理界面对已有表做权限控制、流程处理、数据修正或报表展示数据库结构继续由 DBA、迁移脚本或原系统维护。⚠️ 注意外部 MariaDB 不是 NocoBase 的系统数据库。NocoBase 不会接管它的备份、还原、迁移和表结构变更。这些运维职责仍属于原数据库团队。插件安装该插件为商业插件对应插件名为nocobase/plugin-data-source-external-mariadb。详细的激活方式请参考官方《商业插件激活指南》见原文档链接。与所有外部数据库插件一致安装并启用插件后才能在「数据源管理」的「Add new」菜单中看到 MariaDB 类型。如果在「Add new」菜单中没有找到 MariaDB通常需要按顺序排查对应插件是否已经安装插件是否已经启用当前商业授权是否包含该插件当前用户是否具有数据源管理权限。添加数据源在「数据源管理」中点击「Add new」选择 MariaDB然后填写连接信息。常见连接配置如下配置说明Data source name数据源标识名称用于页面区块、权限、工作流和 API 中引用。创建后不能修改。Data source display name数据源在界面中显示的名称建议使用业务人员能理解的名称比如「ERP MariaDB」「订单库」。Host / PortMariaDB 主机地址和端口。默认端口通常是3306。Database要连接的 MariaDB 数据库名称。Username / Password用于连接 MariaDB 的账号和密码。NocoBase 只能读取这个账号有权限访问的对象不会授权或读取其他账号私有对象。Table prefix表名前缀。配置后NocoBase 只读取匹配该前缀的数据表和视图并在 NocoBase 中生成不带前缀的数据表名称。Collections / Add all collections控制接入范围。启用「Add all collections」时NocoBase 会接入当前范围内的全部表和视图关闭后只接入你在「Collections」里勾选的对象。Enabled the data source是否启用这个数据源。关闭后数据源配置会保留但页面区块、权限、工作流和 API 无法继续读取它的数据。「Table prefix」与「Add all collections」是控制接入范围的两个关键开关。从数据源管理器的实现看database-introspector.tsgetTables在枚举出全部表与视图后会先过滤掉排除列表中的对象再按tablePrefix前缀做startsWith过滤而在生成数据表名称时同文件 tableInfoToCollectionOptions会通过tableName.replace(tablePrefix, )把前缀从表名中剥离从而在 NocoBase 中得到不带前缀的名称并自动把表名中的.替换为_。 提示如果 MariaDB 中对象很多优先通过Database、Table prefix和「Collections」收窄范围。只接入当前应用会用到的表和视图后续权限配置、页面搭建和同步维护都会更轻。选择数据表填写连接信息后可以点击「Load Collections」读取 MariaDB 中可用的数据表和视图。读取结果会受到连接账号、Database、Table prefix和「Collections」配置影响。默认会启用「Add all collections」表示接入当前范围内的全部表和视图。如果只想接入部分对象可以关闭「Add all collections」然后在列表中勾选需要的数据表或视图。在底层表与视图的枚举由数据源方言驱动MariaDB 使用专门的 MariaDBIntrospector通过 Sequelize 的showAllTables()获取表清单而DatabaseIntrospector基类还会调用listViews()把视图并入候选列表再统一执行前缀过滤。⚠️ 注意单个外部数据源一次最多接入 500 张数据表或视图。如果 MariaDB 中对象很多建议先通过Database、Table prefix或「Collections」收窄范围。同步和配置字段外部 MariaDB 的表结构由数据库侧维护。NocoBase 不会在外部 MariaDB 中创建字段、修改字段类型或删除真实字段。当 MariaDB 侧表结构发生变化时可以在数据源中执行「Sync from database」重新读取表和字段元数据。同步会更新 NocoBase 中保存的数据表、字段、主键、唯一键和字段类型映射信息但不会删除 MariaDB 中的真实表或数据。字段同步后可以在 NocoBase 中配置字段标题、字段类型Field type和字段组件Field interface。如果需要建立 NocoBase 关系字段也是在 NocoBase 中保存关系元数据不会在 MariaDB 表里自动新增真实外键字段。从实现角度理解同步的过程DatabaseIntrospector会为每张表调用getTableColumnsInfo()describeTable读取列信息调用getTableConstraints()showIndex读取索引约束再逐列推断 Field type 与 Field interface见 database-introspector.ts。其中能推断出类型的字段进入fields无法推断的进入unsupportedFields单独存放——这正是文档所说不支持的字段类型会在字段配置中单独展示的源码依据。字段类型映射NocoBase 会根据 MariaDB 字段类型自动映射到合适的 Field type 和 Field interface。MariaDB 的常见字段映射与 MySQL 基本一致你可以在字段配置中调整界面展示方式。常见映射如下MariaDB 字段类型NocoBase Field type可选 Field interfaceTINYINT、SMALLINT、MEDIUMINTinteger、boolean、sortInteger、Sort、Checkbox、Switch、Select、Radio groupINT、INTEGERinteger、unixTimestamp、sortInteger、Sort、Unix timestamp、Select、Radio groupBIGINTbigInt、snowflakeId、unixTimestamp、sortInteger、Sort、Unix timestamp、Created at、Updated atFLOAT、DOUBLEfloatNumber、PercentDECIMALdecimalNumber、Percent、CurrencyCHAR、VARCHARstring、uuid、nanoid、encryptionInput、Email、Phone、Password、Color、Icon、Select、Radio group、UUID、Nano IDTINYTEXT、TEXT、MEDIUMTEXT、LONGTEXTtextTextarea、Markdown、Vditor、Rich text、URLDATEdateOnlyDateTIMEtimeTimeDATETIMEdatetimeNoTz、datetimeTz、dateDate、Time、Created at、Updated atTIMESTAMPdatetimeTz、dateDate、Time、Created at、Updated atYEARstring、integerInput、Integer、DateJSONjson、arrayJSON这张映射表有精确的源码对应关系核心包 field-type-map.ts 中定义的mysql映射即为 MariaDB 所复用例如tinyint/smallint/mediumint映射到[integer, boolean, sort]int/integer映射到[integer, unixTimestamp, sort]bigint映射到[bigInt, snowflakeId, unixTimestamp, sort]datetime映射到[datetimeNoTz, datetimeTz, date]等。映射时的具体推断逻辑在DatabaseIntrospector.inferFieldTypeByRawType()中database-introspector.ts先通过extractTypeFromDefinition()去掉类型定义中括号内的长度/精度部分如VARCHAR(255)→varchar再查表得到候选类型数组数组的第一项作为默认 Field type其余作为可切换的候选类型。因此当你把字段从integer切换为sort或从string切换为uuid时本质是在候选类型数组中切换。⚠️ 注意不支持的 MariaDB 字段类型如BLOB、BIT、SET、GEOMETRY等会在字段配置中单独展示。这类字段需要开发适配后才能在 NocoBase 中作为普通字段使用。主键和记录唯一标识用于页面区块展示和编辑的数据表建议有主键或唯一字段。NocoBase 会优先使用主键作为记录唯一标识。如果接入的是视图、无主键表或联合主键表需要在数据表配置中手动设置「Record unique key」。没有可用唯一标识时页面区块可能无法正确查看、编辑或删除记录。关于「记录唯一标识」的自动推断DatabaseIntrospector.collectionOptionsByFields()database-introspector.ts给出了完整的优先级规则优先使用自增字段autoIncrement作为filterTargetKey联合主键多个primaryKey会映射为数组形式的唯一标识只有一个主键时使用该主键字段无主键时若恰好只有一个唯一字段unique则回退使用该唯一字段。此外对于视图对象如果通过上述规则仍没有filterTargetKey但视图中存在名为id的字段则自动将filterTargetKey设置为id见同文件 L144-L153。理解这套推断顺序有助于你判断哪些表可以自动可用哪些表必须手动配置「Record unique key」。相关链接外部数据库 — 查看外部数据库的通用配置和管理说明数据源管理 — 查看数据源入口和数据源管理方式数据表字段 — 查看字段类型和字段映射说明【免费下载链接】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），仅供参考