QloApps 1.7.0 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 服务器上从零安装 QloApps 1.7.0（开源酒店预订与物业管理系统），覆盖官方推荐的「源码 + Web 安装向导」主线方案、CLI 无人值守安装方案与官方 Docker 镜像替代方案，并沉淀安装全程的实测排障（数据库权限、重定向循环、语言包缺失）。全部命令与回显均在 Ubuntu 22.04（Apache 2.4.52 + PHP 8.1 + MySQL 8.0.46）环境实测通过。

一、环境信息

本文实测环境（一台全新 Ubuntu 22.04 服务器即可复现）：

操作系统：Ubuntu 22.04 LTS（x86_64）
Web 服务器：Apache 2.4.52（apache2 -v 实测）
PHP：8.1.2（php -v 实测，QloApps 1.7.0 支持 8.1–8.4）
数据库：MySQL 8.0.46（SELECT VERSION(); 实测返回 8.0.46-0ubuntu0.22.04.4）
应用：QloApps 1.7.0（官方 GitHub v1.7.0 tag 源码包，约 44MB，部署后约 115MB）
站点目录：/var/www/qloapps
数据库：库名 qloapps，业务账号 qloapps，表前缀 qlo_，安装后 SHOW TABLES 输出 301 行（含表头，即 300 张表）
演示域名：hotel.example.com（生产环境替换为你的真实域名）

二、前置条件

2.1 安装 LAMP 组件与 PHP 扩展

QloApps 1.7.0 是 PHP + MySQL 应用，必须先备齐 Web 服务器、PHP 及其必需扩展（官方要求：PDO_MySQL、cURL、OpenSSL、SOAP、GD、SimpleXML、DOM、Zip、Phar）：

sudo apt-get update
sudo apt-get install -y apache2 libapache2-mod-php php8.1 php8.1-mysql \
  php8.1-curl php8.1-gd php8.1-soap php8.1-xml php8.1-zip \
  php8.1-mbstring php8.1-intl php8.1-common mysql-server unzip

验证组件就位（实测回显）：

apache2 -v | head -1
php -v | head -1

Server version: Apache/2.4.52 (Ubuntu)
PHP 8.1.2 (cli) (built: Jul 15 2024 12:07:15) (NTS)

mysql --version

mysql  Ver 8.0.46-0ubuntu0.22.04.4 for Linux on x86_64 ((Ubuntu))

2.2 调整 PHP 配置

按官方 README 要求调整 PHP 参数（memory_limit 128M、upload_max_filesize 16M、max_execution_time 500），写入独立配置文件便于管理：

sudo tee /etc/php/8.1/apache2/conf.d/99-qloapps.ini > /dev/null <<'EOF'
memory_limit = 256M
upload_max_filesize = 16M
post_max_size = 32M
max_execution_time = 500
EOF

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

💡 说明：memory_limit 官方下限 128M，安装与后台批量导入场景 256M 更稳；max_execution_time=500 用于覆盖安装期建表与语言包下载的耗时。

2.3 准备数据库（MySQL 依赖链）

QloApps 与 MySQL 的依赖链为：MySQL 服务运行 → 建空库（utf8mb4）→ 建业务账号并授权 → 安装向导以该账号连 127.0.0.1:3306 建表（300 张，前缀 qlo_）→ 连接凭据写入 config/settings.inc.php。逐条执行：

sudo mysql

CREATE DATABASE qloapps DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER "qloapps"@"localhost" IDENTIFIED BY "q1w2e3r4";
GRANT ALL PRIVILEGES ON qloapps.* TO "qloapps"@"localhost";
FLUSH PRIVILEGES;
EXIT;

验证业务账号可连：

mysql -uqloapps -pq1w2e3r4 qloapps -e "SELECT VERSION();"

实测输出：

+---------------------------+
| VERSION()                 |
+---------------------------+
| 8.0.46-0ubuntu0.22.04.4   |
+---------------------------+

⚠️ 注意：生产环境请为数据库使用强口令并限制来源 IP（qloapps@<应用服务器IP>），本文 q1w2e3r4 仅为演示口令。

三、版本选型说明

安装前先确定版本。QloApps 版本与运行环境对照（官方 README 与 Releases 实查，2026-10-24）：

版本	发布日期	PHP 支持	MySQL 支持	选型建议
1.7.0（当前稳定）	2025-07-07	8.1 – 8.4	5.7 – 8.4	新装必选：PHP 8.x/MySQL 8 兼容（PR #1464）
1.6.1	2024-10-10	PHP 7.x 时代内核	5.7/8.0	仅存量环境沿用
1.6.0	2023-04-18	PHP 7.x	5.7/8.0	已被 1.6.1 取代
≤1.5.2	2022-02 及更早	PHP 7.x	5.6/5.7	不建议新装

选型结论：

服务器是 Ubuntu 22.04（仓库默认 PHP 8.1）→ 直接装 1.7.0，版本完全匹配；
不要装 1.6.x 及以下：它们在 PHP 8.1 上会出现兼容性错误，官方 1.7.0 才完成 PHP 8.1–8.4 适配；
获取最新稳定版号的命令（不硬编码，发新版本后以命令为准）：

curl -s https://api.github.com/repos/Qloapps/QloApps/releases/latest | grep -m1 '"tag_name"'

实测输出：

  "tag_name": "v1.7.0",

四、安装方案 A：源码 + Web 安装向导（官方推荐）

4.1 方案说明

这是官方 README 给出的标准路径：下载官方源码包 → 部署到 Web 目录 → 浏览器打开安装向导完成安装。优点是全程图形化、兼容性检查内建；适用于绝大多数单机部署。

4.2 下载与部署源码

cd /tmp
wget https://github.com/Qloapps/QloApps/archive/refs/tags/v1.7.0.zip -O qloapps-1.7.0.zip
ls -l qloapps-1.7.0.zip

实测输出（约 44MB）：

-rw-r--r-- 1 root root 45975514 Oct 24 10:40 qloapps-1.7.0.zip

⚠️ 国内服务器直连 GitHub 下载慢或失败时，可让 wget 走出网代理：wget -e use_proxy=yes -e http_proxy=<你的代理地址> https://github.com/Qloapps/QloApps/archive/refs/tags/v1.7.0.zip -O qloapps-1.7.0.zip，或本地下载后将 zip 包上传到服务器。

解压并部署到站点目录：

unzip -q qloapps-1.7.0.zip
sudo mkdir -p /var/www/qloapps
sudo cp -a QloApps-1.7.0/. /var/www/qloapps/
sudo chown -R www-data:www-data /var/www/qloapps
ls /var/www/qloapps | wc -l
du -sh /var/www/qloapps

实测输出：

36
115M	/var/www/qloapps

4.3 配置 Apache 虚拟主机

sudo tee /etc/apache2/sites-available/qloapps.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerName hotel.example.com
    DocumentRoot /var/www/qloapps
    <Directory /var/www/qloapps>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/qloapps_error.log
    CustomLog ${APACHE_LOG_DIR}/qloapps_access.log combined
</VirtualHost>
EOF
sudo a2dissite 000-default
sudo a2enmod rewrite
sudo a2ensite qloapps
sudo systemctl reload apache2

💡 说明：AllowOverride All 是必须项——QloApps 依赖 .htaccess 实现伪静态（房态页、SEO URL）；a2dissite 000-default 让该站点成为默认站点，多站点并存时改为按 ServerName 匹配即可。

验证安装器可访问（实测回显）：

curl -sI http://127.0.0.1/install/ | head -3

HTTP/1.1 200 OK
Date: Sat, 24 Oct 2026 03:05:12 GMT
Server: Apache/2.4.52 (Ubuntu)

4.4 运行 Web 安装向导

浏览器打开 http://<服务器IP或域名>/install/，按向导逐步进行（每步右上角 Next）：

Welcome：选择安装语言（选 English 最稳，见「九、常见问题」Q4 的语言包缺失问题）；
License Agreements：勾选同意 OSL 3.0 与相关协议；
System Compatibility：系统自动检查 PHP 版本、扩展、目录写权限，全部显示绿色 Check 才能继续；若报错，回到 2.2 节核对 PHP 配置与 2.1 节扩展；
Store Information：店铺名（示例 QloDemo Hotel）、店铺分类、国家、时区、管理员姓名、管理员邮箱（登录账号）、管理员密码（示例 q1w2e3r4）；
Database Configuration：数据库服务器填 127.0.0.1（1.7.0 官方明确要求填 127.0.0.1 而非 localhost，MySQL 走 TCP）、数据库名 qloapps、登录 qloapps、密码 q1w2e3r4、表前缀 qlo_；点 Verify 确认 Database is connected 后勾选清空已有数据，Next。

向导自动执行建库表、写入默认数据、安装模块与主题，全程约 2–5 分钟（视服务器性能）。

4.5 安装后收尾（必须执行）

安装完成后向导提示两件事，按提示执行：

# 1. 删除安装目录（安全要求：不删除任何人都可重装你的系统）
sudo rm -rf /var/www/qloapps/install

管理后台目录被自动改名为随机串（内置安全特性）。查看实际名称：

ls -d /var/www/qloapps/admin*/

实测输出：

/var/www/qloapps/admin022z5qwsy/

💡 说明：随机后台路径是 QloApps 安装时自动生成的（每次安装不同），安装完成页会显示你的实际地址。生产环境建议再收紧：限制后台路径的来源 IP，或更换为自定义目录名。

4.6 验证安装结果

前台首页（实测回显）：

curl -s -L http://127.0.0.1/ -o /tmp/fo.html -w "http=%{http_code} bytes=%{size_download}\n"
grep -oE "<title>[^<]*</title>" /tmp/fo.html | head -1

http=200 bytes=103298
<title>Hotel Prime - QloDemo Hotel</title>

数据库表数量（实测回显）：

mysql -uqloapps -pq1w2e3r4 qloapps -e "SHOW TABLES;" | wc -l

后台登录验证：浏览器打开 http://<服务器IP>/admin022z5qwsy/（以你的实际随机目录为准），输入管理员邮箱与密码 q1w2e3r4，登录成功后地址栏跳转仪表盘，页面标题显示 Dashboard • QloDemo Hotel，即安装成功。

五、安装方案 B：CLI 命令行安装器（无人值守）

5.1 方案说明

QloApps 自带命令行安装器 install/index_cli.php，无需浏览器，一条命令完成全部安装，适合批量部署、自动化脚本与无图形终端的服务器。参数与 Web 向导一致，全部参数在命令行显式给出。

5.2 部署源码

与方案 A 相同：先完成「二、前置条件」，再按 4.2 节下载解压。以下以第二套站点目录 /var/www/qloapps-cli 为例演示（同一台服务器可与方案 A 并存做对比测试，实际二选一即可）：

cd /tmp
sudo mkdir -p /var/www/qloapps-cli
sudo cp -a QloApps-1.7.0/. /var/www/qloapps-cli/
sudo chown -R www-data:www-data /var/www/qloapps-cli

为 CLI 站点准备独立数据库与虚拟主机（库名 qloapps_cli、域名 qloapps-cli.local，生产替换为真实值）：

mysql -uroot -pq1w2e3r4 -e "CREATE DATABASE IF NOT EXISTS qloapps_cli DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; GRANT ALL PRIVILEGES ON qloapps_cli.* TO 'qloapps'@'localhost'; FLUSH PRIVILEGES;"

5.3 执行 CLI 安装

CLI 安装器完整参数（--db_create 在 5.4 节有实测说明）：

cd /var/www/qloapps-cli
sudo php install/index_cli.php \
  --step=all \
  --language=en \
  --timezone=Asia/Shanghai \
  --domain=hotel.example.com \
  --base_uri=/ \
  --db_server=127.0.0.1 \
  --db_user=qloapps \
  --db_password=q1w2e3r4 \
  --db_name=qloapps_cli \
  --db_clear=1 \
  --prefix=qlo_ \
  --engine=InnoDB \
  --name="QloCli Hotel" \
  --country=us \
  --firstname=Admin \
  --lastname=User \
  --email=admin@qloapps.local \
  --password=q1w2e3r4 \
  --newsletter=0

实测输出（正常完成时末尾；过程中的 Language.php Warning 属良性告警，见 FAQ Q5）：

PHP Warning:  foreach() argument must be of type array|object, int given in /var/www/qloapps-cli/classes/Language.php on line 1051
PHP Warning:  foreach() argument must be of type array|object, int given in /var/www/qloapps-cli/classes/Language.php on line 1057
-- Installation successfull! --

5.4 验证 CLI 安装结果

head -5 /var/www/qloapps-cli/config/settings.inc.php
mysql -uqloapps -pq1w2e3r4 qloapps_cli -e "SHOW TABLES;" | wc -l
ls -d /var/www/qloapps-cli/admin*/

实测输出：

<?php
define('_DB_SERVER_', '127.0.0.1');
define('_DB_NAME_', 'qloapps_cli');
define('_DB_USER_', 'qloapps');
define('_DB_PASSWD_', 'q1w2e3r4');

301
/var/www/qloapps-cli/admin/

💡 说明：CLI 安装器不重命名 admin 目录（与 Web 向导行为不同），生产部署后建议手动改名：sudo mv /var/www/qloapps-cli/admin /var/www/qloapps-cli/yoursecret。配置好虚拟主机后（同 4.3 节，DocumentRoot 指向 /var/www/qloapps-cli）浏览器访问验证前台与后台即可。

六、部署方案 C：官方 Docker 镜像（容器化替代）

本章为容器化部署方案，命令以 Docker/Docker Compose 为载体，供已运行 Docker 的服务器选型；纯主机部署读者可跳过本章。

官方提供 Docker Hub 镜像 webkul/qloapps_docker（内置 Ubuntu 24.04 + Apache + PHP 8.4 + MySQL 8.0，约 481MB），把应用与数据库打包为一台"开箱即装"环境，安装向导仍需走一遍。

单机快速启动（环境变量必须显式给全）：

docker run -tid \
  -p 80:80 \
  -e USER_PASSWORD=q1w2e3r4 \
  -e MYSQL_ROOT_PASSWORD=q1w2e3r4 \
  -e MYSQL_DATABASE=qlo170 \
  --name qloappsv170 \
  webkul/qloapps_docker:latest

Compose 编排（生产推荐，持久化与重启策略显式化）：

name: qloapps-1.7.0-stack
services:
  qloapps:
    image: webkul/qloapps_docker:latest
    container_name: qloapps-170-app
    ports:
      - "80:80"
    environment:
      USER_PASSWORD: "q1w2e3r4"
      MYSQL_ROOT_PASSWORD: "q1w2e3r4"
      MYSQL_DATABASE: "qlo170"
    restart: unless-stopped

docker compose up -d
docker compose ps

实测输出：

NAME                IMAGE                        COMMAND                  SERVICE             STATUS
qloapps-170-app     webkul/qloapps_docker:latest "/usr/bin/bash"          qloapps             Up 8 minutes

⚠️ 两个官方镜像要点（实测确认）：① 1.7.0 镜像在安装向导的数据库服务器一栏必须手动填 127.0.0.1（1.6.x 及以前填 localhost）；② 应用数据在容器内 /home/qloapps/www/QloApps/，生产务必用 volume 挂载持久化该目录与 /var/lib/mysql，安装完成后同样要删除 /home/qloapps/www/QloApps/install 目录。

七、方案对比与选择建议

维度	A：源码 + Web 向导	B：CLI 安装器	C：官方 Docker 镜像
适用对象	单机首次部署（官方推荐）	批量/自动化部署	已有 Docker 运维体系
环境控制	自己装 LAMP，版本完全可控	同 A	镜像内置（Ubuntu 24.04/PHP 8.4/MySQL 8.0.42），不可细调
交互	浏览器五步向导	一条命令全参数	run/compose + 浏览器向导
admin 目录	自动改名随机串	保留 `admin`，需手动改名	保留 `admin`，需手动改名
升级便利	官方源码覆盖升级	同 A	换镜像 tag 重建（数据卷保留）
实测结论	全流程通过，301 行表	通过（需预建库，见 Q1）	通过（九步安装全部 success）

选择建议：常规单机生产选 A（环境自主可控、官方文档与社区排障均基于源码路径）；CI/自动化或多台批量初始化选 B；团队以容器为标准交付物时选 C（注意数据卷持久化）。

八、配置说明

8.1 核心配置文件位置

安装完成后需要掌握的文件与目录（方案 A 路径为例）：

路径	作用
`/var/www/qloapps/config/settings.inc.php`	数据库连接、表前缀、Cookie 加密密钥、版本号（安装向导生成，勿手工重建）
`/var/www/qloapps/config/defines.inc.php`	运行模式开关（调试、SQL 调试、缓存目录等常量定义）
`/var/www/qloapps/cache/`	类自动加载与 Smarty 编译缓存，改代码后清空生效
`/var/www/qloapps/themes/`	前台主题（默认 hotel-reservation-theme）
`/var/www/qloapps/modules/`	模块目录（渠道、支付、语言包等）
`/etc/apache2/sites-available/qloapps.conf`	Apache 虚拟主机（本文 4.3 节创建）
`/etc/php/8.1/apache2/conf.d/99-qloapps.ini`	PHP 定制参数（本文 2.2 节创建）

8.2 settings.inc.php 关键项（安装后实测内容，密码已按演示值脱敏格式照抄）

define('_DB_SERVER_', '127.0.0.1');
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('_PS_CREATION_DATE_', '2026-10-24');
define('_PS_VERSION_', '1.6.1.23');
define('_QLOAPPS_VERSION_', '1.7.0.0');

迁移或改库时编辑 _DB_SERVER_/_DB_NAME_/_DB_USER_/_DB_PASSWD_ 即可；_COOKIE_KEY_ 是密码加密盐，泄露等于全部客户密码可被离线破解，切勿外传。逐字段含义与更多配置项见《QloApps 1.7.0 配置参数详解》。

九、常见问题（FAQ）

Q1：CLI 安装器报 Access denied for user 'qloapps'@'localhost' to database 'qloapps_cli'，即使授权了该用户？

实测现象：CLI 安装器以 --db_user=qloapps 运行时直接抛出致命错误（即使 --db_create=1）：

PHP Fatal error:  Uncaught PrestaShopException: Link to database cannot be established:SQLSTATE[HY000] [1044] Access denied for user 'qloapps'@'localhost' to database 'qloapps_cli' in /var/www/qloapps-cli/classes/db/DbPDO.php:102

原因与解决：CLI 安装器是先连接目标库、再建表的顺序，普通账号没有建库权限时连不上。先用 root 建好库并授权，再跑安装器（本文 5.2 节即此处理）：

mysql -uroot -pq1w2e3r4 -e "CREATE DATABASE qloapps_cli DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; GRANT ALL PRIVILEGES ON qloapps_cli.* TO 'qloapps'@'localhost'; FLUSH PRIVILEGES;"

Web 向导不受此影响（向导阶段就让你填好了库）。

Q2：站点访问被 302 重定向到别的域名，或浏览器提示重定向次数过多？

实测现象：以非 80 端口或与安装时不一致的域名访问时，curl -I 看到响应 Location: http://qloapps-cli.local/index.php? 且循环重定向。原因：安装向导把访问域名写进了数据库 qlo_shop_url 表的 domain/domain_ssl 字段，后续所有请求被强制 302 到该域名的 80 端口。解决二选一：

# 改库对齐实际访问域名
mysql -uqloapps -pq1w2e3r4 qloapps \
  -e "UPDATE qlo_shop_url SET domain='hotel.example.com', domain_ssl='hotel.example.com' WHERE id_shop_url=1;"

或保持网站走标准 80/443 端口 + 与安装时一致的域名访问。结论：QloApps 站点请固定走 80/443 标准端口，换端口访问会出现 302 丢端口循环。

Q3：安装向导数据库步骤填 localhost 连不上？

1.7.0 起 MySQL 连接要求填 127.0.0.1（官方镜像文档明确此变更）：localhost 走 socket 而 PHP 运行用户的 socket 路径可能不一致；127.0.0.1 走 TCP 3306 稳定。同时确认 MySQL 在监听：

sudo ss -ltn | grep 3306

Q4：Web 向导最后一步报语言包安装失败（Cannot install language pack）？

实测现象：店铺国家选 China（默认语言 zh-TW）时，向导在下载语言包环节卡住报错。排查确认是官方语言服务器对 1.7.0 的部分语言包未提供（对 get_lang_pack.php?version=170&iso_lang=zh-tw 的请求返回内容为 false）。解决：安装时店铺区域选 United States（en） 完成安装；安装后在后台 Localization → Translations 再手动添加/导入中文语言包。另外确认服务器能访问 api.qloapps.com（语言包下载源），被墙环境配置出网代理后重试。

Q5：CLI 安装器输出大量 PHP Warning: foreach() argument must be of type array|object, int given in .../classes/Language.php on line 1051/1057？

实测确认属良性告警：CLI 模式下语言列表初始化的类型兼容告警，不影响安装结果，最终仍输出 -- Installation successfull! --，数据库 301 行表完整。可忽略；介意的话在 PHP CLI 配置中降低 error_reporting 级别。

Q6：System Compatibility 步骤红项如何逐个补齐？

常见红项对应处理：memory_limit 不达标 → 2.2 节配置未生效，systemctl restart apache2 后用 php -r 'echo ini_get("memory_limit");' 核对；缺 SOAP/Zip 扩展 → sudo apt-get install -y php8.1-soap php8.1-zip 后重启 Apache；目录不可写 → sudo chown -R www-data:www-data /var/www/qloapps。

十、卸载与清理

完整卸载 QloApps（含数据）：

# 1. 停用并删除站点配置
sudo a2dissite qloapps && sudo systemctl reload apache2
sudo rm /etc/apache2/sites-available/qloapps.conf
sudo a2dissite qloapps-cli 2>/dev/null

# 2. 删除应用目录
sudo rm -rf /var/www/qloapps /var/www/qloapps-cli

# 3. 删除数据库与账号
mysql -uroot -pq1w2e3r4 -e "DROP DATABASE IF EXISTS qloapps; DROP DATABASE IF EXISTS qloapps_cli; DROP USER IF EXISTS 'qloapps'@'localhost'; FLUSH PRIVILEGES;"

# 4. （可选）卸载不需要的 PHP 扩展与组件
sudo apt-get purge -y php8.1-soap php8.1-intl && sudo apt-get autoremove -y

Docker 部署的清理：docker compose down -v（连同数据卷删除），再 docker rmi webkul/qloapps_docker:latest。

⚠️ 卸载前如需保留业务数据，先备份：mysqldump -uqloapps -pq1w2e3r4 qloapps > qloapps_backup.sql。

十一、参考链接

官方安装文档：https://qloapps.com/install-qloapps/
服务器要求（README）：https://github.com/Qloapps/QloApps#requirements
源码包下载：https://github.com/Qloapps/QloApps/releases/tag/v1.7.0
官方 Docker 镜像说明：https://hub.docker.com/r/webkul/qloapps_docker
系统兼容性说明与 PHP 配置要求：https://docs.qloapps.com/
站内相关：《QloApps 1.7.0 介绍与选型指南》（定位与选型）、《QloApps 1.7.0 配置参数详解》（settings.inc.php/defines 逐项说明）、《QloApps 1.7.0 API 使用详解》（安装后开放 Webservice API）