# xpasswall

跨平台代理管理面板：[PassWall](https://github.com/Openwrt-Passwall/openwrt-passwall) 的独立移植版，脱离 OpenWrt 运行，提供独立 Web 界面与认证登录。

- 技术栈：Go 单二进制后端 + Vue3/Naive UI 前端（embed 嵌入）
- 目标平台：linux/amd64、linux/arm64、linux/arm、linux/mipsle、windows/amd64
- 开源协议：**GPL-3.0**（借鉴了上游 Lua/Shell 逻辑，构成衍生作品）
- 详细设计见 [docs/可行性方案.md](docs/可行性方案.md)

## 当前状态（PassWall 功能对齐完成）

- [x] 认证登录（bcrypt / 会话 Cookie / CSRF / 防爆破锁定 / 首次启动随机初始密码）
- [x] 节点管理：vless / vmess / trojan / shadowsocks / **hysteria2**（密码/salamander 混淆/上下行带宽/insecure），支持 ws/grpc 传输、tls/reality 安全、pcs 自签证书指纹
- [x] **多核心引擎路由**：hysteria2 节点由 Hysteria 核心（client 模式）驱动，其余协议由 Xray 驱动；状态含 `engine` 字段
- [x] **组件管理（组件更新）**：仪表盘展示 Xray / Sing-Box / Hysteria / ChinaDNS-NG / Geoview 的安装状态、版本、**二进制文件路径**，一键在线安装/更新（XPASSWALL_GH_MIRROR 镜像，支持手动放置）
- [x] 订阅：base64 订阅与分享链接（vmess/vless/trojan/ss，含 SIP002）导入、刷新、删除
- [x] 分流模式：全局 / 绕过大陆（geosite:cn、geoip:cn）/ **白名单（默认直连，仅规则流量走代理）**
- [x] **规则列表（PassWall 对齐）**：直连/代理/阻断三类列表（域名+IP）+ LAN 网段，默认内置 PassWall 同款内容；订阅规则（gfwlist/chnlist/chnroute/chnroute6）与 Geo 数据在线更新（多源镜像、清洗去重、sha256 校验、失败回滚、定时调度）；UI 双页面管理
- [x] **高级设置（PassWall 对齐）**：Xray TCP 分片（fragment）、UDP 噪声包（noise）、嗅探域名覆盖目标、连接缓冲区、日志级别
- [x] **DNS 防污染分流**：国内域名→223.5.5.5/119.29.29.29 直连，其余→1.1.1.1 经代理出站查询；domainStrategy=IPIfNonMatch
- [x] **多节点故障转移/负载均衡（PassWall 对齐）**：_balancing 节点形态（random/roundRobin/leastPing/leastLoad 策略）+ fallback + observatory 探测，坏节点自动切换
- [x] **Socks 多实例 + 探测自动切换（PassWall 对齐）**：任意多实例，每实例可绑定多端口（SOCKS5/HTTP 混合、独立监听地址）；每端口独立多用户认证；TCP 探测失败自动轮换备用节点池；公网监听无认证时返回 warning（不拦截）
- [x] **主页连通性检测（PassWall 对齐）**：Aliyun / Google / GitHub / YouTube 四站一键检测
- [x] **配置备份 / 恢复 / 出厂重置（PassWall 对齐）**：zip 打包下载、上传恢复（JSON 校验）、一键重置
- [x] **节点分享生态（PassWall 对齐）**：分享链接生成（vless/vmess/ss/trojan/hysteria2）、剪贴板批量导入、节点分组
- [x] **订阅增强（PassWall 对齐）**：过滤关键词 5 模式、allowInsecure 覆盖
- [x] 自定义分流规则：域名/IP → 代理/直连/阻断，优先级高于分流模式
- [x] 延迟测试：单节点 / 全量 TCP 拨测，UI 显示
- [x] 系统代理一键开关：Windows 注册表+wininet 即时通知；Linux GNOME/KDE
- [x] 本地入站：SOCKS5 (127.0.0.1:1080) + HTTP (127.0.0.1:1081)
- [x] 五平台交叉编译打包 + systemd unit + 版本注入
- [x] **Shunt 分流体系（PassWall 对齐）**：分流规则组（remarks/group/network/protocol/inbound/source/port/domain/ip 全条件 + 组内排序）+ 分流总节点（逐条规则分配出口：主节点/直连/阻断/指定节点）；UI 管理页；E2E 验证三种出口路由
- [x] **完整冒烟测试 93/93 通过**（scripts/smoke.ps1：认证/节点/订阅/设置/自定义规则/Shunt 分流/规则列表文件与校验/高级选项/延迟/系统代理/组件管理/双引擎/hysteria2 QUIC 回环/故障转移/双入站/三模式/DNS/启停注销）

对齐说明：PassWall 的透明代理（TPROXY/TUN 网关模式）需要管理员权限与平台特定实现，属 P2 规划；sing-box 核心管理已就绪（组件页可见版本与路径），作为代理引擎支持 TUIC 等协议属后续计划。

## 目录结构

```
cmd/xpasswall/          程序入口
internal/api/       REST API + 前端静态资源服务
internal/auth/      认证（bcrypt、会话、CSRF、防爆破）
internal/config/    运行配置（监听地址、本地代理端口、分流模式）
internal/node/      节点模型与存储
internal/routing/   自定义分流规则与存储
internal/subscribe/ 订阅/分享链接解析与订阅存储
internal/sysproxy/  系统代理一键开关（Windows/Linux 桌面）
internal/core/components/ 组件管理（下载/更新/版本/二进制路径）
internal/core/xray/ Xray 配置生成、核心下载（镜像）、进程管理
internal/core/hysteria/ Hysteria 核心管理与 hysteria2 客户端配置生成
internal/web/       前端构建产物嵌入（internal/web/dist）
web/                Vue3 前端源码
docs/               可行性方案
scripts/            打包脚本、systemd unit、冒烟测试、gencert 测试辅助
```

## 快速开始

### 一键安装（发布包自带，自动开机自启）

**Linux（systemd）**：

```bash
tar -xzf xpasswall-v1.3.1-rc-linux-amd64.tar.gz
sudo ./install.sh        # 安装到 /usr/local/xpasswall 并 enable --now 自启
journalctl -u xpasswall      # 查看日志（首次启动输出 admin 初始密码）
sudo ./install.sh --remove   # 卸载（停止+禁用，保留数据）
```

**Windows（任务计划自启，需管理员）**：

```powershell
# 解压 zip 后，管理员 PowerShell 运行：
powershell -ExecutionPolicy Bypass -File .\install.ps1        # 安装 + 开机自启 + 立即启动
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Remove   # 卸载
```

- Windows 安装位置：`%ProgramFiles%\xpasswall\xpasswall.exe`，数据目录 `%ProgramData%\xpasswall\data`
- 默认监听 `127.0.0.1:8080`；面板初始账号 `admin` / `admin123`（首次登录强制修改）
- 远程访问：改数据目录下 `config.json` 的 `listen` 并自行评估风险

### 开发模式

```powershell
# 终端 1：后端（默认监听 127.0.0.1:8080，可用环境变量 XPASSWALL_LISTEN 覆盖）
go run ./cmd/xpasswall

# 终端 2：前端（Vite 5173，/api 自动代理到 8080）
cd web
npm install
npm run dev
```

> 首次启动会创建管理员账户 admin，**初始密码为固定值 `admin123`**，登录后会强制弹窗要求修改密码（修改前每次登录均会弹出）。

> 若 Go 模块拉取超时（proxy.golang.org 不可达），执行一次 `go env -w GOPROXY=https://goproxy.cn,direct` 切换国内镜像。

> 若系统设置了 `NODE_ENV=production`，npm 会跳过 devDependencies 导致 `vite` 缺失；安装前请切换 `NODE_ENV=development` 或使用 `npm install --include=dev`。

### 生产构建（单二进制）

```powershell
cd web
npm run build        # 输出到 ../internal/web/dist
cd ..
go build -trimpath -ldflags "-s -w" -o xpasswall.exe ./cmd/xpasswall
.\xpasswall.exe
```

> 提交代码前若发现 `internal/web/dist/.gitkeep` 被 vite 清空构建时删除，请用 `git checkout -- internal/web/dist/.gitkeep` 恢复（保证全新克隆后未构建前端也能编译）。

### 交叉编译示例（Linux ARM64）

```powershell
$env:CGO_ENABLED="0"; $env:GOOS="linux"; $env:GOARCH="arm64"
go build -trimpath -ldflags "-s -w" -o dist/xpasswall-linux-arm64 ./cmd/xpasswall
```

## REST API

| 方法 | 路径 | 说明 | 认证 |
| --- | --- | --- | --- |
| POST | /api/login | 登录，返回 CSRF 令牌 | 否 |
| POST | /api/logout | 注销 | 是 |
| GET | /api/session | 当前会话信息 | 是 |
| POST | /api/password | 修改密码（吊销全部会话） | 是 |
| GET | /api/system/status | 服务状态 | 是 |
| GET | /api/nodes | 节点列表 | 是 |
| POST | /api/nodes | 创建节点 | 是+CSRF |
| PUT | /api/nodes/{id} | 更新节点 | 是+CSRF |
| DELETE | /api/nodes/{id} | 删除节点 | 是+CSRF |
| GET | /api/proxy/status | 代理/核心状态 | 是 |
| POST | /api/proxy/start | 启动代理（body: node_id） | 是+CSRF |
| POST | /api/proxy/stop | 停止代理 | 是+CSRF |
| GET | /api/proxy/logs?tail=N | 运行日志 | 是 |
| POST | /api/core/install | 下载安装 Xray 核心 | 是+CSRF |
| GET | /api/subscriptions | 订阅列表 | 是 |
| POST | /api/subscriptions | 添加并拉取订阅（body: url, name） | 是+CSRF |
| POST | /api/subscriptions/{id}/refresh | 刷新订阅（重建其节点） | 是+CSRF |
| DELETE | /api/subscriptions/{id} | 删除订阅及其节点 | 是+CSRF |
| POST | /api/nodes/delay | TCP 延迟拨测（body: ids，空为全部） | 是+CSRF |
| GET | /api/settings | 读取设置（分流模式/端口） | 是 |
| PUT | /api/settings | 更新设置（重启代理后生效） | 是+CSRF |
| GET | /api/sysproxy | 系统代理状态 | 是 |
| POST | /api/sysproxy | 系统代理开关（body: enable） | 是+CSRF |
| GET | /api/rules | 自定义分流规则列表 | 是 |
| POST | /api/rules | 添加规则（kind: domain/ip, action: proxy/direct/block） | 是+CSRF |
| PUT | /api/rules/{id} | 更新规则 | 是+CSRF |
| DELETE | /api/rules/{id} | 删除规则 | 是+CSRF |

### 分流优先级（自上而下匹配）

1. 私有/LAN 直连（geoip:private + lanlist 列表）
2. **阻断列表**（block_host / block_ip，不可被覆盖）
3. 自定义规则（按添加顺序）
4. **代理列表**（proxy_host / proxy_ip）
5. **直连列表**（direct_host / direct_ip）
6. 分流模式规则：bypass_mainland 下 gfwlist→代理、chnlist/chnroute→直连（无列表时退回 geosite:cn / geoip:cn）
7. 兜底：global 走代理 / whitelist 直连

> 注意：列表条目转为 Xray 规则时，域名与 IP 拆分为独立规则（Xray 同一规则内多条件为 AND 语义）。
> 列表保存与规则更新后需重启代理生效；Geo 数据支持一键回滚上一版本。

### 系统代理

仪表盘一键开关。Windows 写 `HKCU\...\Internet Settings` 并经 wininet 即时生效（含内网绕过列表）；Linux 支持 GNOME/KDE，无桌面环境返回不支持提示。

### 打包发布

```powershell
powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -AppVersion v0.3.0
# 产物 dist/:
#   xpasswall-v0.3.0-windows-amd64.zip
#   xpasswall-v0.3.0-linux-{amd64,arm64,arm,mipsle}.tar.gz   (linux 包内含 xpasswall.service)
```

Linux 部署（systemd）：

```bash
sudo tar -xzf xpasswall-v0.3.0-linux-amd64.tar.gz -C /usr/local/xpasswall --one-top-level  # 或手动放置
sudo cp xpasswall.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now xpasswall
journalctl -u xpasswall   # 首次启动查看 admin 初始密码
```

变更类请求（POST/PUT/PATCH/DELETE）必须携带 `X-CSRF-Token` 头（登录响应中下发）。

### Xray 核心

- UI 内点击"安装 Xray 核心"自动从 GitHub Releases 下载（windows-64 / linux-64 / arm64 / arm32-v7a）
- GitHub 不可达时设置环境变量 `XPASSWALL_GH_MIRROR` 使用镜像，两种写法：
  - 前缀式加速：`XPASSWALL_GH_MIRROR=https://gh-proxy.com`（最终地址 `镜像/原始URL`）
  - 主机替换式：`XPASSWALL_GH_MIRROR=qgithub.com`（替换 github.com 及 *.githubusercontent.com）
- 网络受限环境也可手动放置二进制到 `data/bin/xray.exe`（Linux 为 `data/bin/xray`），并放入 `geoip.dat`/`geosite.dat`（绕过大陆分流必需），可从 [XTLS/Xray-core](https://github.com/XTLS/Xray-core/releases) 下载对应平台 zip 解压

## 安全设计

- Web 默认仅监听 `127.0.0.1:8080`；远程访问需修改 `data/config.json` 并自行评估风险
- 密码使用 bcrypt(cost=12) 存储；登录连续失败 5 次锁定 10 分钟
- 会话 Cookie：HttpOnly + SameSite=Lax + 24h 过期；配套 CSRF 令牌
- 修改密码后吊销全部会话，强制重新登录

## 冒烟测试

```powershell
# 1. 启动服务（全新数据目录），从控制台日志获取 admin 初始密码
# 2. 运行套件（可选 -SubUrl 传入订阅地址）
powershell -ExecutionPolicy Bypass -File scripts\smoke.ps1 -BaseUrl http://127.0.0.1:18084 -Password <初始密码> -DataDir <数据目录>
# 输出逐项 PASS/FAIL，最终 RESULT: PASS=N FAIL=0 表示全部通过
```

覆盖范围：认证与会话、节点 CRUD 与校验、订阅导入/刷新/删除、设置读写与非法值、分流规则 CRUD、延迟拨测、系统代理开关（注册表实测）、多节点故障转移（observatory 探测 + balancer）、SOCKS/HTTP 双入站出网、direct/block/proxy 三种路由标签、DNS 防污染查询路由、白名单模式默认直连、代理启停与注销。

## 许可证

GPL-3.0，见 [LICENSE](LICENSE)。

本项目的部分逻辑移植/借鉴自 luci-app-passwall（Copyright (C) 2018-2020 L-WRT Team, (C) 2021-2025 xiaorouji, (C) 2026 Openwrt-Passwall Organization）。
