Metadata-Version: 2.4
Name: kite-strings
Version: 0.1.3
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 服务通过云服务器暴露给外部访问。

## 适用场景

```
┌─────────┐   WebSocket    ┌─────────────┐   HTTP    ┌─────────┐
│ 内网服务器├──────────────►│  云服务器 X   │◄─────────│  浏览器  │
│ A/B/C   │               │  kite-server │           └─────────┘
│(kite-client)             │  Dashboard   │
└─────────┘               │  + 反向代理   │
                          └─────────────┘
```

- 内网服务器 A/B/C 无法从外部直接访问
- A/B/C 可以主动连接云服务器 X，反之不行
- 需要通过 X 访问 A/B/C 上的 Web 服务

## 安装

Python 3.8+，唯一依赖 `aiohttp`：

```bash
pip install aiohttp
```

## 使用

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

```bash
python kite_server.py --port 8080
```

可选参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--host` | `0.0.0.0` | 监听地址 |
| `--port` | `8080` | 监听端口 |

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

假设 A 上有一个运行在 3000 端口的 Web 服务：

```bash
python kite_client.py --server ws://X:8080/ws --port 3000 --name "my-api"
```

可选参数：

| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `--server` | 是 | - | Server 的 WebSocket 地址 |
| `--port` | 是 | - | 本地 Web 服务端口 |
| `--name` | 否 | `主机名:端口` | 服务显示名称 |

### 3. 访问

- **Dashboard**：浏览器打开 `http://X:8080`，查看所有已注册服务
- **代理访问**：点击服务名称，或直接访问 `http://X:8080/proxy/{service_id}/`

## 工作原理

1. Client 通过 WebSocket 连接 Server，注册本地服务信息
2. Server 记录服务并在 Dashboard 展示
3. 浏览器访问代理路径时，Server 将 HTTP 请求通过 WebSocket 转发给 Client
4. Client 向本地服务发起请求，将响应原路返回
5. Client 断线后自动重连（指数退避，1s → 30s）

## 示例

在同一台机器上快速体验：

```bash
# 终端 1：启动 Server
python kite_server.py --port 34321

# 终端 2：启动一个测试 Web 服务
python -m http.server 9000

# 终端 3：启动 Client，将 9000 端口暴露到 Server
python kite_client.py --server ws://localhost:8080/ws --port 9000 --name "file-server"

# 浏览器打开 http://localhost:8080 查看 Dashboard，点击服务即可访问
```

## 多服务注册

每个 Web 服务启动一个 Client 实例即可：

```bash
# Server A
python kite_client.py --server ws://X:8080/ws --port 3000 --name "api-server"
python kite_client.py --server ws://X:8080/ws --port 8888 --name "jupyter"

# Server B
python kite_client.py --server ws://X:8080/ws --port 5000 --name "flask-app"
```
