Firefly III 配置参数详解
Firefly III v6.7.9 的 .env 配置体系全量详解：参数查看（about/config:show）、修改生效流程、_FILE 密钥注入，76 个官方变量按九组逐项说明含实测生效值，附两档生产配置模板与 APP_KEY/PGSQL_SCHEMA 等 FAQ。
Firefly III 配置参数详解
目标：系统讲清 Firefly III v6.7.9 的
.env配置体系——参数怎么查看、怎么修改、怎么生效，按"应用基础/日志审计/数据库/缓存会话/邮件/Cookie/认证安全/定时任务/杂项"九组逐项详解官方全部配置变量，并给出两档生产配置模板。全部参数清单与运行时生效值均取自实测部署（官方镜像内置.env.example与php artisan about/config:show实查），部署过程见《Firefly III Docker Compose 部署实战》。
一、环境信息
本文基于以下实测环境取证（2026-10-28）：
| 项目 | 值 |
|---|---|
| Firefly III 版本 | 6.7.9（fireflyiii/core:latest，PHP 8.5.12 运行时） |
| 数据库 | PostgreSQL 16（DB_CONNECTION=pgsql） |
| 部署形态 | Docker Compose 四服务栈（app/db/cron/importer），.env 经 env_file 注入主程序 |
| 参数清单来源 | 官方镜像内置 /var/www/html/.env.example（295 行，与官方仓库 main 分支一致） |
| 运行时取证 | php artisan about、php artisan config:show firefly、php -i |
| 官方参数文档 | https://docs.firefly-iii.org/how-to/firefly-iii/advanced/cache/ 、认证/邮件/cron 等进阶文档页 |
💡 说明：Firefly III 的配置是"Laravel 标准 .env 体系"——一个环境变量文件驱动全部行为，无独立 XML/YAML 配置文件。官方镜像在启动时会用
.env重建配置缓存，因此修改.env后重启主程序即生效（实测见三、3.3）。
二、前置条件
- 已按《Firefly III Docker Compose 部署实战》完成部署并可访问 Web 界面；
- 能进入主程序执行 artisan 命令（容器内
php artisan，本文全部命令实测）； - 理解两条铁律：
APP_KEY与DB_PASSWORD在首次启动后不可更换（后果见 5.1 与八、FAQ）。
三、参数查看与修改方式
3.1 三种查看途径
途径一：官方参数模板（全量清单）。主程序仓库的 .env.example 是唯一权威全量清单，官方镜像内自带一份（部署机上可用官方 raw 文件对照）：
$ curl -s https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example -o .env.example
$ wc -l .env.example
295 .env.example
$ grep -cE '^[A-Z][A-Z_0-9]+=' .env.example
76
（76 个未注释变量，其余为注释说明与分组分隔。）
途径二：php artisan about（运行时生效概览）。一屏看清当前生效的驱动与开关（实测回显，仅本地部署实测值）：
$ docker exec firefly-iii-6.7.9-app php artisan about
Environment ................................................................
Application Name ............................................... Firefly III
Laravel Version .................................................... 13.35.0
PHP Version ......................................................... 8.5.12
Composer Version .................................................... 2.10.3
Environment ..................................................... production
Debug Mode ............................................................. OFF
URL ................................................... 192.168.146.128:8130
Maintenance Mode ....................................................... OFF
Timezone ..................................................... Asia/Shanghai
Locale ............................................................... en_US
Cache ......................................................................
Config .............................................................. CACHED
Events .............................................................. CACHED
Routes .......................................................... NOT CACHED
Views ............................................................... CACHED
Drivers ....................................................................
Broadcasting .......................................................... null
Cache ................................................................. file
Database ............................................................. pgsql
Logs ................................................. stack / daily, stdout
Mail ................................................................... log
Queue ................................................................. sync
Session ............................................................... file
（输出节选——Storage 与 Environment Variables 段略）
Timezone/Locale/Database/Mail/Session 五行分别对应 .env 的 TZ/DEFAULT_LANGUAGE/DB_CONNECTION/MAIL_MAILER/SESSION_DRIVER——.env 改动经重启后在此核验最直观。
途径三：php artisan config:show firefly（应用级配置明细）。查看 Firefly III 自己的 config 文件生效值（实测回显，节选）：
$ docker exec firefly-iii-6.7.9-app php artisan config:show firefly
firefly ....................................................................
configuration ⇁ single_user_mode ...................................... true
configuration ⇁ is_demo_site ......................................... false
feature_flags ⇁ export ................................................ true
feature_flags ⇁ telemetry ............................................ false
feature_flags ⇁ webhooks .............................................. true
feature_flags ⇁ handle_debts .......................................... true
feature_flags ⇁ expression_engine ..................................... true
feature_flags ⇁ running_balance_column ................................ true
version .............................................................. 6.7.9
api_version .......................................................... 2.1.0
maxUploadSize ................................................... 1073741824
send_error_message .................................................... true
site_owner ............................................. admin@firefly.local
static_cron_token ......................... msiPUbX4gIqx9L1gAkwUmrfgJqYRmGzS
（输出节选）
💡 说明：
config:show暴露的static_cron_token、site_owner等即.env对应变量的最终生效值，排查"改了没生效"时用它对答案。
3.2 修改方式与生效流程
修改 .env（部署目录内，如 /opt/firefly-iii/.env）→ 重启主程序 → 验证：
cd /opt/firefly-iii
vi .env # 修改目标变量
docker compose restart app # 官方镜像启动时重建配置缓存，重启即生效
docker exec firefly-iii-6.7.9-app php artisan about # 核验生效值
3.3 敏感变量的 _FILE 注入（Docker 密钥文件形态）
官方模板为几乎全部敏感变量提供了 _FILE 后缀形态：不直接给值，而是给一个文件路径，程序启动时读文件内容作为变量值。官方注释原文（.env.example 节选）：
# If you use Docker or similar, you can set this variable from a file by using APP_KEY_FILE
# If you use Docker or similar, you can set these variables from a file by appending them with _FILE
# You can set the following variables from a file by appending them with _FILE:
支持该形态的典型变量：APP_KEY_FILE、SITE_OWNER_FILE、DB_PASSWORD_FILE、REDIS_HOST_FILE/REDIS_PASSWORD_FILE/REDIS_PORT_FILE、COOKIE_DOMAIN_FILE、PASSPORT_PUBLIC_KEY_FILE/PASSPORT_PRIVATE_KEY_FILE。适用场景：Docker secrets、Kubernetes Secret 卷挂载等密钥管理体系。> ⚠️ 模板注释同时指出：极个别项（如 PASSPORT_*_KEY）只能用 _FILE 形态覆盖，MAILGUN_ENDPOINT 用 _FILE 单数形式（_FILE 直接后缀）。
四、参数总览
官方 .env.example 的 76 个有效变量按功能分九组：
| 分组 | 代表变量 | 数量（含 SSL/驱动细分） | 作用域 |
|---|---|---|---|
| 应用基础 | APP_KEY、APP_URL、TZ | 8 | 运行环境、加密、展示语言 |
| 日志与审计 | LOG_CHANNEL、AUDIT_LOG_LEVEL | 7 | 日志通道/级别、审计分流 |
| 数据库 | DB_CONNECTION、PGSQL_SCHEMA | 14 | 连接、驱动 SSL、schema |
| 缓存与会话 | CACHE_STORE、REDIS_* | 9 | 缓存/会话驱动与 Redis 连接 |
| Cookie | COOKIE_SECURE | 4 | 会话 Cookie 策略 |
| 邮件与通知 | MAIL_MAILER、MAILGUN_* | 14 | SMTP/第三方邮件服务 |
| 认证与安全 | AUTHENTICATION_GUARD、PASSPORT_* | 10 | 认证守卫、OAuth 密钥、安全响应头 |
| 定时任务与地图 | STATIC_CRON_TOKEN、MAP_DEFAULT_* | 6 | cron 入口口令、地图默认位置 |
| 杂项 | APP_NAME、PHP_MEMORY_LIMIT | 4 | 框架级默认、PHP 限制 |
关键差异与使用逻辑：九组中"数据库"与"应用基础"是必改项（部署时必须落实际值），"邮件/认证/缓存"按场景选配，其余组保持默认即可。以下逐组详解。
五、核心参数分类详解
5.1 应用基础组
APP_ENV=production
APP_DEBUG=false
SITE_OWNER=admin@firefly.local
APP_KEY=CqRn77wKahWp5Bsnwogd4wbgBrXKU9Rw
APP_URL=http://192.168.146.128:8130
DEFAULT_LANGUAGE=en_US
DEFAULT_LOCALE=equal
TZ=Asia/Shanghai
| 变量 | 实测取值 | 默认值 | 说明 |
|---|---|---|---|
APP_ENV | production | production | 运行环境标识；改 local 后多数控制台命令会要求二次确认；严禁 testing（官方注释原文） |
APP_DEBUG | false | false | 调试模式；true 时错误页暴露堆栈与配置，生产必须 false |
SITE_OWNER | admin@firefly.local | mail@example.com | 站点管理员邮箱；非管理员用户看到的错误提示会引导联系该邮箱 |
APP_KEY | 32 位随机串 | 无（模板占位） | 会话加密密钥。必须恰好 32 字符，避免 #、<、> 等特殊字符；官方给的标准生成命令 head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo。首次启动后不可更换：更换即解密失败，表现为全部登录态失效、加密数据不可读（变更演练实测见《Firefly III 常用命令与运维实战》第十一章） |
APP_URL | http://192.168.146.128:8130 | http://localhost | 对外基准 URL；用于校验特定请求与生成邮件内链接，必须与浏览器实际访问地址一致 |
DEFAULT_LANGUAGE | en_US | en_US | 新用户与未登录访客的界面语言；可取值清单在官方仓库 config/firefly.php；界面含简体中文翻译 |
DEFAULT_LOCALE | equal | equal | 数字格式化地区；equal 表示跟随语言设置 |
TZ | Asia/Shanghai | Europe/Amsterdam | 时区；影响页面时间与日志时间戳 |
5.2 日志与审计组
LOG_CHANNEL=stack
APP_LOG_LEVEL=notice
AUDIT_LOG_LEVEL=emergency
AUDIT_LOG_CHANNEL=
PAPERTRAIL_HOST=
PAPERTRAIL_PORT=
| 变量 | 实测取值 | 说明 |
|---|---|---|
LOG_CHANNEL | stack | 日志去向：stack（默认，同时写轮转文件+stdout）/ daily（按天轮转 5 份）/ single（单一大文件，不推荐）/ syslog / errorlog / stdout / papertrail。实测生效值 stack / daily, stdout（about 回显） |
APP_LOG_LEVEL | notice | 日志级别从弱到强：debug, info, notice, warning, error, critical, alert, emergency；debug 会让日志快速增长 |
AUDIT_LOG_LEVEL | emergency | 审计日志独立开关：默认 emergency 即关闭；设 info 开启。审计日志记录"值得注意的财务事件"，官方提醒可能包含敏感财务信息，需单独保管 |
AUDIT_LOG_CHANNEL | （空） | 审计日志分流：audit_stdout/audit_syslog/audit_errorlog/audit_daily/audit_papertrail；留空则跟随主日志通道 |
PAPERTRAIL_HOST/PORT | （空） | 使用 papertrail 云日志时的主机与端口 |
💡 技术拓展：审计日志（audit log）与应用日志（application log）的差别——应用日志记录程序运行事件（错误、异常），审计日志记录"谁在什么时候改了什么财务数据"这类合规性事件。Firefly III 用两个独立通道承载：生产环境建议
AUDIT_LOG_LEVEL=info开启审计，并用AUDIT_LOG_CHANNEL=audit_daily分流到独立轮转文件，避免与运维日志混存。
5.3 数据库组
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=q1w2e3r4
DB_SOCKET=
PGSQL_SCHEMA=public
| 变量 | 实测取值 | 说明 |
|---|---|---|
DB_CONNECTION | pgsql | 驱动：mysql（MySQL/MariaDB，官方默认）/ pgsql（PostgreSQL）/ sqlite。> 💡 技术拓展：三者取舍——MySQL/MariaDB 与 PostgreSQL 是官方推荐的两大主力（本部署选 pgsql，生态成熟且与官方示例一致）；sqlite 仅建议测试/极小规模，官方 FAQ 有专页说明其限制 |
DB_HOST | db | 数据库主机；Compose 部署填服务名，独立数据库填 IP/域名 |
DB_PORT | 5432 | 端口：PostgreSQL 5432 / MySQL 3306 |
DB_DATABASE / DB_USERNAME / DB_PASSWORD | firefly / firefly / （演示口令） | 库名/账号/口令；DB_PASSWORD 首次启动落库后不可再改（官方文档明确警示，Compose 编排的 POSTGRES_PASSWORD 必须同步） |
DB_SOCKET | （空） | Unix socket 连接时填 socket 路径，与 DB_HOST/PORT 二选一 |
PGSQL_SCHEMA | public | PostgreSQL schema；PG 15+ 的 public schema 默认无写权限，官方注释明确指出该坑——安全配置下应建专用 schema 并把此变量指向它 |
SSL 细分项（按驱动二选一配置）：
MYSQL_USE_SSL=false
MYSQL_SSL_VERIFY_SERVER_CERT=true
MYSQL_SSL_CAPATH=/etc/ssl/certs/
MYSQL_SSL_CA=
MYSQL_SSL_CERT=
MYSQL_SSL_KEY=
MYSQL_SSL_CIPHER=
PGSQL_SSL_MODE=prefer
PGSQL_SSL_ROOT_CERT=null
PGSQL_SSL_CERT=null
PGSQL_SSL_KEY=null
PGSQL_SSL_CRL_FILE=null
MYSQL_* 组：MYSQL_USE_SSL 开关 + CA/证书/私钥/加密套件五项，MYSQL_SSL_VERIFY_SERVER_CERT=true 时校验服务端证书。PGSQL_* 组：PGSQL_SSL_MODE 取 disable/allow/prefer/require/verify-ca/verify-full（默认 prefer），其余四项为证书文件路径。数据库与应用同编排网络内网通信时保持默认即可；跨网段/云上部署建议 require 以上并挂 CA。
5.4 缓存与会话组
CACHE_STORE=file
SESSION_DRIVER=file
REDIS_SCHEME=tcp
REDIS_PATH=
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DB="0"
REDIS_CACHE_DB="1"
| 变量 | 实测取值 | 说明 |
|---|---|---|
CACHE_STORE | file | 缓存后端：file（默认，零依赖）/ redis / memcached。官方注释原话："If you're looking for performance improvements, you could install memcached or redis" |
SESSION_DRIVER | file | 会话存储：file（默认）/ redis 等；实测生效值见 about 回显 Session = file |
REDIS_SCHEME | tcp | tcp 或 unix（不支持 http） |
REDIS_HOST/PORT | 127.0.0.1 / 6379 | TCP 模式地址端口；独立 Redis 部署改为对应主机 |
REDIS_USERNAME/PASSWORD | （空） | Redis 6+ ACL 账号密码，未启用 ACL 留空 |
REDIS_DB / REDIS_CACHE_DB | "0" / "1" | 会话库与缓存库编号，官方注释要求始终加引号且确保两个库存在 |
💡 技术拓展：会话驱动选型——
file零依赖、重启即失效（需重新登录），适合单人自托管；redis支持多实例共享会话与更快的读写，适合并发用户较多或 want 长稳会话的场景；memcached是另一经典选择但 Firefly III 更常与 redis 搭配。本部署为个人自托管基线，采用默认file，重启后重新登录属预期行为。
5.5 Cookie 组
COOKIE_PATH="/"
COOKIE_DOMAIN=
COOKIE_SECURE=false
COOKIE_SAMESITE=lax
| 变量 | 实测取值 | 说明 |
|---|---|---|
COOKIE_PATH | "/" | Cookie 路径，一般不动 |
COOKIE_DOMAIN | （空） | 多子域共享会话时设置；留空跟随当前域名 |
COOKIE_SECURE | false | HTTPS 部署时改 true（仅经加密连接发送 Cookie）；本部署 HTTP 直连故为 false |
COOKIE_SAMESITE | lax | lax（默认）/ strict / none；官方注释提醒 strict 可能导致登录异常 |
5.6 邮件与通知组
MAIL_MAILER=log
MAIL_HOST=null
MAIL_PORT=2525
MAIL_FROM=changeme@example.com
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_SENDMAIL_COMMAND=
MAIL_ALLOW_SELF_SIGNED=false
MAIL_VERIFY_PEER=true
MAIL_VERIFY_PEER_NAME=true
SEND_ERROR_MESSAGE=true
MAILGUN_DOMAIN=
MAILGUN_SECRET=
MAILGUN_ENDPOINT=api.mailgun.net
MANDRILL_SECRET=
SPARKPOST_SECRET=
MAILERSEND_API_KEY=
MAIL_MAILER：邮件驱动。log（默认，邮件写入日志——离线/内网环境首选，注册确认邮件在laravel.log可查）/smtp（需配MAIL_HOST/PORT/USERNAME/PASSWORD/ENCRYPTION）/sendmail（走本机 sendmail，可配MAIL_SENDMAIL_COMMAND）/mailgun/mandrill/sparkpost/mailersend（第三方 API，配对应 SECRET）。- 自签证书三件套：
MAIL_ALLOW_SELF_SIGNED=false、MAIL_VERIFY_PEER=true、MAIL_VERIFY_PEER_NAME=true——内网自建 SMTP 用自签证书时按需放开。 SEND_ERROR_MESSAGE=true：允许把应用错误邮件通知给SITE_OWNER。
5.7 认证与安全组
AUTHENTICATION_GUARD=web
AUTHENTICATION_GUARD_HEADER=REMOTE_USER
AUTHENTICATION_GUARD_EMAIL=
PASSPORT_PRIVATE_KEY=
PASSPORT_PUBLIC_KEY=
CUSTOM_LOGOUT_URL=
DISABLE_FRAME_HEADER=false
DISABLE_CSP_HEADER=false
TRACKER_SITE_ID=
TRACKER_URL=
TRUSTED_PROXIES=
STATIC_CRON_TOKEN=msiPUbX4gIqx9L1gAkwUmrfgJqYRmGzS
这是本次实查修正认知的一组——官方 .env.example 认证小节的注释原文（实测逐行摘抄）：
# Firefly III supports a few authentication methods:
# - 'web' (default, uses built in DB)
# - 'remote_user_guard' for Authelia etc
# Read more about these settings in the documentation.
# https://docs.firefly-iii.org/how-to/firefly-iii/advanced/authentication/
#
# LDAP is no longer supported :(
#
AUTHENTICATION_GUARD=web
💡 技术拓展：外部认证接入方式对比（以 v6.7.9 实查为准）——
方式 状态 接入方法 内置 web 认证（邮箱+密码+2FA） ✅ 内置默认 无需配置；双因素认证在个人资料页开启 remote_user_guard（反代注入头） ✅ 内置 AUTHENTICATION_GUARD=remote_user_guard+AUTHENTICATION_GUARD_HEADER=REMOTE_USER，配合 Authelia/authentik 等反向代理认证内置 OIDC/SAML ❌ 无此配置项 v6.7.9 的 .env.example与 config 目录实测均无 OIDC/SAML 变量；需单点登录走 remote_user_guard 形态LDAP ❌ 已移除 官方注释原文"LDAP is no longer supported" 本文部署采用默认
web认证；需要反代单点登录的读者选remote_user_guard。
逐项说明：
| 变量 | 实测取值 | 说明 |
|---|---|---|
AUTHENTICATION_GUARD | web | 认证守卫：web（内置数据库认证）/ remote_user_guard（外部反代注入头） |
AUTHENTICATION_GUARD_HEADER | REMOTE_USER | remote_user_guard 读取的 HTTP 头名（由反代注入） |
AUTHENTICATION_GUARD_EMAIL | （空） | remote_user_guard 场景下的兜底邮箱 |
PASSPORT_PRIVATE_KEY/PUBLIC_KEY | （空） | OAuth 令牌签名密钥对；留空由程序自动生成；Docker secrets 场景用 _FILE 形态注入 |
CUSTOM_LOGOUT_URL | （空） | 自定义登出跳转地址（对接统一认证时用） |
DISABLE_FRAME_HEADER | false | 是否去掉 X-Frame-Options 头；false 时不允许被 iframe 嵌套（官方提醒 frame 嵌套有信息泄露风险） |
DISABLE_CSP_HEADER | false | 是否去掉内容安全策略（CSP）头；生产保持 false |
TRACKER_SITE_ID/TRACKER_URL | （空） | 可选自托管 Matomo 统计接入；默认关闭、无外发流量 |
TRUSTED_PROXIES | （空） | 可信代理网段；置于反向代理后设 **（官方注释示例），直接暴露端口留空 |
STATIC_CRON_TOKEN | 32 位随机串 | 定时任务入口口令：必须恰好 32 字符；cron 服务用它拼出 GET /api/v1/cron/<token> 触发后台作业（自动预算/循环交易/webhook），避免用用户令牌跑定时任务 |
5.8 定时任务与地图组
MAP_DEFAULT_LAT=51.983333
MAP_DEFAULT_LONG=5.916667
MAP_DEFAULT_ZOOM=6
DKR_CHECK_SQLITE=true
| 变量 | 实测取值 | 说明 |
|---|---|---|
MAP_DEFAULT_LAT/LONG/ZOOM | 51.98…/5.91…/6 | 交易位置地图的默认中心点与缩放；按所在城市改。实测 config:show 回显 enable_external_map = false——不开外部地图服务时这些值不生效，属预留配置 |
DKR_CHECK_SQLITE | true | 官方镜像启动项：是否检查 SQLite 库文件存在；非 SQLite 部署可关以微调启动速度（官方注释：提速有限） |
5.9 杂项组（框架级默认）
APP_NAME=FireflyIII
BROADCAST_DRIVER=log
QUEUE_DRIVER=sync
CACHE_PREFIX=firefly
PUSHER_KEY=
PUSHER_SECRET=
PUSHER_ID=
DEMO_USERNAME=
DEMO_PASSWORD=
PHP_MEMORY_LIMIT=512M
APP_URL=http://localhost
| 变量 | 实测取值 | 说明 |
|---|---|---|
APP_NAME | FireflyIII | 应用显示名 |
BROADCAST_DRIVER | log | Laravel 广播驱动，保持 log |
QUEUE_DRIVER | sync | 队列驱动：sync（同步执行，默认）；实测 about 回显 Queue = sync |
CACHE_PREFIX | firefly | 缓存键前缀，多应用共享 Redis 时区分 |
PUSHER_* | （空） | Pusher 实时推送，未使用留空 |
DEMO_USERNAME/DEMO_PASSWORD | （空） | 官方演示站点专用，自托管留空 |
PHP_MEMORY_LIMIT | 512M | 官方镜像按此值设定 PHP 内存上限；实测容器内 php -r "echo ini_get('memory_limit');" 回显 512M。单机大量历史数据导入/报表可调 1G，同时注意编排内存配额 |
5.10 运行时有效参数速查（config:show 核对表）
.env 之外，config/firefly.php 还定义了一批运行时常量（不可经 .env 修改，升级随版本变化）。实测关键值：
| 参数 | 实测值 | 含义 |
|---|---|---|
single_user_mode | true | 单用户模式（默认 true；注册页仅在无用户时开放） |
is_demo_site | false | 是否演示站（演示站有额外限制） |
api_version | 2.1.0 | REST API 版本（与 6.7.9 主版本并行独立演进） |
db_version | 28 | 数据库 schema 版本号（升级迁移的基准） |
maxUploadSize | 1073741824 | 附件上传上限 1GB |
feature_flags.webhooks | true | Webhook 功能开关 |
feature_flags.expression_engine | true | 规则表达式引擎开关 |
feature_flags.running_balance_column | true | 余额列实时计算开关 |
六、生产配置模板
6.1 单人自托管基线（2GB 内存 / 20GB 磁盘 / 个人家用）
APP_ENV=production
APP_DEBUG=false
SITE_OWNER=you@example.com
APP_KEY=<32位随机串，生成后固定>
APP_URL=https://firefly.example.com
DEFAULT_LANGUAGE=zh_CN
DEFAULT_LOCALE=equal
TZ=Asia/Shanghai
TRUSTED_PROXIES=
LOG_CHANNEL=stack
APP_LOG_LEVEL=notice
AUDIT_LOG_LEVEL=info
AUDIT_LOG_CHANNEL=audit_daily
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=<强口令，与编排 POSTGRES_PASSWORD 一致>
PGSQL_SCHEMA=public
CACHE_STORE=file
SESSION_DRIVER=file
STATIC_CRON_TOKEN=<32位随机串>
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=you@example.com
MAIL_USERNAME=you@example.com
MAIL_PASSWORD=<SMTP口令>
MAIL_ENCRYPTION=tls
COOKIE_SECURE=true
COOKIE_SAMESITE=lax
PHP_MEMORY_LIMIT=512M
要点：HTTPS 反代部署（APP_URL 为 https、COOKIE_SECURE=true、TRUSTED_PROXIES 填代理网段）；审计日志开启并分流；真实 SMTP；缓存/会话保持 file 零依赖。磁盘按"每年约 500MB 量级（含附件）"预估。
6.2 家庭多用户/长稳基线（4GB 内存 / 独立 Redis / 反代统一认证）
在 6.1 基础上叠加/替换：
CACHE_STORE=redis
SESSION_DRIVER=redis
REDIS_SCHEME=tcp
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB="0"
REDIS_CACHE_DB="1"
AUTHENTICATION_GUARD=remote_user_guard
AUTHENTICATION_GUARD_HEADER=REMOTE_USER
TRUSTED_PROXIES=**
CUSTOM_LOGOUT_URL=https://auth.example.com/logout
PHP_MEMORY_LIMIT=1G
要点：Redis 承担缓存+会话（注意 REDIS_DB/REDIS_CACHE_DB 两库都要存在）；认证交给 Authelia 类反代统一登录；内存放宽到 1G 应对多用户报表。其余变量同 6.1。
七、常见问题（FAQ）
Q1：.env 改了没生效？
三个检查点：① 是否 docker compose restart app（env_file 在容器创建/重启时注入）；② 改的是部署目录里被编排引用的那个 .env（官方原版模板是 .env + .db.env 双文件，本文编排已合并为单 .env）；③ 用 php artisan config:show firefly 对答案（如 site_owner/static_cron_token 直接可见生效值）。
Q2：能改 APP_KEY 吗？
不能（已启用后）。APP_KEY 参与 Laravel 加密体系，更换后既有加密数据不可读、全部会话/令牌失效。实测变更演练与恢复过程见《Firefly III 常用命令与运维实战》第十一章。
Q3：PostgreSQL 15+ 下 PGSQL_SCHEMA=public 报权限错误？
官方注释明确：PG15 起 public schema 默认无写权限。安全配置下创建专用 schema 并赋权，再把 PGSQL_SCHEMA 指向它；或由数据库管理员显式授权 public schema（不推荐）。
Q4：想要 OIDC/SAML 单点登录，配置哪几个变量？
实测 v6.7.9 的官方 .env.example（295 行全量核查）没有 OIDC/SAML 变量，config 目录同样没有对应配置文件——该版本外部单点登录的唯一内建路径是 AUTHENTICATION_GUARD=remote_user_guard（反代注入 REMOTE_USER 头，配 Authelia/authentik 等）。写作本文前曾预期存在 OIDC 配置，实查修正：以部署镜像内清单为准。
Q5：审计日志开了会有什么影响？
AUDIT_LOG_LEVEL=info 开启后，审计事件独立成流；官方提醒审计日志可能包含敏感财务信息（金额、备注等），建议用 AUDIT_LOG_CHANNEL=audit_daily 分流轮转文件并收紧文件权限，避免混入普通运维日志被随意转发。
Q6：PHP_MEMORY_LIMIT 调大后还不够？
先确认编排侧内存配额没有被限死；再注意该值只调 PHP 运行时，导入大批量历史数据时的耗时瓶颈通常在数据库写入——分开评估。
八、参考链接
- 部署与编排基线：《Firefly III Docker Compose 部署实战》
- 产品与选型背景：《Firefly III 介绍与选型指南》
- artisan 命令与运维实操：《Firefly III 常用命令与运维实战》
- 官方
.env.example（参数全量清单，2026-10-28 取证）：https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example - 官方配置文档（缓存/邮件/cron 认证等进阶页）：https://docs.firefly-iii.org/how-to/firefly-iii/advanced/
- 官方认证文档页：https://docs.firefly-iii.org/how-to/firefly-iii/advanced/authentication/
- 官方 Docker FAQ（含 SQLite 等数据库问答）：https://docs.firefly-iii.org/references/faq/docker/