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

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

2.6.1. 多发比对网关简介

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

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

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

2.6.2. 多发比对网关部署

2.6.2.1. 安装docker环境

多发比对网关的部署依赖于docker环境，需要先安装docker环境。如果系统已有docker环境，可跳过此步骤。

安装docker环境的方法请参考官方文档： https://docs.docker.com/engine/install/

内网环境不能连外网的情况下，可依据以下官方文档说明，下载离线安装包安装： https://docs.docker.com/engine/install/binaries/

2.6.2.2. 配置docker环境

需要通过配置docker环境，允许从从公司配置库: package.hundsun.com 拉取镜像。

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"insecure-registries":["package.hundsun.com"]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

执行命令 sudo docker login package.hundsun.com ，输入用户名密码登录。

用户名为您的域账号，密码为api-key (您可以在效能平台的右上角个人信息中，查看或重新生成api-key)。

2.6.2.3. 拉取LightDB网关镜像

从LightDB的docker制品库: lightdb1.0-docker-release-local(正式版本库)， lightdb1.0-docker-test-local(测试版本库,需单独申请权限)。可以查看LightDB网关程序的镜像名称及版本。

执行docker pull命令拉取镜像，样例如下:

sudo docker pull \
        package.hundsun.com/lightdb1.0-docker-test-local/01standard/lightdb1-0-v202503/lightdb1.0.v202503.01.000/lightdb-gateway:v202503-01-000

2.6.2.4. 获取网关配置

网关配置脚本在发布物中的 /config 目录下，需要将其复制到本地。通过下面命令可将配置脚本拷贝至当前用户的 $HOME/config 目录下。

sudo docker run -it --rm \
        -v $HOME:/configout <镜像名称> /bin/bash -c "cp -r  /config /configout/ "

2.6.2.5. 修改端口与 host 配置

用户需要编辑 conf/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.6. 修改配置文件

修改 conf/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 },
}

-- UUID 插入类功能 uri 清单
_M.UUID_SERVICE_TIMEOUT_MILLIS = 10000
_M.UUID_SERVICE_ADDR = "http://10.20.191.231:9091/ukagent/getLastSyncUuidStatus"
_M.UUID_INSERT_FUNCTIONS = {
        { uri = "/acm/dssp/script/save.json" },
        { uri = "/acm/dssp/product/mulUploads.json" },
}

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

PRIMARY_NODE: 主节点配置，推荐配置为连 MySQL 或 Oracle 的微服务的地址
SHADOW_NODES: 多发节点列表，配置为需要多发到节点的微服务地址
UUID_SERVICE_ADDR: UUID 处理服务地址，配置为 UUID 处理服务地址；UUID 服务的部署方式参考下一节的说明

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. 多发比对网关启停

查看 config 目录(从镜像中拷贝出来的)下的lightdb-gateway.sh脚本，执行 ./lightdb-gateway.sh --help ，可以查看脚本的帮助信息。

执行脚本相应命令，传入镜像名称，配置文件目录(例如: $HOME/config/see) 可以启动网关服务

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

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

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

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

2.6.5.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.5.2. 详细操作指南

2.6.5.2.1. 使用帮助

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

2.6.5.2.2. 上传报文文件

操作步骤：

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

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

注意事项：

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

2.6.5.2.3. 启动发送任务

操作步骤：

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

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

注意事项：

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

2.6.5.2.4. 查看任务详情

操作步骤：

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

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

日志说明：

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

2.6.5.2.5. 查看配置信息

操作步骤：

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

2.6.5.3. 常见操作问题

文件上传失败

可能原因：

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

解决方法：

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