DogeLakeDev · Tanya7z · Sep 28, 2026 · Sep 28, 2026
diff --git a/docs/en/guide/backup-upgrade.mdx b/docs/en/guide/backup-upgrade.mdx
@@ -1,22 +1,23 @@
 import { Tabs, Tab } from '@rspress/core/theme';
 
-# Backup and upgrade
+# Backup, upgrade, and rollback
 
 ## Backup
 
 Back up together:
 
 - `data/` (SQLite)
 - `configs/`
-- `modules/catalog.json`, `modules/module-lock.json`
-- World directory (behavior / resource packs if you need a full restore)
+- `modules/` (installed packages, catalog, and lock)
+- `packs/` and the BDS world, behavior packs, resource packs, and world pack references
 
-Stop db before archiving to avoid inconsistent files under WAL:
+Schedule a maintenance window. Stop BDS and db-server, verify both processes have exited, and then archive the assets above to a location outside the instance. Include the actual database path if it is outside `data/`; do not assume the BDS directory is named `BedrockDedicatedServer`.
+
+Do not copy a live SQLite database while it may have uncheckpointed WAL data:
 
 ```bash
-sfmc> stop db
-# archive data / configs / module lock files, etc.
-sfmc> start db
+sfmc> /stop -all
+# archive and check the backup; keep services stopped if upgrading
 ```
 
 :::warning Important
@@ -45,17 +46,17 @@ pnpm install && pnpm run build
   </Tab>
 </Tabs>
 
-Then restart affected services. The module behavior pack can be rebuilt by the next `start bds` load gate, or manually:
+Confirm `SFMC_ROOT` and the CLI version before changing the instance. Upgrading the CLI does not replace installed modules or the deployed behavior pack. In a maintenance window, install the intended module versions, then build and deploy before starting BDS:
 
 ```bash
-sfmc> mod reload
+sfmc> mod reload --build-only
 ```
 
 ## Upgrade modules
 
 ```bash
 sfmc> mod install <id>
-sfmc> mod reload
+sfmc> mod reload --build-only
 ```
 
 ## Upgrade BDS
@@ -66,14 +67,15 @@ sfmc> update
 sfmc> update --check-only
 ```
 
-db-server runs incremental schema migrations on startup; older databases usually work as-is.
+If the upgrade includes schema migrations, rehearse them on an isolated copy and keep the pre-migration cold backup. Do not assume an older version can read data written by a newer version.
 
 ## Rollback
 
 | Target | Approach |
 | ------ | ------ |
-| Config / lock | Restore from backup and restart |
-| Module behavior pack | Reinstall previous module version, then `mod reload` |
+| Config / lock | Stop affected services, restore the matching cold backup, then start and inspect fresh logs |
+| Module behavior pack | Stop BDS; restore the previous modules, catalog, lock, and deployed pack, or install an exact prior package with `mod install <id> --from npm:@sfmc-bds/module-<id>@<version>`; rebuild and start BDS |
 | BDS | bds-tools rollback (if backup policy enabled) |
+| Database | Stop all writers, preserve a copy of the failed state, restore a verified cold backup, and run SQLite integrity checks before starting |
 
 Runtime state and logs: `<SFMC_ROOT>/.sfmc/` (including `db.log`, `qq.log`, `bds.log` under `logs/`).
diff --git a/docs/zh/dev/stable-release-plan.md b/docs/zh/dev/stable-release-plan.md
@@ -41,7 +41,7 @@
 
 ## 阶段四：发布与复核
 
-- [ ] 通过前三阶段后退出 Changesets `beta` 预发布模式，审查 Version PR 的版本与包间依赖。
+- [x] 退出 Changesets `beta` 预发布模式，审查正式 Version PR 的版本与包间依赖。公开包已发布；阶段三的生产运行门槛仍单独保留。
 - [x] 按依赖顺序发布平台、聚合包和选定模块；核对 npm `latest`、Git tag、GitHub Release 和模块索引。
 - [x] 从公共 registry 进行全新 pnpm 安装，复验 CLI、模块安装和基本功能。
 - [x] 发布正式版公告，列明兼容范围、升级步骤、已知限制和回退版本。
@@ -114,4 +114,14 @@
 - [模块索引 PR #2](https://github.com/Tanya7z/sfmc-modules/pull/2) 合并后自动构建成功；公开 `index.json` 包含 19 个模块，`activity-log=0.2.1`、`data-backup=0.2.1`、`qq-link=0.1.0`。索引对 19/19 个公开 npm 精确版本的联网校验通过。
 - 公共版 CLI `0.2.0` 的 `mod search` 曾把薄索引的 npm 条目显示为 `undefined`，默认安装也未采用索引版本。补丁 PR #114 与正式 Version PR #110 均已合并，Windows/Ubuntu CI 通过，发布 `0.2.1`。全新隔离目录用 pnpm 安装公共 `@sfmc-bds/sfmc@0.2.1` 后，`sfmc --version`、`mod search qq-link` 与从索引安装精确的 `@sfmc-bds/module-qq-link@0.1.0` 均通过，`check-modules OK`。
 - [SFMC 0.2.1 正式版公告](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/releases/tag/%40sfmc-bds/sfmc%400.2.1) 已发布，列出 pnpm 安装、兼容范围、升级前冷备份、未验收项与回退步骤。
-- 生产服未在本轮重启或升级。本机客户端无法连接隔离测试服，维护者要求跳过本次客户端实测；现有服务器历史数据的升级/回退演练、`qq-link` 的客户端绑定/踢人和 QQ 实际投递仍未验收，不能将公开包发布等同于生产运行通过。因此阶段三相关项及阶段四的前置门槛保留未勾选。
+- 生产服未在本轮重启或升级。本机客户端无法连接隔离测试服，维护者要求跳过本次客户端实测；现有服务器历史数据的升级/回退演练、`qq-link` 的客户端绑定/踢人和 QQ 实际投递仍未验收，不能将公开包发布等同于生产运行通过。因此阶段三相关运行门槛保留未勾选。
+
+## 待维护窗口执行的生产验收
+
+维护者将稍后提供维护窗口。窗口前只核对公开版本、源码和操作文档；不停止、重启或改写正在运行的正式服。执行当日按以下顺序记录证据，不把隔离测试服的数据恢复结果充作现有历史数据的升级结果：
+
+1. 只读记录目标实例的 SFMC 安装来源与版本、`SFMC_ROOT`、BDS 版本和进程、已装模块版本，以及实际数据库与世界目录。确认维护窗口覆盖停机和可回退时间；敏感配置、Token、玩家数据不写入公开记录。
+2. 在窗口内停止 BDS、db-server 及其他写入者，确认进程退出。依照[备份与升级指南](../guide/backup-upgrade.mdx)制作完整冷备份，检查关键文件、归档可读性与哈希；保留原版 CLI、模块包和部署包的版本记录。
+3. 从冷备份恢复至隔离副本，对**真实历史数据副本**演练正式版升级、数据库迁移、模块组装与部署；检查 SQLite 完整性、关键配置兼容和启动日志。再恢复原备份到隔离副本，确认回退后可启动。任何失败先修复或终止本次生产升级。
+4. 仅在演练通过后，按实际安装方式用 pnpm 将目标实例升级到已发布版本；按需升级当前启用的模块，构建并部署行为包。不要在同一窗口顺带升级 BDS 核心。启动服务，核对新的 BDS/db/QQ 日志、部署 catalog 与目标版本，并检查玩家和机器人关键路径。
+5. 若启动或数据检查失败，保持停机，从同一份冷备份恢复平台运行时、配置、数据库、模块与世界包，再启动旧版复核。记录实际回退耗时和结果。此前用户要求跳过的客户端绑定、踢人及 QQ 实际投递仍需另行实测，未测不得勾选对应门槛。
diff --git a/docs/zh/guide/backup-upgrade.mdx b/docs/zh/guide/backup-upgrade.mdx
@@ -1,8 +1,8 @@
 import { Tab, Tabs, Steps } from '@rspress/core/theme';
 
-# 备份与无损升级
+# 备份、升级与回退
 
-数据资产是 Minecraft 服务器的命脉所在。SFMC 在设计之初即贯彻了**高可用与灾备优先**准则，本指南将向运维人员介绍标准化的数据备份流程、全组件升级策略以及紧急故障回滚方案。
+升级前先确认当前服务由哪个 SFMC 安装和工作目录管理，并为数据与世界制作可恢复的冷备份。本指南给出操作顺序；实际路径以本机配置为准。
 
 ## 1. 数据安全与冷备份标准
 
@@ -12,8 +12,9 @@ import { Tab, Tabs, Steps } from '@rspress/core/theme';
 | :--- | :--- | :--- |
 | **`data/`** | SQLite 核心数据库文件（`sfmc_data.db` 及日志） | **极高**。包含所有玩家数据与模块持久化数据。 |
 | **`configs/`** | 平台各服务配置与所有业务模块私有配置 | **高**。丢失后需重新配置机器人凭证、端口与游戏规则。 |
-| **`modules/`** | 模块启停状态锁（`module-lock.json`）与本地代码清单 | **中**。记录哪些模块已被激活，重新开服时需依据此文件装配行为包。 |
+| **`modules/`** | 模块包、`module-lock.json` 与 `catalog.json` | **高**。保存已安装的模块版本、代码与启停状态。 |
 | **`<BDS>/worlds/`** | 游戏主世界存档（包含地形、实体与建筑） | **极高**。Minecraft 游戏层面的全量物理世界数据。 |
+| **`<BDS>/behavior_packs/`、`<BDS>/resource_packs/` 与世界包引用文件** | 已部署的行为包、资源包及启用关系 | **高**。回退时需与世界和模块版本一致。 |
 
 ### 严禁在运行状态下直接拷贝 SQLite
 
@@ -28,41 +29,52 @@ SFMC 的 `db-server` 默认工作在 SQLite **WAL（预写式日志，Write-Ahea
 
 <Steps>
 ### 挂起数据库写入并安全停机
-在 `sfmc` 控制台平滑停止数据库与游戏服务：
+安排维护窗口，在管理该实例的 `sfmc` 控制台停止服务，并确认 BDS 与 db-server 进程均已退出：
 ```bash
 sfmc> /stop -all
 ```
 
 ### 执行打包归档
-使用系统原生打包工具将关键资产压缩为时间戳归档文件：
+使用系统原生打包工具将关键资产压缩为带时间戳的归档。下面的 `BDS_DIR` / `$bdsDir` 必须先替换为当前实例实际的 BDS 目录；不要假定目录名为 `BedrockDedicatedServer`。归档须放在被备份目录之外，且空间足够。若数据库位于 `data/` 之外，应另行纳入。
 
 <Tabs>
   <Tab label="Linux (Bash)">
 
 ```bash
-# 生成带时间戳的统一备份压缩包
-tar -czvf "backup-sfmc-$(date +%Y%m%d_%H%M%S).tar.gz" \
+BDS_DIR=/path/to/your/BDS
+BACKUP_DIR=/path/outside/SFMC_ROOT
+mkdir -p "$BACKUP_DIR"
+# 在 SFMC_ROOT 下运行
+tar -czvf "$BACKUP_DIR/backup-sfmc-$(date +%Y%m%d_%H%M%S).tar.gz" \
   data/ \
   configs/ \
-  modules/module-lock.json \
-  modules/catalog.json \
-  BedrockDedicatedServer/worlds/
+  modules/ \
+  packs/ \
+  "$BDS_DIR/worlds" \
+  "$BDS_DIR/behavior_packs" \
+  "$BDS_DIR/resource_packs"
 ```
 
   </Tab>
   <Tab label="Windows (PowerShell)">
 
 ```powershell
+$bdsDir = "D:\path\to\your\BDS" # 改为实际目录
+$backupDir = "D:\path\outside\SFMC_ROOT" # 改为实际备份目录
+New-Item -ItemType Directory -Path $backupDir -Force | Out-Null
 $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
-Compress-Archive -Path data, configs, modules\module-lock.json, modules\catalog.json, BedrockDedicatedServer\worlds `
-  -DestinationPath "backup-sfmc-$timestamp.zip"
+Compress-Archive -LiteralPath data, configs, modules, packs, `
+  (Join-Path $bdsDir "worlds"), `
+  (Join-Path $bdsDir "behavior_packs"), `
+  (Join-Path $bdsDir "resource_packs") `
+  -DestinationPath (Join-Path $backupDir "backup-sfmc-$timestamp.zip")
 ```
 
   </Tab>
 </Tabs>
 
 ### 恢复服务拉起
-备份完成确认落盘后，重新唤醒服务：
+检查归档可打开、关键文件齐全，并记录归档路径与哈希。若此次只做例行备份，可重新启动服务；若准备升级，保持停机直至升级与部署完成：
 ```bash
 sfmc> /start -all
 ```
@@ -96,7 +108,7 @@ pnpm install && pnpm run build
   </Tab>
 </Tabs>
 
-升级 CLI 后，直接重启后台服务即可无缝对接新版指令能力。
+升级 CLI 不会自动升级已安装模块或已部署的行为包。先确认 `SFMC_ROOT` 指向目标实例，再按下文更新模块并重新构建、部署，最后启动服务验收。
 
 ---
 
@@ -122,7 +134,7 @@ sfmc> update
 在安全复原 `server.properties` 后，更新引擎会自动对其执行结构化本地化辅助：在**百分之百保留服主既有自定义配置值**的前提下，自动将配置注释升级为结构清晰的简体中文说明，并校验补全 EULA 遥测项（`emit-server-telemetry=true`）。
 :::
 
-升级完成后，`db-server` 会在首次握手时自动跑增量 Schema 迁移，旧版本数据表结构完全向下兼容。
+涉及数据库 Schema 迁移时，先在隔离副本上演练，并保留迁移前冷备份。不要假定新版本写入的数据可由旧版直接读取。
 
 ---
 
@@ -131,11 +143,11 @@ sfmc> update
 当上游模块作者在 npm 发布了新版本时：
 
 ```bash
-# 重新安装指定模块（自动覆盖拉取最新版源码）
+# 从官方索引安装其记录的精确版本；升级前记录原版本
 sfmc> mod install economy
 
-# 重新组装行为包并向游戏发出热重载指令
-sfmc> mod reload
+# 在停服维护时重新组装并部署行为包，不向 BDS 发送 reload
+sfmc> mod reload --build-only
 ```
 
 ## 3. 紧急灾难恢复与回滚方案（Rollback）
@@ -144,10 +156,10 @@ sfmc> mod reload
 
 | 故障场景 | 回滚与救援步骤 |
 | :--- | :--- |
-| **模块升级后出现逻辑 Bug** | 1. 运行 `sfmc mod install <id>@<旧版本号>` 回退版本。<br/>2. 运行 `sfmc mod reload` 重装世界行为包。若问题紧急，可直接运行 `sfmc mod disable <id>` 快速熔断关闭。 |
+| **模块升级后出现逻辑 Bug** | 停机后从冷备份恢复模块目录、锁文件和 catalog，或运行 `sfmc mod install <id> --from npm:@sfmc-bds/module-<id>@<旧版本号>` 安装精确旧版；重新构建部署，再启动 BDS 验收。仅 `mod disable` 也需要重新部署并重启或重载 BDS 才能生效。 |
 | **BDS 核心升级后无法启动** | 若配置了 `configs/bds_updater.json` 的 `backup_dir`，升级前会自动生成全量镜像；将备份目录中的旧版本二进制解压回覆盖原路径即可。 |
-| **误改配置导致启动崩溃** | 从最近一次生成的冷备份压缩包中，仅将 `configs/` 目录解压还原，随后执行 `sfmc /restart -all`。 |
-| **数据库损坏或脏数据** | 1. 执行 `sfmc /stop -all` 强制停机。<br/>2. 移除当前的 `data/sfmc_data.db*` 全套文件。<br/>3. 解压备份中的历史 `.db` 文件并置于 `data/` 下。<br/>4. 重新启动服务。 |
+| **误改配置导致启动崩溃** | 停止相关服务，从对应版本的冷备份恢复配置，然后启动并检查新日志。 |
+| **数据库损坏或脏数据** | 停止全部写入，保留故障现场副本，再从经校验的冷备份恢复数据库及对应 WAL 文件；启动前检查 SQLite 完整性。不要直接删除当前数据库。 |
 
 :::tip 审计追踪
 所有操作细节与异常堆栈均可在 `<SFMC_ROOT>/.sfmc/logs/` 下查阅独立日志（`db.log`、`qq.log`、`bds.log`）。在报告问题前，请附带该目录下的相关诊断信息。