diff --git a/docs/错题本.md b/docs/错题本.md new file mode 100644 index 0000000..a3493d4 --- /dev/null +++ b/docs/错题本.md @@ -0,0 +1,31 @@ +# 项目错题本 + +## 2026-07-22 — 插件 iframe 资源令牌导致页面空白 + +- 阶段:部署 / 功能行为 +- 类型:环境 / 构建 / 功能行为 +- 现象:在 AstrBot 插件页停留一段时间后,点击素材、角色、图库、设置或日志,主壳仍在但页面内容区域消失。 +- 根因:插件页运行在 sandbox iframe 中,一级页面使用动态分片加载;宿主发放的资源令牌有效期较短,切页时 CSS/JS 分片请求可能失效。错误加载没有稳定的页面级兜底,且一次错误处理尝试读取 sandbox 禁止访问的 sessionStorage,触发 SecurityError。 +- 修复或规避:将素材、角色、图库、设置、日志五个一级页面改为主包同步加载;保留工作流次级组件按需加载;对素材分类和标签字段增加异常数据兜底。 +- 预防规则:AstrBot 插件 iframe 中不要把核心一级路由依赖短时令牌的动态分片;浏览器存储访问必须包在 try/catch 中,不能让可选偏好阻断页面渲染。 +- 验证证据:前端类型检查通过;前端契约测试 26/26 通过;插件页和独立 Web 生产构建通过;NAS `astrbot-ops-pro` 重启后入口切换到同步主包并保留 `plugin_data`。 + +## 2026-07-22 — Windows 发布包不能使用 zip 反向解压部署 + +- 阶段:部署 +- 类型:环境 / 部署 +- 现象:Windows `Compress-Archive` 生成的 ZIP 在 NAS `unzip` 时出现反斜杠路径警告,无法作为可靠插件 staging 包。 +- 根因:Windows ZIP 工具写入的路径分隔符与 NAS 解压工具兼容性不稳定,且 NAS SSH 禁用了 SFTP,不能依赖 scp 上传。 +- 修复或规避:改用本地 `tar.gz`,通过 SSH 标准输入流上传到 NAS;在 NAS 临时 staging 解压后,仅覆盖插件源码目录,不触碰 `data/plugin_data`。 +- 预防规则:NAS 部署优先使用 `tar.gz + SSH cat`;部署前执行压缩包列表和关键入口文件检查,覆盖前创建 `plugin_backups` 备份。 +- 验证证据:NAS staging 可正常解压;`pages/imagestudio/index.html` 指向新主包;容器重启后 ImageStudio 重新加载。 + +## 2026-07-22 — 插件目录不能递归删除缓存文件 + +- 阶段:部署 +- 类型:环境 / 部署 +- 现象:以 `agent` 用户整体删除 NAS 插件目录时,容器生成的 `__pycache__/*.pyc` 文件出现权限拒绝。 +- 根因:部分运行时缓存由容器 root 用户创建,宿主 SSH 用户无权删除;直接 `rm -rf` 会中断替换流程。 +- 修复或规避:保留插件目录并使用 staging 内容覆盖;部署前备份旧插件目录,避免删除运行时缓存和数据目录。 +- 预防规则:不要对 NAS 插件目录直接 `rm -rf`;使用权限可行的覆盖式部署,必要时让容器停止后由具备权限的维护流程清理缓存。 +- 验证证据:覆盖式部署成功,容器重启后插件正常加载,数据库和 `plugin_data` 未删除。