mirror of https://github.com/insistence/RuoYi-Vue3-FastAPI.git synced 2026-09-22 05:02:58 +00:00

Files

T

insistence 2a055ba648 feat: 新增插件系统 (#112 )

* feat: 初始化插件系统

* refactor: 收口插件系统运行时重构

* perf: 优化插件系统类型提示

* fix&perf: 修复和优化插件系统

* fix: 修复gitignore规则误忽略插件文件的问题

* fix: 修复运行时插件根路径算错的问题

* fix: 加强插件发现和路由注册的防护措施

* revert: 回滚定时任务白名单

* fix: 移除未使用的应用路由注册探测

* revert: 恢复部分代码

* perf: 优化插件系统

* docs: 新增插件开发文档

* perf: 优化插件管理模块

* perf: 提升插件系统核心能力

* refactor: 重构生命周期 step runner

* fix: 修复lint错误

* test: 清理测试用例

* test: 调整测试目录名称

* fix: 修复前后端目录硬编码的问题

* fix: 修复插件系统安全性缺口

* refactor: 重新设计插件生命周期 Migration 事务与回滚

* perf: 优化插件系统边界问题

* refactor: 重构当前插件系统的依赖体系设计

* perf: 优化代码

* perf: 优化代码

* fix: 修复代码合并问题

* fix: 修复bug

* perf: 优化代码

* perf&fix: 优化代码和修复bug

* docs: 优化文档格式

* feat: 适配Vue2版本

* docs: 更新README文档

* fix: 修复ruff lint错误

* chore: 更新后端依赖文件

2026-07-28 20:35:18 +08:00

2.8 KiB

Raw Blame History

插件 Migration 故障处理手册

适用场景

本手册用于处理插件安装、升级过程中 migration 执行失败或中断的问题。

插件 migration 采用显式状态记录，不承诺自动回滚 MySQL DDL。平台会保留执行历史，并通过状态阻断不安全的自动重跑。

状态说明

状态	含义	处理方式
`success`	migration 已成功执行	checksum 一致时自动跳过；checksum 变化时必须新增 migration 文件
`failed`	migration 执行失败并记录错误	修复脚本幂等性或数据库结构后可重试
`running`	已开始执行但未记录成功或失败	人工确认数据库结构后标记 success 或 failed
`unknown`	平台无法判断状态	人工核查后标记为明确状态

常见处理流程

running 状态

查看 migration 历史。
- CLI: ruoyi plugin migration-list <plugin_id> --status running
- Web: 插件管理页打开插件详情，在“依赖 / 执行历史”中查看。
检查数据库结构是否已经按 migration 完成。
如果已完成，标记成功。
- CLI: ruoyi plugin mark-success <plugin_id> <migration_path> --note "已人工确认结构完成"
- Web: 点击执行历史中的“标记成功”。
如果未完成，标记失败。
- CLI: ruoyi plugin mark-failed <plugin_id> <migration_path> --note "未完成，允许修复后重试"
- Web: 点击执行历史中的“标记失败”。
修复 migration 幂等性或数据库结构后重新执行安装/升级。

failed 状态

查看错误信息和 attempt_count。
修复 migration 脚本，保证重复执行安全。
重新执行安装或升级。
如果已通过人工方式完成结构变更，可标记成功。

checksum 变化

已成功执行的 migration 文件不能修改。

处理方式:

恢复原 migration 文件内容；或
新增一个后续 migration 文件承载变更。

插件作者约束

SQL migration 应尽量拆小，避免单个文件包含大量不可回滚 DDL。
migration 必须可幂等重试，尤其是 ALTER TABLE、索引、初始化数据。
seed 和 hook 也应可重复执行，不依赖外层事务自动撤销副作用。
不要通过修改已发布 migration 文件修正历史变更。

观测字段

sys_plugin_migration 会记录:

status: 当前执行状态。
attempt_count: 尝试次数。
started_time: 最近开始时间。
finished_time: 最近结束时间。
update_time: 最近状态更新时间。
error_message: 最近失败错误。

生命周期返回 payload 中的 migrations 会包含 status 和 duration_ms。当 migration 失败或中断需要人工处理时，payload 会包含 migrationRecovery，用于展示 migration 路径、状态和恢复建议。

2.8 KiB Raw Blame History