升级与数据维护：data 目录、备份与版本更新

数据目录是整套系统的全部家当——配置、数据库、知识库、插件都在里面。备份意识比升级技巧重要十倍。

data 目录里有什么

所有部署方式的运行数据都在 data 目录（路径因部署方式而异，见各部署页）：

• cmd_config.json：核心配置（面板账号、端口、系统配置）
• dist/：WebUI 静态文件（升级后异常的头号嫌疑）
• 数据库与对话记录
• 知识库索引与向量数据
• skills/：本地技能包
• 各插件自己的数据子目录

特殊部署的数据位置：桌面客户端在 ~/.astrbot；新版启动器在 ~/.astrbot_launcher；旧版 PowerShell 启动器在 bat 脚本同级目录。Docker 部署按挂载卷在宿主机的 data 目录。

备份策略

• 最低限度：定期打包整个 data 目录，升级前必打一份
• 知识库特别提醒：删除文档或知识库不可恢复，原始资料永远另存一份在 data 之外
• 配置文件：改大版本配置前把 cmd_config.json 抄一份
• Docker 用户的 data 是挂载卷，备份宿主机目录即可；但容器内手动装的依赖（uv、Node）重建容器会丢，镜像重建后要补装

升级框架

按部署方式：Docker 换新镜像重建容器；uv 用 uv tool upgrade astrbot；启动器和桌面客户端内更新或重装；源码部署 git pull 后重装依赖。升级前一律先备份 data、升级后进面板确认版本号。

面板文件随框架启动自动检查更新，第一条黄色日志会提示；管理员指令 /dashboard_update 手动更新面板；手动兜底是从 Releases 下载 dist.zip 解压进 data。

升级后常见异常

• 密码正确登不进：旧面板缓存与新后端不兼容——删 data/dist，重启，浏览器强制刷新（Ctrl+Shift+R），详见登录排障
• 面板 404：静态文件没就位——同样用 dist.zip 补，见登录排障
• 插件集体罢工：大版本升级后插件接口可能变动，逐个更新插件、点一键重载修复，顽固的等插件作者适配
• 行为变化：跨大版本（如 v3 → v4）配置结构有重构（人格配置从文件迁移到 WebUI 管理），按新版文档重配而不是硬改旧配置

版本节奏的认知

项目迭代很快，本站整理的功能点基于 v4 系列官方文档，具体功能与界面随版本变化，以官方最新版为准。升级的最小风险路径：小版本及时升（修 bug 为主），大版本等社区反馈一两周再动，动手前备份。