Ubuntu 24.04 安装 LinuxGSM v26.4.0 指南

目标：在一台干净的 Ubuntu 24.04.5 LTS 服务器上，从依赖准备、专用用户创建、官方安装器下载，到 Minecraft 游戏服务端实例 mcserver 的安装、启动、保活托管（cron monitor）与卸载清理，完整走一遍 LinuxGSM v26.4.0 的部署主线。全部命令与回显均在实机执行照抄（实测时间 2026-11-02），含三处真实踩坑：缺 jq/bc 报错、Minecraft 26.3 要求 Java 25、install 交互确认卡住非交互执行。软件定位与选型背景见《LinuxGSM v26.4.0 介绍与选型指南》。

一、环境信息

本文全部操作在以下环境实测，回显均取自真实执行结果：

操作系统：Ubuntu 24.04.5 LTS（x86_64），内核 7.0.0-38-generic
实测时间：2026-11-02
LinuxGSM 版本：v26.4.0（2026-10-18 发布，引导脚本 22071 字节）
游戏实例：mcserver（Minecraft 服务端，构建号 26.3，分支 release）
Java 运行时：openjdk-25-jre-headless 25.0.4.1+1-1~24.04.4（Ubuntu 24.04 仓库）
专用运行用户：lgsm（家目录 /home/lgsm，sudo NOPASSWD）
涉及端口：25565/tcp（游戏）、25565/udp（Query）、25575/tcp（RCON，默认未启用）
示例登录账号：root / admin，口令 q1w2e3r4（生产环境务必更换）
网络前提：服务器可访问 GitHub（LinuxGSM 模块按需拉取）与 mojang.com（服务端文件下载）

💡 技术拓展：LinuxGSM 的「安装」是两段式的——

阶段动作产物
装 LinuxGSM bash linuxgsm.sh mcserver 生成本游戏的管理脚本 ~/mcserver 脚本 + ~/lgsm/ 骨架
装游戏服务端 ./mcserver install 下载游戏文件并建配置 ~/serverfiles/ + ~/lgsm/config-lgsm/mcserver/

管理脚本与游戏服务端是两个独立对象，卸载、升级各自分离。本文按这个顺序展开。

阶段	动作	产物
装 LinuxGSM	`bash linuxgsm.sh mcserver` 生成本游戏的管理脚本	`~/mcserver` 脚本 + `~/lgsm/` 骨架
装游戏服务端	`./mcserver install` 下载游戏文件并建配置	`~/serverfiles/` + `~/lgsm/config-lgsm/mcserver/`

二、前置条件

2.1 系统依赖预装（jq 与 bc 是实测硬坑）

LinuxGSM 的检查模块依赖 jq 与 bc 两个小工具。实测在未装它们的机器上直接跑 install，会先报一串错：

/home/lgsm/lgsm/modules/info_game.sh: line 2648: jq: command not found
/home/lgsm/lgsm/modules/info_game.sh: line 2649: jq: command not found
/home/lgsm/lgsm/modules/info_game.sh: line 2650: jq: command not found
/home/lgsm/lgsm/modules/check_system_requirements.sh: line 80: bc: command not found

因此第一步以 root（示例账号 root/admin，口令 q1w2e3r4）登录服务器，预装基础依赖：

apt update
apt install -y jq bc curl wget tmux python3 bzip2 unzip gzip

💡 技术拓展：这几个不起眼的包各自在 LinuxGSM 流水线里的分工——

工具 LinuxGSM 中的用途
jq 解析 GitHub API/游戏信息 JSON（info_game.sh 用它读版本元数据）
bc 系统需求检查里的浮点比较（内存/磁盘阈值判断）
tmux 托管游戏进程会话，console/debug 的基础
curl/wget 模块与游戏文件下载
python3 gsquery 等查询脚本运行器

其余依赖（binutils、file、pigz 等）LinuxGSM 会在 install 时对照发行版清单自动补装，见第五章。

工具	LinuxGSM 中的用途
jq	解析 GitHub API/游戏信息 JSON（info_game.sh 用它读版本元数据）
bc	系统需求检查里的浮点比较（内存/磁盘阈值判断）
tmux	托管游戏进程会话，console/debug 的基础
curl/wget	模块与游戏文件下载
python3	gsquery 等查询脚本运行器

2.2 资源与端口确认

free -h          # 内存：Minecraft 默认 -Xmx1024M，建议整机空闲内存 > 2GB
df -h            # 磁盘：serverfiles 约 130M，世界存档按需增长
ss -tlnp | grep 25565   # 确认游戏端口未被占用

实测该实例就绪后端口表（./mcserver details 的 Ports 段，见第六章）：

DESCRIPTION  PORT   PROTOCOL  LISTEN
Game         25565  tcp       1
Query        25565  udp       1
RCON         25575  tcp       0

三、创建专用运行用户

LinuxGSM 官方姿势是不用 root 跑游戏服。创建 lgsm 用户并授予免密 sudo（供 install 阶段自动补装依赖）：

useradd -m lgsm
echo 'lgsm ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/90-lgsm
chmod 440 /etc/sudoers.d/90-lgsm
su - lgsm

后续所有命令均在 lgsm 用户家目录 /home/lgsm 执行。切换后确认当前用户与家目录为 lgsm / /home/lgsm 再继续。

💡 说明：lgsm 的 uid（实测 1001）决定 tmux socket 目录名 /tmp/tmux-1001/，多实例排障时会用到，命令篇有对应实测。

四、下载安装器并生成实例脚本

官方安装入口一条命令（以 lgsm 用户执行）：

cd ~ && wget -O linuxgsm.sh https://linuxgsm.sh && chmod +x linuxgsm.sh && bash linuxgsm.sh mcserver

实测回显（关键行）：

2026-11-02 16:57:45 (82.6 MB/s) - 'linuxgsm.sh' saved [22071/22071]

fetching GitHub [ serverlist.csv ] ... OK
Installed Minecraft server as mcserver

bash linuxgsm.sh mcserver 校验了游戏短名 mcserver（来自 serverlist.csv 的 144 款支持列表），并在当前目录生成了实例管理脚本 ./mcserver（22071 字节，与下载回显的字节数一致）。

💡 说明：mcserver 与 linuxgsm.sh 此刻内容相同（都是 22071 字节的引导脚本），实例身份在运行时由脚本名确定——把脚本复制改名成别的游戏短名是不行的，短名必须命中 serverlist.csv。多实例姿势见命令篇。

五、安装 Minecraft 服务端（install）

5.1 先解决 Java 版本

Ubuntu 24.04 默认仓库的 Java 是 21，而 Minecraft 服务端 26.3 要求 Java 25。实测直接 install 会被拦下：

Failure! Minecraft latest requires Java 25; active Java is 21.
Select a compatible Java runtime with: sudo update-alternatives --config java

安装 openjdk-25-jre-headless 并切换默认 Java：

sudo apt install -y openjdk-25-jre-headless
sudo update-alternatives --config java   # 输入 25 对应编号
java -version

实测切换后的回显：

openjdk version "25.0.4.1" 2026-08-18

5.2 执行安装（交互确认的坑）

./mcserver install 会逐项询问确认（安装摘要、目录确认等）。非交互执行时它会直接报错退出，实测：

[ ERROR ] Installing mcserver: Unable to read an answer: no input available

两种正确姿势任选其一：

yes | ./mcserver install     # 管道喂确认
# 或
./mcserver auto-install      # 免提示安装

5.3 安装回显逐段解读

安装横幅（实测照抄，省略 ASCII 艺术图）：

=================================
LinuxGSM_
by Daniel Gibbs
Version: v26.4.0
Game: Minecraft
Website: https://linuxgsm.com
Contributors: https://linuxgsm.com/contrib
Sponsor: https://linuxgsm.com/sponsor
=================================

Server Directory
=================================
creating serverfiles directory [ /home/lgsm/serverfiles ] ... OK

Creating Log Directories
=================================
creating log directory [ /home/lgsm/log ] ... OK
creating script log directory [ /home/lgsm/log/script ] ... OK
creating script log [ /home/lgsm/log/script/mcserver-script.log ] ... OK
creating console log directory [ /home/lgsm/log/console ] ... OK
creating console log [ /home/lgsm/log/console/mcserver-console.log ] ... OK
creating game log directory [ /home/lgsm/serverfiles/logs ] ... OK
creating symlink to game log directory [ /home/lgsm/log/server -> /home/lgsm/serverfiles/logs ] ... OK

Checking Minecraft Dependencies
=================================
bc
binutils
bsdmainutils
bzip2
ca-certificates
cpio
curl
distro-info
file
gzip
hostname
jq
lib32gcc-s1
lib32stdc++6
openjdk version "25.0.4.1" 2026-08-18
pigz
python3
tmux
unzip
util-linux
uuid-runtime
wget
xz-utils
Warning! Missing dependencies: binutils bsdmainutils cpio distro-info file lib32gcc-s1 lib32stdc++6 netcat-openbsd pigz uuid-runtime xz-utils
Information! lgsm has sudo access.
Information! Automatically installing missing dependencies.

依赖清单里绿色/红色标注在纯文本下不可见，以 Warning 行为准：LinuxGSM 对照 ubuntu-24.04.csv 查出 10 个缺失包，检测到 sudo 权限后自动 apt 安装（实测拉入 26 个包、约 46 MB）。随后下载服务端本体与默认配置（进度条压缩为一行）：

downloading file [ minecraft_server.26.3.jar ]
######################################################################## 100.0%
downloading file [ minecraft_server.26.3.jar ] ... OK
clearing tmp directory [ /home/lgsm/lgsm/tmp ] ... OK

Downloading Minecraft Configs
=================================
Downloading default configs from: https://github.com/GameServerManagers/Game-Server-Configs

fetching GitHub [ server.properties ] ... OK
copying config file [ /home/lgsm/serverfiles/server.properties ] ... OK
setting hostname ... OK
generating admin/rcon password ... OK

结尾是匿名统计确认与安装完成提示（实测 common.cfg 里的 stats="on" 即这一步的产物）：

LinuxGSM Stats
=================================
Assist LinuxGSM development by sending anonymous stats to developers.
Collected data is publicly available: https://linuxgsm.com/data/usage
More info: https://docs.linuxgsm.com/configuration/linuxgsm-stats

The following info will be sent:
* game server
* distro
* game server resource usage
* server hardware info

Information! Stats setting is now enabled in common.cfg.
fetching GitHub [ install_complete.sh ] ... OK

Install Complete!
=================================

To start the Minecraft server type:
./mcserver start

5.4 验证安装结果

实测要点：安装产出 ~/serverfiles/ 下的 minecraft_server.jar（details 的启动命令行引用该文件，构建号为 26.3）与 server.properties（由 LinuxGSM 生成，其中 eula=true 已预置，无需手动补 EULA 文件）。配置文件骨架：

ls -l ~/lgsm/config-lgsm/mcserver/

total 32
-rw-rw-r-- 1 lgsm lgsm 5338 Nov  2 16:57 _default.cfg
-rw-rw-r-- 1 lgsm lgsm  192 Nov  2 16:59 common.cfg
-rw-rw-r-- 1 lgsm lgsm  189 Nov  2 16:58 mcserver.cfg
-rw-rw-r-- 1 lgsm lgsm  188 Nov  2 16:58 secrets-common.cfg
-rw-rw-r-- 1 lgsm lgsm  196 Nov  2 16:58 secrets-mcserver.cfg

四层配置如何覆盖、各参数含义见《LinuxGSM v26.4.0 配置参数详解》。

六、启动与状态检查

6.1 启动

./mcserver start

实测回显：

fetching GitHub [ linuxgsm.sh ] ... OK
fetching GitHub [ command_start.sh ] ... OK
[ .... ] Starting mcserver: fetching GitHub [ check_root.sh ] ... OK
fetching GitHub [ check_system_dir.sh ] ... OK
fetching GitHub [ check_executable.sh ] ... OK
fetching GitHub [ check_logs.sh ] ... OK
fetching GitHub [ check_config.sh ] ... OK
fetching GitHub [ check_status.sh ] ... OK
fetching GitHub [ core_logs.sh ] ... OK
[ .... ] Starting mcserver: LinuxGSM
[  OK  ] Starting mcserver: LinuxGSM
[  OK  ] Starting mcserver: LinuxGSM

首行 Starting mcserver: LinuxGSM 中的 "LinuxGSM" 是服务端 motd（默认服务器名），两行 [ OK ] 分别代表 tmux 会话建立与查询端口探活成功。

6.2 status 命令已不存在

习惯旧版的手会先试 status，实测 v26.4.0 直接报错：

Error! Unknown command: ./mcserver status
Usage: ./mcserver [option]

LinuxGSM - Minecraft - Version v26.4.0
https://linuxgsm.com/mcserver

Commands
start         st   | Start the server.
stop          sp   | Stop the server.
restart       r    | Restart the server.
monitor       m    | Check server status and restart if crashed.
...

💡 技术拓展：v26.4.0 里「看状态」的正确入口——

命令用途回答的问题
monitor 健康检查（异常自动拉起），cron 托管用活着吗？要不要救？
details 全量信息打印配置/资源/端口/状态长什么样？
console 附着 tmux 会话游戏日志实时在刷什么？

命令	用途	回答的问题
`monitor`	健康检查（异常自动拉起），cron 托管用	活着吗？要不要救？
`details`	全量信息打印	配置/资源/端口/状态长什么样？
`console`	附着 tmux 会话	游戏日志实时在刷什么？

完整命令清单与逐条实测见命令篇。

6.3 details 验证

./mcserver details

实测关键段（全量输出较长，此处照抄核心段落）：

Distro Details
================================================================================
Date:         Mon Nov  2 17:00:42 UTC 2026
Distro:       Ubuntu 24.04.5 LTS
Arch:         x86_64
tmux:         3.4
Java:         openjdk version "25.0.4.1" 2026-08-18

Minecraft Server Details
================================================================================
Server name:    LinuxGSM
Branch:         release
Server IP:      0.0.0.0:25565
Query enabled:  true
Maxplayers:     20
Game mode:      survival
Status:         STARTED

Command-line Parameters
================================================================================
java -Xmx1024M -jar ./minecraft_server.jar nogui

Status:	STARTED

再用游戏侧日志闭环验证世界已就绪（~/log/console/mcserver-console.log 实测片段）：

[17:00:14] [Server thread/INFO]: Starting minecraft server version 26.3
[17:00:14] [Server thread/INFO]: Starting Minecraft server on *:25565
[17:00:16] [Server thread/INFO]: Done (1.808s)! For help, type "help"
[17:00:16] [Query Listener #1/INFO]: Query running on 0.0.0.0:25565

6.4 monitor 验证

./mcserver monitor

实测回显：

[ .... ] Monitoring mcserver: Checking session ... CHECKING
[  OK  ] Monitoring mcserver: Checking session ... OK
[ .... ] Monitoring mcserver: Querying port: gsquery: 127.0.0.1:25565 : 0/1 ... QUERYING
[  OK  ] Monitoring mcserver: Querying port: gsquery: 127.0.0.1:25565 : 0/1 ... OK

会话在、端口通，两项 CHECKING→OK 即健康。

七、cron 保活托管

LinuxGSM 无常驻守护进程，官方保活方式是给 lgsm 用户配 crontab，每 5 分钟 monitor 一次：

crontab -e

加入实测在用的这一行：

*/5 * * * * bash /home/lgsm/mcserver monitor > /dev/null 2>&1

验证：

crontab -l

*/5 * * * * bash /home/lgsm/mcserver monitor > /dev/null 2>&1

💡 说明：monitor 发现进程死亡会尝试拉起并（启用告警时）发通知；> /dev/null 2>&1 抑制 cron 邮件。如果希望掉线时收到消息而不是静默自救，先配告警渠道（配置篇的 alerts 一节），再用 ./mcserver test-alert 验证链路（命令篇有全渠道未启用时的实测回显）。

八、停止、重启与目录结构

8.1 优雅停止

./mcserver stop

实测回显：

[ .... ] Stopping mcserver: LinuxGSM
[ .... ] Stopping mcserver: Graceful: sending "stop"
[ .... ] Stopping mcserver: Graceful: sending "stop": 1
[  OK  ] Stopping mcserver: Graceful: sending "stop": 2 ... OK

LinuxGSM 向游戏控制台注入 stop 指令等待世界落盘（Minecraft 对应 stopmode="5"），而不是直接杀 tmux——这是存档完整性的保障。重启用 ./mcserver restart。

8.2 安装后的目录全景

/home/lgsm/
├── mcserver                  # 实例管理脚本（所有命令的入口）
├── linuxgsm.sh               # 引导脚本（可删）
├── lgsm/
│   ├── config-lgsm/mcserver/ # 四层配置（_default/common/mcserver/secrets）
│   ├── modules/              # 从 GitHub 拉取的命令/检查模块缓存
│   ├── backup/               # backup 命令产物
│   ├── data/ lock/ tmp/      # 状态、锁、临时文件
│   └── config-default/       # 游戏默认配置模板
├── serverfiles/              # Minecraft 服务端本体（jar/libraries/server.properties/world）
└── log/
    ├── script/               # mcserver-script.log：每条 LinuxGSM 命令的执行日志
    ├── console/              # mcserver-console.log：游戏控制台流水
    └── server -> serverfiles/logs  # 游戏自身日志软链

排障时先看 log/script/（LinuxGSM 做了什么）再看 log/console/（游戏发生了什么），命令篇有完整实例。

九、卸载与清理

按依赖反向清理（root 或 lgsm 用户执行）：

./mcserver stop                    # 1. 停服
crontab -r                         # 2. 清 lgsm 的保活 cron
rm -rf ~/mcserver ~/linuxgsm.sh    # 3. 删实例脚本与引导脚本
rm -rf ~/lgsm ~/serverfiles ~/log  # 4. 删 LinuxGSM 与游戏文件（备份先拷走）

root 侧收尾：

rm -f /etc/sudoers.d/90-lgsm
userdel -r lgsm

验证家目录与 crontab 均已不存在即清理完成。游戏世界存档如需保留，卸载前用 ./mcserver backup 产物（~/lgsm/backup/*.tar.gz）转移。

十、参考链接

官方安装文档：https://docs.linuxgsm.com/start
官方站点与游戏列表：https://linuxgsm.com/
Minecraft 服务端版本要求：https://www.minecraft.net/en-us/download/server
LinuxGSM GitHub 仓库：https://github.com/GameServerManagers/LinuxGSM
本专栏选型篇：《LinuxGSM v26.4.0 介绍与选型指南》