FreeScout 1.8.248 配置参数详解
FreeScout 1.8.248 配置参数体系实测：.env 主参数、config 缓存生效机制、options 表与管理界面四层结构，APP_URL/APP_TIMEZONE/SESSION_SECURE_COOKIE/APP_DOWNLOAD_ATTACHMENTS_VIA 等核心参数逐一改→生效→验证，含 419 会话事故与附件三层上限实测。
FreeScout 1.8.248 配置参数详解
目标：系统讲解 FreeScout 1.8.248 的配置参数体系——
.env主参数、PHP-FPM 上传链路、Nginx 附件上限与数据库内应用设置四个层次的查看方法、修改方法与「改 → 生效 → 验证」闭环，每个核心参数均配有在 Ubuntu 22.04 实测环境（安装流程见 《Ubuntu 22.04 安装 FreeScout 1.8.248 指南》）中的真实改动与验证回显。
一、环境信息
本章记录参数实测所用的环境与基线状态，参数效果均以此环境验证。
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- FreeScout：1.8.248（git tag 检出，安装路径
/var/www/html，Laravel Framework 5.5.40 定制 fork） - PHP：8.3.35（php8.3-fpm + php8.3-cli，ppa:ondrej/php）
- Nginx：1.18.0 (Ubuntu)；MariaDB：10.6.23
- 访问地址：
http://192.168.146.128:8155（.env中APP_URL同值） - 管理员账号：
admin@freescout.local/q1w2e3r4
实测开始时的参数基线（php artisan tinker 读取 config 取证）：
TZ=UTC DBG=false SEC=false VIA=php CBG=false PXY='' HDR=''
（对应：时区 UTC、调试关、会话安全 Cookie 关、附件下载走 php、文件夹计数后台模式关、无代理、无自定义邮件头。）
二、前置条件
本章说明阅读与动手实验前需要具备的环境与权限。
- 已按安装指南完成 FreeScout 安装并能登录（见本专栏安装篇）；组件定位与架构背景见 《FreeScout 1.8.248 介绍与选型指南》。
- 拥有应用目录写权限的运行身份（本文统一用
www-data执行 artisan 命令）。 - 明确两条生效纪律（官方
.env.example头部原话）：- 每次修改
.env后必须执行php artisan freescout:clear-cache，否则改动不生效； - 若走 Web 安装器安装，不要手工创建
.env——.env存在时 Web 安装器拒绝运行。
- 每次修改
三、参数查看与修改方式
本章讲清 FreeScout 配置的四个层次：.env 文件、config 缓存、数据库 options 表、管理界面系统设置。改哪一层、怎么生效、如何验证，是本章的核心。
3.1 .env 主参数：查看与修改
FreeScout 的核心配置集中在应用根目录的 .env 文件（模板为同目录 .env.example）：
cat /var/www/html/.env
实测当前内容（本次实验修改后的状态，节选）：
# Application URL
APP_URL=http://192.168.146.128:8155
# Comment it to use default timezone from php.ini
APP_TIMEZONE=Asia/Shanghai
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=freescout
DB_USERNAME=freescout
DB_PASSWORD=q1w2e3r4
APP_KEY=base64:dE2AnW6wfIo7vB/r8N0HpaS6ykoL7b6GBh9G0igCnWU=
#APP_DEBUG=true
#SESSION_SECURE_COOKIE=true
#APP_TRUSTED_PROXIES=192.168.1.62
#APP_UPDATE_FOLDER_COUNTERS_IN_BACKGROUND=true
APP_DOWNLOAD_ATTACHMENTS_VIA=nginx
生效机制（重点）：FreeScout 继承 Laravel 的 config 缓存体系——.env 并不被每次请求直接读取，而是被缓存进 bootstrap/cache/config.php。这就是「改了没生效」的第一大原因。实测证据：
ls /var/www/html/bootstrap/cache/
grep -o 'Asia/Shanghai' /var/www/html/bootstrap/cache/config.php | head -1
实测输出：
config.php
packages.php
services.php
Asia/Shanghai
（缓存文件里能看到刚改的时区值——说明 .env 的值只有经 freescout:clear-cache 重建缓存后才会进入运行时配置。）
修改 → 生效的标准三步（每一步都有实测）：
# 第 1 步：改 .env（用编辑器或 sed）
# 第 2 步：重建缓存使改动生效
sudo -u www-data php /var/www/html/artisan freescout:clear-cache
# 第 3 步：读取运行时配置验证
sudo -u www-data php /var/www/html/artisan tinker
第 2 步实测输出：
Configuration cached successfully!
Cleared: JS and CSS builds
Created: /js/builds/vars.js
第 3 步在 tinker 交互符内执行 echo config('app.timezone');（退出输入 exit）即可看到新值，后文各参数的「验证」均采用此方法。
3.2 数据库 options 表：应用内设置
FreeScout 把管理界面（Manage » Settings）保存的运行设置存进数据库 options 表，与 .env 分属两层——UI 设置改完即时生效（写库），.env 改完要清缓存。查看实测：
sudo mysql -e "USE freescout; DESCRIBE options;"
sudo mysql -e "USE freescout; SELECT * FROM options LIMIT 6;"
实测输出（节选）：
Field Type Null Key Default Extra
id int(10) unsigned NO PRI NULL auto_increment
name varchar(191) NO UNI NULL
value longtext NO NULL
id name value
1 fetch_emails_last_run 1792557541
💡 说明：
fetch_emails_last_run记录调度器最近一次抓信时间戳（Unix 秒），由每分钟的 cron 写入——它的持续更新本身就证明 cron 调度链路健康，可作为巡检指标。
3.3 管理界面系统设置
管理员登录后 Manage 菜单内的系统设置（站点名、默认语言、通知、邮箱收发参数等）本质是 3.2 节 options 表的 UI 形态。本文以 .env 参数为主线；邮箱级收发参数（IMAP/SMTP 服务器、端口、加密方式）在「Mailbox » Connection Settings」中逐邮箱配置，不属于全局参数。
四、参数总览
本章汇总 .env.example 模板全部参数与实测默认值，作为速查表。默认值一列来自 3.1 节基线实测与 config/app.php 源码中的 env() 第二参数（查询版本 1.8.248）。
| 参数 | 实测默认值 | 作用 | 生效方式 |
|---|---|---|---|
| APP_URL | https://example.com（模板）；本环境 http://192.168.146.128:8155 | 站点对外地址，生成外链与主机校验基准 | clear-cache |
| APP_KEY | 空（模板）；安装时 key:generate 生成 | 加密会话/Cookie/密码重置令牌的 32 字节密钥 | clear-cache |
| APP_DEBUG | false | 调试模式，控制错误页详细信息 | clear-cache |
| APP_TIMEZONE | PHP php.ini 时区（本环境 UTC） | 应用展示与日期计算时区 | clear-cache |
| SESSION_SECURE_COOKIE | false | 会话 Cookie 加 Secure 标记（仅 HTTPS 发送） | clear-cache |
| APP_TRUSTED_HOSTS | 空（仅允许 APP_URL 主机） | 主机名白名单，多域名访问需配置 | clear-cache |
| APP_TRUSTED_PROXIES | 空 | 信任的反向代理 IP 列表，还原真实客户端 IP | clear-cache |
| APP_REMOTE_HOST_WHITE_LIST | 空 | 出站抓取的远程主机白名单（模块下载场景） | clear-cache |
| APP_PROXY | 空 | 出站 HTTP 代理（模块市场/外部资源） | clear-cache |
| APP_CUSTOM_MAIL_HEADERS | 空 | 所有出站邮件附加自定义头 | clear-cache |
| APP_UPDATE_FOLDER_COUNTERS_IN_BACKGROUND | false | 文件夹计数改后台异步计算（大库性能项） | clear-cache |
| APP_DOWNLOAD_ATTACHMENTS_VIA | php | 附件下载方式：php 或 nginx（X-Accel） | clear-cache |
| APP_CUSTOMER_ALLOWED_EXTENSIONS / MIME_TYPES | 空 | 客户头像允许的扩展名/MIME | clear-cache |
| APP_CUSTOMER_PHOTO_SIZE | 64 | 客户头像尺寸(px) | clear-cache |
| APP_CUSTOM_NUMBER | false | 自定义工单编号格式开关 | clear-cache |
| APP_KEY_FILE | 空 | 从文件读取 APP_KEY（便于密钥文件挂载部署） | clear-cache |
| DB_CONNECTION / DB_HOST / DB_PORT | mysql / localhost / 3306 | 数据库连接四项 | clear-cache |
| DB_DATABASE / DB_USERNAME / DB_PASSWORD | 空 | 同上（密码最长 50 字符） | clear-cache |
关键差异解读：.env 层管「应用级全局行为」，options 表管「界面里点出来的设置」，PHP/Nginx 层管「请求体与附件的物理上限」——附件上传上限要三层一起看（见 5.5 节实测），这是 FreeScout 配置里最容易踩坑的交叉区。
五、核心参数分类详解
本章对生产中最常改动的参数逐个做「参数说明 → 改动命令 → 实测验证」闭环。所有回显均来自第一章环境。
5.1 站点地址与主机信任（APP_URL / APP_TRUSTED_HOSTS / APP_TRUSTED_PROXIES）
APP_URL 决定应用生成的所有外链（邮件里的链接、跳转、重定向目标），也是 TrustHosts 主机校验的默认唯一合法主机。实测：根路径 302 跳转目标与 APP_URL 完全一致——
curl -s -o /dev/null -w 'HTTP %{http_code} -> %{redirect_url}\n' http://192.168.146.128:8155/
实测输出：
HTTP 302 -> http://192.168.146.128:8155/login
改法：直接编辑 .env 的 APP_URL= 行后清缓存。⚠️ 必须写用户浏览器实际访问的协议+地址+端口；改成不一致的值会导致跳转/外链全部指向错误地址。
APP_TRUSTED_HOSTS：当需要多个域名/IP 访问同一实例时配置（逗号分隔）。在安装篇 Q3 已实测：不加白名单时用 localhost 访问得到 403，页面提示原样为：
Untrusted Host: localhost. Add the following to your .env file and clear cache: APP_TRUSTED_HOSTS ='localhost'
APP_TRUSTED_PROXIES：实例置于反向代理之后时，告知应用「哪些 IP 是代理」，才能从 X-Forwarded-For 还原真实客户 IP。映射键为 config/trustedproxy.php 的 proxies 项（不是 app.php）。实测闭环：
# 改 .env（取消注释并赋值）
APP_TRUSTED_PROXIES=192.168.1.62
# 清缓存后验证
sudo -u www-data php /var/www/html/artisan freescout:clear-cache
sudo -u www-data php /var/www/html/artisan tinker
tinker 内执行 echo json_encode(config('trustedproxy.proxies'));，实测输出：
["192.168.1.62"]
回滚（重新注释 + 清缓存）后同命令实测输出：
[""]
💡 技术拓展：反向代理信任列表写法业界常见三种——单个 IP（
10.0.0.1）、逗号列表（10.0.0.1,10.0.0.2）、通配（*信任直连者 /**信任转发链全部）。FreeScout 源码对*/**有专门分支处理（config/trustedproxy.php用正则识别后原样传入，否则按逗号 explode）。本文因代理 IP 固定采用单 IP 写法。
5.2 调试模式（APP_DEBUG）
参数说明：APP_DEBUG=true 后错误页会输出异常堆栈与环境信息，便于排障；默认 false 时只显示友好错误页。官方同时注明：Debugbar（Barryvdh\Debugbar）仅在 APP_DEBUG=true 且手动取消 config/app.php 中对应 ServiceProvider 的注释后才会启用——1.8.248 发行包默认连 debugbar 依赖都未安装（vendor/barryvdh/ 下只有翻译管理器），所以仅开 APP_DEBUG 不会在页面注入调试条。
实测改动与验证：
# .env 中改为 APP_DEBUG=true 后清缓存
sudo -u www-data php /var/www/html/artisan freescout:clear-cache
sudo -u www-data php /var/www/html/artisan tinker
tinker 内执行 echo var_export(config('app.debug'), true);，实测输出：
true
⚠️ 注意：调试模式会把堆栈、配置、环境变量暴露给访问者，排障结束务必改回 false（本文实验后已回滚为注释状态）。
5.3 时区（APP_TIMEZONE）
参数说明：控制应用内时间显示与日期计算，默认取 php.ini 的时区（本环境为 UTC）。中文环境通常改为 Asia/Shanghai。
实测改动与验证（三步完整闭环）：
# 1) .env 中取消注释并赋值
APP_TIMEZONE=Asia/Shanghai
# 2) 清缓存
sudo -u www-data php /var/www/html/artisan freescout:clear-cache
# 3) 验证
sudo -u www-data php /var/www/html/artisan tinker
tinker 内执行 echo config('app.timezone');，实测输出：
Asia/Shanghai
同时 3.1 节的缓存文件 grep -o 'Asia/Shanghai' bootstrap/cache/config.php 命中，证明值已进入运行时配置。
5.4 会话安全 Cookie（SESSION_SECURE_COOKIE）
参数说明：置 true 后会话 Cookie 带 Secure 标记——浏览器只在 HTTPS 连接上回传该 Cookie。官方模板注释原话："If you are using HTTPS, feel free to uncomment this line to improve security"。
实测：HTTP 站点上开启它会发生什么（典型误配事故，完整实录）：
# .env 改 SESSION_SECURE_COOKIE=true → 清缓存后用 curl 重放登录
TOKEN=$(curl -s -c cj.txt http://192.168.146.128:8155/login | grep -oP 'name="_token" value="\K[^"]+' | head -1)
curl -s -b cj.txt -c cj.txt -d "_token=$TOKEN" -d 'email=admin@freescout.local' \
-d 'password=q1w2e3r4' -o /dev/null -w 'HTTP %{http_code}\n' \
http://192.168.146.128:8155/login
实测输出：
HTTP 419
继续带同一会话访问 /，实测输出：
HTTP 302
<title>Redirecting to http://192.168.146.128:8155/login</title>
结论：HTTP 站点开启 SESSION_SECURE_COOKIE=true 会导致登录彻底不可用（419 页面 + 会话丢失循环回登录页）。回滚为注释并清缓存后，同样的登录实测输出：
HTTP 302 -> http://192.168.146.128:8155/home
<title>Dashboard - FreeScout </title>
使用建议：HTTPS 站点开启（安全收益）；纯 HTTP 内网站点保持关闭（可用性优先），或尽快上 HTTPS 后再开启。
5.5 附件上传与下载链路（APP_DOWNLOAD_ATTACHMENTS_VIA + PHP + Nginx 三层）
参数说明：附件链路是 FreeScout 配置的交叉区，涉及三层：
- PHP-FPM
upload_max_filesize/post_max_size（/etc/php/8.3/fpm/php.ini）——单文件与请求体上限； - Nginx
client_max_body_size（站点配置，官方模板 20M）——请求体在 Web 层的上限； APP_DOWNLOAD_ATTACHMENTS_VIA——附件下载方式：默认php（应用读盘转发），可改nginx（X-Accel 让 Nginx 直读附件目录提速，需同时在站点配置放开官方模板中的 internal location 段）。
实测 1：采集 PHP-FPM 当前生效值（临时探针验证 fpm 而非 cli 的配置）：
echo '<?php echo ini_get("upload_max_filesize")."|".ini_get("post_max_size");' \
> /var/www/html/public/ini_probe.php
curl -s http://192.168.146.128:8155/ini_probe.php
实测输出（默认值）：
2M|8M
实测 2：超过 Nginx 上限的请求被 413 拒绝：
dd if=/dev/zero of=/tmp/big25m.bin bs=1M count=25
curl -s -o /dev/null -w 'HTTP %{http_code}\n' \
-F 'file=@/tmp/big25m.bin' http://192.168.146.128:8155/upload
实测输出：
HTTP 413
实测 3：调高 PHP 限制后 Nginx 成为约束点（验证「上限取三层最小值」）：
# php.ini 中 upload_max_filesize=20M、post_max_size=25M 后重启 fpm
sudo systemctl restart php8.3-fpm
curl -s http://192.168.146.128:8155/ini_probe.php # 探针复测
curl -s -o /dev/null -w 'HTTP %{http_code}\n' \
-F 'file=@/tmp/big25m.bin' http://192.168.146.128:8155/upload # 25MB 复测
实测输出（探针值已变，但 25MB 请求仍被 Nginx 拦下）：
20M|25M
HTTP 413
实测 4：APP_DOWNLOAD_ATTACHMENTS_VIA 的生效验证。该参数不在 .env.example 模板中，需手工追加（这是 1.8.248 的一个易漏点）：
echo 'APP_DOWNLOAD_ATTACHMENTS_VIA=nginx' >> /var/www/html/.env
sudo -u www-data php /var/www/html/artisan freescout:clear-cache
sudo -u www-data php /var/www/html/artisan tinker
tinker 内执行 echo config('app.download_attachments_via');，实测输出（改前 php，改后 nginx）：
nginx
⚠️ 注意：改为
nginx后，若站点配置没有配套的location ^~ /storage/app/attachment/ { internal; alias /var/www/html/storage/app/attachment/; }段（官方 Nginx 模板中默认注释），附件下载会 404——两处必须同步改。实验探针文件ini_probe.php用完已删除。
5.6 后台性能参数（APP_UPDATE_FOLDER_COUNTERS_IN_BACKGROUND）
参数说明：FreeScout 会实时统计各文件夹（Folder）的会话计数；工单量大时该统计拖慢页面，置 true 后改为后台异步计算。官方模板注释："Uncomment if you have many folders and you are experiencing performance issues"。
实测改动与验证：
# .env：APP_UPDATE_FOLDER_COUNTERS_IN_BACKGROUND=true → 清缓存 → tinker
echo var_export(config('app.update_folder_counters_in_background'), true);
实测输出：
true
（回滚后同命令输出 false。映射键为 config/app.php 的 update_folder_counters_in_background，默认 false。）
5.7 出站代理与自定义邮件头（APP_PROXY / APP_CUSTOM_MAIL_HEADERS）
APP_PROXY：应用所有出站 CURL 请求走该代理，主要用于访问不到 api.freescout.net（官方模块市场）的网络环境。实测（赋值 http://192.168.1.62:7897 后清缓存）：
PXY='http://192.168.1.62:7897'
（tinker echo var_export(config('app.proxy'), true);；默认值为空字符串 ''。）
APP_CUSTOM_MAIL_HEADERS：给全部出站邮件统一附加自定义头，格式为分号分隔的 头名:值 对，如模板示例 IsTransactional:True;X-Custom-Header:value。默认实测为空 ''。两个参数均为运营增强项，不配不影响核心功能。
5.8 数据库连接（DB_*）
参数说明：DB_CONNECTION（mysql/pgsql）、DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD（最长 50 字符）。验证参数是否写对，最直接的办法是用同凭据连库：
mysql -ufreescout -pq1w2e3r4 -h localhost -e "SELECT 1;" freescout
实测输出：
1
改库连接参数后除清缓存外，建议顺带 php artisan migrate:status 确认迁移表可达（正常输出一串已执行的迁移行）。
5.9 应用密钥（APP_KEY）
参数说明：32 字节 AES 密钥（base64: 前缀），加密会话、Cookie 与密码重置令牌。由 php artisan key:generate 生成，实测输出：
Application key [base64:dE2AnW6wfIo7vB/r8N0HpaS6ykoL7b6GBh9G0igCnWU=] set successfully.
⚠️ 注意：生产环境换 APP_KEY 会让所有现有会话与「记住我」Cookie 失效（全员重新登录），但不清工单数据；不要复制别人泄露的 key，也不要轻易轮换。另有
APP_KEY_FILE参数可从文件读 key，便于编排工具挂载密钥文件。
六、生产配置模板
本章给出面向「2C4G 云主机、50 坐席以内、日均几百封邮件」小团队的推荐 .env 生产模板（配套 Ubuntu 22.04 + Nginx + PHP 8.3-FPM + MariaDB 10.6），逐项含义见第五章：
APP_URL=https://helpdesk.example.com
APP_KEY=<key:generate 生成的 base64 密钥>
# 生产关闭调试
#APP_DEBUG=true
# HTTPS 站点开启
SESSION_SECURE_COOKIE=true
# 时区
APP_TIMEZONE=Asia/Shanghai
# 反代后部署时填代理 IP；直连保持注释
#APP_TRUSTED_PROXIES=10.0.0.1
# 多域名访问时填白名单
#APP_TRUSTED_HOSTS="helpdesk.example.com,helpdesk.internal"
# 大库开启后台计数
#APP_UPDATE_FOLDER_COUNTERS_IN_BACKGROUND=true
# 已按官方模板放开 Nginx internal location 后开启
APP_DOWNLOAD_ATTACHMENTS_VIA=nginx
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=freescout
DB_USERNAME=freescout
DB_PASSWORD=<强密码>
# 模块市场不可达的内网环境配置出站代理
#APP_PROXY=http://192.168.1.62:7897
配套三层上限推荐值（小团队附件上限 20M）：php.ini upload_max_filesize=20M、post_max_size=25M；Nginx client_max_body_size 20M——三层取最小值即为实际生效上限（5.5 节已实测验证该约束关系）。
💡 说明：模板中尖括号占位处为密钥/密码——真实部署时分别由
php artisan key:generate生成 APP_KEY、自设强密码替换，二者都不应进入代码库或公开文档。
七、常见问题（FAQ）
本章汇总配置环节的实测排障。
Q1：改了 .env 为什么没生效？
FreeScout 的配置被缓存进 bootstrap/cache/config.php（3.1 节实测可见缓存内容），修改 .env 后必须执行 sudo -u www-data php /var/www/html/artisan freescout:clear-cache，以 tinker config() 复读验证。
Q2：APP_DOWNLOAD_ATTACHMENTS_VIA 在模板里找不到？
1.8.248 的 .env.example 确实没有该行（5.5 节实测踩到），直接在 .env 追加 APP_DOWNLOAD_ATTACHMENTS_VIA=nginx 再清缓存即可；同时确认 Nginx 站点里 location ^~ /storage/app/attachment/ internal 段已放开，否则附件 404。
Q3：HTTP 站点开启 SESSION_SECURE_COOKIE 后登录 419？ Secure Cookie 在非 HTTPS 连接上不回传，会话建立不起来（5.4 节完整实测：登录 POST 返回 419、访问仪表盘 302 回登录页）。HTTP 站点注释该行并清缓存；或尽快上 HTTPS。
Q4：换域名/换端口后访问 403 Untrusted Host？
APP_URL 与 APP_TRUSTED_HOSTS 不含新主机名所致（安装篇 Q3 有完整 403 文案）。改法：APP_URL 改为新地址；确需多主机名时补 APP_TRUSTED_HOSTS="a.com,b.com"，改完清缓存。
Q5：附件传不上去，到底卡在哪层？
按 5.5 节三层排查：先看 Nginx client_max_body_size（实测 25MB 超限返回 413），再用临时探针确认 FPM 的 upload_max_filesize/post_max_size（实测默认 2M|8M），最后确认 Mailbox 设置里的附件策略。三层取最小值，改完各自重启/清缓存（FPM 重启、Nginx reload、.env 清缓存）。
Q6：想看「界面里设置的参数」存哪了？
数据库 freescout.options 表（3.2 节实测结构 id/name/value），UI 修改即时生效；fetch_emails_last_run 行的持续跳动可用作 cron 调度健康巡检。
八、参考链接
- 官方安装指南（配置相关章节）：
https://github.com/freescout-help-desk/freescout/wiki/Installation-Guide - 应用内配置映射源码：
/var/www/html/config/app.php（1.8.248 发行包） - 信任代理映射源码：
/var/www/html/config/trustedproxy.php .env模板：/var/www/html/.env.example- 发信配置专题（官方 Wiki）：
https://github.com/freescout-help-desk/freescout/wiki/Sending-Emails - 安装流程与排障：《Ubuntu 22.04 安装 FreeScout 1.8.248 指南》
- 组件全景与选型：《FreeScout 1.8.248 介绍与选型指南》
- artisan 命令行工具集（config:cache 等命令实测）：《FreeScout 常用 CLI 命令详解》