Skip to content

zsio/netsgo

BranchesTags

Repository files navigation

NetsGo Logo

NetsGo

内网穿透与节点管理平台
内置 Web 控制台 · 单端口接入 · 单文件部署

CI Release Docker

Go React Single Binary Platform License

NetsGo 是一个开箱即用的内网穿透与节点管理平台。它将 Web 控制台、REST API、客户端接入和底层网络隧道整合进一个单文件二进制中，让部署更简单、接入更统一、运维更省心。你可以用它远程访问内网服务，也可以统一管理分散在各处的远程节点。

目录

界面预览

NetsGo Web 控制台总览
Web 控制台总览

NetsGo 客户端详情与隧道管理
客户端详情与隧道管理

快速开始

下文示例默认在下载目录中直接执行 ./netsgo。已通过 netsgo install 安装或已加入系统 PATH 的，可以省略 ./。

1. 启动服务端

推荐方式：Linux Service（systemd）

长期运行最省事的方案。下载 netsgo 二进制后执行：

sudo ./netsgo install

按交互提示选择 Server，并填入管理员账号、访问地址等信息。安装完成后：

# 已经安装到系统中, 可以直接使用 netsgo 命令了
sudo netsgo manage

manage 提供查看状态、启停、看日志、卸载等入口。

数据目录默认位于 /var/lib/netsgo。

方式二：Docker Compose 示例

点击展开 docker-compose.yml 示例 
services:
  netsgo-server:
    image: ghcr.io/zsio/netsgo:latest
    restart: unless-stopped
    ports:
      - "9527:9527"     # Web/API/控制通道/数据通道/HTTP 隧道入口
      # 如需 TCP/UDP tunnel，请额外映射对应 remote port，例如：
      # - "10000:10000/tcp"
      # - "10001:10001/udp"
    environment:
      NETSGO_DATA_DIR: "/var/lib/netsgo"
      NETSGO_INIT_ADMIN_USERNAME: "admin"
      NETSGO_INIT_ADMIN_PASSWORD: "<change-me-strong-password>"
      NETSGO_INIT_SERVER_ADDR: "https://your-netsgo-domain.com"
    volumes:
      - netsgo-data:/var/lib/netsgo

volumes:
  netsgo-data:

Docker 镜像默认执行 netsgo server。这里通过 NETSGO_DATA_DIR=/var/lib/netsgo 明确把数据目录指向挂载卷。

服务端默认不启用内置 TLS，适合放在反向代理后作为 HTTP upstream。如果你不走反向代理、准备直接对外暴露 NetsGo，请设置 NETSGO_TLS_MODE=auto 或 NETSGO_TLS_MODE=custom。如果在反向代理后需要信任 X-Forwarded-* 头，请额外设置 NETSGO_TLS_MODE=off 和精确的 NETSGO_TRUSTED_PROXIES。

方式三：直接运行（仅试用/调试）

点击展开 CLI 直跑命令

首次启动必须提供初始化管理员与服务地址参数：

./netsgo server \
  --port 9527 \
  --init-admin-username admin \
  --init-admin-password '<change-me-strong-password>' \
  --init-server-addr https://your-netsgo-domain.com

请务必把示例中的 <change-me-strong-password> 替换为高强度密码，不要直接用于生产环境。初始化完成后，同一数据目录后续启动可省略 init-* 参数。

2. 登录 Web 面板并创建 Client Key

  1. 浏览器访问服务地址（如 https://your-netsgo-domain.com）。
  2. 用初始化时设置的管理员账号登录。
  3. 进入“客户端管理”，创建一个 client，复制生成的 Client Key（格式类似 sk-...）。

3. 启动客户端

推荐方式：Linux Service（systemd）

# 客户端也是这样进入交互菜单进行安装
sudo ./netsgo install

按交互提示选择 Client，并填入 Web 面板或 Server 安装完成提示中显示的服务地址（通常是 http:// 或 https://）与 Client Key。

注意：Client 会自动从服务地址派生内部 WebSocket 控制/数据通道；通常不需要手动把地址改成 ws:// 或 wss://。旧的 WebSocket 形式仍兼容。

之后用 sudo netsgo manage 查看状态和日志。

方式二：Docker Compose 示例

点击展开 docker-compose.yml 示例 
services:
  netsgo-client:
    image: ghcr.io/zsio/netsgo:latest
    restart: unless-stopped
    environment:
      NETSGO_DATA_DIR: "/var/lib/netsgo"
      NETSGO_SERVER: "https://your-netsgo-domain.com"
      NETSGO_KEY: "<your-client-key>"
    volumes:
      - netsgo-client-data:/var/lib/netsgo
    command:
      - "client"

volumes:
  netsgo-client-data:

Docker 镜像默认执行 netsgo server，所以客户端容器需要把 command 改成 client。如果 tunnel 的本地目标服务也在同一个 Compose 网络中，可以在 Web 面板里把目标地址填成对应服务名；如果目标服务在宿主机上，可以使用 host.docker.internal。

方式三：直接运行（仅试用/调试）

点击展开 CLI 直跑命令 
./netsgo client \
  --data-dir ~/.local/state/netsgo \
  --server https://your-netsgo-domain.com \
  --key <your-client-key>

直接运行 netsgo client 时，推荐显式指定 --data-dir，并填写 http(s) 服务地址；旧的 ws(s) 输入仍兼容并会自动规范化：

  • http://host:port
  • https://host:port
  • ws://host:port
  • wss://host:port

4. 创建 Tunnel 并验证

client 在线后，在 Web 面板里直接添加、修改或删除 tunnel，无需再登录 client 机器改配置。

创建完成后，直接从公网入口访问或连接对应 tunnel，确认流量已经正确转发。

为什么用 NetsGo

如果你只是想尽快把服务端跑起来、把内网机器连上来、然后开始建隧道，NetsGo 的设计重点就是这四件事：

  • 一个二进制就能跑：./netsgo server 启服务端，./netsgo client 连远程节点。
  • 一个端口就够：Web 控制台、控制通道和数据通道共用同一个入口，防火墙和反向代理只配一处就够。（TCP/UDP 隧道按需使用额外端口。）
  • 部署路径清晰：容器或直接运行都可以；Linux 长驻场景可用 netsgo install + netsgo manage。
  • 默认就带控制台：连上客户端后，直接在 Web 面板里管理节点、查看状态、配置隧道。

生产部署建议

生产环境推荐把 NetsGo 放在 Nginx 或 Caddy 反向代理之后。只需要注意两点：

  • 开启 WebSocket Upgrade
  • 把超时时间调大，避免长连接被代理提前断开

Nginx 示例

点击展开 
server {
    listen 80;
    server_name your-netsgo-domain.com;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Sec-WebSocket-Protocol $http_sec_websocket_protocol;
        proxy_buffering off;
        proxy_cache off;
        proxy_pass http://127.0.0.1:9527;
    }
}

Caddy 示例

点击展开 
your-netsgo-domain.com {
    reverse_proxy 127.0.0.1:9527 {
        header_up Host {host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

附录

常用命令参考

netsgo server

除“首次初始化”外，下面示例都默认你使用的是已初始化过的数据目录。

# 首次初始化
netsgo server \
  --init-admin-username admin \
  --init-admin-password '<change-me-strong-password>' \
  --init-server-addr https://panel.example.com

# 已初始化数据目录的后续启动
netsgo server --data-dir ~/.local/state/netsgo

# 自动生成自签 TLS 证书
netsgo server --tls-mode auto

# 使用自定义证书
netsgo server --tls-mode custom --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# 由反向代理处理 TLS
netsgo server --tls-mode off --trusted-proxies 127.0.0.1/32,10.0.0.0/8

netsgo client

# 连接远端 HTTPS 服务端
netsgo client \
  --data-dir ~/.local/state/netsgo \
  --server https://1.2.3.4:9527 \
  --key mykey

# 仅用于测试：跳过 TLS 校验
netsgo client \
  --data-dir ~/.local/state/netsgo \
  --server https://1.2.3.4:9527 \
  --key mykey \
  --tls-skip-verify

旧的 WebSocket 形式仍兼容，会自动规范化为 http(s) 服务地址；首次使用建议优先复制 Web 面板展示的服务地址。

--data-dir 是 NetsGo 的数据根目录。直接运行时默认是 ~/.local/state/netsgo；作为 systemd 服务运行时默认是 /var/lib/netsgo。Client 状态会写入该目录下的 client/，进程锁会写入 locks/。

netsgo install / netsgo manage

sudo netsgo install   # 交互式安装为 systemd 服务
sudo netsgo manage    # 查看状态、启停、日志、卸载
常用环境变量

所有命令都支持 NETSGO_ 前缀环境变量。

服务端

环境变量 对应参数 说明
NETSGO_PORT --port 监听端口，默认 9527
NETSGO_DATA_DIR --data-dir 数据根目录；直接运行默认 ~/.local/state/netsgo，systemd 服务默认 /var/lib/netsgo
NETSGO_SERVER_ADDR --server-addr 强制指定对外访问地址
NETSGO_INIT_ADMIN_USERNAME --init-admin-username 首次初始化管理员用户名
NETSGO_INIT_ADMIN_PASSWORD --init-admin-password 首次初始化管理员密码
NETSGO_INIT_SERVER_ADDR --init-server-addr 首次初始化写入的管理面地址

客户端

环境变量 对应参数 说明
NETSGO_SERVER --server 服务地址，例如 https://netsgo.example.com
NETSGO_KEY --key client 鉴权 key
NETSGO_DATA_DIR --data-dir 数据根目录；直接运行默认 ~/.local/state/netsgo，systemd 服务默认 /var/lib/netsgo

和常见方案的区别

下面对比基于这些工具的常见使用方式，具体能力以各项目当前版本为准。NetsGo 的定位不是替代所有网络工具，而是提供一个更偏“自托管 Web 控制台 + 节点管理 + tunnel 统一配置”的选择。

方案 主要定位 自托管控制面 Web 管理面板 节点 / tunnel 统一管理 配置方式 适合场景
NetsGo 内网穿透 + 节点管理平台 ✅ ✅ ✅ Web 控制台 自托管部署、统一管理多节点与 tunnel
frp 成熟高性能内网穿透工具 ✅ 监控面板 部分 配置文件为主 熟悉配置文件、追求成熟穿透能力
ngrok 托管式开发调试隧道 ❌ ✅ 部分 Web / CLI 快速临时暴露本地服务
cloudflared Cloudflare Tunnel / Zero Trust 接入 ❌ ✅ 部分 Cloudflare 控制台 / CLI 已使用 Cloudflare 生态的公网接入
rathole 轻量级反向代理隧道 ✅ ❌ ❌ 配置文件 轻量、简单、偏底层的隧道转发

架构概览

NetsGo Server 使用单端口承载 Web 控制台、REST API、SSE、控制通道和数据通道；Client 主动连接 Server，并通过 WebSocket + yamux 承载数据面流量。

flowchart LR
  Admin[Admin Browser] -->|Web UI / REST API / SSE| Server[NetsGo Server<br/>single listener]
  Client[NetsGo Client] -->|Control WebSocket| Server
  Client -->|Data WebSocket + yamux| Server
  User[External User] -->|HTTP / TCP / UDP tunnel| Server
  Server -->|Multiplexed tunnel traffic| Client
  Client -->|Local TCP / UDP| Local[Internal Services]
Loading

Web 面板、API、SSE、控制通道和数据通道共用同一个服务端入口；TCP / UDP tunnel 的公网入口端口按 tunnel 配置按需开放。

License

Apache-2.0

About

Self-hosted tunneling and node management platform / 开箱即用的内网穿透与节点管理平台

Topics

golang nat-traversal self-hosted ngrok frp tunneling port-forwarding web-dashboard intranet-penetration single-binary

Resources

Readme

License

Apache-2.0 license
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

19 tags

Packages

 
 
 

Contributors

Languages