从v3到v4：Godot AI升级迁移指南与签名自更新系统原理
【免费下载链接】godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.项目地址: https://gitcode.com/gh_mirrors/go/godot-ai
Godot AI 是一款为 Godot 引擎打造的 MCP 服务器与 AI 工具集，可以让 Claude Code、Codex、Cursor 等 AI 客户端直接操作实时编辑器。本文带你完成一次Godot AI v3 到 v4 的升级迁移，并讲清背后"签名自更新系统"的工作原理——一次点击，自动验签、原子替换、失败可回滚，无需手动替换文件。
为什么 v4 是一次"破坏性"升级
v4 是一次主版本跨越，官方称之为 breaking release：它不再保留永久性的 v3 运行时分支，且要求Godot 4.7 及以上的 4.x 版本。主要变化包括：
- 客户端连接方式：v4 使用
godot-ai attach经 stdio 连接，裸的http://127.0.0.1:8000/mcp地址无法完成认证，也不再被接受； - 端口与能力轮换：跨版本更新会预先选定一对空闲的本地回环端口，并写入原子化的端点覆盖项，老桥接进程无法再向 v4 认证；
- Cherry Studio 不再支持：其 MCP 条目存放在内部数据库中，官方无法安全读写，需你在应用内自行删除旧的 v3 条目；
- 客户端配置自动重钉：受支持的客户端条目（Claude Code、Codex、Cursor、VS Code 等）会被自动迁移更新。
一键升级：v3 到 v4 的完整步骤
整个迁移正常只需三步，全程在编辑器内完成，无需下载发布文件、运行校验器或手动重启 Godot：
- 备份项目：像对待任何大版本更新一样，提交或备份你的项目；
- 确认
uvx可用：Python 服务器由uvx运行，需已安装并在 PATH 中； - 点击一次 Update：用 Godot 4.7+ 打开项目，在 Godot AI dock 中点击Update。
迁移期间请保持 Godot 打开。插件会准备好并认证 v4、替换整个 add-on 目录树、更新受支持的客户端条目，然后自动重启一次匹配的受管服务器。若某个 AI 客户端没有察觉配置变化，只需重开那一个客户端——重启所有客户端不是迁移的必要步骤。
⚠️ 如果你的 AI 客户端运行在另一台机器或容器里（通过裸 URL 访问 v3 的 8000 端口），请先按 client-configuration.md 搭建 SSH 启动的桥接，再执行升级。
迁移"胶囊"：跨版本的关键设计
v4 稳定版发布恰好6 个资产：
- 正式的 v4 三件套：
godot-ai-v4-plugin.zip、.manifest.json清单、.manifest.sig清单签名； - 旧命名的迁移胶囊三件套：
godot-ai-plugin.zip、.sha256、.sha256.sig，供 v3 的更新器消费。
胶囊不是第二份 v4 发行物，而是一个小型"桥接插件"，内部嵌着上面三份正式资产。v3 的签名更新器像处理任何 v3 版本一样认证并解包胶囊，桥接随后在编辑器内运行自带的 v4 安装器，完成：
- 校验内嵌的清单签名、发行身份、压缩包哈希和库存中的每一个文件；
- 将校验通过的树暂存到
addons/.godot_ai_update/stage/并重新哈希； - 移除 v3 的
game_helperautoload，把整个旧 add-on（含桥接）重命名到addons/.godot_ai_update/backup/<旧版本>/，再把新树重命名到位——两次重命名，绝不做逐文件覆盖； - 持久化 v4 插件启用状态，重启 Godot。
首次以 v4 启动时，插件会先把活动目录树与签名库存逐一哈希比对，通过后才记录success、重钉客户端条目并启动受管服务器。
签名自更新系统原理：它防住了什么
v4 的自更新路径由 update_installer.gd 实现，全部步骤在编辑器内执行，核心是"校验 → 暂存 → 交换 → 再校验 → 激活"五段式流程：
- 信任根：RSA-4096 公钥内嵌于 update_manager.gd（
RELEASE_SIGNING_PUBLIC_KEY_PEM），私钥只存在于发布签名环境中。外层 v3 签名防止被篡改的胶囊被执行；内层 v4 签名绑定仓库、通道、tag、版本、源提交、正式压缩包哈希与完整文件库存； - 恶意压缩包防护：清单校验会拒绝绝对路径、
..穿越、符号链接、重复或大小写冲突的路径、超量文件等畸形内容； - 原子交换 + 可恢复：旧树始终完整保留在 backup 目录。若交换后哈希不匹配，替换树被隔离到 quarantine、备份被换回，dock 会显示原因（
rolled_back状态）； - 进程锁：
lock.json通过 PID 和进程指纹识别编辑器，另一个打开的编辑器发起更新会被拒绝； - 状态可见：
addons/.godot_ai_update/pending.json标记记录 from/to 版本、清单哈希、预期树哈希与备份路径，任何中断都留下可读的状态而不是静默损坏。
它不防什么（诚实地说）
文档明确列出了边界：签名密钥或签名环境被攻破、两次重命名之间的瞬间断电（备份与标记让它成为"可见且可恢复"而非"静默失败"）、同用户下已存在的恶意代码，以及两个编辑器绕过进程锁的竞态。GitHub 发布说明是可变的，不构成信任锚点——信任根只有签名密钥与发布审查。
迁移中断了怎么办？
重新用 Godot 4.7+ 打开同一项目即可，pending.json标记和旁边的目录树决定后续走向——不要手动删除addons/.godot_ai_update/或 add-on 目录：
| 标记状态 | 含义 | 处理 |
|---|---|---|
success | 活动树与签名库存匹配 | 旧版本保留在 backup，等下次成功更新时清理 |
rolled_back | 哈希不匹配，已回滚到旧版本 | dock 会显示原因，可直接重试 |
repair_required | 不匹配且无备份可用 | 从版本控制恢复addons/godot_ai/，或用关闭编辑器时的安装器重装 |
其他注意事项：
- Godot 4.5/4.6只能加载桥接到"说明要求"的程度，不会激活 v4——升级引擎后重新打开项目，点击Retry migration；
- 4.0.0/4.0.1报告
download failed (302)时，重试无法修复其重定向缺陷，需按 releasing.md 中的恢复流程做关闭编辑器的安装，切勿手工覆盖 add-on 文件； - 非常老的无签名更新器代次在自动迁移的安全边界之外，请先升级到最新 v3 版本。
写在最后
Godot AI 的 v4 升级把"大版本迁移"做成了普通用户一次点击的事：签名验证保证你装到的字节与发布审查过的字节一致，两次重命名保证活动目录要么是旧树要么是新树，备份与标记保证任何意外都停在"可见且可恢复"的状态。对新手来说，只需记住一句话：备份项目、确认 uvx、点击 Update，然后让 Godot 自己重启一次。
更多细节可查阅官方文档：v4-migration.md、self-update.md、packaging-distribution.md 与 releasing.md。
【免费下载链接】godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.项目地址: https://gitcode.com/gh_mirrors/go/godot-ai
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
