从安装配置到 ORA-28513 / ORA-28500 的分层排障实战

Oracle 客户端经 Oracle Server、Database Gateway 访问 SQL Server

基于 Oracle Database Gateway for Microsoft SQL Server 11.2.0.4（Windows）

更新日期：2026-07-30

摘要｜本文在原有 Oracle 11g 透明网关安装笔记基础上，补充一次真实故障复盘：最初查询报 ORA-28513，修正 Gateway SID 与连接串后错误推进为 ORA-28500，从而确认代理已经正常、剩余问题位于 SQL Server 端口或网络层。全文给出可复用配置模板、验证顺序和错误码判断方法。

1. 为什么还要写这篇文章

Oracle Database Gateway 的配置文件不多，但每个名字都必须彼此对应；同时，一条数据库链路跨越 Oracle 数据库、Oracle Net Listener、Gateway Agent、SQL Server 网络协议和远端对象五个层次。只看最终 SQL 报错，很容易在错误层级反复修改。

这次排障最重要的经验不是某一行参数，而是建立“错误推进”的意识：当 ORA-28513 变成带有 ODBC 原生信息的 ORA-28500 时，说明故障已经从代理初始化层推进到了 SQL Server 网络层。错误变化本身就是定位证据。

结论先行｜先用 DUAL@dblink 验证基础链路，再查业务视图；先看错误来自哪一层，再改对应配置。不要因为 DB Link 查询失败就反复删除、重建 DB Link。

2. 架构与组件职责

两个端口不要混淆｜Gateway Listener 端口（示例 1521）供 Oracle 连接 Gateway；SQL Server 端口（示例 1433/1443）供 Gateway 连接 SQL Server。它们属于不同链路。

3. 环境与前置条件

• 确认 Gateway 主机可以解析或访问 SQL Server 主机名/IP。

• 确认 SQL Server 已启用 TCP/IP，并明确静态端口或实例名。

• 确认 Gateway 与 SQL Server 的位数、驱动和支持版本符合部署要求。

• 正式发布前，将真实 IP、账号和密码替换为安全配置，不在博客或工单中暴露明文凭据。

4. 下载与安装 Oracle Database Gateways

Oracle Database 11.2.0.4 Windows x64 补丁集 13390677 被拆分为 7 个压缩包，其中 Gateway 对应第 5 个包：

p13390677_112040_MSWIN-x86-64_5of7.zip

解压后运行 setup.exe，在产品组件中选择 Oracle Database Gateway for Microsoft SQL Server。建议安装到独立 Oracle Home，例如：

D:\product\11.2.0\tg_1

原文历史截图：在安装器中选择 Oracle Database Gateway for Microsoft SQL Server

安装器会询问 SQL Server 主机、实例和数据库；最终仍应核对生成的 init<SID>.ora

版本提示｜11g 已属于遗留版本。若目标 SQL Server 或 Windows 版本较新，应优先查 Oracle 认证矩阵、补丁要求和支持策略；不要仅凭“能够安装”判断“受支持”。

5. 三份配置必须形成同一个命名闭环

本例统一使用 Gateway SID=MSSQLGW。下列三处必须一致，否则 Agent 可能找不到正确初始化文件，或启动错误的 Gateway 实例。

5.1 配置 init<SID>.ora

文件路径示例：D:\product\11.2.0\tg_1\dg4msql\admin\initMSSQLGW.ora

# 显式端口，省略实例名HS_FDS_CONNECT_INFO=192.0.2.20:1443//HISDB# 排障阶段开启，稳定后改回 OFFHS_FDS_TRACE_LEVEL=DEBUG# 生产环境不要使用示例弱口令HS_FDS_RECOVERY_ACCOUNT=GW_RECOVERHS_FDS_RECOVERY_PWD=<STRONG_PASSWORD>

三种常见连接形式：

本次踩坑｜错误写法将逗号端口、默认实例 MSSQLSERVER 和数据库名混在一起。修正为 host:port//database 后，错误从 ORA-28513 变成 ORA-28500 Connection refused，证明 Gateway 已能正确解析连接串并尝试访问目标端口。

5.2 配置 Gateway 的 listener.ora

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = 192.0.2.10)(PORT = 1521))
(ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1521))
)
)SID_LIST_LISTENER =
(SID_LIST =
(SID_DESC =
(SID_NAME = MSSQLGW)
(ORACLE_HOME = D:\product\11.2.0\tg_1)
(PROGRAM = dg4msql)
)
)

PROGRAM=dg4msql 表示使用专用 SQL Server Gateway。静态注册的 Gateway 服务在 lsnrctl services 中显示 status UNKNOWN 通常是正常现象，并不表示服务异常。

5.3 配置 Oracle 数据库端 tnsnames.ora

TIJIAN =
(DESCRIPTION =
(ADDRESS =
(PROTOCOL = TCP)
(HOST = 192.0.2.10)
(PORT = 1521)
)
(CONNECT_DATA =
(SID = MSSQLGW)
)
(HS = OK)
)

关键参数｜(HS=OK) 告诉 Oracle Net：目标是异构服务，而不是普通 Oracle 数据库实例。

6. 重启并验证 Gateway Listener

务必使用 Gateway Home 自己的 lsnrctl，避免误操作数据库 Oracle Home 下的监听器：

D:\product\11.2.0\tg_1\bin\lsnrctl stop LISTENER
D:\product\11.2.0\tg_1\bin\lsnrctl start LISTENER
D:\product\11.2.0\tg_1\bin\lsnrctl services LISTENER

预期看到类似输出：

Service "MSSQLGW" has 1 instance(s).
Instance "MSSQLGW", status UNKNOWN, has 1 handler(s) for this service...

原文历史截图：Gateway 静态服务显示 UNKNOWN，但 Listener 已识别该 SID

7. 创建 Database Link：先查再建

PUBLIC Database Link 不会出现在 USER_DB_LINKS 中。本次排障中，USER_DB_LINKS 返回 no rows selected，但再次创建同名 public link 却报 ORA-02011，原因就是现有链接属于 PUBLIC。

查询当前用户可见的公有/私有 Database Link

SELECT owner, db_link, username, hostFROM all_db_linksWHERE UPPER(db_link) LIKE 'TIJIAN%';

确认不存在同名链接后再创建

CREATE PUBLIC DATABASE LINK tijianCONNECT TO netstarIDENTIFIED BY "<PASSWORD>"USING 'TIJIAN';

安全提示｜不要把真实密码粘贴到博客、聊天或截图中。PUBLIC Database Link 对数据库中所有用户可见，应使用最小权限 SQL Server 账号，并在凭据暴露后立即轮换。

8. 正确的验证顺序

1. 验证 TNS 能定位 Gateway Listener：tnsping TIJIAN。

2. 验证 Listener 已识别静态 Gateway SID：lsnrctl services LISTENER。

3. 验证 Gateway 能建立最小远端会话：SELECT * FROM dual@tijian。

4. 基础链路成功后，再验证简单实体表与 schema 限定名。

5. 最后再查询复杂视图，并逐列排查不兼容数据类型。

-- 1. 最小链路测试SELECT * FROM dual@tijian;-- 2. schema 限定的简单对象SELECT COUNT(*) FROM "dbo"."SIMPLE_TABLE"@tijian;-- 3. 最后测试业务视图SELECT COUNT(*) FROM "dbo"."V_REGLISREQUEST"@tijian;

为什么先测 DUAL｜如果 DUAL 都失败，问题与业务视图、字段类型和 schema 无关；继续拆视图没有意义。Oracle 官方配置指南也使用 SELECT * FROM DUAL@dblink 验证 Gateway。

9. 本次故障复盘：错误如何一步步变得更具体

9.1 ORA-28513：代理层错误

ORA-28513: internal error in heterogeneous remote agent
ORA-02063: preceding line from TIJIAN

ORA-28513 本身很泛，不能直接说明是表结构问题。若 DUAL 也失败，应优先检查：

• SID_NAME、tnsnames 中的 SID 与 init<SID>.ora 文件名是否完全一致。

• listener.ora 的 ORACLE_HOME 是否确实指向 Gateway Home。

• PROGRAM 是否与安装组件一致：专用 SQL Server Gateway 使用 dg4msql。

• HS_FDS_CONNECT_INFO 是否混用了逗号端口、端口与实例名。

• 是否在正确的 init 文件中设置 HS_FDS_TRACE_LEVEL=DEBUG。

9.2 ORA-28500 + Connection refused：网络端口层错误

ORA-28500: connection from ORACLE to a non-Oracle system returned this message:
[Oracle][ODBC SQL Server Wire Protocol driver] Connection refused.
Verify Host Name and Port Number. {08001}
ORA-02063: preceding 2 lines from TIJIAN

这个错误反而更接近成功：Gateway 已启动、连接串已被解析、驱动已经发起 TCP 连接。当前无需重建 DB Link，应直接检查 SQL Server 监听端口。

在 Gateway Windows 主机执行

Test-NetConnection 192.0.2.20 -Port 1443
Test-NetConnection 192.0.2.20 -Port 1433

10. SQL Server 侧检查清单

• 在 SQL Server Configuration Manager 中启用 MSSQLSERVER 的 TCP/IP。

• 在 TCP/IP 属性的 IPAll 中确认 TCP Dynamic Ports 与 TCP Port；使用静态端口时清空动态端口。

• 修改网络协议或端口后重启 SQL Server 服务。

• 在 Windows 防火墙和中间网络设备上放通实际业务端口。

• 从 Gateway 主机使用 Test-NetConnection 或 sqlcmd 测试，不要只在 SQL Server 本机测试。

sqlcmd -S tcp:192.0.2.20,1443 -U netstar -d HISDB
-- 不带 -P，让工具交互式提示密码，避免密码进入命令历史。

11. 当 DUAL 成功、业务视图仍失败

只有在 DUAL@dblink 成功之后，才进入对象层排障。对于 SQL Server 视图，先在 SQL Server 查询输出字段类型，再逐列测试。

SELECT
    ORDINAL_POSITION,
    COLUMN_NAME,
    DATA_TYPE,
    CHARACTER_MAXIMUM_LENGTH,
    NUMERIC_PRECISION,
    NUMERIC_SCALEFROM INFORMATION_SCHEMA.COLUMNSWHERE TABLE_NAME = 'V_REGLISREQUEST'ORDER BY ORDINAL_POSITION;

11g Gateway 环境应重点关注以下类型：

• datetime2、datetimeoffset、time、date

• uniqueidentifier、xml

• nvarchar(max)、varchar(max)、varbinary(max)

• image、text、ntext

常用处理方式是在 SQL Server 创建面向 Oracle 的兼容视图，显式 CAST 为较传统的数据类型，并避免 SELECT *：

CREATE VIEW dbo.V_REGLISREQUEST_ORACLE ASSELECTCAST(request_guid AS varchar(36)) AS request_guid,CAST(created_at AS datetime) AS created_at,CAST(xml_payload AS varchar(4000)) AS xml_payload,
request_statusFROM dbo.V_REGLISREQUEST;

12. 常见现象速查

13. 上线前最终检查

• Gateway 安装包为 5of7，安装组件为 Oracle Database Gateway for Microsoft SQL Server。

• init<SID>.ora、listener SID_NAME、tnsnames SID 三处一致。

• listener 的 ORACLE_HOME 指向 Gateway Home，PROGRAM=dg4msql。

• TNS 描述符包含 (HS=OK)。

• 明确区分 Gateway Listener 端口与 SQL Server 业务端口。

• Gateway 主机到 SQL Server 端口的 Test-NetConnection 成功。

• DUAL@dblink 成功后再验证实体表和业务视图。

• PUBLIC DB Link 使用最小权限账号，文档中无真实密码。

• 排障完成后将 HS_FDS_TRACE_LEVEL 恢复为 OFF，并妥善保留关键 trace。

• 已核对目标 Windows/SQL Server 版本的认证与补丁要求。

最终经验｜好的排障不是一次猜中，而是让每一步都产生可区分的结果。本次从 ORA-28513 推进到 ORA-28500，正是因为先用 DUAL 隔离业务对象，再用一致的 SID 命名和规范连接串修复代理层，最后把问题准确落在 SQL Server 的 1443 端口。

14. 参考资料

• Oracle Database Gateway 11g Release 2 文档库

• Oracle Database Gateway for Microsoft Windows 安装与配置指南

• Oracle Database Gateway for SQL Server 11g 用户指南

• ORA-28513 官方错误说明

• Oracle Software Delivery Cloud

说明：本文示例使用文档保留地址 192.0.2.0/24 和占位密码，实际部署请替换为本地环境参数。原文安装截图作为历史界面示意保留。