企业官网建设流程全解析

• 数据库客户端
• 数据可视化
• 桌面应用

导读

Falcon（Plotly 出品的免费开源 SQL 客户端）内置了对 Oracle 数据库的支持，但其底层依赖 Node.js 的oracledb绑定，而该绑定并不随包附带 Oracle 客户端运行库——这是它与 Falcon 其他连接器（MySQL、PostgreSQL、SQLite 等）最大的不同。本文以仓库根目录的 ORACLE.md 为骨架，完整给出 Windows、macOS、Ubuntu 三个平台上免费 Oracle Instant Client 的安装步骤，并结合 oracle.js 驱动源码、constants.js 连接配置与 datastores.oracle.spec.js 测试用例，讲清"装什么、为什么装、装完如何验证"的完整闭环。

为什么 Oracle 连接需要单独安装客户端库

Falcon 通过oracledb（Oracle 官方 Node.js 驱动）访问 Oracle 数据库。与mysql、pg等纯 JS/自带原生绑定的驱动不同，oracledb的 npm 包只包含 JavaScript 绑定层与部分编译产物，不包含 Oracle 官方提供的客户端运行库（OCI / Instant Client）。因此，使用 Falcon 连接 Oracle 前，用户必须先完成两件事：

1. 在 Oracle 官网 注册账号（下载客户端库的必要前提，需要登录后才能下载）；
2. 按操作系统下载并配置免费的 Oracle Instant Client（Basic 或 Basic Lite 版本）。

从源码可以印证这一依赖关系：在 package.json 中，oracledb以源码包形式引入（oracledb-src-2.2.0.tgz，版本 v2.2.0）；而 webpack.config.base.js 将其声明为'oracledb': 'commonjs oracledb'的外部依赖。也就是说，运行时如果机器上缺少 Oracle 客户端库，驱动将无法真正建立连接。

Windows 平台安装步骤

Windows 下的安装核心是：下载 Instant Client Basic ZIP → 解压 → 加入 PATH → 安装对应的 Visual Studio 运行库。完整步骤如下：

1. 下载免费 64 位 Instant Client Basic ZIP 包（Oracle Technology Network 提供，需登录 Oracle 账号，即 ORACLE.md 所述的instantclient-basic-windows.x64-12.2.0.1.0.zip）。
2. 解压到目标目录，例如C:\oracle\instantclient_12_2。建议放在无空格的纯英文路径下，避免潜在的路径解析问题。
3. 加入 PATH 环境变量：以 Windows 7 为例，路径为控制面板 → 系统 → 高级系统设置 → 高级 → 环境变量 → 系统变量 → PATH，在其中追加C:\oracle\instantclient_12_2。修改后需要重启终端（必要时重启 Falcon）才能生效。
4. 安装 Visual Studio 运行库：Instant Client 12.2 要求安装Visual Studio 2013 对应的 Redistributable（即 VS2013 可再发行组件包）。缺失该运行库时，oracledb在加载原生模块阶段就会报错（典型的 DLL 加载失败），因此这一步与第 3 步同等重要。

提示：若本机已装有其他版本的 Instant Client（如 19c / 21c），保持 PATH 中只有一个版本、且与oracledb兼容即可；Falcon 仓库锁定的驱动版本为 v2.2.0（见 package.json），实测以 12.2 客户端为基准。

macOS 平台安装步骤

macOS 下同样下载免费的Basic 64 位 ZIP（instantclient-basic-macos.x64-12.2.0.1.0.zip），解压后关键的一步是让动态链接器能找到libclntsh.dylib。官方推荐两种做法：

方式一：符号链接（推荐）

mkdir -p /opt/oracle unzip instantclient-basic-macos.x64-12.2.0.1.0.zip mkdir ~/lib ln -s instantclient_12_2/libclntsh.dylib.12.1 ~/lib/

即在用户默认库路径（~/lib或/usr/local/lib）中为 client shared library 创建符号链接，指向解压目录内的libclntsh.dylib.12.1。

方式二：直接复制所需 OCI 库

mkdir ~/lib cp instantclient_12_2/{libclntsh.dylib.12.1,libclntshcore.dylib.12.1,libons.dylib,libnnz12.dylib,libociei.dylib} ~/lib/

两种方式的本质相同：让oracledb加载原生模块时能通过系统动态库搜索路径找到 OCI 库。若运行 Falcon 时提示dyld: Library not loaded: @rpath/libclntsh.dylib一类错误，通常就是这一步未完成或路径不正确。

Ubuntu / Debian 平台安装步骤

Ubuntu 没有官方 .deb 格式的 Instant Client，因此社区通用的做法是通过alien将 Oracle 的 rpm 包转换为 deb 后安装。完整流程如下：

1. 安装所需依赖：

sudo apt-get -qq update && sudo apt-get --no-install-recommends -qq install alien bc libaio1

其中libaio1是异步 I/O 运行库，alien用于 rpm→deb 格式转换，bc为辅助工具。

2. 在 Oracle 官网注册账号（登录入口），并下载 Oracle Instant Client 的 rpm 包（仓库文档示例为oracle-xe-11.2.0-1.0.x86_64.rpm.zip，即 Oracle 11g XE 安装包；实际可下载对应的 instantclient rpm）。
3. 解压 rpm 包：

unzip oracle-xe-11.2.0-1.0.x86_64.rpm.zip

4. 转换为 deb 格式：

alien oracle-xe-11.2.0-1.0.x86_64.rpm

5. 安装生成的 deb 包：

sudo dpkg -i oracle-instantclient12.2-basiclite_12.2.0.1.0-2_amd64.deb

安装完成后，客户端库默认位于/usr/lib/oracle/12.2/client64/lib。运行时需要让动态链接器找到该目录——Falcon 仓库的 CONTRIBUTING.md 明确给出了运行 Oracle 单元测试前需要设置的环境变量：

export LD_LIBRARY_PATH=/usr/lib/oracle/12.2/client64/lib:$LD_LIBRARY_PATH

安装完成后：Falcon 侧如何对接

客户端库装好后，Falcon 即可通过其 Oracle 驱动 oracle.js 建立连接。该驱动暴露了与 Falcon 其他数据源一致的接口：connect、tables、schemas、query、disconnect，并由 Datastores.js 中的getDatastoreClient在dialect === 'oracle'时分发到该模块（见 Datastores.js）。

连接参数的底层实现：驱动通过oracledb.getConnection建立连接，只依赖三个字段（见 oracle.js）：

• user：对应界面上的 Username；
• password：对应界面上的 Password；
• connectionString：对应界面上的 Connection 字段。

这与 Falcon 界面表单（constants.js 中的CONNECTION_CONFIG[DIALECTS.ORACLE]）完全一致——Falcon 的 Oracle 连接表单只包含这三个输入项，其中 Connection 字段可填写：

• Easy Connect 字符串，如localhost/XE（主机/SID 或主机/服务名格式）；
• Net Service Name（来自本地tnsnames.ora或外部命名服务）；
• 本地 Oracle 实例的 SID；
• 或留空以连接本地默认数据库。

注意：Falcon 的 Oracle 表单没有独立的 Host/Port/Database 输入框，主机与实例信息全部通过connectionString表达，这一点与 MySQL、PostgreSQL 等连接器不同。仓库内置的 Oracle 示例连接（constants.js 中SAMPLE_DBS.ORACLE）即为{username: 'XDB', password: 'xdb', connectionString: 'localhost/XE'}，可直接作为配置格式参考。

查询能力：驱动在执行查询时会把 Buffer 类型的列值转换为十六进制字符串，并返回{columnnames, rows}结构（见 oracle.js）；表列表查询排除MDSYS、SYS、SYSTEM等系统 schema，并过滤名称含$的表与 XMLTYPE 类型表（见 oracle.js）。此外，Falcon 对 Oracle 的预览查询使用SELECT * FROM ${table} WHERE ROWNUM <= 1000（见 constants.js 中PREVIEW_QUERY），这也符合 Oracle 不支持LIMIT的语法特点。

端到端验证：Docker 测试库与单元测试

安装是否正确，最可靠的验证方式是利用仓库自带的 Oracle 测试环境。仓库在 test/docker/oracle 提供了基于wnameless/oracle-xe-11g的 Dockerfile（见 Dockerfile），它会启动一个 Oracle 11g Express 实例，预置登录账号SYSTEM/oracle、XDB/xdb以及样例数据库consumption2010（建表与数据导入逻辑见 setup.sql 与 setup.ctl）。

构建并启动测试库：

docker build test/docker/oracle -t falcon-test-oracle docker run --rm -ti -p 1521:1521 falcon-test-oracle

对应的 npm 脚本已封装在 package.json 中：docker:oracle:build与docker:oracle:start。

容器启动并输出Ready后，另开终端（确保已设置LD_LIBRARY_PATH，Ubuntu 环境）运行 Oracle 单元测试：

export LD_LIBRARY_PATH=/usr/lib/oracle/12.2/client64/lib:$LD_LIBRARY_PATH yarn run test-unit-oracle

测试用例 datastores.oracle.spec.js 覆盖了完整链路：connect建连成功、tables返回CONSUMPTION2010表、schemas返回['CONSUMPTION2010', 'LOCATION', 'VARCHAR2']等行列结构、query执行SELECT * FROM CONSUMPTION2010 WHERE ROWNUM <= 5并断言返回的前 5 行数据，以及disconnect断开连接。值得注意的是，该测试文件在require('oracledb')失败时会自动跳过（见 datastores.oracle.spec.js）——这正是"客户端库未安装"场景的典型表现，若测试被跳过，请先回头检查前文的安装步骤。

常见问题排查速查

小结

Oracle 是 Falcon 众多连接器中唯一需要用户预先自行安装客户端运行库的类型，其安装步骤因平台而异：Windows 侧重 PATH 与环境依赖，macOS 侧重动态库符号链接，Ubuntu 侧重 rpm→deb 转换与LD_LIBRARY_PATH。完成安装后，可结合 oracle.js 驱动、constants.js 连接配置以及 datastores.oracle.spec.js 测试用例，快速验证从建连、列表、取 schema 到执行查询的完整链路是否打通。

• 数据库客户端
• 数据可视化
• 桌面应用