From 7bcb192bd55ff96484a9e8924e29b89a386b0e0b Mon Sep 17 00:00:00 2001 From: Shiroha7z Date: Mon, 28 Sep 2026 15:18:43 +0800 Subject: [PATCH] docs: clarify stable upgrade backup and rollback --- docs/en/guide/backup-upgrade.mdx | 28 +++++++++------- docs/zh/dev/stable-release-plan.md | 14 ++++++-- docs/zh/guide/backup-upgrade.mdx | 54 ++++++++++++++++++------------ 3 files changed, 60 insertions(+), 36 deletions(-) diff --git a/docs/en/guide/backup-upgrade.mdx b/docs/en/guide/backup-upgrade.mdx index ff30a5d0..1a45399e 100644 --- a/docs/en/guide/backup-upgrade.mdx +++ b/docs/en/guide/backup-upgrade.mdx @@ -1,6 +1,6 @@ import { Tabs, Tab } from '@rspress/core/theme'; -# Backup and upgrade +# Backup, upgrade, and rollback ## Backup @@ -8,15 +8,16 @@ 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 -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 -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 --from npm:@sfmc-bds/module-@`; 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/` (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 index fd8697bd..c0726e13 100644 --- 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 index 9a84cf50..e992c3de 100644 --- 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` | **高**。保存已安装的模块版本、代码与启停状态。 | | **`/worlds/`** | 游戏主世界存档（包含地形、实体与建筑） | **极高**。Minecraft 游戏层面的全量物理世界数据。 | +| **`/behavior_packs/`、`/resource_packs/` 与世界包引用文件** | 已部署的行为包、资源包及启用关系 | **高**。回退时需与世界和模块版本一致。 | ### 严禁在运行状态下直接拷贝 SQLite @@ -28,41 +29,52 @@ SFMC 的 `db-server` 默认工作在 SQLite **WAL（预写式日志，Write-Ahea ### 挂起数据库写入并安全停机 -在 `sfmc` 控制台平滑停止数据库与游戏服务： +安排维护窗口，在管理该实例的 `sfmc` 控制台停止服务，并确认 BDS 与 db-server 进程均已退出： ```bash sfmc> /stop -all ``` ### 执行打包归档 -使用系统原生打包工具将关键资产压缩为时间戳归档文件： +使用系统原生打包工具将关键资产压缩为带时间戳的归档。下面的 `BDS_DIR` / `$bdsDir` 必须先替换为当前实例实际的 BDS 目录；不要假定目录名为 `BedrockDedicatedServer`。归档须放在被备份目录之外，且空间足够。若数据库位于 `data/` 之外，应另行纳入。 ```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" ``` ```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") ``` ### 恢复服务拉起 -备份完成确认落盘后，重新唤醒服务： +检查归档可打开、关键文件齐全，并记录归档路径与哈希。若此次只做例行备份，可重新启动服务；若准备升级，保持停机直至升级与部署完成： ```bash sfmc> /start -all ``` @@ -96,7 +108,7 @@ pnpm install && pnpm run build -升级 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 @<旧版本号>` 回退版本。
2. 运行 `sfmc mod reload` 重装世界行为包。若问题紧急，可直接运行 `sfmc mod disable ` 快速熔断关闭。 | +| **模块升级后出现逻辑 Bug** | 停机后从冷备份恢复模块目录、锁文件和 catalog，或运行 `sfmc mod install --from npm:@sfmc-bds/module-@<旧版本号>` 安装精确旧版；重新构建部署，再启动 BDS 验收。仅 `mod disable` 也需要重新部署并重启或重载 BDS 才能生效。 | | **BDS 核心升级后无法启动** | 若配置了 `configs/bds_updater.json` 的 `backup_dir`，升级前会自动生成全量镜像；将备份目录中的旧版本二进制解压回覆盖原路径即可。 | -| **误改配置导致启动崩溃** | 从最近一次生成的冷备份压缩包中，仅将 `configs/` 目录解压还原，随后执行 `sfmc /restart -all`。 | -| **数据库损坏或脏数据** | 1. 执行 `sfmc /stop -all` 强制停机。
2. 移除当前的 `data/sfmc_data.db*` 全套文件。
3. 解压备份中的历史 `.db` 文件并置于 `data/` 下。
4. 重新启动服务。 | +| **误改配置导致启动崩溃** | 停止相关服务，从对应版本的冷备份恢复配置，然后启动并检查新日志。 | +| **数据库损坏或脏数据** | 停止全部写入，保留故障现场副本，再从经校验的冷备份恢复数据库及对应 WAL 文件；启动前检查 SQLite 完整性。不要直接删除当前数据库。 | :::tip 审计追踪 所有操作细节与异常堆栈均可在 `/.sfmc/logs/` 下查阅独立日志（`db.log`、`qq.log`、`bds.log`）。在报告问题前，请附带该目录下的相关诊断信息。