Ubuntu 22.04 安装 Easy!Appointments 1.6.1 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 Easy!Appointments 1.6.1 开源在线预约系统，覆盖依赖链（Apache + PHP 8.2 + MariaDB）、官方 zip 发行包安装、安装向导、验证、升级与卸载全流程，并给出官方镜像备用方案。本文全部命令与回显均在 Ubuntu 22.04（Jammy）+ Apache 2.4.52 + PHP 8.2.35 + MariaDB 10.6.23 环境实测通过，服务器以 192.168.146.128 为例。

一、环境信息

本篇实测环境的关键组件版本如下，读者在同类环境操作时可逐项对照：

二、前置条件

安装开始前需确认服务器具备以下条件，任何一项缺失都会导致后续步骤失败：

1. 一台可登录的 Ubuntu 22.04 服务器，具备 root 或 sudo 权限；
2. 服务器与客户端网络可达：本文用内网地址 192.168.146.128，公网部署时替换为公网 IP 或域名；
3. 软件源可用：Ubuntu 22.04 官方源提供 Apache 与 MariaDB，但 PHP 8.2 需要额外添加 ondrej/php PPA（详见第四章 4.2 节，这是 Ubuntu 22.04 安装本系统的第一个关键差异点）；
4. 端口未被占用：Apache 默认监听 80，确认方式 ss -ltn | grep ':80 '，无输出即可用；
5. 浏览器：安装向导与管理后台均为 Web 页面，需要一台能访问服务器的客户机。

三、版本选型说明

Easy!Appointments 采用「大版本.功能.补丁」命名，截至查询日期 2026-10-23，官方最新稳定版为 1.6.1（2026-10-12 发布）。近几个稳定版节奏如下（摘自软件包内 CHANGELOG.md，全部为官方发布日期）：

选型结论：生产环境直接安装 1.6.1——它是含集中安全修复的最新补丁版（CHANGELOG 中 Security 条目最多的一版），且官方说明其为 stable release。不再建议安装 1.4.x 及更早版本（运行时要求旧、安全修复缺失）。版本号可在下载后用软件包内 composer.json 的 version 字段复核：

grep '"version"' composer.json

实测回显：

    "version": "1.6.1",

四、方案 A：官方 zip 包 + Apache + MariaDB 在线安装（推荐）

4.1 方案说明

这是官方 README「Installation (Production)」给出的标准路径：Apache 或 Nginx + PHP 8.2+ + MySQL 三件套，再解压官方发行包、写配置文件、跑安装向导。发行包自带全部 PHP 依赖（vendor 目录随包分发），全程不需要 Composer，是最贴合传统 LAMP 运维习惯、最易排障的方案。本节按下载 → 依赖 → 数据库 → 配置 → 站点 → 向导 → 验证的顺序完整执行一遍。

4.2 安装基础环境（Apache + PHP 8.2 + 扩展）

先更新索引并安装 Apache：

sudo apt update
sudo apt install -y apache2

Ubuntu 22.04 官方源只带 PHP 8.1，而 Easy!Appointments 1.6.1 要求 PHP ≥ 8.2（composer.json require 声明 php >=8.2），因此必须先添加 ondrej/php PPA 再安装 PHP 8.2 及所需扩展：

sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:ondrej/php
sudo apt update
sudo apt install -y php8.2 libapache2-mod-php8.2 php8.2-mysql php8.2-curl php8.2-gd php8.2-intl php8.2-mbstring php8.2-xml php8.2-zip php8.2-opcache

💡 说明：扩展清单与官方要求逐项对应——curl/json/mbstring/gd/simplexml/fileinfo 为 composer.json 硬性依赖（json、fileinfo 已内置于 PHP 核心），php8.2-mysql 提供 mysqli/pdo_mysql 数据库驱动，intl、xml、zip 为后台功能所需。本环境实测安装后 PHP 已加载模块共 54 个，关键模块核验：

php -m | grep -E '^(curl|gd|intl|mbstring|mysqli|pdo_mysql|SimpleXML|xml|zip)$'

实测回显：

curl
gd
intl
libxml
mbstring
mysqli
PDO
pdo_mysql
SimpleXML
xml
xmlreader
xmlwriter
zip

验证 PHP 与 Apache 版本：

php -v | head -2
apache2ctl -v

实测回显：

PHP 8.2.35 (cli) (built: Oct 21 2026 14:29:22) (NTS)
Copyright (c) The PHP Group
Server version: Apache/2.4.52 (Ubuntu)
Server built:   2026-10-08T19:59:46

⚠️ 排障实录：若跳过 PPA 直接 apt install php，装到的是 8.1 系（apt 源内无 8.2 候选），运行时会出现依赖类不兼容问题且没有清晰的版本报错（composer.json 中 platform-check 为 false，发行包不做运行时版本拦截）。用 apt-cache policy php8.2 可自查来源——正常应只从 ppa.launchpadcontent.net/ondrej/php 获得 500 优先级候选，实测节选：

php8.2:
  Installed: 8.2.35-1+ubuntu22.04.1+deb.sury.org+1
  Candidate: 8.2.35-1+ubuntu22.04.1+deb.sury.org+1
  Version table:
 *** 8.2.35-1+ubuntu22.04.1+deb.sury.org+1 500
        500 https://ppa.launchpadcontent.net/ondrej/php/ubuntu jammy/main amd64 Packages

4.3 安装 MariaDB 并创建数据库与账号

安装 MariaDB 服务端与客户端：

sudo apt install -y mariadb-server mariadb-client
sudo systemctl enable --now mariadb

systemctl enable --now 同时完成开机自启与立即启动，验证服务状态：

systemctl is-active mariadb
systemctl is-enabled mariadb

实测回显：

active
enabled

Ubuntu 的 MariaDB 默认对 root 启用 unix_socket 认证（本机 root 用户免密直连），为便于应用侧统一使用账号密码，本方案创建专用数据库与业务账号（演示口令 q1w2e3r4，生产请改为强口令）：

sudo mysql -e "CREATE DATABASE easyappointments CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'ea_user'@'localhost' IDENTIFIED BY 'q1w2e3r4';"
sudo mysql -e "GRANT ALL PRIVILEGES ON easyappointments.* TO 'ea_user'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

验证账号可连且库已建：

mysql -uea_user -pq1w2e3r4 -e "SHOW DATABASES LIKE 'easyappointments'; SELECT VERSION();"

实测回显：

+---------------------+
| Database (easyappoi |
+---------------------+
| easyappointments    |
+---------------------+
+---------------------+
| 10.6.23-MariaDB     |
+---------------------+

⚠️ 排障实录：若账号或口令敲错，客户端会给出明确报错（实测把口令改为 wrongpass 的回显）——ERROR 1045 (28000): Access denied for user 'ea_user'@'localhost' (using password: YES)，逐项核对账号、口令、host 即可。

4.4 下载官方发行包并部署

从 GitHub Releases 下载 1.6.1 发行包，校验后解压到 /var/www/easyappointments：

cd /tmp
wget https://github.com/alextselegidis/easyappointments/releases/download/v1.6.1/easyappointments-1.6.1.zip
sha256sum easyappointments-1.6.1.zip

实测回显（哈希应与官方发布件一致）：

1671014c371519fa26e0a0a0dbdaa31047f5dda3156329faaea0662f095042f2  easyappointments-1.6.1.zip

解压并落位：

sudo mkdir -p /var/www/easyappointments
sudo unzip -q easyappointments-1.6.1.zip -d /var/www/easyappointments
sudo chown -R www-data:www-data /var/www/easyappointments
ls /var/www/easyappointments

实测回显（目录清单）：

CHANGELOG.md
LICENSE
README.md
application
assets
composer.json
config-sample.php
config.php
index.php
storage
vendor
system

💡 说明：1.6.1 发行包已按官方 CHANGELOG 裁剪了样式源码与依赖开发文件，实测 zip 仅 7232857 字节（约 6.9 MB）；config.php 若解压后不存在（部分发布件只带 config-sample.php），按下一节从模板复制。storage/ 是运行期唯一需要写权限的目录（日志、会话、上传、缓存），上面已随整目录交给 www-data。

4.5 编写 config.php

复制模板并修改四个关键项：BASE_URL（对外访问地址，不带尾斜杠）、DB_HOST、DB_NAME、DB_USERNAME/DB_PASSWORD：

cd /var/www/easyappointments
sudo cp config-sample.php config.php
sudo nano config.php

本环境实测写入后的有效内容（去掉注释后的关键行）：

class Config
{
    const BASE_URL = 'http://192.168.146.128';
    const LANGUAGE = 'english';
    const DEBUG_MODE = false;

    const DB_HOST = 'localhost';
    const DB_NAME = 'easyappointments';
    const DB_USERNAME = 'ea_user';
    const DB_PASSWORD = 'q1w2e3r4';
}

逐项说明：BASE_URL 决定邮件链接、资源引用与预约页对外地址，必须与实际访问地址完全一致（含端口，如带 8443 则写全）；LANGUAGE 支持包内 42 种语言（如简体中文写 'chinese'）；DEBUG_MODE 生产必须 false，排障时可临时置 true 让页面直接显示错误栈；DB_HOST 同机部署用 localhost，独立数据库服务器填其 IP。

4.6 配置 Apache 站点

创建专用站点配置（DocumentRoot 指向应用目录，允许 .htaccess 覆盖）：

sudo tee /etc/apache2/sites-available/easyappointments.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerName ea.example.local
    DocumentRoot /var/www/easyappointments

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

    ErrorLog ${APACHE_LOG_DIR}/easyappointments-error.log
    CustomLog ${APACHE_LOG_DIR}/easyappointments-access.log combined
</VirtualHost>
EOF
sudo a2dissite 000-default
sudo a2ensite easyappointments
sudo apache2ctl configtest
sudo systemctl reload apache2

apache2ctl configtest 实测回显：

Syntax OK

启用 Apache 并确认自启状态：

sudo systemctl enable --now apache2
systemctl is-active apache2 && systemctl is-enabled apache2

实测回显：

active
enabled

💡 说明：AllowOverride All 允许应用目录内的 .htaccess 生效；-Indexes 关闭目录浏览；若服务器还需 HTTPS，可在该 vhost 基础上用 certbot 补 443 配置，BASE_URL 同步改为 https 地址。

4.7 运行安装向导

浏览器打开安装向导（URL 固定）：

http://192.168.146.128/index.php/installation/setup

向导依次完成：数据库连通性校验（读取 config.php 中的 DB_* 值）→ 业务表导入 → 管理员账号表单（姓名、用户名、密码、邮箱）→ 公司信息（名称、地址、默认时区等）→ 提交完成并跳转登录页。

安装完成后，向导自动失效（防止重装攻击），重访同一 URL 实测返回 404：

curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128/index.php/installation/setup

实测回显：

404

4.8 安装验证

验证 1：数据库层——确认业务表已导入、迁移版本为最新：

mysql -uea_user -pq1w2e3r4 easyappointments -e "SHOW TABLES;"
mysql -uea_user -pq1w2e3r4 easyappointments -N -e "SELECT version FROM ea_migrations;"

实测回显（表清单，ea_ 前缀共 14 张）：

ea_appointments
ea_blocked_periods
ea_consents
ea_migrations
ea_roles
ea_secretaries_providers
ea_service_categories
ea_services
ea_services_providers
ea_settings
ea_user_settings
ea_users
ea_webhooks
ea_working_plan_exceptions
69

验证 2：默认账号——向导完成后系统自带演示账号，可在库内核验：

mysql -uea_user -pq1w2e3r4 easyappointments -e "SELECT id,first_name,last_name,email,id_roles FROM ea_users; SELECT id_users,username FROM ea_user_settings;"

实测回显：

1   John   Doe   john@example.org   1
2   Jane   Doe   jane@example.org   2
3   James  Doe   james@example.org  3
1   administrator
2   janedoe

💡 说明：角色 id 对应关系见 ea_roles 表——1=Administrator、2=Provider、3=Customer。演示账号口令为安装向导中自设值，首次登录后应在后台立即改密。

验证 3：登录页与 API：

curl -s http://192.168.146.128/index.php/login | grep -o '<title>[^<]*</title>'
curl -s -u 'administrator:<向导中设置的口令>' http://192.168.146.128/index.php/api/v1/services | head -c 200

实测回显（本环境向导口令为 administrator，仅演示环境如此）：

<title>Login | Easy!Appointments</title>
[{"id":1,"name":"Service","duration":30,"price":0,"currency":"","description":null,"location":null,"slotInterval":15,"attendantsNumber":1,"isPrivate":false,"serviceCategoryId":null}]

验证 4：日志落盘——storage/logs 应出现当日日志文件且属主为 www-data：

ls -la /var/www/easyappointments/storage/logs/ | tail -2

实测回显：

-rw-r--r-- 1 www-data www-data    13 Oct 16 15:45 .htaccess
-rw-r--r-- 1 www-data www-data  5475 Oct 23 01:19 log-2026-10-23.php

至此方案 A 安装完成：预约页 http://192.168.146.128/，后台登录 http://192.168.146.128/index.php/login。

五、方案 B：官方 Docker 镜像安装（备用）

5.1 方案说明

官方同步发布 Docker 镜像 alextselegidis/easyappointments:1.6.1（Docker Hub 拉取量约 140k，2026-10-23 溯源），镜像入口脚本会按环境变量自动生成 config.php 与邮件配置，适合已用容器化运维、不想在宿主机装 PHP 的场景。该方案需要一台装有 Docker Engine 的 Ubuntu 22.04 主机（安装 Docker 的步骤见 Docker 官方文档，此处不展开），数据库单独跑一个 MariaDB 容器。

5.2 快速启动

docker network create ea-net

docker run -d --name ea-mariadb --network ea-net \
  -e MARIADB_ROOT_PASSWORD=q1w2e3r4 \
  -e MARIADB_DATABASE=easyappointments \
  -e MARIADB_USER=ea_user \
  -e MARIADB_PASSWORD=q1w2e3r4 \
  mariadb:10.11

docker run -d --name ea-app --network ea-net \
  -p 8080:80 \
  -e BASE_URL="http://192.168.146.128:8080" \
  -e DEBUG_MODE=FALSE \
  -e DB_HOST=ea-mariadb \
  -e DB_NAME=easyappointments \
  -e DB_USERNAME=ea_user \
  -e DB_PASSWORD=q1w2e3r4 \
  alextselegidis/easyappointments:1.6.1

启动后浏览器打开 http://192.168.146.128:8080/index.php/installation/setup 走同一套安装向导（Docker 方式下数据库已由环境变量注入，向导只补管理员信息）。数据持久化、环境变量全集与重启恢复闭环的完整实践，见《Easy!Appointments 1.6.1 Docker Compose 部署指南》。

5.3 方案 B 验证

docker exec ea-app php -v | head -1
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8080/

实测回显（官方镜像内为更高版本的 PHP 运行时）：

PHP 8.5.12 (cli) (built: Oct 21 2026 15:49:40) (NTS)
200

六、方案对比与选择建议

选择建议：首次接触本系统、单机自托管、希望对配置与日志有完全掌控 → 方案 A；已有 Docker 基础设施、需要快速起多套演示环境或纳入统一容器编排 → 方案 B。两方案数据库层完全一致，后续可互相迁移（mysqldump 导出导入 + config.php/环境变量同步调整）。

七、配置说明

7.1 配置文件布局

所有安装级参数的逐项实测说明见《Easy!Appointments 1.6.1 配置参数详解》。

7.2 PHP 运行时建议

生产环境建议在 /etc/php/8.2/apache2/php.ini 中核对以下项（本环境实测默认值）：

• date.timezone：默认未设置（注释状态），建议设为业务时区如 Asia/Shanghai，避免日志与预约时间偏移；
• upload_max_filesize / post_max_size：默认 2M/8M，头像或附件需求大时上调；
• memory_limit：默认 128M，本系统常规负载足够，无需调整；
• 修改后 sudo systemctl reload apache2 生效，并用 php -i | grep -E 'date.timezone|memory_limit' 核验。

7.3 邮件通知配置

预约通知依赖邮件发送。手动部署时在 application/config/email.php 中配置（Docker 部署通过 MAIL_* 环境变量自动生成同名文件）：

$config['useragent'] = 'Easy!Appointments';
$config['protocol'] = 'smtp';            // 或 'mail'
$config['smtp_host'] = 'smtp.example.org';
$config['smtp_user'] = 'notify@example.org';
$config['smtp_pass'] = 'q1w2e3r4';
$config['smtp_crypto'] = 'tls';          // 或 'ssl'
$config['smtp_port'] = 587;
$config['from_name'] = 'Example';
$config['from_address'] = 'notify@example.org';

保存后无需重启，下一次发信即生效；投递失败可在 storage/logs 当日日志中检索 SMTP 关键字定位。

八、升级、降级与多版本管理

8.1 升级（以 1.6.0 → 1.6.1 为例）

官方升级路径为「备份 → 换应用文件 → 向导自动迁移数据库」：

1. 备份数据库与两处运行态资产：

mysqldump -uea_user -pq1w2e3r4 easyappointments > /tmp/ea-backup-$(date +%F).sql
sudo tar czf /tmp/ea-storage-$(date +%F).tgz -C /var/www/easyappointments storage config.php

2. 下载新版 zip 并解压覆盖应用文件（保留 config.php 与 storage/，不要被新版模板覆盖）；
3. 浏览器打开一次应用首页，若数据库结构需要更新，系统会提示执行更新，向导自动跑迁移；
4. 验证迁移版本号已推进、功能可用：

mysql -uea_user -pq1w2e3r4 easyappointments -N -e "SELECT version FROM ea_migrations;"

实测回显（1.6.1 安装后）：

69

8.2 降级与回滚

若升级后异常：先恢复数据库 mysql -uea_user -pq1w2e3r4 easyappointments < /tmp/ea-backup-<日期>.sql，再用旧版 zip 覆盖应用文件（同样保留 config.php 与 storage/）。注意数据库迁移不可逆——回滚到旧版本时必须连带回滚数据库备份，不能只换文件。

8.3 多版本并存

多版本并存用于灰度或对照测试：把新旧版本分别解压到 /var/www/easyappointments-1.6.0 与 /var/www/easyappointments-1.6.1，各自建立 Apache vhost（不同 ServerName 或端口）与独立数据库，BASE_URL 分别指向各自地址。两套系统互不影响，验证完毕后按第十章卸载流程删旧版即可。

九、常见问题（FAQ）

Q1：安装向导提示数据库连接失败怎么办？ 先在命令行复现连接：mysql -uea_user -pq1w2e3r4 -h localhost。常见报错与对策——ERROR 1045 (28000): Access denied for user 'ea_user'@'localhost' (using password: YES)（账号/口令错，重新执行 4.3 节授权语句）；ERROR 2002（服务未起，systemctl start mariadb）；连接通但向导仍失败时核对 config.php 中 DB_NAME 是否拼写一致。

Q2：页面能开但访问 /api/v1/... 这类短路径返回 404？ 实测本系统发行包根目录不带 .htaccess，URL 重写规则未随包提供，短路径默认不可用（实测 curl /api/v1/services 返回 404）。所有入口统一走 index.php 前缀（如 /index.php/api/v1/services、/index.php/login），这是官方预期用法；如坚持短路径需自行在 Apache vhost 中补充重写规则。

Q3：MariaDB root 登录报「Access denied for user 'root'@'localhost'」？ Ubuntu 的 MariaDB root 默认走 unix_socket 插件，仅限本机 root 系统用户免密使用；用 sudo mysql 进入即可。若要用口令登录 root，可在 sudo mysql 内执行 ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('q1w2e3r4'); FLUSH PRIVILEGES;，随后 SELECT user,host,plugin FROM mysql.user WHERE user='root'; 应显示 plugin 列为 mysql_native_password（实测回显：root localhost mysql_native_password）。

Q4：预约页能打开但中文显示异常或邮件时间不对？ 语言在 config.php 的 LANGUAGE 常量（简体中文写 'chinese'，繁体写 'traditional-chinese'，共 42 种可选）；时区在向导的公司设置与各账号设置里分别控制，PHP 层建议同步设置 php.ini 的 date.timezone。三处一致后刷新页面生效。

Q5：忘记管理员密码怎么办？ 让另一管理员在后台重置；唯一管理员丢失时，可请求登录页的「忘记密码」走邮件重置（需邮件配置可用），或在数据库中用 PHP 为对应用户重新生成口令哈希后更新 ea_user_settings.password 字段（口令以 bcrypt cost 12 存储，勿手工写入明文）。

十、卸载与清理

完全移除本系统按「应用文件 → 数据库 → 账号 → 依赖服务」顺序执行：

1. 删除应用目录与 Apache 站点：

sudo a2dissite easyappointments
sudo rm -f /etc/apache2/sites-available/easyappointments.conf
sudo systemctl reload apache2
sudo rm -rf /var/www/easyappointments

2. 删除数据库与业务账号：

sudo mysql -e "DROP DATABASE IF EXISTS easyappointments;"
sudo mysql -e "DROP USER IF EXISTS 'ea_user'@'localhost';"

3. 若服务器不再承载其他 PHP 站点，可一并移除运行时（保留不影响系统）：

sudo apt purge -y 'php8.2*' libapache2-mod-php8.2
sudo apt autoremove -y

4. 验证清理结果：

curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128/
mysql -uea_user -pq1w2e3r4 -e 'SELECT 1;' 2>&1 | tail -1

实测回显（卸载后访问应失败、账号应不存在）：

000
ERROR 1045 (28000): Access denied for user 'ea_user'@'localhost' (using password: YES)

⚠️ 注意：DROP DATABASE 不可逆，卸载前如需保留预约数据，务必先按 8.1 节第 1 步导出 SQL 备份。

十一、参考链接

1. 官方安装文档：https://easyappointments.org/docs
2. GitHub Releases（1.6.1 发行包下载）：https://github.com/alextselegidis/easyappointments/releases
3. 官方 README（Requirements 章节）：https://github.com/alextselegidis/easyappointments#installation
4. ondrej/php PPA：https://launchpad.net/~ondrej/+archive/ubuntu/php
5. 站内延伸：《Easy!Appointments 1.6.1 Docker Compose 部署指南》《Easy!Appointments 1.6.1 配置参数详解》《Easy!Appointments 1.6.1 API 使用详解》