Files
agent/tunnel/README.md
T
kicer 6a0aed2611 fix(tunnel): client 加心跳看门狗,半死链路 75s 主动重连
Mac 睡眠/切网后 TCP 半死,close 事件永远不来,client 会一直停在「已连接」而服务端早已踢掉。
新增:记录最近收帧时间,75s(连丢 3 个 25s 心跳)无任何帧即 terminate 走既有重连。
顺带把 client 日志时间从 UTC 改为东八区。
2026-11-17 15:01:54 +08:00

191 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
```bash
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",...}
```
## 服务器部署
```bash
cd tunnel
docker compose up -d
docker compose logs | grep TOKEN # 首次启动自动生成,记下来填到家里 client.yml
```
**不需要先写配置**:首次启动会自动生成 `./data/server.yml`,里面带一个随机 token 并打印到日志。
第二次启动直接复用,token 不会变。
裸跑也行(不写配置同样自动生成):
```bash
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` 字段:
```yaml
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` 声明端口归属:
```yaml
routes:
- port: 19001
service: agent
- port: 19002
service: nas
```
`client.yml` 用 `name` 对上:
```yaml
services:
- name: agent
port: 8090
- name: nas
port: 5000
```
`docker-compose.yml` 里把 19001/19002 的 `ports` 放开。**完全不看 Host 头**。
### 3. 一个端口 + 通配(没有域名,只有一个服务)
最简单:所有请求都给同一个服务。
```yaml
services:
- host: "*"
port: 8090
```
浏览器开 `http://<服务器IP>:19000` 就是它。
### 怎么选
| 你的情况 | 用哪个 |
|---|---|
| 有域名 | 方式 1 |
| 没域名,只暴露一个服务 | 方式 3(一行配置) |
| 没域名,要暴露多个服务 | 方式 2(一个服务一个端口) |
方式 1 和 2 **可以同时开**:19000 走 Host 路由,19001/19002 各钉死一个服务,互不干扰。
## 家里部署
```bash
node client.js # 读同目录 client.yml
node client.js /path/to/client.yml
```
```yaml
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 盯上的概率
- 断线自动重连(含半死链路:75 秒收不到任何帧即主动断开重连),启动时自检每个端口可达性(不可达只告警不退出)
## 隧道协议
一条 WebSocket 承载所有请求,用 `id` 多路复用。
```jsonc
// 服务器 → 家里
{"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,影响不大 |
## 排错
```bash
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 不一致