geely-kaipiao/proxy/PROTOCOL.md

代理通信协议设计文档

1. 架构概述

1.1 设备角色

设备	角色	能力	限制
电脑A	代理客户端	可访问内网网站，作为HTTP客户端	无法监听端口
电脑B	代理服务器	可监听端口，转发HTTP请求	无法直接访问内网

1.2 网络拓扑

浏览器 <--(端口8081)--> 电脑B <--(端口8080)--> 电脑A <--(HTTP)--> 目标网站

1.3 核心设计原则

1. 电脑A作为纯HTTP客户端：不保存cookie、session等状态信息
2. 请求头替换：电脑A强制替换Origin、Referer等参数
3. 日志对应：server端每一条请求日志，client端对应一条请求日志
4. 目标网站硬编码：目标网站地址写死在配置中

---

2. 端口分配

端口号	用途	连接方向
8080	设备A连接端口	电脑A → 电脑B
8081	浏览器访问端口	浏览器 → 电脑B

---

3. 通信协议

3.1 协议类型

采用 自定义HTTP代理协议，电脑B将浏览器请求转发给电脑A，电脑A作为HTTP客户端访问目标网站。

3.2 协议流程

阶段1：设备A连接到设备B

电脑A → 电脑B: TCP连接建立
电脑B → 电脑A: "PROXY_CONNECTED\r\n"
电脑A → 电脑B: "READY\r\n"

阶段2：浏览器发起请求

浏览器 → 电脑B: 完整HTTP请求
GET /max/js/jquery/lib.js HTTP/1.1
Host: localhost:8081
Origin: http://localhost:8081
Referer: http://localhost:8081/
[其他请求头...]

[请求体（如有）]

阶段3：电脑B转发请求

电脑B → 电脑A: 完整HTTP请求（透传）

阶段4：电脑A处理请求

1. 修改请求头：替换Origin、Referer为目标网站地址
2. 修改Host头：设置为目标网站地址
3. 移除不必要的头：如Connection、Keep-Alive等

阶段5：电脑A访问目标网站

电脑A → 内网目标: 修改后的HTTP请求
GET /max/js/jquery/lib.js HTTP/1.1
Host: zentao.sunyard.com.cn:9788
Origin: http://zentao.sunyard.com.cn:9788
Referer: http://zentao.sunyard.com.cn:9788/
[其他请求头...]

[请求体（如有）]

阶段6：电脑A返回响应

内网目标 → 电脑A: HTTP响应
电脑A → 电脑B: HTTP响应（透传）
电脑B → 浏览器: HTTP响应（透传）

阶段7：连接保持

• 电脑A与电脑B保持长连接
• 支持同一连接上的多个HTTP请求
• 连接空闲超时时间：300秒

---

4. 请求头处理规则

4.1 强制替换的请求头

请求头	替换值
Origin	http://{TARGET_HOST}:{TARGET_PORT}
Referer	http://{TARGET_HOST}:{TARGET_PORT}/
Host	{TARGET_HOST}:{TARGET_PORT}

4.2 移除的请求头

请求头	原因
Connection	由电脑A管理连接
Keep-Alive	由电脑A管理连接
Proxy-Connection	不需要代理标识
X-Forwarded-For	不需要转发标识

4.3 保留的请求头

所有其他请求头保持不变，包括：

• Accept
• Accept-Encoding
• Accept-Language
• User-Agent
• Cookie（如果有）
• Content-Type
• Content-Length

---

5. 数据格式

5.1 请求格式

电脑B转发给电脑A的请求格式为完整的HTTP请求：

{HTTP_METHOD} {REQUEST_PATH} HTTP/1.1\r\n
{HEADER_NAME}: {HEADER_VALUE}\r\n
...
\r\n
{REQUEST_BODY}

5.2 响应格式

电脑A返回给电脑B的响应格式为完整的HTTP响应：

HTTP/1.1 {STATUS_CODE} {STATUS_MESSAGE}\r\n
{HEADER_NAME}: {HEADER_VALUE}\r\n
...
\r\n
{RESPONSE_BODY}

---

6. 日志规范

6.1 日志格式

字段	格式	示例
时间戳	YYYY-MM-DD HH:MM:SS	2024-01-15 10:30:45
级别	[INFO] / [ERROR]	[INFO]
来源	[Browser] / [DeviceA] / [System]	[Browser]
行号	(line N)	(line 45)
内容	描述信息	请求详情

6.2 请求日志（电脑B）

[时间戳] [INFO] [Browser] (line N) Request: {METHOD} {PATH} - Body: {BYTES} bytes

6.3 请求日志（电脑A）

[时间戳] [INFO] [System] (line N) Request: {METHOD} {PATH} - Body: {BYTES} bytes

6.4 响应日志（电脑B）

[时间戳] [INFO] [Browser] (line N) Response: {METHOD} {PATH} - Status: {CODE} - Time: {MS}ms

6.5 响应日志（电脑A）

[时间戳] [INFO] [System] (line N) Response: {METHOD} {PATH} - Status: {CODE} - Time: {MS}ms

6.6 日志对应原则

server端有一条请求日志，client端必须有一条对应的请求日志：

电脑B: [2024-01-15 10:30:45] [INFO] [Browser] (line 45) Request: GET /max/js/jquery/lib.js - Body: 0 bytes
电脑A: [2024-01-15 10:30:45] [INFO] [System] (line 35) Request: GET /max/js/jquery/lib.js - Body: 0 bytes

---

7. 错误处理

7.1 设备A未连接

当浏览器请求时设备A未连接：

HTTP/1.1 503 Service Unavailable
Content-Type: text/plain

Device A not connected

7.2 目标不可达

当电脑A无法连接目标网站：

HTTP/1.1 502 Bad Gateway
Content-Type: text/plain

Cannot connect to target: zentao.sunyard.com.cn:9788

7.3 重复连接

当已有设备A连接时，拒绝新连接：

ERROR: Another A device is already connected

7.4 请求超时

当请求处理超时：

HTTP/1.1 504 Gateway Timeout
Content-Type: text/plain

Request timeout

---

8. 超时设置

操作	超时时间
设备A连接超时	10秒
目标网站连接超时	30秒
请求处理超时	60秒
连接空闲超时	300秒

---

9. 配置参数

9.1 电脑A配置

参数	说明	默认值
TARGET_HOST	目标内网网站主机	zentao.sunyard.com.cn
TARGET_PORT	目标内网网站端口	9788
B_HOST	电脑B地址	localhost
B_PORT	电脑B端口	8080

9.2 电脑B配置

参数	说明	默认值
A_PORT	设备A连接端口	8080
BROWSER_PORT	浏览器访问端口	8081