auto-mcs Docker Compose 部署指南

目标：在 Ubuntu 24.04.5 上用 Docker Compose 部署官方镜像 macarooniman/auto-mcs:2.3.9，完成 ttyd Web 终端验证、数据持久化确认与等价 docker run 实测。本文全部命令与回显为 2026-11-02 实测，含"默认凭据拒绝启动""tmux 会话懒建""C-c 打崩会话""Telepath 端口与配置不符"等 6 条排障实录。功能与选型背景见《auto-mcs 介绍与选型指南》。

一、环境信息

项目	值
主机 OS	Ubuntu 24.04.5 LTS（内核 x86_64）
Docker	29.9.2, build a82e528
Docker Compose	v5.6.1
组件版本	auto-mcs v2.3.9（GitHub 2026-07-14 发布）
镜像	`macarooniman/auto-mcs:2.3.9`（镜像 ID `47a25db6a0e9`，磁盘占用约 157MB，构建于 2026-08-02）
运行期	容器内 Alpine Linux 3.23.5，ttyd 1.7.7 + libwebsockets 4.3.3 + tmux，root 用户
Web 终端端口	`8132`（宿主）→ `8080`（ttyd）
Telepath API 端口	`7001`（容器内默认监听）
Minecraft 端口	`25565`
自定义网络	`auto-mcs-net`，bridge，子网 `10.89.59.0/24`
compose 项目名	`auto-mcs-2.3.9-stack`（显式 `name:`，防多代理互删）
数据卷	命名卷 `auto-mcs-data` → `/root/.auto-mcs`
实测日期	2026-11-02

二、镜像选型说明

官方镜像发布在 Docker Hub macarooniman/auto-mcs（注意组织名无连字符，与 GitHub 的 macarooni-man 不同）。官方 README 声明的支持面（查询 2026-11-02）：

维度	支持
标签	`latest`、`beta`、任意发布版本号（本例 `2.3.9`）
架构	`amd64`、`arm64`
拉取量	pull_count 72190，last_updated 2026-10-05（Hub API 实查）

镜像内部结构（上游 Dockerfile 实查）：

基底 alpine:3.23，把 headless CLI 二进制 /auto-mcs 包进 ttyd Web 终端；
ttyd 启动命令为 tmux -u -2 new -A -s auto-mcs -- sh -lc /auto-mcs——浏览器里看到的是 tmux 会话中的 auto-mcs headless 界面，断开重连不丢会话；
VOLUME ["/root/.auto-mcs"] 声明数据目录；EXPOSE 8080 7001 25565；
内置默认环境变量 WEB_PORT=8080、WEB_USERNAME=root、WEB_PASSWORD=auto-mcs——但启动器禁止使用默认凭据（见 FAQ 10.1 实测）。

要点：

这是Web 终端而非图形面板：浏览器打开后是命令行界面；GUI 完整体验需另装桌面版经 Telepath 配对（背景见选型篇）；
生产部署建议钉住版本号 tag（如 2.3.9），避免 latest 漂移；
官方 README 明示：镜像以 root 运行，数据目录需读/写/执行权限；若用 bind mount 且目录权限受限，可在宿主执行 chmod -R 777 /path/to/auto-mcs-data（本指南用命名卷规避此问题）。

三、前置条件

# Docker 与 Compose 版本确认（实测）
$ docker --version
Docker version 29.9.2, build a82e528
$ docker compose version
Docker Compose version v5.6.1

# 宿主端口占用检查：8132/7001/25565 需空闲（实测 ss -ltn 摘录）
$ ss -ltn | grep -E ':(8132|7001|25565)' || echo 'ports free'
ports free

⚠️ 开服时 auto-mcs 会自动安装 Java 运行时（走容器内 apk add，Alpine 镜像源可达即可），首次启动需要外网访问 Alpine 包源与 PaperMC 下载站，无需宿主机预装 Java。

四、部署步骤

4.1 编写 docker-compose.yml

完整实测版本（钉版本 tag、显式项目名、自定义网络槽位）：

name: auto-mcs-2.3.9-stack

services:
  app:
    image: macarooniman/auto-mcs:2.3.9
    container_name: auto-mcs-2.3.9-panel
    stdin_open: true
    tty: true
    restart: unless-stopped
    environment:
      WEB_PORT: "8080"
      WEB_USERNAME: "root"
      WEB_PASSWORD: "q1w2e3r4"
    ports:
      - "8132:8080"
      - "7001:7001"
      - "25565:25565"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - auto-mcs-data:/root/.auto-mcs
    networks:
      - auto-mcs-net

networks:
  auto-mcs-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.59.0/24

volumes:
  auto-mcs-data:

逐项说明：

name: 显式项目名——compose 默认用目录名做项目名，多栈并存时 down 会误删他人栈，必须显式命名；
stdin_open/tty 对应官方 compose 示例，给容器保留 TTY（ttyd 起的 tmux 界面依赖伪终端语义）；
WEB_USERNAME/WEB_PASSWORD 必须改，官方默认凭据会被启动器直接拒绝（见 FAQ 10.1）；
端口映射：8132:8080 ttyd Web 终端（宿主端口按空闲情况取），7001 Telepath API，25565 Minecraft Java 服；
extra_hosts: host.docker.internal:host-gateway 便于服务器进程回连宿主服务（官方 compose 示例未含，属可选加固）；
数据全部落在命名卷 auto-mcs-data（挂载点 /root/.auto-mcs），备份即备该卷。

4.2 拉取镜像

$ docker pull macarooniman/auto-mcs:2.3.9
2.3.9: Pulling from macarooniman/auto-mcs
Digest: sha256:47a25db6a0e9...
Status: Downloaded newer image for macarooniman/auto-mcs:2.3.9

4.3 起栈

$ docker compose up -d
 Network auto-mcs-239-stack_auto-mcs-net Creating
 Network auto-mcs-239-stack_auto-mcs-net Created
 Container auto-mcs-2.3.9-panel Creating
 Container auto-mcs-2.3.9-panel Created
 Container auto-mcs-2.3.9-panel Starting
 Container auto-mcs-2.3.9-panel Started

（compose 会把项目名中的点剔除，网络实际名为 auto-mcs-239-stack_auto-mcs-net，属正常现象。）

状态确认：

$ docker compose ps
NAME                   IMAGE                         COMMAND                  SERVICE   CREATED                  STATUS                  PORTS
auto-mcs-2.3.9-panel   macarooniman/auto-mcs:2.3.9   "/usr/local/bin/laun…"   app       Less than a second ago   Up Less than a second   0.0.0.0:7001->7001/tcp, 0.0.0.0:25565->25565/tcp, 0.0.0.0:8132->8080/tcp

4.4 启动日志

docker compose logs 实测主线（节选）：

auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1896] N: ttyd 1.7.7 (libwebsockets 4.3.3)
auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1896] N: tty configuration:
auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1896] N:   credential: cm9vdDpxMXcyZTNyNA==
auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1896] N:   start command: tmux -u -2 new -A -s auto-mcs -- sh -lc /auto-mcs
auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1896] N:   close signal: SIGHUP (1)
auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1896] N:   terminal type: xterm-256color
auto-mcs-2.3.9-panel  | [2026-11-02 16:21:50:1899] N:  Listening on port: 8080

要点：

credential 是 WEB_USERNAME:WEB_PASSWORD 的 Base64（cm9vdDpxMXcyZTNyNA== = root:q1w2e3r4）——日志即泄露口令，不要把 compose 日志外发/入仓；
ttyd 以 Basic auth 保护 Web 终端，-W 开启写权限、标题固定为 auto-mcs (docker)；
tmux 命令 new -A -s auto-mcs 意味着会话在首个浏览器客户端连入时才创建（见 FAQ 10.2）。

4.5 Web 验证

$ ss -ltn | grep 8132
LISTEN 0      4096         0.0.0.0:8132       0.0.0.0:*

$ curl -sI http://127.0.0.1:8132/
HTTP/1.1 401 Unauthorized
server: ttyd/1.7.7 (libwebsockets/4.3.3)
www-authenticate: Basic realm="ttyd"

$ curl -su root:q1w2e3r4 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8132/
200

$ curl -su root:wrong -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8132/
401

四条回显含义：端口已监听；未带凭据 401 并返回 Basic realm="ttyd"；正确口令 200；错误口令同样 401（认证生效）。

浏览器打开 http://<宿主IP>:8132，输入 root / q1w2e3r4 即进入 auto-mcs headless 界面：

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

 ┌───────────────────── auto-mcs v2.3.9 (dev) (headless) ─────────────────────┐
 │Telepath API (v1.2.2)                                                       │
 │> 172.17.0.1:7001                                                           │
 │❯ Type a command, ?, or help                                                │
 └────────────────────────────────────────────────────────────────────────────┘

建服与开服的两条官方命令（详细操作见《auto-mcs 2.3.9 常用 CLI 命令与工具详解》）：

server create paper:latest My Server
server launch My Server

4.6 首次 Java 安装说明

首次 server launch 时 headless 会按配置的 Java 供应商（默认 oracle）自动安装运行时。实测回显：

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

底层实际执行 apk add openjdk25（30 个包，含 openjdk25-jre 25.0.5.0.3_p1-r0），实测耗时约 5 分钟；期间界面停留在 Installing 'oracle-java25'... 属正常，不要重复触发。安装完成后 Minecraft 进程拉起：

$ docker exec auto-mcs-2.3.9-panel ps -ef | grep java
/usr/lib/jvm/java-25-openjdk/bin/java -Xmx4G -Xms2G -XX:+UseG1GC ... -jar server.jar nogui

五、数据持久化说明

数据全部落在命名卷 auto-mcs-data（容器路径 /root/.auto-mcs）。实测卷内容目录树（面板运行一段时间后）：

/root/.auto-mcs
├── Backups/                  # .amb 备份，命名 <服务器名>__HH.MM DD-MM-YY.amb
├── Cache/                    # addon-db.json、guide-cache.json
├── Config/app-config.json    # 实例级配置（详解见配置篇）
├── Logs/application/         # auto-mcs_<时间>.log 会话日志
├── Servers/<服务器名>/        # server.jar、server.properties、Start.sh、eula.txt、.auto-mcs.ini
└── Tools/
    ├── amscript/             # 脚本目录
    ├── telepath/             # telepath-secrets（PKI 密钥，勿外传）
    └── templates/            # stock/optimized/creative/bedrock 四种服务器模板 yml

持久化验证（实测）：docker compose down 再 up -d 后，已建服务器完好：

$ docker exec auto-mcs-2.3.9-panel ls /root/.auto-mcs/Servers/
Test Server

备份口径：备卷即备全部（服务器、配置、备份快照、Telepath 密钥都在卷里）。导出命令示例：

docker run --rm -v auto-mcs-data:/data -v "$PWD":/backup alpine tar czf /backup/auto-mcs-data.tar.gz -C /data .

六、环境变量表

镜像仅认三个环境变量（上游 Dockerfile ENV 实查 + 本栈实测）：

变量	默认值	实测值	说明
`WEB_PORT`	`8080`	`8080`	ttyd 监听端口（容器内），改它需同步改端口映射
`WEB_USERNAME`	`root`	`root`	Web 终端 Basic auth 用户名
`WEB_PASSWORD`	`auto-mcs`	`q1w2e3r4`	Web 终端口令；保持默认会拒绝启动（FAQ 10.1）

实例级行为（自动更新、语言、Java 供应商、Telepath 开关等）不走环境变量，全部在卷内 Config/app-config.json，详解见《auto-mcs 2.3.9 配置参数详解》。

七、配置文件挂载

本指南用命名卷路线。若改 bind mount（把数据目录放宿主便于网盘同步/直接翻文件），官方 README 明确权限要求（查询 2026-11-02）：

auto-mcs needs read, write, and execute permissions for its data directory inside the container. If you're using a bind mount ... ensure that the user running the container can access, modify, and execute everything inside of it. If your mounted data directory requires full permissions, you can run the following on the Docker host: chmod -R 777 /path/to/auto-mcs-data

即：镜像内以 root 运行，bind mount 宿主目录需放开到容器可读写执行；官方给的兜底是宿主上 chmod -R 777。命名卷无此烦恼（卷自动初始化），推荐除非你明确需要直接浏览宿主文件。

八、等价 docker run

与 4.1 compose 等价的单命令路线，两条实测记录：

反例（不带凭据 env，实测秒退）：

$ docker run -d --name auto-mcs-2.3.9-runtest -p 8134:8080 \
    -v auto-mcs-runtest:/root/.auto-mcs macarooniman/auto-mcs:2.3.9
f52f8438cca2...
Error response from daemon: container ... is not running

$ docker logs auto-mcs-2.3.9-runtest
[ERROR] Default/insecure credentials are not allowed

  - To configure the environment variable credentials:
    - WEB_USERNAME='U$ern4me'
    - WEB_PASSWORD='P@s$w0rd'

$ docker inspect auto-mcs-2.3.9-runtest --format '{{.State.ExitCode}}'
64

正例（带凭据 env，验证通过）：

$ docker run -d --name auto-mcs-2.3.9-runtest -p 8134:8080 \
    -v auto-mcs-runtest:/root/.auto-mcs \
    -e WEB_USERNAME=root -e WEB_PASSWORD=q1w2e3r4 \
    macarooniman/auto-mcs:2.3.9

$ curl -su root:q1w2e3r4 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8134/
200
$ curl -sI http://127.0.0.1:8134/ | head -1
HTTP/1.1 401 Unauthorized

验证后已删除该测试容器与卷（docker rm -f auto-mcs-2.3.9-runtest && docker volume rm auto-mcs-runtest）。

💡 实测细节：全新卷在首个 Web 客户端连入前 /root/.auto-mcs 是空的——数据目录由 auto-mcs 进程懒初始化，属正常。

九、常用运维命令

# 查看/日志/重启
docker compose ps
docker compose logs --tail 50
docker compose restart

# 进入 Web 终端之外的 CLI 操作（服务器内跑 headless 的 tmux 会话）
docker exec auto-mcs-2.3.9-panel tmux attach -t auto-mcs

# 升级版本：改 compose 里 tag → 重新 pull → up -d（数据卷不动）
sed -i 's/2\.3\.9/2.4.0/' docker-compose.yml && docker compose pull && docker compose up -d

# 彻底卸载（含数据！先导出备份卷）
docker compose down -v
docker rmi macarooniman/auto-mcs:2.3.9

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

10.1 容器秒退，日志报 Default/insecure credentials are not allowed

现象：docker run/up 后容器立即退出，exit code 64。
定位：镜像虽内置 WEB_PASSWORD=auto-mcs 默认值，但启动器强制拒绝默认/弱凭据。
解决：显式设置 WEB_USERNAME/WEB_PASSWORD 非默认值（实测设置后正常启动、200 通过）。

10.2 容器重启后 `tmux attach` 报 no server running

现象：docker compose restart 后执行 docker exec <容器> tmux attach -t auto-mcs 报 error connecting to /tmp/tmux-0/default。
定位：ttyd 的 start command 是 tmux -u -2 new -A ...，只有浏览器客户端连入 8080 时 tmux 会话才被创建。
解决：先用浏览器（或 curl 认证）访问一次 Web 终端；或手动 docker exec <容器> tmux -u -2 new -d -s auto-mcs -- sh -lc /auto-mcs 预建会话（实测可行，浏览器随后接入会 new -A 直接附加）。

10.3 在 headless 界面按 C-c 把整个会话打崩

现象：CLI 提示符下按 Ctrl-C 后，tmux capture-pane 报 no server running on /tmp/tmux-0/default。
定位：tmux 会话以 sh -lc /auto-mcs 为命令创建，auto-mcs 进程退出即会话结束。
解决：取消正在执行的操作优先用界面自身提示的退出键（如 ESC）；误崩后按 10.2 重建会话即可，卷内数据无损（实测服务器列表、备份完好）。

10.4 首次开服卡在 Installing 'oracle-java25'... 数分钟

现象：server launch 后长时间停在安装 Java 一行。
定位：容器内走 apk add openjdk25（30 包），速度取决于 Alpine 镜像源；实测约 5 分钟。
解决：等待即可；若容器出网受限，可在宿主机代理环境为容器配置代理，或换 java vendor temurin 等供应商后重试。安装完成后可用 docker exec <容器> ps -ef | grep java 验证进程与堆参数。

10.5 应用日志出现 get_public_ip 连接失败

现象：Logs/application/*.log 报 [ERROR] ... get_public_ip ... api.ipify.org ... Connection refused，且界面地址显示 172.17.0.1:25565 而非公网 IP。
定位：enable_ip_lookup 功能默认开，容器无法直连 ipify 时失败，地址回退为默认路由网关。
解决：不影响开服；在意地址显示则放开容器出网，或在 GUI 关闭 IP lookup。跨 NAT 联机建议直接用 playit 隧道（headless 下需 GUI 配对启用，见 CLI 篇）。

10.6 7001 端口在配置未开启时也被监听

现象：curl http://127.0.0.1:7001/openapi.json 返回 200，但 Config/app-config.json 里 enable-api 为 false。
定位：Docker/headless 启动时 Telepath API 随进程初始化，enable-api 配置项与运行时监听状态不一致（实测 telepath stop 可关、telepath start 可开，均不回写配置文件）。
解决：不需要远程管理就 telepath stop；公网暴露务必用防火墙挡 7001 或套 VPN（官方明示会话除认证外为明文）。详见配置篇 Telepath 节。

十一、参考链接

官方 Docker Hub 镜像页：https://hub.docker.com/r/macarooniman/auto-mcs （compose/run 官方样例、tags/架构、权限注记，查询 2026-11-02）
GitHub 仓库（Dockerfile 上游）：https://github.com/macarooni-man/auto-mcs
官网与文档：https://www.auto-mcs.com/guides
同专栏文档：《auto-mcs 介绍与选型指南》
同类面板部署先例：《Crafty Controller Docker Compose 部署指南》

auto-mcs Docker Compose 部署指南

auto-mcs Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 编写 docker-compose.yml

4.2 拉取镜像

4.3 起栈

4.4 启动日志

4.5 Web 验证

4.6 首次 Java 安装说明

五、数据持久化说明

六、环境变量表

七、配置文件挂载

八、等价 docker run

九、常用运维命令

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

10.1 容器秒退，日志报 Default/insecure credentials are not allowed

10.2 容器重启后 tmux attach 报 no server running

10.3 在 headless 界面按 C-c 把整个会话打崩

10.4 首次开服卡在 Installing 'oracle-java25'... 数分钟

10.5 应用日志出现 get_public_ip 连接失败

10.6 7001 端口在配置未开启时也被监听

十一、参考链接

10.2 容器重启后 `tmux attach` 报 no server running