15 KiB
15 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 在 NASunzip时出现反斜杠路径警告,无法作为可靠插件 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.py46 passed in 31.39s;最终python -m pytest -q260 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/bootstrapAPI、实际容器映射端口和 ZeroTier path。区分 TCP timeout、HTTP 401/403、CORS 和应用 6 秒 bootstrap timeout 后再改代码。 - 验证证据:NAS 路由存在
10.147.17.0/24与172.24.0.0/16ZeroTier 网段;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),远端源码包含收窄后的选择器,旧插件已备份。
2026-07-24 — 导入按钮应位于问卷底部操作区
- 阶段:功能修复
- 类型:功能行为 / UI
- 现象:按钮被放在问卷标题栏关闭按钮旁边,且窄宽度下“导入文本识别”竖排;用户实际需要它位于底部“简单问卷 / 复杂问卷”按钮左侧。
- 根因:首次实现只依据标题栏语义放置按钮,没有对照问卷底部操作区的视觉标记;按钮缺少不换行和最小宽度约束。
- 修复或规避:移除标题栏导入按钮,将其放入
.persona-questionnaire-footer-actions,顺序为导入、问卷模式、生成档案,并增加white-space: nowrap与min-width。 - 预防规则:涉及截图定位的 UI 修改必须以用户标记的实际容器为准,并在桌面与窄屏布局检查按钮文字是否换行。
- 验证证据:
npm.cmd run typecheck、npm.cmd run build、git diff --check通过;提交878f1f6已推送;NAS 容器加载1.0.66,远端源码确认导入按钮位于 footer,标题栏仅保留关闭按钮。