Initialize Clash Web source and deployment documentation

docs/api.md

@@ -0,0 +1,44 @@
+# 管理 API v1
+
+所有接口与 Web UI 同源。除首次设置、登录和登录状态外，均需要 `cw_session` HttpOnly cookie。修改接口还需 `X-CSRF-Token`，令牌由登录/首次设置/密码更新及 `/auth/status` 返回。会话有效期 24 小时，退出或修改密码会撤销对应会话。
+
+统一错误：`{"error":"中文说明"}`；认证失败 401、CSRF/跨站失败 403、输入或应用失败 400、内核未连接的实时查询 503。
+
+| 方法 | `/api/v1` 下的路径 | 用途 |
+|---|---|---|
+| GET | `/auth/status` | initialized、authenticated、csrf |
+| POST | `/auth/setup` | `{token,password}` 首次设置；密码 12–72 字节 |
+| POST | `/auth/login` | `{password}` 登录 |
+| POST | `/auth/logout` | 退出 |
+| PUT | `/auth/password` | `{currentPassword,password}`，撤销旧会话 |
+| GET | `/status` | 内核状态、版本、实际出口、设置和配置错误 |
+| GET/POST | `/subscriptions` | 列表/新增 `{name,url,enabled,intervalHours}` |
+| PUT/DELETE | `/subscriptions/{id}` | 编辑/删除 |
+| POST | `/subscriptions/{id}/refresh` | 下载、解析、校验、应用；失败保留旧快照 |
+| GET | `/nodes` | 脱敏节点信息，不返回密码、服务器地址等凭据 |
+| POST | `/nodes/select` | `{mode:"manual",id}` 或 `{mode:"auto"}` |
+| POST | `/nodes/test` | `{ids:[...]}`，1–500 个、并发上限 8 |
+| GET | `/rules` | 默认顺序及自定义规则 |
+| POST | `/rules` | `{type,value,action,enabled}` |
+| PUT/DELETE | `/rules/{id}` | 编辑/删除 |
+| GET/PUT | `/settings` | 读取/完整替换设置；网卡与地址在当前机器校验 |
+| GET | `/connections` | Mihomo 活跃连接 |
+| DELETE | `/connections/{id}` | 关闭指定连接 |
+| DELETE | `/connections` | 关闭全部连接 |
+| POST | `/system/service` | `{action:"start"\|"stop"\|"restart"}`，仅固定内核 unit |
+| GET | `/system/network` | 网卡、IPv4 转发、TUN、资源和辅助程序检查 |
+| GET | `/system/updates` | 手动检查 Mihomo 最新稳定版；返回当前/最新版本、更新状态（无法比较时为 null）、检查时间及发布说明 URL；成功结果缓存 10 分钟，失败返回 502 |
+| GET | `/system/connectivity` | 9 个固定 HTTPS 测试网站的 id/name/url/category |
+| POST | `/system/connectivity/test` | `{siteId}`；当前 VM Mihomo 分流测试；返回 status/detail/httpStatus/durationMS/tlsVerified/checkedAt；全服务并发上限 3，多余返回 429 |
+| GET | `/system/backup` | `{version:1,exportedAt,state}`，敏感配置导出 |
+| POST | `/system/restore` | 同版本备份，校验与回滚；不覆盖管理员 |
+| GET | `/events` | SSE `metrics`，每 2 秒更新累计量、速率与连接数 |
+| GET | `/logs` | SSE `log`、`heartbeat`、`disconnected` |
+
+SSE 认证失效时发送 `expired` 并关闭，浏览器应重新登录。代理关闭使用 settings 的 `proxyEnabled=false`，进入直连模式；与停止内核进程不同，DNS/网关仍运行。
+
+`Settings` 字段：`proxyEnabled,tunEnabled,selectionMode,selectedNode,lanIP,lanCIDR,gateway,interface,mixedPort,dnsPort,testURL,testTimeoutMS`。HTTP/SOCKS 端口为 1024–65535，DNS 为 1–65535，避免与 8080/9090 冲突。开启 TUN 要求填写内网参数并使用 DNS 端口 53。
+
+订阅 ID/规则 ID 为稳定随机 24 位十六进制标识；节点 ID 使用 `订阅ID/提供者/原节点名`，对路径参数需 URL 编码。规则 `type` 为 DOMAIN、DOMAIN-SUFFIX、IP-CIDR，`action` 为 DIRECT 或 PROXY。内网规则优先，其次自定义列表，再大陆规则，最后代理。
+
+默认手动模式首次未选节点或所选节点移除时，代理策略选择 REJECT；不会静默选择其他节点或直连。内核停止时，校验通过的配置可暂存以供下次启动；控制接口认证或通信失败不会当成停止状态忽略。

docs/deployment.md

@@ -0,0 +1,130 @@
+# 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 配置；避免将订阅令牌、配置备份或完整日志写入公开仓库。

docs/development.md

@@ -0,0 +1,121 @@
+# 开发与测试
+
+## 环境
+
+- Go 1.24+。
+- Node.js 22.12+ 或 24+，npm。
+- Python 3；Linux amd64 打包脚本的安全解压校验需要 Python 3.12+。
+- Linux；正式代理服务与开发环境分开。
+
+依赖版本由 go.mod、go.sum 和 web/package-lock.json 固定。Go 模块目录遵循开发机的 go env 配置。
+
+## 首次准备
+
+在项目根目录执行：
+
+```bash
+make build
+make assets
+```
+
+make build 安装锁定的前端依赖、生成 web/dist，再构建 bin/clashweb；静态 Web 资源嵌入 Go 程序。make assets 下载指定 Mihomo 稳定版和大陆 MRS 规则，分别保存到 bin/mihomo 和 data/mihomo/rules。
+
+资源已有时可复用：
+
+```bash
+cd web
+npm run build
+cd ..
+CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
+```
+
+Go 构建与测试依赖 web/dist 存在，首次克隆应先构建前端。前端构建完成后再执行 Go 构建，避免嵌入尚未生成的资源。
+
+## 本地运行
+
+终端一，生成配置并启动内核：
+
+```bash
+./bin/clashweb --mihomo ./bin/mihomo --init
+./bin/mihomo -d ./data/mihomo -f ./data/mihomo/config.yaml
+```
+
+终端二，启动管理服务：
+
+```bash
+./bin/clashweb --mihomo ./bin/mihomo
+```
+
+访问 http://127.0.0.1:8080。首次设置令牌在启动日志中显示，管理员密码为 12–72 字节。已初始化的数据目录使用原管理员密码登录。
+
+默认混合代理为 127.0.0.1:7890，DNS 为 127.0.0.1:1053，Mihomo 控制接口为 127.0.0.1:9090。开发时保持 TUN 关闭；IPv4 转发、防火墙和网关配置在目标 VM 上准备。
+
+前端热更新时，保持 Go 后端运行，并在另一终端执行：
+
+```bash
+cd web
+npm run dev
+```
+
+Vite 将 /api 转发至 http://127.0.0.1:8080。远程开发可用 SSH 转发访问管理服务：
+
+```bash
+ssh -N -L 8080:127.0.0.1:8080 USER@DEV_HOST
+```
+
+停止时在管理服务和内核终端分别按 Ctrl+C。本地 data/ 目录保留管理员、订阅和设置。
+
+## 测试
+
+前端构建已完成时可直接执行：
+
+```bash
+go test -race ./...
+go vet ./...
+cd web
+npm run test
+cd ..
+```
+
+真实内核集成测试：
+
+```bash
+CLASHWEB_TEST_MIHOMO_BIN="$PWD/bin/mihomo" \
+CLASHWEB_TEST_RULES_DIR="$PWD/data/mihomo/rules" \
+go test -race ./...
+```
+
+浏览器测试首次需要安装 Chromium：
+
+```bash
+cd web
+npx playwright install chromium
+cd ..
+python3 scripts/test-e2e.py
+```
+
+E2E 使用临时数据库、本地订阅夹具、真实后端和 Mihomo；管理服务监听 127.0.0.1:18080，需要 9090/7890/1053 空闲。检测到端口占用时终止，结束后清理测试进程和临时数据库。常用网站响应在浏览器测试中使用夹具。
+
+截图写入 .cache/screenshots，测试报告写入 web/test-results，均不提交到 Git。无需重装依赖时，直接使用以上命令；make test、make integration、make e2e 会先重新准备前端依赖。
+
+## 配置与提交范围
+
+- bin/：本地生成的管理程序和下载的内核。
+- data/：SQLite、订阅、控制密钥、内核配置和规则。
+- web/dist/：嵌入 Go 程序的前端输出。
+- web/node_modules/：前端开发依赖。
+- .cache/、测试报告和压缩包：过程或分发产物。
+
+这些目录和文件由 .gitignore 排除。只提交源码、锁文件、测试、部署脚本和维护文档。
+
+## 打包
+
+在 Linux amd64 构建环境执行：
+
+```bash
+GOOS=linux GOARCH=amd64 GOAMD64=v1 CGO_ENABLED=0 \
+go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
+python3 scripts/package.py
+```
+
+脚本只使用现有程序与规则生成完整安装包和管理更新包，附文件清单和 SHA-256，执行解压校验与隔离初始化，不包含开发数据库或订阅。分发包通过 Gitea Release 或其他文件渠道传递，不作为源码提交。

docs/third-party.md

@@ -0,0 +1,7 @@
+# 复用组件
+
+- [Mihomo](https://github.com/MetaCubeX/mihomo)：独立进程形式使用的代理内核，遵循其 GPL-3.0 许可。
+- [MetaCubeX meta-rules-dat](https://github.com/MetaCubeX/meta-rules-dat)：大陆域名/IP MRS 规则资源，使用项目自身的分发与许可约定。
+- Vue、Vue Router、Pinia、Naive UI、Lucide、ECharts：前端组件与图表。依赖许可证随 npm 包分发。
+- modernc.org/sqlite、yaml.v3、gorilla/websocket、golang.org/x：后端存储、解析与通信，依赖版本与校验值见 go.mod/go.sum。
+- Vitest、Playwright：仅用于开发测试；Chromium 与 FFmpeg 测试组件不会打包进服务程序。

docs/upgrading.md

@@ -0,0 +1,92 @@
+# 软件、内核与规则升级
+
+三个部分分别更新：Clash Web 管理程序（包含 Web UI）、Mihomo 代理内核、大陆规则库。管理员、订阅与选择在数据目录中，升级程序时不覆盖它们。
+
+## 检查版本
+
+「系统设置 → Mihomo 服务 → 内核更新」可手动检查 GitHub 官方最新稳定版，显示当前版本、最新版本和发布说明链接。查询结果缓存 10 分钟，避免反复请求 GitHub。内核离线或运行开发版时仍可查最新稳定版，但不能确认版本高低。网络或 GitHub 限流错误会明确提示。
+
+检查仅获取版本信息，不下载程序、不自动升级；未开启无人值守更新。管理程序从仓库获取源码构建，或使用维护者提供的更新包。内核更新检查不等同于管理程序更新。
+
+## 升级 Mihomo
+
+先在 UI 导出配置备份。正式 VM 升级前建议做 PVE 快照，便于恢复完整服务状态。浏览官方发布说明，选择明确的稳定版版本号。
+
+在项目/解压目录下载到新文件；将 `vX.Y.Z` 替换为所选真实版本：
+
+```bash
+python3 scripts/fetch-mihomo.py --version vX.Y.Z --output bin/mihomo.next
+```
+
+下载脚本选择当前机器架构对应的官方资产，根据 GitHub 的 SHA-256 digest 校验，然后解压。缺少校验值或校验失败会终止，不覆盖现有内核。此步会产生一次新的内核下载。
+
+正式 VM 上，先放置候选内核并用现有配置验证，成功后再替换：
+
+```bash
+sudo install -m 0755 -o root -g root bin/mihomo.next /usr/local/bin/mihomo.next
+sudo -u clashweb-mihomo /usr/local/bin/mihomo.next -t \
+  -d /var/lib/clashweb-core -f /var/lib/clashweb-core/config.yaml
+```
+
+只有校验成功才执行：
+
+```bash
+sudo install -m 0755 -o root -g root /usr/local/bin/mihomo /usr/local/bin/mihomo.previous
+sudo mv /usr/local/bin/mihomo.next /usr/local/bin/mihomo
+sudo systemctl restart clashweb-mihomo
+sudo systemctl status clashweb-mihomo --no-pager
+```
+
+在 UI 确认内核版本和节点选择，并用测试客户端验证大陆/国外访问。重启期间代理连接会中断。新版本异常时恢复旧程序：
+
+```bash
+sudo install -m 0755 -o root -g root /usr/local/bin/mihomo.previous /usr/local/bin/mihomo.rollback
+sudo mv /usr/local/bin/mihomo.rollback /usr/local/bin/mihomo
+sudo systemctl restart clashweb-mihomo
+```
+
+本机开发预览也可先下载 `bin/mihomo.next`，使用 `-t -d ./data/mihomo -f ./data/mihomo/config.yaml` 校验；成功后停止预览内核，保留旧二进制再替换 `bin/mihomo` 并重新启动。保持 TUN 关闭。不要在开发机执行上述正式 VM 的 systemd 操作。
+
+## 升级 Clash Web 管理程序
+
+取得新的项目源码，在开发机执行 `make build`。只复制新的 `bin/clashweb` 到目标 VM，保留数据目录：
+
+```bash
+sudo install -m 0755 -o root -g root /usr/local/bin/clashweb /usr/local/bin/clashweb.previous
+sudo install -m 0755 -o root -g root bin/clashweb /usr/local/bin/clashweb.next
+sudo mv /usr/local/bin/clashweb.next /usr/local/bin/clashweb
+sudo systemctl restart clashweb
+```
+
+重新打开页面确认登录、订阅和节点。失败时将 `clashweb.previous` 复制到新临时文件，再移动回 `clashweb` 并重启。未来若更新涉及数据库格式变更，应遵循相应发布说明；不能只替换旧二进制就假定数据必然兼容。
+
+## 更新规则
+
+正式 VM 上在项目/解压目录运行：
+
+```bash
+sudo scripts/update-rules.sh
+```
+
+下载后校验当前配置、重启内核，失败时恢复旧规则。与程序更新互相独立。
+
+## 预构建管理程序更新包
+
+打包脚本生成 `clashweb-update-linux-amd64.tar.gz`（仅管理服务与嵌入 UI）与 `clashweb-linux-amd64.tar.gz`（完整安装）。已有部署使用更新包即可，无需升级 Mihomo 或重配网络。
+
+将更新包传到 VM，在包所在目录执行：
+
+```bash
+tar -xzf clashweb-update-linux-amd64.tar.gz
+cd clashweb-update-linux-amd64
+sha256sum -c SHA256SUMS
+sudo install -m 0755 -o root -g root /usr/local/bin/clashweb /usr/local/bin/clashweb.previous
+sudo install -m 0755 -o root -g root bin/clashweb /usr/local/bin/clashweb.next
+sudo mv /usr/local/bin/clashweb.next /usr/local/bin/clashweb
+sudo systemctl restart clashweb
+sudo systemctl status clashweb --no-pager
+```
+
+成功后刷新管理页面，确认登录、订阅和节点状态。管理服务重启不重启独立 Mihomo；管理员、订阅和网络配置保留。
+
+出现异常可按前面的步骤用 clashweb.previous 回退；数据库格式变更应按对应版本说明处理。