2.6. 多发比对网关部署说明

本章节介绍比对服务网关的部署方法，以及微服务伪多发的配置注意事项。

2.6.1. 多发比对网关简介

多发比对网关是基于 OpenResty 的服务，支持将请求发送给多个对接不同数据库的微服务；这些微服务正确集成了伪多发后，将 SQL 执行数据汇报给比对服务，实现多个异构库微服务的数据比对。

多发网关支持的特性包括：

支持配置多个目标端
支持多目标端 Session 保持
以业务请求为维度生成 TraceID

2.6.2. 多发比对网关部署

2.6.2.1. 启停服务

获取安装包后，使用 unzip 命令解压。

在bin目录下提供有 lightdb-gateway.sh 脚本，可用于启停服务。

请调用 ./lightdb-gateway.sh --help 查看此脚本的详细使用方法。

2.6.2.2. 修改配置

在 conf目录下提供有为不同业务定制的配置脚本，对于服务端口号及其他配置都修改根目录下的 conf/业务/nginx.conf 。具体业务服务名称请咨询lightdb相关支持同学。

例如： ta相关的服务，需要在 conf/ta/ 下修改。

警告

不要修改 nginx/conf 下的文件，这个目录下每次启动会被覆盖。

2.6.2.3. 修改端口与 host 配置

用户需要编辑 nginx.conf ，以修改以下配置：

监听地址
监听端口

要使用网关，一定需要一个 host ，否则与各个微服务的 Session 会无法处理。假设用户使用 example.com 为 host ，需要找到 server { 下面的 server_name 进行修改。

备注

如果没有 DNS 服务，则可能需要配置 hosts 才可以访问网关，需要将 example.com 绑定到网关所在的地址。方法示例 (Windows)：编辑 C:\Windows\System32\drivers\etc\hosts 文件，添加如下内容： 10.20.30.40 example.com

默认端口为 8081 ，如果用户需要修改端口，需要找到 server { 下面的 listen 8081; ，修改为对应端口即可。

2.6.2.4. 修改配置文件

修改 config.lua ，在网关上配置多发到哪些节点，以及 UUID 处理服务的请求地址。

配置示例：

-- 主节点
_M.PRIMARY_NODE = { scheme = "http", host = "10.20.191.231", port = 8081 }

-- 多发节点列表 shadow_servers
_M.SHADOW_NODES = {
        { scheme = "http", host = "10.20.30.217", port = 8081 },
        { scheme = "http", host = "10.20.199.58", port = 8081 },
}

-- IP-机器用户名映射表：key=IP地址（字符串），value=机器用户名（纯字符串）
_M.IP_USER_MAP = {
        ["172.24.1.113"] = "zhangsan",    -- 主节点机器名
}

_M.NOTIFY_TIMEOUT_MILLIS = 10000
_M.COMPARISON_SERVER_URL = "http://10.20.193.103:17800/em"
_M.UUID_SERVICE_ADDR = "http://10.20.193.103:9091/ukagent"

用户需要修改 PRIMARY_NODE SHADOW_NODES UUID_SERVICE_ADDR 这三项配置。

PRIMARY_NODE: 主节点配置，推荐配置为连 MySQL 或 Oracle 的微服务的地址
SHADOW_NODES: 多发节点列表，配置为需要多发到节点的微服务地址
NOTIFY_TIMEOUT_MILLIS: 通知超时时间，单位毫秒，默认值为 10000
COMPARISON_SERVER_URL: 比对服务地址，用于推送接口结束通知到比对服务
UUID_SERVICE_ADDR: UUID 处理服务地址，配置为 UUID 处理服务地址；UUID 服务的部署方式参考下一节的说明
IP_USER_MAP: IP-机器用户名映射表，用于根据请求 IP 地址确定目标机器的用户名，然后展示在比对服务的SQL比对报告中

2.6.3. 伪多发配置注意事项

微服务需要配置伪多发，才能与网关正确配合，实现数据比对；配置伪多发时有一些注意事项：

需要在 jrescloud.properties 中配置 UUID 服务地址，参数为 multi.uuidServiceUrl ，如 multi.uuidServiceUrl=http://10.20.191.231:9091/ukagent/putSyncUuid
需要注意 unisql.conf 中配置正确的元数据 Schema ，否则伪多发可能因无法找到元数据而失败；配置参数为 unisql.table.column.metadata.schemas ，如 SEE 需要配置 unisql.table.column.metadata.schemas = 'acm','acm_job','sys'

备注

由于业务系统可能采用自动生成的 UUID 作为主键插入到数据库中，所以引入了 UUID 服务专门来处理这种情况，使得主库微服务与所有其他目标库微服务的数据保持 ID 一致，避免后续业务无法进行。

2.6.4. 离线文件多发功能说明

本功能用于实现离线报文文件的多发传输，支持从日志文件中批量提取报文，并发发送到多个目标服务器。

通过Web界面，可以上传报文文件、启动发送任务、实时监控任务进度，以及查看详细的报文发送日志。

Web 界面访问 URL ： http://网关地址:端口/multiplex-gateway/offline-file-multiplex.html

2.6.4.1. 快速开始

配置发送目标端

使用前，需要调整网关的 config.lua 配置，添加发送目标端信息，如：

_M.OFFLINE_FILE_SEND_TARGETS = {
        { url = "http://10.20.30.40:28026/api/web/online/JDXJK/request" },
        { url = "http://10.20.30.41:28026/api/web/online/JDXJK/request" },
}

上传报文文件
- 点击侧边栏的”上传文件”按钮
- 选择符合格式的报文文件（文件名格式：message-xxx.txt）
- 确认上传
启动发送任务
- 点击侧边栏的”启动新任务”按钮
- 确认配置信息
- 开始发送
监控任务进度
- 在任务列表中查看任务状态
- 点击任务查看详细统计和日志

2.6.4.2. 详细操作指南

2.6.4.2.1. 使用帮助

页面右上角提供了”使用帮助”按钮，点击后会弹出帮助模态框，提供操作指南和常见问题解答。

2.6.4.2.2. 上传报文文件

操作步骤：

点击侧边栏的”上传文件”按钮，打开上传模态框

选择要上传的报文文件（支持多选）
- 文件名必须遵循格式：message-xxx.txt（如message-001.txt）
- 多个文件按数字顺序编号
确认上传
- 系统会先清空服务器上的已有文件
- 上传成功后会在配置中显示文件列表

注意事项：

上传前请确保本地已备份文件
文件名格式必须正确，否则无法上传
支持同时上传多个文件

2.6.4.2.3. 启动发送任务

操作步骤：

点击侧边栏的”启动新任务”按钮，打开任务启动确认框

查看任务执行流程
- 系统会读取所有已上传的报文文件
- 提取符合格式的报文内容
- 并发发送到所有配置的目标服务器
- 记录发送和接收日志
确认启动
- 点击”确认启动”开始任务
- 任务会自动在后台执行
- 可以在任务列表中查看进度

注意事项：

任务执行期间请勿关闭页面
系统支持同时向多个目标发送报文
发送过程会对目标服务器产生网络压力

2.6.4.2.4. 查看任务详情

操作步骤：

在侧边栏的任务列表中点击要查看的任务

查看任务基本信息
- 任务ID和创建时间
- 任务状态（等待中、处理中、已完成、已失败）
- 处理的文件数量和目标数量
查看统计信息
- 总报文数：从文件中提取的报文总数
- 成功发送：成功发送的报文总数
- 发送失败：发送失败的报文总数
- 成功率：成功发送报文的比例
查看目标进度
- 每个目标服务器的发送进度
- 各目标的成功率统计
- 实时显示已发送/总报文数
查看报文日志
- 点击”查看统计”查看日志统计概览
- 点击”查看日志”查看详细的收发记录
- 支持分页浏览日志

日志说明：

发送日志（📤）：显示发送到目标服务器的报文
接收日志（📥）：显示从目标服务器收到的响应
每条日志包含时间、目标地址、状态码和报文摘要

2.6.4.2.5. 查看配置信息

操作步骤：

点击页面右上角的”查看配置”按钮
查看待发送文件列表
- 显示所有已上传的文件
- 文件按名称排序
查看发送目标配置
- 显示所有目标服务器的URL
- 每个目标支持自定义超时和重试配置

2.6.4.3. 常见操作问题

文件上传失败

可能原因：

文件名格式不正确
- 正确格式：message-xxx.txt
- 示例：message-001.txt、message-002.txt
文件大小超出限制
- 默认上传文件尺寸限制为 1GB

解决方法：

若确实需要上传更大的文件，需要调整网关的 nginx.conf 配置，调整 client_max_body_size 参数为更大的值。

2.6.5. 业务资源映射功能说明

比对报告页面上有一列“业务操作资源”，默认是空的；若要正常利用这一列，需要在多发网关上配置菜单映射规则。

通过配置业务资源映射表，可以实现请求 URL 到业务资源的自动映射，让业务人员快速定位比对结果对应的业务操作位置。

2.6.5.1. 配置步骤

以操作员中心系统为例

# 检查配置目录
ls <网关配置目录>/conf/

# 应该包含：
# uf3_business_resource_mapping.lua (默认配置)

如果默认映射表满足需求，直接重启网关即可

# 重启网关使配置生效
./lightdb-gateway.sh restart <镜像名称> <配置目录>

其他业务系统

需要手工配置映射表：

创建或编辑映射表文件

-- custom_business_resource_mapping.lua
-- 业务资源映射表

return {
    ["resource_id_1"] = "参数-业务运营参数-档案管理-档案系统参数设置",
    ["resource_id_2"] = "运营-档案视频管理-档案管理-协议签署查询",
    -- 根据实际业务系统添加更多映射
}

修改 config.lua 配置，指定映射表文件路径

-- 在 config.lua 中添加或修改以下配置
_M.BUSINESS_RESOURCE_MAPPING_FILE = "custom_business_resource_mapping.lua"

# 复制到配置目录
cp custom_business_resource_mapping.lua <网关配置目录>/conf/

重启网关服务使映射生效

./lightdb-gateway.sh restart <镜像名称> <配置目录>

2.6.5.1.1. 映射表格式说明

映射表采用 Lua 表格式，包含资源 ID 到菜单名称的映射关系：

-- 业务资源映射表

return {
    ["agreementBusiConfig"] = "参数-业务运营参数-流媒体管理-投教视频协议设置",
    ["amsAgreementSignQry"] = "运营-档案视频管理-档案管理-协议签署查询",
    ["/tafund/loginHasValidateCode"] = "登录条件检查",
}

关键字段说明：

键(key): 资源 ID，对应业务系统请求中的 resource_id 或 menu_code 参数，或 URL
值(value): 菜单名称，格式为”父菜单-子菜单-按钮”，如 “运营-档案视频管理-档案管理-协议签署查询”

匹配规则：

网关按照以下优先级匹配业务资源：

优先使用请求参数中的 resource_id 查询映射表
如果 resource_id 为空，则使用 menu_code 参数查询
如果 resource_id 匹配失败，则尝试使用完整的 URL 查询
如果都未匹配到，则 X-MULTIPLEX-BIZRES 头为空，比对报告中”业务操作资源”列显示为空

2.6.5.2. 操作员中心系统映射表配置辅助方式

对于操作员中心系统，可以使用辅助工具从系统中导出菜单数据并生成映射表。这些工具仅作为辅助手段，不是正式的配置流程。

工具一：Python 脚本

使用管理员账号登录操作员中心系统
获取操作员中心菜单 JSON 数据，也就是按下 F12 ，找到 /g/hsxone.omc/v/getUserAuthMenus 返回的 json 保存起来
使用 Python 脚本生成映射表

# 运行生成脚本（脚本位于网关镜像中，可从镜像中提取）
python3 generate_resource_mapping.py menu_data.json uf3_business_resource_mapping.lua

工具二：浏览器 JavaScript 脚本（辅助调试用）

使用管理员账号登录操作员中心系统
打开浏览器开发者工具（F12），切换到”控制台”(Console)标签
执行以下 JavaScript 脚本获取菜单数据并生成映射表：

// 注意：此脚本仅用于辅助调试，生成的映射表需要手动复制保存
// 实际生产环境建议使用 Python 脚本或直接手工配置

(async function() {
    try {
        const response = await fetch('/g/hsxone.omc/v/getUserAuthMenus?menu_type=hui');
        if (!response.ok) throw new Error(`HTTP错误: ${response.status}`);

        const data = await response.json();
        const mappings = {};

        function processNode(node, path = []) {
            if (!node) return;
            const title = node.title || '';
            const newPath = title ? [...path, title] : path;
            if (node.url && newPath.length > 0) {
                mappings[node.id] = newPath.join('-');
            }
            if (node.children && Array.isArray(node.children)) {
                node.children.forEach(child => {
                    if (child !== null && child !== undefined) {
                        processNode(child, newPath);
                    }
                });
            }
        }

        data.forEach(item => { if (item) processNode(item); });

        const sortedMappings = {};
        Object.keys(mappings).sort((a, b) => {
            const aNum = Number(a), bNum = Number(b);
            return (!isNaN(aNum) && !isNaN(bNum)) ? aNum - bNum : a.localeCompare(b);
        }).forEach(key => sortedMappings[key] = mappings[key]);

        let luaCode = '-- 业务资源映射表\n-- 自动生成，请勿手动修改\n\nreturn {\n';
        Object.entries(sortedMappings).forEach(([key, value]) => {
            luaCode += `    ["${key}"] = "${value.replace(/"/g, '\\"')}",\n`;
        });
        luaCode += '}\n';

        // 在浏览器中显示生成的映射表
        console.log(`成功生成 ${Object.keys(mappings).length} 条映射`);
        console.log('\n映射表内容:');
        console.log(luaCode);

        // 提示用户复制
        const textarea = document.createElement('textarea');
        textarea.value = luaCode;
        textarea.style.cssText = 'position:fixed;top:50px;left:0;width:100%;height:300px;zIndex:9999;background:#1e1e1e;color:#d4d4d4;font-family:monospace;font-size:14px;border:2px solid #007acc;padding:10px;';
        document.body.appendChild(textarea);
        textarea.select();

        alert(`已生成 ${Object.keys(mappings).length} 条映射，请复制文本框内容到 uf3_business_resource_mapping.lua 文件`);

    } catch (error) {
        console.error('处理失败:', error);
        alert('生成失败: ' + error.message);
    }
})();

复制生成的 Lua 代码并保存为 uf3_business_resource_mapping.lua 文件
部署到网关配置目录并重启网关

2.6.5.3. 常见操作问题

映射表未生效

可能原因：

网关未重启或配置未重新加载
映射表文件路径不正确
应用程序是 HSIAR + JresCloud T3 协议，链路上部分应用未部署多发程序

解决方法：

重启网关服务，确保配置生效
检查映射表文件是否在网关的 conf 目录下
检查 Lua 语法是否正确，不正确的话会导致启动失败
如果是 HSIAR + JresCloud 架构，最好相关的服务都集成多发