MineSHH
MineSHH 为 Paper 服务器管理员提供安全、密码保护的 SSH 控制台。使用 Terminus、OpenSSH、PuTTY 或其他 SSH 客户端连接,即可远程执行 Minecraft 控制台命令——无需安装 Web 面板。
该插件会启动自己的 SSH 服务器,并将新的 Paper 控制台消息实时镜像到已连接的 SSH 会话中。
功能
- 通过 SSH 远程访问 Paper 控制台
- 兼容 Terminus、OpenSSH、PuTTY 及标准 SSH 客户端
- 可配置的绑定地址和 TCP 端口
- 支持可配置用户名的密码保护登录
- 每个已连接的 SSH 会话均可实时流式传输新的 Paper 控制台输出
- 命令以 Minecraft 服务器控制台的权限执行
- 可见的命令输入、退格键支持,以及日志中断打字时的提示符恢复
- 自动生成 SSH 主机密钥,保存在插件数据文件夹中
- 无需外部数据库或代理
要求
| 要求 |
版本 |
| 服务端软件 |
Paper 1.21.6(含构建版本 87) |
| Java |
Java 21 |
| 网络协议 |
TCP |
MineSHH 是服务端插件。玩家无需安装任何内容。
安装
- 从 Modrinth 版本页面下载最新的
MineSHH-*.jar 文件。
- 停止你的 Paper 服务器。
- 将 JAR 文件放入服务器的
plugins 文件夹。
- 启动服务器一次。MineSHH 会创建
plugins/MineSHH/config.yml 和 SSH 主机密钥。
- 停止服务器并在配置文件中更改默认的 SSH 密码。
- 再次启动服务器。
当 MineSHH 准备就绪时,Paper 会打印:
[MineSHH] started
配置
配置文件:plugins/MineSHH/config.yml
**必须指定一个 TCP 端口。**
**修改此文件后需重启服务器。**
ssh:
**SSH 服务器监听的地址。** 仅使用 127.0.0.1 表示仅限本地访问。
bind-address: "0.0.0.0"
port: 2222
username: "admin"
**在将端口暴露给网络之前请更改此项。**
password: "change-this-password"
| 选项 |
描述 |
bind-address |
0.0.0.0 接受来自任何网络接口的连接。使用 127.0.0.1 仅允许本地连接或同一台机器上的代理/隧道。 |
port |
SSH 监听端口。必须是 1 到 65535 之间未使用的 TCP 端口。默认为 2222。 |
username |
SSH 登录所需的用户名。 |
password |
SSH 登录所需的密码。在允许远程访问之前,请更改默认值。 |
每次配置更改后请重启服务器。
连接
在服务端防火墙以及托管提供商的防火墙面板(如适用)中允许配置的 TCP 端口。
OpenSSH
ssh -p 2222 admin@YOUR_SERVER_IP
将 2222、admin 和 YOUR_SERVER_IP 替换为你自己的值。在提示时输入 config.yml 中的密码。
Terminus
使用以下值创建一个新的 SSH 连接:
| 字段 |
值 |
| 主机 |
你的服务器 IP 地址或域名 |
| 端口 |
配置的 ssh.port(默认:2222) |
| 用户名 |
配置的 ssh.username |
| 密码 |
配置的 ssh.password |
首次连接可能会显示 SSH 主机密钥确认。这是正常现象:MineSHH 会在首次启动时生成其主机密钥。仅在连接到正确的服务器时才确认它。
使用远程控制台
连接后,MineSHH 会显示 MineSHH > 提示符。输入 Minecraft 控制台命令时不要带前导 /。
MineSHH > say Hello from SSH
MineSHH > list
MineSHH > whitelist add PlayerName
MineSHH > stop
命令将以控制台权限发送给 Paper,因此其效力与直接在服务器终端中输入相同。新服务器日志将在 SSH 连接打开期间显示。
输入以下任一命令以仅结束 SSH 连接:
exit
logout
exit 和 logout 仅关闭 SSH 会话。要停止 Minecraft 服务器,请使用 stop 控制台命令。
安全性
SSH 控制台访问功能强大:任何知道凭据的人都可以运行管理服务器的命令。请保持私密。
- 在暴露端口之前更改默认密码。
- 使用长且唯一的密码。
- 不要与不可信的人共享 SSH 凭据。
- 尽可能在防火墙中将端口限制为受信任的 IP 地址。
- 如果你通过 SSH 隧道、VPN 或本地面板集成连接,请将
127.0.0.1 用作 bind-address。
- 不要使用 Minecraft 游戏端口(
25565)作为 MineSHH 端口。
- 保持生成的
plugins/MineSHH/ssh-host-key.ser 文件私密。除非你故意希望客户端看到新主机密钥,否则不要删除它。
故障排除
连接被拒绝
检查服务器是否正在运行,MineSHH 是否打印了 [MineSHH] started,配置的 TCP 端口是否被操作系统防火墙允许,以及端口是否在托管提供商面板中开放。
地址已在使用
另一个应用程序正在使用所选端口。将 ssh.port 更改为空闲的 TCP 端口并重启 Paper 服务器。
身份验证失败
验证 plugins/MineSHH/config.yml 中的 ssh.username 和 ssh.password。更改任一值后请重启服务器。
SSH 客户端报告主机密钥已更改
这通常意味着服务器主机密钥已重新生成、服务器已迁移,或者客户端正在连接到不同的机器。在接受新密钥之前请验证服务器身份。
我可以连接,但没有任何命令起作用
命令不能以 / 开头。例如,输入 list,而不是 /list。
从源代码构建
此仓库包含一个 GitHub Actions 工作流,可在每次推送、拉取请求和手动工作流运行时自动构建插件。从已完成的工作流运行中下载 MineSHH 工件。
本地构建需要 Java 21 和 Maven:
mvn package
构建好的 JAR 文件将放置在 target 目录中。
支持
报告问题时,请附上你的 Paper 版本、Java 版本、MineSHH 版本以及相关的控制台错误日志(请先移除密码、IP 地址等隐私信息)。
MineSHH
MineSHH gives Paper server owners a secure, password-protected SSH console. Connect with Terminus, OpenSSH, PuTTY, or another SSH client and run Minecraft console commands remotely—without installing a web panel.
The plugin starts its own SSH server and mirrors new Paper console messages to connected SSH sessions in real time.
Features
- Remote SSH access to the Paper console
- Compatible with Terminus, OpenSSH, PuTTY, and standard SSH clients
- Configurable bind address and TCP port
- Password-protected login with a configurable username
- Live stream of new Paper console output in every connected SSH session
- Commands are executed as the Minecraft server console
- Visible command input, Backspace support, and prompt restoration when a log interrupts typing
- Automatically generated SSH host key, kept in the plugin data folder
- No external database or proxy required
Requirements
| Requirement |
Version |
| Server software |
Paper 1.21.6 (including build 87) |
| Java |
Java 21 |
| Network protocol |
TCP |
MineSHH is a server-side plugin. Players do not need to install anything.
Installation
- Download the latest
MineSHH-*.jar file from the Modrinth version page.
- Stop your Paper server.
- Put the JAR in the server's
plugins folder.
- Start the server once. MineSHH creates
plugins/MineSHH/config.yml and an SSH host key.
- Stop the server and change the default SSH password in the configuration.
- Start the server again.
When MineSHH is ready, Paper prints:
[MineSHH] started
Configuration
Configuration file: plugins/MineSHH/config.yml
**A TCP port is required.**
**Restart the server after changing this file.**
ssh:
**Address on which the SSH server listens.** Use 127.0.0.1 for local access only.
bind-address: "0.0.0.0"
port: 2222
username: "admin"
**Change this before exposing the port to a network.**
password: "change-this-password"
| Option |
Description |
bind-address |
0.0.0.0 accepts connections from any network interface. Use 127.0.0.1 to allow only local connections or a proxy/tunnel on the same machine. |
port |
The SSH listening port. It must be an unused TCP port from 1 to 65535. The default is 2222. |
username |
Username required for SSH login. |
password |
Password required for SSH login. Change the default value before allowing remote access. |
Restart the server after every configuration change.
Connecting
Allow the configured TCP port in the server firewall and, if applicable, in your hosting provider's firewall panel.
OpenSSH
ssh -p 2222 admin@YOUR_SERVER_IP
Replace 2222, admin, and YOUR_SERVER_IP with your own values. Enter the password from config.yml when prompted.
Terminus
Create a new SSH connection with these values:
| Field |
Value |
| Host |
Your server IP address or domain |
| Port |
The configured ssh.port (default: 2222) |
| Username |
The configured ssh.username |
| Password |
The configured ssh.password |
The first connection can display an SSH host-key confirmation. This is normal: MineSHH generates its host key on its first startup. Confirm it only when you are connecting to the correct server.
Using the Remote Console
After connecting, MineSHH displays a MineSHH > prompt. Type Minecraft console commands without a leading /.
MineSHH > say Hello from SSH
MineSHH > list
MineSHH > whitelist add PlayerName
MineSHH > stop
The command is sent to Paper with console permissions, so it has the same power as typing directly in the server terminal. New server logs are displayed in the SSH connection while it is open.
Type one of the following to end only the SSH connection:
exit
logout
exit and logout close the SSH session only. To stop the Minecraft server, use the stop console command.
Security
SSH console access is powerful: anyone who knows the credentials can run administrative server commands. Keep it private.
- Change the default password before exposing the port.
- Use a long, unique password.
- Do not share the SSH credentials with untrusted people.
- Restrict the port in your firewall to trusted IP addresses whenever possible.
- Use
127.0.0.1 as bind-address if you connect through an SSH tunnel, VPN, or local panel integration.
- Do not use the Minecraft game port (
25565) as the MineSHH port.
- Keep the generated
plugins/MineSHH/ssh-host-key.ser file private. Do not delete it unless you intentionally want clients to see a new host key.
Troubleshooting
Connection refused
Check that the server is running, MineSHH printed [MineSHH] started, the configured TCP port is allowed by the operating-system firewall, and the port is open in your hosting provider panel.
Address already in use
Another application is using the selected port. Change ssh.port to a free TCP port and restart the Paper server.
Authentication failed
Verify ssh.username and ssh.password in plugins/MineSHH/config.yml. Restart the server after changing either value.
The SSH client reports a changed host key
This normally means the server host key was regenerated, the server was moved, or the client is connecting to a different machine. Verify the server identity before accepting the new key.
I can connect, but no command works
Commands must not start with /. For example, enter list, not /list.
Building from Source
This repository includes a GitHub Actions workflow that builds the plugin automatically on every push, pull request, and manual workflow run. Download the MineSHH artifact from the completed workflow run.
Local builds require Java 21 and Maven:
mvn package
The built JAR is placed in the target directory.
Support
When reporting a problem, include your Paper version, Java version, MineSHH version, and the relevant console error (remove passwords, IP addresses, and other private information first).
评论 0
登录后参与评分
还没有评论,来抢沙发吧