简介
本文件聚焦于 DouPHP 后台「模块管理」能力，围绕在线安装、本地安装与卸载三大场景，梳理控制器、服务、模型与视图的职责边界、数据流向与安全校验策略。模块管理以配置驱动为主，结合云端扩展列表与本地缓存 zip 包，为站点提供灵活的模块化扩展能力。
项目结构
模块管理相关代码集中在后台 admin 目录下，采用 MVC + Service 分层：
- 控制器：负责请求处理、参数校验与视图渲染
- 服务：封装业务逻辑（会话、云端交互、安装/卸载流程）
- 模型：仅用于轻量数据访问（如统计逻辑表行数）
- 视图：统一使用 module.htm 模板，通过 rec 参数切换不同功能页签
graph TB
subgraph "后台模块管理"
C["控制器<br/>ModuleController"]
S["服务<br/>ModuleService"]
M["模型<br/>Module"]
V["视图<br/>module.htm"]
CFG["配置<br/>config/module.php"]
CLD["云端服务<br/>CloudService / Cloud"]
end
C --> S
S --> M
S --> CLD
C --> V
C --> CFG图示来源
- admin/controller/module/ModuleController.php:30-138
- admin/service/module/ModuleService.php:30-183
- admin/model/module/Module.php:24-60
- admin/view/module.htm:25-58
- config/module.php:1-132
核心组件
- 控制器 ModuleController：暴露在线安装、本地安装、卸载入口；对卸载进行二次确认与权限校验。
- 服务 ModuleService：封装模块索引数据构建、本地安装列表扫描、卸载确认与执行、云端更新状态同步等。
- 模型 Module：提供“若逻辑表存在则返回行数”的辅助方法，用于卸载前数据检查。
- 视图 module.htm：统一页面模板，按 rec 参数在“云端扩展 / 本地安装 / 卸载”三个标签间切换。
- 配置 config/module.php：维护栏目模块、简单模块、AI 关联、会员/工作人员端关联、订单商品关联、菜单与导航显示控制等元信息。
架构总览
模块管理整体遵循“控制器薄、服务厚”的设计：控制器只做路由分发与响应组装，核心逻辑下沉至服务层；模型仅承担最小化数据访问职责。
sequenceDiagram
participant Admin as "管理员浏览器"
participant Ctrl as "ModuleController"
participant Svc as "ModuleService"
participant Model as "Module(模型)"
participant Cloud as "CloudService/Cloud"
participant View as "module.htm"
Admin->>Ctrl : GET 在线安装
Ctrl->>Svc : buildModuleIndexData(system_sign)
Svc->>Cloud : localSitePayload("module")
Cloud-->>Svc : localsite
Svc-->>Ctrl : payload
Ctrl->>View : 渲染云端扩展列表
Admin->>Ctrl : GET 本地安装
Ctrl->>Svc : buildModuleInstallLocalData()
Svc-->>Ctrl : install_list
Ctrl->>View : 渲染本地 zip 列表
Admin->>Ctrl : GET 卸载确认
Ctrl->>Svc : buildUninstallConfirm(extend_id, token)
Svc-->>Ctrl : 确认消息与跳转地址
Ctrl->>View : 渲染确认提示
Admin->>Ctrl : POST 卸载确认
Ctrl->>Svc : performUninstall(extend_id)
Svc->>Model : countRowsIfTableExists(extend_id)
Model-->>Svc : 行数
Svc->>Cloud : clearModule / changeUpdateDate
Svc-->>Ctrl : 完成
Ctrl->>View : 重定向到卸载列表图示来源
- admin/controller/module/ModuleController.php:53-137
- admin/service/module/ModuleService.php:52-161
- admin/model/module/Module.php:44-60
详细组件分析
控制器 ModuleController
职责要点
- index：读取 system_sign 并写入会话，调用服务获取 localsite，再拉取云端扩展列表，渲染 module.htm。
- installLocal：调用服务扫描 storage/work/install/*.zip，渲染本地安装列表。
- uninstall：调用服务构建可卸载列表，渲染 module.htm。
- destroy：GET 时进行 extend_id 与 token 校验，调用服务生成确认消息；POST 且含 confirm 时执行卸载并跳转。
关键交互
- 依赖注入 ModuleService 与 CloudService。
- 使用 Request 获取输入，Response 与 BaseController 提供的 respondDeleteResult 渲染统一删除结果。
服务 ModuleService
职责要点
- buildModuleIndexData：根据 system_sign 设置或清理会话，返回 localsite 载荷。
- buildModuleInstallLocalData：扫描 storage/work/install/*.zip，返回待装模块名列表。
- buildModuleUninstallData：合并已安装模块与云端记录，返回可卸载列表。
- buildUninstallConfirm：校验 extend_id，构造确认消息与确认 URL。
- performUninstall：校验 extend_id、是否存在数据、installed 标记文件是否完整，调用云端清理并写审计日志。
- buildUninstallIdList：从配置 site.update_date 中解析已安装模块，并与 module.all_module 合并去重。
安全与健壮性
- 使用 Check::rec、Check::extendId 做基础校验。
- 卸载前检查逻辑表是否有数据，避免误删。
- 通过 audit() 写入后台操作日志。
模型 Module
职责要点
- 占位表名，不用于常规 CRUD。
- countRowsIfTableExists：若逻辑表不存在返回 0；否则执行 COUNT(*) 查询并返回行数。
设计说明
- 该模型仅作为卸载前的数据存在性检查工具，避免直接操作业务表。
视图 module.htm
职责要点
- 统一模板，通过 rec 参数切换三个标签：
- default：云端扩展列表
- install_local：本地安装 zip 列表
- uninstall：卸载列表
- 卸载项通过 data-url 触发 JS 删除流程，URL 携带 token 与 extend_id。
配置 config/module.php
职责要点
- column_module：栏目型模块清单（带分类树）。
- single_module：简单模块清单（单一实体或功能）。
- link_ai：支持接入 AI 能力的模块。
- link_user_center / link_work_center：分别对接会员中心与工作人员端的模块。
- link_order_item：可作为订单购买商品的模块。
- no_show_menu / no_show_nav：控制后台菜单与前台导航的可见性。
用途
- 模块管理在安装/卸载过程中会参考这些清单，决定模块类型、可见性与能力标记。
依赖关系分析
- 控制器依赖服务与云端服务，不直接操作数据库。
- 服务依赖 Cloud Facade 与 Session、Config、Check 等基础设施。
- 模型依赖 ORM 与 DB 门面，仅提供只读统计能力。
- 视图与控制器通过模板变量解耦。
classDiagram
class ModuleController {
+index(request)
+installLocal()
+uninstall()
+destroy(formRequest, request)
}
class ModuleService {
+buildModuleIndexData(systemSign)
+buildModuleInstallLocalData()
+buildModuleUninstallData()
+buildUninstallConfirm(extendId, token)
+performUninstall(extendId)
}
class Module {
+countRowsIfTableExists(extendId) int
}
class CloudService
class Cloud
class Config
class Session
class Check
ModuleController --> ModuleService : "调用"
ModuleController --> CloudService : "拉取云端扩展"
ModuleService --> Cloud : "云端交互"
ModuleService --> Config : "读取配置"
ModuleService --> Session : "读写会话"
ModuleService --> Check : "参数校验"
ModuleService --> Module : "行数统计"图示来源
- admin/controller/module/ModuleController.php:30-138
- admin/service/module/ModuleService.php:30-183
- admin/model/module/Module.php:24-60
性能与扩展性
- 本地安装列表通过 glob 扫描 storage/work/install/*.zip，建议保持该目录整洁，避免大量无用 zip 影响 IO。
- 卸载前通过 COUNT(*) 检查数据量，建议在大数据表上确保索引合理，减少统计开销。
- 云端扩展列表拉取受网络与云端接口性能影响，可在前端增加重试与错误提示。
- 模块清单由配置文件集中管理，新增模块只需在相应数组中添加标识，便于扩展与维护。
故障排查指南
常见问题与定位思路
-
无法连接云端扩展列表
- 现象：模块管理页面提示云端连接失败。
- 排查：检查网络连通性与云端服务可用性；确认 Controller 中 cloudService.fetchExtendList 返回值是否为 null。
- 参考：admin/controller/module/ModuleController.php:59-73
-
本地安装列表为空
- 现象：本地安装标签下无模块可装。
- 排查：确认 storage/work/install 目录下是否存在 *.zip 文件；检查 ModuleService 中的 glob 扫描逻辑。
- 参考：admin/service/module/ModuleService.php:71-85
-
卸载时报“非法参数”或“数据仍存在”
- 现象：点击卸载后提示参数非法或存在数据无法卸载。
- 排查：确认 extend_id 与 token 是否正确传递；检查逻辑表是否存在数据；查看 Module::countRowsIfTableExists 返回的行数。
- 参考：admin/service/module/ModuleService.php:107-161, admin/model/module/Module.php:44-60
-
卸载后未生效
- 现象：卸载成功但模块仍显示已安装。
- 排查：检查 storage/installed/<模块>.installed.php 是否被删除；确认云端 update_date 是否已更新。
- 参考：admin/service/module/ModuleService.php:149-156
结论
模块管理工具以清晰的 MVC + Service 分层组织，将在线安装、本地安装与卸载流程抽象为可复用的服务方法，并通过配置集中管理模块元信息。其优势在于：
- 职责清晰：控制器专注请求与响应，服务承载业务，模型仅做最小数据访问。
- 安全可控：参数校验、二次确认、审计日志与数据存在性检查贯穿卸载流程。
- 可扩展性强：模块清单与能力标记集中于配置，便于按需启用与扩展。
在实际使用中，建议：
- 规范本地安装包的命名与存放位置，便于批量安装。
- 谨慎卸载含数据的模块，必要时先备份或迁移数据。
- 关注云端扩展列表的可用性与错误提示，提升用户体验。