基于 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-devsmithay 和 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/ivncGitHub Actions 保留构建发布与容器构建检查。UI 和浏览器回归在本地执行,见 持续集成与本地验证。
| 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=s16leiVnc 会自动检测默认 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 镜像使用 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 并启用
tlsfeature; 音频仍需在配置中启用,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 的原生 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。旧客户端的自动分辨率请求不再调整桌面,刷新即可获得新的适配入口。
目前仍共用一路编码视频:较低解码能力的客户端可能降低共同视频尺寸、帧率或码率,但不会改变桌面和应用布局。详见 显示适配与回归说明。
内置前端通过 HTTP 端口提供:
http://localhost:8008/
WebRTC 信令通过 WebSocket(同端口):
ws://localhost:8008/webrtc
ICE-TCP 连接也复用同一端口,通过首字节分类自动区分。
| 端点 | 说明 |
|---|---|
GET / |
Web 界面 |
GET /health |
健康检查(JSON) |
GET /metrics |
Prometheus 指标 |
GET /clients |
活跃连接列表 |
GET /ui-config |
UI 配置 |
GET /ws-config |
WebSocket 端口配置 |
GET /webrtc |
WebRTC 信令 WebSocket |
输入事件和控制消息通过 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 注入 │
└──────────────┘ └──────────────────┘ └──────────────┘ └──────────────┘
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 应用能力发现与调用(权限、审计日志) |
gst-inspect-1.0 | grep -E "(x264|openh264|vp8|vaapi|nvenc|qsv)"
apt-get install gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly- 确认浏览器能访问 HTTP 端口
- 检查浏览器控制台是否有 ICE/DTLS 错误
- 如果通过反向代理,确保 WebSocket 和 TCP 连接能正确转发
H.264 使用 8-bit 4:2:0 Constrained Baseline,实际分辨率、帧率与码率按当前接收能力调整。浏览器阻止播放时点击“播放画面”;无数据、解码或连接失败会显示对应提示及重试入口。排查协商参数、Safari 验证范围及公共流适配策略见 视频兼容与 Review。
应用 tab 的原生点击现已与拖拽清理分离,后台排序或改名也会保留正在点击的目标。修复根因、跨浏览器回归和实机验证范围见 Safari toolbar 修复与 Review。
- 确认 PulseAudio 正在运行:
pactl info - 确认虚拟 sink 已加载:
pactl list sinks short(应看到ivnc_sink) - 确认
XDG_RUNTIME_DIR环境变量已设置 - 确认配置文件中
[audio] enabled = true - 检查日志中是否有
PulseAudio capture opened消息 - 如果日志显示
PulseAudio connect failed: Timeout,说明 PulseAudio 环境异常(PipeWire-Pulse 的 null-sink 不支持,需换用原生 PulseAudio) - 浏览器自动播放策略要求用户交互(点击/按键)后才能播放音频
[webrtc]
video_bitrate = 4000
keyframe_interval = 30
[display]
width = 1280
height = 720详见 LICENSE 文件。