DreamFactory 7.7.1 配置参数详解

目标：系统梳理 DreamFactory 7.7.1 的 .env 环境变量配置体系（应用/数据库/缓存/队列/JWT/API 行为/脚本等 13 组），逐组给出真实默认值、实测验证方法与生产推荐值，并完成 CORS 与 JWT 两项参数的端到端实测。已在 Ubuntu 22.04 服务器、DreamFactory 7.7.1（官方 df-docker 镜像，MySQL 8.0 系统库）上全量实测通过。

一、环境信息

• 组件版本：DreamFactory 7.7.1（官方镜像 dreamfactorysoftware/df-docker:7.7.1，2026-09-25）
• 系统数据库：MySQL 8.0；缓存：Redis 7；应用内 PHP：8.5.11；NGINX：1.24.0
• 部署形态：Docker Compose 编排（部署过程见《DreamFactory Docker Compose 部署指南》，配置体系两篇通用）
• 访问入口：http://<服务器IP>:8132/，管理端 API 前缀 /api/v2/
• 参数依据：实例内 /opt/dreamfactory/.env 全文（296 行，实测导出）+ 7.7.1 源码 config/ 与入口脚本行为
• 实测日期：2026-10-24

二、前置条件

1. 一套可运行的 DreamFactory 7.7.1 实例（任一安装形态；本文基于 Docker Compose 部署，命令里 docker compose exec 的用法在源码安装形态下等价于直接在 /opt/dreamfactory 目录执行）；
2. 管理员账号可用（本文用 admin@example.com / q1w2e3r4q1w2e3r4 登录管理端 API）；
3. 内置 admin 应用的 API Key（管理端 REST 调用必需，实例初始化时自动生成，可在系统库 app 表查询，本文实例实测值为 6498a8ad1beb9d84d63035c5d1120c007fad6de706734db9689f8996707e0f7d）。

三、参数查看与修改方式

DreamFactory 的配置分三层，优先级从低到高：

1. 内置默认值：源码 config/*.php（Laravel 体系）与 DreamFactory 包内默认值；
2. .env 文件：/opt/dreamfactory/.env，环境变量总入口，本文主题；
3. 数据库动态配置：管理门户「Config」页签或 /api/v2/system/... 管理端 API 写入系统库（如 CORS 规则存 cors_config 表、各服务的连接信息存 service 表）。

查看当前生效的 .env（实例内实测）：

cat /opt/dreamfactory/.env

输出共 296 行，节选（分组头与生效项，# 开头为未启用的默认值）：

##------------------------------------------------------------------------------
## Application Settings
##------------------------------------------------------------------------------
...
APP_ENV=local
APP_KEY=base64:nDBIyjpUi9XOInwnKLceB1nza8o0G+6EMjyaYmkZ2sY=
APP_LOG_LEVEL=warning
...
##------------------------------------------------------------------------------
## Database Settings
##------------------------------------------------------------------------------
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=dreamfactory
DB_USERNAME=df_admin
DB_PASSWORD=q1w2e3r4

修改 .env 后必须重启应用进程才生效（Docker 形态重启容器，源码形态重启 PHP-FPM）：

cd /opt/dreamfactory-stack && docker compose restart web

实测输出：

 Container dreamfactory-771-stack-web-1  Stopping
 Container dreamfactory-771-stack-web-1  Stopped
 Container dreamfactory-771-stack-web-1  Starting
 Container dreamfactory-771-stack-web-1  Started

修改后验证生效的方法（以会话时长为例）见 5.6 节实测。修改 .env 前先备份：cp .env .env.bak；严禁泄露或随意更换 APP_KEY（见 7.3）。

四、参数总览

7.7.1 的 .env 模板按功能分为 13 组，实测导出的分组与核心项：

💡 技术拓展：CACHE_STORE/QUEUE_CONNECTION/BROADCAST_CONNECTION 这类「驱动型」参数是 Laravel 的可插拔驱动机制——同一个配置位可切换 file/redis/memcached/database 等实现，代码逻辑不变只换底层。选型规律：单实例图省事用 file/database，多实例或高并发用 redis/memcached。

五、核心参数分类详解

5.1 应用与安全（Application）

验证当前生效值（实例实测）：

grep -E '^(APP_ENV|APP_KEY|APP_LOG_LEVEL|DF_LANDING_PAGE)' /opt/dreamfactory/.env

实测输出：

APP_ENV=local
APP_KEY=base64:nDBIyjpUi9XOInwnKLceB1nza8o0G+6EMjyaYmkZ2sY=
APP_LOG_LEVEL=warning
DF_LANDING_PAGE=/dreamfactory/dist/index.html

5.2 系统数据库（Database）

系统库存放用户/角色/服务配置等元数据，与被接入的业务数据库是两回事。

5.3 缓存（Cache）

5.4 限流缓存（Limit Cache）

API 速率限制（API Limits，商业版功能）的计数缓存，独立于普通缓存：

多实例部署时与 CACHE_STORE 同理改为 redis，否则各实例限流计数不互通。

5.5 队列与广播（Queuing / Broadcast）

5.6 会话与 JWT（登录令牌）

实测验证（DF_JWT_TTL 端到端）：把 #DF_JWT_TTL=1440 改为 DF_JWT_TTL=60（容器内 sed -i + docker compose restart web），重启后重新登录：

curl -s -X POST http://127.0.0.1:8132/api/v2/system/admin/session \
  -H 'Content-Type: application/json' \
  -H 'X-DreamFactory-API-Key: 6498a8ad1beb9d84d63035c5d1120c007fad6de706734db9689f8996707e0f7d' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4q1w2e3r4"}' | python3 -m json.tool

实测输出（节选）：

{
    "session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "email": "admin@example.com",
    "is_sys_admin": true,
    "token_expiry_date": "2026-10-23 21:09:12"
}

登录时刻为 20:09（UTC），过期时刻 21:09——正好 +60 分钟，证明 DF_JWT_TTL=60 生效（默认 1440 时实测过期时间为登录 +24 小时）。验证后改回默认：sed -i 's/^DF_JWT_TTL=60/#DF_JWT_TTL=1440/' .env 并重启。

5.7 CORS（跨域）

CORS 属于数据库动态配置而非 .env：管理门户 Config → CORS，或管理端 API /api/v2/system/cors，规则落系统库 cors_config 表。表结构实测（DESCRIBE cors_config）：

Field                 Type            Null    Key
id                    int unsigned    NO      PRI
path                  varchar(255)    NO      UNI
description           varchar(255)    YES
origin                varchar(255)    YES
header                text            YES
exposed_header        text            YES
method                int unsigned    NO
max_age               int unsigned    NO
supports_credentials  tinyint(1)      NO
enabled               tinyint(1)      NO

实测创建一条规则（允许 https://portal.example.com 跨域访问全部路径）：

curl -s -X POST http://127.0.0.1:8132/api/v2/system/cors \
  -H 'Content-Type: application/json' \
  -H 'X-DreamFactory-API-Key: 6498a8ad1beb9d84d63035c5d1120c007fad6de706734db9689f8996707e0f7d' \
  -H 'X-DreamFactory-Session-Token: <管理员JWT>' \
  -d '{"resource":[{"path":"*","origin":"https://portal.example.com","methods":"GET, POST, PUT, DELETE","headers":"Content-Type, X-DreamFactory-API-Key, X-DreamFactory-Session-Token","exposed_headers":"","max_age":86400,"supports_credentials":true,"enabled":true}]}'

实测输出：

{"resource":[{"id":1}]}

带 Origin 头请求实测（curl -i 响应头节选）：

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://portal.example.com
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400

跨域响应头按规则实时下发，验证闭环。

5.8 API 行为（API）

5.9 脚本执行与日志（Scripting / LogsDB）

5.10 邮件与安装标识

六、生产配置模板

适用场景：4 核 8GB 内存、SSD 磁盘、单实例到 3 实例水平扩展、生产对外开放 API。以下为在默认模板基础上的差异项（.env 修改或 Compose 注入）：

# ── 应用与安全 ──────────────────────────────
APP_ENV=production            # 生产环境（默认 local）
APP_DEBUG=false               # 关闭调试输出（默认即 false）
APP_LOG_LEVEL=warning         # 告警及以上入库
APP_URL=https://api.example.com
FORCE_HTTPS=true              # 前置 TLS 终止代理时必须
# ── 会话 ───────────────────────────────────
DF_JWT_TTL=120                # 2 小时会话，过期即失效（默认 1440 太长）
DF_JWT_REFRESH_TTL=4320       # 3 天刷新窗口（默认 14 天太宽）
DF_ALLOW_FOREVER_SESSIONS=false
# ── 缓存与限流（多实例必须）────────────────
CACHE_STORE=redis             # 默认 file，多实例必改
CACHE_HOST=redis
CACHE_PORT=6379
CACHE_DATABASE=0
LIMIT_CACHE_DRIVER=redis      # 限流计数多实例共享
LIMIT_CACHE_DATABASE=9
# ── 队列 ──────────────────────────────────
QUEUE_CONNECTION=redis        # 异步任务走 Redis 队列
QUEUE_HOST=redis
QUEUE_PORT=6379
QUEUE_DATABASE=3
# ── 数据库 ─────────────────────────────────
DB_QUERY_LOG_ENABLED=         # 保持注释关闭（性能）

要点：APP_KEY 用首启生成的值永久固定；改完 docker compose restart web（源码安装则重启 PHP-FPM）；上 TLS 后务必 FORCE_HTTPS=true，否则邮件里的链接是 http://。

七、常见问题

Q1：改了 .env 不生效？

两个原因：① 未重启进程——.env 在启动时加载，改完必须 docker compose restart web；② 改的是被注释的默认值行但保留了行首 #——#DF_JWT_TTL=1440 改成 DF_JWT_TTL=60 时必须去掉行首 #（实测 5.6 即按此法生效）。

Q2：CACHE_DRIVER=redis 通过 Compose 传了，为什么缓存还在用文件？

7.7.1 入口脚本会把 Compose 的 CACHE_DRIVER 写成 .env 里的 CACHE_HOST/CACHE_PORT/CACHE_DATABASE 等地址项，但 Laravel 7.x 实际读取的 CACHE_STORE 未被同步（实测 .env 中保持 CACHE_STORE=file）。生产需要 Redis 缓存时手工改：sed -i 's/^CACHE_STORE=file/CACHE_STORE=redis/' .env 后重启；验证 grep '^CACHE_STORE' .env 输出 CACHE_STORE=redis。该项目 master 分支入口脚本已含修复，升级可跟进。

Q3：CORS 规则配了没效果？

检查三点：① 规则 enabled 必须为 true（落库后 SELECT enabled FROM cors_config 验证）；② origin 与浏览器实际 Origin 完全一致（含协议，不带末尾斜杠）；③ path 是平台路径前缀（* 或 /api），不是业务资源路径。可用 curl -i -H 'Origin: https://portal.example.com' http://<host>:<port>/api/v2/system/environment 直接看响应头是否回 Access-Control-Allow-Origin（本文 5.7 实测闭环）。

Q4：更换 APP_KEY 后服务全部连不上？

系统库里已保存的服务凭据用旧 APP_KEY 加密，换新 key 后无法解密。官方口径：重建/迁移实例必须沿用原 APP_KEY。若已丢失，只能逐个服务重录凭据（或清库重装）。

Q5：日志级别调成 debug 后日志暴涨怎么办？

APP_LOG_LEVEL=debug 会记录每个 API 请求/响应（含参数），排障时临时开启，用完改回 warning 并重启。磁盘紧张时同时关注 LOG_TO_STDOUT（日志双写标准输出会放大容器日志量）。

八、参考链接

• 本文实例 .env 全文实测导出与验证记录（2026-10-24，DreamFactory 7.7.1）
• 部署与编排变量：《DreamFactory Docker Compose 部署指南》
• 官方源码 .env 模板：https://github.com/dreamfactorysoftware/dreamfactory/blob/master/.env-dist（7.7.1 对应 tag 下同名文件）
• 官方配置文档：https://docs.dreamfactory.com/（DreamFactory Configuration 章节）