BlockNexus 入门教程

从零开始，用一个网页管理你的 Minecraft 服务器 本教程基于 BlockNexus，面向第一次开服的新手，全程配图、照着点就能学

---

1. BlockNexus 是什么

一句话：开服到管服，一个网页搞定。

传统开服你需要：SSH 进服务器、手写配置、敲命令启停、装各种脚本查在线人数…… BlockNexus 把这些全部收进一个网页面板：

• 一键开服：填个地址，自动装 Agent、下载核心、装好 Java、启动服务器；
• 实例管理：启动/停止/重启、实时控制台、文件管理、Mod 启停、配置可视化编辑；
• 玩家管理：在线名单、在线时长统计、聊天记录、踢出/封禁/OP；
• 备份与自动化：手动/定时备份、崩溃自动重启、定时重启；
• 网络助手：DDNS 动态域名、frp 内网穿透，让家里的电脑也能被朋友连上；
• 省心：Agent 自动升级、面板应用内一键更新、邮件离线通知、AI 日志分析。

架构：面板 + Agent

BlockNexus 分为两个部分，理解了这个后面的一切都好懂：

• 面板：跑在你自己电脑上的 Node.js 程序，提供网页界面（默认 http://127.0.0.1:3080）；
• Agent：跑在「实际开服的机器」上的一个小进程（单个 agent.js 文件），负责管理 MC 实例；
• 两者之间走 token 双向认证 + AES-256-GCM 加密通道，默认由面板主动连入 Agent—— 所以面板不需要公网地址，你在家里路由器后面（NAT）也能管理云服务器；
• 如果面板和 MC 在同一台机器（比如就在家里的 Windows 上开服），Agent 由面板直接托管，连 SSH 都不需要。

本机开服时 Agent 也被面板直接管理，这是最简单的形态，本教程第 3 节就用它演示。

---

2. 安装与启动

三种形态任选其一，新手直接选 A：

形态	适合谁	怎么装
A. Windows 便携包	家里 Windows 开服，零依赖	下载 zip → 解压 → 双击 BlockNexus.exe
B. 源码运行	会用命令行，Linux/Windows 都行	git clone + npm install + node panel/server.js
C. 面板本地 + MC 在远程 Linux	有云服务器/VPS 的人	面板「快速添加」填 SSH，Agent 自动安装

A. Windows 便携包（推荐）

1. 打开 Releases 页面，下载最新的 BlockNexus-<版本>-portable.zip；
2. 解压到任意目录（注意：一定要先解压，不要在压缩包里直接双击运行）；
3. 双击 BlockNexus.exe，浏览器打开 http://127.0.0.1:3080 即可使用。

几个小提示：

• 数据全部存在解压目录的 data/ 里：拷走 data/ 就是迁移，删掉整个目录就是卸载；
• 程序会在系统托盘放一个图标，左键打开面板，右键可以退出；
• 升级很方便：面板里「设置 → 版本与更新」可以应用内一键更新（只换程序文件，不动 data/，服务器列表和配置都保留）。

B. 源码运行

要求 Node.js ≥ 18（官网下载，装完 node -v 能看到版本号即可）：

git clone https://github.com/live-ling/BlockNexus.git
cd BlockNexus
npm install
npm run build:web        # 首次必须构建前端（之后不用再跑）
node panel/server.js     # 启动面板 → http://127.0.0.1:3080

Linux 上如果想开机自启、崩了自动拉起，建议配成 systemd 服务，示例见 docs/deployment.md。

启动后你会看到

第一次打开是空的，什么都不用怕——点「快速添加」就完事：

面板默认只监听本机、无密码：它是本地服务，打开即用。 只有当你想让别人（局域网/公网）也能访问面板时，才需要开启登录保护——见第 7 节。

---

3. 第一次开服（3 分钟）

整个流程面板会自动跑完，你只需要填「目标机器」：

3.1 本机开服（什么都不用填）

点首页右上角「快速添加」，弹窗里：

1. 「目标机器」选 本机电脑——选完你会发现地址、SSH 之类的都不用填了；
2. 勾选「同时创建并启动 Minecraft 实例」；
3. 实例参数（核心/版本/内存/端口）留空就是全自动：
   • 核心默认 Paper（性能好、插件生态成熟，新手首选）；
   • 端口从 25565 起自动找空闲的；
   • 内存按机器物理内存的一半推荐（下限 512MB、上限 8GB）；
4. 点「快速添加」，进度实时显示在弹窗里，通常 1–3 分钟完成。

远程 Linux 机器则选「远程服务器（SSH）」，填主机 IP + SSH 账号密码即可，其余流程完全一样—— 面板会通过 SSH 自动装 Node、上传 Agent、注册 systemd 服务。弹窗见下图：

开服过程中面板会自动处理这些事：

• 缺 Java 自动装：1.20.5+ 装 Java 21、1.18–1.20.4 装 17、更早的装 8（走清华镜像，国内很快）；
• 核心下载多层兜底：官方源 → BMCLAPI 镜像 → MSL 镜像，国内服务器也不怕卡死；
• 失败不丢记录：弹窗提供「重试 / 重装 Agent 后重试」，重试会续装同一个实例，不会给你建出 survival-2。

3.2 开好了：实例总览

完成后回到首页，就能看到实例卡片，绿绿的「运行中」：

卡片上一眼可见：核心版本（Paper 1.21）、在线玩家（0/20）、运行时间、内存、连接地址。 地址后面那个「复制」按钮，发给朋友就能连（同一局域网用你的内网 IP，公网见第 6 节）。

3.3 进入游戏

打开 Minecraft 客户端 → 多人游戏 → 添加服务器 → 粘贴地址 → 进入！ 服务器第一次启动会生成世界，面板终端里看到 Done (xx.xxs)! 就是就绪了。

小知识：快速添加时「正版验证」默认开启（只允许正版账号进入）。 想和离线朋友一起玩，在配置设置里关掉 online-mode 即见下文 5.2 节。

---

4. 界面导览：常用页面都长什么样

点实例卡片进入实例详情页，这里是管理单个服务器的主战场：

从上到下：

• 顶部状态条：运行状态、与 Agent 的延迟、停止/重启按钮；
• 四个页签：概览 / 玩家 / 文件 / 配置与维护；
• 概览页（上图）：在线人数、运行时长、内存上限三张卡 + 连接地址；
• 终端：实时彩色日志（ERROR 红、WARN 黄、就绪行绿），底部输入框直接发指令 （试试输 list、say hello，↑↓ 可以翻历史）；
• 右上角还有「仅看错误」和日志搜索——服务器刷屏时定位问题全靠它。

4.1 服务器列表页

底部导航「服务器」进入 /servers，展示每台机器的硬件状态：

卡片显示系统图标（Windows/Ubuntu 等）、Agent 状态、CPU / 内存 / 磁盘实时占用。 注意 IP 默认打码显示（防止截图泄露），点一下即可显示/隐藏。

4.2 服务器设置页

每台服务器的「设置」页集中了机器级管理：

左侧导航五块：

• 连接信息：地址、连接方式、Token（Agent 认证用）；
• Agent 守护进程：版本号、重新安装、停止；Agent 升级面板会自动推送，不用你管；
• Java 运行环境：多版本安装/切换/卸载（Temurin，走清华镜像）——不同 MC 版本要用不同 Java（≤1.16 用 8、1.17 用 16、1.18–1.20.4 用 17、1.20.5+ 用 21），这里一键搞定；
• 系统信息：主机名、系统版本、内存、磁盘；
• 删除服务器：只从面板移除记录，不会动远程的实例。

4.3 面板设置页

底部导航「设置」进入 /settings：

从上到下（部分）：

• 登录保护：给面板加用户名密码（对外暴露前必须开）；
• 公网访问：绑定面板域名，用于通知邮件里的链接；
• 动态 DNS / frp 内网穿透：见第 6 节；
• SMTP 邮件：配置后服务器掉线会发邮件通知你（有 2 分钟抖动过滤，不会误报刷屏）；
• AI 日志分析：填 OpenAI 兼容接口（DeepSeek、智谱等）即可启用；
• 版本与更新：一键检查、应用内更新、回滚；
• 体验改进计划：匿名遥测，默认关闭，想支持项目再开。

---

5. 日常管理：玩家、文件、配置、备份

5.1 玩家与聊天

实例详情页「玩家」页签：

• 左侧在线玩家栏：列出当前在线玩家，每个玩家可一键 踢出 / 封禁 / 封禁 IP / 设为 OP（都可填原因）；
• 左下角「玩家统计」：累计在线时长、会话数、首次/最近上线，支持排序和搜索；
• 左下角「封禁目录」：查看全部封禁玩家与 IP，一键解封；
• 右侧聊天记录：自动记录玩家聊天/表情/私聊（存在服务器上，面板关掉也照记）， 支持按玩家过滤和关键词搜索。

聊天记录属于隐私数据（文件权限已收紧到 0600），面板对外暴露时务必开启登录保护。

5.2 可视化改配置（不用碰文件）

「配置与维护」页签集中了所有维护入口：

点「配置设置 → 打开」，server.properties 变成了中文表单：

• 约 50 个常用配置项都有中文标签和说明（比如「正版验证：关闭后未登录账号也能进入」）；
• 布尔值是开关、枚举是下拉框，改完点「保存并重启」即可生效；
• 保存时保留原文件的注释和顺序，未映射的键可以在「原始文本」里整文件编辑；
• 同一个入口还能编辑插件配置（YAML/JSON 自动生成表单）和管理 Mod （启用/禁用是改名加 .disabled，不删文件，重启生效）。

5.3 备份

「配置与维护」页下方就是备份区：

• 点「创建备份」生成 .tar.gz 完整快照（含存档、配置、Mod），存于实例目录 .backups/ 下；
• 支持下载到本地、一键恢复、删除；
• 打开「定时备份」可以设每日固定时间或固定间隔自动备份，并设置保留份数（自动清理最旧的）；
• 备份时会先让服务器落盘存档（save-all flush），不会备份到写了一半的存档；
• 删除实例前可勾选自动备份，删错了也能恢复。

5.4 自动重启

同一页的「自动化」区：

• 崩溃后自动重启：进程异常退出（非手动停止）延迟拉起，连续崩溃自动退避；
• 定时重启：每日固定时间（可选星期几）或固定间隔（5 分钟～每周），跑久了清内存必备。

5.5 文件管理

实例详情页「文件」页签就是完整文件管理器：

• 左侧目录树（world/、plugins/、server.properties 都在这里）；
• 文本文件（.yml / .json / .log / .properties）直接在网页里编辑保存；
• 上传支持拖拽、断点续传（单文件最大 200MB；有 SSH 凭据时可走 SFTP 无上限直传）；
• 复制/剪切/粘贴/压缩/解压/下载/删除都支持多选批量；
• 安全边界：所有操作锁定在实例目录内，碰不到机器上的其他文件。

---

6. 进阶：远程服务器、内网穿透、AI 分析

6.1 管理一台远程 Linux 服务器

家里电脑太卡、想 24 小时开服？找台云服务器（VPS），在面板「快速添加」里：

1. 目标机器选「远程服务器（SSH）」，填 IP + root 账号密码；
2. 连接方式保持默认「面板连接 Agent」——需要在云安全组放行 Agent 端口 3099（TCP）；
3. 其余和本机开服一模一样：面板通过 SSH 自动装好一切，实例跑在远程，你在本地网页上管。

为什么不用在服务器上装任何面板？因为 Agent 只是一个单文件脚本，由面板托管升级； 而面板躲在自己电脑后面，不需要公网 IP，更安全。

6.2 让外网的朋友连进你家的服务器

家里宽带通常没有公网 IP，两种方案（设置页 → 网络）：

• DDNS（动态域名）：有公网 IP 但会变（家宽常见）。绑定 Cloudflare/DNSPod/DuckDNS 域名， IP 变了自动更新解析记录；
• frp 内网穿透：完全没有公网 IP（CGNAT）时用。支持 SakuraFrp（填访问密钥+隧道 ID 即用） 和自建 frps 两种模式；frpc 二进制需要自备（放 data/frp/bin/，Defender 误报需加排除目录）。

提醒：SakuraFrp 免费节点共享带宽，官方明确说「游戏服务器慎用」，小范围联机可以， 正经公开服建议还是买台公网 VPS。经 frp 接入时不要用「封禁 IP」功能（所有玩家显示同一 IP）。

6.3 AI 日志分析

服务器崩了看不懂日志？在设置页填好 AI 接口（OpenAI Chat Completions 兼容格式， DeepSeek / 智谱等国产模型都行）后，实例详情页会出现「AI 分析」入口：

• 预设问题：分析运行状态、只看报错、崩溃原因、卡顿排查、插件冲突；
• 也可以自由提问，支持多轮追问；
• 面板把最近 500 行控制台日志喂给模型，流式返回分析结果。

---

7. 安全须知（必读）

面板很强大（能装 Agent、能读写服务器文件），所以权限也很大，部署时逐条确认：

1. 面板默认无密码，只监听 127.0.0.1——这没问题；但只要 --host 0.0.0.0 对外， 必须先在设置页开启登录保护，否则任何人可以接管你的服务器；
2. 反向代理（nginx）后面必须加 --trust-proxy，否则登录限流会退化成全局限流；
3. data/config.json 里存着 SSH 密码、Agent token 等明文凭据——机器要可信， 不要把 data/ 目录发给别人或提交到 git；
4. 用 frp 把面板端口映射到公网前，先确认登录保护已开；
5. 聊天记录、玩家统计是明文隐私数据，备份外发前自行掂量；
6. Agent 默认以 root/systemd 身份运行，MC 实例共享该权限——给玩家的权限其实就是 你机器的 root 权限，装插件/Mod 要挑可信的。

---

8. 常见问题 FAQ

Q：开服时提示端口被占？ 快速添加会自动找空闲端口，一般不会遇到。手动指定了端口被占时，Windows 可用 netsh interface portproxy show all 和 Get-NetTCPConnection -LocalPort 25565 排查 （常见元凶：IP Helper 服务或另一个 MC 实例）。

Q：朋友怎么连我的服务器？

• 同一局域网：直接发内网 IP + 端口，如 192.168.1.5:25565；
• 外网：路由器端口映射（有公网 IP）或 frp 内网穿透（没有），见 6.2 节；
• 实例卡片上的「连接地址/域名」可以在「编辑」里自定义，域名还会自动做连通性检测。

Q：正版验证是什么？关了会怎样？online-mode：开启时只有微软正版账号能进；关闭后离线账号（盗版客户端）也能进， 但任何人人冒充任意名字，只适合熟人小圈子。

Q：MC 版本和 Java 版本怎么对应？ 面板会自动处理：1.20.5+ → Java 21，1.18–1.20.4 → Java 17，1.17 → 16，更早 → 8。 也可以在服务器设置页「Java 运行环境」手动安装切换。

Q：升级面板/Agent 需要手动操作吗？ 不需要。面板在「设置 → 版本与更新」里应用内一键升级（保留全部数据）； Agent 会在上线时自动比对版本并由面板推送更新，token 和实例数据都不受影响。

Q：面板关了，服务器会停吗？ 不会。Agent（连同 MC 实例）是独立进程，面板退出后照常运行；重新打开面板会自动重连。 要停服务器请在面板上点「停止」。

Q：Windows 上弹出很多 cmd 黑窗口？ 0.5.x 之后已全静默托管（windowsHide），不会再弹。如果你在用旧版，升级即可。

Q：frpc 被 Windows Defender 查杀？ 误报。把 data\frp\bin 目录加入排除列表即可（frpc 是内网穿透工具，常被启发式规则误判）。

---

9. 下一步阅读

本教程覆盖了新手常用功能，更多细节在官方文档里：

文档	内容
README	30 秒上手与功能速览
docs/features.md	完整功能说明、API 一览
docs/deployment.md	Linux systemd / 反向代理 / 安全清单
docs/development.md	加密通道设计、目录结构、构建与测试

也欢迎：

• 在 GitHub Issues 反馈问题或提建议；
• 点设置页底部「关于」查看开源依赖与 MIT 许可证全文。

祝开服愉快！⛏️