Metadata-Version: 2.4
Name: kite-strings
Version: 0.2.1
Summary: Expose web services on internal servers through a cloud relay with a dashboard and reverse proxy over WebSocket tunnels.
Author: fuqingxu
License-Expression: MIT
Project-URL: Homepage, https://github.com/binary-husky/kite-string
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Dynamic: license-file

# Kite - 反向隧道服务注册系统

将内网服务器上的 Web 服务通过云服务器暴露给外部访问。**Raw TCP 隧道，零 HTTP 解析，完全透明。**

## 架构

```
Browser ──HTTP──► X:10001 ──raw TCP tunnel──► Server-A localhost:3000
Browser ──HTTP──► X:10002 ──raw TCP tunnel──► Server-B localhost:8888

Dashboard:        X:8080
```

每个服务分配独立端口，浏览器直连。不解析、不改写、不编码任何 HTTP 内容。

## 安装

```bash
pip install kite-strings
```

## 使用

### 1. 在云服务器 X 上启动 Server

```bash
kite-server --port 8080 --tunnel-port 8081 --proxy-port-start 10001
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--port` | 8080 | Dashboard 端口 |
| `--tunnel-port` | 8081 | 隧道连接端口（Client 连接用） |
| `--proxy-port-start` | 10001 | 代理端口范围起始 |
| `--proxy-port-end` | 10100 | 代理端口范围结束 |

### 2. 在内网服务器上启动 Client

```bash
kite-client --server ws://X:8080/ws --port 3000 --name "my-api"
```

| 参数 | 必填 | 说明 |
|------|------|------|
| `--server` | 是 | Server 的 WebSocket 地址 |
| `--port` | 是 | 本地 Web 服务端口 |
| `--name` | 否 | 服务显示名称（默认 hostname:port） |
| `--tunnel` | 否 | 隧道地址（默认从 --server 推导） |

### 3. 访问

- **Dashboard**：`http://X:8080` 查看服务列表
- **服务访问**：点击 Dashboard 中的链接（如 `http://X:10001/`）

## 原理

1. Client 通过 WebSocket 注册，Server 分配独立端口
2. Client 维护一组到 Server 的 raw TCP 隧道连接池
3. 浏览器连接分配的端口时，Server 激活一条隧道
4. Client 连接本地服务，双向 pipe raw TCP 字节
5. 完全透明 —— SPA、WebSocket、SSE、gzip 全部正常工作

## 防火墙要求

Server X 需要开放：
- Dashboard 端口（默认 8080）
- Tunnel 端口（默认 8081）
- 代理端口范围（默认 10001-10100）
