server.js 原来用 req.on('aborted') 发 abort,但 SSE 是 GET 无 body,
这个事件只在传输请求体时触发(Node 也已废弃它),实际永远不触发。
后果:前端切会话时 es.close() 关掉旧 SSE,隧道这边收不到 abort,client 继续
读流、继续往 WS 灌数据,core 那边的 SSE 连接也没断。切到正在运行的会话就是
新旧两条流同时推,把单条 WS 占满,后发的 detail 请求只能排队 —— 表现为白屏 1-2 秒。
改挂 res.on('close'):正常结束时 pending 已删会直接返回,只在客户端提前断开时发 abort。
tunnel · 通用反向隧道
把本机(家里)的 HTTP 服务,经一台有公网 IP 的服务器中转出去。对访问方完全透明—— 浏览器看到的仍是标准 HTTP/SSE,服务本身不需要任何改造。
手机/浏览器 ──https──> nginx:443 ──> server.js ──WebSocket──> client.js ──> 127.0.0.1:<port>
(服务器) (家里)
- server.js 不认识任何业务:只按
Host头(或固定端口)把字节搬给 client - client.js 按
services配置把请求映射到本地端口 - 新增服务 = 改 client 配置一行,两边代码都不用动
启动顺序
没有严格要求。client 连不上会 1s→30s 指数退避重连,先起谁都能自动接上。 第一次配置建议先起 server,日志会直接告诉你 client 是否连上、token 对不对。
快速验证(本机,不碰 nginx)
cd tunnel && npm install # 国内慢就加 --registry=https://registry.npmmirror.com
cp client.example.yml client.yml # server 改成 ws://127.0.0.1:19000/tunnel,token 先留空
node server.js & # 首次启动生成 server.yml,日志打印 TOKEN
# 把 TOKEN 填进 client.yml 的 token,再:
node client.js &
curl -H "Host: agent.home.example.com" http://127.0.0.1:19000/api/health
curl -s http://127.0.0.1:19000/__tunnel/health # {"ok":true,"client":"online",...}
服务器部署
cd tunnel
docker compose up -d
docker compose logs | grep TOKEN # 首次启动自动生成,记下来填到家里 client.yml
不需要先写配置:首次启动会自动生成 ./data/server.yml,里面带一个随机 token 并打印到日志。
第二次启动直接复用,token 不会变。
裸跑也行(不写配置同样自动生成):
node server.js # 配置落在 ./server.yml
TUNNEL_CONFIG=/path/to/server.yml node server.js
请求怎么找到对应的服务
一台服务器、一个端口,请求进来后要决定「这个请求是给 agent 还是给 NAS」。三种做法:
1. 看域名(有域名时最自然)
agent.home.example.com → 家里 8090
nas.home.example.com → 家里 5000
隧道读请求里的 Host 头决定转发给谁。配置就是 client.yml 的 host 字段:
services:
- host: agent.home.example.com
port: 8090
需要 DNS 泛解析 *.home.example.com 指到服务器,前面再套一层 nginx 做 TLS。
2. 一个端口钉一个服务(没有域名,又要多个服务)
隧道同时监听好几个端口,每个端口只认一个服务名:
http://<服务器IP>:19001 → 固定给 agent
http://<服务器IP>:19002 → 固定给 NAS
server.yml 声明端口归属:
routes:
- port: 19001
service: agent
- port: 19002
service: nas
client.yml 用 name 对上:
services:
- name: agent
port: 8090
- name: nas
port: 5000
docker-compose.yml 里把 19001/19002 的 ports 放开。完全不看 Host 头。
3. 一个端口 + 通配(没有域名,只有一个服务)
最简单:所有请求都给同一个服务。
services:
- host: "*"
port: 8090
浏览器开 http://<服务器IP>:19000 就是它。
怎么选
| 你的情况 | 用哪个 |
|---|---|
| 有域名 | 方式 1 |
| 没域名,只暴露一个服务 | 方式 3(一行配置) |
| 没域名,要暴露多个服务 | 方式 2(一个服务一个端口) |
方式 1 和 2 可以同时开:19000 走 Host 路由,19001/19002 各钉死一个服务,互不干扰。
家里部署
node client.js # 读同目录 client.yml
node client.js /path/to/client.yml
server: "wss://agent.home.example.com/tunnel"
token: "<和服务器同一个>"
userAgent: "Mozilla/5.0 (...) Chrome/131.0.0.0 Safari/537.36"
services:
- name: agent
host: agent.home.example.com
port: 8090
name:固定端口路由用的服务标识(有域名时可省略)host:域名/*.example.com/"*"(兜底)userAgent:可选,握手时伪装浏览器 UA,降低被 DPI 盯上的概率- 断线自动重连,启动时自检每个端口可达性(不可达只告警不退出)
隧道协议
一条 WebSocket 承载所有请求,用 id 多路复用。
// 服务器 → 家里
{"id":"r1","op":"req","method":"POST","path":"/api/x","headers":{...},"service":"agent"}
{"id":"r1","op":"body","b64":"..."} // 请求体分帧
{"id":"r1","op":"end"}
{"id":"r1","op":"abort"} // 浏览器提前断开
// 家里 → 服务器(响应分帧,边收边转)
{"id":"r1","ev":"head","status":200,"headers":{...}}
{"id":"r1","ev":"data","b64":"..."}
{"id":"r1","ev":"end"}
{"id":"r1","ev":"error","msg":"..."}
service 只在「固定端口路由」时出现;没有它 client 就按 Host 头匹配。
已知边界
| 能力 | 状态 |
|---|---|
| 普通 HTTP / 大 body(测过 27 MB) | ✅ |
| SSE / 流式响应 | ✅ 逐帧透传(800ms/帧测试,间隔与直连一致) |
| 重定向(302) | ✅ 原样透传,不在隧道里跟跳 |
| 未知 Host | 502 |
| client 离线 | 503(快速失败,不挂住) |
固定端口路由 / * 通配 |
✅ |
| WebSocket 升级 | ❌ 未实现(需双向字节流,二期) |
| HTTP/2 | ❌ 对外仍是 1.1,影响不大 |
排错
curl -s http://127.0.0.1:19000/__tunnel/health # client 在不在线
tail -f /tmp/tunnel-client.log # 家里端
tail -f /tmp/tunnel-server.log # 服务器端
- 502 没有匹配的本地服务:
services[].host和请求 Host 不一致;无域名时用"*"或固定端口 - SSE 憋着不出来:nginx 少了
proxy_buffering off - 大 body 报
expect header not supported:旧版本才有,client 现在会剥掉Expect头 - 握手 401:两边 token 不一致