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

# Kite - SSH 隧道反向代理

将内网服务器上的 Web 服务通过云服务器暴露给外部访问。**基于 SSH 端口转发，安全可靠。**

## 架构

```
                        SSH -R tunnel
Client (内网)  ◄──────────────────────────►  Server X (云)
  localhost:3000  ──►  X:10001                  ┃
  localhost:8888  ──►  X:10002                  ┃
                                                ┃
Browser ──► X:34321 (Dashboard / Reverse Proxy) ┛
```

流程：
1. Client 调用 `/pre_connect` 提交公钥，Server 验证 API Key 后返回 SSH 连接信息
2. Client 建立 SSH 端口转发隧道（`ssh -R`）
3. Client 定期调用 `/connect`（默认 30s）上报映射信息和心跳
4. 用户在 Dashboard 点击服务条目后获取 Cookie，后续请求自动转发到对应端口

## 安装

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

## 使用

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

设置环境变量：

```bash
export KITE_APIKEY="your-secret-api-key"
export KITE_SSH_IP="x.example.com"
export KITE_SSH_PORT="22"                # 默认 22
export KITE_SSH_USER="kite"
```

启动服务：

```bash
kite-server --port 34321
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--host` | `0.0.0.0` | 监听地址 |
| `--port` | `34321` | Dashboard / 代理端口 |

| 环境变量 | 说明 |
|----------|------|
| `KITE_APIKEY` | 客户端认证用 Bearer Token |
| `KITE_SSH_IP` | 返回给客户端的 SSH 地址 |
| `KITE_SSH_PORT` | SSH 端口（默认 22） |
| `KITE_SSH_USER` | 返回给客户端的 SSH 用户名 |

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

```bash
kite-client --server http://X:34321 \
            --apikey your-secret-api-key \
            --map 3000:my-api \
            --map 8888:jupyter
```

| 参数 | 必填 | 说明 |
|------|------|------|
| `--server` | 是 | Server 的 HTTP 地址 |
| `--apikey` | 是 | API Key（也可用 `KITE_APIKEY` 环境变量） |
| `--map` | 是 | `本地端口:描述`，可重复 |
| `--name` | 否 | 服务显示名称（默认 hostname） |
| `--ttl` | 否 | 存活超时秒数（默认 60） |
| `--heartbeat` | 否 | 心跳间隔秒数（默认 30） |

### 3. 访问

- **Dashboard**：`http://X:34321` 查看服务列表和状态
- **连接服务**：在 Dashboard 点击 "Connect :PORT" 获取代理 Cookie
- **断开代理**：访问 `http://X:34321/_deselect` 清除 Cookie
- **始终查看 Dashboard**：访问 `http://X:34321/_dashboard`

## API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/pre_connect` | POST | 提交公钥，获取 SSH 连接信息（需 Bearer） |
| `/connect` | POST | 上报端口映射和心跳（需 Bearer） |
| `/_api/services` | GET | 获取所有服务状态（JSON） |
| `/_select/{id}/{port}` | GET | 设置代理 Cookie 并跳转 |
| `/_deselect` | GET | 清除代理 Cookie |
| `/_dashboard` | GET | 强制显示 Dashboard |

## 防火墙要求

Server X 需要开放：
- Dashboard 端口（默认 34321）
- SSH 端口（默认 22）
- 映射端口范围（默认从 10001 开始，取决于客户端数量）
