PyRunner ?
将你的 Python Discord 机器人直接运行在 Minecraft 服务器旁——无需外部托管、无需 VPS、无需繁琐配置。
PyRunner 是一个 Paper 插件,它将一个 Python 进程(通常是 Discord 机器人)作为 Minecraft 服务器的子进程进行管理。它自动处理所有事务:下载 Python、从 requirements.txt 安装依赖、崩溃后重启、将日志流式传输到实时 Web 仪表板,以及发送 Discord 通知——所有这些都通过单一的 config.yml 进行配置。
? 1.3.0 新增功能
Java 25 & 构建现代化
- 升级至 Java 25 — 使用 Java 25 字节码编译,以获得最新的 JVM 性能和语言特性。
- Gradle 9.5.1 — 构建系统从 Gradle 8.x 升级至 9.5.1,以原生支持 Java 25。
- 虚拟线程执行器 — 仪表板的 HTTP 服务器现在使用
newVirtualThreadPerTaskExecutor(),以便在 Java 25 上实现非阻塞 I/O 扩展。
plugin.yml api-version 更新为 1.21,以匹配目标平台。
兼容性
- Minecraft 1.21.x – 26.2.x — 基于 Paper 1.21.1 API 编译,向前兼容所有通过 26.2.x 的 Paper 版本。
现有配置完全兼容——无需更改配置。
✨ 功能特性
? 零接触 Python 设置
服务器上未安装 Python?没问题。PyRunner 会自动检测你的操作系统和 CPU 架构,并在首次启动时通过 python-build-standalone 下载独立的 Python 二进制文件。适用于 Linux (x64 & ARM64)、macOS (x64 & ARM64) 和 Windows (x64)。该二进制文件仅下载一次并缓存在本地。
? 自动依赖安装
如果你的机器人有 requirements.txt,PyRunner 将在启动前自动运行 pip install -r requirements.txt(前提是依赖尚未安装)。删除 bot/.pyrunner_deps_installed 可在下次启动时强制重新安装。
? 崩溃恢复与循环保护
机器人进程受到持续监控。如果它崩溃,PyRunner 会等待一段可配置的延迟时间,然后自动重启它。如果在短时间内崩溃次数过多,崩溃循环保护机制将介入并停止重试——防止无限重启刷屏,同时向你发出警报。
?️ 实时 Web 仪表板
内置 HTTP 服务器提供一个时尚的、受密码保护的控制中心,可通过任何浏览器访问。功能包括:
- 通过 Server-Sent Events (SSE) 进行 实时日志流传输 ——无需刷新
- 启动 / 停止 / 重启 / pip install 按钮
- 实时的 状态、运行时间、PID 和重启计数
- 内存监控 ——显示实时 RSS 内存使用情况
- 彩色编码的日志行(错误、警告、系统消息、回溯)
- 带切换功能的自动滚动
- stdin 输入栏 ——直接向机器人进程发送命令
- 多机器人选择器 ——从仪表板切换机器人(自动检测)
- 所有修改类 API 端点的 CSRF 保护
- 暴力破解登录保护 ——5 次失败尝试后锁定
? Discord Webhook 通知
当你的机器人启动、停止、崩溃或运行 pip install 时,在 Discord 频道中接收通知——全部通过标准的 Discord webhook URL 完成。通知无需机器人令牌。每种事件类型均可单独切换。
? 游戏内命令
通过 Minecraft 控制台或游戏内的 /pybot 命令进行完整控制。无需 SSH 进入服务器即可重启机器人。
? 多机器人支持
同时运行多个 Python 机器人——每个机器人拥有自己的进程、日志文件和独立的崩溃恢复机制。使用 /pybot start <n>、/pybot stop <n> 等命令分别控制每个机器人。
? Python 版本锁定
锁定特定的 Python 次要版本(例如 "3.11"、"3.12"),而不是始终下载最新版本。
? stdin 透传
直接从 Web 仪表板向机器人进程发送输入,而无需重启它——这对于接受通过 stdin 的控制台命令的机器人非常有用。
? 内存监控
Web 仪表板显示机器人进程的实时内存使用情况 (RSS),直接从 Linux 上的 /proc/<pid>/status 读取。
? TunnelMC 集成
如果安装了 TunnelMC 并且仪表板端口上有活动的隧道,PyRunner 会在机器人启动时在控制台中打印公共 URL——纯属信息提示,TunnelMC 绝不会自动启动。
? 安装
- 下载
PyRunner.jar 并将其放入 plugins/ 文件夹
- 启动服务器一次以生成配置文件
- 将你的机器人代码放在
plugins/PyRunner/bot/ 中(应包含用于依赖项的 requirements.txt)
- 编辑
plugins/PyRunner/config.yml ——至少需在 env: 下设置你的机器人令牌
- 重启服务器,或运行
/pybot start
PyRunner 将处理其余事宜——Python 下载、pip install 和机器人启动均自动完成。
? 文件结构
plugins/
PyRunner/
config.yml ← 所有插件设置
bot/ ← 你的机器人代码放在这里
main.py
requirements.txt
.pyrunner_deps_installed ← 成功 pip install 后创建
logs/
bot.log ← 实时机器人输出(5MB 时轮换,保留 3 个备份)
bot-<n>.log ← 使用多机器人时的每个机器人日志文件
python/ ← 自动下载的 Python 二进制文件(请勿编辑)
python.properties ← 缓存的二进制路径
? 命令与权限
权限节点: pyrunner.admin (默认: OP)
| 命令 |
描述 |
/pybot start [name] |
启动机器人(或通过名称指定特定机器人) |
/pybot stop [name] |
停止机器人(或通过名称指定特定机器人) |
/pybot restart [name] |
重启机器人(或通过名称指定特定机器人) |
/pybot status [name] |
显示所有机器人或特定机器人的状态 |
/pybot install [name] |
强制重新运行 pip install |
/pybot reload |
重新加载 config.yml |
? Web 仪表板
在任何浏览器中打开 http://<your-server-ip>:<port>(默认端口:8080)。
控制面板受密码保护。请在 config.yml 中更改默认密码。
? Discord Webhook 设置
- 打开你想要接收通知的 Discord 频道
- 进入 编辑频道 → 集成 → Webhooks → 新建 Webhook
- 复制 Webhook URL
- 将其粘贴到
config.yml 中的 discord.webhook.url 下
- 设置
discord.webhook.enabled: true
- 重启服务器或运行
/pybot reload
? 兼容性
|
|
| Minecraft |
Paper 1.21.x – 26.2.x |
| Java |
25+(使用 Java 25 编译) |
| 操作系统 |
Linux, macOS, Windows |
| 架构 |
x64, ARM64 |
| 托管方式 |
自托管、Pterodactyl、任意 VPS |
⚠️ 需要 Java 25: 该 JAR 文件使用 Java 25 编译。你的服务器必须运行 Java 25 或更高版本。推荐使用并已充分测试的配置为 Paper 1.21.x + Java 25。
? 相关项目
NodeRunner — 此插件的 Node.js 等效版本。让你的 Minecraft 服务器旁同时运行一个 Node.js Discord 机器人。
TunnelMC — 通过 ngrok 隧道将任意服务器端口暴露到互联网。如果你的主机不提供多个端口分配,TunnelMC 可与 PyRunner 完美配合,使 Web 控制面板无需额外端口即可公开访问。
? 许可证
保留所有权利 — 本插件及其源代码均为专有软件。
由 Spider 开发
PyRunner ?
Run your Python Discord bot directly alongside your Minecraft server — no external hosting, no VPS, no hassle.
PyRunner is a Paper plugin that manages a Python process (typically a Discord bot) as a child process of your Minecraft server. It handles everything automatically: downloading Python, installing dependencies from requirements.txt, restarting on crash, streaming logs to a live web dashboard, and sending Discord notifications — all configured from a single config.yml.
? What's new in 1.3.0
Java 25 & Build Modernization
- Upgraded to Java 25 — compiled with Java 25 bytecode for the latest JVM performance and language features.
- Gradle 9.5.1 — build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support.
- Virtual thread executor — the dashboard HTTP server now uses
newVirtualThreadPerTaskExecutor() for non-blocking I/O scaling on Java 25.
plugin.yml api-version updated to 1.21 to match the target platform.
Compatibility
- Minecraft 1.21.x – 26.2.x — compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.2.x.
Existing configs remain fully compatible — no config changes required.
✨ Features
? Zero-Touch Python Setup
No Python installed on your server? No problem. PyRunner automatically detects your OS and CPU architecture and downloads a self-contained Python binary via python-build-standalone on first start. Works on Linux (x64 & ARM64), macOS (x64 & ARM64), and Windows (x64). The binary is downloaded once and cached locally.
? Automatic Dependency Installation
If your bot has a requirements.txt, PyRunner will automatically run pip install -r requirements.txt before launching whenever the deps haven't been installed yet. Delete bot/.pyrunner_deps_installed to force a reinstall on next start.
? Crash Recovery & Loop Protection
The bot process is monitored constantly. If it crashes, PyRunner waits a configurable delay then restarts it automatically. If it crashes too many times in a short window, crash-loop protection kicks in and stops retrying — preventing infinite restart spam while alerting you.
?️ Live Web Dashboard
A built-in HTTP server hosts a sleek, password-protected control panel accessible from any browser. Features include:
- Live log streaming via Server-Sent Events (SSE) — no refresh needed
- Start / Stop / Restart / pip install buttons
- Real-time status, uptime, PID, and restart count
- Memory monitoring — live RSS memory usage display
- Color-coded log lines (errors, warnings, system messages, tracebacks)
- Auto-scroll with toggle
- stdin input bar — send commands directly to the bot process
- Multi-bot selector — switch between bots from the dashboard (auto-detected)
- CSRF protection on all mutating API endpoints
- Brute-force login protection — lockout after 5 failed attempts
? Discord Webhook Notifications
Get notified in a Discord channel when your bot starts, stops, crashes, or when pip install runs — all via a standard Discord webhook URL. No bot token required for notifications. Each event type is individually toggleable.
? In-Game Commands
Full control from the Minecraft console or in-game with the /pybot command. No need to SSH into your server just to restart the bot.
? Multiple Bot Support
Run more than one Python bot simultaneously — each with its own process, log file, and independent crash recovery. Control each bot individually with /pybot start <n>, /pybot stop <n>, etc.
? Python Version Pinning
Pin a specific Python minor version (e.g. "3.11", "3.12") instead of always downloading the latest release.
? stdin Passthrough
Send input directly to the bot process from the web dashboard without restarting it — useful for bots that accept console commands via stdin.
? Memory Monitoring
The web dashboard shows live memory usage (RSS) of the bot process, read directly from /proc/<pid>/status on Linux.
? TunnelMC Integration
If TunnelMC is installed and has an active tunnel on the dashboard port, PyRunner will print the public URL to console when the bot starts — purely informational, TunnelMC is never auto-started.
? Installation
- Download
PyRunner.jar and place it in your plugins/ folder
- Start the server once to generate config files
- Place your bot code in
plugins/PyRunner/bot/ (should include requirements.txt for dependencies)
- Edit
plugins/PyRunner/config.yml — at minimum set your bot token under env:
- Restart the server, or run
/pybot start
PyRunner will handle the rest — Python download, pip install, and bot launch happen automatically.
? File Structure
plugins/
PyRunner/
config.yml ← All plugin settings
bot/ ← Your bot code goes here
main.py
requirements.txt
.pyrunner_deps_installed ← Created after successful pip install
logs/
bot.log ← Live bot output (rotates at 5MB, keeps 3 backups)
bot-<n>.log ← Per-bot log files when using multiple bots
python/ ← Auto-downloaded Python binary (do not edit)
python.properties ← Cached binary paths
? Commands & Permissions
Permission node: pyrunner.admin (default: OP)
| Command |
Description |
/pybot start [name] |
Start the bot (or a specific bot by name) |
/pybot stop [name] |
Stop the bot (or a specific bot by name) |
/pybot restart [name] |
Restart the bot (or a specific bot by name) |
/pybot status [name] |
Show status of all bots or a specific one |
/pybot install [name] |
Force re-run pip install |
/pybot reload |
Reload config.yml |
? Web Dashboard
Open http://<your-server-ip>:<port> in any browser (default port: 8080).
The dashboard is password protected. Change the default password in config.yml.
? Discord Webhook Setup
- Open the Discord channel you want notifications in
- Go to Edit Channel → Integrations → Webhooks → New Webhook
- Copy the Webhook URL
- Paste it into
config.yml under discord.webhook.url
- Set
discord.webhook.enabled: true
- Restart the server or run
/pybot reload
? Compatibility
|
|
| Minecraft |
Paper 1.21.x – 26.2.x |
| Java |
25+ (compiled with Java 25) |
| OS |
Linux, macOS, Windows |
| Architectures |
x64, ARM64 |
| Hosting |
Self-hosted, Pterodactyl, any VPS |
⚠️ Java 25 Required: The JAR is compiled with Java 25. Your server must run Java 25 or higher. Paper 1.21.x+ with Java 25 is the recommended and fully tested setup.
? Related Projects
NodeRunner — The Node.js equivalent of this plugin. Run a Node.js Discord bot alongside your Minecraft server.
TunnelMC — Expose any server port to the internet via ngrok tunnels. If your host doesn't provide multiple port allocations, TunnelMC pairs perfectly with PyRunner to make the web dashboard publicly accessible without needing an extra port.
? License
All Rights Reserved — This plugin and its source code are proprietary.
Developed by Spider
评论 0
登录后参与评分
还没有评论,来抢沙发吧