Easy!Appointments 1.6.1 配置参数详解

目标：逐层逐项讲清 Easy!Appointments 1.6.1 的全部配置面——安装级 config.php、框架级 application/config/、邮件 email.php 与数据库运行时设置表，每项给出实测验证方法与生效证据。本文全部命令与回显均在 Ubuntu 22.04 + PHP 8.2.35 + MariaDB 10.6.23、Easy!Appointments 1.6.1 环境实测通过。

一、环境信息

💡 说明：同一套参数在官方 Docker 镜像下由环境变量在启动时生成（生成结果在第 3 章对照给出），配置含义完全一致；Compose 部署的变量清单见《Easy!Appointments 1.6.1 Docker Compose 部署指南》第六章。

二、前置条件

1. 一套已完成安装的 Easy!Appointments 1.6.1（安装流程见《Ubuntu 22.04 安装 Easy!Appointments 1.6.1 指南》）；
2. 服务器上可编辑应用文件（本文示例用 root；生产建议以部署账号操作）；
3. 数据库账号可连（验证配置正确性时需要查询，本文用 ea_user）；
4. 修改 PHP 配置文件无需重启应用即可生效（每次请求重新加载），修改 Apache/php.ini 需 sudo systemctl reload apache2。

三、参数查看与修改方式

3.1 四层配置体系总览

Easy!Appointments 1.6.1 的配置分四层，作用域与持久化方式各不相同：

⚠️ 注意：升级版本时应用文件会被新版覆盖，手工改动框架级文件会丢失，升级前备份（处理办法见《Ubuntu 22.04 安装 Easy!Appointments 1.6.1 指南》第八章）；运行时设置存数据库，随数据备份走，不受升级影响。

3.2 安装级 config.php 实测样例

本环境实测的 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';

    // const GOOGLE_SYNC_FEATURE = false;
    // const GOOGLE_CLIENT_ID = '';
    // const GOOGLE_CLIENT_SECRET = '';
}

官方 Docker 镜像在同一文件生成的等价物（实测于镜像内 /var/www/html/config.php）：

class Config {
    const BASE_URL              = 'http://192.168.146.128:8128';
    const LANGUAGE              = 'english';
    const DEBUG_MODE            = FALSE;
    const DB_HOST               = 'mariadb';
    const DB_NAME               = 'easyappointments';
    const DB_USERNAME           = 'ea_user';
    const DB_PASSWORD           = 'q1w2e3r4';
    const GOOGLE_SYNC_FEATURE   = FALSE;
    const GOOGLE_CLIENT_ID      = '';
    const GOOGLE_CLIENT_SECRET  = '';
}

两层写法除常量名风格外完全等价，逐项含义见第四章。

四、参数总览与核心参数详解

4.1 BASE_URL —— 对外访问地址

含义：系统的对外完整地址（协议 + 主机 + 端口），不含尾斜杠。它决定页面内静态资源引用、邮件中的确认链接、开放图谱元信息与框架级 $config['base_url'] 推导。

实测证据：预约页源码中的 og:url 元信息直接反映该值（实测）：

<meta property="og:url" content="http://192.168.146.128:8128/">

改错的影响：若 BASE_URL 与实际访问地址不一致，会出现样式丢失（资源 404）、预约确认邮件链接指向错误地址。修改后浏览器需强刷；Docker 部署需重建容器（docker compose up -d --force-recreate easyappointments）让入口脚本重新生成。

取值规则：反代 HTTPS 时写 https://域名；非 80/443 端口必须带上端口；本地测试可用 http://localhost。

4.2 LANGUAGE —— 默认界面语言

含义：系统默认界面语言，取值为 application/language/ 目录下的语言目录名（1.6.1 实测共 42 种，含 chinese、traditional-chinese）。

实测验证：把 const LANGUAGE = 'english'; 改为 'chinese'; 后访问预约页：

curl -s http://192.168.146.128/ | grep -o '<title>[^<]*</title>'

实测回显（改后）：

<title>准备预约 Company Name | Easy!Appointments</title>

改回 english 后同命令回显：

<title>Book Appointment With Company Name | Easy!Appointments</title>

逐项说明：语言切换即时生效、无需重启；客户可在预约页自行切换语言（会写入会话）；单账号界面语言可在后台账号设置单独覆盖。

4.3 DEBUG_MODE —— 调试模式

含义：决定框架运行环境。实测源码定位（index.php 第 126 行）：

define('ENVIRONMENT', Config::DEBUG_MODE ? 'development' : 'production');

development 环境下 PHP 错误与异常直接显示在页面上，production 显示友好错误页。

实测验证：访问一个不存在的路由，对比两种模式的响应——

curl -s http://192.168.146.128/index.php/nonexistent-page | grep -o '<title>[^<]*</title>'

DEBUG_MODE=false（生产）实测回显：

<title>404 Page Not Found | Easy!Appointments</title>

DEBUG_MODE=true（开发）实测回显（页面变为带 error 详情的开发态错误输出，不再是友好 404 页）：

error
error
error

取值规则：生产环境必须 false——开发态错误页会泄露路径、堆栈等敏感信息；排障时临时置 true，问题复现后立即改回。

4.4 DB_HOST / DB_NAME / DB_USERNAME / DB_PASSWORD —— 数据库连接

含义：应用连接 MySQL/MariaDB 的四要素。DB_HOST 同机部署填 localhost（走 socket），独立数据库服务器填 IP；Docker 部署填 compose 服务名。

实测验证：凭据错误时应用的报错形态（实测将口令改为 wrongpass 执行连接）：

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

逐项说明：库名默认 easyappointments（安装向导导入 14 张 ea_ 前缀表）；账号只需该库的读写权限（GRANT ALL PRIVILEGES ON easyappointments.*）；修改连接信息后无需重启，下一次数据库访问即用新值——若改错，页面会出现数据库错误，改回即可恢复。

4.5 GOOGLE_SYNC_FEATURE / GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET —— Google 日历同步

含义：启用 Google Calendar 双向同步的全局开关与 OAuth2 应用凭据。默认三行被注释（即不启用）。

使用方式：置 const GOOGLE_SYNC_FEATURE = true; 并填入 Google Cloud Console 创建的 OAuth 客户端 ID/Secret 后，每个提供者可在后台 Settings → Integrations → Google Calendar 绑定自己的日历。凭据也可只在后台界面配置（config.php 值作为兜底）。1.6.1 起 Google 同步与 CalDAV 同步相互独立，任一通道故障不影响另一通道（官方 CHANGELOG 1.6.1）。全部离线内网环境保持默认关闭即可。

4.6 框架级 application/config/config.php 关键项

该文件为 CodeIgniter 框架配置，1.6.1 对若干安全相关项做了动态化处理。实测关键行与默认值：

站点地址自动推导（第 33 行）——框架级 base_url 由请求头自动推导，CLI 场景回落到 Config::BASE_URL，因此框架层无需手改：

$config['base_url'] = rtrim(!is_cli() ? $protocol . $domain . $request_uri : Config::BASE_URL, '/');

会话（Session）——实测默认值：

$config['sess_driver'] = 'files';
$config['sess_cookie_name'] = 'ea_session';
$config['sess_expiration'] = 604800; // 1 week
$config['sess_save_path'] = __DIR__ . '/../../storage/sessions';

逐项说明：会话以文件形式存储在 storage/sessions（实测该目录下可见 ea_session* 文件、属主 www-data）；登录态保持 1 周（604800 秒）；需收紧会话时长时改 sess_expiration 并清空 storage/sessions。

CSRF 防护——实测默认开启：

$config['csrf_protection'] = true;
$config['csrf_token_name'] = 'csrf_token';
$config['csrf_cookie_name'] = 'csrf_cookie';
$config['csrf_expire'] = 7200;
$config['csrf_exclude_uris'] = ['api/v1/.*', 'booking/.*', 'booking_cancellation/.*', 'booking_confirmation/.*', 'localization/.*'];

逐项说明：表单请求携带 csrf_token（浏览器侧同时下发 csrf_cookie）；令牌有效期 7200 秒；REST API 与公开预约页等无状态入口列在豁免清单（它们各自有 Basic/Bearer 认证或哈希签名保护）——对接 API 报 CSRF 错误时先核对 URL 是否命中豁免规则。

Cookie 安全属性——1.6.1 实测（config.php 中段）：

if (defined('COOKIE_SAMESITE')) {
    $config['cookie_samesite'] = COOKIE_SAMESITE;
}
$config['cookie_secure'] =
    strpos($config['base_url'], 'https') !== false || strcasecmp($config['cookie_samesite'], 'None') === 0;

逐项说明：可在根 config.php 里定义 COOKIE_SAMESITE 常量覆盖 Cookie 的 SameSite 策略（1.6.1 CHANGELOG 明确该策略由框架层管理）；一旦 BASE_URL 为 https 或 SameSite=None，cookie_secure 自动为 true——「SameSite=None 必须搭配 Secure」由系统自动保证。

加密密钥——实测默认逻辑（framework 源码原样）：未在根 config.php 定义 ENCRYPTION_KEY 时，自动用「应用路径 + 数据库口令 + 主机名」派生一个稳定密钥，功能开箱可用；对密钥有合规要求时在根 config.php 定义 ENCRYPTION_KEY 常量即可显式指定：

$config['encryption_key'] =
    defined('ENCRYPTION_KEY') && !empty(ENCRYPTION_KEY)
        ? ENCRYPTION_KEY
        : hash('sha256', APPPATH . (defined('DB_PASSWORD') ? DB_PASSWORD : '') . php_uname(), true);

4.7 routes.php 中的 CORS 允许来源

1.6.1 把 CORS 头处理移到 application/config/routes.php（CHANGELOG 1.6.1：preflight 请求必须在进入控制器前被响应）。实测默认值：

$allowed_origins = [];

if (defined('CORS_ALLOWED_ORIGINS')) {
    $allowed_origins = array_filter(array_map('trim', explode(',', CORS_ALLOWED_ORIGINS)));
}

逐项说明：默认空数组 = 拒绝一切跨域请求（同源不受限）；需要让前端页面（如把预约页嵌入自家门户域）跨域调用时，在根 config.php 定义 const CORS_ALLOWED_ORIGINS = 'https://portal.example.org,https://www.example.org';（逗号分隔多域）。不要设成 *——1.6.1 的实现按来源白名单回显，开放通配会放大 CSRF 面。

4.8 email.php —— 邮件发送

含义：通知邮件的发送协议与 SMTP 参数（Docker 部署由 MAIL_* 环境变量生成，实测生成的文件与下述键一一对应）：

$config['useragent'] = 'Easy!Appointments';
$config['protocol'] = 'smtp';          // 或 'mail'
$config['mailtype'] = 'html';          // 或 'text'
$config['smtp_debug'] = '0';           // 或 '1'
$config['smtp_auth'] = TRUE;           // 匿名中继置 FALSE
$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';
$config['reply_to'] = '';

逐项说明：protocol 选 smtp 走外部邮件服务器（最常用），选 mail 用 PHP mail()（需本机 MTA）；smtp_crypto 与 smtp_port 搭配——tls 配 587（STARTTLS）、ssl 配 465；mailtype=html 让通知邮件呈现排版模板；保存后下次发信生效，失败排查看 storage/logs 当日日志中的 SMTP 会话记录。

4.9 运行时设置（ea_settings 表 / 后台 Settings 页面）

运行时可调参数全部存于数据库 ea_settings 表（后台界面「Settings」分区保存），无需改文件。实测本环境的现值（节选关键项）：

查看与修改：后台 Settings 页面逐区（公司、预约、客户、集成…）图形化操作；命令行查看用 SQL：

mysql -uea_user -pq1w2e3r4 easyappointments -e "SELECT name,value FROM ea_settings WHERE name IN ('company_name','default_timezone','book_advance_timeout');"

实测回显：

company_name    Company Name
default_timezone        UTC
book_advance_timeout    30

⚠️ 注意：建议直接改后台界面而非 UPDATE 语句——部分设置项有关联缓存与校验，界面保存会触发完整处理链。

4.10 google.php —— Google API 客户端

application/config/google.php 定义 Google API 应用名与凭据兜底，普通部署无需改动；启用 Google 同步时的授权流程在后台「Settings → Integrations → Google Calendar」完成，凭据优先取各提供者绑定时的授权数据。

五、生产配置模板

以下为面向「中小机构、2–8 名服务提供者、日预约量数百」场景的推荐配置基线（适用 4GB 内存 / 40GB 磁盘 / 常规 VPS 单机）：

class Config
{
    const BASE_URL = 'https://booking.example.org';   // 必须 https，反代后与外网地址一致
    const LANGUAGE = 'chinese';                        // 中文机构默认中文
    const DEBUG_MODE = false;                          // 生产必 false

    const DB_HOST = 'localhost';
    const DB_NAME = 'easyappointments';
    const DB_USERNAME = 'ea_user';
    const DB_PASSWORD = '<强口令，12 位以上随机串>';
}

配套动作清单（每项含义见第四章对应小节）：

1. 后台 Settings：default_timezone 改 Asia/Shanghai；book_advance_timeout 按业务定（30 分钟基线）；开启 altcha_enabled 与 require_captcha 防机器人抢约；
2. application/config/email.php：protocol=smtp + tls/587，from_address 用业务域名邮箱；
3. 根 config.php 追加 const CORS_ALLOWED_ORIGINS = '';（保持默认拒绝，仅白名单需要嵌入的域）；
4. Apache/php.ini：date.timezone=Asia/Shanghai 与后台时区一致；session 时长按需调小（默认 7 天）；
5. 定期备份：mysqldump + storage/ 目录（含 uploads 上传文件）。

六、常见问题（FAQ）

Q1：改了 config.php 没有任何变化？ 三步排查：确认编辑的是部署目录下的 config.php（多目录部署易改错副本）；确认 PHP 进程用户对文件有读权限；用 php -l config.php 检查语法（实测语法错误会导致整站 500）。语法正确仍不生效时，确认没有 OPcache 缓存——php -m | grep opcache 为有则 systemctl reload apache2 清一次。

Q2：BASE_URL 带不带尾斜杠有区别吗？ 规范写法不带尾斜杠（官方样例即如此）；带斜杠会导致拼接出的资源 URL 出现双斜杠，多数浏览器可容忍但邮件链接可能异常。已填错的改正后强刷浏览器。

Q3：DEBUG_MODE 开着安全吗？ 不安全，仅用于临时排障。开发态会向访客输出错误堆栈、文件路径与数据库错误详情。排障完成立即置回 false（实测回显对比见 4.3 节）。

Q4：改了 ea_settings 里的 default_timezone，已有预约时间变了？ 不会。预约时间按创建时的时区规则存储，改默认时区只影响「新录入」与展示换算。跨时区迁移部署时，先核对既有预约展示是否正确再切换。

Q5：Docker 部署能手工改容器里的 config.php 吗？ 能改，但下次容器重建（compose up -d --force-recreate、镜像升级）会被入口脚本按环境变量覆盖重写。Docker 形态下请以环境变量为准（变量清单见《Easy!Appointments 1.6.1 Docker Compose 部署指南》第六章）；确有环境变量覆盖不了的参数，用挂载文件方式固定（同章第七节）。

Q6：语言包里有的词条显示英文？ 42 种语言为社区贡献，覆盖度不完全一致；缺失词条自动回落 english 显示。可在后台确认 LANGUAGE 值拼写正确（目录名，全小写，如 chinese、traditional-chinese）。

七、参考链接

1. 官方配置文档：https://easyappointments.org/docs
2. config-sample.php 模板（GitHub 源码）：https://github.com/alextselegidis/easyappointments/blob/master/config-sample.php
3. CodeIgniter 3 用户指南（框架配置继承自其规范）：https://codeigniter.com/userguide3/
4. 1.6.1 CHANGELOG（CORS/SameSite 调整出处）：https://github.com/alextselegidis/easyappointments/blob/master/CHANGELOG.md
5. 站内延伸：《Ubuntu 22.04 安装 Easy!Appointments 1.6.1 指南》《Easy!Appointments 1.6.1 Docker Compose 部署指南》《Easy!Appointments 1.6.1 API 使用详解》