ARAS-Workspace/phantom-wg

## 什么是 Phantom-WG Modern？ ***Phantom-WG*** 是一个模块化工具，可让你在自己的服务器上设置和管理 WireGuard VPN 基础设施。除了基本的 VPN 管理之外，它还提供抗审查连接、多层加密和高级隐私场景。 ***Phantom-WG Modern*** 是这一愿景的容器原生实现。所有组件均在 Docker 内运行，并与主机系统隔离： - **用户态 WireGuard** — 通过 Go FFI 桥接实现容器范围的 TUN 设备。不需要内核模块，不会触碰主机的网络命名空间。 - **nftables netlink FFI** — Rust 后端直接与内核通信。没有子进程调用，防火墙规则以编程方式管理。 - **SQLite 状态持久化** — 所有状态都存储在 SQLite 数据库中。崩溃后重启守护进程即可——内核状态将从数据库重建。 - **双栈 IPv6** — 即使主机没有 IPv6，也会在容器内分配一个 IPv6 子网，并且流量通过隧道传输。 - **容器隔离** — `NET_ADMIN` + `NET_RAW` 就足够了。WireGuard 接口存在于容器命名空间内。不使用 `SYS_ADMIN`、`privileged` 或 `host` 网络模式等削弱主机安全性的配置。 ## 拓扑 三个容器，通过 Docker Compose 管理。管理流量通过 TLS + JWT 身份验证，WireGuard 流量直接到达守护进程。 ``` flowchart A[Internet] -->|"HTTPS :443"| B[nginx] B --> C[auth-service] C <-->|"UDS"| D[daemon] A -->|"WireGuard :51820/udp"| D ``` | 组件 | 角色 | |------------------|-----------------------------------------------------------------------------------------------------| | **nginx** | TLS 终止，React SPA（静态编译文件），反向代理配置 | | **auth-service** | 综合身份验证系统，通过 UDS 连接到守护进程的 API 代理 | | **daemon** | 用户态 WireGuard (Go FFI)，nftables 防火墙 (Rust FFI)，客户端和隧道管理，数据库 | ## 主要特性 ### 桥接架构 守护进程通过两个原生桥接执行系统级操作。Python 管理业务逻辑，桥接直接与内核通信。 ``` graph D["Daemon (Python)"] -->|"ctypes FFI"| WG["wireguard-go-bridge (Go)"] D -->|"ctypes FFI"| FW["firewall-bridge (Rust)"] WG --> TUN["TUN device"] FW --> NFT["nftables kernel"] ``` | 桥接 | 语言 | 职责 | |-------------------------|--------|-----------------------------------------------| | **wireguard-go-bridge** | Go | 用户态 WireGuard，TUN 设备，IPC 状态持久化 | | **firewall-bridge** | Rust | nftables 规则组，策略路由，预设系统 | ### 多跳出口路由 你可以定义出口隧道，通过外部的 WireGuard VPN 服务器路由流量。同时支持 IPv4 和 IPv6 隧道。 ``` flowchart LR C[Client] -->|"WireGuard"| M["wg_main"] -->|"forward + masquerade"| E["wg_exit"] --> X[Exit Server] ``` ### IPv6 双栈 跨越所有层的 IPv6 支持——防火墙规则、策略路由、伪装和多跳预设均以 `family: 10` (AF_INET6) 运行。即使主机上没有 IPv6 地址，也可以从容器内承载 IPv6 隧道流量。 ### 崩溃恢复 当服务启动时，内核状态（nftables 规则、路由策略）将从 SQLite 状态数据库重建。意外关机后不会丢失数据。 ## Auth-Service（身份验证和安全代理层） 对守护进程的访问受独立的身份验证服务保护。Auth-service 在与守护进程分离的容器中运行，并通过 UDS 代理 API 请求。 ### 身份验证 | 功能 | 详情 | |------------------|-----------------------------------------------------------------------------------| | 会话管理 | JWT (Ed25519 签名) | | 多因素身份验证 | TOTP (RFC 6238)，备份代码访问 | | 密码存储 | Argon2id 哈希 | | 暴力破解保护 | 基于 IP 的速率限制（可配置的滑动窗口和基于尝试的配置） | | 审计日志 | 所有身份验证和 API 代理事件按用户记录（登录、登出、尝试失败、MFA） | ### RBAC（基于角色的访问控制） | 权限 | Superadmin | Admin | |-------------------------------------------------|:----------:|:-----:| | 守护进程管理（客户端、多跳、防火墙、备份） | ✓ | ✓ | | 修改自己的密码 | ✓ | ✓ | | 配置自己的 TOTP | ✓ | ✓ | | 创建 / 删除管理员账户 | ✓ | — | | 修改任何用户的密码 | ✓ | — | | 禁用其他用户的 TOTP | ✓ | — | | 查看审计日志 | ✓ | — | 这两个角色都可以在相同的权限级别下管理守护进程——所有通过守护进程执行的操作（如客户端创建、多跳、防火墙和备份）都是共享的。区别仅在于 auth-service 端：superadmin 具有用户管理和审计权限，而 admin 仅具有操作访问权限。Auth-service 是一个独立的组件——自定义不会影响守护进程的结构。守护进程不知道此服务的存在，仅处理网络操作。如果你想隔离不同的用户组，可以不通过 auth-service 进行授权，而是通过更改配置在同一主机上设置多租户结构。这样，你就可以通过成倍增加端口和网络配置来创建独立的实例，同时确保网络和用户访问两端的隔离。这些操作配置适用于希望将现有结构调整为适合自己场景的高级用户。 ## 安装 **前提条件：** Docker Engine 20.10+，Docker Compose v2，bash。 ``` curl -sSL get.phantom.tc | bash ``` ### 配置 ``` cd phantom-wg # 首次设置 ./tools/prod.sh setup # 或者使用自定义 subnet（参见 https://www.phantom.tc/docs/architecture/terazi） # ./tools/prod.sh setup --terazi-ipv4-subnet=10.9.0.0/24 # Endpoint 配置 IPV4=$(curl -4 -sSL https://get.phantom.tc/ip) IPV6=$(curl -6 -sSL https://get.phantom.tc/ip) sed -i "s/^WIREGUARD_ENDPOINT_V4=.*/WIREGUARD_ENDPOINT_V4=${IPV4}/" .env.daemon sed -i "s/^WIREGUARD_ENDPOINT_V6=.*/WIREGUARD_ENDPOINT_V6=${IPV6}/" .env.daemon # 启动 ./tools/prod.sh up ``` **访问：** - Dashboard: `https://` - WireGuard: UDP 端口 `51820` - 管理员密码: `cat container-data/secrets/production/.admin_password` ## 环境变量 配置通过安装期间从模板创建的 env 文件进行管理： | 文件 | 服务 | |--------------------|--------------| | `.env.daemon` | daemon | | `.env.auth-service`| auth-service | 有关所有可用选项，请参见 `.example` 文件。 ## 管理 `./tools/prod.sh` 提供了一个便捷的管理工具。 | 命令 | 描述 | |-------------------------------------|----------------------------------------| | `setup` | 完整安装 | | `setup --terazi-ipv4-subnet=SUBNET` | 使用自定义子网安装（例如 `10.9.0.0/24`） | | `up` | 启动 | | `down` | 停止 | | `restart [service]` | 重启（所有或特定服务） | | `build` | 构建镜像 | | `rebuild` | 从头构建镜像（无缓存） | | `update` | 更新（git pull + 重启） | | `compose lock` | 永久锁定 docker-compose.yml | | `compose unlock` | 解锁 docker-compose.yml | | `logs [service]` | 日志跟踪（所有或特定服务） | | `status` | Docker Compose 状态 | | `certbot ` | 获取 Let's Encrypt TLS 证书 | | `show-versions` | 组件版本（守护进程、第三方包） | | `shell [service]` | Shell（默认：daemon） | | `exec ` | 执行命令 | | `hard-reset` | 删除所有数据 | ### 安装 `setup` 命令将在首次安装期间创建所有必需的组件： 1. 从 `.example` 模板创建 `.env.daemon` 和 `.env.auth-service` 文件。 2. 生成 WireGuard 服务器密钥对。（Curve25519 — `wg_private_key`, `wg_public_key`） 3. Auth-Service 引导周期： - 生成 Ed25519 签名密钥对。（`auth_signing_key`, `auth_verify_key`） - 创建身份验证数据库。（`auth.db` — 用户、会话、TOTP、审计日志） - 创建管理员账户。（32 个字符的随机密码，使用 Argon2id 哈希加密） 4. 为 nginx 生成自签名的 TLS 证书。（`tls_cert`, `tls_key`） 所有这些操作都在容器内进行——主机上不需要安装额外的依赖项或工具。 Terazi 需要一个基础子网来创建 IP 池。默认值为 `10.8.0.0/24`，可以在安装时使用 `--terazi-ipv4-subnet` 参数进行自定义。该值仅在创建 `wallet.db` 时使用——一旦数据库存在，子网就会存储在其中，不再需要该参数。有关详细信息，请参见 [Terazi 文档](https://www.phantom.tc/docs/architecture/terazi)。 ### 更新机制 守护进程和 auth-service 的源代码以只读方式挂载到容器中（`phantom_daemon:/app/phantom_daemon:ro`，`services/auth-service:/app/auth-service:ro`）。Dockerfile 仅提供系统依赖（Python、runtime 包）——应用程序代码不会被构建到镜像中。这使得： - **快速更新**：`git pull` + `restart` 即可，代码更改无需重建镜像 - **快速回滚**：`git checkout ` + `restart` 可立即回滚 - **构建独立性**：代码更改不会触发容器构建周期 ``` ./tools/prod.sh update # git pull + restart ``` #### Compose 锁定 如果你修改了 `docker-compose.yml`（端口、卷、环境），更新可能会覆盖你的更改。Compose lock 可保护此文件免受 git 更新的影响： ``` ./tools/prod.sh compose lock # Permanently lock ./tools/prod.sh update # docker-compose.yml is preserved ./tools/prod.sh compose unlock # Release the lock ``` #### 重建 当系统依赖发生变化（Dockerfile、requirements.txt）时，需要重新构建镜像： ``` ./tools/prod.sh rebuild ./tools/prod.sh up ``` #### Let's Encrypt（可选） 默认的自签名证书可以替换为 Let's Encrypt 证书。使用 HTTP-01 standalone 验证——域名必须具有指向服务器的 A 记录，并且端口 80 必须可用。 ``` ./tools/prod.sh certbot ./tools/prod.sh restart nginx ``` 证书文件将写入 `container-data/secrets/production/tls_cert` 和 `tls_key`。续期是幂等的——在证书即将过期时再次运行相同的命令即可。 ## 架构 有关详细的架构文档，请访问 [www.phantom.tc/docs/architecture](https://www.phantom.tc/docs/architecture)。 | 资源 | URL | |----------------|---------------------------------------------------------------------------------------------------| | 网站 | [www.phantom.tc](https://www.phantom.tc) | | 架构 | [www.phantom.tc/docs/architecture](https://www.phantom.tc/docs/architecture) | | API 参考 | [www.phantom.tc/docs/api](https://www.phantom.tc/docs/api) | | 安装指南 | [安装指南](SETUP) | ## 开发 积极开发在 [`dev/daemon`](https://github.com/ARAS-Workspace/phantom-wg/tree/dev/daemon) 分支上进行。`main` 分支仅包含可用于生产环境的版本。 ## Phantom-Frontmatter 放置在 Phantom-WG Modern 服务器前面的 WSS/TLS 隧道层。接受 TCP 443 上的 wstunnel 连接，并将流量转发到后端服务器。网络观察者只能看到标准的 HTTPS 流量。  ### 要求 Phantom-Frontmatter 安装在与 Phantom-WG Modern 后端独立的专用裸机服务器上。 | 要求 | 详情 | |-----------------|--------------------------------------------------| | 操作系统 | Debian 12 / 13, Ubuntu 22.04 / 24.04 | | 访问权限 | Root (sudo) | | 后端 | 可访问的 Phantom-WG Modern 服务器（UDP 51820） | ### 安装 最新发布版本：[frontmatter-v1.0.0](https://github.com/ARAS-Workspace/phantom-wg/releases/tag/frontmatter-v1.0.0) ``` wget https://github.com/ARAS-Workspace/phantom-wg/releases/download/frontmatter-v1.0.0/phantom-wg-frontmatter-v1.0.0.zip unzip phantom-wg-frontmatter-v1.0.0.zip cd phantom-wg-frontmatter-v1.0.0 sudo ./frontmatter-install.sh ``` ### 配置 ``` # 定义 backend server (IPv4 或 IPv6) sudo frontmatter-api setup init backend= # 启动 data path sudo frontmatter-api ghost start # 验证 sudo frontmatter-api ghost status # Client 配置块 sudo frontmatter-api ghost client_config # Client 连接命令（standalone wstunnel） sudo frontmatter-api ghost client_command ``` ### Let's Encrypt（可选） ``` sudo frontmatter-api ghost stop sudo frontmatter-certbot front.example.com sudo frontmatter-api ghost start ``` ### 探索 | 资源 | 链接 | |------------------|---------------------------------------------------------------------------------------------------| | 安装指南 | [安装指南](https://github.com/ARAS-Workspace/phantom-wg/blob/frontmatter/SETUP) | | 架构 | [架构](https://github.com/ARAS-Workspace/phantom-wg/blob/frontmatter/ARCHITECTURE) | | 架构 (TR) | [架构_TR](https://github.com/ARAS-Workspace/phantom-wg/blob/frontmatter/ARCHITECTURE_TR) | | 源代码 | [GitHub](https://github.com/ARAS-Workspace/phantom-wg/tree/frontmatter) | ## 商标声明 WireGuard® 是 Jason A. Donenfeld 的注册商标。 本项目不隶属于 Jason A. Donenfeld、ZX2C4 或 Edge Security，也未获得其授权、认可或与之有任何官方联系。 ## 许可证 版权所有 (c 2025 Riza Emre ARAS 根据 [AGPL-3.0](LICENSE) 获得许可。有关依赖项许可证，请参见 [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES)。

标签：Docker, VPN, WireGuard, 可视化界面, 安全防御评估, 抗审查, 日志审计, 版权保护, 网络安全, 请求拦截, 逆向工具, 隐私保护