auto-mcs 2.3.9 常用 CLI 命令与工具详解

auto-mcs 2.3.9 headless/Docker 全命令面实测详解：顶层 12 命令与 server 10 子命令逐条真实回显，建服→开服→控制台 ! 系列→备份→删除闭环演示，Telepath API 端点与运行时开关验证，含引号参数踩坑、C-c 崩会话、apk 装 Java、playit 需 GUI 首链等 6 条排障实录，全部 2026-11-02 实测。

auto-mcsauto-mcsMinecraft游戏服务器面板自托管2026/11/03

auto-mcs 2.3.9 常用 CLI 命令与工具详解

目标：把 auto-mcs 2.3.9 headless/Docker 形态下的全部命令面讲透——顶层 12 个命令、server 的 10 个子命令、控制台 ! 系列内置命令、Telepath API 端点，每条都配 2026-11-02 实测真实回显；并给出建服→开服→控制台→备份→删除的完整闭环演示。环境为 《auto-mcs Docker Compose 部署指南》 的在跑栈，参数背景见 《auto-mcs 2.3.9 配置参数详解》。

一、环境信息

项目值
实例auto-mcs-2.3.9-panel（镜像 macarooniman/auto-mcs:2.3.9）
版本回显v2.3.9-beta.1822 - Alpine Linux 3.23.5 (k-7.0.0, 64-bit, Docker)
Telepath APIv1.2.2，容器内 0.0.0.0:7001
Web 终端http://<宿主IP>:8132，root / q1w2e3r4
会话载体ttyd → tmux 会话 auto-mcs → /auto-mcs（headless）
演示服务器Test Server（Paper 26.3 b237）；另建临时 Quick Test 演示创建/删除
实测日期2026-11-02

进入 CLI 的两种方式：浏览器打开 Web 终端登录后即得（首个连接会创建 tmux 会话）；或宿主侧驱动：

docker exec auto-mcs-2.3.9-panel tmux attach -t auto-mcs          # 交互式
docker exec auto-mcs-2.3.9-panel tmux send-keys -t auto-mcs 'server list' Enter   # 脚本式
docker exec auto-mcs-2.3.9-panel tmux capture-pane -p -t auto-mcs                 # 取回显

二、工具概览

顶层命令面（实测 help 回显）：

❯ Available commands:
 - Type help <command> for syntax

help   exit   server   console   backup   telepath   java   playit   version
 debug   update
命令子命令（实测 usage 行）用途
serverlaunch|stop|kill|restart|list|info|properties|create|import|delete服务器全生命周期
consoleconsole <server name>附着到指定服务器控制台
backupsave|restore备份/恢复（按名）
telepathstart|stop|pair|users|restrict|revoke|reset远程管理 API 与配对
javalist|vendorJVM 供应商查看/切换
playitenable|disableplayit.gg 隧道开关
updateinfo查看变更日志/自更新
debugstatus|log|enable|disable会话调试日志
version / help / exit—版本/帮助/退出

三、前置条件

  • 栈已起、Web 终端 401/200 验证通过（见部署指南第四、五章）；
  • 参数不带引号：服务器名含空格直接裸写（如 server info Test Server）。带引号是实测踩坑（FAQ 6.1）；
  • 服务器名建议用字母+空格的自然语言风格，CLI 按"剩余全部参数拼名字"解析。

四、各命令详解（子命令 + 参数 + 真实回显）

4.1 version 与 help

❯ v2.3.9-beta.1822 - Alpine Linux 3.23.5 (k-7.0.0, 64-bit, Docker)

help <命令> 给出语法行，格式统一为 >> <用法>，例如：

❯ create usage:
 - creates a server on a specified type/version

>>  server create <type:version> <server name>

❯ launch usage:
 - launches a server by name

>>  server launch <server name>

4.2 server create：建服

官方口径 <type:version> <name>，type 支持 9 种发行版（vanilla/paper/purpur/fabric/quilt/neoforge/forge/spigot/craftbukkit）。实测：

❯ Successfully created Quick Test (Paper 26.3)

 - to modify this server, run telepath pair to connect from a remote
instance of auto-mcs

 - to launch this server, run server launch Quick Test

要点：建服即下载对应 server.jar（走 PaperMC 官方源）并生成目录骨架（server.properties、eula.txt、Start.sh、.auto-mcs.ini），eula.txt 自动置 eula=true（实测文件含官方 EULA 注释行）。创建回显直接告诉你下一步命令，无需查文档。

4.3 server list / info

❯ Installed Servers * - active (1 total):

Test Server

❯ Server info - Test Server

A Minecraft Server
Paper 26.3 (b237)

 < not running >

* 标记当前活动视图对象；运行中时 info 显示实际地址与状态（见 4.5）。

4.4 server launch：开服与控制台附着

server launch <名> 直接进入该服控制台界面。实测首启触发 Java 自动安装：

 │ 4:26:12 PM   INIT █   Launching 'Test Server', please wait...
 │ 4:26:12 PM   INFO █   Installing 'oracle-java25'...

（apk add openjdk25 30 包约 5 分钟，见部署指南 FAQ 10.4。）就绪后状态栏：

 ┌───────────────┐  ┌───── Test Server ─────┐  ┌──────────────────────────────┐
 │    up-time:   │  │                       │  │                          0%  │
 │  00:00:00:38  │  │   A Minecraft Server  │  │  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀   CPU  │
 │               │  │       Paper 26.3      │  │                              │
 │    players:   │  │                       │  │  ▄▄▄                  15.1%  │
 │     0 / 20    │  │   > 172.17.0.1:25565  │  │  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀   RAM  │
 └───────────────┘  └───────────────────────┘  └──────────────────────────────┘

底部提示 ❯❯ enter command, or 'ESC' to detach...——ESC 脱离回主 CLI：

❯ Run console Test Server to re-attach to the console

堆参数落地验证（实测 ps）：/usr/lib/jvm/java-25-openjdk/bin/java -Xmx4G -Xms2G -XX:+UseG1GC ... -jar server.jar nogui——auto 内存档与 Aikar's flags 生效证据（参数语义见配置篇 5.2/5.4）。

4.5 控制台命令：Minecraft 原生 + auto-mcs 的 ! 系列

控制台内直接输入即为 Minecraft 服务端命令，实测：

 │ 4:33:11 PM   EXEC █   Console issued server command: /list
 │ 4:33:11 PM   INFO █   System chat: There are 0 of a max of 20 players online:

! 前缀是 auto-mcs 注入的跨发行版命令（Vanilla 兼容），实测 !help 两页全清单：

命令官方描述（实测回显）
!helpView the auto-mcs command directory (auto-mcs provided)
!infoView server information (auto-mcs provided)
!stopStops the server with optional delay (seconds) (auto-mcs provided)
!restartStops and restarts with optional delay (seconds) (auto-mcs provided)
!backupManage server back-ups in-game (auto-mcs provided)
!aclView access control configuration in-game (auto-mcs provided)
!amsManage amscript in-game (auto-mcs provided)（第 2 页仅此一条）

!info 实测回显：

 │ --------------- Server Information ---------------
 │ auto-mcs v2.3.9 - running "Test Server"
 │ Version:   Paper 26.3
 │ Address:   172.17.0.1:25565
 │ Uptime:    00:00:01:46
 │ Players:   0 / 20
 │ CPU:       0.0%
 │ RAM:       15.08%

（Address 显示 172.17.0.1 是容器内 IP 查询回退，见配置篇 FAQ 7.4。）

4.6 server properties：headless 内置编辑器

❯ server properties Test Server

  1  # Minecraft server properties
  2  # Mon Nov 02 16:31:21 GMT 2026
  3  accepts-transfers    =  false
  4  allow-flight         =  true
  ...
                       ESC - save & quit, CTRL+F - search

键值表界面 + 键搜索，ESC 保存回显 Successfully saved 'server.properties'。这是 headless 下唯一官方支持的 properties 修改通道（防手滑写坏设计）。

4.7 backup save / restore

❯ backup save Test Server
❯ Saved a back-up of Test Server

产物落 bkupDir（默认 /root/.auto-mcs/Backups），实测命名规律 <服务器名>__HH.MM DD-MM-YY.amb：

-rw-r--r-- 1 root root  55276544 Test Server__15.31 11-02-26.amb
-rw-r--r-- 1 root root 233411072 Test Server__16.33 11-02-26.amb

实测细节：运行中可直接 save（服务器不停）；restore 按同格式选文件恢复。大操作（更新/换 jar/换世界）前 GUI 会按 bkupAuto=prompt 询问。

4.8 server stop / kill / restart / delete

  • server stop <名>：优雅停服，实测回显后 ps -ef | grep java 计数归 0；
  • server kill：强杀（无回显差异取证，语义按 usage "kill" 直译——崩溃卡死时用）；
  • server restart <名>：停后重开；
  • server delete <名>：实测自动先备份再删除：
❯ Deleted Quick Test and saved a back-up

对应 Backups/ 立即多出 Quick Test__16.38 11-02-26.amb。误删可用 backup restore 找回。

4.9 telepath 系列与 API 端点

运行时开关实测（配置语义见配置篇 5.1）：

❯ telepath stop
❯ disabled API on '0.0.0.0:7001'          ← 此后 curl 拒连

❯ telepath start
❯ initialized API on '0.0.0.0:7001'       ← 恢复 200

❯ telepath users
❯ There are no authenticated Telepath users. Please run telepath pair first to pair a client

❯ telepath pair
❯ Listening to pair requests for 177s (CTRL-C to cancel)
Enter the IP above into another instance of auto-mcs to continue

（telepath pair 等待期间不要按 C-c——实测会把整个 tmux 会话打崩，见 FAQ 6.3。）

API 端点实测（openapi 3.1.0，标题 auto-mcs - Telepath API，版本 1.2.2）：

$ curl -s http://127.0.0.1:7001/telepath/check_status
true                                     # 健康检查（GET）

$ curl -s http://127.0.0.1:7001/telepath/get_public_key
"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq..."   # PKI 公钥（GET）

$ curl -s -X POST -d '{}' http://127.0.0.1:7001/main/open_remote_server
{"detail":"Not authenticated"}           # 未配对一律 401

主要路径分组：/telepath/*（check_status、get_public_key、request_pair、submit_pair、login、logout）、/main/*（telepath_banner、open_remote_server、upload_file、download_file）、/ServerObject/*（对远端服务器对象的全套操作代理）。安全口径：认证走 PKI+配对，会话内容除认证外明文，跨公网套 VPN（官方 telepath 指南明示）。

4.10 java / playit / update / debug

❯ java list
❯ Available Java vendors * - active (4 total):

*oracle    temurin    zulu    corretto

❯ help java vendor
>>  java vendor <vendor ID>       # 切默认供应商，"will install automatically"

❯ playit enable Test Server
❯ a playit.gg account must first be linked using the GUI over Telepath

❯ update info
❯ (!) Update - v2.3.9
> Stability and security update for v2.3.8
• Hardened Modrinth imports, Telepath uploads, and archive extraction
• Reworked backup migration and renaming for speed, reliability, and ...

❯ debug status
❯ Debug logging is currently disabled for this session

实测结论：playit 在 headless 下只能对已链接过账号的实例开关（enableProxy 继承自 GUI），首链必须 GUI；update info 在 Docker 场景只作变更日志查看（升级走换镜像 tag）；debug enable 后同会话日志写入 Logs/application/。

五、注意事项

  1. 参数解析按空格切分、剩余参数拼服务器名——一切带空格的服务器名在 CLI 里直接裸写，不要加引号（FAQ 6.1）；
  2. headless 是功能子集：建服/开服/控制台/备份/properties 编辑/Telepath/Java 供应商在 CLI 可用；加世界、装模组插件、改内存档位、playit 首链、amscript IDE 需要 GUI（经 telepath pair 从桌面版接入）；
  3. ESC 与 C-c 语义不同：脱离控制台用 ESC；C-c 会杀死 auto-mcs 进程进而终结 tmux 会话（FAQ 6.3）；
  4. 日志即敏感：ttyd 启动日志含 Base64 口令、telepath-secrets 与 management-server-secret 属密钥材料，勿外发勿入仓；
  5. 服务器名即目录名（Servers/<名>/），改名请走 GUI 删除重建或备份恢复，不要手改目录。

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

6.1 带引号的服务器名报 does not exist

  • 现象：server info "Test Server" 回显 "Test Server" does not exist。
  • 定位：headless 解析器不剥引号，把 "Test Server" 整体当名字。
  • 解决：裸写 server info Test Server（实测成功返回 Paper 26.3 (b237)）。官方 README 示例 server create paper:latest My Server 也是无引号写法。

6.2 容器重启后 tmux 会话不存在

  • 现象：tmux attach -t auto-mcs 报 error connecting to /tmp/tmux-0/default。
  • 定位：ttyd 用 tmux new -A 懒建会话，首个浏览器客户端连入才创建。
  • 解决：浏览器先连一次；或手动 docker exec <容器> tmux -u -2 new -d -s auto-mcs -- sh -lc /auto-mcs 预建（实测可行）。

6.3 按 C-c 后整个 CLI 会话消失

  • 现象：telepath pair 等待中按 CTRL-C，随后所有 tmux 命令报 no server running on /tmp/tmux-0/default。
  • 定位：界面提示的 CTRL-C 是"取消当前操作"，但信号实际终结了 auto-mcs 进程；会话命令随进程退出。
  • 解决：等超时（实测 pair 监听 177s 自动结束）或用界面内 ESC；崩了按 6.2 重建，卷内数据无损（实测服务器与备份完好）。

6.4 launch 卡在 Installing 'oracle-java25'...

  • 现象：首次开服长时间停在安装行，ps 里能看到 apk add openjdk25 在跑。
  • 定位：Java 供应商默认 oracle，Docker 内落地为 apk 安装 30 个包；速度取决于 Alpine 源可达性。
  • 解决：等待（实测约 5 分钟）；源不可达时给容器配代理或 java vendor temurin 后重试。完成后 ps -ef | grep java 验证 -Xmx 生效。

6.5 控制台 !help 只显示一页

  • 现象：!help 尾部提示 Page 1/2。
  • 定位/解决：auto-mcs 命令分页，用 !help 2 翻页（实测第 2 页为 !ams）。

6.6 想改内存/加模组但 CLI 没有命令

  • 现象：server 子命令表里没有 memory/mod 相关项。
  • 定位：headless 功能子集设计（官方定位"资源受限、低频访问的最小界面"）。
  • 解决：桌面版 auto-mcs telepath pair 配对本实例后远程 GUI 操作（配对流程见 4.9）；参数语义见 配置篇。

七、参考链接

auto-mcs 2.3.9 常用 CLI 命令与工具详解 - Quzuo