QloApps 1.7.0 配置参数详解

目标：逐项讲清 QloApps 1.7.0 运行涉及的五层配置——config/settings.inc.php（安装生成）、config/defines.inc.php（运行模式与路径常量）、数据库 qlo_configuration 表（后台业务配置）、PHP 运行参数、Web 服务器参数。所有文件内容、表数据、修改效果均在 Ubuntu 22.04（Apache 2.4.52 + PHP 8.1 + MySQL 8.0.46）安装实例上实测取证，官方来源以仓库内文件原文为准。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS
• 应用：QloApps 1.7.0（源码安装于 /var/www/qloapps，_QLOAPPS_VERSION_ 1.7.0.0 / _PS_VERSION_ 1.6.1.23）
• Web 服务器：Apache 2.4.52（含 mod_rewrite）
• PHP：8.1.2，定制参数文件 /etc/php/8.1/apache2/conf.d/99-qloapps.ini
• 数据库：MySQL 8.0.46，库名 qloapps，表前缀 qlo_
• 安装方式与过程见《QloApps 1.7.0 Ubuntu 22.04 安装指南》

二、前置条件

• 已按安装指南完成安装并可访问前台与后台（config/settings.inc.php 已生成）；
• 具备服务器命令行权限（修改配置文件、执行 SQL）；
• 后台超级管理员账号（默认你安装时填写的管理员邮箱）；
• 排障时用到的日志位置：Apache 错误日志 /var/log/apache2/qloapps_error.log（虚拟主机配置里定义）。

三、配置体系总览

QloApps 的配置分散在五层，改哪层取决于要调什么：

💡 改动生效方式：①② 层是 PHP 文件，改完即生效（个别受 cache/ 编译缓存影响的场景需清缓存）；③ 层后台保存即写库即生效；④ 层要 systemctl restart apache2；⑤ 层 systemctl reload apache2。

四、settings.inc.php：安装级参数详解

安装完成后 config/settings.inc.php 的完整实测内容（Cookie 密钥为实测样本，你的值会不同）：

<?php
define('_DB_SERVER_', '127.0.0.1');
define('_DB_TYPE_', 'MySQL');
define('_DB_NAME_', 'qloapps');
define('_DB_USER_', 'qloapps');
define('_DB_PASSWD_', 'q1w2e3r4');
define('_DB_PREFIX_', 'qlo_');
define('_MYSQL_ENGINE_', 'InnoDB');
define('_PS_CACHING_SYSTEM_', 'CacheMemcache');
define('_PS_CACHE_ENABLED_', '0');
define('_COOKIE_KEY_', 'HBGOBv0ApUSrBIoxaafch4sAhE1Xr2xAgJMif33fahjvuzyUnOiLr7mq');
define('_COOKIE_IV_', 'gA6HOps2');
define('_NEW_COOKIE_KEY_', 'yE7YabGZKjbhsLvS468yZ9wcfX3ErltdYQ986hQxt1ouCusLn6vcgXla');
define('_PS_CREATION_DATE_', '2026-10-24');
define('_PS_VERSION_', '1.6.1.23');
define('_QLOAPPS_VERSION_', '1.7.0.0');

逐项说明（全部为安装实例实测内容）：

⚠️ 操作红线：settings.inc.php 由安装器生成，不手工重建；备份系统时优先备份它；文件权限建议 640 且属主 www-data——它含数据库口令与加密盐。

五、defines.inc.php：运行模式与路径常量

config/defines.inc.php 是源码自带的框架级常量定义（实测原文节选）：

5.1 调试模式（排障最常用）

实测原文（27–38 行）：

/* Debug only */
if (!defined('_PS_MODE_DEV_')) {
    define('_PS_MODE_DEV_', false);
}
/* Compatibility warning */
define('_PS_DISPLAY_COMPATIBILITY_WARNING_', false);
if (_PS_MODE_DEV_ === true) {
    @ini_set('display_errors', 'on');
    @error_reporting(E_ALL | E_STRICT);
    define('_PS_DEBUG_SQL_', true);
} else {
    @ini_set('display_errors', 'off');
    define('_PS_DEBUG_SQL_', false);
}

define('_PS_DEBUG_PROFILING_', false);
define('_PS_MODE_DEMO_', false);

实测验证：将 _PS_MODE_DEV_ 改为 true 后前台仍正常响应（curl -L 实测 http=200），错误页从"白屏/500"变为完整堆栈；改回 false 恢复静默。改完无需清缓存立即生效。

5.2 目录与部署形态常量

实测原文节选（含路径依赖关系）：

if (!defined('_PS_CACHE_DIR_')) {
    define('_PS_CACHE_DIR_',             _PS_ROOT_DIR_.'/cache/');
}
define('_PS_CONFIG_DIR_',             _PS_CORE_DIR_.'/config/');
define('_PS_CUSTOM_CONFIG_FILE_',     _PS_CONFIG_DIR_.'settings_custom.inc.php');
define('_PS_CLASS_DIR_',             _PS_CORE_DIR_.'/classes/');

要点：

• _PS_ROOT_DIR_ = 应用根目录（本文实例 /var/www/qloapps），_PS_CORE_DIR_ 同值；_PS_CACHE_DIR_ 指向 cache/（Smarty 编译产物与类索引），改代码/改模板不生效时第一步就是清它：rm -rf /var/www/qloapps/cache/*；
• _PS_CUSTOM_CONFIG_FILE_（config/settings_custom.inc.php）默认不存在，可手工创建用于在不污染 settings.inc.php 的前提下覆盖常量（升级时 settings.inc.php 可能被重写，custom 文件更稳）；
• 另有 _PS_HOST_MODE_ 支持 getenv() 注入，是官方给托管环境（如云市场镜像）用的部署形态开关，自建服务器不动它。

六、qlo_configuration 表：业务级参数（后台可视化）

后台「Advanced Parameters」各页面的保存动作，最终都落到数据库 qlo_configuration 表（键值对）。改这层优先用后台界面（带校验、带钩子触发），直连 SQL 仅在批量初始化/后台进不去时使用。以下为安装实例的真实取样（SELECT name,value ... 实测回显）：

name                    value
PS_COUNTRY_DEFAULT      21
PS_LANG_DEFAULT         1
PS_MAIL_METHOD          1
PS_REWRITING_SETTINGS   1
PS_SHOP_EMAIL           hotelprime@htl.com
PS_SHOP_NAME            QloDemo Hotel
PS_SMARTY_CACHE         1
PS_SMARTY_FORCE_COMPILE 0
PS_TIMEZONE             Asia/Shanghai
PS_WEBSERVICE           1

常用键逐项说明（值均为实测）：

💡 直连 SQL 的正确姿势（以开 API 为例）：UPDATE qlo_configuration SET value='1' WHERE name='PS_WEBSERVICE';。注意个别键（如 PS_WEBSERVICE）在未于后台保存过前表中没有行，此时用 INSERT INTO qlo_configuration (name,value,date_add,date_upd) VALUES ('PS_WEBSERVICE','1',NOW(),NOW());（API 启用过程实测）。改完立即生效，无需清缓存。

另一张易混表：qlo_shop_url（domain/domain_ssl/physical_uri/virtual_uri 字段）存站点访问域名——换域名迁移必改它，不改会 302 循环（实测见安装指南 FAQ Q2）：

SELECT id_shop_url, domain, domain_ssl, physical_uri, virtual_uri FROM qlo_shop_url;
-- 迁移示例：UPDATE qlo_shop_url SET domain='newhotel.example.com', domain_ssl='newhotel.example.com' WHERE id_shop_url=1;

七、PHP 运行级参数（php.ini / conf.d）

安装指南 2.2 节创建的 /etc/php/8.1/apache2/conf.d/99-qloapps.ini（实测内容与生效值）：

修改后生效命令与核验（实测回显）：

sudo systemctl restart apache2
php -r 'echo ini_get("memory_limit"), " ", ini_get("upload_max_filesize"), " ", ini_get("max_execution_time"), PHP_EOL;'

256M 16M 500

另外两个与排障相关的隐含项：allow_url_fopen=on（官方要求，语言包下载与市场模块依赖，PHP 8.1 默认 on）；时区不设的话 PHP 警告 date.timezone，可在同文件补 date.timezone = Asia/Shanghai。

八、Web 服务器级参数（Apache）

实测 vhost（/etc/apache2/sites-available/qloapps.conf）关键项：

Nginx 用户对照：无 .htaccess 机制，需把伪静态规则翻译进 location / { try_files $uri $uri/ /index.php?$query_string; }，官方文档 docs.qloapps.com 有 Nginx 参考配置。

九、生产配置模板

9.1 中型酒店（10–100 间房，日均 1–3 千 UV）单机 4C/8G

; /etc/php/8.1/apache2/conf.d/99-qloapps.ini
memory_limit = 256M
upload_max_filesize = 16M
post_max_size = 32M
max_execution_time = 500
date.timezone = Asia/Shanghai
; opcache 对 PHP 8.1 提速明显，建议常开
opcache.enable = 1
opcache.memory_consumption = 128

-- 数据库层（配合 MySQL 8 默认即可）
-- 缓存改文件缓存（无需额外服务）
UPDATE qlo_configuration SET value='1' WHERE name='PS_SMARTY_CACHE';

// settings.inc.php 追加启用 CacheFs（文件缓存，无需装扩展）
define('_PS_CACHE_ENABLED_', '1');
define('_PS_CACHING_SYSTEM_', 'CacheFs');

9.2 场景 → 配置对照

十、常见问题（FAQ）

Q1：改了 defines.inc.php 不生效？ 确认编辑的是运行实例的 config/defines.inc.php（CLI 与 Web 用的同一份，但注意多实例服务器别改错目录）；删除 _PS_CACHE_DIR_（cache/）内容后刷新；PHP 不需要重启（该文件每请求都重新 include）。

Q2：后台保存某项后前台没变化？ 后台多数页面写的是 qlo_configuration 表，保存即生效；但模板相关项（主题设置、首页编排）受 Smarty 缓存影响，清 cache/ 或后台 Advanced Parameters → Performance 点 Clear cache。

Q3：settings.inc.php 丢了/被误删？ 系统报 "Link to database cannot be established"。从备份恢复；没有备份时按本文第四节字段手工重建（_COOKIE_KEY_ 无原值则所有用户密码需重置）。

Q4：_PS_MODE_DEV_ 开着会不会有安全风险？ 有。错误页暴露绝对路径、SQL 结构与部分配置。原则：排障时开、排障完立即 false；生产常态必须 false。

Q5：如何确认当前实际生效的 PHP 参数？ 不要只看配置文件——用运行时核验：php -r 'echo ini_get(...);' 核 CLI，Web 端受 mod_php 池配置影响时以安装目录下临时 phpinfo() 页面为准（用完即删）。

十一、参考链接

• 官方安装要求（PHP 参数依据）：https://github.com/Qloapps/QloApps#requirements
• settings.inc.php 生成逻辑（安装器源码）：https://github.com/Qloapps/QloApps/blob/develop/install/classes/controllerHttp.php
• 官方性能配置文档：https://docs.qloapps.com/
• 站内相关：《QloApps 1.7.0 介绍与选型指南》、《QloApps 1.7.0 Ubuntu 22.04 安装指南》、《QloApps 1.7.0 API 使用详解》（PS_WEBSERVICE 与密钥配置的实操篇）