2026-07-23 22:32:51 +08:00
|
|
|
|
# 项目错题本
|
2026-07-23 02:45:19 +08:00
|
|
|
|
|
|
|
|
|
|
## 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-23 22:32:51 +08:00
|
|
|
|
|
|
|
|
|
|
## 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 22:48:15 +08:00
|
|
|
|
|
|
|
|
|
|
## 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`。
|
2026-07-23 22:56:58 +08:00
|
|
|
|
- 验证证据: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 版本都存在。
|
2026-07-23 23:13:22 +08:00
|
|
|
|
- 验证证据:删除 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 请求。
|