131 lines
7.8 KiB
Markdown
131 lines
7.8 KiB
Markdown
# 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）：
|
||
|
||
```bash
|
||
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 数据库。
|
||
|
||
```bash
|
||
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 上检查，再显式应用网络配置：
|
||
|
||
```bash
|
||
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（或停止内核），再执行：
|
||
|
||
```bash
|
||
sudo python3 scripts/network-vm.py rollback --target-vm
|
||
```
|
||
|
||
它删除本项目 NAT 表和网络 unit/config，恢复记录的 sysctl 值。也可恢复中途失败的 apply。不要对其他软件或系统防火墙执行 flush。
|
||
|
||
```bash
|
||
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 和节点凭据：
|
||
|
||
```bash
|
||
sudo python3 scripts/diagnose-subscription.py --host subscription.example.com
|
||
```
|
||
|
||
默认代理地址取保存的 VM IPv4 与混合端口，也可显式传入 --proxy http://VM_IP:7890。根据诊断结果修复 VM 使用的网络管理器/DNS 配置；避免将订阅令牌、配置备份或完整日志写入公开仓库。
|