MC Server Control 使用文档

开源自托管 Minecraft 服务器管理面板——从安装到日常运维的完整指南。

安装部署

支持的系统

Linux — Ubuntu/Debian · CentOS/Fedora · Arch（apt / dnf / pacman） macOS — 10.15+ Intel & Apple Silicon（Homebrew） 依赖自动补全 — curl · wget · jq · tar · unzip · dialog · aria2 自动安装

一键安装

安装 git 并克隆仓库

确保系统已安装 git，然后克隆项目到本地。

# 如未安装 git，先用包管理器安装
# Ubuntu/Debian: sudo apt install git
# macOS: brew install git

git clone https://github.com/Shirakawa-Kotone/MinecraftServerPanel mc-manager
cd mc-manager

运行安装脚本

交互式安装（推荐）：

bash install.sh

或无人值守安装（使用默认配置）：

bash install.sh --non-interactive

完成配置

安装脚本会：

检测并安装系统依赖
创建 Python 虚拟环境并安装 Flask/gunicorn
选择安装目录（默认 ~/mc_manager）和 Web 端口（默认 8080）
选择下载镜像源（官方 / TUNA 清华 / BMCLAPI）
注册系统服务：systemd（Linux）或 launchd（macOS）

访问面板

打开浏览器访问 http://<服务器IP>:8080，进入初始设置创建管理员账号即可开始使用。

守护进程管理

系统	管理命令
Linux (systemd)	`systemctl status mc_manager.service` — 查看状态 `systemctl stop mc_manager.service` — 停止 `journalctl -u mc_manager.service -f` — 查看日志
macOS (launchd)	`launchctl load ~/Library/LaunchAgents/com.mcmanager.web.plist` — 加载 `launchctl unload ~/Library/LaunchAgents/com.mcmanager.web.plist` — 卸载

手动启动

cd ~/mc_manager
venv/bin/gunicorn -b 0.0.0.0:8080 "app:app"

配置文件位于 ~/mc_manager/config.json：

{
  "install_dir": "/home/user/mc_manager",
  "web_port": 8080,
  "mirror_url": "https://mirrors.tuna.tsinghua.edu.cn/minecraft/",
  "pypi_mirror": "https://pypi.tuna.tsinghua.edu.cn/simple"
}

快速开始

首次使用

访问 http://<服务器IP>:8080，进入初始设置页面
创建管理员用户名和密码（密码不少于 6 位）
登录后进入仪表盘（Dashboard）
点击"Create Instance"创建第一个服务器实例
将 Minecraft 服务端 JAR 放入实例目录，或通过面板自动下载
点击"启动"即可开始游戏

登录与认证

基于 Flask session 的认证机制，密码使用 bcrypt 加密存储。登录后可在设置中修改用户名和密码。

仪表盘

Dashboard 是面板的主页，提供服务器状态的总览视图：

实例概览：所有实例的名称、MC 版本、状态、JVM 参数、世界大小
系统资源：CPU 使用率、内存（已用/总量）、磁盘（已用/总量）
统计卡片：实例总数、运行中数量
最近活动：后端错误日志摘要
自动刷新：默认 2 秒刷新，可在设置中调整或关闭

实例管理

创建实例

选择 Java 版本（从已安装的 Java 中选择）
选择 Minecraft 版本（官方版本清单，区分正式版/快照）
选择 Mod 加载器：Fabric Forge NeoForge Quilt 或无
配置 JVM 参数（-Xmx / -Xms）
设置服务端端口
系统自动创建目录、下载 server.jar（显示进度）、安装加载器

启动与停止

操作	说明
启动	检测 server.jar → 清理残留 → 启动 Java 进程，自动适配 Forge/NeoForge
正常停止	发送 `stop` 命令到控制台，等待 120 秒
强制停止	发送 SIGTERM → 2 秒后 SIGKILL
状态检测	每 2 秒轮询进程状态

控制台

向运行中的服务器发送 Minecraft 命令，支持 Enter 键快捷发送。日志实时滚动显示。

server.properties 编辑

可视化表单编辑，自动分组显示。支持开关（true/false）、数字、文本输入，保存即生效。

删除实例

二次确认后删除实例目录（含世界数据）及数据库记录。

Mod 管理

已安装 Mod 列表

从 mods/ 目录读取，显示名称、文件大小，支持删除。

搜索与安装

内置 Modrinth API v2：输入关键词搜索，结果自动根据实例的 Mod 加载器和 MC 版本过滤，一键下载安装。

上传 Mod

支持拖拽或点击上传 .jar / .zip / .disabled 文件，可批量上传。

当实例 mod_loader = none 时，Mods 标签灰显不可点击，提示用户需创建带加载器的实例。

数据包管理

从 world/datapacks/ 目录读取，显示名称和大小。

安装：输入数据包下载 URL（支持 ZIP），自动下载并解压
删除：确认后删除

文件管理

完整的 Web 文件浏览器，面包屑导航，支持以下操作：

操作	说明
查看/编辑	点击打开文本文件编辑器，在线编辑并保存
下载	下载单个文件
删除	删除文件或目录（含确认）
新建	新建文件或目录
上传	上传文件，支持拖拽
重命名	重命名文件

实时日志

实时滚动显示 logs/latest.log
基于 Server-Sent Events (SSE) 的实时流
每 1.5 秒自动刷新
智能滚动跟随（用户在底部时自动滚动）
超过 500 行自动截断
支持下载完整日志文件

RCON 远程控制新功能

启用 RCON

在实例详情中进入 RCON 标签页
设置端口（默认 25575）
系统自动生成 20 位强随机密码（含特殊字符）
自动写入 server.properties 并添加 iptables 规则限制仅 localhost 访问
密码一次性显示，保存后不再返回

RCON 控制台

向运行中的服务器发送任意命令
显示命令输出
支持 Enter 键快捷发送
命令历史保留

禁用 RCON

设置 enable-rcon=false
自动移除 iptables 规则

玩家管理

在线玩家

通过 RCON list 命令获取，每 5 秒自动刷新
显示在线人数/最大人数
服务器离线时显示红色 "Server is offline"
在线玩家旁的操作按钮：Whitelist Op/De-Op Kick Ban
OP 玩家显示 OP 标签

白名单管理

从 whitelist.json 读取
通过 Modal 输入玩家名，RCON 执行添加
确认后 RCON 移除

OP 管理

从 ops.json 读取，显示权限等级
通过 Modal 输入玩家名，RCON op 命令添加
确认后 RCON deop 命令移除

封禁管理

从 banned-players.json 读取
折叠/展开列表显示被封禁玩家、原因、时间
封禁：Modal 输入原因，RCON ban 命令
解封：确认后 RCON pardon 命令

备份管理

即时备份

点击"Backup Now"立即将 world/ 目录打包为 world_backup_YYYYMMDD_HHMMSS.tar.gz，存储到 backups/ 目录。进度通过进度条实时显示。

自动备份

配置项	说明
启用/禁用	一键开关
备份间隔	可配置小时数（最小 0.5 小时）
保留数量	最多保留 N 个备份（自动删除最旧）
下次执行时间	自动计算并显示

一键回档

游戏内广播 [Backup] Server will restart for world restore in 5 seconds...

自动停止服务器

将当前 world 备份为 world.restore_bak

从选定备份文件解压恢复

自动重启服务器，广播恢复完成

解压失败时自动还原 .bak，安全可靠。

游戏内广播

备份完成时通过 /say 广播备份编号、占用空间、下次备份时间。回档时广播开始和完成通知。

Java 版本管理

检测：扫描系统常见路径和 update-alternatives
安装：通过系统包管理器（apt）安装指定版本
卸载：通过 apt 卸载指定版本
实例指定：创建实例时可为每个实例选择独立的 Java 版本

全局设置

设置项	说明
镜像源	官方源 / BMCLAPI 一键切换，内置速度测试
仪表盘刷新	配置自动刷新间隔（秒），可关闭
时区设置	下拉选择时区，影响日志时间戳显示
管理员账户	修改用户名和密码
Web 端口	修改 Web 服务端口，修改后自动重启服务

API 参考

所有 API 端点前缀为 /api，认证通过 Flask session。

认证

端点	方法	说明
`/api/auth/setup`	POST	初始管理员设置
`/api/auth/login`	POST	登录
`/api/auth/logout`	POST	登出
`/api/auth/status`	GET	认证状态
`/api/auth/change-password`	PUT	修改密码/用户名

仪表盘 & 实例

端点	方法	说明
`/api/dashboard`	GET	仪表盘数据（资源+实例概览）
`/api/instances`	GET	实例列表
`/api/instances`	POST	创建实例
`/api/instances/<id>`	GET	实例详情
`/api/instances/<id>`	DELETE	删除实例
`/api/instances/<id>/start`	POST	启动实例
`/api/instances/<id>/stop`	POST	停止实例
`/api/instances/<id>/console`	POST	发送控制台命令
`/api/instances/<id>/logs`	GET	获取日志
`/api/instances/<id>/logs/stream`	GET	SSE 实时日志流
`/api/instances/<id>/properties`	GET/PUT	server.properties

Mod & 数据包

端点	方法	说明
`/api/instances/<id>/mods`	GET	Mod 列表
`/api/instances/<id>/mods/search`	POST	搜索 Mod（Modrinth）
`/api/instances/<id>/mods/install`	POST	安装 Mod
`/api/instances/<id>/datapacks`	GET	数据包列表
`/api/instances/<id>/datapacks/install`	POST	安装数据包

RCON & 玩家

端点	方法	说明
`/api/instances/<id>/rcon/config`	GET/PUT	RCON 配置
`/api/instances/<id>/rcon/command`	POST	发送 RCON 命令
`/api/instances/<id>/players`	GET	在线玩家
`/api/instances/<id>/players/whitelist`	GET/POST/DELETE	白名单管理
`/api/instances/<id>/players/ops`	GET/POST/DELETE	OP 管理
`/api/instances/<id>/players/bans`	GET	封禁列表

备份 & 文件

端点	方法	说明
`/api/instances/<id>/backup`	POST	执行备份
`/api/instances/<id>/backup/list`	GET	备份列表
`/api/instances/<id>/backup/restore`	POST	回档
`/api/instances/<id>/backup/config`	GET/PUT	自动备份配置
`/api/instances/<id>/files`	GET	文件列表
`/api/instances/<id>/files/read`	GET	读取文件
`/api/instances/<id>/files/write`	PUT	写入文件
`/api/instances/<id>/files/upload`	POST	上传文件

系统

端点	方法	说明
`/api/minecraft/versions`	GET	Minecraft 版本列表
`/api/java/versions`	GET	已安装 Java
`/api/java/install`	POST	安装 Java
`/api/settings`	GET/PUT	全局设置
`/api/settings/speedtest`	POST	镜像测速

常见问题

如何修改 Web 端口？

在 Settings → Web Port 中修改，修改后系统自动重启服务。

备份文件存在哪里？

每个实例目录下的 backups/ 文件夹。

RCON 密码忘了怎么办？

在实例的 RCON 配置页面重新配置即可，系统会生成新的随机密码。

支持哪些 Mod 加载器？

Fabric、Forge、NeoForge、Quilt 以及原版（无加载器）。创建实例时选择。

能在 Windows 上运行吗？

Web 后端设计为 Linux/macOS 环境。Windows 用户推荐使用 WSL2 或 Docker。

如何升级？

拉取最新代码，重新运行 bash install.sh。配置文件和数据不会丢失。

服务器和面板的日志在哪？

面板日志：~/mc_manager/logs/
服务器日志：各实例 logs/latest.log（面板中实时查看或下载）

MC Server Control · MIT License · 返回首页 · GitHub