auto-mcs 2.3.9 配置参数详解

目标：以一台在跑的 auto-mcs 2.3.9 Docker 实例为对象，把四层配置（容器环境变量 / 实例级 app-config.json / 服务器级 .auto-mcs.ini / Minecraft server.properties）的每个关键参数讲清默认值、实测值、修改途径与生效验证。全部参数值与回显为 2026-11-02 实测。部署环境见 《auto-mcs Docker Compose 部署指南》，命令操作见 《auto-mcs 2.3.9 常用 CLI 命令与工具详解》。

一、环境信息

二、前置条件

• 已按 部署指南 起栈并至少建过一台服务器（本文大量参数以 Test Server 实测值举例）；
• 进容器看文件：docker exec -it auto-mcs-2.3.9-panel sh；
• 改服务器级/Minecraft 级参数的推荐通道是桌面 GUI 经 Telepath 配对（headless 功能子集限制，见第七章 FAQ）。

三、参数查看与修改方式

auto-mcs 没有统一的"配置文件一把梭"，四层配置各有查看/修改途径：

headless CLI 自带的 server.properties 安全编辑器实测：server properties Test Server 打开键值表界面（ESC - save & quit, CTRL+F - search），退出回显 Successfully saved 'server.properties'。

四、参数总览

实测数据目录全景（2026-11-02）：

/root/.auto-mcs
├── Config/app-config.json        # 实例级（本文第五章 5.1）
├── Servers/Test Server/
│   ├── .auto-mcs.ini             # 服务器级（5.2）
│   ├── server.properties         # Minecraft 级（5.3）
│   ├── Start.sh                  # 由配置生成的 JVM 启动命令（5.4）
│   ├── .start-cmd.tmp            # 开服后自动执行的命令（模板 gamerule 落地）
│   └── server.jar / eula.txt
├── Tools/templates/*.yml         # 建服模板（5.5）
├── Tools/telepath/telepath-secrets  # Telepath PKI 密钥（敏感，勿外传）
├── Backups/*.amb / Cache/ / Logs/application/

五、核心参数分类详解

5.1 实例级 Config/app-config.json（实测全文）

{
  "fullscreen": false,
  "geometry": {},
  "auto_update": true,
  "locale": "en",
  "master_volume": 100,
  "sponsor_reminder": null,
  "discord_presence": true,
  "prompt_feedback": true,
  "enable_ip_lookup": true,
  "java_vendor": "oracle",
  "telepath_settings": {
    "enable-api": false,
    "api-host": "0.0.0.0",
    "api-port": 7001,
    "show-banners": true,
    "id_hash": "9bec5504a73f9c98bace0f35cda2dd3b334ecf738c0717cfdbd62f5442b655cb"
  },
  "ide_settings": { "fullscreen": false, "font-size": 15, "geometry": {} }
}

逐项：

telepath_settings 子树（重点）：

5.2 服务器级 Servers/<名>/.auto-mcs.ini（实测全文）

[general]
serverName = Test Server
serverVersion = 26.3
serverBuild = 237
serverType = paper
isFavorite = false
allocatedMemory = auto
enableGeyser = false
enableProxy = false
updateAuto = prompt
viewedNotifs = {}

[bkup]
bkupAuto = prompt
bkupMax = 5
bkupDir = /root/.auto-mcs/Backups

5.3 Minecraft 级 server.properties（Paper 26.3 实测关键项）

完整文件 80+ 键，列运维必改项（其余按 Minecraft 通用语义）：

5.4 派生配置：Start.sh 与 .start-cmd.tmp

• Start.sh 是 auto-mcs 按 5.2 的 allocatedMemory + 内置 Aikar's flags 生成的启动命令，实测（auto 档、16GB 宿主）：

/usr/lib/jvm/java-25-openjdk/bin/java -Xmx4G -Xms2G -XX:+UseG1GC ... -XX:G1NewSizePercent=30 ... -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true ... -jar server.jar nogui

开服后用 docker exec <容器> ps -ef | grep java 验证 -Xmx 实际值即配置生效证据。

• .start-cmd.tmp 是开服后自动注入的命令清单，实测内容来自建服模板的 gamerule 段（gamerule keep_inventory false 等 4 条），控制台对应回显 System chat: Game rule keep_inventory is already set...。

5.5 建服模板 Tools/templates/*.yml

出厂四模板：stock.yml / optimized.yml / creative.yml / bedrock.yml。以 optimized.yml 实测结构为例：

server:
  type: fabric          # 发行版
  version: latest       # 版本
  settings:
    playit: true        # 自动开隧道（对应 5.2 enableProxy）
    addons: [lithium, lmd, almanac, moonrise, ferritecore, clumps]  # Modrinth 插件清单
    geyser_support: false
    world: { path: null, seed: null, level_type: default }
    difficulty: normal
    gamemode: survival
    spawn_creatures: true
    spawn_protection: false
    pvp: false
    max_players: 20
    keep_inventory: false
    random_tick_speed: 3

模板字段与 5.2/5.3 参数一一对应——用模板建服等于批量写这两层配置。

六、生产配置模板

面向"VPS 单人朋友服"的推荐终态（本实测栈即按此思路）：

# docker-compose.yml 环境变量：三项必须显式设置
environment:
  WEB_PORT: "8080"
  WEB_USERNAME: "root"
  WEB_PASSWORD: "<强口令>"     # 默认值会被镜像拒绝启动

# Config/app-config.json 推荐调整
{
  "auto_update": false,          # 升级走换镜像 tag，避免失控
  "discord_presence": false,     # 服务器无需展示在线状态
  "enable_ip_lookup": false,     # 容器出网受限时关掉，消除报错
  "java_vendor": "temurin",      # 若 oracle 源不稳可换（java list 实测 4 家可选）
  "telepath_settings": {
    "api-host": "0.0.0.0",       # 公网机器：防火墙挡 7001，或套 WireGuard 后绑内网地址
    "api-port": 7001
  }
}

# .auto-mcs.ini 推荐（GUI 内设置）
allocatedMemory = <按宿主余量定档，勿长期依赖 auto>
updateAuto = prompt              # 保留人工确认
bkupMax = 5
bkupDir = /root/.auto-mcs/Backups  # 或改挂网盘同步目录

# server.properties 推荐
online-mode=true                 # 能开就开
white-list=true                  # 配合 Access Control 加人
view-distance=8
simulation-distance=8

安全三件套（全部实测相关）：① WEB_PASSWORD 非默认（镜像强制）；② 7001 不对公网裸开（Telepath 会话除认证外明文，官方建议 VPN）；③ telepath-secrets 与 management-server-secret 不截图、不入日志仓。

七、常见问题（排障实录）

7.1 enable-api: false 但 7001 仍在监听

• 现象：配置文件写 false，curl http://127.0.0.1:7001/openapi.json 却返回 200（服务名 auto-mcs - Telepath API，版本 1.2.2）。
• 定位：Docker/headless 实例启动时 API 随进程初始化；telepath start|stop 是运行时开关且不回写配置（实测两向切换均即时生效、app-config.json 保持 false 不变）。
• 解决：以运行时状态为准，不需要远程管理就执行 telepath stop；持久关闭需在桌面 GUI 的 Telepath 菜单操作（或防火墙挡端口）。

7.2 allocatedMemory = auto 到底给了多少？headless 怎么改？

• 现象：ini 里只有 auto，看不出实际堆大小。
• 定位：auto 按宿主可用内存定档，实测 16GB 宿主生成 -Xmx4G -Xms2G（证据在 Start.sh 与 ps -ef | grep java）；官方文档口径是"滑杆 + GC 自动调优，仅在出现 java.lang.OutOfMemoryError: Java heap space 崩溃时再调大"。
• 解决：headless CLI 没有内存设置命令（server properties 只管 server.properties）；改档位需 GUI（本地或 Telepath 配对远端 GUI）。内存紧张的小 VPS 建议先经 GUI 定档再开服，避免 auto 超配。

7.3 playit 隧道在 headless 下开不了

• 现象：playit enable Test Server 回显 a playit.gg account must first be linked using the GUI over Telepath。
• 定位：playit 账号链接是 GUI-only 流程，headless 仅继承结果（ini enableProxy）。
• 解决：桌面版 auto-mcs 经 Telepath 配对本实例后在 GUI 内链接 playit 账号；或建服时用带 playit: true 的模板（仍需账号链接一次）。

7.4 界面地址显示 172.17.0.1 而不是公网 IP

• 现象：控制台状态栏与 !info 显示 Address: 172.17.0.1:25565；应用日志报 get_public_ip ... api.ipify.org ... Connection refused。
• 定位：enable_ip_lookup: true 但容器出网受限，公网 IP 查询失败后回退为默认路由地址。
• 解决：放开容器出网，或把 enable_ip_lookup 置 false 消除噪音；对外连接地址以你的 NAT/隧道实际入口为准。

7.5 应用日志警告 running with admin-level permissions

• 现象：Logs/application/*.log 有 [WARNING] constants.is_admin: auto-mcs is running with admin-level permissions。
• 定位：官方镜像即以 root 运行（Dockerfile VOLUME /root/.auto-mcs），Docker 场景属预期。
• 解决：无需处理；在意则不要给容器多余 capability/挂载 docker.sock。

7.6 手改 .auto-mcs.ini 后行为异常

• 现象：直接编辑 ini 后参数不生效或界面显示错乱。
• 定位：文件首行官方警告 DON'T MODIFY THE CONTENTS OF THIS FILE——它由 GUI 写入、字段格式无文档承诺（如 allocatedMemory 档位值格式未知）。
• 解决：ini 只读不改；要改参数走 GUI/Telepath，改完用 cat 回读确认 GUI 已落盘。

八、参考链接

• 官方设置指南（GUI 参数语义）：https://www.auto-mcs.com/guides/settings （memory/Geyser/playit/自动更新各节，查询 2026-11-02）
• 官方 Telepath 指南：https://www.auto-mcs.com/guides/telepath （PKI 认证与明文会话警告）
• Docker Hub 镜像页（环境变量与权限注记）：https://hub.docker.com/r/macarooniman/auto-mcs
• Aikar's Flags 调优说明：https://mcflags.emc.gs （Start.sh 中 GC 参数出处）
• 同专栏：《auto-mcs 介绍与选型指南》、《auto-mcs Docker Compose 部署指南》