3.4 集成与外部数据源：接上别的车间

3.4 集成与外部数据源：接上别的车间

本节摘要：集成回答「平台之外的数据与能力怎么接进来」：外部数据库整库接入是最粗的一根管子，API 与工作流节点是最灵活的软管，界面嵌入是最后那道门。本节讲三种接法的机制与边界，并用「老系统渐进迁移」一例展示组合用法。

权限把内场锁好了，现在把门开向外面。多数组织不是从零开始：财务系统在跑、老 CRM 在跑、还有一堆导出表格在邮件里飞。NocoBase 的集成定位是「调度台」——把散落各处的数据与动作接进来统一呈现与编排，而不是把这些系统吃掉。

一、外部数据源：最粗的一根管子

外部数据源插件把已有的 MySQL、PostgreSQL、MariaDB 整库接入，接入后库里的表原样出现在数据表列表里，区块、筛选、关系引用全都可用。配置只需要连接信息，动作序列如下：

接入外部库（设置 → 数据源管理 → 新建）：
  1. 类型选 PostgreSQL，填主机、端口、库名、账号口令
  2. 连接测试通过 → 保存 → 该库的表出现在数据表列表
  3. 点开任一外部表 → 字段与索引原样展示
  4. 对外部表新建区块 → 像用本地表一样拖配置
  注意事项：
  · 为平台单独建一个数据库账号，只授予必要表的权限
  · 结构变更（加字段改类型）回原库做，平台侧刷新结构即可
  · 大表先评估行数与索引，列表区块务必配默认筛选与分页
​

管子粗，规矩也多。外部表的读写边界要分清：读通常没问题，写则要克制——写入会绕过原系统自己的校验逻辑，并发写同一行还可能跟老系统打架。经验法则：外部表优先只读，确要写入时配权限范围收紧到特定角色，并错开原系统的批处理窗口。

图 3-3 集成拓扑：调度台与三个车间的接线

二、HTTP 节点与 API：最灵活的软管

不成库、只成接口的能力——发消息、查快递单、取汇率——用工作流的 HTTP 请求节点接，或者在前端用自定义请求接。这条软管的拧法在 3.1 见过一次，这里补三颗关键螺丝：超时时间要设，外部服务慢会拖住整条流程；鉴权信息放配置而不是明文写死在参数里；失败重试要有节制，外部接口抖动时不该放大成消息轰炸。

反方向的管子同样重要：NocoBase 自身对外提供 API，别处的系统能拉平台里的数据。给外部系统配独立密钥与独立角色（3.3 的规矩），接口粒度的权限就复用了三层锁。当某个外部系统既不能给库、又需要深交互时，别硬接——把同步任务做在中间层，按小时批量同步到主库，比实时双向同步可靠得多。

三、组合实战：老系统的渐进迁移

一桩典型工单把三种接法串起来：某公司有跑了六年的订单系统，数据库不敢动、界面没人爱用。迁移策略分三步走。第一步「只读并跑」：订单库整库接入，在平台上配查询页面与统计图表，老系统继续承担录入——用户先在新界面上获得洞察，迁移阻力大幅下降。第二步「写路切换」：新订单录入在平台表单完成，平台把数据写回订单库（写权限只授给这一个角色、这几张表），老系统退化为查询终端。第三步「结构收编」：一年后按真实使用情况把仍有价值的表迁入主库，其余外部链接保留。整个迁移没有停机日，每一步都留了退路——这就是调度台模式的价值：它不要求一场婚礼，只要求多次握手。

⚠️ 常见坑：把外部数据源当成「跨库联表」的万能钥匙。关系字段可以跨数据源建，但关联查询的执行与索引在外部库那边，大表跨源关联的性能坑非常深——跨源的关联尽量用流程同步成冗余字段，而不是实时联查。

💡 关键直觉：集成的成熟度不看接了多少系统，看断开任何一路之后，主业务是否仍能降级运行。接线的前提是两头都能独立站立。

深入一格：外部数据源连接的参数底账

接入外部库时，连接配置里每颗螺丝都有讲究，把底账列出来，出问题时按图索骥：

// 外部数据源连接配置骨架（界面上逐项填写）
{
  "name": "legacy-orders",               // 数据源标识，建好后不改
  "dialect": "postgres",                 // 库类型，决定方言与能力
  "host": "10.0.0.12",                   // 内网地址，勿用公网裸连
  "port": 5432,
  "database": "orders",
  "username": "nocobase_ro",             // 专用账号，最小授权原则
  "password": "配置在环境变量或密钥管理里，不进配置导出包",
  "options": { "poolSize": 5 }           // 连接池：小团队 5 足够，防占满老库连接数
}
​

三颗螺丝值得多看一眼。账号螺丝：为平台单独建只读账号（示例里的 ro 后缀），把 3.4 的「外部表只读优先」落实在库的授权层面，而不只是平台配置层面——双保险的意义在于，配置被误改时库这边还有一道闸。连接池螺丝：老系统的连接数余量往往很小，平台这头把池子开太大，会把老应用挤下线，5 人左右是稳妥起点。结构刷新螺丝：外部库的表结构变更后，平台侧要做一次结构刷新才会感知，刷新前留意有无字段被改名——改名对平台意味着「删一列加一列」，配置引用会断。

集成的边界问答

问：平台里的数据能整库导出给别的系统吗？能，数据库就在你手里，但建议别让外部系统直连平台库。直连意味着表结构耦合——平台升级或结构调整时，外部系统跟着断。规范做法是走平台 API 加独立密钥，把「表结构」这个实现细节关在平台内部，外部只见接口契约。这条边界与 3.4 开头的老系统接入互为镜像：你接别人时用粗管，别人接你时用软管。

问：备份要不要包含外部数据源的数据？要分清责任边界。外部库的数据属于原系统，平台的备份清单不含它；但平台配置里引用外部表的部分（页面、区块、权限范围）必须随配置包备份。责任边界写成一行字贴进运维手册：平台备份平台的东西，外部的东西外部自己负责——写清楚，事故时才不会互相等待。

集成责任边界卡（接入每个外部源时填一张）：
  数据源：____________    接入方式：粗管或软管
  数据归属：____________  备份责任：____方
  结构变更通知人：______  平台侧刷新联系人：______
  故障时降级方案：____________
​

装配要点回顾

• 三种接法：外部数据源是粗管、HTTP 节点是软管、页面嵌入是门，按问题类型选管子；
• 外部表只读优先，写入收紧到特定角色并错开批处理窗口；
• 软管三螺丝：超时、鉴权配置化、有节制的重试；
• 渐进迁移三步：只读并跑、写路切换、结构收编，每步留退路；
• 跨源联表慎用：跨数据源的实时关联是性能深坑，能冗余就冗余；
• 下一站：第 4 章插件车间——当配置与集成都够不着时，自己造零件。