从安装配置到 ORA-28513 / ORA-28500 的分层排障实战Oracle 客户端经 Oracle Server、Database Gateway 访问 SQL Server基于 Oracle Database Gateway for Microsoft SQL Server 11.2.0.4Windows更新日期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 网络层。错误变化本身就是定位证据。结论先行先用 DUALdblink 验证基础链路再查业务视图先看错误来自哪一层再改对应配置。不要因为 DB Link 查询失败就反复删除、重建 DB Link。2. 架构与组件职责组件所在位置职责Oracle DatabaseOracle 服务器解析 SQL通过 TNS 别名连接 Gateway并维护 Database Link。Gateway ListenerWindows Gateway 主机监听 Oracle Net 请求按静态 SID 启动 dg4msql.exe。dg4msql AgentGateway Home登录 SQL Server、翻译 SQL 与数据类型并将结果返回 Oracle。SQL Server远端数据库服务器在业务 TCP 端口接受连接并执行查询。两个端口不要混淆Gateway Listener 端口示例 1521供 Oracle 连接 GatewaySQL Server 端口示例 1433/1443供 Gateway 连接 SQL Server。它们属于不同链路。3. 环境与前置条件项目示例值说明Oracle 数据库11.2.0.4数据库端可运行在 Linux 或 Windows。Gateway11.2.0.4 x64安装在能访问 SQL Server 的 Windows 主机。SQL Server2008 / 兼容版本本文原始环境为 SQL Server 2008新版本需核对认证矩阵。Gateway 程序dg4msql专用 Microsoft SQL Server Gateway不是通用 dg4odbc。示例 TNS 别名TIJIANOracle 端使用的连接别名。示例 Gateway SIDMSSQLGW同时出现在 init 文件名、listener.ora 和 tnsnames.ora。确认 Gateway 主机可以解析或访问 SQL Server 主机名/IP。确认 SQL Server 已启用 TCP/IP并明确静态端口或实例名。确认 Gateway 与 SQL Server 的位数、驱动和支持版本符合部署要求。正式发布前将真实 IP、账号和密码替换为安全配置不在博客或工单中暴露明文凭据。4. 下载与安装 Oracle Database GatewaysOracle 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 主机、实例和数据库最终仍应核对生成的 initSID.ora版本提示11g 已属于遗留版本。若目标 SQL Server 或 Windows 版本较新应优先查 Oracle 认证矩阵、补丁要求和支持策略不要仅凭“能够安装”判断“受支持”。5. 三份配置必须形成同一个命名闭环本例统一使用 Gateway SIDMSSQLGW。下列三处必须一致否则 Agent 可能找不到正确初始化文件或启动错误的 Gateway 实例。位置必须出现的值示例dg4msql\admin初始化文件名initMSSQLGW.oralistener.oraSID_NAMEMSSQLGWtnsnames.oraCONNECT_DATA / SIDMSSQLGW5.1 配置 initSID.ora文件路径示例D:\product\11.2.0\tg_1\dg4msql\admin\initMSSQLGW.ora# 显式端口省略实例名 HS_FDS_CONNECT_INFO192.0.2.20:1443//HISDB # 排障阶段开启稳定后改回 OFF HS_FDS_TRACE_LEVELDEBUG # 生产环境不要使用示例弱口令 HS_FDS_RECOVERY_ACCOUNTGW_RECOVER HS_FDS_RECOVERY_PWDSTRONG_PASSWORD三种常见连接形式场景写法注意事项指定端口省略实例host:port//database端口与实例名不要同时填写。指定命名实例host/instance/database依赖实例解析/SQL Server Browser。默认实例与默认端口host//database确认服务实际监听 1433。本次踩坑错误写法将逗号端口、默认实例 MSSQLSERVER 和数据库名混在一起。修正为 host:port//database 后错误从 ORA-28513 变成 ORA-28500 Connection refused证明 Gateway 已能正确解析连接串并尝试访问目标端口。5.2 配置 Gateway 的 listener.oraLISTENER (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) ) )PROGRAMdg4msql 表示使用专用 SQL Server Gateway。静态注册的 Gateway 服务在 lsnrctl services 中显示 status UNKNOWN 通常是正常现象并不表示服务异常。5.3 配置 Oracle 数据库端 tnsnames.oraTIJIAN (DESCRIPTION (ADDRESS (PROTOCOL TCP) (HOST 192.0.2.10) (PORT 1521) ) (CONNECT_DATA (SID MSSQLGW) ) (HS OK) )关键参数(HSOK) 告诉 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\lsnrctlstartLISTENER 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 已识别该 SID7. 创建 Database Link先查再建PUBLIC Database Link 不会出现在 USER_DB_LINKS 中。本次排障中USER_DB_LINKS 返回 no rows selected但再次创建同名 public link 却报 ORA-02011原因就是现有链接属于 PUBLIC。查询当前用户可见的公有/私有 Database LinkSELECTowner,db_link,username,hostFROMall_db_linksWHEREUPPER(db_link)LIKETIJIAN%;确认不存在同名链接后再创建CREATEPUBLICDATABASELINK tijianCONNECTTOnetstar IDENTIFIEDBYPASSWORDUSINGTIJIAN;安全提示不要把真实密码粘贴到博客、聊天或截图中。PUBLIC Database Link 对数据库中所有用户可见应使用最小权限 SQL Server 账号并在凭据暴露后立即轮换。8. 正确的验证顺序验证 TNS 能定位 Gateway Listenertnsping TIJIAN。验证 Listener 已识别静态 Gateway SIDlsnrctl services LISTENER。验证 Gateway 能建立最小远端会话SELECT * FROM dualtijian。基础链路成功后再验证简单实体表与 schema 限定名。最后再查询复杂视图并逐列排查不兼容数据类型。-- 1. 最小链路测试SELECT*FROMdualtijian;-- 2. schema 限定的简单对象SELECTCOUNT(*)FROMdbo.SIMPLE_TABLEtijian;-- 3. 最后测试业务视图SELECTCOUNT(*)FROMdbo.V_REGLISREQUESTtijian;为什么先测 DUAL如果 DUAL 都失败问题与业务视图、字段类型和 schema 无关继续拆视图没有意义。Oracle 官方配置指南也使用 SELECT * FROM DUALdblink 验证 Gateway。9. 本次故障复盘错误如何一步步变得更具体阶段现象证据与结论下一步1ORA-28513 ORA-02063Gateway Agent 内部失败业务视图、COUNT(*)、空结果查询均失败。停止查视图改测 DUAL开启 DEBUG trace。2USER_DB_LINKS 无记录但创建报 ORA-02011现有链接为 PUBLIC不是链接缺失。改查 ALL_DB_LINKS/DBA_DB_LINKS。3DUALTIJIAN 仍报 ORA-28513确认与业务对象无关故障在 Gateway 初始化/连接阶段。核对 SID、init 文件名、listener、tnsnames。4修正连接串后变为 ORA-28500 Connection refuseddg4msql 已正常启动并调用 SQL Server Wire Protocol目标端口拒绝连接。检查 SQL Server TCP 端口、服务和防火墙。9.1 ORA-28513代理层错误ORA-28513: internal error in heterogeneous remote agent ORA-02063: preceding line from TIJIANORA-28513 本身很泛不能直接说明是表结构问题。若 DUAL 也失败应优先检查SID_NAME、tnsnames 中的 SID 与 initSID.ora 文件名是否完全一致。listener.ora 的 ORACLE_HOME 是否确实指向 Gateway Home。PROGRAM 是否与安装组件一致专用 SQL Server Gateway 使用 dg4msql。HS_FDS_CONNECT_INFO 是否混用了逗号端口、端口与实例名。是否在正确的 init 文件中设置 HS_FDS_TRACE_LEVELDEBUG。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-NetConnection192.0.2.20-Port 1443Test-NetConnection192.0.2.20-Port 1433测试结果判断处理1443False1433True实际监听默认端口 1433将连接串改为 host:1433//database。1443False1433False端口未监听或被网络阻断检查 SQL Server 服务、TCP/IP、绑定地址和防火墙。1443TrueTCP 可达继续检查登录、加密策略、数据库名和账号权限。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 成功、业务视图仍失败只有在 DUALdblink 成功之后才进入对象层排障。对于 SQL Server 视图先在 SQL Server 查询输出字段类型再逐列测试。SELECTORDINAL_POSITION,COLUMN_NAME,DATA_TYPE,CHARACTER_MAXIMUM_LENGTH,NUMERIC_PRECISION,NUMERIC_SCALEFROMINFORMATION_SCHEMA.COLUMNSWHERETABLE_NAMEV_REGLISREQUESTORDERBYORDINAL_POSITION;11g Gateway 环境应重点关注以下类型datetime2、datetimeoffset、time、dateuniqueidentifier、xmlnvarchar(max)、varchar(max)、varbinary(max)image、text、ntext常用处理方式是在 SQL Server 创建面向 Oracle 的兼容视图显式 CAST 为较传统的数据类型并避免 SELECT *CREATEVIEWdbo.V_REGLISREQUEST_ORACLEASSELECTCAST(request_guidASvarchar(36))ASrequest_guid,CAST(created_atASdatetime)AScreated_at,CAST(xml_payloadASvarchar(4000))ASxml_payload,request_statusFROMdbo.V_REGLISREQUEST;12. 常见现象速查现象/错误最可能层级优先动作ORA-02011 duplicate database link nameDB Link 元数据查询 ALL_DB_LINKS确认是否已有 PUBLIC 链接。ORA-28513Gateway Agent测试 DUAL、核对命名闭环、开启 DEBUG trace。ORA-28500 Connection refusedTCP/SQL Server检查目标 IP、端口、SQL Server TCP/IP 与防火墙。ORA-02063错误上下文它只说明前面的错误来自哪个 DB Link根因看上一条错误。status UNKNOWN静态 Listener 注册通常正常关注是否有 handler 以及 Agent 能否启动。DUAL 成功业务视图失败对象/数据类型schema 限定、逐列测试、创建兼容视图。13. 上线前最终检查Gateway 安装包为 5of7安装组件为 Oracle Database Gateway for Microsoft SQL Server。initSID.ora、listener SID_NAME、tnsnames SID 三处一致。listener 的 ORACLE_HOME 指向 Gateway HomePROGRAMdg4msql。TNS 描述符包含 (HSOK)。明确区分 Gateway Listener 端口与 SQL Server 业务端口。Gateway 主机到 SQL Server 端口的 Test-NetConnection 成功。DUALdblink 成功后再验证实体表和业务视图。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 和占位密码实际部署请替换为本地环境参数。原文安装截图作为历史界面示意保留。