TunnelMC ?
通过 ngrok、cloudflared 或 playit.gg 将任何本地端口暴露到互联网——无需进行端口分配。包含一个完整的基于浏览器的管理仪表板。
TunnelMC 是一个 Bukkit/Spigot/Paper 插件,它会自动下载并管理 ngrok、cloudflared 和/或 playit.gg,为任何本地端口创建隧道,并在隧道就绪时将公共 URL 广播到控制台和所有在线 OP(管理员)。
? 1.5.0 新功能:可靠性与安全性修复
这是一次基于系统性审计的维护版本,同时增加了一项功能以跟上 ngrok 的变更:
- 新增:ngrok 隧道现在可以使用保留/静态域名。 ngrok 已将域名选择移至其自己的仪表板(“Choose your URL”)——在那里选择一个,将其放入新的
hostname 字段中,它会随 --url 一起传递。留空则每次启动时随机生成域名,与之前相同。
- 修复:编辑隧道可能会静默清除其保存的 authtoken/cfToken。 编辑表单正确地从不向浏览器发送密钥,但保存不相关的更改(如切换自动启动)会用空白值覆盖存储的令牌,导致隧道在下一次启动时失效。保存时空白秘密字段现在会保留现有值;只有实际的新值才会覆盖它。
- 修复:隧道名称中包含撇号会导致该隧道卡片上的每个操作按钮失效。 Start/Stop/Restart/Delete/Copy 按钮现在对包含
'、" 或 \ 的名称、URL 和 ID 进行了正确的转义处理。
- 修复:将隧道重命名为已存在的隧道名称会导致旧隧道成为孤儿进程。 旧隧道的进程仍在运行,但没有任何东西跟踪它,并且它完全从
config.yml 中消失。现在如果尝试重命名到已使用的名称,将被拒绝。
- 修复:在启动后立即点击停止可能会导致未跟踪的隧道进程继续运行, 并且在稍后即使你明确停止了它,它在仪表板上也会重新显示为“运行状态”。启动/停止的竞争条件不再允许输掉竞争的启动进程接管其进程。
- 修复:playit.gg 的“Try Again”按钮在被拒绝或取消链接尝试后的长达约 11 分钟内,可能会返回一个过期的会话声明, 而不是发布一个新的代码。
- 修复:未经清理的隧道名称可能将 ngrok 的每隧道配置文件写入预期目录之外。 现在隧道名称被限制为字母、数字、
_ 和 -。
- 修复:编辑任何隧道可能会静默清除保存的 ngrok 保留域名至空白, 因为持久化路径在每次保存时都会从头重建所有隧道的条目。
- 修复:格式错误的仪表板 API 请求可能会返回一个空的、无法解释的服务器错误, 日志中没有任何内容。现在不良请求会获得清晰的 JSON 错误,并且真实原因会在服务器端记录。
- 改进:错误日志记录 对于 playit/ngrok/cloudflared 下载和连接失败的情况,现在始终包含异常类型(如果没有消息,则包含抛出位置),而不仅仅是有时打印裸 "null"。
✨ 功能特性
? 三种隧道提供商 — ngrok、cloudflared 和 playit.gg,可针对每个隧道进行配置。自由混合使用。
? UDP + 静态地址 (playit.gg) — 这是此处唯一提供稳定 UDP 地址的提供商,专为 Bedrock/Geyser 设计。也可提供仅 TCP 以及组合 TCP+UDP 隧道(需要 playit premium)。
? 多个 ngrok 账户 — 每个 ngrok 隧道都有自己独立的 authtoken(v3 必需)。同时运行不同的账户。
? 零设置快速隧道 — Cloudflared 快速隧道开箱即用,无需账户。
? 自定义域名 — Cloudflared 命名隧道通过 Cloudflare Zero Trust 为您提供持久的自定义主机名。
?️ Web 仪表板 — 完整的管理界面。直接从浏览器实时创建/编辑/删除隧道、下载二进制文件、更改设置。
⚡ 自动下载 — 检测操作系统和 CPU 架构,在首次使用时下载正确的二进制文件。之后永久缓存。
? 即时 URL 广播 — 一旦隧道就绪,URL 就会发送到控制台和所有在线 OP。
? 完整的命令支持 — /tunnel 命令支持所有功能的 Tab 补全。
? 自动重启与崩溃循环保护 — 隧道在失败后自动重启。如果在短时间内失败次数过多,则停止重试。
? 健康检查 — ngrok 隧道获得 API 级别的检查;cloudflared 隧道获得进程存活检查。
? Pterodactyl 兼容 — 隧道是出站连接,因此永远不需要额外的端口分配。
? 安装
- 将
TunnelMC.jar 放入 plugins/ 文件夹
- 启动服务器 —— TunnelMC 会生成配置文件,如果未配置任何隧道,则通过 cloudflared 自动暴露仪表板
- 在浏览器中打开打印出的 URL
- 从仪表板配置隧道,或编辑
config.yml 并运行 /tunnel reload
⚙️ 配置
auto-start: false
default-region: "us" # ngrok 隧道的备用区域
notify-ops: true
auto-restart: true
restart-delay-seconds: 10
max-restarts: 5
crash-window-seconds: 60
health-check-interval-seconds: 30
dashboard:
enabled: true
port: 8090
bind-address: "127.0.0.1"
password: "changeme"
auto-expose-on-first-run: true
tunnels:
# Cloudflared 快速隧道 —— 无需账户,随机 URL,仅限 HTTP
- name: "dashboard"
port: 8090
provider: "cloudflared"
auto-start: true
# 具有自己账户令牌的 ngrok HTTP 隧道
- name: "noderunner"
port: 8080
provider: "ngrok"
protocol: "http"
region: "us"
authtoken: "your-ngrok-token-here"
# 来自不同账户的 ngrok TCP 隧道
- name: "gameserver"
port: 25565
provider: "ngrok"
protocol: "tcp"
region: "eu"
authtoken: "another-account-token"
# 具有保留/静态域名的 ngrok 隧道(从 ngrok 仪表板中选择)
- name: "stable-mc"
port: 25565
provider: "ngrok"
protocol: "tcp"
authtoken: "your-ngrok-token-here"
hostname: "your-reserved-domain.ngrok-free.dev"
Cloudflared 命名隧道 — 持久化自定义域名
- name: "mc"
port: 25565
provider: "cloudflared"
token: "your-cloudflare-zero-trust-token"
hostname: "mc.yourdomain.com"
playit.gg — 请先在仪表板(Settings 选项卡)中链接账户;Bedrock 仅支持 UDP
- name: "bedrock"
port: 19132
provider: "playit"
playit-type: "minecraft-bedrock"
auto-start: true
---
## ? 命令与权限
**权限:** `tunnelmc.admin` *(默认:OP)*
| 命令 | 描述 |
|---|---|
| `/tunnel start [name]` | 启动所有或指定名称的隧道 |
| `/tunnel stop [name]` | 停止所有或指定名称的隧道 |
| `/tunnel restart [name]` | 重启所有或指定名称的隧道 |
| `/tunnel url [name]` | 显示公共 URL |
| `/tunnel status` | 显示所有隧道状态 |
| `/tunnel download ngrok` | 下载 ngrok 二进制文件 |
| `/tunnel download cloudflared` | 下载 cloudflared 二进制文件 |
| `/tunnel download playit` | 下载 playit 二进制文件 |
| `/tunnel playit claim` | 打印用于链接 playit.gg 账户的链接 |
| `/tunnel playit status` | 显示 playit.gg 链接状态 |
| `/tunnel playit unlink` | 取消链接 playit.gg 并停止其隧道 |
| `/tunnel dashboard` | 显示仪表板端口信息 |
| `/tunnel reload` | 重新加载配置并重启隧道 |
---
## ? 服务商对比
| | ngrok | Cloudflared Quick | Cloudflared Named | playit.gg |
|---|:---:|:---:|:---:|:---:|
| 需要账户 | ✅ 免费 | ❌ 无需 | ✅ 免费 | ✅ 免费 |
| HTTP 隧道 | ✅ | ✅ | ✅ | ✅ (通过 TCP) |
| TCP 隧道 | ✅ | ❌ | ✅ | ✅ (Java 预设免费;自定义 TCP 需高级版) |
| UDP 隧道 | ❌ | ❌ | ❌ | ✅ (免费 — Bedrock 预设及自定义 UDP) |
| 持久化 URL | 仅限付费 | ❌ | ✅ | ✅ |
| 多账户支持 | ✅ (每隧道) | — | — | — |
| macOS 构建 | ✅ | ✅ | ✅ | ⚠️ TunnelMC 编译版 |
---
## ⚠️ 免费计划说明
**ngrok 免费版:** 同时只能运行一个活动隧道,每次重启时 URL 随机变化,有带宽限制。所有 ngrok v3 隧道均需 Authtoken。使用每隧道 authtoken 可以利用多个免费账户来绕过单隧道限制。
**Cloudflared quick tunnels:** 仅支持 HTTP,使用随机的 `*.trycloudflare.com` URL,无带宽限制。
**Cloudflared named tunnels:** 需要 Cloudflare 账户(免费),支持任意协议,提供持久化的自定义域名。
---
## ? Pterodactyl
无需额外分配端口 — 隧道均为出站连接。仪表板也绑定在本地,因此不需要分配端口。
**下载缓慢?** 如果手动安装耗时超过 30 秒,TunnelMC 会发出警告并提供手动安装步骤。将二进制文件放置在 `plugins/TunnelMC/ngrok/ngrok`、`plugins/TunnelMC/cloudflared/cloudflared` 或 `plugins/TunnelMC/playit/playitd`,然后重启服务器即可。
---
## ? 兼容性
| | |
|---|---|
| **平台** | Bukkit, Spigot, Paper, Purpur |
| **Minecraft** | 1.21.x – 26.2.x |
| **Java** | 25+ (使用 Java 25 编译) |
| **操作系统** | Linux, macOS, Windows |
| **架构** | x64, ARM64 |
> ⚠️ **macOS + playit.gg:** ngrok 和 cloudflared 提供官方 macOS 构建版本,可正常运行。playit.gg 不提供 — 仪表板的 Settings 选项卡提供了由 TunnelMC 编译的版本(SHA-256 已验证)或自行编译的说明。
---
## ? 相关插件
**[NodeRunner](https://modrinth.com/plugin/noderunner)** — 在 Minecraft 服务器内运行 Node.js Discord 机器人。
**[PyRunner](https://modrinth.com/plugin/pyrunner)** — 在 Minecraft 服务器内运行 Python Discord 机器人。
*TunnelMC 与这两款插件完美搭配 — 为端口 8080 建立 cloudflared quick tunnel 即可让它们的仪表板公开访问,且无需任何端口分配。*
---
*由 [Spider](https://github.com/Spider2742) 开发*
TunnelMC ?
Expose any local port to the internet via ngrok, cloudflared, or playit.gg — no port allocations needed. Includes a full browser-based management dashboard.
TunnelMC is a Bukkit/Spigot/Paper plugin that automatically downloads and manages ngrok, cloudflared, and/or playit.gg, creates tunnels for any local port, and broadcasts the public URL to console and online OPs the moment the tunnel is ready.
? What's New in 1.5.0: Reliability & Security Fixes
A maintenance release from a systematic audit, plus one addition to keep pace with an ngrok change:
- Added: ngrok tunnels can now use a reserved/static domain. ngrok moved domain selection to their own dashboard ("Choose your URL") — pick one there, drop it into the new
hostname field, and it's passed along with --url. Leave it blank for a random domain each start, same as before.
- Fixed: editing a tunnel could silently wipe its saved authtoken/cfToken. The edit form correctly never sends secrets back to the browser, but saving an unrelated change (like toggling auto-start) was overwriting the stored token with blank — breaking the tunnel on its next start. Blank secret fields on save now keep the existing value; only an actual new value overwrites it.
- Fixed: a tunnel name containing an apostrophe broke every action button on that tunnel's card. Start/Stop/Restart/Delete/Copy buttons are now correctly escaped for names, URLs, and IDs containing
', ", or \.
- Fixed: renaming a tunnel to an existing tunnel's name silently orphaned the old one. The old tunnel's process kept running with nothing left tracking it, and it disappeared from
config.yml entirely. Renaming to a name already in use is now rejected instead.
- Fixed: clicking Stop immediately after Start could leave an untracked tunnel process running, and later resurrect it as "running" in the dashboard even though you'd explicitly stopped it. A start/stop race no longer lets a launch that lost the race adopt its process.
- Fixed: playit.gg's "Try Again" button could hand back a dead claim session for up to ~11 minutes after a rejected or cancelled link attempt, instead of issuing a fresh code.
- Fixed: an unsanitized tunnel name could write ngrok's per-tunnel config file outside the intended directory. Tunnel names are now restricted to letters, numbers,
_, and -.
- Fixed: editing any tunnel could silently wipe a saved ngrok reserved domain back to blank, since the persistence path rebuilt every tunnel's entry from scratch on every save.
- Fixed: a malformed dashboard API request could return an empty, unexplained server error with nothing in the log. Bad requests now get a clear JSON error and the real cause is logged server-side.
- Improved: error logging for playit/ngrok/cloudflared download and connection failures now always includes the exception type (and throw site when there's no message), instead of sometimes printing a bare "null".
✨ Features
? Three Tunnel Providers — ngrok, cloudflared, and playit.gg, configurable per tunnel. Mix them freely.
? UDP + Static Addresses (playit.gg) — the only provider here with a stable UDP address, built for Bedrock/Geyser. TCP-only and combined TCP+UDP tunnels are also available (require playit premium).
? Multiple ngrok Accounts — Each ngrok tunnel has its own authtoken (required for v3). Run different accounts simultaneously.
? Zero-Setup Quick Tunnels — Cloudflared quick tunnels work out of the box with no account.
? Custom Domains — Cloudflared named tunnels give you persistent custom hostnames via Cloudflare Zero Trust.
?️ Web Dashboard — Full management UI. Create/edit/delete tunnels live, download binaries, change settings — all from a browser.
⚡ Auto-Download — Detects OS and CPU arch, downloads the right binary on first use. Cached forever after.
? Instant URL Broadcast — URL goes to console and all online OPs the moment the tunnel is ready.
? Full Command Support — /tunnel with tab completion for everything.
? Auto-Restart & Crash Loop Protection — Tunnels restart after failure. Stops retrying if it fails too many times in a short window.
? Health Checks — ngrok tunnels get API-level checks; cloudflared tunnels get process-alive checks.
? Pterodactyl Compatible — Tunnels are outbound connections, so no extra port allocations are ever needed.
? Installation
- Drop
TunnelMC.jar into plugins/
- Start the server — TunnelMC generates config and auto-exposes the dashboard via cloudflared if no tunnels are configured
- Open the printed URL in your browser
- Configure tunnels from the dashboard, or edit
config.yml and run /tunnel reload
⚙️ Configuration
auto-start: false
default-region: "us" # fallback region for ngrok tunnels
notify-ops: true
auto-restart: true
restart-delay-seconds: 10
max-restarts: 5
crash-window-seconds: 60
health-check-interval-seconds: 30
dashboard:
enabled: true
port: 8090
bind-address: "127.0.0.1"
password: "changeme"
auto-expose-on-first-run: true
tunnels:
# Cloudflared quick tunnel — no account, random URL, HTTP only
- name: "dashboard"
port: 8090
provider: "cloudflared"
auto-start: true
# ngrok HTTP tunnel with its own account token
- name: "noderunner"
port: 8080
provider: "ngrok"
protocol: "http"
region: "us"
authtoken: "your-ngrok-token-here"
# ngrok TCP tunnel from a different account
- name: "gameserver"
port: 25565
provider: "ngrok"
protocol: "tcp"
region: "eu"
authtoken: "another-account-token"
# ngrok tunnel with a reserved/static domain (picked from ngrok's dashboard)
- name: "stable-mc"
port: 25565
provider: "ngrok"
protocol: "tcp"
authtoken: "your-ngrok-token-here"
hostname: "your-reserved-domain.ngrok-free.dev"
# Cloudflared named tunnel — persistent custom domain
- name: "mc"
port: 25565
provider: "cloudflared"
token: "your-cloudflare-zero-trust-token"
hostname: "mc.yourdomain.com"
# playit.gg — link an account from the dashboard first (Settings tab); Bedrock is UDP-only
- name: "bedrock"
port: 19132
provider: "playit"
playit-type: "minecraft-bedrock"
auto-start: true
? Commands & Permissions
Permission: tunnelmc.admin (default: OP)
| Command |
Description |
/tunnel start [name] |
Start all or a specific tunnel |
/tunnel stop [name] |
Stop all or a specific tunnel |
/tunnel restart [name] |
Restart all or a specific tunnel |
/tunnel url [name] |
Show public URL(s) |
/tunnel status |
Show all tunnel status |
/tunnel download ngrok |
Download ngrok binary |
/tunnel download cloudflared |
Download cloudflared binary |
/tunnel download playit |
Download playit binary |
/tunnel playit claim |
Print a link to link a playit.gg account |
/tunnel playit status |
Show playit.gg link status |
/tunnel playit unlink |
Unlink playit.gg and stop its tunnels |
/tunnel dashboard |
Show dashboard port info |
/tunnel reload |
Reload config and restart tunnels |
? Provider Comparison
|
ngrok |
Cloudflared Quick |
Cloudflared Named |
playit.gg |
| Account required |
✅ free |
❌ none |
✅ free |
✅ free |
| HTTP tunnels |
✅ |
✅ |
✅ |
✅ (via TCP) |
| TCP tunnels |
✅ |
❌ |
✅ |
✅ (Java preset free; custom TCP-only needs premium) |
| UDP tunnels |
❌ |
❌ |
❌ |
✅ (free — Bedrock preset and custom UDP) |
| Persistent URL |
paid only |
❌ |
✅ |
✅ |
| Multiple accounts |
✅ per-tunnel |
— |
— |
— |
| macOS build |
✅ |
✅ |
✅ |
⚠️ TunnelMC-built |
⚠️ Free Plan Notes
ngrok free: one active tunnel at a time, random URL on each restart, bandwidth limits. Authtoken is required for all ngrok v3 tunnels. Per-tunnel authtokens let you use multiple free accounts to work around the one-tunnel limit.
Cloudflared quick tunnels: HTTP only, random *.trycloudflare.com URL, no bandwidth limits.
Cloudflared named tunnels: require a Cloudflare account (free), any protocol, persistent custom domain.
? Pterodactyl
No extra port allocations needed — tunnels are outbound connections only. The dashboard also binds locally and doesn't need an allocated port.
Slow download? TunnelMC will warn after 30 seconds with manual install steps. Place the binary at plugins/TunnelMC/ngrok/ngrok, plugins/TunnelMC/cloudflared/cloudflared, or plugins/TunnelMC/playit/playitd and restart.
? Compatibility
|
|
| Platforms |
Bukkit, Spigot, Paper, Purpur |
| Minecraft |
1.21.x – 26.2.x |
| Java |
25+ (compiled with Java 25) |
| OS |
Linux, macOS, Windows |
| Arch |
x64, ARM64 |
⚠️ macOS + playit.gg: ngrok and cloudflared ship official macOS builds and work normally. playit.gg does not — the dashboard's Settings tab offers a TunnelMC-compiled build (SHA-256 verified) or self-build instructions.
? Related
NodeRunner — Run a Node.js Discord bot inside your Minecraft server.
PyRunner — Run a Python Discord bot inside your Minecraft server.
TunnelMC pairs perfectly with both — a cloudflared quick tunnel to port 8080 makes their dashboards publicly accessible with zero port allocation.
Developed by Spider~~~~
评论 0
登录后参与评分
还没有评论,来抢沙发吧