WebSocket TCP Relay 镜像文档

概述

WebSocket TCP Relay是一个轻量级服务器，主要功能是将WebSocket流量中继到任意TCP服务器，同时支持从指定目录提供静态文件服务。它适用于需要通过WebSocket协议访问传统TCP服务的场景，提供灵活的配置选项和多种部署方式。

核心功能与特性

• 流量中继：将客户端WebSocket连接转换为TCP连接，实现WebSocket到TCP服务的透明中继
• 静态文件服务：可从指定目录（--webroot）提供静态HTML、CSS、JavaScript等文件
• 安全支持：内置TLS加密功能，可通过配置证书实现HTTPS/WebSocket Secure (WSS) 连接
• 代理协议支持：可选启用PROXY协议，适用于需要传递客户端真实IP的上游服务
• 灵活配置：支持通过命令行参数或配置文件进行配置，满足不同部署需求

使用场景与适用范围

• 需要通过WebSocket协议访问TCP服务的网络环境
• 为TCP服务提供WebSocket接入层，简化客户端访问
• 结合静态文件服务，构建包含Web界面和后端TCP服务访问的一体化应用
• 开发环境中快速搭建WebSocket到TCP的代理服务

安装与部署

Docker快速启动

通过Docker/Podman可快速部署，镜像已发布至Docker Hub。基本运行命令：

bash
docker run --rm -it -p ***:*** cloudamqp/websocket-tcp-relay --upstream tcp://container:5672

Docker Compose示例

yaml
version: '3'
services:
  websocket-relay:
    image: cloudamqp/websocket-tcp-relay
    ports:
      - "***:***"
    volumes:
      - ./webroot:/app/webroot  # 挂载静态文件目录
      - ./certs:/app/certs      # 挂载TLS证书目录（如需启用TLS）
    command: --upstream tcp://backend-service:5672 --webroot /app/webroot
    restart: unless-stopped

使用方法

命令行参数说明

Usage: websocket-tcp-relay [arguments]
    -u URI, --upstream=URI           上游TCP服务器地址（例如：tcp://localhost:5672 或 tls://127.0.0.1:5671，必填）
    -b HOST, --bind=HOST             绑定地址（默认值：localhost）
    -p PORT, --port=PORT             绑定端口（默认值：***）
    --tls-cert=PATH                  TLS证书+链路径（默认值：./certs/fullchain.pem）
    --tls-key=PATH                   TLS证书密钥路径（默认值：./certs/privkey.pem）
    -P, --proxy-protocol             上游是否期望PROXY协议（默认值：false）
    -w PATH, --webroot=PATH          静态文件服务目录（默认值：./webroot）
    -c PATH, --config=PATH           配置文件路径
    -v, --version                    显示版本号
    -h, --help                       显示帮助信息

配置文件示例

支持INI格式配置文件，示例如下：

ini
[main]
# 上游TCP服务器地址（必填）
upstream = tcp://127.0.0.1:5672
# 绑定地址
bind = 127.0.0.1
# 绑定端口
port = ***
# 是否启用PROXY协议（true/false）
proxy-protocol = false
# 静态文件服务目录
webroot = /var/lib/wwwroot
# TLS证书路径
tls-cert = /etc/ssl/certs/fullchain.pem
# TLS证书密钥路径
tls-key = /etc/ssl/private/privkey.pem

使用配置文件启动：

bash
docker run --rm -it -p ***:*** -v ./config.ini:/app/config.ini cloudamqp/websocket-tcp-relay --config /app/config.ini

TLS配置

启用TLS加密（WSS协议）需指定证书路径，Docker环境中通过挂载证书目录实现：

bash
docker run --rm -it -p ***:*** \
  -v ./certs:/app/certs \
  cloudamqp/websocket-tcp-relay \
  --upstream tcp://container:5672 \
  --tls-cert /app/certs/fullchain.pem \
  --tls-key /app/certs/privkey.pem

注：./certs目录需包含fullchain.pem（证书链）和privkey.pem（私钥）文件。

常见问题

• 静态文件访问：通过http://<服务器地址>:<端口>/文件名访问--webroot目录下的静态文件
• 中继验证：可通过WebSocket客户端连接ws://<服务器地址>:<端口>验证中继功能
• 证书错误：TLS启动失败时，检查证书路径是否正确及证书与密钥是否匹配