sPROFFEs/GUEST
GitHub: sPROFFEs/GUEST
这是一个模块化的VPN与防火墙网关模板，用于安全隔离内部网络并提供细粒度访问控制。
Stars: 0 | Forks: 0
# 网关
一个模块化的 VPN + 防火墙网关，一次快照，永久克隆。每个实例都是一个小型的 Debian 12（或 Ubuntu Server 22.04/24.04）虚拟机，它：
- 终止一组开发对等体的 WireGuard 连接（通过 WGDashboard 管理）；
- 将内部局域网隔离在其后（Proxmox UI、实验虚拟机，任何您希望隔离的东西）；
- 执行基于每个对等体的访问控制列表（ACL），以便对等体只能访问您白名单中的目标（例如 `192.168.100.211:8006`，别无其他）；
- 可选地为特定对等体或特定内部主机通过 Tor 路由流量；
- 提供一个小型网络面板来管理以上所有功能，无需 SSH 登录。
设计和原理详见 [ARCHITECTURE.md](ARCHITECTURE.md)。本文档是运维指南。
## 1. 要求
- 一台 **虚拟机**（非 LXC）。KVM/Proxmox 虚拟机、ESXi 或任何拥有真正内核的环境。WireGuard、nftables fwmark 路由以及 `CAP_NET_ADMIN` 在非特权容器中无法正常工作。
- **Debian 12** (Bookworm) 最小化安装，或 **Ubuntu Server 22.04 / 24.04 / 26.04**。安装程序会自动检测网络后端（ifupdown 或 netplan）。
- 虚拟机连接 **两个网络接口**：
- `WAN` — 网关用于连接外部世界的网络。通常是 Proxmox 中的管理桥接网络；也可以是真实的互联网。
- `LAN-internal` — 一个 **无上行链路** 的桥接网络，Proxmox/实验虚拟机在此运行。隔离此桥接是使整个设置实现故障安全的关键：如果网关宕机，虚拟机无法逃逸。
- 安装时需要从 WAN 侧访问互联网（用于 apt、pip 和 git clone）。
硬件：1 个 vCPU、512 MB 内存、8 GB 磁盘空间绰绰有余。
## 2. 快速安装
```
# 在虚拟机上，以 root 权限或使用 sudo：
git clone gateway
cd gateway
cp gateway.toml.example gateway.toml
$EDITOR gateway.toml # see §4 below
sudo ./install.sh
```
就是这样。安装程序在面板模块结束时会打印一个一次性管理员密码——在终端滚动之前复制它。
如果中途出现任何问题，修复后重新运行即可。每个模块都是幂等的——它会从中断的地方继续。
## 3. 分模块安装
当您想一次验证一个部分，或跳过某个模块时很有用：
```
sudo ./install.sh --module 00-base
sudo ./install.sh --module 10-network
sudo ./install.sh --module 20-wireguard
sudo ./install.sh --module 30-tor # only if [modules].tor = true
sudo ./install.sh --module 40-panel
sudo ./install.sh --module 50-monitoring # only if [modules].monitoring = true
```
或者在不影响系统的情况下对所有内容进行语法检查：
```
sudo ./install.sh --dry-run
```
各模块功能说明：
| 模块 | 安装内容 | 影响范围 |
|-----------------|---------------------------------------------------------|--------------------------------------------|
| `00-base` | nftables, dnsmasq, sqlite3, python3, rsync, openssl… | sysctl, `/etc/nftables.conf` 骨架, `gateway` 用户 |
| `10-network` | LAN 静态 IP, dnsmasq DHCP/DNS, NAT 伪装 | `/etc/network/interfaces.d/`, `/etc/dnsmasq.d/` |
| `20-wireguard` | WireGuard 内核模块 + WGDashboard | `/etc/wireguard/wg0.conf`, `/opt/wgdashboard` |
| `30-tor` | 支持 TransPort + DNSPort 的 Tor，针对 `0x1` 的策略路由 | `/etc/tor/torrc.d/`, ip rule, 路由表 100 |
| `40-panel` | 自定义 FastAPI 面板 + 扫描器定时器 | `/opt/gateway-panel`, `/var/lib/gateway/`, sudoers |
| `50-monitoring` | node_exporter (wg0:9100) + vnstat | `/etc/default/prometheus-node-exporter` |
## 4. 配置 (`gateway.toml`)
```
[gateway]
name = "gw-isolated-01" # used in the cert CN, panel header, audit log
wan_iface = "ens18" # internet-facing or upstream NIC inside the VM
lan_iface = "ens19" # NIC connected to the isolated bridge
lan_cidr = "192.168.100.1/24" # the gateway's IP on the LAN (CIDR form)
[modules]
wireguard = true # WG + WGDashboard
tor = false # Tor TransPort + nft fwmark redirect
dhcp = true # dnsmasq on lan_iface
monitoring = false # node_exporter + vnstat
[wireguard]
listen_port = 51820
peer_cidr = "10.66.66.0/24" # tunnel subnet — peer IPs come from here
endpoint = "vpn.example:51820" # baked into peer config files
[dhcp]
range = "192.168.100.100,192.168.100.200,12h"
[panel]
bind_addr = "10.66.66.1" # see §5 (Access)
bind_port = 8443
wgd_bind_addr = "10.66.66.1"
wgd_bind_port = 10086
expose_on_wan = false # also open ports on wan_iface in nft
tls = false # serve panel over HTTPS with self-signed cert
[tor]
trans_port = 9040
dns_port = 5353
```
### 模块开关与配置值
`gateway.toml` 中的值在安装时和面板启动时被读取。分为两类：
- **网络标识**（接口、CIDR、端口）— 安装后不可变。更改它们需要重新运行相关模块。
- **模块开关** — 也可以在面板运行时切换。TOML 提供初始状态；面板将其自身状态写入 SQLite 数据库。
## 5. 访问面板
有两个网络用户界面：
- **自定义面板**（`bind_port`，默认 `8443`）— 管理对等体、ACL、主机、Tor 开关、应用更改。
- **WGDashboard**（`wgd_bind_port`，默认 `10086`）— 创建对等体、生成二维码、下载配置。
它们监听的位置取决于 `[panel].bind_addr` 和 `[panel].expose_on_wan`：
| 场景 | `bind_addr` | `expose_on_wan` | 可从何处访问 |
|------------------------------------------------|--------------|-----------------|-------------------------------------|
| 默认 — 仅现有对等体可管理 | `10.66.66.1` | `false` | 仅限 WireGuard 隧道内部 |
| WAN 是内部管理 LAN，您希望方便访问 | `0.0.0.0` | `true` | WireGuard 隧道和 WAN 侧均可 |
| WAN 是公共互联网，禁止从外部管理 | `10.66.66.1` | `false` | 仅限 WireGuard 隧道内部 — 请保持此设置 |
**切勿**在公共互联网 WAN 上将 `expose_on_wan` 设为 `true`，除非您完全理解后果 — 在公共互联网上 `tls = false` 会在传输中暴露密码。
### 引导问题 — 鸡生蛋问题
默认配置（仅限 WireGuard）是安全的，但会产生引导问题：您需要一个 WireGuard 对等体才能访问 WGDashboard，但创建对等体正是 WGDashboard 的功能。有两种解决方法：
**A. SSH 本地端口转发**（推荐，零额外暴露）：
```
ssh -L 10086:10.66.66.1:10086 -L 8443:10.66.66.1:8443 root@
# 然后在浏览器中打开 http://localhost:10086
```
在那里创建您的对等体，将配置导入您的 WireGuard 客户端，然后断开 SSH 连接，之后使用隧道。
**B. 临时将 `expose_on_wan` 设为 `true`**，安装您的对等体，将其改回，重新运行模块 20：
```
$EDITOR gateway.toml # expose_on_wan = true
sudo ./install.sh --module 20-wireguard
# 在 WGDashboard 的 http://:10086 地址创建 peer
$EDITOR gateway.toml # expose_on_wan = false
sudo ./install.sh --module 20-wireguard
```
## 6. TLS
当您设置 `[panel].tls = true` 时，模块 40 会：
1. 使用 `openssl req -x509 -nodes -days 3650` 创建 `/etc/gateway/tls/panel.{crt,key}`。CN = `[gateway].name`，SAN 包含 `[panel].bind_addr`。
2. 在 `gateway-panel` systemd 单元中添加 `--ssl-keyfile` 和 `--ssl-certfile`。
3. 自动将会话 cookie 切换为 `Secure`（面板会检测请求方案）。
浏览器在首次访问时会发出警告 — 接受例外，或将证书导入您的信任存储。要轮换证书，删除这两个文件并重新运行模块 40：
```
sudo rm /etc/gateway/tls/panel.{crt,key}
sudo ./install.sh --module 40-panel
```
WGDashboard 在其设置页面有自己的 TLS 开关 — 如果您也想在 `:10086` 上启用 HTTPS，请在那里打开它。
## 7. 日常流程
1. 在 WGDashboard 中 **添加一个对等体**，将二维码/配置文件交给开发者。
2. **打开自定义面板**，进入 *对等体*，找到新对等体，为其添加标签。
3. **点击 ACL 下的 "编辑"**，添加他们被允许访问的目标。Proxmox UI 的示例：
- `dst_cidr`: `192.168.100.211/32`
- `proto`: `tcp`
- `dport`: `8006`
- `action`: `accept`
4. 当黄色的 "待处理更改" 横幅出现时，**点击 "应用"**。
就是这样。如果没有明确的 ACL，对等体**无法**访问局域网上的任何资源 — `panel_forward` 链以隐式丢弃结束。
要临时使对等体离线，点击其所在行的 *阻止: 是*。要通过 Tor 发送其流量，点击 *Tor: 开*（并确保 Tor 模块已安装并启用）。
## 8. 内部主机（LAN 侧）
扫描器每 30 秒运行一次（`gateway-scanner.timer`），并通过 `ip neigh` 在 `lan_iface` 上检测到的任何内容填充 *主机* 选项卡。从面板中您可以：
- **固定 IP**（切换 `dhcp` → `fixed`，编辑 IP）— 在应用时，会将一行 `dhcp-host=` 写入 `/etc/dnsmasq.d/gateway-hosts.conf`。
- **阻止** 一个主机 — 丢弃来自该 IP 的所有转发流量（它仍然可以与网关本身通信以进行 DHCP/DNS）。
- **Tor 路由** 一个主机 — 来自该 IP 的每个数据包都会被标记 `fwmark 0x1` 并重定向到 Tor 的 TransPort。UDP 会被丢弃（Tor 不支持；您需要处理基于 TCP 的 DNS 或接受 Tor 的 DNSPort 作为解析器）。
为了使 Tor 路由可靠，主机必须不能伪造自己的 IP。通过 MAC 进行 DHCP 固定绑定是轻量级保护；更严格的隔离需要在桥接上使用 ebtables。
## 9. 复制到其他网关
这种设计的全部意义 — 克隆虚拟机，更改一个文件：
```
# 在 Proxmox 主机上：
qm clone --name gw-iso-02
# 在新虚拟机上：
$EDITOR /home//gateway/gateway.toml # change name, lan_cidr, modules…
sudo ./install.sh # re-runs modules with new config
```
使用场景：
- **相同模板，无 WireGuard**（纯隔离网关）：在重新运行前设置 `[modules].wireguard = false`。面板会隐藏对等体/ACL 用户界面，不启动 WireGuard 服务，也没有 WGDashboard。
- **相同模板，为某个主机启用 Tor**：启用 `[modules].tor = true`，安装，然后在面板中为特定内部主机的 MAC 切换 Tor 开关。
- **多层隔离**：克隆两次，为每个克隆体分配其自己的 `lan_cidr` 和独立的 WireGuard 对等体池 — 无重叠，无共享状态。
## 10. 常见问题
**`00-base` 期间出现 `sysctl: permission denied on key kernel.pid_max`。**
您在 LXC 容器内，而非虚拟机。请迁移到真正的虚拟机。整个技术栈都假设使用真正的内核。
**`10-network` 期间出现 `ifup: unknown interface ensXY`。**
`gateway.toml` 中的接口名称与虚拟机实际拥有的接口名称不匹配。使用 `ip -br link show` 进行检查。
**`pip ... Failed to resolve files.pythonhosted.org`。**
虚拟机中的 DNS 损坏。检查 `/etc/resolv.conf` — 如果它指向 `127.0.0.53`，请改为写入公共 DNS：
```
sudo rm /etc/resolv.conf
echo -e "nameserver 1.1.1.1\nnameserver 9.9.9.9" | sudo tee /etc/resolv.conf
```
然后重新运行模块 40。
**面板返回 502 / 拒绝来自 WAN 的连接。**
检查两个层面：
- `systemctl status gateway-panel` — 服务是否正在运行？
- `ss -ltnp | grep <端口>` — 是否绑定在正确的地址上？如果 `bind_addr = 10.66.66.1`，您将无法从 WAN 侧访问它；将 `bind_addr` 改为 `0.0.0.0` 并将 `expose_on_wan` 设为 `true`，然后重新运行模块 20 和 40。
**应用失败，显示 nft 验证错误。**
面板在应用前会创建快照，失败时会回滚。在用户界面的 *审计* 中查看错误详情，或使用 `journalctl -u gateway-panel`。最常见原因是 ACL 规则中存在语法错误的 CIDR。
**Tor 开关无效。**
未安装模块 30。检查 `[modules].tor = true` 并重新运行 `--module 30-tor`。同时确保 Tor 本身运行正常：`systemctl status tor`。
**丢失管理员密码。**
从虚拟机重置它（`cd` 目录很重要 — `python -m app.cli` 只有在从安装目录调用时才能找到 `app` 包）：
```
sudo sqlite3 /var/lib/gateway/db.sqlite \
"DELETE FROM users WHERE username='admin'"
cd /opt/gateway-panel && sudo runuser -u gateway -- \
/opt/gateway-panel/venv/bin/python -m app.cli create-admin \
--db /var/lib/gateway/db.sqlite \
--username admin --password 'NEW_PASSWORD_HERE'
```
## 11. 卸载
```
sudo ./uninstall.sh # remove configs, services, state — keep packages
sudo ./uninstall.sh --purge # also `apt purge` the packages we installed
```
## 12. *尚未包含* 的功能
我在 v0 中故意省略了这些功能 — 如果您需要，请提出来：
- 面板的 TOTP / 2FA（目前仅有密码）。
- OIDC / SSO 集成。
- 将 `db.sqlite` 远程备份到另一台主机。
- 针对虚拟机内 IP 欺骗的每主机 Tor 路由保护（需要在桥接上使用 ebtables）。
- Alembic 风格的数据库迁移 — 目前只有一个 `0001_init.sql`。
- IPv6（防火墙规则是 `inet` 族的，但未生成 IPv6 NAT/转发规则）。
该架构旨在吸收所有这些功能 — 它们是现有设计中的插槽，而非重新设计。
标签：ACL管理, Debian, nftables, Proxmox, Tor集成, VPN网关, Web管理面板, WireGuard, 安全网关, 开发对等点, 快照克隆, 服务器部署, 模块化, 生成式AI安全, 网络安全, 网络隔离, 虚拟化, 虚拟机, 访问控制列表, 逆向工具, 防火墙, 隐私保护