Plugins

插件机制

插件机制

架构总览

• 发现与加载：启动时扫描 plugins/*/__init__.py，导入失败仅标红不拖垮启动。
• 门控：以 Setting('enabled_plugins') 逗号分隔 slug 集合为唯一真值。
• 启用：幂等写入权限点 → 预设角色补授权 → db.create_all() 建表 → 写启用清单。
• 禁用：仅从清单移除 slug，不删表、不清数据；前台/后台/API 即时隐身。

官方内置插件

slug	名称	关键接口
banner	轮播图	banner_items('home-hero')；GET /api/v1/banners/
product	产品展示	product_latest()；/product-<id>.html；GET /api/v1/products/<id>；全站搜索提供者
friend_link	友情链接	friend_links()；后台 /friend-links
form	自定义表单	后台 /forms；前台 /form/<slug>；v2.3 由核心转插件
analytics	统计代码	`analytics_head()
oss_storage	对象存储	阿里云/腾讯云/七牛云；v2.4 新增
recruit	招聘管理	recruit_jobs()；/job-<id>.html；简历上传；全站搜索提供者
auto_translate	一键翻译	编辑页多语言 Tab 一键调用百度/有道/Google/DeepSeek 翻译；v2.5.2 新增
db_migrator	数据库迁移	后台把 SQLite 开发库一键迁移到 MySQL/PostgreSQL：建表、按外键依赖逐表复制、PostgreSQL 重置序列、同步 Alembic 版本号；目标库非空保护、连接测试、迁移后免重启热切换；v3.1.0 新增（默认不启用）
member	前台用户中心	注册/登录/资料/改密/找回密码、微信/QQ 一键登录、短信验证码登录、注册协议、栏目会员可见性；v2.6.4 新增（社区插件，builtin=false）

插件依赖、继承与最低版本校验（v2.6.4）

manifest.json 支持三个依赖相关字段（均可选）：

字段	类型	说明
requires	string[]	启用前必须已启用的依赖插件 slug 列表
extends	string	父插件 slug，本插件基于其二次开发，父插件须已安装且已启用
min_core_version	string	最低核心 CMS 版本，低于此值拒绝启用

启用时按 最低核心版本 → requires → extends 顺序强校验，不满足则拒绝启用并返回明确错误；禁用时若有已启用插件依赖或继承该插件，也会被拦截（需先禁用依赖方）。详见项目根目录 PLUGIN_DEPENDENCIES.md。

插件管理页

后台 系统 → 插件管理（权限 system:plugins_manage）。列出全部已发现插件，导入失败的标红显示错误栈；启用/禁用写入审计日志。v2.6.4 起列表中以徽章展示插件的最低核心版本、依赖插件、父插件。

上传 / 卸载 / 打包下载

• 上传：.zip/.tar.gz/.tgz，8 层校验后解压至 plugins/；失败零写入。
• 下载：打包 zip，可在其他站点直接上传复用；写入导出审计。
• 卸载：验证码确认后物理删除目录；内置/启用中不可卸载；数据表保留。