Skip to content
XiechengqiPublic

About

基于 Rust 的高性能 Wayland VNC。WebRTC 丝滑体验,内嵌 MCP Server,Claude 一键接入

Resources

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

iVnc

基于 Rust 的高性能 Wayland 桌面流媒体服务,内置 Smithay 合成器,使用 str0m Sans-I/O WebRTC 库 + GStreamer 实现低延迟流媒体传输。

功能特性

  • Wayland 合成器 - 内置 Smithay headless 合成器,无需外部 X11/Wayland 服务
  • str0m Sans-I/O WebRTC - 基于 str0m 的纯 Rust WebRTC 实现,ICE-lite 模式,TCP 传输
  • 同端口复用 - HTTP、WebSocket 信令、ICE-TCP 共享同一端口
  • 多编码器支持 - H.264, VP8, VP9, AV1
  • 硬件加速 - Intel VA-API, NVIDIA NVENC, Intel Quick Sync Video
  • 输入转发 - 通过 WebRTC DataChannel 支持键盘/鼠标/文本输入(IME)
  • 双向剪贴板 - 浏览器 ↔ 远程应用剪贴板同步,500ms 回声抑制
  • 任务栏 - 窗口列表广播,支持从浏览器切换焦点/关闭窗口;共享应用和远程应用以标签显示
  • 光标同步 - 远程光标样式实时同步到浏览器
  • 音频流媒体 - PulseAudio/PipeWire 捕获 + Opus 编码
  • 文件传输 - 支持上传/下载文件
  • Web UI - 内置 Web 界面,支持 PWA 安装
  • HTTP API - 健康检查和 Prometheus 指标端点
  • 登录认证 - 网页会话保持登录,兼容 HTTP Basic API 认证,见 登录与会话
  • 远程桌面应用 - 按应用开启远程访问,A 启动后以工具栏标签显示,A 中继 B 的画面、输入、声音和上传,多个连接可同时操作
  • 应用工具栏 - 应用多时横向滚动,支持拖动排序并持久化,与控制台应用表同步;窄屏提供紧凑工具和状态,见 工具栏与排序
  • 数据清理 - 内置 Chrome 可按缓存、Cookie、历史、密码、书签、扩展分类选择性清理,默认保留扩展;完全重置才移除完整配置目录,见 选择性数据清理
  • 浏览器代理 - 内置 Chrome 的代理地址在编辑应用中显式配置,默认留空不使用代理,见 内置浏览器代理配置
  • Shell 启动文件 - 应用启动和 Web Terminal 默认自动加载真实 HOME 的 .profile / .bashrc,可用配置关闭,见 Shell 启动文件加载
  • TLS - 支持持久化自签名或指定证书(构建启用 tls,运行加 --tls)

快速开始

# 1. 安装编译依赖(见"从源码编译"章节)
# 2. 编译
bash build.sh --release

# 3. 运行
./ivnc -c config.toml --http-port 8008

浏览器访问 http://<server-ip>:8008/ 即可使用。

从源码编译

编译依赖

apt-get install build-essential pkg-config curl ca-certificates cmake \
  libxcb1-dev libxkbcommon-dev \
  libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
  libpulse-dev libopus-dev \
  libwayland-dev libpixman-1-dev libinput-dev libudev-dev libseat-dev

smithay 和 str0m 通过 Git URL 引用,cargo 构建时自动拉取,无需手动 clone。

编译

使用 build.sh 脚本(推荐):

# Release 构建(默认包含 PulseAudio 音频)
bash build.sh --release

# Debug 构建
bash build.sh --debug

# 追加额外 feature(如 TLS)
bash build.sh --release --features tls

构建完成后二进制文件位于项目根目录:./ivnc

也可以直接使用 cargo:

bash scripts/build-miao.sh --release
IVNC_MIAO_BIN="$PWD/target/release/miao-rust" cargo build --release
# 输出:target/release/ivnc

GitHub Actions 保留构建发布与容器构建检查。UI 和浏览器回归在本地执行,见 持续集成与本地验证。

Cargo Features

Feature 说明 默认
pulseaudio PulseAudio 音频捕获 + Opus 编码 ✅
audio cpal 音频捕获 + Opus 编码
tls 自签名 HTTPS(--tls 启用,PWA 支持)
vaapi Intel VA-API 硬件编码
nvenc NVIDIA NVENC 硬件编码
qsv Intel Quick Sync Video

部署

运行时依赖

从预编译二进制直接运行时,需要安装以下运行时库:

apt-get install \
  openssh-client \
  libgstreamer1.0-0 libgstreamer-plugins-base1.0-0 \
  libpixman-1-0 libxkbcommon0 \
  gstreamer1.0-tools gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly gstreamer1.0-x \
  libpulse0 libopus0 pulseaudio pulseaudio-utils

libglib-2.0、libgobject-2.0 等由 GStreamer 自动依赖,无需单独安装。

音频配置

音频捕获需要 PulseAudio。推荐使用原生 PulseAudio(PipeWire-Pulse 的 null-sink 在无音频播放时处于 SUSPENDED 状态,会导致捕获超时)。

启动 PulseAudio 并配置虚拟音频设备(无物理声卡的服务器环境必需):

export XDG_RUNTIME_DIR=/run/user/$(id -u)
mkdir -p "$XDG_RUNTIME_DIR"

# 启动 PulseAudio(--exit-idle-time=-1 防止空闲退出)
pulseaudio --start --exit-idle-time=-1

# 加载虚拟 sink(远程应用的音频输出目标)
pactl load-module module-null-sink sink_name=ivnc_sink \
  sink_properties=device.description=iVnc_Output \
  rate=48000 channels=2 format=s16le

iVnc 会自动检测默认 sink 的 monitor source(ivnc_sink.monitor)来捕获桌面音频输出。也可通过 PULSE_SOURCE 环境变量指定音频源。

注意:PipeWire-Pulse 的 module-null-sink 在 SUSPENDED 状态下不产生数据,PulseAudio Simple API 连接会超时。如果必须使用 PipeWire,需要确保有真实音频设备或始终有客户端连接到 sink。

硬件加速(可选)

# Intel VA-API
apt-get install gstreamer1.0-vaapi libva-dev

# NVIDIA NVENC(需要 NVIDIA 驱动)
apt-get install gstreamer1.0-plugins-bad

# Intel Quick Sync Video
apt-get install intel-media-va-driver-non-free

Docker 部署

正式 Docker 镜像使用 Ubuntu 24.04 LTS 运行时。默认从 GHCR 启动:

./docker-run.sh

# 覆盖默认端口、容器名或镜像
PORT=9000 NAME=ivnc-noble IMAGE=ghcr.io/xiechengqi/ivnc:noble ./docker-run.sh

# 指定 VPS,Miao 部署/恢复节点并启用全局代理
./docker-run.sh --proxy-ip 203.0.113.10

脚本将仓库下的 ivnc-data 和 miao-data 分别挂载到 /root/.ivnc 和 /root/.miao,并为 miao 全局和进程代理模式提供 /dev/net/tun 与 NET_ADMIN。 容器默认使用 --restart unless-stopped。宿主机必须已安装 Docker 且提供 TUN 设备。

也可直接在镜像名后传入 iVnc 参数:

docker run -d --name ivnc --restart unless-stopped \
  -p 8008:8008 --cap-add NET_ADMIN --device /dev/net/tun \
  -v "$PWD/ivnc-data:/root/.ivnc" -v "$PWD/miao-data:/root/.miao" \
  ghcr.io/xiechengqi/ivnc:latest --proxy-ip 203.0.113.10

--proxy-ip 接受 IPv4/IPv6,使 Miao 以 --nopasswd --mode global --vps-host <IP> 启动,默认使用运行账户的 SSH 密钥或 agent。Docker 若需使用密钥,可将专用 SSH 目录挂载到 /root/.ssh;需可写以保存 known_hosts。详细行为见 Miao 后台应用。

可用镜像标签包括滚动更新的 latest、固定 Ubuntu 24.04 运行时的 noble,以及 不可变的 sha-<提交短哈希>。需要回滚时,将 IMAGE 指向此前的提交标签或镜像摘要。

正式 Docker 镜像和独立发布二进制保留默认 PulseAudio feature 并启用 tls feature; 音频仍需在配置中启用,HTTPS 运行时使用 --tls。

配置

命令行参数

# 使用默认配置(/etc/ivnc.toml,不存在则使用内置默认值)
./ivnc

# 指定配置文件
./ivnc -c config.toml

# 覆盖端口和分辨率
./ivnc -c config.toml --http-port 8008 --width 1920 --height 1080

# 指定 Miao 使用的 VPS 并启动全局代理
./ivnc --proxy-ip 203.0.113.10

# 启用自签名 HTTPS(需要 tls feature 编译)
./ivnc -c config.toml --tls

# 调试模式
./ivnc -c config.toml --verbose

音频捕获需要 XDG_RUNTIME_DIR 环境变量指向 PulseAudio socket 所在目录:

XDG_RUNTIME_DIR=/run/user/$(id -u) ./ivnc -c config.toml --http-port 8008
参数 默认值 说明
-c, --config /etc/ivnc.toml 配置文件路径
--width 1920 显示宽度
--height 1080 显示高度
--http-port 配置文件值 HTTP 端口(同时用于 ICE-TCP)
--proxy-ip <IP> 未指定 Miao 部署/恢复指定 VPS,并以全局模式启动;接受 IPv4/IPv6
--proxy-autostart <true/false> 兼容旧版偏好,首次默认开启 控制本次 Miao 自启动;关闭后仍可手动启动
--proxy-enabled <true/false> 配置文件值 Miao 总开关,关闭后禁止自启动和手动启动
--tls 启用自签名 HTTPS
--basic-auth-enabled true 启用网页登录与 Basic API 认证
--basic-auth-user 认证用户名
--basic-auth-password 认证密码
-v, --verbose 详细日志
--foreground 前台运行

完整参数列表:./ivnc --help

配置文件

复制示例配置:

cp config.example.toml config.toml

主要配置段:

[display]
width = 1920
height = 1080
refresh_rate = 60

[http]
host = "0.0.0.0"
port = 8008
basic_auth_enabled = true
basic_auth_user = "user"
basic_auth_password = "mypasswd"

[encoding]
target_fps = 30
max_fps = 60

[audio]
enabled = true
sample_rate = 48000
channels = 2
bitrate = 128000

[webrtc]
enabled = true
tcp_only = true
video_codec = "h264"
video_bitrate = 8000
video_bitrate_max = 16000
video_bitrate_min = 1000
hardware_encoder = "auto"
keyframe_interval = 60
candidate_from_host_header = true
# public_candidate = "1.2.3.4:8008"

完整配置示例见 config.example.toml。

环境变量

环境变量 说明
IVNC_HOME 持久化数据根目录(默认 $HOME/.ivnc)
XDG_RUNTIME_DIR PulseAudio/PipeWire socket 目录(音频捕获必需;不迁入 IVNC_HOME)
PULSE_SOURCE 指定 PulseAudio 音频源(默认自动检测 monitor source)
IVNC_ENCODER 编码器选项(逗号分隔)
IVNC_FRAMERATE 帧率或帧率范围(如 30 或 15-60)
IVNC_AUDIO_ENABLED 启用音频 (true/false)
IVNC_AUDIO_BITRATE 音频比特率或范围
IVNC_MOUSE_ENABLED 启用鼠标
IVNC_KEYBOARD_ENABLED 启用键盘
IVNC_CLIPBOARD_ENABLED 启用剪贴板
IVNC_MANUAL_WIDTH 手动分辨率宽度
IVNC_MANUAL_HEIGHT 手动分辨率高度
IVNC_UI_SHOW_SIDEBAR 显示侧边栏

UI 相关环境变量值后加 |locked 可锁定前端不可修改。

数据目录

iVnc 持久化数据默认位于 $HOME/.ivnc(可用 IVNC_HOME 覆盖):

$IVNC_HOME/
  apps.db / console.json / app_running_state.json
  remote.db / remote.key
  capability_calls.jsonl / ivnc.pid / Desktop/
  applications/   # .desktop 入口
  miao/           # 内置 miao 二进制与 miao.log
  apps/<id>/      # 日志、应用 HOME、data、chrome profile、worker-state
  runtimes/<id>/  # 共享应用运行环境的内部代次与端点
  tls/            # 持久化 TLS 证书与私钥

miao 自身的配置、订阅缓存和运行状态遵循 miao 的目录约定,位于 $HOME/.miao。Docker 部署应同时持久化 /root/.ivnc 与 /root/.miao。

Chrome 首次注册默认关闭自启动。在“编辑应用”中保存的“开机启动”选择会保留,iVnc 或容器重启、内置启动命令更新及旧版应用迁移均不会重置它。自启动随 iVnc 服务启动执行。

Miao 以内置后台应用显示在控制台应用列表,首次默认随 iVnc 启动,升级时保留旧版自启动偏好。可直接启动、停止、重启、查看日志并打开代理配置,默认以 --nopasswd 免密码进入 Miao 面板。“编辑应用”展示完整只读配置,启动参数通过 iVnc CLI 控制。VPS 部署依赖 OpenSSH 客户端,Docker 镜像已包含。详细行为、配套版本和构建方式见 Miao 后台应用。

首次启动会尝试从旧路径(~/.config/ivnc、/tmp/ivnc-apps 等)自动迁移。

Electron 桌面应用

支持新版 Electron 的原生 Wayland 后端,可在添加桌面应用时使用 Electron Wayland 启动模板。窗口、中文输入、剪贴板及桌面服务的配置与边界见 Electron 支持。

远程应用

在 B 上“编辑”桌面应用,在“远程访问”中打开开关、设置访问密码并复制连接地址;在 A 添加“远程应用”并启动,即可连接 B 上已运行的进程,它以标签形式出现在 A 桌面的工具栏中。浏览器只连接 A;停止或删除 A 中的远程应用不会停止 B 的应用。B 关闭共享或修改密码会立即断开所有远程会话。所有连接都可以操作应用。

未开启远程访问的桌面应用是主桌面的 Wayland 窗口;开启远程访问的应用在独立运行环境(自带合成器和私有 PulseAudio)中运行,重启后切换。两种方式下应用的文件、网络和环境与本机运行相同,没有沙箱隔离,只支持 Wayland 应用。使用步骤、证书、升级和验证范围见 远程桌面应用。

不同分辨率客户端

桌面保持服务器设定的尺寸;连接、刷新、浏览器缩放、DPR、旋转、全屏和工具栏固定都不会改变其他客户端或应用窗口。底部工具栏提供“适应窗口 / 原始大小”切换:前者完整等比居中显示,后者按视频原始像素显示并允许滚动。共享和远程应用使用相同的本地适配规则。

需要改变实际桌面时,在“设置 → 连接质量 → 桌面分辨率”选择主桌面或正在运行的本地共享应用,再应用宽高。此操作影响该桌面的所有连接,成功后保存,服务重启恢复。普通共享链接没有此管理权限;远程应用的尺寸由来源实例管理。修改密码、退出登录与重启或升级集中在设置顶部右侧,见 设置。

启动优先级为 [display].locked = true 的配置尺寸、旧版 IVNC_MANUAL_* 锁定环境设置、控制台保存尺寸、[display] 默认尺寸。允许偶数宽高,宽 320–7680、高 200–4320,总像素不超过 3840×2160。旧客户端的自动分辨率请求不再调整桌面,刷新即可获得新的适配入口。

目前仍共用一路编码视频:较低解码能力的客户端可能降低共同视频尺寸、帧率或码率,但不会改变桌面和应用布局。详见 显示适配与回归说明。

API 参考

Web 界面

内置前端通过 HTTP 端口提供:

http://localhost:8008/

WebRTC 信令通过 WebSocket(同端口):

ws://localhost:8008/webrtc

ICE-TCP 连接也复用同一端口,通过首字节分类自动区分。

HTTP 端点

端点 说明
GET / Web 界面
GET /health 健康检查(JSON)
GET /metrics Prometheus 指标
GET /clients 活跃连接列表
GET /ui-config UI 配置
GET /ws-config WebSocket 端口配置
GET /webrtc WebRTC 信令 WebSocket

DataChannel 协议

输入事件和控制消息通过 WebRTC DataChannel 传输。

客户端 → 服务端:

格式 说明
m,{x},{y},{buttonMask},{0} 鼠标移动(buttonMask 变化时合成按键事件)
b,{button},{pressed} 鼠标按键
w,{dx},{dy} 鼠标滚轮
k,{keysym},{pressed} 键盘事件(X11 KeySym)
t,{text} 兼容 IME 文本输入(优先 zwp_text_input_v3)
ti,{json} 带目标窗口与回执的 IME 提交/取消(协商 commit:1 后使用,见 中文输入)
cw,{base64} 剪贴板内容
_display,1 请求权威桌面/视频尺寸及几何版本
_viewport,{json} 当前客户端工作区报告,不调整桌面
i,{revision},{pointer_message} 使用桌面坐标的指针消息,拒绝过期版本
r,{width}x{height} 旧客户端提示,服务端忽略尺寸修改
focus,{id} 切换窗口焦点
close,{id} 关闭窗口
kr 键盘重置(释放所有修饰键)
pong 心跳响应

服务端 → 客户端:

格式 说明
cursor,{json} 光标样式变化
clipboard,{base64} 剪贴板内容
taskbar,{json} 窗口列表与应用标签更新
display,{json} 权威桌面尺寸、视频尺寸及几何版本
stats,{json} 性能统计(每秒)
ping 心跳请求

完整协议规范见 docs/PROTOCOL.md。

技术架构

流媒体管道

视频流 (Server → Browser):
┌──────────────┐    ┌─────────────────────────────────────────────┐    ┌──────────────┐
│   Smithay    │    │              GStreamer Pipeline              │    │    str0m      │
│  Compositor  │───▶│ appsrc → videoconvert → encoder → rtppay    │───▶│  write_rtp()  │
│  (headless)  │    │                         H.264/VP8/VP9/AV1   │    │  Sans-I/O     │
└──────────────┘    └─────────────────────────────────────────────┘    └──────┬───────┘
   RGBA 帧                                                                    │
                                                                    SRTP 加密 │ NullPacer
                                                                              ▼
                    ┌─────────────┐    ┌──────────────────┐    ┌──────────────────┐
                    │   Browser   │◀───│  RFC 4571 TCP    │◀───│  poll_output()   │
                    │  (WebRTC)   │    │  帧封装 (同端口)  │    │  drain_outputs() │
                    └─────────────┘    └──────────────────┘    └──────────────────┘

音频流 (Server → Browser):
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
│  PulseAudio  │───▶│    Opus      │───▶│    str0m     │───▶│  SRTP → TCP 帧   │───▶ Browser
│  /PipeWire   │    │   Encoder    │    │  write_rtp() │    │  (RFC 4571)      │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────────┘

输入流 (Browser → Server):
┌──────────────┐    ┌──────────────────┐    ┌──────────────┐    ┌──────────────┐
│   Browser    │───▶│  RTCDataChannel  │───▶│    str0m     │───▶│   Smithay    │
│  键盘/鼠标   │    │  SCTP/DTLS/TCP   │    │  ChannelData │    │  Seat 注入   │
└──────────────┘    └──────────────────┘    └──────────────┘    └──────────────┘

WebRTC 传输层

iVnc 使用 str0m Sans-I/O WebRTC 库,所有 I/O 由调用方驱动:

  • ICE-lite 模式 - 服务端仅提供 TCP passive candidate,不主动探测
  • RTP 模式 - GStreamer 产出的 RTP 包通过 write_rtp() 直接传入 str0m,str0m 负责 SRTP 加密、SSRC 分配、RTP header extension 注入
  • NullPacer - BWE 默认关闭,使用 NullPacer,每次 handle_timeout() → poll_output() 循环发射一个包
  • 同端口复用 - 通过首字节分类区分 HTTP 请求和 ICE-TCP 数据包

双向剪贴板同步

浏览器 → 远程应用:

  • DataChannel cw,{base64} → set_data_device_selection() → Wayland 客户端读取
  • 500ms clipboard_suppress_until 窗口防止回声循环(Wayland 客户端重新断言 wl_data_source)

远程应用 → 浏览器:

  • Wayland 客户端复制 → new_selection() 保存 mime type(延迟模式)
  • 主循环 event_loop.dispatch() 后调用 request_data_device_client_selection() + flush_clients()
  • 非阻塞 pipe 读取 → base64 编码 → DataChannel clipboard,{base64} 广播

延迟读取原因:smithay 在 new_selection() 返回后才更新 seat_data.clipboard_selection,回调内直接读取会失败。

任务栏窗口管理

  • window_registry 维护窗口列表(稳定顺序)
  • 窗口创建/销毁时通过 DataChannel 广播 taskbar,{json}(包含 id, title, app_id, display_name, focused)
  • 浏览器可发送 focus,{id} / close,{id} 控制窗口
  • display_name 从 .desktop 文件解析
  • 新 DataChannel 打开时(datachannel_open_count 变化)自动重发窗口列表
  • 共享应用和已启动的远程应用通过 apps 字段下发,前端以标签显示,选中时用内嵌应用视图覆盖主画面

模块结构

模块 功能
compositor/ Smithay Wayland 合成器(headless backend)
gstreamer/ GStreamer 管道、编码器选择、RTP 打包
webrtc/rtc_session.rs str0m Sans-I/O 会话驱动(事件循环、RTP 转发、DataChannel)
webrtc/session.rs 会话管理、ICE-TCP 连接匹配
webrtc/tcp_framing.rs RFC 4571 TCP 帧编解码
transport/ WebRTC 信令服务器(WebSocket)
input.rs 键盘/鼠标事件处理
audio/ PulseAudio/PipeWire 捕获和 Opus 编码
web/ Axum HTTP 服务器、同端口复用、嵌入式前端资源
config/ TOML 配置管理、UI 配置
clipboard.rs 剪贴板同步
file_upload.rs 文件上传处理
apps/ 应用管理(SQLite 注册表、进程管理、桌面项)
capabilities/ CLI 应用能力发现与调用(权限、审计日志)

故障排除

GStreamer 编码器未找到

gst-inspect-1.0 | grep -E "(x264|openh264|vp8|vaapi|nvenc|qsv)"
apt-get install gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

WebRTC 连接失败

  1. 确认浏览器能访问 HTTP 端口
  2. 检查浏览器控制台是否有 ICE/DTLS 错误
  3. 如果通过反向代理,确保 WebSocket 和 TCP 连接能正确转发

浏览器已连接但画面黑屏

H.264 使用 8-bit 4:2:0 Constrained Baseline,实际分辨率、帧率与码率按当前接收能力调整。浏览器阻止播放时点击“播放画面”;无数据、解码或连接失败会显示对应提示及重试入口。排查协商参数、Safari 验证范围及公共流适配策略见 视频兼容与 Review。

Safari 应用 tab 点击无反应

应用 tab 的原生点击现已与拖拽清理分离,后台排序或改名也会保留正在点击的目标。修复根因、跨浏览器回归和实机验证范围见 Safari toolbar 修复与 Review。

无音频

  1. 确认 PulseAudio 正在运行:pactl info
  2. 确认虚拟 sink 已加载:pactl list sinks short(应看到 ivnc_sink)
  3. 确认 XDG_RUNTIME_DIR 环境变量已设置
  4. 确认配置文件中 [audio] enabled = true
  5. 检查日志中是否有 PulseAudio capture opened 消息
  6. 如果日志显示 PulseAudio connect failed: Timeout,说明 PulseAudio 环境异常(PipeWire-Pulse 的 null-sink 不支持,需换用原生 PulseAudio)
  7. 浏览器自动播放策略要求用户交互(点击/按键)后才能播放音频

高延迟或卡顿

[webrtc]
video_bitrate = 4000
keyframe_interval = 30

[display]
width = 1280
height = 720

许可证

详见 LICENSE 文件。

About

基于 Rust 的高性能 Wayland VNC。WebRTC 丝滑体验,内嵌 MCP Server,Claude 一键接入

Resources

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages