简介
本指南面向部署 DouPHP 的运维与开发者，聚焦于 Linux/Unix 与 Windows 环境下的文件系统权限、Web 服务器安全配置（Apache/Nginx）、storage 目录读写要求、以及 .htaccess 的安全策略。文档基于仓库内实际代码与配置文件进行分析，提供可操作的步骤、验证方法与常见问题解决方案。
项目结构与关键路径
- 应用根路径常量：ROOT_PATH
- 运行时存储根目录常量：STORAGE_PATH
- 配置文件目录：CONFIG_PATH
- 后台入口目录：由 ADMIN_DIR 决定（默认 admin）
- API 入口目录：API_DIR（默认 api）
上述路径在引导阶段定义，并在安装流程中用于判断是否已安装、加载配置等。
graph TB
A["应用入口"] --> B["bootstrap.php<br/>定义 ROOT_PATH / STORAGE_PATH / CONFIG_PATH"]
B --> C["config/config.php<br/>数据库与站点常量"]
B --> D["storage/<br/>运行时缓存/日志/上传临时数据"]
B --> E["admin/ 或自定义后台目录"]
B --> F["api/"]图表来源
- core/bootstrap.php:24-29
- core/bootstrap.php:42-65
- config/config.php:15-52
章节来源
- core/bootstrap.php:24-73
- config/config.php:15-52
核心组件与权限检查机制
- 运行时存储目录 storage 及其子目录需要“写”权限，否则网站无法正常运行。
- 图片目录 images 及子目录（如 slide、article、product）需要“写”权限以支持上传。
- 模板目录 theme 需要“写”权限以支持在线下载模板。
- 工具服务会递归收集 storage 下所有子目录并逐一检测写入能力。
- 文件权限检测通过尝试创建测试文件实现，返回 write/no_write/no_exist。
flowchart TD
Start(["开始"]) --> CheckStorage["检测 storage 是否存在且可写"]
CheckStorage --> |存在且可写| CheckImages["检测 images 及子目录可写"]
CheckStorage --> |不存在或不可写| FixStorage["创建/修复 storage 权限"]
CheckImages --> CheckTheme["检测 theme 可写"]
CheckTheme --> Done(["完成"])
FixStorage --> CheckImages图表来源
- admin/service/tool/ToolService.php:70-135
- core/support/FileHelper.php:319-347
章节来源
- admin/service/tool/ToolService.php:70-135
- core/support/FileHelper.php:319-347
架构总览
DouPHP 在启动时定义关键路径常量，随后根据 storage/install.lock 判断是否进入安装流程；未安装则重定向到安装脚本。运行时，后台工具页面会扫描 storage 子目录并报告写入状态；上传功能将文件落盘至 images 或 storage 相关目录。
sequenceDiagram
participant Client as "浏览器"
participant Apache as "Apache/Nginx"
participant PHP as "PHP-FPM/Cookie"
participant Boot as "bootstrap.php"
participant Tool as "ToolService"
participant FS as "文件系统"
Client->>Apache : 请求 /admin 或 /
Apache->>PHP : 转发到 index.php
PHP->>Boot : 执行引导
Boot-->>PHP : 定义 ROOT_PATH/STORAGE_PATH/CONFIG_PATH
PHP->>Tool : 打开后台工具页
Tool->>FS : 递归检测 storage 子目录可写
FS-->>Tool : 返回每个目录的写入状态
Tool-->>Client : 展示权限检查结果图表来源
- core/bootstrap.php:24-65
- admin/service/tool/ToolService.php:70-135
详细组件分析
Linux/Unix 文件系统权限设置
- 目标用户与组
- Web 服务器运行用户通常为 www-data、nginx、apache 等。
- 建议将项目目录所有者设置为该用户，或将其加入对应组。
- 目录与文件权限
- 代码文件（PHP/HTML/JS/CSS）：建议 644（rw-r--r--），目录 755（rwxr-xr-x）。
- 敏感配置文件（如 config/config.php）：建议 640 或 600，仅 Web 用户可读。
- storage 目录及全部子目录：必须可写，建议 755 或 775（取决于组策略）。
- images 目录及子目录（slide/article/product 等）：必须可写，建议 755 或 775。
- theme 目录：如需在线下载模板，需可写，建议 755 或 775。
- 常用命令
- 修改所有者：chown -R www-data:www-data /path/to/douphp.dou
- 修改权限：chmod -R 755 /path/to/douphp.dou && chmod -R 775 /path/to/douphp.dou/storage /path/to/douphp.dou/images /path/to/douphp.dou/theme
- 针对特定目录更严格：chmod 640 /path/to/douphp.dou/config/config.php
章节来源
- core/bootstrap.php:24-29
- admin/service/tool/ToolService.php:70-135
Windows 系统权限配置
- 使用“属性 > 安全”为 IIS 应用池账户（如 IUSR、IIS_IUSRS 或自定义账户）授予相应权限。
- 对 storage、images、theme 目录授予“修改”或“完全控制”权限（视需求而定）。
- 避免使用管理员账户运行 Web 服务，遵循最小权限原则。
- 注意大小写敏感性差异：Windows 不区分大小写，应避免仅大小写不同的目录名冲突（项目内部已有相关校验逻辑）。
章节来源
- admin/service/tool/ToolService.php:236-240
storage 目录读写权限要求
- storage 是运行时存储根目录，承载缓存、日志、临时脚本等。
- 工具服务会递归收集 storage 下所有子目录并检测写入能力。
- 若缺少写入权限，可能导致：
- 无法生成缓存文件
- 无法写入日志
- 无法执行后台目录更名等一次性脚本（写入 storage/cache）
- 建议：
- 确保 storage 及其全部子目录可写。
- 定期清理过期缓存与日志，避免磁盘占满。
章节来源
- admin/service/tool/ToolService.php:70-135
- core/support/FileHelper.php:319-347
图片与上传目录权限
- images 目录用于产品、文章、幻灯片等图片存储，需可写。
- 上传流程涉及分块上传与草稿模式，最终落盘到 images 或 storage 相关目录。
- 建议：
- images 及子目录（slide/article/product）设为可写。
- 限制上传类型与大小，防止恶意文件写入。
章节来源
- admin/service/tool/ToolService.php:90-109
- admin/controller/file/FileController.php:82-102
- core/service/attachment/ChunkedUploadHandler.php:46-71
- core/service/attachment/ChunkedUploadHandler.php:155-181
.htaccess 安全设置（Apache）
- 禁止访问敏感扩展名（bak/inc/lib/sh/tpl/lbi/dwt/pem），降低源码泄露风险。
- 重写规则：
- 透传 Authorization 头，支持 Basic Auth。
- 静态入口与 API、后台路由重写。
- 建议：
- 保持 .htaccess 启用，并确保 Apache 允许覆盖（AllowOverride All）。
- 生产环境关闭 DOU_DEBUG 以减少信息泄露。
章节来源
- .htaccess:1-45
- config/config.php:51-52
Nginx 配置差异
- Nginx 不使用 .htaccess，需在 server/location 中实现等价重写与安全策略：
- 拒绝访问敏感扩展名（deny 或 return 403）。
- 重写 API 与后台路由（try_files + rewrite）。
- 传递 Authorization 头（proxy_set_header Authorization $http_authorization;）。
- 建议：
- 将 .htaccess 中的规则转换为 Nginx 配置片段。
- 确保 location 匹配正确，避免误放行静态资源。
不同 Web 服务器的权限配置差异
- Apache：
- 使用 .htaccess 进行目录级安全与重写。
- 需要 AllowOverride 开启以生效。
- Nginx：
- 通过 server 块与 location 指令实现相同效果。
- 更强调集中式配置与性能优化。
依赖关系分析
- bootstrap.php 定义 ROOT_PATH、STORAGE_PATH、CONFIG_PATH，并加载配置。
- ToolService 依赖 FileHelper 进行权限检测。
- 上传控制器与处理器依赖文件系统写入能力。
- .htaccess 影响 Apache 的请求处理与安全策略。
graph LR
Bootstrap["bootstrap.php"] --> Config["config/config.php"]
Bootstrap --> Storage["storage/"]
Tool["ToolService"] --> FileHelper["FileHelper"]
Upload["FileController/ChunkedUploadHandler"] --> FS["文件系统(images/storage)"]
Apache[".htaccess"] --> Request["请求处理(重写/安全)"]图表来源
- core/bootstrap.php:24-65
- admin/service/tool/ToolService.php:70-135
- core/support/FileHelper.php:319-347
- admin/controller/file/FileController.php:82-102
- .htaccess:1-45
章节来源
- core/bootstrap.php:24-65
- admin/service/tool/ToolService.php:70-135
- core/support/FileHelper.php:319-347
- admin/controller/file/FileController.php:82-102
- .htaccess:1-45
性能与安全注意事项
- 性能
- 合理设置 storage 缓存目录，避免频繁重建。
- 定期清理过期日志与临时文件。
- 在 Nginx 上启用 gzip 与静态资源缓存。
- 安全
- 严格限制 storage 与 images 的访问范围，避免直接暴露。
- 生产环境关闭调试模式（DOU_DEBUG=false）。
- 使用 HTTPS 并正确传递 Authorization 头。
- 限制上传文件类型与大小，防止恶意注入。
故障排查指南
- 现象：后台工具显示 storage 或 images 无写入权限
- 检查目录所有者与权限是否正确。
- 确认 Web 服务器用户对该目录有写权限。
- 使用 FileHelper 的检测逻辑验证：尝试创建测试文件。
- 现象：上传失败
- 检查 images 与 storage 目录可写性。
- 查看 PHP 上传限制（upload_max_filesize、post_max_size）。
- 检查分块上传逻辑与临时目录权限。
- 现象：后台目录更名失败
- 确认 storage/cache 可写，以便生成一次性引导脚本。
- 检查新目录名合法性（不允许大写，避免跨平台不一致）。
- 现象：Apache 重写不生效
- 确认 .htaccess 被启用（AllowOverride All）。
- 检查敏感扩展名是否被错误放行。
- 验证 Authorization 头透传配置。
章节来源
- core/support/FileHelper.php:319-347
- admin/service/tool/ToolService.php:236-265
- .htaccess:1-45
结论
- 确保 storage、images、theme 目录具备正确的读写权限是 DouPHP 正常运行的基础。
- 使用 .htaccess（Apache）或等效 Nginx 配置强化安全策略，避免敏感文件泄露。
- 通过内置工具与权限检测机制快速定位问题，结合日志与文件系统检查进行排障。
- 在生产环境中遵循最小权限原则，关闭调试模式，并定期维护缓存与日志。