ROAMSWITCH SERVER 1.1.0+ · 最后更新：2026-09-18

RoamSwitch服务器版操作手册

云 VPS（AWS、GCP、Azure、Linode、DigitalOcean）、裸机数据中心和容器主机的官方安装、部署和操作参考。

1. 概述及要求

RoamSwitch 服务器版是一个 无头（零 GUI 依赖）自主防御和完整性监控套件 ，专为暴露于公共互联网的 Linux 服务器而设计。

与基于 Wi-Fi 状态动态切换配置文件的客户端版本不同，服务器版本强制执行入站默认丢弃、关键路径文件完整性监控 (FIM)、预防性内核 LPE 缓解（Frag Gap）、eBPF 运行时威胁检测、SSH 锁定预防和自动多通道紧急警报（Telegram / LINE / Webhook）。

零遥测架构

RoamSwitch 将零诊断遥测、主机 IP 元数据、文件哈希或系统日志传输到外部服务器。守护程序二进制文件中不存在外部网络库，从而保证了完全的本地机密性。

系统要求

支持的发行版：Ubuntu 22.04 / 24.04 LTS、Debian 12+、AlmaLinux / Rocky Linux / RHEL 9+、Fedora 39+、openSUSE Leap 15.5+、Raspberry Pi OS（64 位）
架构：x86_64 (amd64) 或 aarch64 (arm64)
Kernel：Linux 5.10+（推荐nftables、cgroups v2、eBPF BTF）
Footprint：20–30 MB 驻留内存，空闲/正常工作负载期间 <0.1% CPU

2. 安装步骤

使用官方签名的存储库可确保通过标准系统包管理器自动解决依赖关系并进行无缝更新。

2.1 APT（Ubuntu / Debian / Raspberry Pi 操作系统）

# 1. 注册仓库签名密钥
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. 添加仓库
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/roamswitch.list

# 3. 安装
sudo apt update && sudo apt install roamswitch-server

2.2 DNF / RPM（Fedora / RHEL / AlmaLinux / Rocky Linux）

# 1. 导入 GPG 密钥
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. 添加仓库配置文件
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. 安装
sudo dnf install roamswitch-server

2.3 openSUSE（zypper）

sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch
sudo zypper addrepo https://lafine.net/rpm/opensuse/roamswitch.repo
sudo zypper refresh && sudo zypper install roamswitch-server

包互斥（冲突）

客户端版本 (roamswitch) 和服务器版本 (roamswitch-server) 声明相互的包冲突。在无头服务器环境中始终选择 roamswitch-server。

3. 初始设置和服务验证

3.1 服务状态

安装后，roamswitch-server.service 立即启动并在系统引导时启用。

sudo systemctl status roamswitch-server.service

3.2 交互式设置向导

使用以下命令启动交互式设置向导，交互式配置端口、维护来源 IP、通知渠道和遏制操作（按 Enter 采用各项默认值）。

sudo roamswitch server setup

端口：分别以逗号分隔输入 SSH 维护端口（默认 22）和公开服务端口（默认 80,443）。
维护来源 IP：指定 SSH 跳板机或监控来源的 IP/CIDR（例如 203.0.113.50/32）；留空则允许来自任意 IP 的 SSH。
通知渠道设置：分别启用 Telegram Bot、LINE Messaging API、通用 Webhook（Slack / Discord / Teams）。
eBPF 重大事件时的响应：选择 isolate（隔离主机）/ freeze（冻结该进程）/ alert_only（仅通知）。保存后会确认发送测试通知并重启服务。
内核 CVE 数据自动更新（默认 n）：选择是否让容器隔离审计使用的内核 CVE 数据库每天一次从 lafine.net 匿名获取（不含查询字符串、Cookie 或识别性请求头）。即使保持禁用，审计本身仍会基于内置基线运行。这是 Server Edition 零网络代码方针中唯一的例外，默认关闭（需手动开启）。
File Scan Guard 设置：设置是否为邮件中继、共享文件夹、上传目标启用病毒扫描（§13）及目标目录。可选功能，默认关闭。
Resource Guard 设置：设置是否启用检测网络公开服务持续 RSS 增长（内存泄漏/DoS）或崩溃循环的资源枯竭防护。
常驻核心防护说明：显示无需通过向导、始终生效的核心防护功能列表，如入站默认拒绝、FIM、eBPF 集成等（无需输入）。
调查代理协作（investigation）设置：设置是否将 eBPF 重大事件，或关键路径 FIM/依赖锁文件篡改检测（均为仅通知判定时）的初步调查自动委托给外部 AI 代理 CLI（Claude Code / agy / Codex CLI / OpenCode，或自定义命令）（§10.1）。默认关闭。

Telegram Chat ID 提示

超级群组的 Chat ID 是以 -100 开头的负数（例如 -1001234567890）。可在 curl -s "https://api.telegram.org/bot<token>/getUpdates" 响应中的 "chat":{"id":...} 字段确认正确的值。

3.3 30项服务器安全审计

sudo roamswitch status --server

对防火墙规则、Frag Gap 缓解、Yama LSM 限制、权限和 Docker 端口暴露执行即时 30 项检查审核，产生 0-100 的安全评分和等级（S 到 C）。

4. 防火墙和端口规则

配置文件 /etc/roamswitch/server.conf 出于保护敏感信息的目的，强制要求权限为 0600（仅 root 可读写）。格式为扁平的 key=value，形如 [network] 的分区标题行会被忽略。

# --- 防火墙 ---
ssh_ports=22                     # SSH 管理端口（紧急隔离时也保留）
allowed_ports=80,443             # 公开服务端口
whitelist_ips=203.0.113.10/32    # 维护来源 IP / CIDR（留空 = 全部允许，旧名 admin_source_ips 也可）
protect_docker_ports=true        # DOCKER-USER 保护（阻止容器绕过防火墙）
preserve_ssh_on_isolation=true   # 紧急隔离时也保留 SSH 管理通道（设为 false 则完全阻断）

# --- eBPF 运行时防护 ---
action_on_critical=isolate       # isolate | freeze（SIGSTOP+网络阻断） | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Egress / C2 阻断与 DNS 黑洞 ---
egress_ip_blocklist_enabled=true # 默认 true。情报源未填充时无害（不会阻断任何内容）
dns_sinkhole_enabled=false       # 默认 false（避免破坏内部 DNS/split-horizon 环境）
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- 容器隔离 CVE 数据（可选启用） ---
cve_kernel_map_updates_enabled=false # 默认 false。唯一的外部通信例外（每天一次·匿名）

# --- 通知 ---
telegram_enabled=false
telegram_bot_token=
telegram_chat_id=
line_enabled=false
webhook_enabled=false
webhook_url=

# --- 系统 ---
language=ja
fim_check_interval_secs=300      # 旧名 scan_interval 也可

如果直接编辑了配置，需要重启服务才能生效（roamswitch-server 不支持 reload）：

sudo roamswitch server restart

4.1 按严重级别设置策略（`guard.yaml`，可选）

如果仅靠 action_on_critical 无法满足更精细的控制需求，可创建 /etc/roamswitch/guard.yaml（分发模板位于 /etc/roamswitch/guard.yaml.example）。若该文件不存在，会根据 server.conf 中的 action_on_critical 自动合成等效策略，不影响现有运行。

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # 同一进程再次发生时自动升级为主机隔离
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # 主机隔离后，若在此秒数内无 ack 则自动恢复（0 为禁用）

安全定时器：主机隔离（Air-Gap）触发后，管理员在排查原因后使用以下命令进行确认应答（ack）。若在 safety_timer_secs 内未收到应答，RoamSwitch 会自动解除隔离，以避免误报导致服务器无限期与网络断开。

sudo roamswitch server ack

4.2 Egress / C2 阻断与 DNS 黑洞

设置 egress_ip_blocklist_enabled=true（默认）后，会通过 nftables 阻断对已知恶意 IP 的外发连接。优先使用 /var/lib/roamswitch/threatfeed/malicious_ips.txt（由更新机制维护）的情报源，若不存在则回退到软件包自带的空种子文件（/usr/share/roamswitch/threatfeed/），因此在情报源尚未填充数据前，默认值 true 不会阻断任何流量。

将 dns_sinkhole_enabled=true 设置为启用后，会强制通过过滤型 DNS 解析器（Quad9 / Cloudflare / AdGuard / CleanBrowsing）解析域名，阻断对已知恶意域名的解析。因可能破坏内部 DNS 或 split-horizon 环境，默认值为 false。

4.3 入站端口扫描检测防护

通过将 nftables 日志规则与 journald 进行比对，检测在短时间内连接了大量不同端口的来源 IP（默认启用）。高置信度的扫描来源可在一定时间内自动封锁。与 RoamSwitch Sensor 一起使用时（与 §10.1 是不同的功能——已配对 Sensor 的全端口审计探测会作为误报对策被排除），Sensor 一侧的 IP 会自动排除在外。

# --- 入站端口扫描检测（默认启用） ---
port_scan_detect_enabled=true              # false 表示禁用
port_scan_detect_min_distinct_ports=15     # 连接到不少于此数量的不同端口时判定为扫描
port_scan_detect_window_secs=300           # 判定的统计窗口（秒）
port_scan_block_enabled=true               # 自动封锁检测到的扫描来源 IP
port_scan_block_duration_secs=600          # 自动封锁的持续时间（秒）

可通过 roamswitch port-scan 命令查看检测历史。

5. SSH 锁定预防故障保护

由于防火墙配置错误而导致的意外锁定是无法容忍的操作灾难。 RoamSwitch 服务器版包含多层保护措施：

已建立/相关无条件通过：在规则重新加载期间，活动会话永远不会被删除。
Air-Gap 上的 SSH 保留：即使在敌对攻击遏制下，preserve_ssh_on_isolation = true 仍保持来自授权 CIDR 的管理访问权限以进行调查。
Atomic nftables 加载并回滚：规则语法错误立即触发零停机回滚到之前已验证的规则集。

6.容器保护（Docker/Podman）

Docker 的默认行为会创建绕过标准主机防火墙的自定义 iptables 规则，将容器端口（例如 -p 8080:8080）直接暴露到互联网。

当 protect_docker_ports=true（默认）时，RoamSwitch 会在 DOCKER-USER 链的最前面插入检查规则，使发往容器的流量也遵循 allowed_ports 和 whitelist_ips 策略，从而可靠地防止开发用数据库容器等被意外暴露到外部。

此外，监控 docker events 的实时防护会在以 --privileged 启动的容器或挂载了 /var/run/docker.sock 的容器（存在容器逃逸风险）启动后立即检测并发出通知。无需配置、始终启用，检测仅用于通知（不会自动阻断）。

7. 关键路径文件完整性监控（FIM）

使用 SHA-256 哈希监视 150 多个基本二进制文件（/bin/login、/usr/bin/sudo、/usr/sbin/sshd）、身份验证配置（/etc/shadow、/etc/pam.d/）和 systemd 单元。

7.1 手动哈希验证

sudo roamswitch fim verify

7.2 事件驱动检测（即时）

受监控文件通过 fanotify（FAN_CLASS_NOTIF，写入完成事件）被逐一监视，无需等待下一次周期性扫描，篡改发生的瞬间即会重新校验哈希。周期性扫描（默认 fim_check_interval_secs=300 秒间隔）仍会作为漏检事件的后备保障并存。

7.3 操作系统更新时自动基线同步

在 Debian/Ubuntu 上，安装软件包时会自动配置 /etc/apt/apt.conf.d/99roamswitch-fim 的 DPkg::Post-Invoke 钩子。在 Fedora/RHEL/Rocky/AlmaLinux/openSUSE 上，监控 /var/lib/rpm 的 systemd.path 单元（roamswitch-fim-update.path）承担相同职责。

在 Debian/Ubuntu 上，/etc/apt/apt.conf.d/99roamswitch-fim 附加一个 DPkg::Post-Invoke 挂钩。通过 sudo apt upgrade 进行的合法软件包更新会自动刷新 FIM 基线，从而消除误报警报。

sudo roamswitch fim update

8. eBPF 运行时防护和 Falco 集成

挂钩内核空间 eBPF 事件 (Falco / Tetragon) 以检测 Frag Gap 内核权限升级、容器逃逸和未经授权的反向 shell。

8.1 抗膨胀架构

传统安全代理遭受严重的系统日志爆炸和磁盘磨损。 RoamSwitch 通过专用 UNIX 域套接字 (/run/roamswitch/events.sock) 直接连接到 Falco：

捆绑的 /etc/falco/config.d/99-roamswitch-optimized.yaml 将事件直接流式传输到守护程序中，磁盘 I/O 为零。
/etc/logrotate.d/roamswitch-falco 确保任何后备文件输出的每日干净轮换。

8.2 自主收容

一旦检测到严重攻击，RoamSwitch 会立即发出 SIGSTOP 来冻结违规进程 PID 并应用 nftables 气隙隔离。

9. 紧急警报（Telegram / LINE / Webhook）

当发生端口异常、FIM 篡改或 eBPF 遏制事件时，立即向外部通知通道发送警报：

[notifications]
language = ja
# Telegram：Bot Token 与 Chat ID
telegram_bot_token = "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
telegram_chat_id = "-1001234567890"

# LINE：Messaging API 频道访问令牌与用户 ID
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# 通用 Webhook（Slack、Discord、Teams、自建监控平台）
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

即使未配置这些外部通知渠道，已发送的通知也会在本地保留最近1周。可通过 roamswitch notifications 查看。

10.AI代理/MCP集成（模型上下文协议）

RoamSwitch 服务器版包括 roamswitch-mcp，允许 AI 代理（Claude、Gemini、Cursor）监控基础设施健康状况和状态。

只读安全保证

为了防止即时注入攻击损害基础设施，MCP 接口严格是只读的。 AI 代理无法通过 MCP 打开端口、取消隔离或更改安全配置。修复需要经过身份验证的本地 TTY shell 访问。

配置示例（`claude_desktop_config.json`）

{
  "mcpServers": {
    "roamswitch": {
      "command": "/usr/bin/roamswitch-mcp",
      "args": []
    }
  }
}

10.1 调查代理协作（investigation，将初步自动调查委托给 AI 代理）

§10 的 roamswitch-mcp 面向「人类通过 AI 客户端发起的查询」，而investigation 协作是另一种机制：由守护进程自身在检测到事件时自主启动外部 AI 代理 CLI。其对象是被判定为仅通知（未触发自动隔离或进程冻结）的 eBPF 重大事件，以及关键路径 FIM、依赖锁文件篡改检测。启用后，守护进程会先生成本地启发式一次判定报告（误报可能性、依据、下一步调查建议），随后附带该报告以子进程方式启动已配置的 AI 代理 CLI，委托其进行进一步调查与总结。默认关闭。

# 追加到 /etc/roamswitch/guard.yaml（与 server.conf 是不同的文件）
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | 任意自定义命令
  args: ["-p"]                      # 提示词会自动作为末尾参数追加
  timeout_secs: 180

同样内容也可在 sudo roamswitch server setup 的交互式向导（§3.2 最后一步）中设置。可选择 Claude Code（claude -p）/ agy（agy -p --dangerously-skip-permissions）/ Codex CLI（codex exec）/ OpenCode（opencode run）预设，或任意自定义命令。再次运行时会根据已保存的设置自动选中对应预设。

关于提示词注入的注意事项

investigation 协作会将检测事件的详细信息（进程名、文件路径等攻击者可能部分控制的字符串）作为提示词的一部分传递给 AI 代理。尤其是将工具配置为以跳过权限确认的模式（例如 --dangerously-skip-permissions）运行，会提高恶意输入导致代理执行非预期操作的风险。选择 agy 时向导会显示此警告。在存在不可信日志输入路径的环境中，建议使用不跳过权限确认的工具配置。

在网络中断期间（如 Air-Gap 触发时等，相当于 isolate_host_all 的状态）不会调用 investigation 协作。

11. CLI 命令备忘单

命令	特权	描述
`sudo roamswitch status --server`	root	显示 30 项服务器状态评分并检查细分
`sudo roamswitch ports`	root	审计开放的监听端口和绑定的进程
`sudo roamswitch fim verify`	root	验证关键路径系统文件的 SHA-256 完整性
`roamswitch notifications`	用户	显示过去1周的通知历史（所有已发送的告警）
`sudo roamswitch server setup`	root	启动交互式初始配置向导
`sudo roamswitch fim update`	root	刷新 FIM SHA-256 基线数据库
`sudo roamswitch server config set <key> <value>`	root	修改并保存单个配置键（列表见 §4）
`sudo roamswitch airgap enable` / `disable`	root	手动触发/解除 Air-Gap 紧急切断
`sudo roamswitch emergency-restore`	根	解除全部 eBPF/防火墙紧急隔离，恢复到初始基线
`roamswitch port-scan`	普通用户	显示入站端口扫描检测防护（§4.3）的检测历史（来源 IP、是否自动封锁及封锁时长）
`roamswitch sensor [key\|list\|pair\|unpair\|request-audit\|results]`	普通用户/root	与 RoamSwitch Sensor 之间基于配对码的相互信任。`pair --addr <IP> --code <配对码>` 完成配对，`request-audit` 请求主动漏洞审计（通过 `results` 获取结果）。需要 `sensor_pairing_enabled: true`（默认关闭）。详情请参阅 Sensor 运维手册

12. 故障排除和常见问题解答

Q1. RoamSwitch 会意外断开我的 SSH 会话吗？

不会。RoamSwitch 无条件允许已建立的 ESTABLISHED/RELATED 连接状态以及 ssh_ports（默认 22）。即使因严重攻击触发 Air-Gap 紧急隔离，preserve_ssh_on_isolation=true（默认）也会保留管理会话。

Q2。如果不小心被锁定，如何重新获得访问权限？

通过云服务商的 Web 管理控制台（VNC/串行控制台）登录，执行 sudo roamswitch emergency-restore 解除紧急隔离，或执行 sudo systemctl stop roamswitch-server 停止服务。

Q3。如何为新添加的 Web 服务（例如 Nginx）公开端口？

执行 sudo roamswitch server config set allowed_ports 80,443,3000（或直接编辑 /etc/roamswitch/server.conf），然后执行 sudo roamswitch server restart。

13. File Scan Guard（保护邮件中继、共享文件夹与上传目的地）

仅当此主机存在用于保存要交给他人的文件的目录（如邮件中继、Samba/NFS 共享、文件上传目的地）时才需要关注的可选功能。内置 YARA 引擎无需外部依赖即可持续扫描 clamav_scan_dirs，设置 clamav_enabled=true 后还会加入 ClamAV 作为第二重判断。确认的威胁会自动隔离至 /var/lib/roamswitch/quarantine，并通知运维人员。

# --- File Scan Guard（ClamAV，可选启用） ---
# 内置 YARA 引擎始终无条件扫描 clamav_scan_dirs。
clamav_enabled=false             # 设为 true 可启用 clamdscan 进行额外检查
clamav_scan_dirs=                # 扫描目标的绝对路径（以逗号分隔）
clamav_scan_interval_secs=86400  # 扫描间隔（秒，最小 3600）
clamav_freshclam_interval_secs=7200  # 特征库自动更新间隔（秒，最小 1800）

也可通过交互式向导 sudo roamswitch server setup 进行配置，并可通过 get_file_scan_guard_status MCP 工具查看配置与隔离状态。

14. Log Audit（日志模式异常检测与通知）

通过定期扫描 journalctl 将日志消息模板化，检测新模式（前所未见的日志形态）与频率异常（统计学激增，Z-score > 3.0）。由于无需额外守护进程或外部依赖，这是一种轻量机制，默认已启用。检测到异常时会通过与 File Scan Guard 和 FIM 相同的通知渠道（Telegram / LINE / Webhook）发送通知。日志中可能出现的 API 密钥或令牌，会在写入通知正文之前自动脱敏。

# --- Log Audit（默认启用） ---
log_audit_enabled=true           # 设为 false 可禁用
log_audit_interval_secs=1800     # 扫描间隔（秒，最小 300）

也可通过交互式向导 sudo roamswitch server setup 进行配置，并可通过 roamswitch audit-logs CLI 命令或 audit_security_logs MCP 工具查看最新的检测结果。

← 服务器版白皮书前往 Linux 版安装页面 →

RoamSwitch服务器版操作手册

1. 概述及要求

系统要求

2. 安装步骤

2.1 APT（Ubuntu / Debian / Raspberry Pi 操作系统）

2.2 DNF / RPM（Fedora / RHEL / AlmaLinux / Rocky Linux）

2.3 openSUSE（zypper）

3. 初始设置和服务验证

3.1 服务状态

3.2 交互式设置向导

3.3 30项服务器安全审计

4. 防火墙和端口规则

4.1 按严重级别设置策略（guard.yaml，可选）

4.2 Egress / C2 阻断与 DNS 黑洞

4.3 入站端口扫描检测防护

5. SSH 锁定预防故障保护

6.容器保护（Docker/Podman）

7. 关键路径文件完整性监控（FIM）

7.1 手动哈希验证

7.2 事件驱动检测（即时）

7.3 操作系统更新时自动基线同步

8. eBPF 运行时防护和 Falco 集成

8.1 抗膨胀架构

8.2 自主收容

9. 紧急警报（Telegram / LINE / Webhook）

10.AI代理/MCP集成（模型上下文协议）

配置示例（`claude_desktop_config.json`）

10.1 调查代理协作（investigation，将初步自动调查委托给 AI 代理）

11. CLI 命令备忘单

12. 故障排除和常见问题解答

Q1. RoamSwitch 会意外断开我的 SSH 会话吗？

Q2。如果不小心被锁定，如何重新获得访问权限？

Q3。如何为新添加的 Web 服务（例如 Nginx）公开端口？

13. File Scan Guard（保护邮件中继、共享文件夹与上传目的地）

14. Log Audit（日志模式异常检测与通知）

4.1 按严重级别设置策略（`guard.yaml`，可选）