Metadata-Version: 2.4
Name: aliyun-ecs-vnc
Version: 0.0.1
Summary: A local relay that bridges Alibaba Cloud ECS VNC (RFB over WebSocket) to any VNC client over plain TCP
Author-email: Moha-Master <hongkongreporter@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Moha-Master/Aliyun-ECS-VNC
Project-URL: Repository, https://github.com/Moha-Master/Aliyun-ECS-VNC
Project-URL: Issues, https://github.com/Moha-Master/Aliyun-ECS-VNC/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: alibabacloud-ecs20140526
Requires-Dist: alibabacloud-tea-openapi
Requires-Dist: alibabacloud-tea-util
Requires-Dist: websocket-client
Requires-Dist: PyYAML
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# 阿里云 ECS VNC 中继

这个项目提供了一个本地中继服务，将阿里云 ECS 的 VNC 远程连接（RFB over WebSocket）桥接到普通的 TCP 端口，使任何支持标准 VNC 协议的客户端（RealVNC、TigerVNC、macOS 屏幕共享、Android bVNC 等）都能免公网连接 ECS 实例。

```
VNC 客户端 ──TCP 127.0.0.1:5900──> [本中继] ──wss://(binary)──> 阿里云 vncproxy
```

## 特性

- 免公网 IP、不占用公网带宽连接 ECS 实例
- 兼容任意标准 VNC 客户端
- 支持同时中继多个实例，每个实例一个本地端口
- 每次客户端接入自动获取新的 VncUrl（token 15 秒过期，自动刷新）
- 可选的 WebSocket ping 保持连接
- `--list-instances` 快速查看账号下的实例

## 安装

1. 克隆仓库：
   ```bash
   git clone https://github.com/Moha-Master/Aliyun-ECS-VNC.git
   cd Aliyun-ECS-VNC
   ```

2. 安装：
```bash
pip install -e .
```

安装后可以直接使用命令：

```bash
aliun-ecs-vnc --dir /path/to/config
```

参数说明：
- `--dir`: 工作目录，从中读取 config.yaml（默认：~/.config/aliyun-ecs-vnc/）
- `--host`: 绑定的主机地址（默认：来自 config.yaml）
- `--list-instances`: 列出账号下的 ECS 实例后退出
- `--verbose`: 输出调试日志

## 配置

在希望的工作目录中创建一个基于 `config.yaml.example` 的 `config.yaml` 文件。服务会从 `~/.config/aliyun-ecs-vnc/` 或设置的 `--dir` 中读取 `config.yaml`。

如果指定的目录中没有 `config.yaml` 文件，程序会自动从包内的 `config.yaml.example` 复制一份到该目录并提示您编辑，编辑完成后重新运行即可。

配置选项：
- `alibaba_cloud.access_key_id`: 您的阿里云 AccessKey ID
- `alibaba_cloud.access_key_secret`: 您的阿里云 AccessKey Secret
- `alibaba_cloud.region_id`: 实例所在的地域（如 cn-hangzhou）
- `listen.host`: 本地监听地址（所有实例共用，默认 127.0.0.1）
- `instances`: 实例列表，每项包含
  - `name`: 可选，日志中用于标识该实例
  - `instance_id`: ECS 实例 ID
  - `port`: 该实例对应的本地监听端口
- `behavior.auto_refresh`: 每次客户端接入自动获取新 VncUrl（默认 true）
- `behavior.rfb_keepalive`: RFB 空闲保活，周期性发送 FramebufferUpdateRequest（默认 true）
- `behavior.rfb_keepalive_interval`: 增量更新请求间隔秒数（默认 15）
- `behavior.rfb_full_refresh_interval`: 上游长时间无回包时强制全屏刷新以产生回包（秒，0=关闭，默认 45）

## 连接保持（为什么需要 RFB 保活）

阿里云官方文档描述的"300 秒 KeepAlive"是服务端真实的闲置断开限制：300 秒内无任何 RFB
交互操作，服务端会主动关闭连接。官方控制台页面闲置时也不发送任何周期性数据，
因此闲置 300 秒后会断开（页面显示连接断开提示）。

本中继在 RFB 握手完成后，会周期性注入标准的 `FramebufferUpdateRequest`
（增量刷屏请求，普通 VNC 客户端本就会发送，无副作用）。这属于真实 RFB 数据，
能重置服务端的 300 秒闲置计时器，使闲置连接可以长期保持；同时兜底定时强制全屏刷新，
保证即使画面静止服务端也会回包。这些消息与您的 VNC 客户端自身的请求完全兼容，
不会干扰正常使用。

## 前提条件

- RAM 用户需拥有 `ecs:DescribeInstances` 和 `ecs:DescribeInstanceVncUrl` 权限
- 实例需处于「运行中」或「停止中」状态
- 同一实例同一时间只允许一个 VNC 会话

## 使用示例

启动中继后，用任意 VNC 客户端连接对应的本地端口即可。连接后使用实例的登录账号密码（root / Administrator）登录系统。
