简介
DouPHP 提供两种安装方式：推荐的 Web 安装向导和传统的手动安装。Web 安装向导提供了图形化界面，自动完成环境检测、数据库配置、文件生成等所有步骤，适合大多数用户。手动安装方式则适合高级用户或需要特殊配置的部署场景。
Web 安装向导（推荐）
访问安装向导
将 DouPHP 项目上传到服务器后，直接访问 http://your-domain/install/index.php 即可启动安装向导。
安装流程概览
flowchart TD
A[欢迎页面] --> B[环境检测]
B --> C[数据库配置]
C --> D[管理员设置]
D --> E[执行安装]
E --> F[安装完成]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#fff3e0
style D fill:#e8f5e8
style E fill:#fce4ec
style F fill:#e1f5fe图表来源
- install/controller/IndexController.php:23-44
- install/init/route.php:26-33
详细安装步骤
第一步：许可协议确认
访问安装向导后，首先显示许可协议页面。您需要勾选同意框才能继续下一步。
第二步：环境检测
系统自动检测以下环境要求：
- PHP 版本（最低 5.6.0）
- MySQL/MariaDB 支持
- GD 扩展
- Zlib 压缩库
- Socket 功能
- 时区设置
- 目录写入权限
第三步：数据库配置
填写以下数据库信息：
- 数据库主机：通常为
127.0.0.1或localhost - 数据库用户名：具有创建数据库权限的用户
- 数据库密码：对应用户的密码
- 数据库名称：系统将自动创建此数据库
- 表前缀：默认为
dou_，可自定义
第四步：管理员设置
设置后台管理员账户：
- 用户名：管理员登录用户名
- 密码：管理员密码（需再次确认）
- 邮箱：管理员联系邮箱（可选）
第五步：测试数据选择
可选择是否导入测试数据：
- 是：导入示例文章、产品等内容用于演示
- 否：仅安装纯净的系统框架
第六步：执行安装
点击提交按钮后，系统将：
- 创建数据库和表结构
- 生成配置文件
config/config.php - 初始化管理员账户
- 写入安装锁文件
安装向导组件结构
install/
├── controller/ # 控制器层
│ ├── IndexController.php # 欢迎页面
│ ├── CheckController.php # 环境检测
│ ├── SettingController.php # 配置页面
│ ├── InstallController.php # 安装执行
│ ├── FinishController.php # 完成页面
│ └── LockController.php # 锁定控制
├── service/ # 服务层
│ ├── EnvironmentCheckService.php # 环境检测服务
│ ├── DatabaseInstallService.php # 数据库安装服务
│ ├── ConfigWriterService.php # 配置文件写入服务
│ ├── InstallLockService.php # 安装锁服务
│ └── FinishService.php # 完成处理服务
├── view/ # 视图层
│ ├── index.htm # 欢迎页面模板
│ ├── check.htm # 环境检测模板
│ ├── setting.htm # 配置页面模板
│ └── finish.htm # 完成页面模板
└── init/ # 初始化配置
└── route.php # 路由映射配置章节来源
- install/controller/IndexController.php:15-46
- install/service/EnvironmentCheckService.php:21-54
- install/service/DatabaseInstallService.php:27-54
手动安装（备选）
适用场景
- 需要特殊的环境配置
- 批量部署多个站点
- 自动化脚本集成
- 高级用户自定义需求
安装步骤
1. 准备数据库
CREATE DATABASE douphp DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON douphp.* TO 'douphp_user'@'localhost' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;2. 上传文件
将整个 DouPHP 项目上传到 Web 服务器文档根目录。
3. 配置数据库连接
编辑 config/config.php 文件，修改以下参数：
$dbhost = '127.0.0.1'; // 数据库主机地址
$dbname = 'douphp'; // 数据库名称
$dbuser = 'douphp_user'; // 数据库用户名
$dbpass = 'password'; // 数据库密码
$prefix = 'dou_'; // 表前缀4. 导入数据库结构
使用 phpMyAdmin 或其他数据库管理工具导入 install/data/backup/douphp.sql 文件。
5. 创建管理员账户
通过 SQL 语句创建管理员账户：
INSERT INTO dou_admin (username, password, email, created_at)
VALUES ('admin', '$2y$10$...', 'admin@example.com', NOW());6. 创建安装锁文件
touch storage/state/install.lock
echo "DOUPHP INSTALLED" > storage/state/install.lock环境要求
服务器环境
- Web服务器：Apache（启用 mod_rewrite）或 Nginx
- PHP版本：5.6.0 或更高版本
- 数据库：MySQL 5.7+ 或 MariaDB 10.2+
- 必需扩展：mysqli, gd, zlib, mbstring, json, openssl
目录结构要求
storage/
├── cache/ # 缓存目录
│ ├── template/{admin,front}/ # 模板编译缓存
│ └── tmp/ # 临时文件
├── state/ # 运行时状态
│ ├── install.lock # 安装锁文件
│ └── throttle/ # 限流计数器
├── log/ # 日志目录
└── backup/ # 备份目录章节来源
- install/service/EnvironmentCheckService.php:29-46
配置文件详解
自动生成的配置文件
Web 安装向导会自动生成 config/config.php 文件，包含以下关键配置项：
数据库连接配置
$dbhost = '127.0.0.1'; // 数据库主机地址
$dbname = 'douphp'; // 数据库名称
$dbuser = 'douphp_user'; // 数据库用户名
$dbpass = 'password'; // 数据库密码
$prefix = 'dou_'; // 表前缀系统常量配置
define('DOU_CHARSET', 'utf-8'); // 字符集设置
define('SYSTEM_SIGN', 'company'); // 系统标识
define('ADMIN_DIR', 'admin'); // 后台目录
define('API_DIR', 'api'); // API 目录
define('MINIPROGRAM_DIR', 'miniprogram'); // 小程序目录
define('ADMIN_REWRITE', false); // 后台 URL 重写开关
define('DOU_APP_KEY', 'your-secret-key'); // 应用密钥
define('DOU_DEBUG', true); // 调试模式开关配置文件生成逻辑
Web 安装向导通过 ConfigWriterService 类自动生成配置文件，确保格式正确且安全。
章节来源
- install/service/ConfigWriterService.php:23-50
- config/config.php:15-53
URL重写规则
Apache 配置
系统使用 .htaccess 文件进行 URL 重写，包含以下主要规则：
安全规则
- 禁止访问敏感文件后缀（bak, inc, lib, sh, tpl, lbi, dwt, pem）
路由重写规则
- API 路由：
/api/*→api/index.php?route=... - 后台路由：
/admin/*→admin/index.php?route=... - 前台路由：非静态资源请求统一转发到
index.php
Authorization 头透传
- 透传 Authorization 头给后端 PHP 处理
Nginx 配置
对于 Nginx 服务器，需要在虚拟主机配置中添加相应的 location 块来处理路由重写。
章节来源
- .htaccess:1-45
权限设置
目录权限配置
# 设置 storage 目录权限
chmod -R 755 storage/
chmod -R 777 storage/cache/
chmod -R 777 storage/state/
chmod -R 777 storage/log/
chmod -R 777 storage/backup/
# 设置 images 目录权限
chmod -R 777 images/文件所有权
确保 Web 服务器进程对必要的目录具有写入权限：
chown -R www-data:www-data storage/
chown -R www-data:www-data images/安装验证
基本功能测试
- 前台访问测试：访问网站根域名，确认首页正常加载
- 后台访问测试：访问
/admin，使用管理员账户登录 - API 接口测试：调用健康检查接口，确认 JSON 响应正常
- 数据库连通性测试：执行简单查询，确认读写功能正常
权限验证
- 检查
storage目录写入能力（缓存、日志、上传） - 验证
storage/state/install.lock文件能正常创建 - 测试图片上传功能是否正常
- 验证模板缓存生成是否成功
安全验证
- 确认敏感文件无法直接访问
- 验证 URL 重写规则正常工作
- 检查安全响应头是否正确设置
多站点部署
共享代码库方案
多个站点共用同一份代码，通过不同数据库和配置区分：
- 数据库隔离：每个站点创建独立数据库
- 配置分离：在各自的
config/config.php中设置不同的数据库连接 - 表前缀隔离：使用不同的表前缀进行数据隔离
域名配置
- 确保每个站点的
.htaccess生效 - 在虚拟主机层面配置
ServerName和DocumentRoot - 配置可信 Host 白名单防止 Host 头注入
安全考虑
- 为每个站点生成不同的
DOU_APP_KEY - 配置独立的云端账户
- 设置合理的会话隔离策略
故障排除指南
Web 安装向导问题
安装页面无法访问
- 检查项目文件是否完整上传
- 确认 PHP 版本满足最低要求（5.6.0+）
- 查看 Web 服务器错误日志获取详细信息
环境检测失败
- 检查 PHP 扩展是否全部启用
- 确认目录权限设置正确
- 验证磁盘空间是否充足
数据库连接失败
- 检查数据库主机、用户名、密码是否正确
- 确认数据库服务正常运行
- 验证用户权限是否足够访问指定数据库
- 检查防火墙设置是否阻止数据库连接
配置文件生成失败
- 确保
config/目录有写入权限 - 检查磁盘空间是否充足
- 验证文件系统权限设置
传统安装问题
数据库连接失败
- 检查数据库主机、用户名、密码是否正确
- 确认数据库服务正常运行
- 验证用户权限是否足够访问指定数据库
- 检查防火墙设置是否阻止数据库连接
配置文件问题
- 确保
config/config.php文件存在且可读 - 检查配置文件语法是否正确
- 验证数据库连接参数配置无误
权限相关问题
- 检查
storage目录权限设置 - 确认 Web 服务器进程有写入权限
- 验证 SELinux 或 AppArmor 等安全模块未阻止文件访问
URL 重写问题
- 确认
.htaccess文件存在且被服务器允许覆盖 - 检查 Apache 的
AllowOverride配置 - 验证 Nginx 的 rewrite 规则配置正确
安装锁相关的问题
重复安装提示
如果看到"系统已安装"的提示，可能是安装锁文件存在问题：
- 检查
storage/state/install.lock文件是否存在 - 删除该文件后重新访问安装向导
- 确认
core/bootstrap.php中的三级判定逻辑
安装完成后无法访问
- 检查安装锁文件是否正确创建
- 验证配置文件
config/config.php是否生成成功 - 确认数据库连接参数正确
章节来源
- core/bootstrap.php:42-60
- install/service/InstallLockService.php:47-57