LinuxGSM v26.4.0 配置参数详解

目标：把 LinuxGSM v26.4.0 的配置体系一次讲透——_default.cfg → common.cfg → <实例>.cfg → secrets-*.cfg 四层模型的优先级与适用边界，启动参数（javaram/startparameters/branch/mcversion）、告警渠道、生命周期保护、备份与日志、querymode/stopmode 等高级项逐项解释，并给出游戏侧 server.properties 关键项。所有参数效果均经实机验证（实测时间 2026-11-02），含 --force-gamemode 误配秒退与 javaram="512" 极限压缩两处真实案例。安装过程见《Ubuntu 24.04 安装 LinuxGSM v26.4.0 指南》。

一、环境信息

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

• 操作系统：Ubuntu 24.04.5 LTS（x86_64），Java：openjdk 25.0.4.1
• 实测时间：2026-11-02
• LinuxGSM 版本：v26.4.0；游戏实例：mcserver（Minecraft 服务端 26.3，分支 release）
• 运行用户：lgsm（家目录 /home/lgsm）；示例登录账号 root / admin，口令 q1w2e3r4
• 配置目录：~/lgsm/config-lgsm/mcserver/；游戏配置：~/serverfiles/server.properties
• 软件背景与选型：《LinuxGSM v26.4.0 介绍与选型指南》

二、四层配置模型

2.1 文件清单（实测）

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

四层职责与优先级（低 → 高）：

_default.cfg 头部注释原文即是规则（实测照抄）：

##################################
######## Default Settings ########
##################################
# DO NOT EDIT, ANY CHANGES WILL BE OVERWRITTEN!
# Copy settings from here and use them in either:
# common.cfg - applies settings to every instance.
# [instance].cfg - applies settings to a specific instance.

2.2 加载与覆盖机制

LinuxGSM 启动实例时按「_default.cfg → common.cfg → mcserver.cfg → secrets-common.cfg → secrets-mcserver.cfg」顺序 source 同名变量，后层覆盖前层。判断某参数当前生效值的方法：改完配置 ./mcserver restart，用 ./mcserver details 核对（见第九章验证法）。

💡 技术拓展：「同名变量后层覆盖」与常见配置体系的对照——

体系	合并方式	与 LinuxGSM 的差异
systemd drop-in（*.d/*.conf）	键级合并，可局部覆盖	LinuxGSM 是整变量覆盖，无局部合并
Nginx http/server/location	层级继承	LinuxGSM 无层级，只有全局/实例两层
shell profile 系列	顺序 source，后者赢	与 LinuxGSM 完全同构，配置就是 shell 赋值

因此 LinuxGSM 配置值必须写成合法 bash 赋值（key="value"），注释用 #，不能塞任意格式。

2.3 实例层与 secrets 层实测内容

新装实例的 mcserver.cfg / secrets-mcserver.cfg 只有模板注释（实测）：

##################################
####### Instance Settings ########
##################################
# PLACE INSTANCE SETTINGS HERE
## These settings will apply to a specific instance.

common.cfg 则因安装尾段的统计确认多了一行（实测）：

stats="on"

告警 webhook 这类敏感值放 secrets-mcserver.cfg，例如：

discordwebhook="https://discord.com/api/webhooks/xxxx/yyyy"

postdetails 命令上传信息时会自动剔除密码类字段（命令篇实测），secrets 层的存在就是为了让「粘贴求助」不泄露凭据。

三、启动参数组（改得最多的一组）

3.1 javaram —— JVM 堆上限

_default.cfg 默认（实测）：

javaram="1024" # -Xmx$1024M

它被拼进启动命令的 -Xmx${javaram}M。在 mcserver.cfg 写 javaram="2048" 后 restart，details 的 Command-line Parameters 变为（实测）：

java -Xmx2048M -jar ./minecraft_server.jar nogui

极限实测：改 javaram="512" 后 restart，ps -ef 确认参数生效且服务端正常就绪：

lgsm  41771  ...  tmux -L mcserver-24e91d1d new-session -d -x 80 -y 23 -s mcserver java -Xmx512M -jar ./minecraft_server.jar nogui
lgsm  41772  ...  java -Xmx512M -jar ./minecraft_server.jar nogui

details 显示 Mem Used: 3% 483MB——空载 Minecraft 26.3 在 512 MB 堆下可运行。结论：小圈子服 512 MB 够用，人多或加 Mod 再上调。

💡 技术拓展：-Xmx 是堆上限（max heap），不是预留——

概念	含义	实测佐证
-Xmx512M	堆最大 512 MB，超了抛 OutOfMemory	javaram=512 空载实际 RSS 483 MB
预留内存	JVM 默认不预留，随用随向 OS 要	空载与有人时占用不同
整机 OOM	堆超限后 JVM 内部崩，堆超物理才触发系统 OOM killer	monitor 会把崩溃会话拉起

规划原则：javaram 总和（同机所有 Java 服）+ 系统开销 < 物理内存。

3.2 startparameters —— 追加启动参数

默认只有（实测）：

startparameters="nogui"

失败案例实测：把它改成 startparameters="nogui --force-gamemode" 后 ./mcserver start：

[ .... ] Starting mcserver: LinuxGSM 5b9e6d4b670d
[ FAIL ] Starting mcserver: Unable to start LinuxGSM 5b9e6d4b670d

details 显示 Status: STOPPED，~/log/console/mcserver-console.log 尾部是 Java 参数解析异常 joptsimple.UnrecognizedOptionException——--force-gamemode 是 server.properties 里的配置键（force-gamemode=false），不是 jar 的命令行选项，塞进 startparameters 直接导致进程秒退。改回 startparameters="nogui" 后 restart 成功（实测）：

[ .... ] Starting mcserver: LinuxGSM Test Server
[  OK  ] Starting mcserver: LinuxGSM Test Server
[  OK  ] Starting mcserver: LinuxGSM Test Server

教训：startparameters 只放 jar 认可的命令行参数；Minecraft 的行为开关几乎都在 server.properties（第八章）。

3.3 branch 与 mcversion —— 版本通道

_default.cfg 默认（实测）：

branch="release"
mcversion="latest"

branch 可选 release|snapshot（官方分支/快照），mcversion 在 latest 之外可钉住历史版本。details 的 Branch: release 与 check-update 回显的 * Branch: release 是核对入口（命令篇实测：Local build: 26.3 / Remote build: 26.3）。

四、告警与通知参数组

_default.cfg 告警段实测节选（全部默认 off）：

## Notification Alerts
# (on|off)
displayip=""
postalert="off"
statusalert="off"

discordalert="off"
discordwebhook="webhook"
emailalert="off"
email="email@example.com"
emailfrom=""
gotifyalert="off"
gotifytoken="token"
gotifywebhook="webhook"
iftttalert="off"
ifttttoken="accesstoken"
iftttevent="linuxgsm_alert"
ntfyalert="off"
ntfytopic="LinuxGSM"
ntfyserver="https://ntfy.sh"
matrixalert="off"
matrixhomeserver="matrix.org"
matrixtoken="accesstoken"
matrixroom=""
pushbulletalert="off"
pushbullettoken="accesstoken"
channeltag=""
pushoveralert="off"
pushovertoken="accesstoken"
pushoveruserkey="userkey"
rocketchatalert="off"
rocketchatwebhook="webhook"
slackalert="off"
slackwebhook="webhook"
telegramapi="api.telegram.org"
telegramalert="off"
telegramtoken="accesstoken"
telegramchatid=""
curlcustomstring=""

要点：

• 渠道开关 + 凭据成对：每个渠道一个 *alert="on|off" 加若干 token/webhook 键，凭据写进 secrets-*.cfg；
• statusalert：启/停/重启也发通知（默认只发异常）；
• displayip：通知里显示的公网 IP，NAT 后面可手工指定；
• postalert="on"：告警后自动 postdetails 附诊断链接；
• curlcustomstring：Telegram 渠道的 cURL 附加参数（如 --socks5 ipaddr:port 走代理）；
• stats：匿名使用统计（与告警无关），common.cfg 实测为 stats="on"，可在其中改 off。

配好后用 ./mcserver test-alert 验证链路——全渠道未启用时的实测回显见命令篇（12 行 WARN ... not enabled）。

五、生命周期与保护参数组

_default.cfg 实测节选：

## Stop
stoponlyifnoplayers="off"
stoponlyifnoplayersallcommands="on"

## Player Warnings
warnplayerstimer="0"

## Updating
updateonstart="off"

• stoponlyifnoplayers：有人在服时拒绝 stop/restart/update，防误操作踢人；stoponlyifnoplayersallcommands 控制该保护是否扩展到全部命令；
• warnplayerstimer：设 15 则停/重启/更新前 15、10、5、3、1 分钟向游戏内广播警告（0 为关闭）；
• updateonstart：start 前先跑 update，配合 cron 可实现「每天凌晨更新并重启」。

stopmode（实测默认 stopmode="5"）——优雅停止策略编号，_default.cfg 注释原文：

# 1: tmux kill
# 2: CTRL+c
# 3: quit
# 4: quit 120s
# 5: stop
# 6: q
# 7: exit
# 8: 7 Days to Die
# 9: GoldSrc
# 10: Avorion
# 11: end

Minecraft 用 5（向控制台发 stop，等待世界落盘），实测 stop 回显即 Graceful: sending "stop"（安装篇）。1 是硬杀 tmux，仅在卡死时用。

六、备份与日志参数组

_default.cfg 实测节选：

## Backup
maxbackups="4"
maxbackupdays="30"
stoponbackup="on"

## Logging
consolelogging="on"
logdays="7"

## Monitor
querydelay="1"

## ANSI Colors
ansi="on"

• backup 产物落 ~/lgsm/backup/，保留策略为「最多 4 份 且 最多 30 天」双条件；
• stoponbackup="on"（默认）：备份前停服——实测 backup 回显先 mcserver will be restarted 倒计时、发 stop、压缩、再 start（命令篇全量回显）；存档一致性要求高的场景不要关它；
• consolelogging：把 tmux 控制台流水写到 ~/log/console/，logdays 控制保留天数；
• querydelay：monitor 端口探测的重试间隔秒数；
• ansi：命令行彩色输出开关，脚本抓取日志时建议临时关。

另有 logtimestamp="off" / logtimestampformat="%Y-%m-%d %H:%M:%S" 控制 LinuxGSM 自身日志时间戳格式。

七、高级参数组

_default.cfg 实测节选：

sleeptime="0.5"

## Query mode
# 1: session only
# 2: gamedig (gsquery fallback)
# 3: gamedig
# 4: gsquery
# 5: tcp
querymode="2"
querytype="minecraft"

## Console type
consoleverbose="yes"
consoleinteract="yes"

## Game Server Details
# Do not edit
gamename="Minecraft"
engine="lwjgl2"
glibc="null"

• querymode 决定 monitor/details 如何「问」游戏服在线状态：默认 2 = 优先 gamedig（Node 生态的查询器，LinuxGSM 内置其 Python 回退 gsquery）。实测 monitor 回显 Querying port: gsquery: 127.0.0.1:25565——说明本环境走了 gsquery 回退路径；查询失败会让 monitor 误判，排障时可用 1（只查 tmux 会话）隔离变量；
• consoleverbose：debug/console 是否转发游戏输出；consoleinteract：console 会话可否输入（改 no 变只读）；
• gamename/engine/glibc 标注 Do not edit，是游戏元数据；
• 目录变量段（systemdir/executable/servercfgfullpath/backupdir 等）同样不建议动，实测 Minecraft 的关键值：executable="./minecraft_server.jar"、servercfg="server.properties"、backupdir="${lgsmdir}/backup"。

💡 技术拓展：gamedig 与 gsquery 都是「Server Query 协议」客户端——

查询方式	协议	端口	说明
gamedig	GameServer Query / 各类专有协议	多为 UDP query 端口	支持游戏面广
gsquery	GS2/Source Query	UDP	LinuxGSM 自带的 Python 回退实现
tcp	专有 TCP 状态协议	游戏端口	部分游戏适用

Minecraft 对应 server.properties 的 enable-query=true + query.port（实测默认已开、同 25565）。关掉 query 后 monitor 只能靠会话存在性判断，「进程活着但假死」将无法被发现。

八、游戏侧配置：server.properties

LinuxGSM 的四层 cfg 管「怎么把进程拉起来」，游戏行为参数在 ~/serverfiles/server.properties（details 的 Config file: 行实测指向它）。关键项实测节选（凭据已打码）：

motd=LinuxGSM Test Server
max-players=30
gamemode=survival
difficulty=easy
online-mode=true
white-list=false
server-port=25565
query.port=25565
enable-query=true
enable-rcon=false
rcon.port=25575
rcon.password=<安装时随机生成，见 details 的 RCON password 行>
view-distance=10
simulation-distance=10
spawn-protection=16
enforce-secure-profile=true
eula=true
management-server-enabled=false
management-server-secret=<32 位随机值，打码>

实测生效验证：

• max-players=30：改后 restart，details 显示 Maxplayers: 30（默认模板为 20）；
• motd=LinuxGSM Test Server：details 的 Server name: 行、start/stop 回显里的实例名全部随之变化——motd 即 LinuxGSM 眼里的「服务器名」；
• management-server-secret：新版 Minecraft 服务端自动生成的管理接口凭据，属敏感值，分享 server.properties 前务必打码（postdetails 只处理 LinuxGSM 层，不处理游戏配置文件里的全部键）。

💡 技术拓展：motd 一词的两种语境——

语境	含义
传统 SSH（/etc/motd）	登录服务器时的提示文本
Minecraft server.properties	服务器列表里显示的标题文本（可含颜色代码）

本文与 LinuxGSM 回显中的 motd 均指后者。

九、配置改动的标准验证法

每改一处，走同一条闭环（实测有效）：

./mcserver restart
./mcserver details | grep -A3 "Command-line Parameters"
ps -ef | grep minecraft_server.jar | grep -v grep
tail -n 20 ~/log/console/mcserver-console.log

对照关系：javaram/startparameters 看 Command-line Parameters 与 ps；max-players/motd 看 details 的 Maxplayers/Server name；起不来先看 console 日志（3.2 的 --force-gamemode 案例即如此定位）。命令级工具（details/monitor/debug/send）的完整用法见《LinuxGSM v26.4.0 常用 CLI 命令与工具详解》。

十、参考链接

• 官方配置文档：https://docs.linuxgsm.com/configuration
• 启动参数说明：https://docs.linuxgsm.com/configuration/start-parameters
• 告警渠道文档：https://docs.linuxgsm.com/alerts
• LinuxGSM Stats：https://docs.linuxgsm.com/configuration/linuxgsm-stats
• Game-Server-Configs 仓库（server.properties 默认模板来源）：https://github.com/GameServerManagers/Game-Server-Configs
• Minecraft 服务端配置项参考：https://minecraft.wiki/w/Server.properties
• 本专栏安装篇：《Ubuntu 24.04 安装 LinuxGSM v26.4.0 指南》