host1syan/homeip

•Updated 3 months ago

Image

299

host1syan/homeip repository overview

⁠host1syan/homeip — Proxy-Lite: Free Residential IP Proxy Controller

一款开箱即用的免费住宅 IP 代理控制器，基于 VPN Gate + OpenVPN + WARP，自动获取全球免费节点，主备双活自动切换。

A ready-to-use residential IP proxy controller, powered by VPN Gate + OpenVPN + WARP. Auto-harvests free global VPN nodes with dual active-standby tunnel failover.

⁠🇨🇳 中文说明

⁠简介

Proxy-Lite 是一个本地集成版的免费住宅 IP 代理控制器。它将 VPN Gate 全球免费 OpenVPN 节点自动采集、主备双活隧道调度、IP 质量检测、Web 管理面板全部整合到一个 Docker 容器中，无需注册任何第三方服务，一行命令即可启动。

⁠核心功能

功能	说明
🔄 主备双活	双 OpenVPN 隧道自动切换，主通道故障秒级切换至备用通道
🌍 全球节点池	自动从 VPN Gate 获取 90+ 国家免费 OpenVPN 节点
🔍 双重 IP 质检	机房 IP 检测 + YouTube 连通性验证，自动踢线不合格节点
🖥️ Web 管理面板	可视化配置、节点状态监控、实时日志、IP 深度质检
🛡️ WARP 伪装（可选）	系统出站流量走 Cloudflare WARP，隐藏 VPS 真实 IP
🔌 SOCKS5/HTTP 双协议	同时支持 SOCKS5 和 HTTP 代理，兼容各种客户端

⁠数据流架构

 用户代理流量路径（出站 IP = VPN 节点 IP）：
 ┌──────┐     ┌──────────────┐     ┌──────────┐     ┌──────────┐     ┌────────┐
 │ 用户  │ ──▶ │ proxy:7920   │ ──▶ │ tun_main │ ──▶ │ OpenVPN  │ ──▶ │ 目标网站│
 │      │     │ SO_BINDTODEVICE│     │ (虚拟网卡)│     │ 隧道     │     │        │
 └──────┘     └──────────────┘     └──────────┘     └──────────┘     └────────┘

 系统流量路径（VPN 服务器看到的是 Cloudflare IP）：
 ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────────┐
 │ 系统进程  │ ──▶ │  WARP    │ ──▶ │Cloudflare│ ──▶ │ VPN Gate API │
 │ OpenVPN  │     │ (默认出口)│     │  边缘    │     │ VPN 节点     │
 └──────────┘     └──────────┘     └──────────┘     └──────────────┘

关键设计：用户代理流量直接绑定 tun_main 网卡进入 OpenVPN 隧道，不经过 WARP，出站 IP 为 VPN 节点 IP。系统自身流量（获取节点列表、OpenVPN 建连握手）走 WARP，保护 VPS 真实 IP。

⁠快速开始

⁠方式一：docker run（推荐）

docker run -d \
  --name homeip \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --device=/dev/net/tun \
  --sysctl net.ipv4.conf.all.rp_filter=2 \
  --sysctl net.ipv4.conf.default.rp_filter=2 \
  -p 7920:7920 \
  -p 2055:2055 \
  -e ADMIN_PASSWORD="admin888" \
  --restart unless-stopped \
  host1syan/homeip

⁠方式二：docker compose

创建 docker-compose.yml：

services:
  homeip:
    image: host1syan/homeip
    container_name: homeip
    cap_add:
      - NET_ADMIN
      - NET_RAW
    devices:
      - /dev/net/tun
    sysctls:
      - net.ipv4.conf.all.rp_filter=2
      - net.ipv4.conf.default.rp_filter=2
    environment:
      ENABLE_WARP: "false"
      ADMIN_PASSWORD: "admin888"
    ports:
      - "7920:7920"
      - "2055:2055"
    restart: unless-stopped

启动：

docker compose up -d

⁠使用指南

⁠访问管理面板

http://你的VPS-IP:2055

默认密码：admin888（可通过环境变量 ADMIN_PASSWORD 修改）

⁠测试代理

# SOCKS5
curl -x socks5://proxy:888888@你的VPS-IP:7920 https://api.ipify.org

# HTTP
curl -x http://proxy:888888@你的VPS-IP:7920 https://api.ipify.org

⁠端口说明

端口	用途
7920	代理端口（SOCKS5 / HTTP）
2055	Web 管理面板

⁠代理连接格式

socks5://proxy:888888@你的VPS-IP:7920
http://proxy:888888@你的VPS-IP:7920

代理端口可在 Web 面板中动态修改，修改后容器自动重启。

⁠Web 管理面板功能

功能	说明
🌐 国家代码库	预设 95+ 国家代码，动态从 VPN Gate 获取可用国家
📋 策略下发	输入目标国家代码（如 `JP`、`US`、`GB`）
🔄 端口修改	修改代理端口，自动重启生效
🔨 强制换 IP	一键销毁当前通道，获取新的住宅 IP
📊 节点监控	实时查看双通道状态（ACTIVE / STANDBY）
✅ IP 质检报告	集成 IP 深度质检，显示评分、场景类型、ASN、风险检测
📝 日志查看	实时查看引擎运行日志

⁠环境变量

变量	默认值	说明
`ENABLE_WARP`	`false`	设置为 `true` 启用 WARP 流量伪装
`ADMIN_PASSWORD`	`admin888`	Web 管理面板登录密码

⁠启用 WARP（可选）

当 VPS 网络受限或需要隐藏 VPS IP 时，可启用 WARP。启用后，系统获取 VPN 节点和 OpenVPN 建连的连接走 Cloudflare WARP，VPN 服务器看到的是 Cloudflare IP。

docker run -d \
  --name homeip \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --device=/dev/net/tun \
  --sysctl net.ipv4.conf.all.rp_filter=2 \
  --sysctl net.ipv4.conf.default.rp_filter=2 \
  -p 7920:7920 \
  -p 2055:2055 \
  -e ENABLE_WARP=true \
  -e ADMIN_PASSWORD="admin888" \
  --restart unless-stopped \
  host1syan/homeip

WARP 注意事项：

需要内核 WireGuard 支持（Docker 宿主机需加载 wireguard 模块）
WARP 仅影响系统出站流量，不影响代理用户流量
面板中会显示 WARP 连接状态，支持一键重连

⁠查看日志

docker logs -f homeip

⁠故障排查

⁠容器不断重启

通常是缺少权限，确保包含以下参数：

--cap-add=NET_ADMIN
--cap-add=NET_RAW
--device=/dev/net/tun

⁠无法获取 IP / 节点池为空

启动后等待 1-2 分钟让节点池预热
检查日志：docker logs homeip
如果 VPS 网络受限，启用 WARP：-e ENABLE_WARP=true
确保 VPS 能访问 https://www.vpngate.net

⁠面板打不开

# 检查容器是否运行
docker ps

# 查看端口映射
docker port homeip

# 检查 VPS 防火墙是否放行 2055 端口

⁠清空数据重新开始

docker rm -f homeip
docker run ...  # 重新运行

⁠许可证

MIT

⁠🇬🇧 English

⁠Overview

Proxy-Lite is an all-in-one Docker-based residential IP proxy controller. It automatically harvests free OpenVPN nodes from VPN Gate (90+ countries), manages dual active-standby tunnels, performs IP quality checks, and provides a built-in Web management dashboard — all within a single container. No third-party registration required.

⁠Features

Feature	Description
🔄 Active-Standby Failover	Dual OpenVPN tunnels with sub-second automatic failover
🌍 Global Node Pool	Auto-harvests free OpenVPN nodes from VPN Gate (90+ countries)
🔍 Dual IP Quality Check	Datacenter IP detection + YouTube connectivity validation
🖥️ Web Dashboard	Visual configuration, node monitoring, real-time logs
🛡️ WARP Masquerade (opt.)	System outbound traffic routed through Cloudflare WARP
🔌 SOCKS5/HTTP Dual Protocol	Both SOCKS5 and HTTP proxy support

⁠Traffic Architecture

User Proxy Traffic (exit IP = VPN node IP):
 ┌──────┐     ┌──────────────┐     ┌──────────┐     ┌──────────┐     ┌────────┐
 │ User  │ ──▶ │ proxy:7920   │ ──▶ │ tun_main │ ──▶ │ OpenVPN  │ ──▶ │ Target │
 │       │     │ SO_BINDTODEVICE│     │ (virtual)│     │ Tunnel   │     │ Website│
 └──────┘     └──────────────┘     └──────────┘     └──────────┘     └────────┘

System Traffic (VPN servers see Cloudflare IP):
 ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────────┐
 │ Processes │ ──▶ │  WARP    │ ──▶ │Cloudflare│ ──▶ │ VPN Gate API │
 │ OpenVPN  │     │ (default)│     │   Edge   │     │ VPN Nodes    │
 └──────────┘     └──────────┘     └──────────┘     └──────────────┘

Key design: User proxy traffic binds directly to tun_main via SO_BINDTODEVICE, entering the OpenVPN tunnel without touching WARP. Exit IP is the VPN node IP. System traffic (node harvesting, OpenVPN handshake) uses WARP to hide the VPS IP.

⁠Quick Start

⁠docker run

docker run -d \
  --name homeip \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --device=/dev/net/tun \
  --sysctl net.ipv4.conf.all.rp_filter=2 \
  --sysctl net.ipv4.conf.default.rp_filter=2 \
  -p 7920:7920 \
  -p 2055:2055 \
  -e ADMIN_PASSWORD="admin888" \
  --restart unless-stopped \
  host1syan/homeip

⁠docker compose

services:
  homeip:
    image: host1syan/homeip
    container_name: homeip
    cap_add:
      - NET_ADMIN
      - NET_RAW
    devices:
      - /dev/net/tun
    sysctls:
      - net.ipv4.conf.all.rp_filter=2
      - net.ipv4.conf.default.rp_filter=2
    environment:
      ENABLE_WARP: "false"
      ADMIN_PASSWORD: "admin888"
    ports:
      - "7920:7920"
      - "2055:2055"
    restart: unless-stopped

docker compose up -d

⁠Usage

⁠Access Dashboard

http://your-vps-ip:2055

Default password: admin888 (configurable via ADMIN_PASSWORD env)

⁠Test Proxy

# SOCKS5
curl -x socks5://proxy:888888@your-vps-ip:7920 https://api.ipify.org

# HTTP
curl -x http://proxy:888888@your-vps-ip:7920 https://api.ipify.org

⁠Ports

Port	Purpose
7920	Proxy (SOCKS5 / HTTP)
2055	Web Dashboard

⁠Proxy Connection Format

socks5://proxy:888888@your-vps-ip:7920
http://proxy:888888@your-vps-ip:7920

⁠Environment Variables

Variable	Default	Description
`ENABLE_WARP`	`false`	Set to `true` to enable WARP traffic masquerade
`ADMIN_PASSWORD`	`admin888`	Web dashboard login password

⁠WARP (Optional)

When your VPS network is restricted or you need to hide the VPS IP, enable WARP. System traffic (node harvesting, OpenVPN connections) will be routed through Cloudflare WARP, so VPN servers see a Cloudflare IP instead of your VPS IP.

Notes:

Requires kernel WireGuard support (load wireguard module on host)
WARP only affects system outbound traffic, NOT user proxy traffic
Dashboard shows WARP connection status with one-click reconnect

⁠Troubleshooting

⁠Container Keeps Restarting

Ensure these flags are present:

--cap-add=NET_ADMIN
--cap-add=NET_RAW
--device=/dev/net/tun

⁠No Nodes / No IP

Wait 1-2 minutes for the node pool to warm up
Check logs: docker logs homeip
If VPS network is restricted, enable WARP: -e ENABLE_WARP=true
Ensure VPS can reach https://www.vpngate.net

⁠Dashboard Not Accessible

docker ps
docker port homeip
# Check firewall rules for port 2055

⁠Reset Everything

docker rm -f homeip
docker run ...  # Start fresh

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:a055d3662…

Size

349.1 MB

Last updated

3 months ago

docker pull host1syan/homeip