跳转到内容
rVPN rVPN

macOS 应用

rVPN macOS 应用使用 Network Extension 建立全隧道 VPN 连接。所有流量都通过加密隧道路由。

需求

Section titled “需求”
  • macOS 13.0 或更高版本
  • 一台已部署的 rVPN 服务器
  • 服务器地址、身份密钥和预共享密钥包

设置

Section titled “设置”

1. 安装应用

Section titled “1. 安装应用”

从 Mac App Store 安装 rVPN。

2. 添加配置文件

Section titled “2. 添加配置文件”

从菜单栏图标打开应用。点击 Settings…（或按 ⌘,）。设置窗口有两个分段选项卡——Profiles 和 Settings。停留在 Profiles。

点击底部工具栏中的 + 按钮（或点击旁边的向上箭头图标以导入从其他设备导出的 .rvpn 文件）。窗口中会打开配置文件编辑器。

填入你关心的字段；基本项包括：

  • Name — 任意名称（例如 “Home HK”）
  • Colour — 用于在列表和菜单栏中识别配置文件的色块
  • Default Profile — 点击星标行将其设为默认（启动时自动连接）
  • Server Address — wss://your-server.com/api/v1/ws/tun
  • Trust on First Use — 保持开启以启用标准 TOFU 固定，或在下方粘贴预期的 Server Fingerprint 以获得更严格的验证
  • Identity Key — 点击 Generate 为该配置文件创建新的 X3DH 身份，或点击 Import… 加载已有密钥文件
  • Prekey Bundle — 点击 Import Prekey Bundle 并选择服务器管理员提供的 JSON 文件
  • DNS Servers — 当 DNS 回落到本地解析时使用的解析器列表，以逗号分隔（默认 1.1.1.1, 8.8.8.8）
  • Bypass Networks — 额外的直连 CIDR 范围
  • MTU — TUN 接口 MTU（默认 1420）
  • Split Tunnel — 关闭时所有流量通过 VPN；开启时会显示下方的相关部分
  • Bypass Country — 选择一个内置国家（CN、HK、SG、JP、KR 等），其 CIDR 范围将绕过隧道
  • Bypass Domains — 额外的直连域名
  • Tunnel Domains — 即便启用分流也强制通过隧道的域名

点击 Save。Identity Key 和 Prekey Bundle 行在填入后会显示绿色对勾。

3. 连接

Section titled “3. 连接”

在菜单栏下拉菜单中点击 Connect。首次连接时 macOS 会提示你允许 VPN 配置。请批准以继续。

应用会：

  1. 通过 TLS WebSocket 连接到你的服务器
  2. 建立前向保密加密（X3DH + Double Ratchet）
  3. 从服务器接收隧道 IP 地址
  4. 将所有流量路由通过 VPN

连接后，菜单栏下拉菜单会显示实时的 IP、Uptime 和 Sent/Recv 计数——随时点击菜单栏图标进行查看。

分流

Section titled “分流”

分流位于配置文件编辑器的 Traffic 部分。它只将国际流量路由通过 VPN，让本地流量（例如中国站点）直连。每项设置请参见上方字段列表。

广告拦截在每个配置文件中都开启，且无法从界面关闭（与移动端应用一致）。

配置文件

Section titled “配置文件”

应用最多支持 10 个配置文件。从菜单栏下拉菜单或 Profiles 设置选项卡切换配置文件。

每个配置文件独立存储：

  • 服务器地址
  • 身份密钥
  • 预共享密钥包
  • 分流设置

分享配置文件

Section titled “分享配置文件”

要将配置文件转交给另一台设备 —— 你的 iPhone、另一台 Mac、同事 —— 可以将其导出为 .rvpn 文件，然后通过你喜欢的方式（AirDrop、邮件、“文件” 应用）分享。

打开 设置 › 配置文件，在需要分享的配置文件上滑动或右键点击，选择 导出。弹出的对话框会询问是否包含身份密钥：

  • 导出但不包含身份密钥 —— 更安全。接收方可以查看该配置文件，并使用自己的密钥材料连接（他们需要来自同一服务器管理员的预共享密钥包）。跨用户或分享到不完全可信的场合时请选此项。
  • 包含身份密钥 —— 接收方可以直接在另一台设备上原样连接。仅在另一台设备是你自己的、或你完全信任接收方时选择此项。导出的文件会包含你的私钥。

随后 macOS 打开保存面板保存 .rvpn 文件 —— 你可以将其拖入 AirDrop、在邮件中添加为附件，或拖入信息。

一旦你至少成功连接过一次，导出的文件还会携带服务器已固定的身份（ik:1: 指纹）。这意味着接收方的客户端在服务器出示不同密钥时会拒绝连接，无需另行带外核验 —— 发送方通过转交文件为服务器做了背书。完整模型请参考 服务器身份固定。

服务器身份 (TOFU)

Section titled “服务器身份 (TOFU)”

首次使用即信任 (TOFU) 默认在每个配置文件中启用，会在首次成功连接时接受并固定服务器的身份。固定值以规范的 ik:1:<base32> 形式写入，并存放在配置文件本身。

若服务器日后使用了不同的密钥，应用会弹出 Server identity changed 提示，同时显示已固定和当次收到的两个固定值，并提供三个选项：取消、删除配置文件 或 信任新身份。若运营方通过带签名的轮换仪式更换密钥，应用会静默更新固定值 —— 不会弹出提示。

如需更严格的验证，可在首次连接前，将运营方提供的固定值（ik:1: 形式）粘贴到配置文件的 Server Fingerprint 字段中。

完整模型 —— 固定值格式、轮换仪式、威胁模型 —— 请参考 服务器身份固定。

故障排查

Section titled “故障排查”

应用显示 “Connected” 但没有流量

Section titled “应用显示 “Connected” 但没有流量”
  1. 检查服务器是否正在运行并在 443 端口可访问。
  2. 确认配置文件中的服务器地址正确（必须以 wss:// 开头）。
  3. 查看服务器日志中的连接错误。

“Failed to start VPN” 或连接立即失败

Section titled ““Failed to start VPN” 或连接立即失败”
  1. 确保配置文件编辑器中同时存在身份密钥和预共享密钥包（绿色对勾）。
  2. 确认服务器地址末尾没有多余空白。
  3. 如果问题仍然存在，请重新生成身份密钥并重新导入预共享密钥包。

应用更新后 VPN 停止工作

Section titled “应用更新后 VPN 停止工作”

macOS 独立于应用在系统设置中保留 VPN 配置文件。更新后，保存的配置文件可能引用了过时的隧道扩展。

解决办法：

  1. 打开系统设置 > VPN（或较新 macOS 上的系统设置 > 通用 > VPN 与过滤）。
  2. 删除 rVPN 条目。
  3. 重新打开 rVPN 应用并连接。应用会创建全新的配置文件。

此问题在 1.2.4 及更高版本中已解决，该版本会自动检测并替换陈旧的配置文件。

VPN 配置文件出现在系统设置中但应用显示 “Disconnected”

Section titled “VPN 配置文件出现在系统设置中但应用显示 “Disconnected””

该 VPN 配置文件可能是由旧版本或不同构建创建的。请删除：

  1. 打开系统设置 > VPN。
  2. 点击 rVPN 条目旁的信息按钮 (i) 并删除。
  3. 重新打开 rVPN 应用。它会在下次连接尝试时创建新的配置文件。

隧道已连接但 DNS 无法解析

Section titled “隧道已连接但 DNS 无法解析”

应用运行本地 DNS 代理用于分流的 DNS 解析。若 DNS 失败：

  1. 检查服务器地址是否可达。
  2. 尝试在配置文件编辑器中关闭分流以使用全隧道模式。
  3. 查看服务器日志中的 DNS 代理错误。

如何收集诊断日志

Section titled “如何收集诊断日志”

Rust 层日志被写入 App Group 容器中的文件：

Terminal window
cat ~/Library/Group\ Containers/group.org.rvpn.client/rvpn_tunnel_rust.log

系统级日志：

Terminal window
log show --predicate 'subsystem == "org.rvpn.tunnel"' --last 5m --level debug

后续步骤

Section titled “后续步骤”