RoamSwitch for Linux 操作手册
本篇介绍桌面版（托盘图标 + 主窗口）RoamSwitch，按实际显示顺序逐一讲解托盘菜单以及主窗口的每一个标签页。内容假定您使用的是 GTK 桌面环境（GNOME、KDE、XFCE 等）。若要在无图形界面的服务器上运行，请参阅服务器版运维手册。
1. 关于本手册
RoamSwitch for Linux 是一款以 🛡️ 图标常驻在桌面系统托盘（通知区域）中的应用。点击托盘图标会打开一个菜单，从那里再打开主窗口，就能进入功能更详细的设置界面。
许多高级功能都带有 Pro 标记，这意味着只有购买（或试用）RoamSwitch Pro 之后才能启用。没有该标记的项目均可免费使用。
2. 托盘菜单
点击托盘图标后打开的菜单。下面按从上到下的顺序逐一介绍。
| 项目 | 说明 |
|---|---|
| 状态显示行 | 显示当前的保护状态（例如“🔒 外出防护 [级别]”）。点击后会打开主窗口。 |
| 🚨 解除 Air-Gap 并恢复通信 条件显示 | 仅当检测到严重威胁、网络处于紧急隔离（Air-Gap）状态时才会显示。请在确认安全后手动解除隔离。 |
| 📶 Wi-Fi / 有线连接状态 | 显示当前连接的网络名称与安全方式，或有线连接的状态（仅供查看，不可操作）。 |
| 恢复通信 条件显示 | 仅当 Wi-Fi 或蓝牙等无线功能因保护措施而被关闭时才会显示，可手动恢复。 |
| 立即应用 Lockdown / Balanced / Open | 只需单击一下，即可为当前网络立即应用三档安全级别之一。Lockdown 最严格，Open 最宽松。 |
| 恢复自动判定模式 / 解除覆盖 | 取消手动固定的级别，恢复为根据网络自动判定的模式。 |
| 持续时间子菜单 | 选择手动应用的级别要维持多久：直到下次断开连接为止 / 1 小时 / 2 小时 / 4 小时 / 今天之内 / 直到手动解除为止，共 6 个选项。 |
| DNS 子菜单 | 开关 DNS 威胁防护，并可从 Quad9、Cloudflare Security、AdGuard DNS、CleanBrowsing 四种安全 DNS 提供商中选择。 |
| 恢复子菜单 | 可以执行“紧急恢复网络”（在无法通信时强制恢复连接）以及“卸载”。 |
| 登录时自动启动 | 开关每次登录操作系统时是否自动启动 RoamSwitch。为了保持持续保护，建议保持开启。 |
| 语言子菜单 | 切换托盘菜单的显示语言。除“跟随系统语言”外，共有 10 种语言可选：日语、英语、简体中文、繁体中文、韩语、法语、德语、西班牙语、意大利语、葡萄牙语。 |
| 打开主窗口 | 打开第 3 章之后介绍的详细设置界面。 |
| 退出 | 退出 RoamSwitch。退出期间自动保护功能不会工作。 |
操作步骤
- 立即切换防护级别: 点击托盘图标，然后点击 Lockdown、Balanced 或 Open 中的任意一个。在随后显示的持续时间列表（直到下次断开连接为止 / 1 小时 / 2 小时 / 4 小时 / 今天之内 / 直到手动解除为止）中，点击您想维持的时长即可生效。
- 恢复自动判定: 点击托盘图标→"恢复自动判定模式"。
- 切换安全 DNS 提供商: 将鼠标悬停在托盘图标→DNS 子菜单上，点击您想使用的提供商。
- 无法通信时: 点击托盘图标→恢复子菜单→"紧急恢复网络"。
- 更改显示语言: 点击托盘图标→语言子菜单中您想使用的语言。
在屏幕较小或 DPI 缩放比例较高的环境下，Lockdown/Balanced/Open 这三项有时会被合并显示在一个名为“防护级别”的子菜单中（显示内容相同）。
3. 打开主窗口的方法
您可以通过托盘菜单中的“打开主窗口”，或点击状态显示行来打开主窗口。与 Mac 版“每个功能都打开独立窗口”的方式不同，这里所有设置都汇集在一个大窗口中，通过左侧边栏的 19 个标签页（分区）切换。后续章节将严格按照侧边栏中出现的顺序依次讲解。
4. 🌐 Network Management
侧边栏最顶部的标签页，用于注册当前所在的网络，以及管理已注册网络的列表。
| 卡片 | 说明 |
|---|---|
| 当前连接的网络 | 显示当前网络名称，以及一个用于“注册”该场所的按钮。如果已经注册过，则会改为显示当前的安全级别。 |
| 手动切换安全策略 | 与 Mac 版的“手动覆盖”功能相同：暂时忽略自动判定，将安全级别固定为您指定的值。 |
| 自动共享服务控制 | 在您处于非信任网络期间，自动禁用文件共享等服务的功能。 |
| 已注册网络列表 | 列出并可编辑您迄今为止注册过的所有网络及各自的安全级别。 |
操作步骤
- 注册当前网络: 点击"当前连接的网络"卡片中的"注册"按钮，选择名称和安全级别，然后点击"保存"。
- 编辑或删除已注册的网络: 在"已注册网络列表"中选择目标行，点击铅笔图标进行编辑，或点击垃圾桶图标进行删除。
- 临时固定级别: 在"手动切换安全策略"卡片中选择级别与持续时间，点击"应用"。
5. 📊 Security Diagnostic Suite
对 Linux 设备的安全配置进行评分的综合诊断标签页。顶部显示分数和标题，下方列出各检查项的通过或未通过状态。对应 Mac 版的“Mac 安全综合诊断”。建议养成定期打开这个标签页、确认没有遗留红色或黄色项目的习惯。
操作步骤 显示为红色或黄色的项目右侧配有处理按钮。点击后大多数情况下可以当场修复，分数也会自动更新。
6. 🚪 Ports & DevIsolator
所有标签页中内容最丰富的一个。它汇集了与网络边界相关的所有功能——从防止开发服务器端口暴露，到 ARP 异常检测、Sensor 配对，再到漏洞扫描。
| 卡片 | 说明 |
|---|---|
| 暴露端口 & 开发服务器隔离 | 列出对外可访问的开放端口（例如忘记关闭的开发服务器），并管理对它们的隔离与拦截。 |
| 端口与 ARP 异常的自动封堵 | 在检测到 ARP 欺骗或可疑端口扫描时，自动封堵相关通信的设置。 |
| 已配对的 Sensor 列表 | 列出已与独立产品“RoamSwitch Sensor”关联的设备。 |
| 使用配对码手动配对 | 输入 Sensor 颁发的配对码，即可关联一个新的 Sensor。 |
| Sensor 诊断结果 | 查看已关联的 Sensor 上报的诊断结果。 |
| 验证式漏洞扫描状态 | 显示对开放端口实际执行可达性验证后得到的漏洞扫描结果。 |
操作步骤
- 隔离开发服务器的端口: 在"暴露端口 & 开发服务器隔离"卡片的列表中选择目标端口，点击"隔离"或"拦截"。
- 配对 Sensor: 在"使用配对码手动配对"卡片的输入框中，输入 Sensor 端颁发的配对码，然后点击"关联"。
7. 🔌 USB & BadUSB Guard
| 卡片 | 说明 |
|---|---|
| USB / BadUSB 防御 | 启用或停用针对“BadUSB”攻击的防护——这类设备伪装成 U 盘，实际却表现得像键盘一样执行未经授权的操作。 |
| 已连接的 USB・HID 设备 | 列出当前连接的 USB 设备、键盘、鼠标等硬件。 |
| 已允许的 USB 设备（白名单） | 预先注册已确认安全的设备，这样就只有其他未知设备的连接才会触发警告。 |
操作步骤
- 点击"USB / BadUSB 防御"卡片中的开关，将其启用。
- 从"已连接的 USB・HID 设备"列表中选择您今后仍会使用的设备，然后点击"添加到许可列表"。
8. 🦠 Malware & Quarantine
整合了基于 ClamAV 的病毒防护，以及 Linux 特有的底层防御机制——fanotify、熵值分析、YARA 规则匹配和禁止执行保护。
| 卡片 | 说明 |
|---|---|
| ClamAV 病毒库 & 引擎状态 | 查看病毒库的最后更新时间以及引擎的运行状态。 |
| Linux 底层高级防御 | 在一处统一配置 fanotify（在文件被访问的瞬间进行实时检查）、熵值分析（检测勒索软件特有的加密行为）、YARA 规则匹配，以及强制禁止执行属性等设置。检测到类似勒索软件的写入激增时，会冻结相应进程并同时切断网络（Air-Gap）。 |
| ClamAV 按需扫描 | 立即手动扫描您指定的文件夹。 |
| 隔离库 | 可以还原或永久删除被判定为恶意软件并已隔离的文件。 |
| 监控文件夹（网页与邮件保护） | 设置哪些文件夹（例如下载文件夹）在出现新文件时会被自动扫描。 |
| 扫描排除设置 | 指定想从扫描范围中排除的文件夹，例如开发用目录。 |
| 可疑自启动通知 | 检查新创建或被改写的自启动项（systemd、cron、桌面自启动），只对看起来像恶意软件持久化手法的项目发出通知（默认开启，仅通知）。 |
操作步骤
- 立即扫描: 在"ClamAV 按需扫描"卡片中选择目标文件夹，点击"开始扫描"。
- 处理隔离文件: 在"隔离库"卡片的列表中选择文件，点击"还原"或"永久删除"。
- 添加监控文件夹: 在"监控文件夹"卡片的"添加文件夹"中选择下载文件夹等位置，然后点击"保存"。
9. 🛡️ DNS Threat Guard
在 DNS 层拦截对钓鱼网站以及恶意软件指挥控制服务器（C2）的域名解析。从下拉菜单中选择提供商（例如 Quad9），并通过“生效范围”设置它应用于哪些网络。此功能与托盘菜单（第 2 章）中的 DNS 子菜单联动。
操作步骤 打开开关后，从"安全 DNS 提供商"下拉菜单中选择您想使用的提供商，再通过"生效范围"选择要应用于哪些网络。
10. 🔒 VPN Tunnel Pro
在非信任网络上通过 VPN 加密通信的功能。状态卡片显示当前连接状态，配置卡片用于管理连接目标（例如导入 WireGuard 配置）。其思路与 Mac 手册 11.2 节相同，用于在不受信任的网络上防止通信被窃听或篡改。
操作步骤
- 在配置卡片的"后端"中选择 WireGuard 或 Tailscale。
- 如果使用 WireGuard，请通过"导入配置文件"选择
.conf文件；如果使用 Tailscale，请点击"登录"在浏览器中完成账号验证。 - 设置完成后点击"连接"。当状态卡片变为"已连接"时，说明 VPN 已生效。
11. 🔑 Secret & API Key Audit
一款审计工具，用于扫描主目录和配置文件中是否遗留了以明文形式意外保存的 API 密钥、密码、令牌等敏感信息。有助于预防开发者无意间将敏感信息留在代码仓库或配置文件中的事故。
操作步骤 点击"开始扫描"即可开始审计，完成后会以列表形式显示检测结果（文件路径与类型）。
12. 📜 Security Log Audit
用于审计和查看 RoamSwitch 及 Linux 系统所记录的安全相关日志的标签页，可按时间顺序追溯过去检测到了什么、又是如何处理的。
13. 🔔 Notifications
记录了 RoamSwitch 在过去 7 天内显示过的所有通知。即使错过了托盘弹出的通知，也可以在这里事后查看。
14. 🕒 Incident Timeline
一个按时间顺序汇总检测、响应、解除等安全事件，方便您整体回顾的界面（实验性功能）。当您想把握“到底发生了什么”的整体脉络，而不是逐条追查日志时，会很有用。
15. 🔎 Security Activity Log
可在同一画面中横跨检索并可视化 RoamSwitch 迄今检测、通知或处理过的所有内容。它将第 14 章的“Incident Timeline”与第 13 章的“Notifications”整合到一个视图中，可按时间范围、类别、严重度和关键字进行筛选。这与第 12 章的“Security Log Audit”（审计 journald 等操作系统侧日志的标签页）不同，此标签页用于回顾 RoamSwitch 自身已经检测、通知或处理过的内容。
操作步骤 使用时间范围、类别、严重度下拉菜单和关键字搜索框缩小范围后，点击画面上方柱状图中的特定时间段，即可将列表缩小到该时间段的事件。要取消缩小范围，请点击“取消筛选”按钮。
16. 🔗 Link Safety Audit
汇集了链接保护设置，以及一个可粘贴单个 URL 当场检查的手动检查工具的标签页。对应 Mac 手册的 9.5 节和 9.6 节。
操作步骤 要当场检查某个 URL，请将您想确认的 URL 粘贴到"手动检查"卡片的输入框中，然后点击"检查"。几秒钟内即会显示安全性判定结果。
17. 📦 Package CVE Scan
涵盖操作系统软件包管理器，直到各开发语言专属软件包的一个广泛的漏洞与供应链防护标签页。
| 卡片 | 说明 |
|---|---|
| 操作系统软件包 CVE 扫描 | 对照 dpkg、pacman、dnf、zypper 等发行版的软件包管理系统，检查是否存在已知漏洞（CVE）。 |
| 开发依赖项 CVE 扫描 | 对照 npm、PyPI、crates.io、RubyGems、Packagist、Go、Maven 等来源，检查开发项目依赖包的已知漏洞。 |
| 依赖锁定文件篡改监控 Pro | 监控 package-lock.json 等锁定文件是否被非法篡改。 |
| 安装脚本清单 Pro | 列出软件包安装过程中会执行的脚本，方便您检查是否存在可疑行为。 |
| 仿冒包名检测（Typosquatting）Pro | 检测是否安装了名称故意模仿正规软件包的仿冒软件包（Typosquatting）。 |
| npm 签名与来源验证（可选启用）Pro | 一项附加检查：验证 npm 软件包的签名与来源信息，确认其未被篡改。 |
在 Ubuntu（20.04、22.04、24.04、26.04）上，操作系统软件包 CVE 扫描使用 Ubuntu 专用数据，按源软件包名称和源版本比对。比对的只有 Ubuntu 已发布修复的高危 CVE（CVSS 7.0 及以上）。尚未发布修复的、尚未评估的以及 Ubuntu 决定不修复的 CVE 不在其中，因此“无匹配”不代表没有已知 CVE。内核由现有的内核 CVE 数据负责，不包含在此次比对中。只有 Ubuntu Pro（ESM）才能获得的修复，会带有 🔒 标记和“此修复仅通过 Ubuntu Pro（ESM）提供”的提示。在 Linux Mint、Pop!_OS 等衍生版和不支持的版本上，会显示“此 Ubuntu 不在 CVE 比对的支持范围内”。这种情况下也不会改用 Debian 的数据，以避免误报。Ubuntu 的数据带有签名，只发送给 Ubuntu 设备（约 4 MB）。尚未安装的设备在下一次每日更新时获取，之后约每 30 天确认一次。Debian、Arch、RHEL 系和 SUSE 的比对与以前相同。
操作步骤
- 点击"操作系统软件包 CVE 扫描"或"开发依赖项 CVE 扫描"卡片中的"开始扫描"。
- 完成后会显示相应的漏洞列表。每个项目都附有处理方法（例如更新命令）。
18. 💎 Pro License
汇总了免费版包含的功能列表、在服务器、VPS、云端或裸金属环境下运行时的商业相关信息，以及用于统一管理多台设备的 Fleet 面板入口。Pro 版的许可证激活也在此进行。
操作步骤
- 将密钥粘贴到许可证密钥输入框中，点击"激活"。
- 如果您还没有密钥，可以点击"购买"进入购买流程。激活成功后，此标签页和托盘菜单的显示会随之更新。
19. 🧰 Recovery & Uninstall
整合了紧急恢复（用于流量被意外持续拦截的情况）与卸载入口的标签页——功能与托盘菜单的“恢复”子菜单相同，只是附带了更详细的说明。
操作步骤
- 通信中断时的紧急恢复: 点击"紧急恢复网络"按钮，然后在确认对话框中选择"恢复"。
- 卸载: 请按照此标签页的说明操作，或在终端中运行与您所用软件包格式对应的命令（例如：
sudo apt purge roamswitch）。详情请参阅卸载步骤。
20. 📖 Help & Guide
应用内置的帮助界面，涵盖从基本用法到各项功能的补充说明。建议与本网页手册配合使用。
21. 🌐 Language
设置主窗口的显示语言。此处可选的语言与托盘菜单自身的语言设置（第 2 章）相同。
操作步骤 从下拉菜单中选择您想使用的语言，主窗口的显示会当场切换。
22. ℹ️ About RoamSwitch
汇总了版本信息、常规设置、开发者信息、许可证、安全政策、隐私政策、服务条款（EULA）、免责声明以及商标与版权声明等应用基本信息和法律信息。联系支持团队之前，请先在这个标签页确认您的版本号。
23. 🔄 Upgrade
可查看应用本体的自动更新状态、软件包更新状态，以及威胁库和诈骗网站列表更新状态的标签页。如果是通过发行版的包管理器安装的，通常会随常规系统更新一起自动保持最新。
24. 🛟 勒索软件恢复(快照与按文件复原)
在侧边栏的“勒索软件恢复”标签页中，针对您的主目录，可从损害发生前自动创建的快照中安全地只取出所需的文件或文件夹。当前文件不会被覆盖。（标准桌面版自 Linux 1.11.21 起提供。）
快照分为三种。“损害前(预先)”快照与是否受损无关，按固定间隔(默认每 6 小时)自动创建。“检测时”快照会在检测到类似勒索软件的行为时一定创建。“手动”快照是您自己用命令创建的。
取出文件时，请选择标有“★ 推荐”的“损害前(预先)”快照。 检测时: ⚠ 该快照在检测之后创建,包含已被加密的文件,不能用于恢复到加密之前(用于保全未受损内容和留作证据)。
取出的文件不会覆盖当前文件，而是放到单独的文件夹中(默认为目标文件夹内的 RoamSwitch-Recovered/快照ID/)。
损害前的快照默认每 6 小时自动创建一次（btrfs 保留 4 代，LVM 保留 2 代）。可用命令 sudo roamswitch-ransomware-rollback config set --periodic-interval-secs <N> 修改间隔（0 表示停用，其他值须为 300 秒以上）。创建检测时快照后，为避免已加密的数据挤掉最后一份完好的版本，会暂停事前快照 7 天。检测时的快照无论此设置如何都会创建。
支持的对象是 btrfs 和 LVM。在没有这些对象的环境中，会显示如下提示。 无法获取快照列表(未安装勒索软件回滚,或没有 btrfs/LVM 目标)。
整体回滚（高级，仅命令）：sudo roamswitch-ransomware-rollback restore <ID>。注意：当前状态会被所选快照的内容覆盖。请先尝试“取出文件”和“取出文件夹”。检测时的快照在不加 --accept-tampered 时会被拒绝。
也可以通过命令行使用(roamswitch-ransomware-rollback)。详情请参阅 CLI / 无头运行页面。
25. 🕸️ Web Shell 与注入代码检测(Web Rules)
用专用规则发现 PHP、JavaScript、JSP、ASP 的 Web Shell、被注入的混淆代码、伪装成图片的 PHP 以及 .htaccess 滥用。在开发 Web 应用的电脑上，项目文件夹同样在检测范围内。无需任何设置：文件在写入或打开时会被自动检查。规则随产品附带，并通过每日更新（仅接收）刷新。（自 Linux 1.11.23 起。）
发现问题时会出现确认对话框（“检测到危险文件”），显示文件名称和位置，按钮有三个：“稍后”“允许（今后不扫描）”“移入隔离区”。在您选择之前，不会对文件做任何处理。选择“移入隔离区”后，文件会被移到隔离区（之后可在“恶意软件与隔离”标签页中恢复）。若正在开发的代码被提示，请先查看其内容再做选择。选择“允许”后，该文件今后不再被检查。
要成批检查文件夹，请使用命令 roamswitch web-scan <文件夹>。默认只检查、不移动任何文件。结果会显示严重度（CRITICAL / HIGH / MEDIUM）、规则名称和说明。退出码：无命中为 0，发现 critical 或 high 为 2（可用于 CI 等）。--json 输出 JSON，--no-default-excludes 会连 tests/、fixtures/、.git/ 之下也一并检查；这些位置因测试代码会使用相同写法，默认不检查。用 roamswitch web-rules 可查看规则版本与状态。
这些是高级设置。自定义规则放在 /etc/roamswitch/rules.d/*.json（只读取 root 所有且他人不可写的文件；模板见 roamswitch web-rules example rules，验证用 roamswitch web-rules validate <文件>）。若要在每次检测时调用自己的脚本，请在 /etc/roamswitch/hooks/post-detection 放置可执行文件（检测内容会以 JSON 通过标准输入传入；模板见 roamswitch web-rules example hook）。隔离级别等选项在 /etc/roamswitch/web_rules.conf 中设置（roamswitch web-rules example conf）。
局限：写入/执行时只读取文件开头 256 KB，扫描时读取开头 4 MB；无法跟踪变量名拼接（'ev'.'al'）这类拆分；因没有真实样本，未附带针对已知恶意软件的个别签名。怀疑误报时，请选择“允许”，或用自定义规则排除。
26. 🤖 AI 智能体设置审计
此页面检查提供给 AI 智能体（Claude Code、Codex、Cursor、Gemini、OpenClaw 等）的指示文件和技能，以及 OpenClaw 的设置文件中是否有危险内容。在左侧菜单打开「🤖 AI 智能体设置审计」并点击“运行审计”，即以只读方式检查。检查对象是主目录中的 ~/.claude（CLAUDE.md、commands、agents、skills）、~/.codex、~/.cursor/rules、~/.gemini、~/.agents、~/.openclaw，以及在“软件包 CVE 扫描”中登记的项目文件夹里的 CLAUDE.md、AGENTS.md、.cursorrules 等。不进行任何网络通信，文件正文以及密钥、令牌的值既不会显示在界面上，也不会出现在结果中。
会查找隐藏在不可见 Unicode 字符中的指示、“忽略之前的指示”“不要告诉用户”之类的措辞、下载脚本后直接执行的写法（curl … | sh）、解码字符串后执行的写法、对机密文件（SSH 密钥、云凭据等）的引用及其附近的外发、技能中的已编译代码、其他用户可写入的文件，以及 OpenClaw 的认证被关闭、不足 24 个字符的令牌、允许所有网站的设置和以 dangerously 开头的危险开关。HTML 注释（渲染 Markdown 后会消失的部分）中的内容会按更高风险处理。
结果分为“重大度：高”和“中”，每项都会显示文件位置、行号和原因。匹配只表示“需要人来读一读”，并不断定为恶意；讲解攻击手法的文档或用于提醒的示例句也可能被匹配。无法读取的文件会单独列出，不会被说成“没有发现问题”。命令行为 roamswitch audit-agent-setup [文件夹…] [--json]。AI 助手可通过 MCP 工具 audit_agent_setup 获取同样的结果。
27. 🔐 SSH 暴力破解的阻断与入侵路径通知（无界面）
仅当这台设备上的 SSH（sshd）在运行时，才会监视 SSH 登录失败，并阻断在短时间内反复失败的来源的新连接。该来源已经建立到 SSH 的连接也会被切断，但已认证的会话和写入排除列表的来源不会被切断。在 sshd 没有运行的设备上，不读取任何内容，也不改动任何内容。没有设置界面，通过 ~/.config/roamswitch/config.json 中的 ssh_guard_*（10 个键，参见 CLI / 无界面运维 中的设置表）来修改。通知为桌面通知，也会保留在历史记录中。
正在阻断的来源列表用 sudo roamswitch bans 查看，用 sudo roamswitch unban <IP> 解除（全部解除用 --all）。在客户端的默认防护级别下，入站是关闭的，连接可能根本到不了 SSH，这时阻断起作用的场合也会变少。当 fail2ban 或 CrowdSec 已在保护 sshd 时，RoamSwitch 会让出阻断，只做检测和通知。
通知关键文件被篡改的消息（FIM）中，会附上做出修改的进程，以及该进程所属的 SSH 登录（来源、时间、认证方式）。凭据文件访问的通知，只有在属于某个 SSH 登录时才会附上。无法查明时，会写“无法查明登录路径”，而不会写成不是登录。要关闭，请在 config.json 中写入 "fim_intrusion_context_enabled": false。