darkver8/tunnel-control repository overview

⁠Tunnel Control

Source repository: https://github.com/qwernot/tunnel-control⁠

Docker image: darkver8/tunnel-control:latest

Tunnel Control is an all-in-one tunnel control panel that embeds FRP server and NPS server-side capabilities into a single tunnel-control process and a single Docker container.

The goal is to keep only one control panel:

• One Web login entry
• Admin and normal user roles
• Unified user port pools, domain pools, and tunnel limits
• One place to create FRP and NPS tunnels
• Normal users can only view their own resources, tunnels, and client configs
• Native FRP/NPS dashboards are disabled by default

⁠Image

docker pull darkver8/tunnel-control:latest

The container runs one main process:

tunnel-control

This process starts:

• Unified Web control panel
• Embedded FRP server
• Embedded NPS bridge
• NPS HTTP/HTTPS proxy

⁠Quick Start

Linux servers should use host networking because FRP/NPS need to listen on dynamic user ports.

mkdir -p tunnel-control
cd tunnel-control
cat > compose.yml <<'EOF'
services:
  tunnel-stack:
    image: darkver8/tunnel-control:latest
    container_name: tunnel-stack
    restart: unless-stopped
    network_mode: host
    environment:
      PUBLIC_ADDR: your-server-ip-or-domain
      ADMIN_USER: admin
      ADMIN_PASSWORD: change-this-password
      FRP_BIND_PORT: 17000
      FRP_HTTP_PORT: 9081
      FRP_HTTPS_PORT: 9444
      NPS_BRIDGE_PORT: 18024
      NPS_TLS_BRIDGE_PORT: 18025
      NPS_HTTP_PORT: 9080
      NPS_HTTPS_PORT: 9443
      USER_PORT_RANGE: 10000-20000
    volumes:
      - ./data:/app/data
EOF

docker compose up -d

Open the panel:

http://your-server-ip:8088

On first start, if there is no enabled admin user, the container creates one from ADMIN_USER and ADMIN_PASSWORD.

⁠Default Ports

8088/tcp        Web control panel
17000/tcp       FRP client access port
18024/tcp       NPS bridge
18025/tcp       NPS TLS bridge
9080/tcp        NPS HTTP proxy
9443/tcp        NPS HTTPS proxy
9081/tcp        FRP HTTP vhost
9444/tcp        FRP HTTPS vhost
10000-20000/tcp User TCP/SOCKS5 tunnel port range
10000-20000/udp User UDP tunnel port range

FRP dashboard and NPS dashboard are disabled by default:

FRP_DASHBOARD_PORT=0
NPS_WEB_PORT=0

⁠Features

• Single-container deployment
• Unified admin/user control panel
• User-scoped fixed port pools
• User-scoped domain pools for HTTP/HTTPS tunnels
• FRP and NPS tunnel creation from one backend
• Generated frpc.toml and npc command per user
• Client online/offline status display
• Runtime logs page for admins
• Listener self-check and resource usage overview
• Docker upgrade script with data backup and health check

⁠Tunnel Types

TCP, UDP, and SOCKS5 use port pools:

• A remote port is required
• The remote port must be inside the user's port pool
• The same protocol and remote port can be used by only one tunnel
• TCP/SOCKS5 and UDP may use the same numeric port

HTTP and HTTPS use domain pools:

• A domain is required
• A remote port is not required
• The domain must be inside the user's domain pool
• Exact domains are supported, for example app.example.com
• Wildcard pools are supported, for example *.example.com
• FRP also validates domain ownership server-side, so users cannot bind other users' domains by editing frpc.toml

HTTP entry ports are separate for FRP and NPS:

NPS HTTP:  http://domain:9080
NPS HTTPS: https://domain:9443
FRP HTTP:  http://domain:9081
FRP HTTPS: https://domain:9444

In production, map 80/443 to these ports with firewall rules, port forwarding, or a reverse proxy.

⁠Data Directory

Persistent data is stored under /app/data; mount it to the host:

data/
  control/tunnel-control.json
  frp/frps-users.json
  nps/conf/
  export/

Back up the data directory to preserve users, tunnels, and engine config.

⁠Common Commands

docker compose ps
docker compose logs -f tunnel-stack
docker compose restart tunnel-stack
docker compose down

Health check:

curl http://127.0.0.1:8088/healthz

⁠Build From Source

go test ./...
go build -o tunnel-control ./cmd/tunnel-control
docker build -t darkver8/tunnel-control:latest .