Cypht 2.13 配置参数详解

‍‍​​‌​> 目标：讲透 Cypht 2.13 的配置体系（.env → config/*.php → config_gen.php 重建），按功能域逐项解释 200+ 参数的语义、默认值与改动影响，并给出生产配置模板。参数清单以 v2.13.0 源码 /.env.example、config/app.php 为准，关键行为已在 Ubuntu 22.04 + Cypht 2.13.0 环境实测。

一、环境信息

• 软件版本：Cypht v2.13.0（2026-10-16 发布）
• 运行栈：Ubuntu 22.04.5 LTS + PHP 8.1.2 + Nginx + MariaDB 10.6（源码安装形态；配置体系与部署形态无关）
• 配置载体：应用根目录 .env（由 .env.example 复制而来，2.13.0 共 266 行）
• 生效链路：.env → config/app.php 等用 env('KEY', 默认值) 读取 → scripts/config_gen.php 生成 config/dynamic.php 与 site/ 生产资源 → Web 请求按新配置执行

二、前置条件

• 已完成安装（任一种形态均可：源码见本站《Ubuntu 22.04 安装 Cypht 2.13 指南》，编排部署见本站《Cypht 2.13 Docker Compose 部署指南》）
• 对应用目录有读写权限（源码形态默认 /var/www/cypht）

三、参数查看与修改方式

3.1 查看现有配置

cd /var/www/cypht
grep -vE '^\s*#|^\s*$' .env | head -20   # 查看当前生效的非注释项

3.2 修改并生效（实测流程）

改完 .env 必须重跑配置生成器，否则界面仍是旧配置。实测把 APP_NAME 改为 QuzuoMail、DEFAULT_LANGUAGE 改为 zh-Hans 后：

cd /var/www/cypht
sed -i -e 's/^APP_NAME=.*/APP_NAME=QuzuoMail/' -e 's/^DEFAULT_LANGUAGE=.*/DEFAULT_LANGUAGE=zh-Hans/' .env
php ./scripts/config_gen.php
curl -s http://127.0.0.1/ | grep -oE '<title>[^<]*</title>'

KindEditor assets copied successfully
copying assets directory...
<title>QuzuoMail</title>

页面标题立即变为 QuzuoMail，无需重启 PHP-FPM。改回 Cypht 重跑一次即恢复（实测 <title>Cypht</title>）。

⚠️ 注意：浏览器可能缓存旧的 site.js/site.css，验证界面类改动时请强刷（Ctrl+F5）。若采用编排化部署（见本站《Cypht 2.13 Docker Compose 部署指南》），环境变量在服务启动时才写入 .env，改变量需按该篇第七节重建服务实例。

四、参数总览

.env 参数按功能域分为 9 组，下表给出组内要点，逐项详解见第五章：

五、核心参数分类详解

5.1 基础与调试

5.2 数据库

💡 技术拓展：DB_DRIVER 支持三种数据库——

驱动	特点	适用场景
mysql	生态最熟、官方 compose 默认搭配 MariaDB	生产首选
pgsql	事务与一致性更强	已有 PostgreSQL 基础设施
sqlite	零服务、单文件	个人试用/边缘小部署

本文及官方 compose 均采用 mysql（MariaDB 10），生态与运维资料最全。

5.3 认证与会话

💡 技术拓展：AUTH_TYPE 三种认证后端对比——

后端	账号管理	适用场景
DB	Cypht 自建账号表，CLI 建号	通用默认
IMAP	直接用现有邮箱账号，免开户	给已有邮件系统加 Web 入口
LDAP	对接企业目录（AD/OpenLDAP）	组织统一认证

本文示例与官方 compose 默认均为 DB；企业已有目录服务时优先 LDAP。

5.4 用户数据与目录

5.5 缓存

5.6 安全加固

5.7 第三方集成

5.8 界面与默认设置

💡 说明：DEFAULT_SETTING_* 只决定新用户初始值，用户在自己的「Settings」页可覆盖；管理员改这些值不影响存量用户已保存的偏好。

5.9 模块开关与其他

六、生产配置模板

适用场景：8GB 内存单机、MariaDB 同机、Redis 会话缓存、面向国内用户的生产部署（在 .env.example 基础上的差异项）：

APP_NAME=MyWebmail
ENABLE_DEBUG=false
LOG_LEVEL=WARNING

DB_CONNECTION_TYPE=host
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_NAME=cypht_db
DB_USER=cypht
DB_PASS=q1w2e3r4            # 生产替换为强口令
DB_SSL_VERIFY_SERVER_CERT=true

AUTH_TYPE=DB
SESSION_TYPE=Redis           # 装了 Redis 后用 Redis 会话
USER_CONFIG_TYPE=DB
ADMIN_USERS=admin

ENABLE_REDIS=true
REDIS_SERVER='127.0.0.1'
REDIS_PORT=6379
ENABLE_MEMCACHED=false       # 只保留一种缓存，避免双写困惑

APP_2FA_SECRET=<随机 64 位字符串>
ALLOW_EXTERNAL_IMAGE_SOURCES=false

DEFAULT_LANGUAGE=zh-Hans
DEFAULT_SETTING_TIMEZONE='Asia/Shanghai'
DEFAULT_SETTING_IMAP_PER_PAGE=50

CYPHT_MODULES="core,contacts,local_contacts,feeds,imap,smtp,account,idle_timer,desktop_notifications,calendar,themes,profiles,imap_folders,sievefilters,tags,history,scheduled_sends"

模板取舍说明：会话走 Redis 减库压；模块清单剔除了 developer/nux/gmail_contacts/ldap_contacts/idle_timer 等非必需项；默认中文界面 + 上海时区；改完执行 php ./scripts/config_gen.php 生效。

七、常见问题

Q1：改完 .env 为什么不生效？

九成是漏跑 php ./scripts/config_gen.php（实测重跑后 <title> 立即变化，见 3.2）；剩下一成是浏览器缓存了旧 site.js/site.css，强刷即可。

Q2：日志里一直刷 Redis/Memcached 连接失败？

ENABLE_REDIS/ENABLE_MEMCACHED 在 .env.example 里默认 true，没装对应服务就会反复报错。显式设为 false 或安装对应服务。

Q3：用户开了 2FA 但二维码显示不出？

缺 gd 或 imagick 扩展（composer suggest 段明确标注）。装 php-gd 后重跑 config_gen.php。

Q4：AUTH_TYPE=IMAP 后登录报认证失败？

确认 IMAP_AUTH_SERVER/PORT/TLS 指向真实邮局（如 993 + IMAP_AUTH_TLS=true）；env.example 里的 localhost:143 只是占位值。同时 DB_* 仍需配置——会话与用户设置仍依赖数据库。

Q5：如何确认某参数的最终默认值？

.env 未设置的项以 config/app.php 中 env('KEY', 默认值) 的第二参数为准（如 imap_auth_server 兜底 mail.gandi.net、暴力破解 5 次/900 秒），可直接查源码对应行。

八、参考链接

• 配置项全量样例（官方）：https://github.com/cypht-org/cypht/blob/master/.env.example
• 参数语义源码（官方）：https://github.com/cypht-org/cypht/blob/master/config/app.php
• 官方文档：https://cypht.org/documentation.html