NocoBase 外部数据源 Oracle 实战指南Thin/Thick 连接模式、字段映射与表接入全流程【免费下载链接】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 中把 Oracle 数据库作为外部数据源接入覆盖插件安装、Thin/Thick 连接模式选择与 Oracle Instant Client 安装、连接配置项逐项说明、数据表读取范围控制Owner 账号 / Table prefix / Collections、字段类型自动映射规则以及主键与记录唯一标识的设置方法。读完后你可以将已有 ERP、MES、WMS、CRM 等业务系统的 Oracle 数据库直接接入 NocoBase在不迁移历史数据的前提下为其搭建管理界面、配置权限、工作流与 API。外部 Oracle 的定位只读结构不接管库Oracle 可以作为外部数据库接入 NocoBase。接入后NocoBase 会读取 Oracle 中的数据表、字段和视图并把它们作为外部数据源中的数据表使用。与主数据库不同外部 Oracle 的真实表结构仍由原业务系统、数据库客户端或迁移脚本维护。NocoBase 负责读取结构、保存字段元数据、配置页面区块、权限、工作流和 API。配置项说明支持版本Oracle 11g商业版本企业版支持对应插件nocobase/plugin-data-source-external-oracle连接模式Oracle Database 12.1 及以上版本通常使用 Thin 模式早于 12.1 的版本使用 Thick 模式适合使用外部 Oracle 的场景接入已有 ERP、MES、WMS、CRM 等业务系统的 Oracle 数据库在不迁移历史数据的情况下用 NocoBase 搭建管理界面对已有表做权限控制、流程处理、数据修正或报表展示数据库结构继续由 DBA、迁移脚本或原系统维护注意外部 Oracle 不是 NocoBase 的系统数据库。NocoBase 不会接管它的备份、还原、迁移和表结构变更。插件安装与依赖说明nocobase/plugin-data-source-external-oracle是商业插件需要企业版许可证激活激活方式见 NocoBase 官方商业插件激活指南。该插件未包含在本开源仓库中因此本文以官方文档描述其行为为准并结合仓库中外部数据源的公共实现nocobase/data-source-manager核心包与 plugin-data-source-manager 插件说明底层机制。如果连接模式选择 Thick需要在 NocoBase 运行环境中安装 Oracle Client libraries并在数据源配置里填写「Client directory」。从仓库结构看外部数据源插件统一通过nocobase/data-source-manager包提供的DataSourceManager/DatabaseIntrospector机制完成表结构读取与字段推断Oracle 插件在其上提供 Oracle 方言的 introspector 与类型映射。安装 Oracle 客户端Thick 模式Oracle Database 12.1 及以上版本通常使用 Thin 模式不需要额外安装 Oracle Client。只有当你连接 Oracle Database 12.1 之前的版本或者必须使用 Thick 模式时才需要在 NocoBase 运行环境中安装 Oracle Client libraries。在数据源配置中选择「Thick」模式后需要确认 NocoBase 服务所在机器可以加载 Oracle Client。Linux 环境可以参考下面的方式安装 Oracle Instant Clientapt-get update apt-get install -y unzip wget libaio1 wget https://download.oracle.com/otn_software/linux/instantclient/1925000/instantclient-basic-linux.x64-19.25.0.0.0dbru.zip unzip instantclient-basic-linux.x64-19.25.0.0.0dbru.zip -d /opt/ echo /opt/instantclient_19_25 /etc/ld.so.conf.d/oracle-instantclient.conf ldconfig各步骤的作用libaio1是 Oracle Instant Client 在 Linux 上运行所需的异步 I/O 库依赖将 Instant Client 解压到/opt/instantclient_19_25通过/etc/ld.so.conf.d/oracle-instantclient.confldconfig让动态链接器能加载客户端库。如果 Oracle Client 不是安装在系统默认可加载的位置需要在「Client directory」中填写客户端库目录。比如上面的安装方式对应目录是/opt/instantclient_19_25。提示Client directory只在 Thick 模式下需要配置Thin 模式不使用这个配置。更多初始化规则可以参考 node-oracledb 的初始化文档Oracle 官方 node-oracledb 库的 user_guide/initialization 章节。添加数据源与连接配置在「数据源管理」中点击「Add new」选择 Oracle然后填写连接信息。常见连接配置如下配置说明Data source name数据源标识名称用于页面区块、权限、工作流和 API 中引用。创建后不能修改。Data source display name数据源在界面中显示的名称建议使用业务人员能理解的名称比如「ERP Oracle」「财务库」。Host / PortOracle 主机地址和端口。默认端口通常是1521。ServerNameOracle 服务名。填写数据库监听中配置的 service name。Username / Password用于连接 Oracle 的账号和密码。NocoBase 读取这个账号 Owner 下的数据表和视图不会授权或读取其他 Owner 下的对象。Connection modeOracle 连接模式。Oracle Database 12.1 及以上版本通常使用 Thin 模式早于 12.1 的版本使用 Thick 模式。Client directoryOracle Thick 模式下的 Oracle Client libraries 目录。只有选择 Thick 模式时才需要配置。Table prefix表名前缀。配置后NocoBase 只读取匹配该前缀的数据表和视图并在 NocoBase 中生成不带前缀的数据表名称。Collections / Add all collections控制接入范围。启用「Add all collections」时NocoBase 会接入当前 Owner 和前缀范围内的全部表和视图关闭后只接入你在「Collections」里勾选的对象。Enabled the data source是否启用这个数据源。关闭后数据源配置会保留但页面区块、权限、工作流和 API 无法继续读取它的数据。提示Oracle 中的接入范围主要由连接账号 Owner、Table prefix和「Collections」决定。如果同一个实例里对象很多建议使用专门账号连接业务需要的 schema减少无关对象进入 NocoBase。Table prefix 在源码中的实现Table prefix的行为可以在仓库中外部数据源的公共 introspector 中得到印证。DatabaseIntrospector.getTables 会在拉取表列表后按tablePrefix做前缀过滤if (this.db.options.tablePrefix) { tableList tableList.filter((tableName) { return tableName.startsWith(this.db.options.tablePrefix); }); }而生成 NocoBase 数据表名时tableInfoToCollectionOptions 会把前缀剥离tableName.replace(this.db.options.tablePrefix, )并把表名中的.替换为_——这解释了为什么 Oracle 中SCHEMA.TABLE这类带点号的对象名进入 NocoBase 后会变成下划线形式的数据表名。选择数据表500 张上限与 Load Collections填写连接信息后可以点击「Load Collections」读取 Oracle 中可用的数据表和视图。读取结果会受到连接账号 Owner、Table prefix和「Collections」配置影响。默认会启用「Add all collections」表示接入当前范围内的全部表和视图。如果只想接入部分对象可以关闭「Add all collections」然后在列表中勾选需要的数据表或视图。注意单个外部数据源一次最多接入 500 张数据表或视图。如果 Oracle 中对象很多建议先通过连接账号 Owner、Table prefix或「Collections」收窄范围。这一上限与默认行为在前端组件中可以直接确认。CollectionsTableField 中定义了硬性上限并决定「Add all」的默认状态const MAX_SELECTION_LIMIT 500; const defaultAddAllCollections tableProps.formValues?.options?.addAllCollections undefined ? true // 未显式配置时默认勾选「Add all collections」 : tableProps.formValues?.options?.addAllCollections;同时该组件会把tablePrefix与勾选状态联动只有表名以tablePrefix开头的对象才会随勾选状态参与接入见 CollectionsTableField.tsx 第 56–77 行 的enrichedDisplayCollections逻辑。同步和配置字段外部 Oracle 的表结构由数据库侧维护。NocoBase 不会在外部 Oracle 中创建字段、修改字段类型或删除真实字段。当 Oracle 侧表结构发生变化时可以在数据源中执行「Sync from database」重新读取表和字段元数据。同步会更新 NocoBase 中保存的数据表、字段、主键、唯一键和字段类型映射信息但不会删除 Oracle 中的真实表或数据。从源码结构看同步走的是DatabaseIntrospector.getCollection流程getCollection 方法依次调用describeTable读取列信息、showIndex读取约束再把每列转换为字段选项columnInfoToFieldOptions并区分出「受支持的字段」与「不受支持的字段」后者记录在unsupportedFields中例如无法映射的 BLOB 类类型。字段同步后可以在 NocoBase 中配置字段标题、字段类型Field type和字段组件Field interface。如果需要建立 NocoBase 关系字段也是在 NocoBase 中保存关系元数据不会在 Oracle 表里自动新增真实外键字段。字段类型映射NocoBase 会根据 Oracle 字段类型自动映射到合适的 Field type 和 Field interface。你可以在字段配置中调整界面展示方式。映射的实现入口是 introspector 的 inferFieldTypeByRawType它先按方言dialect取fieldTypeMap来自nocobase/database再从typeInterfaceMap见 type-interface-map.ts取得该类型对应的可选 Field interface。常见映射如下Oracle 字段类型NocoBase Field type可选 Field interfaceNUMBERinteger、float、boolean、bigInt、unixTimestamp、sortInteger、Number、Sort、Checkbox、Switch、Select、Radio groupBINARY_FLOAT、BINARY_DOUBLE、FLOATfloatNumber、PercentINTEGER、SMALLINT、PLSQL_INTEGERinteger、boolean、sortInteger、Sort、Checkbox、Switch、Select、Radio groupCHAR、NCHAR、VARCHAR2、NVARCHAR2string、uuid、nanoid、datetimeNoTzInput、Email、Phone、Password、Color、Icon、Select、Radio group、UUID、Nano IDLONG、NCLOBstring、textInput、Textarea、Markdown、Vditor、Rich textCLOBstringInput、Textarea、Rich textDATEdatetimeNoTzDate、Time、Created at、Updated atTIMESTAMPdatetimeNoTzDate、Time、Created at、Updated atTIMESTAMP WITH TIME ZONE、TIMESTAMP WITH LOCAL TIME ZONEdatetimeTzDate、Time、Created at、Updated atROWID、UROWIDstring、text、integerInput、Textarea、IntegerJSONjsonJSON两个值得注意的点Oracle 的DATE被映射为datetimeNoTz而非datetimeTz。因为 OracleDATE类型本身不含时区信息只有TIMESTAMP WITH (LOCAL) TIME ZONE才映射到带时区的datetimeTz跨时区展示时需要留意这一点。同一原始类型可以映射到多种 Field type例如VARCHAR2可作string、uuid或datetimeNoTz这是为了让同一列可以按业务需要选择不同界面组件同步后可以在字段配置中调整。注意BLOB、BFILE等二进制对象类型不会自动作为普通文件字段使用。如果需要在页面中管理附件通常建议在 NocoBase 中使用文件表或附件字段保存文件元信息。主键和记录唯一标识用于页面区块展示和编辑的数据表建议有主键或唯一字段。NocoBase 会优先使用主键作为记录唯一标识。如果接入的是视图、无主键表或联合主键表需要在数据表配置中手动设置「Record unique key」。没有可用唯一标识时页面区块可能无法正确查看、编辑或删除记录。从源码结构看约束信息来自 DatabaseIntrospector.getTableConstraints内部调用showIndex主键/唯一键正是在字段推断阶段由这些约束推导出来并写回 collection 元数据的视图还会在存在id字段时被自动设置filterTargetKey idgetCollection 中第 144–153 行这正是「视图接入后通常可以直接用 id 过滤」的底层原因。延伸阅读外部数据库通用说明 — 查看外部数据库的通用配置和管理说明数据源管理 — 查看数据源入口和数据源管理方式数据表字段 — 查看字段类型和字段映射说明核心实现DatabaseIntrospector、字段类型-接口映射表、CollectionsTableField 组件适用前提与限制小结Oracle 插件为商业插件企业版适用于 Oracle 11g 及以上12.1 建议 Thin 模式零客户端依赖更早版本需 Thick 模式并正确配置Client directory单个数据源最多 500 张表/视图NocoBase 对外部 Oracle 只做结构读取与元数据维护不做备份、还原或 DDL 变更。【免费下载链接】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），仅供参考