clash-web/docs/deployment.md

PVE Linux VM 部署与恢复

网络前提

• 开发测试机与正式 VM 分开，正式 VM 位于 PVE。
• 本方案以现有路由器为上游；VM 不负责替代路由器的 DHCP 服务。
• VM 不提供 DHCP。首先手动配置一台测试客户端；全网设备逐台配置，或后续增加可控路由器。
• 第一版只处理 IPv4，客户端 IPv6 可能继续通过光猫绕过 VM。测试设备先关闭 IPv6；全网部署前关闭路由器 IPv6 通告。若无法关闭，需要调整网络设备。

1. 创建 VM

推荐 Ubuntu 24.04 LTS / Debian 12+，1–2 vCPU、1 GB 内存、8 GB 磁盘起步。VM 网卡连接 PVE 的 LAN bridge（通常是 vmbr0），用 VirtIO 网卡，与客户端在同一网段。不要把 VM 放进仅 NAT 的虚拟网络；无需修改 PVE 宿主机的默认网关。

假设（示例地址，部署时替换）：

角色	地址
光猫/上游路由器	192.168.1.1
LAN 网段	192.168.1.0/24
VM 固定地址	192.168.1.10
VM 网卡	ens18
测试客户端	192.168.1.50

将路由器 DHCP 地址池设为如 192.168.1.100–200，把 VM 固定地址放在池外，并确认没有地址冲突。VM 自身的上游网关始终为 192.168.1.1；初始化时 VM 自身 DNS 可用光猫或公共 DNS，不要指向尚未运行的自己。

2. 复制程序并安装服务

开发机生成的 clashweb-linux-amd64.tar.gz 包含管理程序、Mihomo 和规则，复制到 amd64 VM 即可，无需再次构建或下载内核。将配套 .sha256 文件一起复制。在 VM 上准备系统工具（这些 apt 包仅需安装到目标 VM）：

sudo apt update
sudo apt install -y sudo python3 iproute2 nftables ca-certificates
sha256sum -c clashweb-linux-amd64.tar.gz.sha256
tar -xzf clashweb-linux-amd64.tar.gz
cd clashweb-linux-amd64
sha256sum -c SHA256SUMS
sudo ./scripts/install.sh --target-vm --bind 192.168.1.10:8080

安装脚本创建普通用户 clashweb 与 clashweb-mihomo，配置独立数据目录、核心网络能力和受限的服务控制辅助程序。管理后端通过 sudo 仅允许启停固定的 clashweb-mihomo.service，不允许执行任意 root 命令。

安装完成时 TUN 仍关闭；光猫、DHCP 和客户端网络不变。已有配置再次安装时会保留，安装脚本不会复制开发机 SQLite 数据库。

sudo systemctl status clashweb clashweb-mihomo --no-pager
sudo journalctl -u clashweb -n 30 --no-pager

打开 http://192.168.1.10:8080，使用日志中的首次设置令牌设置密码。添加订阅、更新节点、测试延迟并选择一个节点。先在客户端用显式 HTTP/SOCKS 代理验证：代理地址为 192.168.1.10:7890。需在 UI 填写 VM 地址、LAN 网段、网卡并保存后，代理端口才会监听 LAN。

3. 准备单网卡旁路转发

在 VM 上检查，再显式应用网络配置：

python3 scripts/network-vm.py check
sudo python3 scripts/network-vm.py apply --target-vm --interface ens18 --lan-cidr 192.168.1.0/24

脚本开启 IPv4 转发、关闭 ICMP 路由重定向、调整所需反向路径检查，并创建独立的 ip clashweb_nat nftables 表，为单网卡转发提供回程处理。只管理自己的配置文件和 NAT 表，不清空现有防火墙，不修改网卡 IP、默认网关或 DHCP。原 sysctl 值记录在 /var/lib/clashweb-network/backup.json。

如果 VM 使用 UFW/nftables 或启用了 PVE 防火墙，应允许 LAN 到 VM 的管理 TCP 8080、混合代理 TCP 7890、DNS UDP/TCP 53、以及所需的转发流量；规则仅面向实际内网网段。若已有转发链默认 DROP，需要在已有防火墙中放行该 VM 的 LAN 转发。不要开放控制端口 9090；它只监听 VM 本机。

4. UI 启用网关模式

在「系统设置」填写：VM 地址 192.168.1.10、网段 192.168.1.0/24、上游网关 192.168.1.1、网卡 ens18、DNS 端口 53，开启 TUN，保存。

检查日志没有 TUN、DNS 监听或路由创建错误；VM 上 ip link show cw-tun 应存在，ip rule 应出现内核管理的路由规则。已有程序占用 VM 的 IP:53 时，应先处理冲突；systemd-resolved 的 127.0.0.53:53 与只绑定 VM LAN IP 的监听通常可以共存。

手动配置测试客户端：

• IPv4 地址仍在 LAN 内，若采用固定地址应选光猫 DHCP 地址池之外的未占用地址。
• IPv4 网关设为 192.168.1.10。
• DNS 只设为 192.168.1.10，不保留备用光猫 DNS；关闭客户端 IPv6。
• 清除原系统/浏览器代理设置，测试纯透明代理。

浏览器的加密 DNS 不会自动被普通 53 端口 DNS 劫持覆盖；验证阶段关闭浏览器安全 DNS/系统私人 DNS，使用 VM DNS，确保域名分流行为一致。

5. 验收

1. 从客户端访问管理页面、光猫、内网设备，确认内网仍可达。
2. 访问大陆网站，在「连接」中确认命中大陆规则且出口为 DIRECT。
3. 访问国外网站，确认使用所选代理节点；切换节点后以新连接验证出口。
4. 测试 UDP：需要订阅节点和目标应用都支持 UDP。HTTP 代理节点等不支持 UDP 的节点不会凭空获得 UDP 能力。
5. 所选节点失效时，国外访问失败，内核运行期间大陆和内网仍直连；手动模式不自动换节点。
6. 重启 VM，确认服务、网络准备、订阅快照与选择恢复，再扩大客户端范围。

开发环境的显式代理测试不能替代以上真实 LAN/TUN 验收。

恢复与故障定位

节点故障与 VM 停机不同。VM 停机或内核停止时，作为 DNS/网关的客户端可能整体断网，不能由该 VM 自动修复。

优先恢复客户端：把网关和 DNS 改回光猫 192.168.1.1，或恢复自动获取，刷新 DHCP 租约/DNS 缓存。光猫 DHCP 一直保留，因此无需恢复光猫 DHCP。

要撤销 VM 网络准备：先在 UI 关闭 TUN（或停止内核），再执行：

sudo python3 scripts/network-vm.py rollback --target-vm

它删除本项目 NAT 表和网络 unit/config，恢复记录的 sysctl 值。也可恢复中途失败的 apply。不要对其他软件或系统防火墙执行 flush。

sudo journalctl -u clashweb -u clashweb-mihomo -n 100 --no-pager
sudo systemctl restart clashweb-mihomo
ip -4 route
ip rule
sudo nft list table ip clashweb_nat

运维与备份

• UI 导出备份含订阅 URL 和节点凭据，备份不包含管理员密码、登录会话或内核控制密钥；导入不会更改管理员密码。
• 需要完整迁移管理员时，停止服务后备份 /var/lib/clashweb 与 /var/lib/clashweb-core；不要在 SQLite 正在写入时只复制单个 .sqlite 文件而遗漏 WAL。
• 规则库更新：在目标 VM 解压目录运行 sudo scripts/update-rules.sh。下载失败不替换旧文件，校验或重启失败恢复旧规则。
• 默认下载脚本使用 Mihomo v1.19.32；升级时显式下载、检查、部署并复测。首次部署与规则更新需要外网下载能力，可先在开发机准备文件。
• 如通过 HTTPS 反向代理管理界面，关闭 SSE 缓冲，并设置 CLASHWEB_SECURE_COOKIE=true。默认方案只用于受信任内网。

订阅下载故障排查

下载由管理服务发起，先检查 VM 的系统 DNS、时间、CA 证书和出站连接，确认订阅地址有效；YAML 解析失败与网络下载失败分别排查。

只读诊断脚本根据保存的订阅 hostname 匹配，使用服务用户测试系统 DNS、直接下载与 Mihomo 代理下载，仅输出状态摘要，不显示订阅 URL 和节点凭据：

sudo python3 scripts/diagnose-subscription.py --host subscription.example.com

默认代理地址取保存的 VM IPv4 与混合端口，也可显式传入 --proxy http://VM_IP:7890。根据诊断结果修复 VM 使用的网络管理器/DNS 配置；避免将订阅令牌、配置备份或完整日志写入公开仓库。