Skip to content

user-guide.md

Latest commit

 

History

History
188 lines (119 loc) · 11.9 KB

user-guide.md

File metadata and controls

188 lines (119 loc) · 11.9 KB
Raw

用户指南：Mac 主端与 Windows 子端

1. 使用前确认

请先确认以下条件：

  • 主端为 macOS 14 或更高版本，子端为 Windows 10/11 64 位。
  • 两台设备在同一个由你管理的可信 IPv4 局域网，最好是同一 VLAN/子网。
  • Windows 子端可发出 UDP 47771 广播、接收入站 TCP 47772 信令，并允许 LanExtend 在专用网络协商 WebRTC 动态 UDP；Mac 能接收入站发现报文。
  • 网络未开启 AP/客户端隔离，且没有把相关端口映射到公网。
  • 你接受当前 MVP 没有认证：同网攻击者可能伪装设备或干扰信令。

建议第一次验收使用有线网络，或让两台设备连接信号良好的 5/6 GHz Wi‑Fi。先用 1920×1080、30 FPS、8 Mbps、关闭 HiDPI，链路稳定后再提高参数。

2. 获取和安装

GitHub Releases 与 CI 构建产物

面向用户发布的安装包位于项目的 GitHub Releases：

  • Mac：Universal DMG 和 ZIP；目前未配置 Developer ID 正式签名与 Apple 公证；
  • Windows：portable EXE 和 ZIP；目前未配置 Authenticode 签名；
  • 发布页同时提供 SHA-256 校验文件；下载后应先核对哈希和版本说明。

仓库的 Build desktop artifacts GitHub Actions 会分别生成 Mac 和 Windows artifacts。它们是开发/验收产物：

  • Mac：DMG 和 ZIP；未配置 Developer ID 正式签名与 Apple 公证；
  • Windows：portable EXE 和 ZIP；未配置 Authenticode 签名；
  • artifacts 只保留有限时间，不等同于维护者发布的 Release。

只从你信任的仓库运行记录下载，并核对工作流对应的提交。正式分发要求见发布说明。

应用启动后会向 GitHub 的公开 Release API 检查一次稳定版本，也可点击侧边栏底部的更新卡片手动复查。发现新版本时，卡片会打开本项目固定的 GitHub Releases 页面；LanExtend 不会后台下载、不会静默安装，也不会绕过系统安全提示。升级前先断开会话，并让主端与子端安装相同版本。

从源码运行

两端都需要 Node.js 22+ 和 npm 10+。Mac 还需要 Xcode Command Line Tools 和 macOS SDK。

Mac：

npm ci
npm run build:native
npm run dev:host

Windows PowerShell：

npm ci
npm run dev:receiver

平台会自动选择正常角色；--role=host 和 --role=receiver 主要用于开发。Windows 不能创建 macOS 虚拟显示器。

3. 配置 Windows 子端

  1. 先启动 LanExtend 子端。
  2. 设置便于辨认且不包含敏感信息的设备名称。
  3. 保持默认信令端口 47772，除非端口冲突或网络策略要求修改。
  4. 根据需要开启“连接后自动全屏”。
  5. 若 Windows Defender 防火墙提示，选择允许访问“专用网络”，不要为“公用网络”放行。固定方向是 Windows 出站 UDP 47771 广播、Windows 入站 TCP 信令；WebRTC 还会使用动态 UDP，因此优先按 LanExtend 应用放行，而不是只开两个固定端口。
  6. 确认 GUI 显示正在监听，然后再启动 Mac 主端。

子端会每 1.5 秒发送 UDP 广播。它只接受一个活动主端；已被占用时，第二台 Mac 会收到“子端当前正在使用”或连接关闭。

4. 配置 macOS 权限

屏幕录制

主端必须能够捕获虚拟显示器。把 LanExtend 安装到“应用程序”目录，并且只从该位置启动。打开“系统设置 → 隐私与安全性 → 屏幕录制”（在部分版本中显示为“屏幕与系统音频录制”），启用 LanExtend；返回应用后会自动重新检测。不要交替启动下载目录、DMG、源码或 release/ 中的同名副本，否则 macOS 可能把它们当成不同的权限主体。

授权只用于视频画面；LanExtend MVP 不采集或发送音频。

本地网络

若系统询问是否允许访问本地网络，请允许。拒绝后自动发现和连接可能失败。可以在“系统设置 → 隐私与安全性 → 本地网络”中复查。

辅助功能

只有键鼠共享需要辅助功能权限。首次点击“启动键鼠共享”时允许 LanExtend，然后返回应用重试。该模式不需要屏幕录制权限。应用不需要麦克风、摄像头、管理员权限、内核扩展，也不应要求关闭 SIP。

5. 配置扩展方式与画面参数

正常使用时保持默认来源模式“创建扩展屏”，只需设置逻辑分辨率、帧率、码率和 HiDPI。这是连接流程选项，不是独立创建按钮：虚拟屏会在你选中子端并点击“扩展到 …”、收到该子端真实 UUID 后自动创建；应用随后自动定位并捕获它。

“已有显示器”是兼容模式：只有私有虚拟显示不可用，或你明确需要发送现有屏幕时才选择它。兼容模式下刷新并手选捕获源；所选物理屏的全部可见内容都可能被发送。

参数含义

参数 允许范围 首次建议 注意
逻辑宽 800–7680，偶数；HiDPI 时不超过 3840 1920 越高越耗 WindowServer、捕获和编码资源
逻辑高 600–4320，偶数；HiDPI 时不超过 3840 1080 与 Windows 窗口比例一致更自然
帧率 15–60 30 60 FPS 需双端和网络实测
码率 2–80 Mbps 8 Mbps 是 WebRTC 编码目标，不是硬保证
HiDPI 开/关 关 输入仍是逻辑尺寸，物理帧缓冲宽高各 2×；1920×1080 会创建 3840×2160 framebuffer

HiDPI 使同一逻辑尺寸的物理像素数变为四倍。发送端会尝试把捕获轨道约束/缩放到所选逻辑尺寸，但实际编码尺寸以连接后的运行统计为准，不应仅根据设置值断言。

兼容模式下不要仅凭屏幕名称猜测捕获源。可以先清空敏感内容并使用测试画面，再确认 Windows 端看到正确屏幕；选错源可能把主屏内容发送到子端。

6. 发现并连接子端

自动发现

在线 Windows 子端会出现在主端设备列表。离线判定约需 6 秒，网络切换后可手动刷新。

选中正确设备后由 Mac 主端点击“扩展到 …”。实际流程是：

  1. 主端打开到子端的 WebSocket。
  2. 子端用 welcome 返回真实持久 UUID；主端据此合并记忆设备，手动地址的临时 ID 会被替换。
  3. 主端发送 hello；默认模式自动创建虚拟显示器、轮询并匹配其捕获源。兼容模式则使用你预先选择的已有显示器。
  4. 主端创建 WebRTC offer，双端交换 answer/ICE 并发送单路视频。
  5. 连接成功后再打开“系统设置 → 显示器 → 排列”，把新增屏拖到和 Windows 实际摆放一致的位置。

手动连接

如果两台设备可以互通但网络禁止广播，在 Windows 运行 ipconfig 查看活动网卡的 IPv4 地址，在主端输入该私有 IPv4 和子端端口。MVP 只接受私有/回环/链路本地 IPv4，不接受主机名、IPv6 或公网地址。

跨 VLAN 手动连接只有在路由和防火墙都允许时才可能工作；这不会提升安全性，也不在默认验收拓扑内。

7. 投放与结束

  1. 默认模式连接成功后，把要显示的 Mac 窗口拖过桌面边缘，移入自动创建的虚拟显示器。
  2. Windows 子端可用顶部按钮或画面悬浮按钮进入/退出全屏，按 Esc 也会退出全屏。画面底部的主端名称、分辨率、FPS、码率与操作按钮默认隐藏；在画面内移动鼠标、触摸或用键盘聚焦后会出现，无操作约 2.2 秒后再次隐藏。
  3. 需要切换分辨率时，先点击“断开扩展屏”，修改参数后重新点击“扩展到 …”；不需要单独创建/销毁按钮。
  4. 由 Mac 主端点击断开结束会话。
  5. 断开会清理本会话自动创建的虚拟显示器；直接退出主端也会尝试清理 helper 和显示器。兼容模式下不会删除已有物理/系统显示器。

子端在会话期间阻止显示器自动休眠，断开后恢复系统原有电源策略。不要把它视为阻止整机睡眠或网络断开的保证。

主端和子端都会显示尽力而为的实时分辨率、FPS、码率和 RTT。这些值来自 WebRTC stats，适合排障，不是精密测量或性能承诺。

若开启“网络中断后自动重连”，只有网络/异常断线会按约 1.6、3.2、6.4、12 秒退避重试，之后封顶 12 秒；等待期间可点击“取消自动重连”。用户主动断开、子端显式拒绝/断开，或 WebSocket 正常/策略关闭（1000/1008）不会重连。重新建链时默认模式会用真实子端 UUID 恢复稳定显示身份，并安全替换上一轮虚拟屏进程。

8. 键鼠与剪贴板共享

键鼠共享与扩展屏互相独立，同一时间只运行一种会话。它不会创建虚拟屏，也不会把任何屏幕画面发送到 Windows。

  1. 在设备列表选择 Windows 子端。
  2. 滚动到“键鼠与剪贴板共享”，布局画布会按 macOS 当前真实坐标显示全部 Mac 显示器。
  3. 拖动橙色 Windows 屏幕并贴到物理摆放对应的边缘。按题图布局，应把 Windows 放在上方 Mac 屏幕右侧、右下 Mac 屏幕上方。
  4. 选择是否双向同步纯文本剪贴板；设置边缘停留时间，默认 80 ms。
  5. 点击“启动键鼠共享”。鼠标从相邻边缘移出后，Windows 本机光标会接管位置，键盘随鼠标一起切换。
  6. 从 Windows 对应边缘移回即可返回 Mac；紧急情况下按 Control + Option + Command + Esc。

默认键位为 Mac Command → Windows Ctrl、Option → Alt、Mac Control → Windows 键。断线、停止或返回 Mac 时会发送 releaseAll，释放远端仍按下的按键和鼠标按钮。

剪贴板当前只同步 UTF-8 纯文本，上限 128 KiB；不包含图片、文件、富文本或剪贴板历史。刚启动共享时以 Mac 当前剪贴板为初始值，之后两端任一侧复制的新文本都会同步。

9. 记忆功能

双端把设置写到各自本机的 settings.json：

  • 主端：画面参数、自动重连偏好、上次设备/捕获源标识、键鼠布局、边缘停留和剪贴板开关；
  • 子端：稳定设备 UUID、名称、端口和自动全屏偏好；
  • 设备：名称、上次私有 IPv4、端口、最后发现和最后连接时间。

常见位置是：

  • macOS：~/Library/Application Support/LanExtend/settings.json
  • Windows：%APPDATA%\LanExtend\settings.json

最终路径以 Electron 的 app.getPath('userData') 为准，开发版或包名变化时目录名可能不同。

特别地，仓库的 npm run dev:host / dev:receiver 为方便调试会使用系统临时目录下独立的 lanextend-dev-<role> userData，并允许多实例；它不用于验证正式配置路径或单实例。使用 npm start/打包产物才采用正常 userData。

记忆不等于认证

离线设备保留在列表只是为了快速重连。应用会按设备 id 合并新广播，但攻击者可以伪造相同 id；不要根据“曾连接”或“已记忆”图标判断设备可信。

忘记或重置

  • 单台设备：在主端设备列表使用“忘记”。
  • 全部设置：完全退出应用，先备份，再重命名 settings.json；下次启动会生成默认设置和新的子端 UUID。
  • 不要在应用运行中编辑配置，退出时或设置更新时可能覆盖手工内容。

10. 日常安全操作

  • 只在可信的家庭实验网、隔离测试 VLAN 或受控办公网使用。
  • Windows 防火墙规则只选择“专用网络”，并尽可能限制到 Mac 所在子网。
  • 每次连接前核对设备名称和 IP；敏感投放前在 Windows 旁现场确认。
  • 不做公网端口转发，不通过共享 VPN/穿透工具暴露，不在酒店/机场/访客 Wi‑Fi 使用。
  • 不使用来历不明的未签名二进制；保留对应提交和构建日志。
  • 结束后断开会话并退出两端，尤其是共享会议室设备。

出现问题时按故障排除检查；首次双机交付请完整执行验收清单。