Live Helper Chat 4.97v 配置参数详解

目标：讲清 Live Helper Chat 4.97v 的三层配置体系——文件主配置 settings/settings.ini.php、缓存配置 cache/cacheconfig/、数据库运行时配置 lh_chat_config，逐项说明主配置每个小节的关键参数、默认值与取值影响，并给出安装后默认值差异的实测对照。文中默认值与结构均核对自 4.97v 源码（settings.ini.default.php），安装后的实际值取自一次全新安装的实机（2026-10-26）。

一、配置体系总览

LHC 的配置分三层，修改入口和生效方式各不相同：

先在后台找，再到文件里找：日常运维中绝大多数行为开关（聊天自动关闭、审计、部门规则等）都在后台 System configuration 下，落库为 lh_chat_config 的 identifier-value 对。文件主配置管的是"安装级"参数——数据库怎么连、哪些扩展启用、URL 形态等。实测 lh_chat_config 里已有大量条目：

SELECT identifier FROM lh_chat_config LIMIT 12;

identifier
accept_chat_link_timeout
accept_tos_link
activity_timeout
activity_track_all
allow_reopen_closed
application_name
assign_workflow_timeout
audit_cleanup_last
audit_configuration
autoclose_abandon_pending
autoclose_activity_timeout
autoclose_timeout

主配置文件在安装前是模板 settings/settings.ini.default.php（默认值来源），安装时向导读取它并生成 settings/settings.ini.php。因此改默认值模板只影响后续新安装，已有实例必须改 settings.ini.php 本身。

二、site 节：站点行为

settings → site 数组，主配置的核心。按功能分组说明（默认值摘自 4.97v settings.ini.default.php）：

2.1 身份与地址

2.2 安装状态与安全

2.3 运行开关

2.4 语言与扩展

site_access_options 节按语言入口给出各自配置（locale、content_language、dir_language=rtl/ltr、theme、default_url），结构统一，按需调整即可。

三、db 节：数据库连接

安装向导第二步填的表单就写进这一节。默认值全部取自环境变量（留空则安装时手工填）：

'db' => array (
    'host' => getenv('LHC_DB_HOST') ?: '',
    'user' => getenv('LHC_DB_USERNAME') ?: '',
    'password' => getenv('LHC_DB_PASSWORD') ?: '',
    'database' => getenv('LHC_DB_DATABASE') ?: '',
    'port' => getenv('LHC_DB_PORT') ?: 3306,
    'use_slaves' => false,
    'tz' => '',              // 会话时区偏移，如 '+02:00'
    'db_slaves' => array (   // 从库数组，use_slaves=true 时生效
        0 => array ( 'host' => '', 'user' => '', 'port' => 3306,
                     'password' => '', 'database' => '' ),
    ),
),

一次全新安装后的实测值（向导填入 127.0.0.1:3306 的场景）：

'host' => '127.0.0.1',
'user' => 'lhcuser',
'password' => 'q1w2e3r4',
'database' => 'lhc',
'port' => 3306,

四、缓存与会话：redis / memecache / cacheEngine 节

三个节点管的对象不同，容易混淆：

4.1 redis 节

'redis' => array (
    'server' => array (
        'host' => 'localhost',
        'port' => 6379,
        'auth' => null,
        'database' => 0
    )
),

这是应用级 Redis（安装了 nodejshelper 等依赖 Redis 的扩展时使用）。注意与队列用的 Redis 地址区分：队列后端地址在扩展自身的配置（lhcphpresque 扩展的 settings.ini.php）里，二者相互独立，host/database 都可以不同。

4.2 memecache 节

'memecache' => array (
    'servers' => array (
        0 => array ( 'host' => '127.0.0.1', 'port' => '11211', 'weight' => 1 ),
    ),
),

Memcached 服务器列表，供依赖 Memcached 的组件使用；不装相关组件可忽略。

4.3 cacheEngine 节

'cacheEngine' => array (
    'cache_global_key' => 'global_cache_key',
    'className' => false,
),

系统对象缓存引擎。className 为 false 时使用默认的文件/按需方式；填入实现类名后（类需提供 get/set/clear 等方法，见 lib/core/lhcore/lhsys.php 的调用约定），系统缓存统一走该引擎，cache_global_key 是全局键前缀。多机部署建议配置共享缓存引擎，避免各机缓存不一致。

4.4 会话存储

会话的存储位置不在 settings.ini.php 里，而由 PHP 运行环境决定：默认落文件，需要 Redis 会话时通过 PHP 的 session.save_handler = redis 覆盖配置指定（官方部署形态通过 php-fpm 附加配置实现，实测会话键 PHPREDIS_SESSION:<id> 出现在 Redis db0）。同一 Redis 实例的 db0 做会话、db1 做队列，是官方编排的既定分工，排查会话问题时先确认连的是不是同一个实例。

五、webhooks 节与队列 worker

'webhooks' => array(
    'enabled' => false,
    'worker' => 'http',
    'single_event' => false
),

对应的扩展启用（两处要一致，缺一会话静默失效）：

'extensions' => array (
    0 => 'lhcphpresque',
),
'webhooks' => array (
    'enabled' => '1',
    'worker' => 'resque',
    ...
),

worker 数量等运行参数在扩展配置与环境变量层（LHC_RESQUE_WORKERS_COUNT、LHC_RESQUE_QUEUE、REDIS_BACKEND、REDIS_BACKEND_DB），见部署篇。实测 worker 正常时 Redis db1 出现 resque:workers、resque:stat:processed 等键，可作为队列健康检查手段。

六、chat 节：聊天行为基线

'chat' => array(
    'online_timeout' => 300,
    'back_office_sinterval' => 10,
    'chat_message_sinterval' => 3.5,
    'check_for_operator_msg' => 10,
    'new_chat_sound_enabled' => true,
    'new_message_sound_admin_enabled' => true,
    'new_message_sound_user_enabled' => true,
),

注意：这里只列文件级基线参数。聊天自动关闭时长、超时转移等行为在后台配置（lh_chat_config，如 autoclose_timeout、activity_timeout、accept_chat_link_timeout），两处同名概念不要混改。

七、数据库运行时配置与 REST API 密钥

7.1 lh_chat_config（后台配置落库处）

后台 System configuration 的所有表单都写入 lh_chat_config（identifier + 序列化 value），保存即生效、无需清缓存。常用排查 SQL：

-- 查看某项配置当前值
SELECT identifier, value FROM lh_chat_config WHERE identifier='autoclose_timeout';

邮件 SMTP 是典型例子：发信配置不在文件里，而是后台 System configuration → Mail settings 保存为 lh_chat_config 中的 smtp_data 条目（含 use_smtp、host、port、default_from 等字段，发信类 erLhcoreClassChatMail 直接读取）。"邮件发不出去"的官方答案也是这一条：把发信方式改为 SMTP 并在后台填对服务器信息。

7.2 REST API 密钥

REST API 的调用凭据在后台 System configuration → REST API 里创建，落库为 lh_abstract_rest_api_key 表记录（含 key、允许的模块与用户绑定）。与 2.2 节的 rest_api_limit 配合使用：文件层限制来源 IP（默认拒绝本机直连，防止 SSRF 类滥用），后台层管理密钥本身。实测表存在性：

SHOW TABLES LIKE '%rest%';

Tables_in_lhc (%rest%)
lh_abstract_rest_api_key
lh_abstract_rest_api_key_remote
lh_generic_bot_rest_api
...

八、配置修改的生效规则

主配置（settings.ini.php）与模板编译缓存有强关联，改完必须清缓存，否则改动不生效或新旧混杂：

php cron.php -s site_admin -c cron/util/clear_cache

或直接清空 cache/ 目录（系统自动重建）。清缓存的完整说明与更多 cron 工具见下一篇《Live Helper Chat 4.97v 常用 CLI 命令与工具详解》。

实操顺序建议：

1. 备份 settings/settings.ini.php（唯一手工维护的主配置）；
2. 改 site_address、proxy_mode、extensions 这类高频项时逐项改、逐项验证；
3. 改完执行 clear_cache，再用浏览器复验 URL 形态与功能；
4. installed 与 secrethash 两项永远不要手改。

九、安装前后差异实测对照

同一台实例安装前后的关键差异（模板默认值 → 实测安装后值）：

相关阅读：部署方式与首次安装见《Debian 12 安装 Live Helper Chat 4.97v 指南》与《Docker Compose 部署 Live Helper Chat 4.97v 指南》；配置修改用到的命令行工具详见《Live Helper Chat 4.97v 常用 CLI 命令与工具详解》。