docs/zh/updates.md

Rama main · réplica de lectura del repositorio original.

# DiceFrame 应用更新

中文 | [English](../en/updates.md)

这里介绍 DiceFrame 主程序怎么更新。插件请在“管理 → 插件”的插件商店中单独更新。

## 已有数据升级

支持的存档和资料册数据库在载入或启动时自动迁移，沿用 main 拆分后的模块契约，并识别已知的未发布本地存储分支；未知或未来格式明确拒绝。当前存档 schema 48、资料册 schema 12，beta.2 及更早程序不能读取升级后的存档。托管 Docker 保留程序与数据配对，可以恢复上一配对；源码和便携版只回退程序不会还原数据。升级前请停服并备份完整 `data/`，包含 updater 内的数据副本。

旧直填 AI 地址、密钥等配置不自动转换，需要在设置中添加服务商并分配能力引用。部分旧玩家链接需要重新发席位邀请。已有托管 Docker 在 Python/系统运行时兼容时可直接点更新；候选程序在独立副本迁移，失败时旧启动器能恢复旧程序和可读数据，runtime API 保持 1。真正的基础运行时变化仍需更新镜像。完整步骤见[应用更新](updates.md)。

## AI 配置契约变更

**AI 配置契约变更：**应用仅支持 `ai_providers` 与各能力的 `*_provider_ref`，API Key 使用 `ai_provider_key_<id>` 保存到敏感配置。旧能力级直填地址、密钥、API 格式及 `TRPG_LLM_*`、`TRPG_EMBEDDING_*`、`TRPG_TTS_*`、`TRPG_ASR_*`、`TRPG_IMAGEGEN_*` 环境入口不再启用，也不会自动迁移或创建服务商；旧配置更新请求返回 HTTP 400 `unsupported AI config fields`。请在设置页手动添加服务商并分配用途。

主备模型、向量、生图及 OpenAI-compatible/GPT-SoVITS 语音只使用对应服务商引用；缺失或未知引用不会恢复旧地址和密钥，相关远程能力保持未配置。浏览器语音、edge-tts 和已禁用 ASR 无需服务商引用，本地服务商允许空 API Key。服务商连接测试可使用临时地址与密钥，但不会回退到旧能力级配置。

## 不同安装方式

| 安装方式 | 怎么更新 |
|---|---|
| Windows 便携版 | 在“管理 → 设置 → 关于”的版本更新区检查、下载并应用更新 |
| Windows 安装版 | 与便携版相同；直接运行新版安装程序覆盖安装也能升级 |
| 解压的源码发布包 | 在“管理 → 设置 → 关于”的版本更新区应用更新，完成后手动重启 |
| Git 开发目录 | 收到新版本提示后使用 `git pull` |
| 支持托管更新的 Docker / NAS | 在“管理 → 设置 → 关于”的版本更新区下载、应用并自动回滚 |
| 旧 Docker 镜像或基础运行时升级 | 拉取最新镜像并重新创建容器 |

更新主程序不会删除存档和配置。升级前仍建议备份整个 `data/` 文件夹。

## Docker 直接升级与数据保留

升级到支持托管更新的基线镜像后，普通应用版本可以直接在“管理 → 设置 → 关于”的版本更新区完成；Python 或系统运行时变化仍需拉取新镜像。程序不会挂载或控制 Docker socket。

已有 runtime-1 托管 Docker 可以在设置中直接应用新包，Python ABI 和系统运行时兼容时不需要更换镜像；不会因为程序从 2.6 升到新版就被兼容编号拦住。

启动器停止旧服务后，候选程序复制一份独立的游戏与内容数据，并通过 SQLite backup 保留已提交的 WAL 内容。迁移只作用于副本，旧程序的原数据继续可读。旧启动器仍检查真实候选服务的健康状态与观察期，不用维护页面假装应用已启动成功。

数据绑定先单独准备，启动器确认程序后才正式生效。业务写入、插件及外部待发送事件等待确认，界面会显示正在验证。复制失败、启动失败或候选进程异常退出时，上一份数据不受影响，现有启动器可以自动恢复旧程序。

重启已确认版本沿用它的数据，后续升级复制当前正在使用的数据；手动降级使用该旧程序保留的对应数据。确认窗口说明该次升级之后的进度和内容改动不会带回。房主设置、服务商密钥、密码、会话、设备撤销记录及 HTTPS 证书保持当前状态；手动恢复游戏数据会清除旧邀请凭据并关闭玩家入口，需要 GM 重新开启和邀请。升级失败自动恢复时不撤销原邀请。

请备份完整挂载的 `data/`。**不要排除 `data/_updater/data-versions/`、`data-bindings/` 和 `data-pending/`，它们包含业务数据和恢复记录。** 启动器保留当前与上一程序，数据清理保留配对副本和仍被共享设置中的本地文件路径引用的副本，再删除验证过的退役副本；最初的旧数据仍保留。复制需要额外磁盘空间；准备无法在旧启动器启动限时内完成时，更新安全失败并恢复旧服务。真正的 Python/系统运行时不兼容仍需更换镜像。

支持的存档迁移到 schema 48，资料册迁移到 schema 12；歧义或不支持的未来输入明确拒绝。源码与 Windows 便携版沿用既有更新机制，跨格式恢复仍需升级前完整备份。旧直填 AI 配置不会猜测转换为服务商；缺少有效引用时仍需要在设置中配置服务商和能力。

存档 44→45 迁移将本局配置拆为内核配置、叙事偏好和骰子展示偏好，奖励策略归入经济模块；45→46 只建立新剧情、成长和结团写入契约的读者隔离边界，不猜测历史计划、成长标记或回滚记录。视角、覆盖提示词的 `None` / 空对象、幸运超时 `0` 和奖励金额原样保留，账本不重新结算。迁移在副本上进行；不支持的槽位版本或混合格式会明确拒绝，不覆盖原存档。该存档格式号不是应用版本号。

46→47 迁移增加一次性资源恢复权威与旧读者隔离，不会从历史叙事或日志猜测恢复资格。beta.2 及更早程序不能读取升级后的存档；降级应使用对应版本保留的数据或升级前备份。启动时也会重绑定已知旧世界与资料册引用，保留展示名称和内容；歧义、冲突或不支持的未来数据会在发布迁移结果前明确拒绝。

47→48 迁移为好感度回滚快照增加读者隔离。旧存档没有历史好感度分数，因此不会补建或推断这些分数。

## Windows 便携版

打开“管理 → 设置 → 关于”，在版本更新区按页面提示下载并应用即可。更新完成后 DiceFrame 会自动重启并刷新页面。

网络不方便时也可以手动覆盖升级：关闭 DiceFrame，解压新的便携版压缩包，把压缩包里那一层文件夹中的内容（`app/`、`python/`、`DiceFrame.exe`）复制到原安装目录并覆盖，再双击 `DiceFrame.exe`。启动器发现根目录里覆盖进来的版本比当前版本新，会把它当作一次更新：搬进 `versions/`，用与应用内更新相同的健康检查和观察期启动，失败就回到覆盖前的版本。`data/` 留在原处，不需要复制。覆盖时 `DiceFrame.exe` 本身也会换成新启动器，所以已有安装同样适用。

如果新版本无法正常启动，启动器会尝试恢复上一程序，但无法撤销数据迁移；跨数据格式边界需要按上文恢复匹配的数据备份。更新成功后，下载包和多余的旧版本也会自动清理。

便携版保留上一版本时，“管理 → 设置 → 通用 → 系统维护”会显示“回退到上一版本”。检查更新、下载、安装和更新渠道仍在“关于”里。确认后启动器会停止当前服务，用同一套健康检查和观察期启动上一版本；切换成功后两个版本仍会保留，因此可以再次切回。回退只切换程序文件，不删除 `data/`，但仍应先备份数据。

便携版最多保留两套程序文件。初始压缩包根目录里的 `app/` 和 `python/` 算作第一套；第一次更新后它们作为回滚版本保留。第二次及后续更新成功后，程序只保留 `versions/` 中的当前版本和上一版本，并清理根目录里的旧 `app/`、`python/`。`data/`、`logs/` 和根目录启动器不属于版本副本，不会随旧版本清理。当前版本损坏时，启动器会根据版本指针尝试上一版本。用户安装的插件源码存放在 `data/plugin-packages/`，随 `data/` 跨版本保留；`app/plugins/` 仅存放随版本分发的内置与示例插件，会随旧版本清理。

DiceFrame 会在保留控制台输出的同时写入运行日志。Windows 便携版使用根目录 `logs/`，托管 Docker 使用持久化的 `data/logs/`；源码运行默认使用项目根目录 `logs/`。日志按天轮转，只保留最近 30 天，也可以在“管理 → 设置 → 通用 → 运行日志”中手动清除。运行日志与对局记录、聊天历史和存档相互独立。

如果版本更新区只有新版本提示、没有应用按钮，请先到 GitHub Releases 手动下载一次最新便携版。之后即可继续从“管理 → 设置 → 关于”更新。

## 源码发布包

从 GitHub Releases 下载并解压的源码版，可以在“管理 → 设置 → 关于”的版本更新区应用更新。完成后按提示手动重启 DiceFrame。

更新前的程序文件会自动备份，失败时会尝试恢复。更新成功后只保留最近一次备份，存档和配置不会被覆盖。

如果你使用的是 Git 克隆目录，请继续使用 `git pull` 更新。

## Docker 与 NAS

Docker 用户需要先手动拉取一次支持“托管更新”的基线镜像。这个镜像使用稳定 launcher 管理 `data/_updater/docker-versions/` 中的当前和上一应用版本。完成基线迁移后，普通 DiceFrame 应用版本可以在“管理 → 设置 → 关于”的版本更新区下载和应用；容器 ID 不变，候选版本通过健康检查后才会提交，失败会自动回到上一版本。

托管 Docker 同样会在“管理 → 设置 → 通用 → 系统维护”提供“回退到上一版本”。回退会复用 launcher 的健康检查与观察期，并交换 `current.json` 中的当前/上一版本指针；两个应用副本都会保留。只有清单声明 `data_rollback_safe: true` 的应用版本才允许这样切换。

Docker Update 清单继续要求 `data_rollback_safe: true`，以及匹配的 runtime API / Python ABI。声明 `data_mode: versioned-copy-v1` 的包保留上一程序自己的数据，不要求旧程序读取候选程序的新格式；同时校验 bootstrap 和数据格式声明。旧的兼容包沿用原契约。共享设置与安全数据必须保持向后兼容，改变该共享契约时需要单独的过渡方案。

Python ABI、系统动态库、CA、字体或 launcher 协议变化仍属于基础运行时升级，需要再次拉取镜像。DiceFrame 不挂载 Docker socket，也不会从容器内控制 Docker daemon。

使用 Docker Compose 部署时运行：

```bash
cd /path/to/diceframe  # 必须是存放 docker-compose.yml 的部署目录
docker compose pull
docker compose up -d
```

如果提示 `no configuration file provided: not found`，说明当前目录没有 Compose 配置文件。请进入原部署目录后重试；如果最初使用 `docker run` 启动，则应拉取新镜像后按原端口、卷和环境变量重新创建容器，不能直接套用 Compose 更新命令。

NAS 用户可以直接在设备自带的容器管理界面检查更新、拉取最新镜像并重新创建容器。请确认 `data/` 已挂载到宿主机。

用户存档、配置和插件仍位于 `data/`。`data/_updater/docker-versions/` 存放程序，相邻的数据版本和绑定记录存放持久业务数据。备份时包含整个 updater 目录，不要独立删除指针或数据记录。传统的镜像更新方式始终可用，新镜像会使用与 GitHub Release 完全相同的 Docker 应用更新包作为 seed。

如果你从本地源码构建镜像，请拉取新源码后运行：

```bash
docker compose up -d --build
```

## 常见问题

### 检查更新出现 HTTP 403

这通常表示镜像源和 GitHub 的临时访问额度已经用完，只会影响版本检查，不影响游戏、存档或模型调用。稍后重试，或直接前往 GitHub Releases 查看即可。

### 更新失败

不要删除 `data/`。便携版和托管 Docker 会尽量自动恢复到旧版本；源码版会尝试恢复更新前的程序文件。如果仍无法启动，可以从 GitHub Releases 重新下载对应版本，并保留日志用于排查。

源码发布包和 Git 开发目录没有 launcher 管理的双版本切换，设置页不会提供自动回退按钮；需要保留数据备份后手动恢复旧程序文件或使用对应 Release。