VexBot 备份与恢复

← 运维与备份 · 所有分区

在面板「设置 → 备份与恢复」操作。默认手动备份，不启动定时任务，不需要显卡或额外依赖。

创建与保存

服主点击「创建并下载备份」，在本地 data/backups 保存 ZIP 并下载到浏览器；授权团队成员可以创建备份，但密钥文件只由服主下载。列表显示总占用空间，可再次下载或删除；删除服务器上的副本不删除已经下载的文件。最多保留 100 份。

「保留规则」默认关闭自动清理，可设置保留份数（1–100）、保留天数（1–365）和是否保护手动备份。超过任一规则的非保护备份可清理；恢复前安全备份和损坏文件始终保护。保护文件计入总份数，可能使数量超过规则；达到硬上限时仍需手动处理。可保存规则后点击「按规则立即清理」，或开启每小时自动检查、创建备份前检查。规则设置变化不会直接删除文件，自动清理只在启用后运行。

备份包括：

• 主程序已保存的配置：QQ 连接、服务器、关联群、命令和功能开关。
• SQLite 数据库：玩家档案、手动归属地、绑定、到访记录、社区账号、密码哈希、游戏 UUID 关联及日志。
• 邮件注册设置、网站 API 设置和游戏登录设置。
• 社区官网名称、内容、游戏地址、入群链接、配色、默认明暗模式、网格/公开/登录开关，以及网站地址、公开 API 地址和接入方式（不接入 / VexBot 官网 / 自建官网）。
• 当前 JSON 插件文件，以及插件启用状态、关键词回复和插件权限。
• 定时任务、执行记录、白名单申请、审核备注及申请设置。
• 服主账号、团队管理员密码哈希及权限、运行提醒设置、故障历史、服务器统计和最多 150 条插件版本快照。

不会包含 Minecraft 世界、游戏服务端插件配置、AuthMe 数据、JAR、Python 环境、历史 ZIP、官网静态源文件与部署包或已移除插件的归档。不包含面板里尚未保存的草稿。迁移游戏服务器还需要分别备份这些服务器文件。官网部署包可在面板重新下载。

ZIP 包含管理令牌、OneBot / 游戏密钥、SMTP 授权码等敏感设置，不是加密文件。请存放在受保护的位置，不要公开上传或转发。 数据库中的游戏密码保持哈希，不会导出明文密码。

数据库使用 SQLite 在线备份接口，包含已经提交到 WAL 的数据；不直接复制打开中的 DB 文件，也不拼接 WAL 文件。压缩、完整性检查和大文件摘要计算在后台线程完成，一次只允许一个创建、上传或恢复操作。ZIP 最大 64 MiB，数据库最大 128 MiB，全部解压数据最大 144 MiB。

恢复

上传后预览会显示当前与备份的玩家档案、账号、绑定、服务器、插件数量及变化值，以及将替换的配置分类。数量差异不是逐条合并；恢复仍是完整替换。管理员权限和保留规则变动会使旧预览失效。恢复后所有面板管理会话撤销，本机兼容管理 API 令牌和连接设置保留。

1. 点击「上传备份，预览恢复」，选择 VexBot 生成的 ZIP。校验清单、文件摘要、配置、插件格式、数据库结构和完整性后，显示玩家、账号、绑定、服务器及外部插件数量。关键词回复属于内置插件，其状态也会恢复。
2. 核对时间和内容，点击「创建安全备份并恢复」并确认。预览有效 5 分钟；设置或插件变化后需要重新上传。
3. 程序自动保存恢复前的副本，停止接收新写入，等待现有工作结束，再关闭服务和数据库。最后刷新安全副本，确保它包含停服前的已提交数据。
4. 恢复数据并重启服务，面板自动重新连接。成功或回滚结果显示在备份页。

恢复会完整替换账号、档案、绑定、业务设置、当前 JSON 插件文件及其状态；备份中不存在的当前 JSON 插件将移除，旧 ZIP 列表保留。

保留当前机器的面板监听地址、端口、app.admin_token 和数据库位置，不会采用上传包中的任意数据库路径。恢复后在原面板地址使用备份时的服主用户名和密码重新登录；旧备份没有服主账号时，点击「创建服主账号」，用当前 app.admin_token 完成首次授权并设置账号。该令牌继续用于兼容管理 API，不是日常登录密码。需要改变地址或存储位置时，在软件设置中另行保存和重启。存在尚未应用的监听 / 数据库更改时，先完成重启再恢复。

网站 API、SMTP、OneBot 与游戏连接密钥恢复为备份时的值。外部 QQ 实现端与游戏插件可能需要更新连接信息。旧邮件验证码、绑定码、网站短期令牌、游戏登录会话和待执行游戏命令撤销，未完成玩家管理任务标记取消，避免恢复后重放旧操作。注册账号、密码哈希和已经建立的游戏身份关联保留。

恢复后的定时任务全部停用，待确认的白名单下发标记撤销。检查服务器、群和预设命令后，再手动启用任务。支持升级前 0.4.0 的 VexBot 备份，新的自动化表会在启动时补齐；不会执行备份内的未知 SQL。白名单历史恢复不直接更改游戏端白名单文件。

旧备份没有 data/website-settings.json 时，恢复后使用默认官网内容和公开范围，请在「网站绑定」中检查设置。官网临时用户令牌与原注册令牌一并撤销。

恢复要求以正常 python -m starbridge run 方式运行，支持服务重启。嵌入式或临时实例仍可导出，但不允许没有重启协调的恢复。

中断和失败

写入错误或恢复后的服务启动失败时，自动恢复操作前的数据库、配置和插件文件。程序在恢复过程中被停止，下次正常启动会检测日志并回滚未确认完成的恢复。

安全备份显示为「恢复前安全备份」，可下载或重新上传预览恢复。如果磁盘权限或硬件故障导致回滚自身也失败，程序不会删除恢复日志和回滚副本；请先修复磁盘问题，保留 data/restore-job.json 与 data/backups/staging，再启动。不要在服务运行时手动覆盖 SQLite 文件。

仅支持本备份格式 v1、与当前程序兼容的数据库结构。其他软件的 ZIP、任意 SQL、脚本插件、符号链接、路径穿越、重复条目、加密 ZIP、超大文件和损坏的数据库均拒绝恢复。

管理 API

服主操作使用 Authorization: Bearer <服主登录后的会话令牌或兼容管理 API 令牌>；团队会话只能执行授予的备份管理操作，下载与恢复仍仅服主可用。不允许使用玩家短期令牌或网站 API 密钥。业务网页无需调用这些接口。响应带 Cache-Control: no-store，预览不会返回 SMTP 或访问密钥。

方法	路径	作用
GET	/api/backups	列表、忙状态、恢复能力、最后恢复结果
POST	/api/backups	创建手动备份，返回 id、时间、大小、版本
GET	/api/backups/{id}	下载 ZIP
DELETE	/api/backups/{id}	删除本地 ZIP
POST	/api/backups/preview	原始 ZIP 请求体，Content-Type 为 application/zip；返回 preview_id、到期时间和数据数量
POST	/api/backups/restore	JSON { "preview_id":"预览编号" }，返回 accepted、safety_backup 和消息

普通 JSON 接口继续受原有请求体限制，ZIP 上传单独采用流式读取并实施 64 MiB 上限。409 表示已有操作、预览过时或存在待重启设置；410 表示预览已过期；413 表示超出大小限制；503 表示此启动方式不能恢复或正在维护。上传到期的临时副本会在后续上传时清理，不计为正式备份。