简介
本运维文档面向运维工程师与系统管理员，基于仓库中的入口引导、配置与安全策略等源码，给出DouPHP在生产环境的部署前置条件、安装步骤、权限与路径要求、安全加固、性能调优、监控告警、备份恢复以及自动化部署建议。文档所有技术细节均来源于代码与配置文件，确保可落地执行。特别更新了storage目录结构的重大变更，从原来的扁平布局重组为语义化的三层架构，为生产环境的站点维护和版本升级提供完整的运维支持。新的架构将运行时状态、可重建缓存和安装域数据明确分离，提升了系统的可维护性和安全性。
项目结构
- 站点根入口为 index.php，负责加载核心引导并设置路由分发。
- 核心引导 core/bootstrap.php 完成PHP版本检查、常量定义、未安装跳转、数据库配置加载、自动加载与容器初始化。
- 配置集中在 config/ 目录：
- config.php：数据库连接、表前缀、字符集、应用密钥、调试开关等。
- security.php：可信代理、可信Host、安全响应头、限流存储、会话Cookie硬化。
- 管理端入口 admin/index.php（由 bootstrap 动态识别 ADMIN_DIR），提供备份恢复等运维能力。
- 运行时数据写入 storage/（新的三层语义化架构）
- 部署工具位于 _'/tool/ 目录，包含模块移除、数据迁移等运维脚本。
graph TB
A["浏览器"] --> B["Nginx/Apache<br/>静态资源与PHP解析"]
B --> C["index.php<br/>入口"]
C --> D["core/bootstrap.php<br/>引导与初始化"]
D --> E["config/config.php<br/>数据库与应用配置"]
D --> F["config/security.php<br/>安全策略"]
D --> G["storage/<br/>三层语义化架构"]
C --> I["路由分发<br/>front/admin/api"]
J["_'/tool/<br/>部署运维工具"] --> K["模块移除工具"]图表来源
- index.php:1-75
- core/bootstrap.php:15-180
- config/config.php:15-52
- config/security.php:51-87
章节来源
- index.php:1-75
- core/bootstrap.php:15-180
- config/config.php:15-52
- config/security.php:51-87
核心组件
- 入口与引导
- 入口 index.php 设置路由委托、语言前缀解析、异常处理与JSON响应。
- 引导 core/bootstrap.php 强制PHP版本下限、定义路径常量、检测未安装状态并跳转安装程序、加载数据库配置、注册自动加载与DI容器、绑定Request与路由。
- 配置中心
- config.php：数据库主机、库名、用户、密码、表前缀、字符集、应用密钥、调试开关。
- security.php：可信代理、可信Host、安全响应头、限流存储、会话Cookie策略。
- 运行态存储（新架构）
- storage/state/：安装锁、授权凭据、限流计数器等运行时状态
- storage/cache/：模板编译缓存、JS URL世代标记、路由清单等可重建缓存
- storage/install/：模块包下载、安装会话、已安装清单等安装域数据
- storage/log/：系统日志
- storage/backup/：数据库备份文件
- 部署运维工具
- remove.install.php：开源包清理工具，包含storage目录修剪
章节来源
- index.php:1-75
- core/bootstrap.php:15-180
- config/config.php:15-52
- config/security.php:51-87
架构总览
请求从Web服务器进入入口，经引导初始化后交由路由分发到前台、后台或API；后台提供备份恢复等运维功能。部署工具提供模块移除、站点清理等高级运维能力。storage目录采用三层语义化架构，明确区分运行时状态、可重建缓存和安装域数据。
sequenceDiagram
participant U as "用户"
participant N as "Web服务器"
participant I as "index.php"
participant B as "bootstrap.php"
participant R as "路由分发"
participant A as "Admin(备份)"
participant T as "部署工具"
U->>N : HTTP请求
N->>I : 转发至入口
I->>B : 加载引导
B-->>I : 返回已就绪的Request/Route
I->>R : 调度路由
alt 访问后台备份
R->>A : 调用备份控制器
A-->>U : 返回备份/恢复页面或结果
else 访问部署工具
R->>T : 调用模块移除工具
T-->>U : 返回清理结果
end图表来源
- index.php:16-75
- core/bootstrap.php:59-180
详细组件分析
环境与前置条件
- PHP版本
- 最低版本要求：PHP 5.6.0 及以上（引导中硬校验）。
- 数据库
- 通过 config/config.php 配置 host、dbname、user、pass、prefix、charset。
- 字符集统一使用 utf-8。
- Web服务器
- 需支持PHP解析；HTTPS可通过 SERVER_PORT/REQUEST_SCHEME/$_SERVER['HTTPS'] 判定。
- 文件系统（新架构）
- storage/state/：必须可写（用于安装锁、授权凭据、限流计数器等运行时状态）
- storage/cache/：必须可写且可删除（模板编译缓存、路由清单等可重建缓存）
- storage/install/：必须可写（模块包下载、安装会话、已安装清单）
- storage/log/：必须可写（系统日志）
- storage/backup/：必须可写（数据库备份文件）
- images/upload/ 及主题相关目录需可写（由 file.php 默认磁盘与业务上传逻辑决定）。
- 域名与反向代理
- 若位于Nginx/负载均衡之后，需在 security.php 中配置 trusted_proxies 与 trusted_hosts，避免IP与Host被伪造污染。
章节来源
- core/bootstrap.php:19-57
- config/config.php:15-52
- config/security.php:51-87
安装与初始化流程
- 未安装检测
- 引导阶段检测 storage/state/install.lock 是否存在；不存在且非安装路径时，自动跳转到安装程序。
- 三级判定链：storage/state/install.lock → storage/install.lock → data/install.lock（向后兼容）
- 数据库配置
- 在 config/config.php 中填写数据库连接信息、表前缀与应用密钥。
- 权限与目录
- 确保 storage/state/、storage/cache/、storage/install/、storage/log/、storage/backup/ 对Web进程用户可写。
- 首次访问
- 访问站点根触发引导与路由，按是否已安装分流到安装器或主站。
flowchart TD
Start(["请求到达"]) --> CheckLock{"存在 storage/state/install.lock ?"}
CheckLock --> |否| CheckOldLock{"存在 storage/install.lock ?"}
CheckOldLock --> |是| Boot["加载配置与引导"]
CheckOldLock --> |否| Redirect["重定向到安装程序"]
CheckLock --> |是| Boot
Boot --> Route["路由分发"]
Route --> End(["返回页面/JSON"])图表来源
- core/bootstrap.php:42-65
- index.php:26-75
章节来源
- core/bootstrap.php:42-65
- config/config.php:15-52
安全加固要点
- 可信代理与Host
- 在 security.php 中配置 trusted_proxies（CIDR或精确IP）与 trusted_hosts（域名白名单），防止X-Forwarded-*与Host头注入。
- 安全响应头
- 启用 X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy；可按需开启HSTS。
- 会话Cookie硬化
- httponly=true；secure跟随IS_HTTPS或强制；samesite=Lax/Strict/None；use_strict_mode=true防会话固定。
- 限流
- 将 throttle.store 指向 storage/state/throttle/，按需配置默认限流策略。
- 调试模式
- 生产环境务必关闭 DOU_DEBUG，避免错误堆栈泄露。
章节来源
- config/security.php:51-87
- config/config.php:48-52
storage目录结构迁移指南
重大更新 DouPHP的storage目录结构已从扁平布局重组为语义化的三层架构，需要特别注意迁移和权限配置。
新目录架构概览
storage/
├── cache/ # 可重建缓存：随时可删，访问后自动重建
│ ├── template/{admin,front}/ # 模板编译缓存
│ ├── js/generation.txt # JS URL世代标记
│ ├── route/manifest.cache # 路由清单
│ ├── cloud/connect_check.json # 云连通检查
│ ├── cloud/update_number.txt # 更新数节流
│ └── tmp/ # 临时载荷：一次性文件袋
├── state/ # 运行时状态：删除有后果，永不碰
│ ├── admin_dir.php # 自定义后台目录
│ ├── cdkey.php # 授权凭据
│ ├── install.lock # 安装锁（从storage根迁入）
│ ├── quick.start.dou # 后台快捷入口
│ ├── payment_reconcile.lock # 对账flock锁
│ └── throttle/ # 限流计数器
├── install/ # 安装域：输入→过程→产出
│ ├── package/ # 模块包下载工作区
│ ├── session/ # 云安装会话
│ └── records/ # 已安装清单
├── watermark/ # 用户侧投放资产
├── log/ # 系统日志
└── backup/ # SQL备份权限配置要求
- storage/state/：最高权限要求，包含敏感数据和运行时状态
- storage/cache/：读写权限，但允许删除重建
- storage/install/：读写权限，安装过程中使用
- storage/log/：写权限，记录系统日志
- storage/backup/：写权限，存储数据库备份
迁移步骤
- 备份现有数据：在执行迁移前，完整备份storage目录
- 创建新目录结构：按照上述架构创建新目录
- 数据迁移：使用upgrade_2.0.php进行幂等迁移
- 权限设置：为新目录设置适当的文件权限
- 验证测试：确认系统正常运行
章节来源
- chat.md:8-37
模块移除工具与小程序清理
更新 DouPHP提供了完善的模块移除工具，支持复杂的文件发现机制和小程序安全清理功能，现已适配新的storage目录结构。
模块文件删除机制
模块移除工具实现了与index.php相同的文件发现逻辑，支持以下类型的文件扫描和删除：
- PHP各层目录：front/service、front/request、front/model、front/controller、core/domain、core/service、api/service、api/request、api/controller、admin/model、admin/request、admin/service、admin/controller
- 声明式路由：admin/route、front/route、api/route下的模块路由文件
- 管理导航：admin/nav下的模块导航声明文件
- 语言包：languages/{locale}/[admin/]module.lang.php
- 模板资源：admin/view和theme/default下的模板文件及css/js/inc资源
- 小程序资产：miniprogram/pages下的模块页面和_category分类页面
- 附加文件：通过extraFiles配置的模块专属文件
flowchart TD
Module["目标模块"] --> Step1["步骤1: 同名文件夹扫描"]
Step1 --> Step1b["步骤1b: 声明式路由扫描"]
Step1b --> Step2["步骤2: 模块级目录覆盖"]
Step2 --> Step3["步骤3: 语言包扫描"]
Step3 --> Step4["步骤4: 模板资源扫描"]
Step4 --> Step5["步骤5: 小程序页面扫描"]
Step5 --> Step5b["步骤5b: 小程序附加文件"]
Step5b --> Step6["步骤6: 模块级附加文件"]
Step6 --> Step7["步骤7: 已安装清单"]
Step7 --> Result["生成删除清单"]图表来源
- _'/tool/remove.install.php:507-756
小程序安全清理功能
小程序清理功能专门处理敏感配置和运行时生成的文件：
- 动作一：删除开发者私有配置文件 project.private.config.json
- 动作二：将 project.config.json 中的 appid 替换为占位符 touristappid
- 动作三：重置小程序生成文件为标准模板内容
- 动作四：清洗 site.ts 中的部署地址为占位符
sequenceDiagram
participant Tool as "清理工具"
participant FS as "文件系统"
participant Config as "配置文件"
Tool->>FS : 扫描小程序目录
FS-->>Tool : 返回文件列表
Tool->>Config : 读取敏感配置
Config-->>Tool : 返回配置内容
Tool->>FS : 删除私有配置文件
Tool->>FS : 替换AppID为占位符
Tool->>FS : 重置生成文件
Tool->>FS : 清洗部署地址
FS-->>Tool : 确认操作完成图表来源
- _'/tool/remove.install.php:240-273
工具变体与用途
- remove.install.php：开源包清理，包含storage目录修剪和install.lock删除
章节来源
- _'/tool/remove.install.php:32-103
备份与恢复（内置）
- 功能入口
- 后台提供备份与恢复页面，支持分卷备份、ZIP打包、导入SQL、删除备份、下载备份。
- 关键流程
- 列表页获取表清单与总量；备份接口执行分卷与压缩；恢复接口导入SQL；删除接口清理备份文件；下载接口流式输出。
- 注意事项
- 大库建议分卷备份；确保 storage/backup/ 空间充足；恢复前做好停机或只读预案。
sequenceDiagram
participant U as "管理员"
participant BC as "BackupController"
participant BS as "BackupService"
participant DB as "数据库"
U->>BC : 打开备份页
BC->>BS : 构建表清单
BS-->>BC : 表清单/总量
U->>BC : 提交备份
BC->>BS : runBackup()
BS->>DB : 导出SQL(分卷)
DB-->>BS : SQL片段
BS-->>BC : 生成ZIP/进度
BC-->>U : 提示成功/超时/确认链接
U->>BC : 恢复/导入
BC->>BS : runImport()
BS->>DB : 执行SQL
DB-->>BS : 结果
BS-->>BC : 消息/超时/确认
BC-->>U : 恢复结果图表来源
- admin/controller/backup/BackupController.php:53-162
章节来源
- admin/controller/backup/BackupController.php:53-162
依赖关系分析
- 入口与引导
- index.php 依赖 core/bootstrap.php 完成环境准备与对象实例化。
- 配置依赖
- bootstrap 在早期加载 config/config.php 以获取数据库配置，并据此构造连接。
- 安全与存储
- security.php 影响Request的IP/Host判定与会话Cookie策略；file.php 影响上传与磁盘行为。
- 后台备份
- BackupController 依赖 BackupService 与 DB 门面进行备份/恢复操作。
- 部署工具
- 模块移除工具依赖文件系统操作函数和路径解析逻辑。
graph LR
Index["index.php"] --> Bootstrap["core/bootstrap.php"]
Bootstrap --> Config["config/config.php"]
Bootstrap --> Security["config/security.php"]
Index --> Router["路由分发"]
Router --> Admin["admin/controller/backup/BackupController.php"]
Admin --> DB["数据库"]
RemoveTools["模块移除工具"] --> FileSystem["文件系统操作"]
RemoveTools --> PathResolver["路径解析逻辑"]图表来源
- index.php:16-75
- core/bootstrap.php:59-180
- admin/controller/backup/BackupController.php:53-162
章节来源
- index.php:16-75
- core/bootstrap.php:59-180
- admin/controller/backup/BackupController.php:53-162
性能与生产优化
- PHP与扩展
- 满足最低PHP版本；建议开启OPcache、启用常用扩展（PDO、MySQLi、Zip、GD/Imagick等）。
- Web服务器
- 启用Gzip/Brotli压缩；静态资源开启长期缓存；合理配置worker与并发。
- 数据库
- 调整连接池与查询缓存；为大表建立合适索引；定期维护。
- 安全与限流
- 生产关闭DOU_DEBUG；配置trusted_proxies与trusted_hosts；启用必要的安全响应头；按需开启限流。
- 文件与缓存（新架构优化）
- storage/state/：确保高性能磁盘，避免频繁IO操作
- storage/cache/：可使用内存缓存或SSD提升性能
- storage/install/：仅在安装时使用，可减少IO频率
- storage/log/：考虑日志轮转和异步写入
- storage/backup/：建议使用对象存储或NAS进行远程备份
故障排查指南
- 无法访问或跳转安装
- 检查 storage/state/install.lock 是否存在；若误删会再次跳转安装。
- 确认 config/config.php 数据库配置正确。
- 数据库连接失败
- 核对 host、dbname、user、pass、prefix；确认字符集utf-8。
- 上传失败或无权限
- 检查 images/upload/ 与 storage/ 权限；确认 upload_max_kb 与 allow_extensions 配置。
- storage目录相关问题
- 检查 storage/state/、storage/cache/、storage/install/ 目录权限
- 确认目录结构是否符合新的三层架构
- 检查是否有旧目录残留导致的路径冲突
- 验证安装锁路径是否正确：storage/state/install.lock
- 安全头或Host问题
- 若位于反代后，配置 trusted_proxies 与 trusted_hosts；检查安全响应头是否生效。
- 模块移除工具问题
- 确认工具运行模式（preview/execute）；检查modules参数格式；验证目标模块是否存在。
- 查看工具输出的删除清单，确认文件路径是否正确。
- 小程序清理问题
- 检查小程序目录权限；确认敏感配置文件是否存在；验证占位符替换是否成功。
- 调试与日志
- 临时开启DOU_DEBUG定位问题；关注PHP错误日志与系统日志。
章节来源
- core/bootstrap.php:19-65
- config/config.php:15-52
- config/security.php:51-87
备份与恢复策略
- 数据备份
- 使用后台"备份"功能进行分卷备份与ZIP打包；建议定时任务触发备份并归档到异地存储。
- 文件备份
- 同步 images/ 与 storage/ 到对象存储或NAS；注意排除敏感缓存和临时文件。
- 重点备份：storage/state/（运行时状态）、storage/install/records/（已安装清单）
- 可重建备份：storage/cache/（可删除重建）、storage/log/（日志可轮转）
- 恢复流程
- 停写或只读 -> 导入SQL -> 验证数据一致性 -> 恢复服务。
- 灾难恢复
- 制定RTO/RPO目标；演练恢复流程；保留多份历史备份。
章节来源
- admin/controller/backup/BackupController.php:53-162
自动化部署与CI/CD
- 构建与发布
- 将代码仓库作为制品源；部署时拉取最新代码，确保 storage/ 与 images/upload/ 权限正确。
- 配置管理
- 使用环境变量或配置中心注入 config/config.php 中的数据库与密钥；避免硬编码。
- 健康检查
- 暴露健康检查端点（如 health 路由）供负载均衡探测。
- 回滚策略
- 采用蓝绿或滚动发布；每次发布前自动备份数据库与关键文件。
- 监控与告警
- 采集PHP-FPM/Nginx指标；记录错误日志；对5xx、慢查询、磁盘使用率设置阈值告警。
- 模块卸载与站点清理
- 在CI/CD流水线中集成模块移除工具，实现自动化站点清理。
- 使用 remove.install.php 进行开源包清理，确保不包含敏感配置。
flowchart TD
Build["代码构建"] --> Test["单元测试"]
Test --> Package["打包制品"]
Package --> Deploy["部署到测试环境"]
Deploy --> ModuleCleanup["模块清理"]
MiniClean["小程序清理"] --> StoragePrune["Storage清理"]
StoragePrune --> HealthCheck["健康检查"]
HealthCheck --> Production["部署到生产环境"]
Production --> Monitor["监控告警"]图表来源
- _'/tool/remove.install.php:94-103
章节来源
- _'/tool/remove.install.php:94-103
结论
本指南基于DouPHP源码与配置，给出了从环境准备、安装初始化、安全加固、性能优化到备份恢复与自动化部署的完整运维方案。特别地，最新的storage目录结构重构为语义化的三层架构，为生产环境的站点维护和版本升级提供了更加清晰和安全的文件组织方式。 新的架构通过将运行时状态、可重建缓存和安装域数据明确分离，显著提升了系统的可维护性和安全性。
重要提醒：在安装和初始化流程中，安装锁路径已从storage/install.lock迁移到storage/state/install.lock，并实现了三级判定链以保证向后兼容性。在进行storage目录迁移时，请务必遵循新的目录结构规范，确保数据完整性。新的三层架构虽然增加了复杂性，但显著提升了系统的可维护性和安全性。请结合生产实际调整参数与流程，确保系统稳定、安全、可观测、可恢复。