# forward-gateway 转发网关 **Repository Path**: cy469971983/forwardgateway ## Basic Information - **Project Name**: forward-gateway 转发网关 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-31 - **Last Updated**: 2026-07-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # forward-gateway 转发网关 部署在中间机 **B** 上的简单转发网关,让可上外网的机器 **A** 与不能上外网的多台第三方设备 **C**(C1、C2...)之间互相调用 HTTP 接口,并支持 **TCP 端口转发**(如 S7 协议)让 A 直接访问 C 的 PLC。 ## 架构拓扑 ``` +--------+ +----------------+ +--------+ | 机器 A | <-------> | 机器 B (本网关) | <-------> | 机器 C1 | | 可上外网 | 外网可达 | port: 9000 | 局域网 +--------+ +--------+ | A/C 双向转发 | <-------> | 机器 C2 | +----------------+ +--------+ ``` - **A 调 C**:A → `http://:9000/forward/c/{deviceId}/**` → 对应 C 设备 - **C 调 A**:C → `http://:9000/forward/a/**` → A 服务 - **A 走 TCP 访问 C 的 PLC**:A --TCP/S7--> B:10201 --> C1:102(每台 C 设备一个映射端口,见「TCP 端口转发」章节) 网关透传:请求方法(GET/POST/PUT/DELETE/PATCH)、请求头(自动剔除 Host、Content-Length 等 hop-by-hop 头)、查询参数、请求体(JSON / 表单 / 二进制),并原样返回响应状态码、响应头与响应体。 ## 技术栈 - Spring Boot 2.7.18(JDK 8 兼容) - Maven 构建,仅依赖 `spring-boot-starter-web` + Apache HttpClient - RestTemplate 转发 HTTP,支持连接/读取超时配置 - TCP 端口转发基于 JDK 自带的 Java NIO(Selector + SocketChannel),无额外依赖 ## 配置说明(application.yml) ```yaml server: port: 9000 # 网关监听端口 gateway: connect-timeout: 5000 # 连接超时(毫秒),同时作为 TCP 转发连接目标设备的超时 read-timeout: 30000 # 读取超时(毫秒) connection-request-timeout: 5000 # 从连接池获取连接的超时(毫秒),避免池耗尽时无限等待 max-total-connections: 200 # 连接池最大总连接数 max-per-route: 50 # 连接池每个路由(目标主机)最大连接数 access-token: "" # 可选访问令牌,为空(默认)不校验;非空时请求必须带 X-Gateway-Token 头 a-server: base-url: http://:8080 # A 服务地址 c-devices: # C 设备列表:deviceId -> baseUrl c1: http://192.168.1.101:8080 c2: http://192.168.1.102:8080 tcp-forwards: # TCP 端口转发规则(见下文),不配置则不启动 TCP 监听 - name: c1-s7 listen-port: 10201 target-host: 192.168.1.101 target-port: 102 ``` ### 可选访问令牌(access-token) 默认 `access-token` 为空,网关不做任何校验,开箱即用。配置非空后,所有 `/forward/**` 请求必须携带相等的 `X-Gateway-Token` 请求头,否则返回 `401`: ```yaml gateway: access-token: "my-secret-token" ``` ```bash # 调用时携带令牌 curl -H "X-Gateway-Token: my-secret-token" "http://192.168.1.100:9000/forward/c/c1/api/device/status" ``` 令牌不匹配时返回: ```json {"error":"unauthorized","message":"缺少或错误的 X-Gateway-Token 请求头"} ``` > 注意:`access-token` 只作用于 HTTP 转发(`/forward/**`),TCP 端口转发是纯字节流透传,不做鉴权。 ### 如何新增 C 设备 只需在 `gateway.c-devices` 下加一行,重启网关即可: ```yaml c-devices: c1: http://192.168.1.101:8080 c2: http://192.168.1.102:8080 c3: http://192.168.1.103:8080 # 新增设备 c3 ``` ## TCP 端口转发(S7 等协议) ### 用途 A 端的 Java 程序需要用 **S7 协议(TCP 102 端口)** 访问多台 C 设备的 PLC,但 A 无法直连 C。网关在 B 机上为每台 C 设备监听一个本地端口,把 TCP 字节流原样双向透传到该设备的 `102` 端口: ``` A 程序(PLC4X / Moka7 等) --TCP--> B机:10201 --TCP--> C1:102 B机:10202 --TCP--> C2:102 ``` 该转发是**协议无关的纯字节流透传**,因此除 S7 外,Modbus TCP、OPC UA、数据库端口等任意 TCP 协议都可以照同样方式配置。 ### 配置方式 在 `application.yml` 的 `gateway` 下配置 `tcp-forwards` 列表,每条规则四个字段: ```yaml gateway: tcp-forwards: - name: c1-s7 # 规则标识,仅用于日志区分 listen-port: 10201 # B 机监听端口 target-host: 192.168.1.101 # C 设备 IP target-port: 102 # S7 协议端口 - name: c2-s7 listen-port: 10202 target-host: 192.168.1.102 target-port: 102 # SAP RFC 协议转发(端口 = 3300 + SAP 实例号) - name: c1-sap-rfc listen-port: 13300 target-host: 192.168.1.101 target-port: 3300 - name: c2-sap-rfc listen-port: 13301 target-host: 192.168.1.102 target-port: 3300 ``` - **列表为空或未配置 `tcp-forwards` 时,不启动任何 TCP 监听**,网关行为与纯 HTTP 网关一致。 - 单条规则端口被占用或配置非法(端口越界、缺少 `target-host`、`listen-port` 重复)时,只跳过该条并打 WARN,不影响其他规则和 HTTP 转发。 - 建议监听端口统一用 `102xx` 段(如 c1→10201、c2→10202),便于与设备编号对应。 ### 如何新增设备 在 `tcp-forwards` 下追加一条规则,分配一个未占用的监听端口,重启网关即可: ```yaml - name: c3-s7 listen-port: 10203 target-host: 192.168.1.103 target-port: 102 ``` 同时确保 B 机防火墙放行新的监听端口(仅对 A 机开放)。 ### A 端如何改 PLC 连接地址 A 端程序不需要改协议或代码逻辑,只把 PLC 的连接地址从「C 设备 IP:102」换成「B 机 IP:映射端口」即可。假设 B 机 IP 为 `192.168.1.100`: | C 设备 | 原连接地址(A 直连不通) | 改为(经网关) | | --- | --- | --- | | C1 | `192.168.1.101:102` | `192.168.1.100:10201` | | C2 | `192.168.1.102:102` | `192.168.1.100:10202` | ```java // 以 PLC4X 为例:原来 // "s7://192.168.1.101:102?remote-rack=0&remote-slot=1" // 改为 String url = "s7://192.168.1.100:10201?remote-rack=0&remote-slot=1"; // 以 Moka7 为例:原来 client.ConnectTo("192.168.1.101", 0, 1) client.ConnectTo("192.168.1.100", 0, 1); // 默认端口 102 时需改用支持指定端口的 API ``` > 注意:部分 S7 客户端库默认写死 102 端口,若无法指定端口,可把某台 C 设备的 `listen-port` 直接配成 `102`(需 B 机上 102 端口空闲,Linux 下监听 1024 以下端口需相应权限)。此时一个 102 端口只能映射一台设备,多设备仍建议用高位端口。 ### SAP RFC 转发 SAP RFC 同样是 **TCP 协议**,可直接复用上面的 `tcp-forwards` 透传,无需任何额外能力。其端口计算规则为 `3300 + 实例号`: | SAP 实例号(sysnr) | RFC 端口 | | --- | --- | | 00 | 3300 | | 01 | 3301 | | 02 | 3302 | A 端 JCo 只需把 `jco.client.ashost` 改为 B 机 IP: - 若 B 上的 `listen-port` 与 SAP 端口一致(即直接监听 `3300`),则 `jco.client.sysnr` 保持不变; - 若用了不同的映射端口(如示例中的 `13300`),JCo 无法直接用 `sysnr` 表达该端口,需要相应调整(例如另配一台 B 监听规范端口 `3300`,或采用能显式指定端口的连接方式)。 JCo 配置示例对照(假设 B 机 IP 为 `192.168.1.100`,C1 实例号为 `00`): ```properties # 改前:A 直连 C1(不通) jco.client.ashost=192.168.1.101 jco.client.sysnr=00 jco.client.client=100 jco.client.user=RFCUSER # 改后:经网关(B 上 listen-port 直接监听 3300,sysnr 不变) jco.client.ashost=192.168.1.100 jco.client.sysnr=00 jco.client.client=100 jco.client.user=RFCUSER ``` > 提示:若按本文示例把 `listen-port` 设为 `13300`(≠3300),因 `sysnr` 只能表达 `3300+实例号` 的规范端口,此时应在 B 上直接监听 `3300` 以保持 `sysnr=00` 不变,或改用支持显式指定端口的连接串。 ### 实现与日志 - 基于 Java NIO:单个 `Selector` 线程(`tcp-forward-selector`)处理所有监听端口与所有连接的读写事件,不会一个连接一个线程;带背压控制(对端写不下时暂停读),支持半关闭。 - 连接目标设备的超时复用 `gateway.connect-timeout`。 - 日志示例: ``` TCP 转发监听启动 [c1-s7] 0.0.0.0:10201 -> 192.168.1.101:102 TCP 连接建立 [c1-s7] /192.168.0.10:53124 -> 192.168.1.101:102(当前连接数 1) TCP 连接关闭 [c1-s7] #1 /192.168.0.10:53124 -> 192.168.1.101:102,上行 128 字节,下行 512 字节,持续 1532ms,原因:双方关闭 ``` - 目标设备不可达 / 连接超时 / 转发过程中出错,记录 WARN 并关闭该连接对,不影响其他连接。 - 网关关闭时(`destroy`)会优雅停止事件循环、关闭所有监听端口与在途连接。 ## 构建与启动 ```bash # 构建(需要 JDK 8+ 和 Maven) mvn package # 启动 java -jar target/forward-gateway-1.0.0.jar # 也可以在启动时覆盖配置(无需改 jar 包内配置文件) java -jar target/forward-gateway-1.0.0.jar --server.port=9000 --gateway.a-server.base-url=http://10.0.0.5:8080 # 或将 application.yml 放在 jar 同级目录 config/ 下,Spring Boot 会自动优先加载外部配置 ``` ## 调用示例 假设 B 机 IP 为 `192.168.1.100`,网关端口 `9000`。 ### A 端如何调用 C 设备 原本 A 想调 C1 的 `GET /api/device/status`,现在改为调网关: ```bash # GET(带查询参数) curl "http://192.168.1.100:9000/forward/c/c1/api/device/status?id=123" # POST JSON 到 C2 curl -X POST "http://192.168.1.100:9000/forward/c/c2/api/device/command" \ -H "Content-Type: application/json" \ -d '{"cmd":"restart"}' ``` 即:把原始 URL 的 `http://:<端口>` 替换为 `http://:9000/forward/c/`。 deviceId 未配置时返回 `404`: ```json {"error":"device_not_found","deviceId":"c9","message":"未找到设备 [c9] 的配置..."} ``` ### C 端如何调用 A 服务 原本 C 想调 A 的 `POST /api/report`,现在改为调网关: ```bash curl -X POST "http://192.168.1.100:9000/forward/a/api/report" \ -H "Content-Type: application/json" \ -d '{"deviceId":"c1","data":"..."}' ``` 即:把原始 URL 的 `http://:<端口>` 替换为 `http://:9000/forward/a`。 ### 验证 TCP 转发是否连通 ```bash # 在 A 机上测试到 B 机映射端口的连通性(通则说明 B -> C1:102 也已打通) telnet 192.168.1.100 10201 ``` ## 异常与日志 - 目标服务不可达 / 超时:返回 `502` + JSON,包含目标地址与原因: ```json {"error":"bad_gateway","targetUrl":"http://192.168.1.101:8080/api/x","reason":"timeout","message":"转发到目标服务失败:..."} ``` - 每次转发都会记录一行日志:方法、源路径、目标 URL、状态码、耗时: ``` FORWARD POST /forward/c/c1/api/device/command -> http://192.168.1.101:8080/api/device/command [200] 35ms ``` ## 安全建议 - 本网关默认无鉴权,建议用防火墙限制 B 机的 9000 端口以及所有 TCP 转发监听端口(如 10201、10202)仅对 A 机和 C 设备所在网段开放。 - 如需轻量鉴权,可配置 `gateway.access-token`(见上文),要求调用方携带 `X-Gateway-Token` 请求头(仅对 HTTP 转发生效)。 - 生产环境建议不要直接使用 jar 内置的示例 IP,可将真实配置放在 jar 同级目录的 `config/application.yml` 中覆盖(Spring Boot 自动优先加载外部配置)。 - 网关对请求/响应体是全量缓冲转发(非流式),建议限制报文大小(如通过 `server.max-http-header-size` 及调用方约定),避免大报文耗尽内存。 ## 范围说明 本网关保持简单:HTTP 转发除可选的访问令牌外,不包含完整鉴权、限流、HTTPS、WebSocket 等能力;TCP 端口转发是纯字节流透传,不含 TLS、鉴权与限流。