Installation zh - FrankoonG/hy2scale GitHub Wiki

🌐 English | 中文 | 한국어

安装

HY2 SCALE 以单个 Docker 容器运行。所有配置通过 Web UI 管理 — 无需编辑配置文件。

系统要求

  • Docker（任何支持 Docker 的 Linux 主机）
  • NET_ADMIN 权限（用于 VPN 协议和路由规则）
  • --network host（L2TP/IPsec 和 IKEv2 必需）

快速开始（Full 模式 — 包含路由规则在内的全部功能）

docker run -d --name hy2scale \
  --network host --privileged \
  -v hy2scale-data:/data \
  --restart unless-stopped \
  frankoong/hy2scale:latest

打开 http://<主机IP>:5565/scale/ — 默认登录：admin / admin。

警告： 首次登录后请立即通过 设置 → 系统 修改默认密码。

Bridge 模式（VPN + 代理，不含路由规则）

当 --network host 不可用时，改为使用显式端口映射。L2TP / IKEv2 / WireGuard 在兼容模式下均可正常工作，仅 Rules 引擎不可用。

docker run -d --name hy2scale \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -p 5565:5565/tcp -p 5565:5565/udp \
  -p 500:500/udp -p 4500:4500/udp -p 1701:1701/udp -p 51820:51820/udp \
  -v hy2scale-data:/data \
  --restart unless-stopped \
  frankoong/hy2scale:latest

侧边栏版本标识显示自动检测到的运行模式：Normal、Bridge、Compat 或 Limited — 详见 设置。

Docker Compose

services:
  hy2scale:
    image: frankoong/hy2scale:latest
    container_name: hy2scale
    restart: unless-stopped
    network_mode: host
    privileged: true
    volumes:
      - hy2scale-data:/data

volumes:
  hy2scale-data:

Bridge 模式：

services:
  hy2scale:
    image: frankoong/hy2scale:latest
    container_name: hy2scale
    restart: unless-stopped
    cap_add: [NET_ADMIN, NET_RAW]
    devices: ["/dev/net/tun"]
    ports:
      - "5565:5565/tcp"
      - "5565:5565/udp"
      - "500:500/udp"
      - "4500:4500/udp"
      - "1701:1701/udp"
      - "51820:51820/udp"
    volumes:
      - hy2scale-data:/data

volumes:
  hy2scale-data:

端口

端口 协议 服务
5565 TCP + UDP Hysteria 2 服务器 + Web UI
1701 UDP L2TP
500 UDP IKEv2/IPsec (IKE)
4500 UDP IKEv2/IPsec (NAT-T)
51820 UDP WireGuard（可配置）

使用 --network host 时，所有端口自动可用。使用端口映射时，需逐个映射每个端口：

docker run -d --name hy2scale \
  --cap-add NET_ADMIN \
  -p 5565:5565/tcp -p 5565:5565/udp \
  -p 1701:1701/udp \
  -p 500:500/udp -p 4500:4500/udp \
  -p 51820:51820/udp \
  -v hy2scale-data:/data \
  frankoong/hy2scale:latest

注意： L2TP 和 IKEv2 需要 --network host 才能工作。仅使用端口映射并不足够，因为 Docker 无法对 IPsec ESP 报文进行 NAT。

环境变量

变量 默认值 说明
DEBUG false 启用详细日志（iptables 检测、权限检查、数据包流向、strongSwan 详细输出）

无需其他环境变量。所有配置通过 Web UI 管理，持久化存储在 /data/config.yaml 中。

数据目录

所有状态持久化到 /data 卷：

/data/
├── node-id          # 唯一节点标识（8 位十六进制字符）
├── config.yaml      # 配置文件（自动生成，原子写入）
└── tls/             # TLS 证书（PEM 格式）
    ├── default.crt
    ├── default.key
    └── default.name

注意： 首次启动时会自动生成自签名 TLS 证书。

命令行参数

二进制支持以下参数（通过 Docker 运行时通常不需要）：

参数 默认值 说明
-api 0.0.0.0:5565 API / UI 监听地址
-base-path /scale URL 基础路径
-data /data 持久化数据目录

从源码构建

git clone https://github.com/FrankoonG/hy2scale.git
cd hy2scale
docker build -t hy2scale .

镜像（约 73MB）包含：

  • Go 二进制（静态编译）
  • strongSwan 5.8.4（源码编译）
  • xl2tpd、pppd、iptables-legacy
  • Alpine 3.19 基础镜像

升级

docker pull frankoong/hy2scale:latest
docker stop hy2scale
docker rm hy2scale
# 使用相同的 docker run 命令重新启动

配置数据保存在数据卷中，不受升级影响。

网络模式对比

功能 --network host 端口映射
网状中继 ✅ ✅
Web UI ✅ ✅
SOCKS5 ✅ ✅
Shadowsocks ✅ ✅
WireGuard ✅ ✅
L2TP/IPsec ✅ ✅（兼容模式）
IKEv2/IPsec ✅ ✅（兼容模式）
路由规则 ✅ ❌
运行模式标识 Normal Bridge / Compat / Limited
⚠️ **GitHub.com Fallback** ⚠️