升级与备份

先备份，再升级面板和节点，最后检查游戏服务器与插件。

升级到 1.2.0 前

面板、节点、Registry、Client 与 Wiki 统一为 1.2.0。面板和节点须配套升级，使用相同的生成契约清单。官方插件、插件工作区及 @gamex/plugin-tools 保持 1.0.0。
各安装组件需分别更新。Client 1.2.0 默认使用面板和节点的 1.2.0 镜像；更新服务器不会替换桌面应用及其专用运行环境。
更换镜像或配置前备份，并检查下列文件策略变化。

文件大小策略

FILE_UPLOAD_HARD_MAX_BYTES 统一限制资产上传、工作区上传与导入，以及下载到工作区的文件，默认 2147483648 字节（2 GiB）。

原服务端设置 WORKSPACE_FILE_HARD_MAX_BYTES 和平台设置 workspaceFiles.maxFileBytes 不再控制该上限。记录原值，并从配置中移除旧服务端设置。已有自定义 FILE_UPLOAD_HARD_MAX_BYTES 继续生效，已保存的工作区限制会被忽略，不会自动复制到此项。若此前依赖默认 1 GiB 或其他更小的限制，需在重启前明确设置统一上限；不再提供独立的工作区大小上限。

从工作区下载到浏览器时，每块最多 48 MiB，上传上限不代表浏览器下载的总大小上限。反向代理每次请求至少允许 50 MiB，以容纳 multipart 开销，并按完整传输时长设置超时。见 HTTPS。

从 1.0.0 迁移个人记忆

1.1.0 的迁移会保留个人记忆；不能转换为个人数据的旧共享或工作区记忆、生成任务及用量记录会阻止迁移。先用旧版本导出并备份，再显式移除迁移错误中列出的记录后重试，迁移不会自动删除。

已迁移到 1.1.0 的数据库，升级到 1.2.0 时不会重复转换。使用目标版本检查并应用待执行迁移，不删除个人记忆，也不重新运行初始化。

备份哪些数据

安装方式	备份内容
源码构建面板	仓库根目录的 `config.toml` 及其回滚文件、`data`、`logs` 和程序版本，设置 `GAMEX_CONFIG_DIR` 时使用实际配置目录
安装器部署面板	`/var/lib/gamex-panel/` 下的 `config`、`data`、`logs`，以及服务配置和程序版本
原生节点（Linux）	`/etc/gamex-daemon/` 和 `/var/lib/gamex-daemon/`，一起保存配置、身份和命令日志
原生节点（macOS / Windows）	按节点配置路径，一起备份配置文件、`identity` 和 `state` 目录
Compose	原配置目录、项目名、镜像版本或摘要，以及部署实际使用的 `panel-data`、`panel-logs`、`daemon-data`、`enrollment` 卷，Wiki 模板的卷前缀为 `gamex_`

表中为默认路径。Compose 安装器默认使用 /opt/gamex-compose/，并在配置和清单中记录镜像摘要，应一起备份；自定义部署以实际路径和卷名为准。

外部数据库使用对应数据库的备份工具，配置了外部对象存储时，一起备份存储中的文件。
单独备份各游戏主机上的工作区文件和 Docker 工作区卷，它们不在 Compose 应用的持久卷中。
保留加密密钥、身份材料、文件权限和插件数据。面板 data/assets 下的私有资产原件须与数据库一同备份，外部公开对象存储不包含它们。插件事件绑定和投递记录保存在面板数据库中。
限制备份读取权限，并验证可恢复后再依赖备份。

升级顺序

阅读目标版本说明，检查面板、节点、插件和数据库结构兼容性。
停止受影响游戏服务器的写入或创建一致性快照，再停止面板和受影响的节点服务。
备份数据、旧程序或镜像、配置和 Compose 项目名。
安装目标程序或镜像，保留持久数据。
启动面板前，应用目标面板版本的数据库迁移。
启动服务，验证登录、节点连接、工作区文件、终端、游戏服务器和插件功能。

安装脚本不执行版本升级。升级时保留 Compose 项目名和持久卷。容器化节点通过替换镜像升级，daemon update 仅用于原生节点安装。

执行面板数据库迁移

使用目标版本检查迁移状态并应用待执行更新。从 1.0.0 升级前，先完成个人记忆迁移准备。以下命令会修改数据库，请先完成备份。新安装由浏览器初始化完成，无需重复执行。

源码安装先停止面板，再在目标版本的面板仓库执行，使用与服务相同的账号、配置目录和数据库：

bash

npm --prefix backend run db:status &&
npm --prefix backend run db:migrate &&
npm --prefix backend run db:check

已编译安装可在程序根目录依次运行 node dist/backend/scripts/database.js status、up 和 check，每条成功后再执行下一条，保持服务使用的 GAMEX_CONFIG_DIR 和权限。

Compose 部署先将 compose.yaml 改为目标镜像，再在原配置目录执行。以下适用于本 Wiki 默认模板；自定义项目中的数据库服务需保持运行，--no-deps 不会启动数据库：

bash

docker compose stop panel &&
docker compose pull &&
docker compose run --rm --no-deps panel \
  node dist/backend/scripts/database.js status &&
docker compose run --rm --no-deps panel \
  node dist/backend/scripts/database.js up &&
docker compose run --rm --no-deps panel \
  node dist/backend/scripts/database.js check &&
docker compose up -d &&
docker compose ps

安装器默认部署需将每条 docker compose 前缀替换为 sudo docker --host unix:///var/run/docker.sock compose -p gamex -f /opt/gamex-compose/compose.yaml，自定义过项目或目录时使用实际值。安装器将镜像固定到摘要，仅修改其他位置的标签不会更新部署，需在保留的 Compose 文件中明确选择目标镜像或摘要。

结构检查或迁移失败时，保留备份，先排查错误中的不匹配原因，再启动服务。不要通过删除数据库、重置节点状态或重新初始化来绕过错误。

恢复与回退

恢复前先停止服务，一起恢复匹配的配置、加密密钥、面板数据库、节点身份与命令日志，以及工作区数据。每个面板数据库只运行一个 backend 进程。

回到之前版本时，使用升级前的完整备份和对应程序或镜像。仅替换程序不能还原数据变化；个人记忆迁移前显式移除的记录需从此前备份恢复。保留的插件事件数据、会话集成上下文或不绑定登录会话的排队任务也会阻止数据库回退，任务已经结束不代表可以安全回退。

down -v、删除数据目录或重建数据库会清除持久数据。

升级与备份 ​

升级到 1.2.0 前 ​

文件大小策略 ​

从 1.0.0 迁移个人记忆 ​

备份哪些数据 ​

升级顺序 ​

执行面板数据库迁移 ​

恢复与回退 ​