Plugins

Plugins

事实来源：主仓 pr-88 @ a312645 的 src/souwen/plugin.py、src/souwen/plugin_manager.py、src/souwen/server/routes/admin/plugins.py，以及主仓 docs/plugin-management.md。

本页是运维侧插件管理（Web Panel / CLI / HTTP API 三入口）。开发侧——怎么写一个插件——见 Plugin Development。

---

1. 三入口对比

入口	适合	进程位置
Web Panel /plugins	日常运维、图形化	浏览器调用服务端 API
CLI souwen plugins ...	脚本、CI、SSH 远程	直接 import souwen.plugin_manager
HTTP API /api/v1/admin/plugins/*	自动化、第三方面板	服务端

三者共用同一份状态文件（data_dir/plugins.state.json）和同一组管理函数，行为完全一致。

---

2. 状态机

flowchart LR
    Start([discover]) --> Loaded[loaded]
    Loaded --> |disable| Disabled[disabled]
    Disabled --> |enable| Loaded
    Loaded --> |reload| Loaded
    Available[available] --> |reload + enabled| Loaded
    Loaded --> |on_shutdown| Available
    Loaded --> |error 加载/卸载| Error[error]

Loading

状态	含义
loaded	已通过 entry-point/配置加载，注册了 adapter / fetch handler
available	目录可发现，但当前进程未加载（多半是禁用列表或包未装）
disabled	写入禁用列表，重启会跳过
error	加载/卸载抛异常，详见服务端日志

改动状态都是幂等的，重启才完全生效。响应里的 restart_required 与 Panel 顶部黄条提示需要重启。

---

3. CLI 完整调用

souwen plugins list                     # 列出全部插件 + 状态
souwen plugins list --health            # 附健康检查（并发调 health_check）
souwen plugins info <name>              # 详情：adapter / fetch handler / health 历史
souwen plugins enable <name>            # 启用（重启后生效）
souwen plugins disable <name>           # 禁用 + 运行时尽力卸载（含 on_shutdown）
souwen plugins health <name>            # 单插件健康检查
souwen plugins reload                   # 重新扫描 entry points（追加加载）
souwen plugins install <package>        # pip 安装（需开关）
souwen plugins uninstall <package>      # pip 卸载（同上）
souwen plugins new <name>               # 生成插件项目骨架

CLI 直接 import souwen.plugin_manager，所以：

• 不需要运行 server 也可用（CI / Docker entrypoint 友好）。
• 不会触碰其他进程的运行时状态：禁用/启用写状态文件，其他进程下次启动才看到。

---

4. HTTP API（受 Admin 鉴权）

export AUTH="Authorization: Bearer $SOUWEN_ADMIN_PASSWORD"

# 列表
curl -H "$AUTH" http://localhost:8000/api/v1/admin/plugins | jq

# 详情
curl -H "$AUTH" http://localhost:8000/api/v1/admin/plugins/superweb2pdf | jq

# 健康检查
curl -H "$AUTH" http://localhost:8000/api/v1/admin/plugins/superweb2pdf/health

# 启用/禁用
curl -X POST -H "$AUTH" http://localhost:8000/api/v1/admin/plugins/<name>/enable
curl -X POST -H "$AUTH" http://localhost:8000/api/v1/admin/plugins/<name>/disable

# 安装/卸载（需开关）
curl -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"package":"superweb2pdf"}' \
  http://localhost:8000/api/v1/admin/plugins/install

# 重新扫描 entry points
curl -X POST -H "$AUTH" http://localhost:8000/api/v1/admin/plugins/reload

完整字段见 HTTP API#7-管理端点。

---

5. Web Panel

1. Admin 登录 → 左侧 插件（/plugins）。
2. 表格列出每个插件：状态 / 来源（entry_point / catalog / config_path）/ 版本 / 健康。
3. 操作按钮：启用/禁用 / 健康检查 / 详情。
4. 顶部"重新扫描"触发 reload。
5. 底部"安装/卸载"卡片在 SOUWEN_ENABLE_PLUGIN_INSTALL=1 时可用，包名必须在允许列表。
6. 任何状态变化后顶部出现黄色横幅提示重启。

---

6. 安全门禁

操作	默认	显式开启
列表 / 详情 / 健康 / 启用 / 禁用 / 重新扫描	受 Admin 鉴权保护	—
安装 / 卸载	拒绝	SOUWEN_ENABLE_PLUGIN_INSTALL=1

为什么 install 默认关？

• pip install 可执行任意 setup.py 代码，相当于以 SouWen 进程权限跑第三方代码；
• 防止 admin 凭据被攻破后扩大破坏面；
• 生产部署建议走镜像构建或 sidecar，而非运行时 pip。

允许列表（src/souwen/plugin_manager.py::ALLOWED_PACKAGES）：

ALLOWED_PACKAGES = frozenset({"superweb2pdf", "souwen-example-plugin"})

外加任何通过 souwen.plugin_catalog entry point 注册的目录条目。

---

7. 状态文件

data_dir/plugins.state.json：

{
  "disabled_plugins": ["legacy_plugin"],
  "installed_via_api": ["superweb2pdf"]
}

• disabled_plugins：启动时被 discover_entrypoint_plugins(skip_names=...) 跳过。
• installed_via_api：仅记账，便于审计。

文件原子写入，反复读写不丢数据；路径来自 config.data_path（默认 ~/.local/share/souwen/）。

---

8. 已知插件目录

名	说明
superweb2pdf	网页截图转 PDF（基于 Playwright Chromium）
souwen-example-plugin	最小示例（参考 examples/minimal-plugin/）

---

9. 排障

现象	修复
状态显示 error	看服务端日志 event=plugin_load_failed；先 disable 让服务可启动；修复后 enable
disable 后还在响应请求	预期：禁用是"重启后跳过 + 运行时尽力清理"。某些 adapter 引用可能被其他模块缓存（如 fetch 调度器）；重启彻底释放
install 报"未启用"	容器/进程缺 SOUWEN_ENABLE_PLUGIN_INSTALL=1。注意：本机 shell 临时 export 不影响已运行的服务，要 export 后再 souwen serve
装成功但插件不出现	1) souwen plugins reload 触发追加扫描；2) 仍不行重启进程；3) 包是否声明 souwen.plugins entry point
health_check 返 degraded	插件作者用它表 "自降级 / 部分能力受限"。不影响 loaded 状态，但 Panel 显示警告

---

10. 接下来

• Plugin Development — 写一个插件
• HTTP API#7-管理端点-Plugins — REST 字段
• 主仓 docs/plugin-management.md · docs/plugin-integration-spec.md