MCSync 2.0.3

MCSync 2.0.3 发布说明 / Release Notes

发布日期 / Release date: 2026-08-26

中文

MCSync 2.0.3 是一次可靠性修复版。核心原则改为：云端或网络故障不能阻止玩家使用上一次完整可用的客户端；只有本地存在未能自动恢复的事务损坏时才阻止启动，避免继续写坏文件。

主要变更

1. 云端故障放行

   • mods-v5.json、前置自更新入口、文件下载、平台来源或服务器列表临时失败时，保留当前客户端并正常进入游戏，下次启动自动重试。
   • 服务器列表同步独立于玩法 OTA；服务器列表故障不会推翻已经完成的核心更新。
   • 下载、校验和暂存阶段失败不会修改正式文件。

2. 中断恢复与本体更新加固

   • 每次联网前先恢复未完成的本地发布事务，再检查新版本。
   • BakaXL 的持久实例与运行副本会先全部预检下载和哈希，再开始任一目录提交，避免双目录半升级。
   • 若自动回滚失败并留下 .modsync/RECOVERY_REQUIRED.txt，启动仍会被阻止，以免在已知损坏状态上继续运行。
   • 前置自更新不再先生成第二个文件名。退出后只原子替换当前 MCSync JAR 的内容，完整 OTA 在下一次启动整理文件名，消除强杀时出现两个相同 modId JAR 的崩溃窗口。

3. 更快的平台匹配

   • 移除发布阶段的 SHA-512 查询。Modrinth 使用 SHA-1 定位固定文件元数据，客户端仍以清单锁定的大小和 SHA-256 验收实际下载。
   • CurseForge fingerprint/fileId 只用于锁定文件元数据；发布器不再为每个 Mod 重复下载完整 JAR。客户端最终 SHA-256 不符时拒绝该候选并保留旧客户端。
   • 未变化文件继续复用本地哈希与平台证据缓存。

4. 故障回归覆盖

   • 新增 HTTP 500、无效 JSON、文件 503、下载失败、事务中断及人工恢复标记等故障测试。
   • 构建流程新增真实启动冒烟测试：云端不可用必须进入游戏，本地回滚不完整必须阻止启动。

兼容说明

• 技术 modId 仍为 mcmodsync，schema-v5 和旧版升级入口保持不变。
• 2.0.3 可以读取现有 2.0.x 发布项目和清单，不要求重新设计云端目录。
• 云端故障放行不是跳过安全校验：任何下载仍必须匹配清单中的大小和 SHA-256；失败时使用旧文件，而不是安装未经确认的文件。

English

MCSync 2.0.3 is a reliability release. Its central rule is that cloud or network failures must not prevent players from using the last complete working client. Startup is blocked only when a local interrupted transaction cannot be recovered safely.

Highlights

1. Fail-open cloud handling

   • Temporary failures of mods-v5.json, the updater bootstrap, artifact downloads, platform sources, or the server-list endpoint preserve the current client and allow the game to start. MCSync retries on the next launch.
   • Server-list synchronization is isolated from gameplay OTA, so a server-list outage cannot invalidate an otherwise successful core update.
   • Failures during download, verification, or staging do not modify live files.

2. Interrupted-update recovery and safer self-update

   • Pending local release transactions are recovered before any new network work begins.
   • BakaXL persistent and runtime copies are fully prefetched and hash-checked before either copy is committed, preventing a half-updated pair.
   • If automatic rollback fails and leaves .modsync/RECOVERY_REQUIRED.txt, startup remains blocked to avoid operating on known-corrupt local state.
   • The bootstrap updater no longer creates a second updater filename first. After exit it atomically replaces the bytes of the current MCSync JAR; the next full OTA normalizes the filename. A hard kill therefore cannot leave two JARs with the same modId.

3. Faster platform matching

   • Removed publisher-side SHA-512 lookup. Modrinth now uses SHA-1 to locate pinned file metadata, while the client still accepts downloaded bytes only after manifest size and SHA-256 verification.
   • CurseForge fingerprint/fileId is metadata location only. The publisher no longer redownloads every complete Mod JAR; a client-side SHA-256 mismatch rejects the candidate and preserves the old client.
   • Unchanged files continue to reuse local hash and platform-evidence caches.

4. Fault-regression coverage

   • Added coverage for HTTP 500, invalid JSON, artifact 503, download failures, interrupted transactions, and explicit recovery markers.
   • The build now performs real startup smoke tests: cloud outages must reach the game, while incomplete local rollback must block startup.

Compatibility

• The technical modId remains mcmodsync; schema-v5 and legacy upgrade entry points are unchanged.
• 2.0.3 reads existing 2.0.x publisher projects and manifests without requiring a new cloud layout.
• Fail-open cloud handling does not bypass integrity verification. Every downloaded artifact must still match its manifest size and SHA-256; on failure MCSync uses the old file instead of installing unverified bytes.