安装部署指南

XPCMS 系统环境要求、安装步骤、配置说明与生产环境部署指南

一、环境要求

项目	最低要求	推荐配置
操作系统	Windows / Linux / macOS	Linux (CentOS 7+ / Ubuntu 20.04+)
PHP 版本	PHP 8.0+	PHP 8.1+
Web 服务器	Nginx / Apache	Nginx 1.20+
数据库	MySQL 5.7+	MySQL 8.0+ (InnoDB, utf8mb4)
PHP 扩展	PDO, PDO_MySQL, Mbstring, Fileinfo, GD/Imagick, OpenSSL, Curl, JSON, XML, Tokenizer
Composer	Composer 2.0+	最新稳定版
磁盘空间	200MB+	500MB+

提示：PHP 需开启 allow_url_fopen 和 putenv 函数。如使用 Redis 缓存需额外安装 php-redis 扩展。

二、安装步骤

下载源码

将项目文件上传至 Web 服务器目录（如 /www/wwwroot/xpcms/），确保 tp/ 目录为网站根目录。

设置运行目录

将网站运行目录指向 tp/public/。TP6/8 框架规范要求 public 目录作为入口，确保核心代码不被直接访问。

配置伪静态（Nginx）

location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=$1 last;
        break;
    }
}

配置伪静态（Apache）

确保已开启 mod_rewrite 模块，项目已内置 .htaccess 文件。

安装 Composer 依赖

cd tp/
composer install

如未安装 Composer，请访问 getcomposer.org 下载安装。

设置目录权限

chmod -R 755 tp/runtime/
chmod -R 755 tp/public/uploads/
chmod -R 755 tp/storage/

确保 PHP 进程用户有写入权限。

访问安装向导

浏览器访问 http://你的域名/install，按向导提示完成：
① 数据库连接配置 → ② 管理员账号创建 → ③ 系统初始化 → ④ 完成安装

注意：安装完成后请删除或重命名 tp/public/install.php 文件和 tp/app/install/ 目录，防止被恶意重复安装。

三、配置说明

3.1 环境配置文件 (.env)

项目根目录下的 .env 文件为环境变量配置，安装向导会自动生成。主要配置项：

配置项	示例值	说明
DB_TYPE	mysql	数据库类型
DB_HOST	127.0.0.1	数据库主机地址
DB_PORT	3306	数据库端口号
DB_NAME	xp_cms	数据库名称
DB_USER	root	数据库用户名
DB_PASS	your_password	数据库密码
DB_PREFIX	xp_	数据表前缀（固定，不可修改）
DB_CHARSET	utf8mb4	数据库字符集
APP_DEBUG	false	调试模式（生产环境必须 false）
TOKEN_JWT_SECRET	随机字符串	JWT 签名密钥（HS256）
TOKEN_ACCESS_EXPIRE	7200	Access Token 有效期（秒）
TOKEN_REFRESH_EXPIRE	604800	Refresh Token 有效期（秒）

警告：.env 文件不得使用节分组（如 [DATABASE]），ThinkPHP 的 parse_ini_file() 会错误解析节名作为变量名前缀。

3.2 数据库配置

配置文件位置：tp/config/database.php，所有参数从 .env 读取：

return [
    'default' => env('DB_DRIVER', 'mysql'),
    'connections' => [
        'mysql' => [
            'type'     => env('DB_TYPE', 'mysql'),
            'hostname' => env('DB_HOST', '127.0.0.1'),
            'database' => env('DB_NAME', ''),
            'username' => env('DB_USER', 'root'),
            'password' => env('DB_PASS', ''),
            'hostport' => env('DB_PORT', '3306'),
            'charset'  => env('DB_CHARSET', 'utf8'),
            'prefix'   => env('DB_PREFIX', 'xp_'),
        ],
    ],
];

四、生产环境部署建议

建议项	说明
关闭调试模式	设置 APP_DEBUG = false，避免暴露错误详情
启用 HTTPS	配置 SSL 证书，强制 HTTPS 访问
配置 Redis 缓存	修改 config/cache.php 使用 Redis 驱动提升性能
设置定时任务	配置 crontab 定时执行 BackupDatabase 命令自动备份数据库
文件权限收紧	仅 runtime/、public/uploads/、storage/ 允许写入
OPcache 加速	PHP 8 内置 OPcache，生产环境建议启用并配置合理参数
日志管理	定期清理 runtime/log/ 下的旧日志文件

五、系统更新

XPCMS 支持在线 ZIP 更新包安装，无需手动替换文件：

上传更新包

后台 → 系统更新 → 上传 .zip 格式的更新包文件

解析变更

系统自动解析 ZIP 内容，展示文件变更清单

确认安装

确认变更清单后系统自动备份原文件到 runtime/update/backup_YYYYMMDD_HHMMSS/，然后安装更新

安全机制：更新包路径白名单仅允许覆盖 app/、config/、route/、public/static/ 等安全目录；黑名单排除 .env、runtime/、storage/、vendor/ 等关键文件。安装前自动备份，支持手动回滚。