简介

本指南面向首次部署 DouPHP 的新手，目标是帮助你在最短时间内完成环境准备、源码部署、数据库初始化、基础配置与验证运行。内容覆盖 PHP/MySQL/Web 服务器要求、完整安装步骤、关键配置项说明、首次启动与验证、常见问题排查以及简单功能演示路径。

项目结构

DouPHP 采用“前台/后台/API 三端分离 + 核心框架”的目录组织方式：

• 根入口 index.php 负责统一引导、路由分发与异常处理
• core/bootstrap.php 负责环境检测、常量定义、配置加载、自动加载与容器初始化
• config/* 存放数据库连接、安全策略、模块清单等配置
• admin/ 为后台管理端，api/ 为 API 端，front/ 为前台业务端
• storage/ 为运行时存储（如安装锁、缓存、日志）
• theme/ 与 languages/ 提供主题与多语言资源
• .htaccess 提供 URL 重写与安全头透传

graph TB
A["浏览器"] --> B[".htaccess<br/>URL 重写"]
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["config/module.php<br/>模块清单"]
C --> H["路由分发<br/>Front/Admin/API"]
H --> I["业务控制器/服务"]
I --> J["数据库<br/>MySQL"]

核心组件

• 入口与引导
  • 根入口 index.php 设置路由委托、解析语言前缀、执行 Init 引导、调度路由并发送响应；集中捕获业务异常与未捕获异常，按 JSON/HTML 输出错误页或消息提示。
  • core/bootstrap.php 进行 PHP 版本检测、定义根路径与常量、加载站点配置、注册自动加载、初始化 DI 容器与请求对象、注册全局助手函数。
• 配置中心
  • config/config.php 定义数据库连接、表前缀、字符集、系统标识、目录别名、应用密钥与调试开关。
  • config/security.php 定义可信代理、可信 Host、安全响应头、限流与 Session Cookie 硬化策略。
  • config/module.php 声明列模块与单页模块清单，影响导航与菜单生成。
• 路由与重写
  • .htaccess 将 /admin/、/api/ 与前台 route 参数统一重写至对应入口，同时屏蔽敏感扩展名访问。

架构总览

下图展示从请求到响应的整体流程，包括安装检查、配置加载、路由分发与异常处理。

sequenceDiagram
participant U as "用户"
participant W as "Web服务器"
participant R as ".htaccess"
participant I as "index.php"
participant B as "core/bootstrap.php"
participant C as "配置(config)"
participant S as "路由/控制器"
participant DB as "数据库"
U->>W : 访问网站
W->>R : 匹配规则
R-->>I : 转发到 index.php?route=...
I->>B : 引入引导
B->>B : 版本检测/常量定义
B->>C : 加载 config/config.php
B->>C : 加载 security.php/module.php
I->>I : 解析语言前缀/设置路由
I->>S : 调度路由
S->>DB : 读取/写入数据
S-->>I : 返回响应
I-->>U : HTML/JSON 响应

详细组件分析

环境与依赖要求

• PHP
  • 最低版本：5.6.0（由引导脚本强制校验）
  • 建议版本：8.x（SQL 脚本头部显示使用 8.2.30 测试）
• MySQL
  • 建议使用 5.7+ 或更高版本（SQL 脚本头部显示 5.7.44）
  • 字符集：utf8mb4（建库与表均使用该字符集）
• Web 服务器
  • Apache：启用 mod_rewrite，开启 .htaccess 重写
  • Nginx：需实现与 .htaccess 等效的重写规则（/admin、/api、前台 route 参数）
• 其他
  • 文件系统：storage/ 目录需可写（用于安装锁、缓存、日志等）
  • 时区：确保 PHP 时区与业务一致

安装步骤（从零到可运行）

1. 准备数据库

• 创建数据库（字符集 utf8mb4，排序规则 utf8mb4_unicode_ci）
• 导入系统表结构 SQL（位于 _'/doc/开发手册/系统表结构.sql）
• 如需 AI/聊天/预约等功能，请一并导入对应模块的备份 SQL（各模块 storage/backup/*.sql）

2. 部署源码

• 将源码放置到 Web 根目录（例如 ）
• 确认 storage/ 目录对 Web 进程可写

3. 配置数据库与应用

• 编辑 config/config.php，填写数据库主机、库名、用户名、密码、表前缀
• 按需修改应用密钥 DOU_APP_KEY（生产环境务必更换默认值）
• 根据需要调整 DOU_DEBUG（开发阶段可开启，生产建议关闭）

4. 配置 Web 服务器重写

• Apache：确保启用 mod_rewrite，允许 .htaccess
• Nginx：配置与 .htaccess 等效的重写规则，将 /admin、/api 与前台 route 参数正确转发

5. 首次访问与安装

• 浏览器访问站点根路径
• 若检测到未安装（storage/install.lock 不存在），会自动跳转到安装程序
• 在安装向导中完成站点信息、管理员账号、数据库连接等设置
• 安装完成后会生成 install.lock，后续访问不再跳转

6. 登录后台

• 访问 /admin 使用管理员账号登录
• 在后台“模块管理”中启用所需模块（参考 config/module.php 中的模块清单）

基本配置要点

• 数据库连接
  • 字段：数据库主机、库名、用户名、密码、表前缀
  • 位置：config/config.php
• 应用密钥
  • 字段：DOU_APP_KEY（用于签名、加密等）
  • 位置：config/config.php
• 路径与目录
  • 后台目录、API 目录、小程序目录通过常量定义，可在 config/config.php 中调整
• 安全策略
  • 可信代理、可信 Host、安全响应头、限流与 Session Cookie 策略
  • 位置：config/security.php
• 模块清单
  • 列模块与单页模块列表，影响导航与菜单
  • 位置：config/module.php

首次启动与验证

• 访问前台首页，确认页面正常渲染
• 访问 /admin 登录后台，查看仪表盘与模块列表
• 访问 /api/health（如已启用健康检查）验证 API 连通性
• 检查 storage/ 下是否生成 install.lock（表示已完成安装）

简单功能演示

• 前台
  • 浏览商品/文章/案例等栏目（取决于启用的模块）
  • 搜索与分类页面
• 后台
  • 管理员登录 /admin
  • 在“模块管理”中启用所需模块
  • 在“内容管理”中添加示例数据（如商品、文章）
• API
  • 调用 /api/index.php?route=... 访问公开接口（根据路由配置）

依赖关系分析

• 入口依赖
  • index.php 依赖 core/bootstrap.php 完成引导
  • bootstrap.php 依赖 config/* 完成配置加载
• 路由与重写
  • .htaccess 将三类请求重写到对应入口：前台、后台、API
• 运行时状态
  • storage/install.lock 控制是否进入安装流程
  • storage/cache、storage/logs 等目录需可写

graph LR
HT[".htaccess"] --> IDX["index.php"]
IDX --> BOOT["core/bootstrap.php"]
BOOT --> CFG["config/config.php"]
BOOT --> SEC["config/security.php"]
BOOT --> MOD["config/module.php"]
IDX --> RT["路由/控制器"]
RT --> DB["MySQL"]

性能注意事项

• 开启 OPcache 与合适的 PHP-FPM 池配置
• 合理设置 MySQL 连接池与查询缓存（视版本而定）
• 静态资源走 CDN 或本地缓存
• 生产环境关闭 DOU_DEBUG，减少异常堆栈输出
• 限制不必要的模块，减少路由与视图开销

故障排除指南

• 无法访问或白屏
  • 检查 PHP 版本是否满足最低要求
  • 检查 storage/ 目录是否可写
  • 检查 .htaccess 是否生效（Apache 需启用 mod_rewrite）
• 数据库连接失败
  • 核对 config/config.php 中的数据库主机、库名、用户名、密码
  • 确认数据库已创建且字符集为 utf8mb4
  • 确认已导入系统表结构 SQL
• 始终跳转到安装页面
  • 检查 storage/install.lock 是否存在
  • 若误删，删除后重新访问以触发安装流程
• 后台/ API 404
  • 检查 .htaccess 重写规则是否正确
  • Nginx 需配置等价重写规则
• 安全相关报错
  • 检查 config/security.php 的 trusted_hosts 与 trusted_proxies 配置
  • 生产环境建议开启 HSTS 与严格的安全响应头

结论

按照本指南完成环境准备、源码部署、数据库初始化与基础配置后，即可快速启动 DouPHP。建议在开发阶段开启调试以便定位问题，在生产环境关闭调试并强化安全配置。遇到问题时优先检查数据库连接、安装锁与重写规则。

附录：安装与配置清单

• 环境
  • PHP ≥ 5.6.0（推荐 8.x）
  • MySQL ≥ 5.7（推荐 utf8mb4）
  • Apache/Nginx 支持 URL 重写
• 数据库
  • 创建数据库与用户
  • 导入系统表结构 SQL
• 源码
  • 上传至 Web 根目录
  • 赋予 storage/ 可写权限
• 配置
  • 编辑 config/config.php 填写数据库与应用密钥
  • 按需调整 config/security.php 安全策略
  • 按需启用/禁用模块（config/module.php）
• 验证
  • 访问前台首页
  • 访问 /admin 登录后台
  • 检查 storage/install.lock 存在