Ubuntu 22.04 安装 Geeftlist 0.51.2 指南

在 Ubuntu 22.04 服务器上以源码方式安装 Geeftlist 0.51.2（Apache + PHP 8.3 + MariaDB + Redis）的实测指南：在线与离线双方案、服务与站点配置、安装验证与 7 条排障实录。

GeeftlistGeeftlist2026/10/28

Ubuntu 22.04 安装 Geeftlist 0.51.2 指南

目标：在 Ubuntu 22.04 服务器上完成 Geeftlist 0.51.2 的源码直装，覆盖"在线安装"与"离线安装"两条路径，并给出安装验证与常见故障处置。Geeftlist 的定位、架构与选型背景见《Geeftlist 介绍与选型指南》。本文所有命令与输出均在实测环境逐条执行并如实记录。

一、环境信息

本文实测环境如下（版本号均为实测环境中实际安装的软件版本）：

项目值
操作系统Ubuntu 22.04（x86_64）
Web 服务Apache/2.4.52（Ubuntu 官方仓库）
PHP8.3.36（CLI 与 Apache 模块，来自 ondrej/php PPA）
Composer2.2.30
数据库MariaDB 10.6.23（Ubuntu 22.04 官方仓库）
缓存Redis 6.0.16（Ubuntu 22.04 官方仓库）
前端构建Node.js v20.20.2 + npm 10.8.2
应用源码Geeftlist tag 0.51.2（commit a9aaf889e9b0c619b97b34af693f3c1fcc5ad179，提交日期 2026-10-23）
安装目录/var/www/webapp
访问地址http://localhost:8150/（本地验证用）

💡 关于版本来源：Geeftlist 官方仓库托管在 Codeberg（codeberg.org/nanawel/geeftlist），tag 0.51.2 为撰写本文时（查询日期 2026-10-28）的最新发布版本，安装时建议先到仓库 Releases 页核对是否有更新。

二、前置条件

2.1 安装系统软件包

Ubuntu 22.04 官方源自带的 PHP 为 8.1，而 Geeftlist 0.51.2 的 composer.lock 锁定依赖要求 PHP ≥ 8.2（详见排障实录第 1 条），因此 PHP 8.3 需来自 ondrej/php PPA：

sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get install -y apache2 mariadb-server redis-server \
  php8.3 libapache2-mod-php8.3 php8.3-intl php8.3-gd php8.3-mysql \
  php8.3-curl php8.3-xml php8.3-mbstring php8.3-zip php8.3-redis
sudo a2dismod php8.1 && sudo a2enmod php8.3

若系统未曾启用过 PHP 8.1，a2dismod php8.1 会提示模块不存在，忽略即可。Composer 参照官方文档安装（实测版本 2.2.30）。

2.2 校验软件版本与 PHP 模块

实测版本输出：

Server version: Apache/2.4.52 (Ubuntu)
mariadb  Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper
Redis server v=6.0.16 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=d6ed09173b889769

PHP 8.3.36 (cli) (built: Oct 21 2026 14:31:50) (NTS)
Composer version 2.2.30 2026-08-27 13:34:49
node v20.20.2
10.8.2

Geeftlist 要求的 PHP 扩展可用 php -m | grep 核对，实测确认以下 10 个模块均已加载：

curl
gd
intl
mbstring
mysqli
openssl
pdo_mysql
redis
xml
zip

2.3 启动基础服务

sudo systemctl enable --now apache2 mariadb redis-server
systemctl is-active apache2 mariadb redis-server

实测回显：

active
active
active

数据库与缓存的部署细节不在本文展开，可分别参考《MariaDB 11.8 配置参数详解》与《Ubuntu 22.04 安装 Redis 8 指南》（本文使用发行版自带的 10.6/6.0 版本，配置思路一致）。

三、版本与获取方式选型

Geeftlist 0.51.2 的源码获取有两条路径，按服务器网络条件二选一：

方案适用条件需要的外网访问特点
方案A：在线 git clone服务器可直接访问 codeberg.org、packagist.org、registry.npmjs.org全程联网步骤最少，依赖为最新解析结果；对出口网络要求最高
方案B：离线 tarball服务器无法出网或外网受限仅"打包机"联网在打包机完成依赖安装与前端构建后整体搬运，离线服务器零外网依赖

两方案最终产物一致：/var/www/webapp 目录（应用源码 + PHP 依赖 vendor + 已构建主题资源），区别仅在于依赖安装发生在哪台机器上。建议先在打包机完成方案A的全部步骤，再按方案V打包分发，这样两条路径的内容完全同源。

四、方案A：在线安装

4.1 获取源码

sudo mkdir -p /var/www && cd /var/www
sudo git clone --branch 0.51.2 --depth 1 https://codeberg.org/nanawel/geeftlist.git webapp

实测回显（输出节选）：

Cloning into 'webapp'...
Note: switching to 'a9aaf889e9b0c619b97b34af693f3c1fcc5ad179'.

Note: switching to ... 是 git clone --branch <tag> 检出到标签提交的正常提示。核对版本：

git -C /var/www/webapp log -1 --format="%H %cd" --date=short

实测回显：

a9aaf889e9b0c619b97b34af693f3c1fcc5ad179 2026-10-23

4.2 安装 PHP 依赖

cd /var/www/webapp/src
sudo composer install --no-dev --optimize-autoloader --no-interaction

实测回显（输出节选，首尾）：

Generating optimized autoload files
Class OliveOil\Core\Test\Model\ResourceModel\Db\SetupTest located in ./app/code/OliveOil/Core/Test/Model/Resource/Db/SetupTest.php does not comply with psr-4 autoloading standard. Skipping.
> test ! -x vendor/bin/phpcs || vendor/bin/phpcs --config-set installed_paths vendor/phpcompatibility/php-compatibility

其中 SetupTest ... does not comply with psr-4 为上游仓库自带的 psr-4 提示（测试类路径不规范，安装脚本已主动跳过），可安全忽略。

4.3 构建前端主题

主题源码位于 src/app/ui/default/，构建脚本为 Gulp + Webpack（npm run build 实际执行 gulp buildTask --production）：

cd /var/www/webapp/src/app/ui/default
npm install
npm run build

实测回显（输出尾部）：

webpack 5.74.0 compiled with 3 warnings
[07:17:15] Finished 'javascriptTask' after 12 s
[07:17:15] Finished 'buildTask' after 13 s

compiled with 3 warnings 为依赖内的告警，实测不影响功能。构建产物写入 src/pub/asset/default/，实测目录内容：

css
font
i18n
img
js
scss

未执行主题构建时页面样式与交互脚本不完整，因此该步骤在两种方案中都是必做项。

4.4 准备可写目录

运行时目录 src/var/ 需对 Web 服务运行用户（www-data）可写：

mkdir -p /var/www/webapp/src/var
sudo chown -R www-data:www-data /var/www/webapp/src/var

五、方案B：离线安装

5.1 在联网机器上制作离线包

先按第四章在该机器完成全部安装（含主题构建），然后打包。排除运行时目录 src/var（安装后自动重建）：

cd /var/www/webapp
tar czf /opt/geeftlist-0.51.2-src-vendor.tar.gz --exclude=./src/var -C /var/www webapp
ls -lh /opt/geeftlist-0.51.2-src-vendor.tar.gz

实测回显：

-rw-r--r-- 1 root root 154M Oct 28 07:14 /opt/geeftlist-0.51.2-src-vendor.tar.gz

包体 154M（其中 PHP vendor 依赖约 66M）。将 tarball 以任意内网手段（scp/U盘/内部制品库）搬运到目标服务器的 /opt/。

5.2 解压并安装

sudo mkdir -p /var/www && sudo tar xzf /opt/geeftlist-0.51.2-src-vendor.tar.gz -C /var/www
mkdir -p /var/www/webapp/src/var
sudo chown -R www-data:www-data /var/www/webapp/src/var

随后按第六章完成数据库初始化与 local.ini 配置，再执行安装命令（见 6.5 节）。离线路径实测同样以 Installation finished successfully 与 Success. 结束。

5.3 验证数据结构完整

安装完成后核对数据库表数量，实测 28 张：

mariadb -ugeeftlist -pq1w2e3r4 -N \
  -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='geeftlist';"

实测回显：

28

六、服务与站点配置

6.1 初始化数据库

以 root 进入 MariaDB 客户端执行（实测执行成功无输出）：

CREATE DATABASE geeftlist CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'geeftlist'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL ON geeftlist.* TO 'geeftlist'@'localhost';
FLUSH PRIVILEGES;

6.2 确认 Redis

应用默认使用 127.0.0.1:6379 的 0 号库，发行版默认配置即可满足；Redis 为硬依赖，停止后站点与健康检查端点会立即返回 500（实测）。

6.3 配置 Apache 虚拟主机

新建 /etc/apache2/sites-available/geeftlist.conf（实测内容）：

<VirtualHost *:80>
    ServerName geeftlist.local
    DocumentRoot /var/www/webapp/src/pub

    <Directory /var/www/webapp/src/pub>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/geeftlist-error.log
    CustomLog ${APACHE_LOG_DIR}/geeftlist-access.log combined
</VirtualHost>

要点：DocumentRoot 必须指向 src/pub（入口 index.php 所在目录），且 AllowOverride All 放行目录内 .htaccess 的重写与缓存规则。启用站点与重写模块：

sudo a2ensite geeftlist
sudo a2enmod rewrite
sudo systemctl reload apache2

实测 a2enmod rewrite 输出：

Module rewrite already enabled

模块加载核对：

apache2ctl -M 2>/dev/null | grep -E "rewrite|php"

实测回显：

 php_module (shared)
 rewrite_module (shared)

6.4 编写 local.ini

新建 /var/www/webapp/src/etc/local.ini（可直接复制，密钥替换为自己的值）：

; Local overrides for this deployment (do not edit src/etc/config.ini)
[globals]
DEBUG=2

[app]
MODE=production
TITLE=Geeftlist
BASE_URL=http://localhost:8150/
TIMEZONE=Asia/Shanghai
GEEFTER_REGISTRATION_ENABLE=1
EMAIL_ENABLED=0
NO_CONFIRMATION_EMAIL=1
SKIP_EMAIL_CHECK_MX=1
RESOURCE_CONFIG.db.driver=Pdo_Mysql
RESOURCE_CONFIG.db.database=geeftlist
RESOURCE_CONFIG.db.username=geeftlist
RESOURCE_CONFIG.db.password=q1w2e3r4
RESOURCE_CONFIG.db.hostname=127.0.0.1
RESOURCE_CONFIG.db.port=3306
RESOURCE_CONFIG.db.charset=utf8mb4
RESOURCE_CONFIG.redis_cache.host=127.0.0.1
RESOURCE_CONFIG.redis_cache.port=6379
RESOURCE_CONFIG.redis_cache.database=0
GEEFTER_SESSION_SECRET_KEY=<openssl rand -base64 48 生成>
AUTHENTICATION_JWT_SECRET_KEY=<openssl rand -base64 48 生成>

密钥生成命令（两把密钥各执行一次，输出整行粘贴到对应参数）：

openssl rand -base64 48

两个高频踩坑点（均有实测复盘，见排障实录第 4、5、6 条）：DEBUG 必须保持 2；AUTHENTICATION_JWT_SECRET_KEY 必须写在 [app] 段。参数级的完整解释见《Geeftlist 0.51.2 配置参数详解》。

6.5 执行安装命令

cd /var/www/webapp
sudo -u www-data php8.3 ./src/console setup/install

实测回显（输出尾部）：

2026-10-28T06:38:38+00:00 [20 MB] INFO Upgrade finished successfully []
2026-10-28T06:38:38+00:00 [20 MB] INFO Installation finished successfully []
Success.

6.6 配置定时任务

应用的延迟通知、数据清理等由内置调度器执行，需外部周期性请求 /cron/run 触发。为 www-data 配置 crontab：

*/5 * * * * curl -s http://127.0.0.1/cron/run > /dev/null

七、验证与自检

7.1 健康检查端点

curl -s http://127.0.0.1/system/healthcheck

实测回显（输出节选）：

# HELP geeftlist_collect_time 
# TYPE geeftlist_collect_time gauge
geeftlist_collect_time 1.4938969612122
# HELP geeftlist_cron_last_run 
# TYPE geeftlist_cron_last_run gauge
geeftlist_cron_last_run{date_iso="2026-10-28T06:57:19+00:00"} 1793170639
# HELP geeftlist_entity_count 
# TYPE geeftlist_entity_count gauge
geeftlist_entity_count{entity_code="geefter",count_type="total"} 3
geeftlist_entity_count{entity_code="gift",count_type="total"} 1
# HELP geeftlist_system_info 
# TYPE geeftlist_system_info gauge
geeftlist_system_info{version="dev",version_full="dev",version_date="2026-10-28T06:33:03+00:00"} 1
# HELP php_info Information about the PHP environment.
# TYPE php_info gauge
php_info{version="8.3.36"} 1

两点说明：其一，源码直装（--depth 1 拉取）不含标签元数据，version 显示为 dev，不影响功能；其二，cron_last_run 在定时任务首次触发后开始更新，可作为 cron 配置是否生效的核对项。

7.2 首次登录

浏览器访问 http://localhost:8150/，进入注册页创建首个用户。本文示例账号：用户名 admin、邮箱 admin@example.com、密码 q1w2e3r4（默认密码最小长度为 8，该密码满足校验；若你在 local.ini 中调高了 PASSWORD_MIN_LENGTH，注册时需用更长密码，之后再通过命令行重置——该约束的实测细节见参数详解篇）。

7.3 定时任务验证

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/cron/run

实测回显：

200

八、常见问题与排障实录

以下 7 条均来自本文实测过程中的真实故障与处置记录。

8.1 PHP 8.1 下 composer install 失败：lock 文件不兼容

现象：在 Ubuntu 22.04 自带的 PHP 8.1.2 上执行 composer install，实测报错（输出节选）：

Your lock file does not contain a compatible set of packages. Please run composer update.

  Problem 1
    - laminas/laminas-stdlib is locked to version 3.21.0 and an update of this package was not requested.
    - laminas/laminas-stdlib 3.21.0 requires php ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0 -> your php version (8.1.2) does not satisfy that requirement.
  Problem 2
    - lcobucci/clock is locked to version 3.5.0 and an update of this package was not requested.
    - lcobucci/clock 3.5.0 requires php ~8.3.0 || ~8.4.0 || ~8.5.0 -> your php version (8.1.2) does not satisfy that requirement.
  Problem 3
    - symfony/css-selector is locked to version v7.3.6 and an update of this package was not requested.
    - symfony/css-selector v7.3.6 requires php >=8.2 -> your php version (8.1.2) does not satisfy that requirement.

原因：composer.lock 锁定的依赖版本要求 PHP ≥ 8.2，且上游期望用锁定版本安装（不应按提示执行 composer update）。 处置：安装 ondrej/php PPA 的 PHP 8.3 并切换 Apache 模块（见 2.1 节），CLI 与 Web 两端都要确认切到 8.3（php -v 与 apache2ctl -M 双验证）。

8.2 Composer 克隆依赖时报 Host key verification failed

现象：composer install 过程中访问 GitHub 依赖时报 Host key verification failed。 原因：Composer 默认的 github-protocols 包含 SSH 协议，服务器未配置 GitHub SSH 密钥且未收录主机指纹。 处置：强制 Composer 走 HTTPS：

composer config -g github-protocols https

8.3 出口网络受限：clone/依赖下载超时

现象：git clone Codeberg 仓库或 composer install/npm install 长时间无输出直至超时。 原因：服务器访问 codeberg.org / packagist.org / registry.npmjs.org 的链路不通或过慢。 处置：临时为当前会话配置 HTTP 代理后重试；或彻底放弃在线路径，改用方案B离线包（本文实测 154M 单文件即可完成搬运）。

8.4 JWT 密钥写在 [api] 段导致整站跳 /error

现象：安装完成后首页 302 跳转 /error，src/var/log/error.log 出现 InvalidKeyProvided: Key cannot be empty。 原因：AUTHENTICATION_JWT_SECRET_KEY 只写在了 local.ini 的 [api] 段，而该段仅在 API 上下文加载；Web 上下文读取的是 [app] 段，取不到密钥。 处置：把该密钥补进 [app] 段（[api] 段可保留同值），随后清缓存：

sudo -u www-data php8.3 ./src/console cache/clear

8.5 注册使用内部邮箱域不生效

现象：使用 admin@geeftlist.local 这类不可公网解析的邮箱域注册，提交后新用户未入库（首次实测中 geefter 表保持为空）。 原因：注册流程默认对邮箱域做 MX 记录校验，.local 等内部域无 MX 记录。 处置：改用具备 MX 记录的域名（实测 example.com 注册成功），或在 local.ini 中设置 SKIP_EMAIL_CHECK_MX=1 跳过校验；无 SMTP 的实验环境建议同时设置 EMAIL_ENABLED=0、NO_CONFIRMATION_EMAIL=1。

8.6 DEBUG 设为 0 后整站 500

现象：将 [globals] 段 DEBUG 从 2 改为 0 并清缓存后，所有页面返回 500，日志报 Could not parse file: etc/monolog.yml。 原因：实测 0.51.2 在 DEBUG=0 时日志配置初始化失败（monolog 配置文件解析异常），属于该版本的可用性边界，而非配置笔误。 处置：DEBUG 保持 2；该参数逐档实测行为见参数详解篇。

8.7 词典目录权限不足

现象：执行词典同步类维护命令时报 Permission denied（目标为 src/app/dict/ 目录）。 原因：src/app/dict/ 随源码落地时属 root，未纳入 4.4 节的可写目录授权。 处置：将词典目录一并授权给运行用户：

sudo chown -R www-data:www-data /var/www/webapp/src/app/dict

九、卸载与清理

按依赖的反序拆除，实测可完全还原系统状态：

# 1. 停用站点与模块
sudo a2dissite geeftlist && sudo systemctl reload apache2
# 2. 删除应用与数据
sudo rm -rf /var/www/webapp
mariadb -e "DROP DATABASE IF EXISTS geeftlist; DROP USER IF EXISTS 'geeftlist'@'localhost'; FLUSH PRIVILEGES;"
# 3. 移除定时任务（删除对应 crontab 条目）
crontab -l -u www-data
# 4. 如需彻底回收软件包
sudo apt-get purge -y php8.3* libapache2-mod-php8.3

数据库层面的备份先行原则（先备份后变更）与恢复演练见《Geeftlist 0.51.2 常用 CLI 命令与工具详解》。

十、参考链接