Minecraft Bedrock + ChatGPT MCP + 智能物品管理系统

第一阶段部署、迁移与灾难恢复手册
整理日期：2026-10-14
适用：Raspberry Pi 4B / ARM64 / Linux / Docker / 1Panel / MCSManager
目标：只记录最终成功的方案，不记录失败尝试。标记为“需从原机导出”的内容不能凭 Git 仓库重建。

0. 先读：三种不同的入口

本项目有三条独立的访问路径，不要混为一谈：

1. ChatGPT 操作游戏：ChatGPT 自定义 MCP 插件 → OpenAI Secure MCP Tunnel → 本机兼容代理（18766）→ Minecraft MCP 容器（8765）→ Bedrock 游戏。
2. 智能物品自动运行：Python manager.py → 本机兼容代理（18766）→ Minecraft MCP → Bedrock 游戏。
3. 浏览器管理智能物品：域名/OpenResty → Vue Web 容器（18768）→ Python API（18767）→ SQLite；设置生效后由 manager.py 通过 MCP 修改游戏世界。

Secure MCP Tunnel 不依赖公开域名或 FRP。网站的 HTTPS/FRP 与 ChatGPT 的 MCP Tunnel 是不同的连接。

ChatGPT 网页 / 自定义 MCP 插件
       │
       ▼
OpenAI Secure MCP Tunnel（云端）
       │ 加密出站连接（由树莓派 tunnel-client 发起）
       ▼
树莓派 tunnel-client（systemd 用户服务）
       │ http://127.0.0.1:18766/mcp
       ▼
Python MCP 兼容代理（systemd 用户服务）
       │ http://172.17.0.1:8765/mcp
       ▼
Minecraft MCP Server（Docker）
       │
       ▼
Minecraft Bedrock Server（MCSManager 管理的 Docker 容器）
       ▲
       │ MCP 世界操作
Python Smart Items Manager（systemd 用户服务）
       ▲
       │ 设置变化
SQLite ← Python REST API :18767 ← Node/Vue Web :18768
                                         ▲
                                OpenResty /bedrock/
                                         ▲
                                  浏览器用户

1. 当前原机实际信息（迁移前核对）

注意：容器名、镜像版本、端口、主机路径是当前环境的实际记录；新机器上的 Docker 网桥地址、MCSManager 容器 ID 和端口可能不同。

2. 迁移前必须备份：Git 管不到的东西

在旧树莓派上执行：

# 建立只有当前用户可读取的备份目录
mkdir -p "$HOME/minecraft-recovery-private"
chmod 700 "$HOME/minecraft-recovery-private"

# 备份 MCP/Tunnel/代理/智能物品完整运行目录（可能包含敏感凭据）
tar -czf "$HOME/minecraft-recovery-private/minecraft-mcp-runtime.tar.gz" \
  -C "$HOME" minecraft-mcp

# 备份用户级 systemd 配置
tar -czf "$HOME/minecraft-recovery-private/systemd-user.tar.gz" \
  -C "$HOME" .config/systemd/user

# 记录容器配置（注意：docker inspect 可能包含密码，不能公开提交）
docker inspect mc-bedrock-mcsm minecraft-bedrock-mcp minecraft-smart-items-web \
  > "$HOME/minecraft-recovery-private/docker-inspect.json"

# 记录本机镜像
docker image ls > "$HOME/minecraft-recovery-private/docker-images.txt"

# 保存 MCSManager 配置与实例信息（位置取决于 1Panel 安装方式）
# 在 1Panel 的 MCSManager 应用详情、容器挂载及实例设置中导出/截图。

必须另外备份：

• 游戏世界存档：原机曾使用 /home/mango/docker-vols/mc_data:/data 绑定挂载。迁移前用 docker inspect mc-bedrock-mcsm 确认当前实际挂载路径，再在停止游戏或使用可靠快照机制后备份。不要仅凭旧路径直接覆盖。
• 本地定制镜像的 Dockerfile / 构建上下文：mc-bedrock-mcsm:local-1.26.52.3 不是普通官方镜像。原先为适应 MCSManager 创建 Docker 实例的方式，使用基于 itzg/minecraft-bedrock-server 的定制镜像，设置 ENV EULA=TRUE。若构建文件未在 Git 中，必须备份，或者导出镜像 docker save。
• MCSManager 实例：启动命令、环境变量、工作目录、实例 UUID、挂载目录、端口映射、重启策略、世界名等；从管理面板导出或截图。
• 1Panel / OpenResty：网站配置、SSL 证书及私钥、FRP 端口映射；如果网站是另一个服务器上的代理，还要备份那个服务器的配置。
• ChatGPT 插件和 Tunnel：ChatGPT 账号内的插件创建记录、Tunnel 关联关系不在 Git 中。保存插件名称、Tunnel ID、权限和配置截图；凭据放在密码管理器。
• 管理员账号：data/initial_admin_password.txt 如仍存在，属于敏感信息；数据库里还可能保存用户账户、权限、方块允许范围和插件配置。

# 安全地复制备份到另一台机器，示例：
scp "$HOME/minecraft-recovery-private/"*.tar.gz user@backup-host:/secure-backups/

备份目录中有凭据：不要提交到公开 Git 仓库，不要粘贴到聊天，不要把私钥放入文档。

3. 准备新树莓派

1. 安装支持 ARM64 的 Linux，创建普通用户（以下假设 mango）。
2. 安装 Docker、Docker Compose 插件、Python 3、Git、Node（Node 主要用于本地开发；前端 Docker 构建时自带 Node）。
3. 安装并配置 1Panel 与 MCSManager，或恢复原有的应用/容器配置。
4. 确认 Docker 可以启动 ARM64 镜像：

uname -m                         # 预期 aarch64
docker version
docker compose version
python3 --version

5. 对需要在用户登出后继续运行的 systemd 用户服务，启用 linger：

sudo loginctl enable-linger mango
loginctl show-user mango -p Linger

不要直接把示例中的用户名、Docker 网桥 IP 或 MCSManager 实例 ID 当作所有机器的固定值。

4. 恢复 Minecraft Bedrock 游戏服务

本环境通过 1Panel 安装的 MCSManager 管理 Bedrock Docker 实例。最终运行的容器是 mc-bedrock-mcsm。

1. 恢复 MCSManager Web 与 Daemon 的配置和数据；确保管理页面能连接 Daemon。
2. 恢复 Bedrock 的自定义 Docker 镜像构建文件。其关键兼容配置是：

FROM itzg/minecraft-bedrock-server
ENV EULA=TRUE

该片段只是定制镜像的关键部分，不是原镜像完整构建记录；若要完全复现原版本，优先使用备份的 Dockerfile/镜像。

3. 在 MCSManager 中恢复原实例设置与 Docker 端口映射。原机实际存在 19134:19132/tcp 及其他 UDP 映射；请从 docker inspect 和 MCSManager 导出配置恢复完整端口，不要以 TCP 19134 代替所有 Bedrock UDP 游戏端口。
4. 恢复世界数据，确认世界名称、种子/版本、玩家数据与附加包均正确。
5. 启动并检查：

docker ps --filter name=mc-bedrock-mcsm
docker logs --tail 80 mc-bedrock-mcsm

6. 从 Bedrock 客户端实际进入世界测试。当前曾验证的世界名是 test-world；迁移时以备份的实际世界为准。

重要：MCSManager 的 Docker 实例创建方式、容器环境变量限制以及自定义镜像属于非 Git 配置。请保存管理面板的实例导出或截图。

5. 部署 Minecraft MCP 服务

当前使用的容器镜像：

ghcr.io/chapmanjw/minecraft-bedrock-mcp-server:0.3.0

1. 从原机备份的 docker inspect minecraft-bedrock-mcp 恢复容器的完整环境变量、挂载、网络、重启策略。这些参数与 Bedrock Bridge 的连接方式有关，不能仅凭镜像名推导。
2. MCP 服务端口在原机映射为：

172.17.0.1:8765 → 容器内 8765/tcp

3. 启动容器后检查：

docker ps --filter name=minecraft-bedrock-mcp
docker logs --tail 100 minecraft-bedrock-mcp

4. 使用 MCP Inspector 或兼容代理的健康检查验证 MCP 初始化、工具列表和世界操作。最终曾成功读取世界信息、玩家列表并执行方块读写。

不要直接把 8765 暴露给公网；目前由本地代理和 Secure MCP Tunnel 访问。

6. 部署 MCP 兼容代理（容易遗漏的关键环节）

ChatGPT 的 MCP 客户端与原 Minecraft MCP 服务在会话、工具发现、工具 Schema 上存在兼容要求，因此在中间增加了一个独立 Python 代理。

ChatGPT / Tunnel
      ↓
http://127.0.0.1:18766/mcp
      ↓
/home/mango/minecraft-mcp/compat/proxy.py
      ↓
http://172.17.0.1:8765/mcp
      ↓
Minecraft MCP Docker

最终代理已包含：会话兼容处理、server/discover 相关处理、工具发现/Schema 适配，以及 mc_structure_create_from_blocks 的 Schema 修正。不能拿早期未修正版本替换。

恢复：

# 将备份恢复到：
# /home/mango/minecraft-mcp/compat/proxy.py
# /home/mango/minecraft-mcp/.env

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/minecraft-mcp-compat.service <<'UNIT'
[Unit]
Description=Minecraft MCP session compatibility proxy
After=network-online.target

[Service]
Type=simple
EnvironmentFile=/home/mango/minecraft-mcp/.env
ExecStart=/usr/bin/python3 /home/mango/minecraft-mcp/compat/proxy.py
Restart=on-failure
RestartSec=5
NoNewPrivileges=true

[Install]
WantedBy=default.target
UNIT

systemctl --user daemon-reload
systemctl --user enable --now minecraft-mcp-compat.service
systemctl --user status minecraft-mcp-compat.service

.env 中的具体变量和认证值必须从原机安全备份恢复。文档不编造未知的环境变量名或凭据。

7. ChatGPT 个人开发者 / 自定义 MCP 插件配置

这是 ChatGPT 网页端账户内的设置，不属于树莓派代码，也不会随着 Git 克隆恢复。

当前 OpenAI 官方流程（产品界面可能更新）：

1. 在 ChatGPT 网页版进入 Plugins（插件）。
2. 点击 + → Add custom MCP server。
3. 输入插件名称和说明。
4. 在连接方式中选择 Tunnel / Secure MCP Tunnel，而不是填写内网 127.0.0.1 地址。
5. 选择与当前 ChatGPT 账户/工作空间关联的 Tunnel，或填写有效的 Tunnel ID。
6. 配置认证方式，审阅安全风险，创建插件。
7. 在个人插件列表安装/启用新插件。
8. 新建聊天，通过 @ 选择该插件，尝试读取世界信息和玩家列表；再在确认权限后测试写入方块。

官方文档：

• https://developers.openai.com/api/docs/guides/custom-mcp-server
• https://developers.openai.com/api/docs/guides/secure-mcp-tunnels

个人开发者/开发者模式：原环境曾在 ChatGPT 内完成相关申请和插件添加；当前官方 UI/套餐权限会调整。若你的账户没有上述入口，先检查当前套餐、工作空间权限和官方说明，不能保证任何新账号都能照旧获得完整写入权限。不要把 OpenAI API Key 与 ChatGPT 自定义 MCP 插件误认为同一配置。

7.1 Tunnel ID 与连接关系

原环境记录的 Tunnel ID 为：

tunnel_6ace6b4124b8819190b24e12894fd63e

它是历史部署标识，不是新账户通用 ID。新账户、新工作空间或重建 Tunnel 后应以 ChatGPT 实际显示的 ID 为准。

7.2 树莓派上的 Tunnel Client

原机：

/home/mango/minecraft-mcp/tunnel/
├── start.sh
├── openai.env              # 私有连接配置，必须单独备份
└── bin/
    ├── tunnel-client       # v0.0.16 linux-arm64
    └── cloudflared         # 随客户端部署的组件

最终 Tunnel 连接目标：

http://127.0.0.1:18766/mcp

注意：不是旧的 http://172.17.0.1:8765/mcp。 如果直接连原 MCP 容器，会绕过兼容代理。

恢复原机的 start.sh、openai.env 和二进制文件，或从 OpenAI 官方渠道重新获取对应 ARM64 Tunnel Client，再按照官方流程重新绑定 Tunnel。

原机 systemd 用户服务：

[Unit]
Description=OpenAI Secure MCP Tunnel for Minecraft
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/home/mango/minecraft-mcp/tunnel/start.sh run
Restart=always
RestartSec=8
NoNewPrivileges=true

[Install]
WantedBy=default.target

保存为 ~/.config/systemd/user/minecraft-mcp-tunnel.service，然后：

chmod 700 /home/mango/minecraft-mcp/tunnel
chmod 600 /home/mango/minecraft-mcp/tunnel/openai.env
chmod +x /home/mango/minecraft-mcp/tunnel/start.sh
systemctl --user daemon-reload
systemctl --user enable --now minecraft-mcp-tunnel.service
journalctl --user -u minecraft-mcp-tunnel.service -n 50 --no-pager

Tunnel 必须在代理已经正常启动后验证。可以使用客户端 doctor 功能，但具体命令参数以备份的 start.sh 或该版本的 --help 为准。

8. 恢复 Python 智能物品管理器

项目：

/home/mango/minecraft-mcp/work/smart_items/
├── manager.py
├── mc.py
├── items/clock.py
├── web/api.py
├── web/blocks.py
├── data/settings.sqlite3
├── frontend/
└── compose.yaml

mc.py 通过 HTTP JSON-RPC 连接本机 MCP 兼容代理：

http://127.0.0.1:18766/mcp

SQLite 存储物品设置、版本信息及后台相关数据，不能只恢复代码而忘记数据库。

原机服务文件 ~/.config/systemd/user/minecraft-smart-items.service：

[Unit]
Description=Minecraft smart items manager
After=minecraft-mcp-compat.service
Wants=minecraft-mcp-compat.service

[Service]
Type=simple
ExecStart=/usr/bin/python3 -u /home/mango/minecraft-mcp/work/smart_items/manager.py
WorkingDirectory=/home/mango/minecraft-mcp/work/smart_items
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now minecraft-smart-items.service
systemctl --user status minecraft-smart-items.service
journalctl --user -u minecraft-smart-items.service -n 60 --no-pager

电子钟插件已改名为 items/clock.py，实例 ID 为 clock-1。旧版 jst_clock.py 和旧实例 ID 不应重新引入。电子钟的坐标目前写在代码中；迁移到不同的世界前先确认目标位置不会覆盖其他建筑。

8.1 避免旧服务重复运行

原机仍有一个已禁用的旧服务文件：

minecraft-jst-redstone-clock.service

它属于旧版单独电子钟，不是当前推荐架构。新部署不要启用，否则可能有两个程序同时修改同一片建筑。确认：

systemctl --user is-enabled minecraft-jst-redstone-clock.service 2>/dev/null || true
systemctl --user is-active minecraft-jst-redstone-clock.service 2>/dev/null || true

9. 部署网页前端（Docker）

从项目目录执行：

cd /home/mango/minecraft-mcp/work/smart_items

docker compose config
docker compose up -d --build frontend
curl -I http://127.0.0.1:18768/
curl http://127.0.0.1:18768/api/health

compose.yaml 负责构建 frontend/Dockerfile，启动容器 minecraft-smart-items-web，通过宿主机网络访问 Python API 127.0.0.1:18767。

本地方块图片放在 frontend/public/icons/，普通构建不需要联网下载。仅明确更新图标时：

UPDATE_BLOCK_ICONS=true docker compose build --no-cache frontend
docker compose up -d frontend

注意：构建时下载的新图标进入 Docker 镜像，不会自动覆盖 Git 仓库中的本地备份图片。

后台账户与密码、用户角色、允许使用的方块范围和电子钟配置，应从 SQLite 备份恢复。不要依赖重新安装后生成的初始密码替代原有用户数据。

10. 域名、HTTPS 与 OpenResty（网站接入）

计划中的管理网址：

https://mc.chenyuge.com        → 重定向到 /bedrock/
https://mc.chenyuge.com/bedrock → 重定向到 /bedrock/
https://mc.chenyuge.com/bedrock/ → 管理页面

状态说明：这是已讨论的推荐配置，不代表已经核实在原机上成功启用。

在负责该域名的 1Panel/OpenResty 网站 server 块内加入（注意与原有 location 去重）：

location = / {
    return 302 /bedrock/;
}
location = /bedrock {
    return 301 /bedrock/;
}
location /bedrock/ {
    proxy_pass http://127.0.0.1:18768/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/ {
    proxy_pass http://127.0.0.1:18768;
    proxy_set_header Host $host;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /icons/ {
    proxy_pass http://127.0.0.1:18768;
}
# Vite 构建资源也使用根路径 /assets/，必须单独代理
location /assets/ {
    proxy_pass http://127.0.0.1:18768;
}

为何要代理 /api/、/icons/、/assets/？ 现有前端在构建时使用根路径资源：Vue 请求 /api、方块图标 /icons、Vite JS/CSS /assets。只代理 /bedrock/ 会导致页面空白、图片缺失或无法保存。

若 OpenResty 在另一台机器上或 Docker 网络中，127.0.0.1 指向的是 OpenResty 所在的机器/容器，而不是树莓派；应换成正确的内网地址或 FRP 入口。FRP 具体映射必须从实际部署导出，不能臆造。

站点证书、私钥、域名 DNS 记录、1Panel 网站设置及 FRP 转发都不在本项目 Git 仓库中。恢复后测试：

curl -I https://mc.chenyuge.com/
curl -I https://mc.chenyuge.com/bedrock/
curl -I https://mc.chenyuge.com/assets/

最后一条仅用于排查路由，不保证目录本身返回 200；应以网页 HTML 实际引用的 JS/CSS 资源 URL 测试 HTTP 200。必须使用 HTTPS 保护后台登录信息。不要将 18767 或 Minecraft MCP 内部端口直接公开到公网。

11. 推荐恢复顺序（照着做）

• [ ] 恢复 Linux、Docker、1Panel、MCSManager、用户和持久化目录。
• [ ] 恢复 Bedrock 自定义镜像、MCSManager 实例及世界存档；确认能进入游戏。
• [ ] 恢复 Minecraft MCP 容器配置；确认工具能读取游戏世界。
• [ ] 恢复 .env、compat/proxy.py，启动 minecraft-mcp-compat.service。
• [ ] 恢复 tunnel/openai.env、start.sh 和 ARM64 客户端；启动 minecraft-mcp-tunnel.service。
• [ ] 在 ChatGPT 账户中关联/恢复 Tunnel，创建并安装自定义 MCP 插件；测试读/写工具。
• [ ] 恢复智能物品代码与 SQLite，启动 minecraft-smart-items.service。
• [ ] 通过 Docker Compose 构建前端；验证 18768 页面与 API。
• [ ] 恢复域名 DNS、HTTPS 证书、OpenResty、FRP（如需要），验证 /bedrock/。
• [ ] 检查旧版电子钟服务没有启用，避免重复写入世界。
• [ ] 登录管理页面，保存一项设置，确认游戏中的电子钟实际变化。

12. 常用检查命令

# Docker
docker ps --filter name=mc-bedrock-mcsm
docker ps --filter name=minecraft-bedrock-mcp
docker ps --filter name=minecraft-smart-items-web

# systemd 用户服务
systemctl --user status minecraft-mcp-compat.service
systemctl --user status minecraft-mcp-tunnel.service
systemctl --user status minecraft-smart-items.service

# 日志
journalctl --user -u minecraft-mcp-compat.service -n 80 --no-pager
journalctl --user -u minecraft-mcp-tunnel.service -n 80 --no-pager
journalctl --user -u minecraft-smart-items.service -n 80 --no-pager

docker logs --tail 80 minecraft-bedrock-mcp

# HTTP 服务
curl -I http://127.0.0.1:18768/
curl http://127.0.0.1:18768/api/health

# SQLite 文件
ls -lh /home/mango/minecraft-mcp/work/smart_items/data/settings.sqlite3

13. 仍需从原机补齐的“不可凭空推断”项目

这份文档已经记录了能够核实的最终运行架构，但为了让第三方真正从全新机器做到完全复现，以下信息还需要导出成附录（不要公开秘密）：

1. Bedrock Bridge/MCP Docker 的完整 Compose 或 docker run 参数：尤其是游戏桥接、挂载、环境变量和网络。现有记录只确认了镜像、容器和端口。
2. MCSManager 实例导出：实际实例工作目录、Docker 配置、游戏世界挂载、完整 UDP/TCP 端口、游戏版本/构建方式。
3. compat/proxy.py 与 .env 的安全备份：最终兼容逻辑与配置，不可只保存代理的描述。
4. Tunnel 客户端完整启动参数与 openai.env：不能把 Tunnel ID 当成唯一凭据。
5. ChatGPT 插件设置截图：插件名称、所选 Tunnel、授权方式、启用的工具权限及当前账户可用性。
6. OpenResty/FRP 实际生效配置：域名所在机器、FRP 入口、SSL 证书续签方式、是否已启用 /bedrock/。
7. 代码仓库地址与提交版本：当前目录是否已全部提交到 Git 需要单独核对；data/、.env、Tunnel 文件和 systemd 文件即使在仓库外也必须有备份。
8. 服务账户与权限：新机器需确保目录属主、systemd 用户服务、Docker 权限及证书读取权限一致。

这些不是失败步骤，而是成功运行时存在、但还没有完整固化为可移植安装文件的环境依赖。补齐之后才适合称为完全自动化的一键复现手册。

14. 官方参考

• OpenAI 自定义 MCP 插件：https://developers.openai.com/api/docs/guides/custom-mcp-server
• OpenAI Secure MCP Tunnel：https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
• ChatGPT 开发者模式及权限：https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt

维护建议：以后每次新增容器、systemd 服务、证书、环境变量或 ChatGPT 插件配置，都在本文“非 Git 配置”部分补充备份位置。迁移时优先恢复世界数据与凭据，再恢复程序，最后开放网站访问。