Minecraft 开服器 - 需求规格说明书

项目代号：MCever 技术栈：Node.js + ink（TUI 终端端）+ React（Web 端） 参考产品：MCSManager、Crafty Controller、Multicraft、Pterodactyl Panel、AMP、Cosmos

一、项目概述

本项目旨在开发一款 Minecraft 开服器，面向个人服主和小团队，提供：

• CLI 终端端（TUI）：基于 ink 的命令行交互界面，适合运维和 SSH 远程管理
• Web 管理端：基于 React 的可视化界面，适合日常管理

后端统一使用 Node.js，负责 Java 服务端进程管理、文件 IO、RCON 通信、定时任务、数据持久化等。

二、核心功能模块（需求点）

1. 服务端生命周期管理 🔑

| 需求点 | 说明 | 优先级 | 状态 | |---|---|---|---| | 多实例管理 | 同时管理多个 Minecraft 服务端实例 | P0 | ✅ | | 服务端类型 | Vanilla、Spigot、Paper、Purpur、Fabric、Forge、Sponge、Velocity、BungeeCord、Waterfall、Folia、NeoForge | P0 | ✅（itzg 镜像全支持） | | 版本选择 | 支持 1.7.10 ~ 1.21+ 所有版本 | P0 | ✅（itzg 镜像 VERSION 环境变量） | | 一键安装 | 选择类型 → 输入名称 → 选版本 → 设端口 → 自动部署 | P0 | ✅ | | JVM/启动参数 | 自定义 -Xms、-Xmx、JVM_OPTS 等 | P0 | ✅（通过 -e MEMORY / -e JVM_OPTS） | | 启动/停止/重启 | mcever start/stop/restart <name|id> | P0 | ✅ | | 删除实例 | mcever remove <name|id>，交互式确认是否删数据 | P0 | ✅ | | 实例列表 | mcever list 表格展示，含 ID/状态/名称/类型/端口/容器名 | P0 | ✅ | | 控制台实时输出 | 保留 ANSI 颜色高亮，支持搜索/过滤 | P0 | ⏳ | | 命令发送 | 在控制台输入游戏命令 | P0 | ⏳ | | EULA 自动同意 | 首次启动自动写入 eula=true | P0 | ✅（-e EULA=TRUE） |

2. 文件管理 📁

| 需求点 | 说明 | 优先级 | |---|---|---| | 文件浏览 | 服务端根目录树状结构浏览 | P0 | | 配置文件可视化编辑 | server.properties、spigot.yml、bukkit.yml、paper.yml、purpur.yml | P0 | | 玩家数据文件 | ops.json、whitelist.json、banned-players.json、banned-ips.json | P0 | | 协议文件 | eula.txt | P0 | | 文件 CRUD | 上传、下载、删除、重命名、创建文件夹 | P1 | | 编辑器 | 在线编辑 + 保存（带格式校验） | P0 | | 权限管理 | 文件读写权限检查 | P2 |

3. 世界管理 🌍

| 需求点 | 说明 | 优先级 | |---|---|---| | 世界列表 | overworld / nether / end 三个维度 | P1 | | 世界大小 | 显示占用空间 | P1 | | 世界重置 | 删除当前世界，下一次启动自动重新生成 | P2 | | 多世界支持 | 支持加载自定义世界文件夹 | P2 | | 世界导入/导出 | 上传 zip 还原 | P2 |

4. 玩家管理 👥

| 需求点 | 说明 | 优先级 | |---|---|---| | 在线玩家列表 | 基于 list 命令或 RCON 拉取 | P0 | | 白名单 | 添加/移除/启用/禁用/列表 | P0 | | OP 管理 | 提升/降级/列表 | P0 | | 玩家封禁 | ban / unban / banlist | P0 | | IP 封禁 | ban-ip / pardon-ip / banip-list | P0 | | 踢出玩家 | kick 命令 | P1 |

5. 插件 / 模组管理 🔌

| 需求点 | 说明 | 优先级 | |---|---|---| | 插件上传 | 上传 .jar 文件到 plugins/ 目录 | P1 | | 模组上传 | 上传 .jar 到 mods/ 目录（Forge/Fabric） | P1 | | 删除/启用/禁用 | 通过重命名或删除实现 | P1 | | 列表查看 | 文件名、大小、修改时间 | P1 | | 插件版本检查 | 检查服务端对应的插件版本（高级） | P3 |

6. 性能监控 📊

| 需求点 | 说明 | 优先级 | |---|---|---| | CPU 使用率 | Node.js 读取 /proc 或 os.cpus() | P1 | | 内存使用率 | 堆内存 / 非堆内存 | P1 | | TPS | Tick Per Second，通过 /tps 命令（Paper/Purpur）或 NMS | P1 | | MSPT | Milliseconds Per Tick | P1 | | 在线人数 | 实时统计 | P0 | | 历史性能曲线 | 折线图（Web 端） | P2 | | 进程状态 | PID、运行时长 | P1 |

7. 网络与连接配置 🌐

| 需求点 | 说明 | 优先级 | 状态 | |---|---|---|---| | 端口配置 | Java 25565 / 自定义，多实例自动分配不同端口 | P0 | ✅ | | RCON | 启用、端口、密码、远程命令发送 | P0 | ⏳ | | MOTD | 支持彩色代码 | P1 | ⏳ | | 正版验证 | online-mode=true/false | P0 | ⏳ | | 最大玩家数 | max-players | P0 | ⏳ | | 游戏规则 | 难度、PVP、白名单开关等 | P1 | ⏳ |

8. 计划任务（定时任务） ⏰

| 需求点 | 说明 | 优先级 | |---|---|---| | 定时重启 | cron 表达式或相对时间 | P1 | | 定时备份 | 按小时/天/周 | P1 | | 定时广播 | 自动执行 say 命令 | P2 | | 定时执行命令 | 自定义任意命令 | P2 |

9. 用户与权限系统 👤

| 需求点 | 说明 | 优先级 | |---|---|---| | 多用户系统 | 管理员 / 普通用户 | P1 | | 细粒度权限 | 控制哪个用户能管理哪个实例 | P2 | | 登录鉴权 | 本地账号（密码哈希） | P1 | | 登录鉴权 | OAuth（GitHub、Google，可选） | P3 |

10. 备份系统 💾

| 需求点 | 说明 | 优先级 | |---|---|---| | 手动备份 | zip/tar 打包整个服务端目录 | P0 | | 自动定时备份 | 按周期执行 | P1 | | 保留策略 | 保留最近 N 份，自动清理 | P1 | | 一键恢复 | 从备份还原到指定目录 | P0 | | 备份下载 | 下载到本地 | P1 |

11. 日志系统 📜

| 需求点 | 说明 | 优先级 | 状态 | |---|---|---|---| | 容器日志查看 | mcever logs <name|id> 查看最近 200 行 | P0 | ✅ | | 实时日志流 | CLI 端 stdout 流、Web 端 WebSocket 推送 | P0 | ⏳ | | 历史日志查看 | latest.log、logs/*.log.gz | P1 | ⏳ | | 日志搜索 | 关键字过滤 | P1 | ⏳ | | 日志级别着色 | INFO/WARN/ERROR 不同颜色 | P1 | ⏳ |

12. 系统设置 ⚙️

| 需求点 | 说明 | 优先级 | 状态 | |---|---|---|---| | Docker 环境检测 | 启动时自动检测 docker/podman，无则给出安装指引 | P0 | ✅ | | 孤儿资源清理 | 自动清理残留容器和数据库孤儿记录 | P0 | ✅ | | 端口冲突检测 | 多实例端口冲突时自动报错提示 | P0 | ✅ | | 命名灵活 | 支持实例名 / 容器名 / ID 三种方式操作 | P0 | ✅ | | Java 版本管理 | 1.8 / 11 / 16 / 17 / 21 自动检测 | P0 | ⏳ | | 主题/语言 | Web 端 UI 主题切换 | P2 | ⏳ | | Docker 支持 | 基于 itzg/minecraft-server 镜像的容器化部署 | P3 | ✅ |

13. 高级 / 增值功能 🔔

| 需求点 | 说明 | 优先级 | 状态 | |---|---|---|---| | 跨平台 | Windows / Linux / macOS | P0 | ✅（基于 Docker） | | 交互式菜单 | CLI 主菜单，选择操作避免背命令 | P0 | ✅ | | 守护进程 | 服务端崩溃自动重启（--restart unless-stopped） | P1 | ✅（Docker 自带） | | 远程管理 | REST API | P1 | ⏳ | | Webhook 通知 | Discord / Telegram / 邮件 | P2 | ⏳ | | 资源限制 | CPU 限额、内存上限 | P3 | ⏳ |

三、非功能性需求

| 需求点 | 说明 | |---|---| | 性能 | 控制台输出延迟 < 100ms；Web 端 UI 响应 < 300ms | | 安全 | 密码使用 bcrypt 哈希存储；RCON 密码加密存储 | | 稳定性 | 长时间运行不内存泄漏；崩溃后能自恢复 | | 国际化 | 中文 / 英文双语 | | 可扩展性 | 模块化设计，方便后续接入 Docker / K8s | | 可观测性 | 自身运行时也有日志输出（便于排查问题） |

四、技术架构

┌─────────────────────────────────────────────┐
│      React Web UI     /     ink TUI          │  ← 交互层
├─────────────────────────────────────────────┤
│   REST API (Express/Fastify) + WebSocket    │  ← 通信层
├─────────────────────────────────────────────┤
│   进程管理 / RCON / 文件 / 备份 / 调度       │  ← 核心服务层
├─────────────────────────────────────────────┤
│          SQLite (better-sqlite3)             │  ← 数据层
└─────────────────────────────────────────────┘

技术栈选型

| 模块 | 推荐库 | |---|---| | HTTP 服务 | Express 或 Fastify | | WebSocket | ws | | 进程管理 | Node.js child_process | | RCON 客户端 | rcon-client 或自实现（TCP + Source RCON 协议） | | 文件 IO | fs-extra + globby | | 备份压缩 | archiver（zip）/ tar | | 定时任务 | node-cron | | 数据存储 | better-sqlite3（轻量、无依赖） | | Web UI | React + Vite + Tailwind + shadcn/ui | | TUI | ink + ink-select-input + ink-text-input | | 鉴权 | jsonwebtoken + bcrypt | | 日志 | pino 或 winston |

五、MVP（最小可行产品）优先级

🎯 P0 - 必须有（首个可发布版本）

1. 多实例创建 + 服务端下载 + 启动/停止/重启
2. 实时控制台（Web 端 + TUI 端）
3. EULA 自动同意
4. 文件管理（重点：server.properties 可视化编辑）
5. 玩家管理（白名单 / OP / 封禁）
6. 备份与恢复
7. 端口与 Java 版本配置

🎯 P1 - 第二阶段

• 性能监控（CPU/内存/TPS/在线人数）
• 计划任务（定时重启/备份）
• 日志系统（历史日志查看、搜索）
• 用户与权限系统
• 插件/模组管理
• 守护进程（崩溃自动重启）

🎯 P2 - 第三阶段

• Webhook 通知
• MOTD 编辑器
• 备份保留策略
• Docker 隔离
• 国际化

🎯 P3 - 长期规划

• OAuth 登录
• 插件市场/版本检查
• K8s 集成
• 集群管理

六、数据模型（初步）

instances 实例表

• id、 name、 type（paper/spigot/forge 等）、 version、path、port、rcon_port、rcon_password、jvm_args、java_path、status（stopped/starting/running/stopping）、 created_at、updated_at

users 用户表

• id、 username、 password_hash、 role（admin/user）、 created_at

backups 备份表

• id、 instance_id、 filename、 size、 created_at

scheduled_tasks 计划任务表

• id、 instance_id、 cron、 command、 enabled

audit_logs 操作日志表（可选）

• id、 user_id、 instance_id、 action、 created_at

七、目录结构（建议）

MCever2/
├── packages/
│   ├── core/             # 核心服务（进程、RCON、文件、备份、调度）
│   ├── cli/              # ink TUI 端
│   ├── web/              # React Web 端
│   └── shared/           # 共享类型与工具
├── server/               # 后端服务入口
├── data/                 # SQLite 数据库
├── instances/            # Minecraft 实例根目录（默认）
├── backups/              # 默认备份目录
├── package.json
├── 需求点.md             # 本文档
└── README.md

文档版本：v0.1 最后更新：2026-07-25 作者：调研输出 by Cline