astrbot_plugin_imagestudio/docs/错题本.md

14 KiB

项目错题本

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 未删除。

2026-07-22 — 在线恢复不能直接覆盖活动 SQLite 与媒体目录

  • 阶段:发布前最终审计
  • 类型:部署 / 数据安全 / 并发
  • 现象:备份恢复接口可在插件正常运行、worker 和请求仍可能写库时,直接覆盖配置与 SQLite 文件,并把媒体目录合并到现有目录。
  • 根因:恢复流程没有维护模式、写入隔离、同盘 staging、原子切换和全链路失败回滚,把多个有状态资源当成普通文件逐个复制。
  • 修复或规避:修复前禁用生产环境在线恢复;恢复必须先停止并确认 worker 退出,拒绝新写入,完整恢复到 staging 并校验后原子切换,失败自动回滚。
  • 预防规则:任何数据库、配置和媒体联合恢复都必须具备 quiesce、staging、atomic switch、rollback 四个阶段,不能在活动 SQLite 上执行 copy2。
  • 验证证据:审计定位 backend/services/data_backup_service.py 的恢复链路;现有测试集没有备份恢复并发和故障注入覆盖;完整建议见 docs/final-release-audit-2026-07-22.md。

2026-07-22 — worker 超时停止后不能丢弃运行实例

  • 阶段:发布前最终审计
  • 类型:并发 / 生命周期 / 功能行为
  • 现象:远程 provider 调用超过停止等待时间时,stop() 可返回仍在运行,但插件 terminate() 仍清空 runtime 引用并允许后续实例启动新 worker。
  • 根因:worker 只有停止事件,无法中断正在执行的 handler;终止链路忽略 running 返回值,没有双实例栅栏和晚到结果保护。
  • 修复或规避:provider 调用必须有可控 timeout/cancel;统一广播停止并确认全部线程退出;仍存活时阻止重新启动 worker并保留 runtime 引用;终态更新使用状态条件保护。
  • 预防规则:生命周期结束只有在所有后台执行器确认停止后才能报告成功;禁止“stop 超时但继续卸载”。
  • 验证证据:审计定位 backend/services/worker_service.py 和 main.py;现有 worker 测试只覆盖可及时退出场景,没有阻塞 handler 热重载测试。

2026-07-22 — 最终审计验证与测试临时目录陷阱

  • 阶段:发布前最终审计
  • 类型:测试 / 环境
  • 现象:复用固定仓库内 --basetemp 运行全套测试时两次超时且残留 pytest 进程;不指定 basetemp 后全套正常完成。
  • 根因:Windows 环境下固定临时目录与残留测试进程/旧目录状态相互影响,且安静模式在长测试期间缺少进度输出,容易误判为代码死锁。
  • 修复或规避:终止本轮残留 pytest 进程,改用 pytest 默认唯一临时目录;对慢文件单独验证后重跑全套。
  • 预防规则:CI 为每次运行生成唯一 basetemp,并设置全局 timeout 和进度输出;测试超时时先查残留进程和单文件耗时,不要直接判定业务死锁。
  • 验证证据:test_advanced_style_set_workflow.py 46 passed in 31.39s;最终 python -m pytest -q 260 passed in 178.03s;前端 26 项契约、typecheck 和双构建均通过。

2026-07-23 — 公司电脑经 ZeroTier 访问后端超时

  • 阶段:网络排障
  • 类型:环境 / 网络 / 功能行为
  • 现象:家用电脑访问 ImageStudio 正常,公司电脑经 ZeroTier 访问时出现“后端连接 timeout”。
  • 根因:当前尚未拿到公司电脑的实际请求失败包;现有证据排除“NAS 端口未监听”和“插件进程完全未启动”,优先怀疑公司网络到 ZeroTier 网段的路由、ZeroTier flow rule/成员授权、Windows 防火墙或实际访问端口不一致。应用侧首屏 bootstrap 只等待 6 秒,插件 bridge GET 等待 15 秒,链路有丢包/中继延迟时会被前端表现为后端超时。
  • 修复或规避:先在公司电脑验证 ZeroTier IP 到实际映射端口 26385 的 TCP 连通性,并确认浏览器访问的地址不是旧端口 6185;若 TCP 不通,放行公司电脑到 NAS ZeroTier 地址 10.147.17.231 或 172.24.141.75 的对应端口并检查 ZeroTier 授权/Flow Rules;若 TCP 通但页面仍超时,再检查浏览器开发者工具中 ui/bootstrap 的请求、认证会话和响应耗时。
  • 预防规则:不要只用“页面能打开”判断后端链路正常;必须分别验证静态入口、ui/bootstrap API、实际容器映射端口和 ZeroTier path。区分 TCP timeout、HTTP 401/403、CORS 和应用 6 秒 bootstrap timeout 后再改代码。
  • 验证证据:NAS 路由存在 10.147.17.0/24 与 172.24.0.0/16 ZeroTier 网段;26385/26395/26399 监听在 0.0.0.0;NAS 本机通过 127.0.0.1、192.168.31.210、10.147.17.231、172.24.141.75 访问 26385 均返回 HTTP 200;插件日志可见正常加载,但当前 NAS 日志版本为 1.0.66。项目代码中 bootstrap timeout 为 6 秒,bridge GET timeout 为 15 秒。

2026-07-23 — 角色删除被示例来源判断静默拦截

  • 阶段:功能修复
  • 类型:功能行为 / API契约
  • 现象:角色详情页点击“删除”无确认弹窗、无请求、页面角色不消失。
  • 根因:前端删除函数额外判断 profile.metadata.source === "sample" 后直接返回;该判断没有错误提示,也与后端已授权角色软删除接口的能力边界不一致,导致用户可见角色被静默当作不可删除示例处理。
  • 修复或规避:删除流程只保留角色存在、未处于删除中和后端写权限检查;移除删除专用的 sample 静默拦截。示例角色的生成、工作流和素材编辑限制保持不变。
  • 预防规则:前端禁止操作必须有明确 UI 状态或错误提示;不要在单个操作中复用与其他操作不同的 sample 保护条件,先对照后端路由权限和资源生命周期。
  • 验证证据:已修改 frontend/standalone-web/src/App.vue:6241;前端 vue-tsc --noEmit 通过;契约测试 26/26 通过;git diff --check 通过。

2026-07-23 — NAS 部署路径与容器重启边界

  • 阶段:部署
  • 类型:部署 / 环境
  • 现象:首次部署校验失败是插件目录拼写错误;随后在容器内执行 docker restart 导致执行 shell 被 context canceled 终止,旧 staging 目录短暂留在插件扫描目录并被 AstrBot 当作第二个插件加载。
  • 根因:实际目录是 astrbot_plugin_imagestudio,不是 astrabot_plugin_imagestudio;容器内重启自身会立即杀掉当前 exec;AstrBot 会扫描 data/plugins 下所有目录,旧目录不能用改名方式留在那里。
  • 修复或规避:改用正确目录名;旧目录移入 /AstrBot/data/plugin_backups;重启必须由 NAS 宿主机执行;部署包先做 SHA-256 校验再替换。
  • 预防规则:部署脚本必须先验证目标目录存在;禁止在目标容器内部重启自身;插件旧版本只允许放在 plugin_backups,不得留在 data/plugins。
  • 验证证据:NAS 容器 Up;日志只加载一个 astrbot_plugin_imagestudio (1.0.66);插件 metadata 为 1.0.66;frontend/standalone-web/src/App.vue:6241 删除修复标记存在;容器状态为已知的 health: starting。

2026-07-23 — 插件桥接不支持角色删除 DELETE

  • 阶段:功能修复
  • 类型:API契约 / 功能行为
  • 现象:角色详情页删除按钮仍无效;前端在插件 iframe 中调用 DELETE,但部分 AstrBot Plugin Page bridge 只暴露 apiPost,请求回退到未注册的 method override 路径。
  • 根因:后端只注册 DELETE profiles/{profile_id},没有给桥接层提供稳定的 POST 删除入口;DELETE 能力是否暴露取决于 AstrBot 版本和运行时 bridge 实现。
  • 修复或规避:新增 POST profiles/{profile_id}/delete,复用原有所有者校验、软删除和审计逻辑;前端角色删除统一调用该 POST 入口,保留原 DELETE 接口兼容外部调用。
  • 预防规则:插件 iframe 内的写操作优先提供明确的 POST 动作路由;不能假定 apiPut、apiPatch 或 apiDelete 在所有 AstrBot 版本都存在。
  • 验证证据:删除 POST 路由回归测试通过;前端类型检查通过;插件页与 standalone web 构建通过。

2026-07-23 — 插件 iframe 原生确认框吞掉删除动作

  • 阶段:功能修复
  • 类型:功能行为 / 环境
  • 现象:删除按钮点击后没有后端审计记录,页面也没有删除结果。
  • 根因:角色删除流程依赖 window.confirm;AstrBot 插件 iframe 的原生确认框在部分运行时可能不显示或直接返回取消,导致函数在请求前静默退出。
  • 修复或规避:删除操作不再依赖原生确认框,直接调用已有 POST profiles/{profile_id}/archive 软删除接口;后端仍保留权限、所有者和审计校验。
  • 预防规则:插件 iframe 中不要把关键业务动作依赖在 window.alert/confirm/prompt 上;需要确认时使用应用内对话框,或让动作具备明确的单击语义。
  • 验证证据:NAS 审计查询确认此前没有 delete_profile 或 update_profile 记录;前端修改后需重新构建并验证 POST 请求。

2026-07-23 — 文本角色导入入口藏在问卷外层

  • 阶段:功能优化
  • 类型:功能行为 / UI
  • 现象:创建角色问卷里没有直接上传文本识别入口,用户只能先退出问卷再从角色页寻找外部角色卡导入。
  • 根因:文本导入功能已实现,但入口只放在工作台动作卡,未与问卷填写流程相邻。
  • 修复或规避:在问卷标题栏增加“导入文本识别”按钮,复用现有 .txt/.md/.markdown 上传、粘贴、模型识别和问卷回填流程。
  • 预防规则:与当前编辑表单强相关的导入能力应放在表单标题或首屏操作区,不应只依赖外层工作流卡片。
  • 验证证据:前端类型检查和生产构建通过后,需确认按钮打开外部角色卡识别层并自动回填问卷。

2026-07-24 — 问卷标题栏按钮选择器误匹配

  • 阶段:功能修复
  • 类型:编码 / UI
  • 现象:新增“导入文本识别”后,按钮文字竖排并与关闭按钮错位,没有出现在标题栏右上角。
  • 根因:.persona-questionnaire-card header > div 同时匹配标题内容容器和右侧操作容器,覆盖了操作容器原本的 flex 布局。
  • 修复或规避:将标题内容选择器收窄为 .persona-questionnaire-card header > div:first-child,保留操作容器的横向 flex 布局。
  • 预防规则:新增嵌套布局容器时避免使用过宽的结构选择器,检查同级操作区是否被继承布局规则覆盖。
  • 验证证据:npm.cmd run typecheck、npm.cmd run build、git diff --check 通过;提交 2dbf90b 已推送;NAS 容器加载 astrbot_plugin_imagestudio (1.0.66),远端源码包含收窄后的选择器,旧插件已备份。