For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/backup-upgrade.md.
SFMC
  • 简体中文

      • 备份、升级与回退

      升级前先确认当前服务由哪个 SFMC 安装和工作目录管理，并为数据与世界制作可恢复的冷备份。本指南给出操作顺序；实际路径以本机配置为准。

      1. 数据安全与冷备份标准

      必须纳入备份的核心资产清单

      资产目录 / 文件存储内容丢失影响
      data/SQLite 核心数据库文件（sfmc_data.db 及日志）极高。包含所有玩家数据与模块持久化数据。
      configs/平台各服务配置与所有业务模块私有配置高。丢失后需重新配置机器人凭证、端口与游戏规则。
      modules/模块包、module-lock.json 与 catalog.json高。保存已安装的模块版本、代码与启停状态。
      <BDS>/worlds/游戏主世界存档（包含地形、实体与建筑）极高。Minecraft 游戏层面的全量物理世界数据。
      <BDS>/behavior_packs/、<BDS>/resource_packs/ 与世界包引用文件已部署的行为包、资源包及启用关系高。回退时需与世界和模块版本一致。

      严禁在运行状态下直接拷贝 SQLite

      严防 WAL 脏数据

      SFMC 的 db-server 默认工作在 SQLite WAL（预写式日志，Write-Ahead Logging） 高性能并发模式。数据在写入主数据库前会暂存在同级的 .db-wal 与 .db-shm 文件中。
      严禁在 db-server 处于运行状态时直接强行拷贝 .db 文件，否则极易导致数据库页损坏（SQLITE_CORRUPT）。

      标准备份流程操作

      推荐在例行维护窗口（或通过计划任务脚本）执行标准化冷备份：

      挂起数据库写入并安全停机

      安排维护窗口，在管理该实例的 sfmc 控制台停止服务，并确认 BDS 与 db-server 进程均已退出：

      sfmc> /stop -all

      执行打包归档

      使用系统原生打包工具将关键资产压缩为带时间戳的归档。下面的 BDS_DIR / $bdsDir 必须先替换为当前实例实际的 BDS 目录；不要假定目录名为 BedrockDedicatedServer。归档须放在被备份目录之外，且空间足够。若数据库位于 data/ 之外，应另行纳入。

      先检查 modules/packages/ 是否含符号链接或 Windows junction。 归档 modules/ 不等于备份链接目标：本机用 Compress-Archive 对 junction 的隔离验证中，归档只包含普通文件，漏掉了链接模块的内容。若存在链接，应逐个记录模块名与目标路径，确认目标可访问，并将实际源码目录另行归档；恢复演练时要连同链接关系一起验证。目标已丢失的链接应先查明原因，不能把它记作已备份。下面的简例仅适用于模块目录内没有链接的实例。

      Linux (Bash)
      Windows (PowerShell)
      BDS_DIR=/path/to/your/BDS
BACKUP_DIR=/path/outside/SFMC_ROOT
if [ -n "$(find modules/packages -mindepth 1 -maxdepth 1 -type l -print -quit)" ]; then
  echo "modules/packages contains links; back up each target separately" >&2
else
  mkdir -p "$BACKUP_DIR"
  # 在 SFMC_ROOT 下运行
  tar -czvf "$BACKUP_DIR/backup-sfmc-$(date +%Y%m%d_%H%M%S).tar.gz" \
    data/ \
    configs/ \
    modules/ \
    packs/ \
    "$BDS_DIR/worlds" \
    "$BDS_DIR/behavior_packs" \
    "$BDS_DIR/resource_packs"
fi

      恢复服务拉起

      检查归档可打开、关键文件齐全，并记录归档路径与哈希。若此次只做例行备份，可重新启动服务；若准备升级，保持停机直至升级与部署完成：

      sfmc> /start -all

      2. 组件升级指引

      SFMC 平台的各层组件相互解耦，可按需分别升级：

      ① 升级 SFMC CLI 与平台运行时

      全局 pnpm 安装
      平台 Monorepo 源码开发者
      # 获取最新版官方 CLI
pnpm add -g @sfmc-bds/[email protected]

# 验证更新后版本
sfmc --version

      pnpm v11 起默认要求新版本发布满 24 小时才参与无版本号解析。升级当天请先运行 pnpm view @sfmc-bds/sfmc version，然后安装该精确版本。

      升级 CLI 不会自动升级已安装模块或已部署的行为包。先确认 SFMC_ROOT 指向目标实例，再按下文更新模块并重新构建、部署，最后启动服务验收。

      ② 升级 Bedrock Dedicated Server

      SFMC 内置了版本检测与升级命令，支持直接从 Mojang 官方源下载：

      # 检查当前运行版本与远端最新版本
sfmc> update --check-only

# 一键下载解压并安全升级
sfmc> update

      文件保留与配置处理

      升级过程中，系统会依据 configs/bds_updater.json 中的 preserve 清单，在覆盖前保留以下文件/目录，覆盖完成后自动恢复：

      • server.properties（服务端配置）
      • whitelist.json / permissions.json（原生白名单）
      • worlds/（所有世界存档与已安装的行为包）
      server.properties 本地化注释

      恢复 server.properties 后，平台会自动将常用配置注释翻译为简体中文说明，并在保留服主既有配置值的前提下补全 EULA 遥测项（emit-server-telemetry=true）。

      涉及数据库 Schema 迁移时，先在隔离副本上演练，并保留迁移前冷备份。不要假定新版本写入的数据可由旧版直接读取。

      ③ 升级业务功能模块

      当上游模块作者在 npm 发布了新版本时：

      # 从官方索引安装其记录的精确版本；升级前记录原版本
sfmc> mod install economy

# 在停服维护时重新组装并部署行为包，不向 BDS 发送 reload
sfmc> mod reload --build-only

      3. 灾难恢复与回滚方案（Rollback）

      如果在升级后发现版本兼容性问题或异常，可按以下方式实施应急回滚：

      故障场景回滚与救援步骤
      模块升级后出现逻辑 Bug停机后从冷备份恢复模块目录、锁文件和 catalog，或运行 sfmc mod install <id> --from npm:@sfmc-bds/module-<id>@<旧版本号> 安装精确旧版；重新构建部署，再启动 BDS 验收。仅 mod disable 也需要重新部署并重启或重载 BDS 才能生效。
      BDS 核心升级后无法启动若配置了 configs/bds_updater.json 的 backup_dir，升级前会自动生成全量镜像；将备份目录中的旧版本二进制解压覆盖回原路径即可。
      误改配置导致启动崩溃停止相关服务，从对应版本的冷备份恢复配置，然后启动并检查新日志。
      数据库损坏或脏数据停止全部写入，保留故障现场副本，再从经校验的冷备份恢复数据库及对应 WAL 文件；启动前检查 SQLite 完整性。不要直接删除当前数据库。
      诊断日志

      服务日志与异常堆栈保存在 <SFMC_ROOT>/.sfmc/logs/ 目录下（db.log、qq.log、bds.log）。在排查或反馈问题时，请附带该目录下的相关诊断日志。