模块清理工具 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

模块清理工具

简介

本仓库为 DouPHP 模块化企业网站管理系统，提供"三端入口 + 共享核心 + 模块化"的架构。围绕"模块抽取/迁移/打包/升级/清理"等运维场景，项目在 _'/tool 目录下提供了完整的工具链，包括：

传统工具：

将站点源码按模块抽取到独立包（便于发布或二次分发）
从旧版安装包合并 data/_update 到新的 storage/_update
一次性将历史 data 目录统一重命名为 storage
执行 v1.9 版本结构升级

新增专业清理工具：

remove.php：模块删除与小程序开源清理，支持完整发现规则匹配
remove.install.php：安装准备工具，包含 storage 目录修剪和安装锁管理
remove.update.php：升级专用清理，处理根目录散文件和导航目录

这些工具以 CLI/Web 双入口、纯文本输出、可配置白名单/黑名单的方式工作，强调安全与可回滚（先预览再执行）。

章节来源

README.md:1-101

项目结构

与模块清理相关的关键目录与文件：

传统工具：

_'/tool/index.php：模块抽取主脚本（按规则收集源文件并复制到 MODULE_PATH/<module>/）
_'/tool/copy_sql.php：旧包 data -> 新包 storage 合并
_'/tool/copy_update.php：旧包 _update -> 新包 _update 合并
_'/tool/migrate_data_to_storage.php：一次性把 MODULE_PATH 下各模块的 data 重命名为 storage
_'/tool/upgrade_v1.9.php：v1.9 版本结构升级小程序

新增清理工具：

_'/tool/remove.php：模块删除与小程序开源清理
_'/tool/remove.install.php：安装准备与 storage 目录修剪
_'/tool/remove.update.php：升级专用清理工具

graph TB
A["站点根 ROOT_PATH"] --> B["_'/tool/index.php<br/>模块抽取"]
A --> C["_'/tool/copy_sql.php<br/>data->storage 合并"]
A --> D["_'/tool/copy_update.php<br/>_update 合并"]
A --> E["_'/tool/migrate_data_to_storage.php<br/>data->storage 重命名"]
A --> F["_'/tool/upgrade_v1.9.php<br/>v1.9 升级"]
A --> G["_'/tool/remove.php<br/>模块删除+小程序清理"]
A --> H["_'/tool/remove.install.php<br/>安装准备+storage修剪"]
A --> I["_'/tool/remove.update.php<br/>升级专用清理"]
B --> J["MODULE_PATH/<module>/"]
C --> J
D --> J
E --> J
K["config/module.php<br/>模块清单与标记"] -.-> B

图表来源

_'\tool\index.php:25-50
_'\tool\remove.php:32-82
_'\tool\remove.install.php:32-104
_'\tool\remove.update.php:32-114

章节来源

_'\tool\index.php:25-50
config\module.php:1-132

核心组件

传统工具组件

模块抽取器（index.php）
- 作用：按约定规则扫描站点源码，将某模块涉及的 PHP 层、路由、语言包、模板资源、小程序页面等集中复制到 MODULE_PATH/<module>/，并生成/刷新 installed 清单与 SQL 备份。
- 关键能力：选择性清空输出目录（仅保留 _update/storage）、导出 DDL、保留 INSERT、重写 installed 清单。
数据迁移与合并（copy_sql.php / copy_update.php / migrate_data_to_storage.php）
- 作用：将旧版安装包中的 data/_update 合并到新包的 storage/_update；一次性将 MODULE_PATH 下的 data 目录统一重命名为 storage。
- 关键能力：幂等性提示、预览/执行模式、统计与错误计数。
版本升级器（upgrade_v1.9.php）
- 作用：将旧版（< v1.9）位于 data/ 与根 cache/ 下的关键文件/目录迁移到新版本结构。
- 关键能力：自包含升级、幂等执行、数据库配置自动检测、文件映射复制。

新增清理工具组件

模块删除器（remove.php）
- 作用：在站点根 ROOT_PATH 上对指定模块按与 index.php 相同的发现规则列出并删除其源文件/目录。
- 关键能力：完整发现规则匹配、预览模式、小程序开源清理、共享路径保护。
安装准备器（remove.install.php）
- 作用：为安装准备环境，包含模块删除、storage 目录修剪、install.lock 管理。
- 关键能力：storage 目录语义化修剪、state/ 整目录保留、install.lock 独立删除任务。
升级清理器（remove.update.php）
- 作用：专为升级场景设计的清理工具，处理根目录散文件和导航目录。
- 关键能力：根目录文件清理、admin/nav 目录整体删除、升级包标准 storage 骨架。

章节来源

_'\tool\index.php:52-199
_'\tool\remove.php:32-82
_'\tool\remove.install.php:32-104
_'\tool\remove.update.php:32-114

架构总览

三个维度理解工具链：

输入：站点根 ROOT_PATH（含 front/admin/api/core/languages/theme/miniprogram 等）
处理：各脚本通过"发现规则"定位模块相关文件（目录前缀匹配、声明式路由、模板资源、小程序页面、附加文件/目录、已安装清单）
输出：MODULE_PATH/<module>/（抽取产物）、storage/installed/*.installed.php（卸载清单）、存储/日志统计

sequenceDiagram
participant Dev as "开发者"
participant Tool as "_'/tool/*"
participant Site as "站点根 ROOT_PATH"
participant Out as "MODULE_PATH/<module>"
participant DB as "数据库(仅抽取时)"
Dev->>Tool : 运行抽取/迁移/升级/清理命令
Tool->>Site : 扫描模块文件(目录/路由/模板/小程序/附加)
Tool->>DB : (抽取时) 导出DDL/保留INSERT
Tool-->>Dev : 输出统计/清单
Tool->>Out : 复制/写入产物

图表来源

_'\tool\index.php:25-50
_'\tool\remove.php:444-692
_'\tool\remove.install.php:519-768
_'\tool\remove.update.php:539-788

详细组件分析

模块抽取器（_'/tool/index.php）

功能要点
- 定义列模块/单页模块、扫描根目录、模板/小程序/附加项、排除项
- 每次抽取前对输出目录做"选择性清空"，仅保留 _update 与 storage
- 导出 DDL 并保留已有 INSERT，最终重写 storage/installed/<m>.installed.php
关键流程（简化）
- 解析参数与环境头
- 构建模块目标集合（目录/路由/语言/模板/小程序/附加）
- 复制文件/目录至 MODULE_PATH/<module>/
- 导出 SQL 并写入 backup
- 生成 installed 清单

flowchart TD
Start(["开始"]) --> Parse["解析参数与环境"]
Parse --> Scan["扫描模块文件(目录/路由/模板/小程序/附加)"]
Scan --> CleanOut["选择性清空输出目录(保留_update/storage)"]
CleanOut --> Copy["复制文件/目录到 MODULE_PATH/<module>"]
Copy --> DumpSQL{"是否导出DDL?"}
DumpSQL --> |是| BuildDDL["构建DDL并保留INSERT"]
DumpSQL --> |否| SkipDDL["跳过DDL"]
BuildDDL --> WriteBackup["写入backup/*.sql"]
SkipDDL --> WriteInstalled["写入installed清单"]
WriteBackup --> WriteInstalled
WriteInstalled --> End(["结束"])

图表来源

_'\tool\index.php:52-199
_'\tool\index.php:206-225
_'\tool\index.php:231-353
_'\tool\index.php:500-608
_'\tool\index.php:619-737
_'\tool\index.php:748-790

章节来源

_'\tool\index.php:25-50
_'\tool\index.php:52-199

新增模块删除器（_'/tool/remove.php）

功能要点
- 按与 index.php 相同的发现规则对指定模块进行文件/目录删除
- 支持完整发现规则：PHP 各层目录、声明式路由、语言包、模板资源、小程序页面、附加文件
- 内置小程序开源清理：删除私有配置、清洗 appid、重置生成文件、清洗部署地址
- 默认预览模式，需显式添加 --apply 参数才执行实际删除
关键特性
- 共享路径保护：$skipShared 控制跨模块共享文件的删除行为
- 已安装清单管理：自动处理 storage/install/records/<module>.installed.php
- 小程序四步清理：私有配置删除、appid 清洗、生成文件重置、site.ts 地址清洗

flowchart TD
Start(["开始"]) --> ParseArgs["解析参数(--apply/--modules)"]
ParseArgs --> MiniCleanup["小程序开源清理"]
MiniCleanup --> ModuleScan["扫描模块文件(与index.php相同规则)"]
ModuleScan --> CollectTargets["收集待删除目标(files/dirs/shared)"]
CollectTargets --> PreviewCheck{"预览模式?"}
PreviewCheck --> |是| ShowList["显示删除清单"]
PreviewCheck --> |否| ExecuteDelete["执行文件/目录删除"]
ShowList --> End(["结束"])
ExecuteDelete --> UpdateStats["更新统计数据"]
UpdateStats --> End

图表来源

_'\tool\remove.php:724-771
_'\tool\remove.php:472-692

章节来源

_'\tool\remove.php:32-82
_'\tool\remove.php:472-692

安装准备器（_'/tool/remove.install.php）

功能要点
- 集成模块删除、storage 目录修剪、install.lock 管理三大功能
- storage 目录语义化修剪：只保留必要的运行时目录和文件
- state/ 整目录保留：保护站点运行时状态（安装锁、支付对账锁等）
- install.lock 独立删除任务：与 storage 清理解耦，确保安装状态正确
storage 修剪规则
- 保留目录：cache/template/admin/、cache/template/front/、log/（目录保留，内容清空）
- 整目录保留：state/、watermark/（内容也保留）
- 精确保留文件：backup/index.html、非本次删除模块的 installed.php 清单

flowchart TD
Start(["开始"]) --> ModuleDelete["模块删除流程"]
ModuleDelete --> StoragePrune["storage 目录修剪"]
StoragePrune --> KeepDirs["保留目录(内容清空)"]
StoragePrune --> KeepWholeDirs["整目录保留(state/watermark)"]
StoragePrune --> KeepFiles["精确保留文件"]
KeepDirs --> InstallLock["install.lock 删除任务"]
KeepWholeDirs --> InstallLock
KeepFiles --> InstallLock
InstallLock --> End(["结束"])

图表来源

_'\tool\remove.install.php:276-329

章节来源

_'\tool\remove.install.php:32-104
_'\tool\remove.install.php:276-329

升级清理器（_'/tool/remove.update.php）

功能要点
- 专为升级场景设计，处理升级包相关的清理需求
- 根目录散文件清理：删除 favicon.ico 等用户资产文件
- admin/nav 目录清理：整目录删除后台导航族声明
- 升级包标准 storage 骨架：不保留 log/ 空目录和水印素材
升级特定逻辑
- 保留 data.installed.php 和 language.installed.php 作为基础清单
- 不删除 install.lock（升级不改变站点安装状态）
- 非标准残留清单（如 ai.installed.php）按常规清理

章节来源

_'\tool\remove.update.php:32-114
_'\tool\remove.update.php:285-350

数据迁移与合并（copy_sql.php / copy_update.php / migrate_data_to_storage.php）

copy_sql.php：将旧包 <legacyModuleRoot>/<module>/data 递归合并到 MODULE_PATH/<module>/storage
copy_update.php：将旧包 <legacyModuleRoot>/<module>/_update 递归合并到 MODULE_PATH/<module>/_update
migrate_data_to_storage.php：一次性将 MODULE_PATH 下各模块的 data 重命名为 storage（仅保留 data 顶层项，其余删除）

flowchart TD
A["旧包 data/_update"] --> B["copy_sql.php / copy_update.php"]
B --> C["MODULE_PATH/<module>/storage/_update"]
D["MODULE_PATH/<module>/data"] --> E["migrate_data_to_storage.php"]
E --> F["MODULE_PATH/<module>/storage"]

图表来源

_'\tool\copy_sql.php:21-37
_'\tool\copy_update.php:21-37
_'\tool\migrate_data_to_storage.php:21-53

章节来源

_'\tool\copy_sql.php:39-67
_'\tool\copy_update.php:39-67
_'\tool\migrate_data_to_storage.php:55-78

版本升级器（_'/tool/upgrade_v1.9.php）

功能要点
- 将旧版（< v1.9）位于 data/ 与根 cache/ 下的关键文件/目录迁移到新版本结构
- 支持 config/、storage/、images/ 目录结构的重新组织
- 自动检测数据库配置，支持 mysqli 连接
- 幂等执行，不覆盖已存在的目标文件
关键流程（简化）
- 读取数据库配置（优先 config/config.php，回退 data/config.php）
- 建立数据库连接
- 段一：文件/目录复制（config、storage、images）
- 段二：配置文件格式转换
- 段三：数据库记录路径更新

章节来源

_'\tool\upgrade_v1.9.php:18-24
_'\tool\upgrade_v1.9.php:88-135
_'\tool\upgrade_v1.9.php:138-200

依赖关系分析

模块清单依赖
- config/module.php 维护了列模块/单页模块及各类关联标记（AI、用户中心、工作台、订单商品等），影响模块抽取时的范围判断与行为。
工具间协作
- index.php 负责抽取与清单生成；copy_* 系列负责合并；migrate_data_to_storage.php 负责一次性重命名；upgrade_v1.9.php 负责版本升级
- remove.php 系列工具专注于清理，与抽取工具形成互补
外部依赖
- 抽取阶段依赖数据库连接以导出 DDL；其他脚本主要进行文件系统操作

graph LR
M["config/module.php"] --> I["index.php"]
I --> O["MODULE_PATH/<module>"]
CS["copy_sql.php"] --> O
CU["copy_update.php"] --> O
MD["migrate_data_to_storage.php"] --> O
UV["upgrade_v1.9.php"] --> S["站点根 ROOT_PATH"]
R1["remove.php"] --> S
R2["remove.install.php"] --> S
R3["remove.update.php"] --> S

图表来源

config\module.php:1-132
_'\tool\index.php:25-50
_'\tool\remove.php:32-82
_'\tool\remove.install.php:32-104
_'\tool\remove.update.php:32-114

章节来源

config\module.php:1-132

性能与安全性考量

性能
- 大量文件遍历采用递归扫描与排序，建议在大站点上优先使用 CLI 模式，避免 Web 超时。
- 抽取时 DDL 导出与 SQL 拼接可能耗时，可按需关闭 dumpSchema。
- 新增清理工具优化了文件操作效率，支持批量处理和智能缓存。
安全性
- 所有脚本均输出纯文本日志，便于审计与自动化集成。
- 升级脚本 upgrade_v1.9.php 完成后应立即删除以避免被外部访问。
- 迁移脚本默认预览模式，需要显式添加 --apply 参数才执行实际修改。
- 新增清理工具强化了权限检查和安全验证，防止误删重要文件。
- 共享路径保护机制避免删除跨模块基础设施。

故障排查指南

常见问题
- 权限不足：无法创建/删除目录或文件，检查运行用户对 ROOT_PATH/MODULE_PATH 的读写权限。
- 路径不一致：确认 ROOT_PATH/SUB_PATH/MODULE_PATH/TOOL_PATH 常量是否正确（由 init/init.php 引入）。
- 数据库连接失败：抽取脚本需要数据库连接以导出 DDL，检查配置与扩展。
- 升级失败：检查数据库配置文件的优先级和 mysqli 扩展可用性。
- 清理工具报错：检查目标路径是否存在，确认权限设置是否正确。
诊断方法
- 查看脚本输出的统计信息（files/dirs/errors/skipped 等）
- 使用 --modules=xxx 限定模块，逐步缩小问题范围
- 先在 preview 模式下核对清单，再执行 apply
- 检查 storage 目录结构是否符合语义化要求

章节来源

_'\tool\index.php:206-225
_'\tool\migrate_data_to_storage.php:319-347
_'\tool\upgrade_v1.9.php:88-135

结论

DouPHP 的工具链围绕"模块抽取/迁移/合并/升级/清理"形成完整闭环，具备以下特点：

规则驱动：通过 folderRoots/routeRoots/templateRoots/miniprogramPagesRoot/folderOverrides/extraFiles/excludes 等配置精确控制范围
安全可控：默认预览、可限定模块、纯文本日志、共享路径保护
可组合：多个脚本协同完成从源码到安装包的全流程
版本兼容：提供专门的版本升级工具处理历史数据结构变更
专业化分工：新增的清理工具针对不同场景提供专门化的解决方案

建议在 CI/CD 中优先使用 CLI 模式，配合 --modules 与 --apply 实现自动化抽取与清理。

附录：运行方式速查

传统工具
- 模块抽取：CLI：php index.php；Web：浏览器访问该文件
- 数据合并/迁移：php copy_sql.php / php copy_update.php / php migrate_data_to_storage.php（默认预览，加 --apply 执行）
- 版本升级：上传到站点根目录后访问：http(s)://yoursite/upgrade_v1.9.php
新增清理工具
- 模块删除：CLI：php remove.php [--apply] [--modules=article,point]；Web：/_dou/tool/remove.php[?apply][&modules=article]
- 安装准备：CLI：php remove.install.php [--apply]；Web：/_dou/tool/remove.install.php[?apply]
- 升级清理：CLI：php remove.update.php [--apply]；Web：/_dou/tool/remove.update.php[?apply]
通用参数
- --apply：执行实际删除操作（默认仅预览）
- --modules=module1,module2：指定要处理的模块列表
- 所有工具都支持 CLI 和 Web 两种运行方式

章节来源

_'\tool\index.php:25-50
_'\tool\remove.php:73-82
_'\tool\remove.install.php:95-104
_'\tool\remove.update.php:105-114
_'\tool\copy_sql.php:34-37
_'\tool\copy_update.php:34-37
_'\tool\migrate_data_to_storage.php:48-53
_'\tool\upgrade_v1.9.php:18-24

添加日期：2026-10-05