ProjectSend 2.8.0 配置参数详解

目标：讲清 ProjectSend 2.8.0 的三层配置体系（环境变量 → storage/.env → Web 系统设置）、全部环境参数的语义与默认值，并给出三种典型规模的生产配置模板。全部取值与回显均在 2.8.0 实测环境（Ubuntu 24.04 + 官方 Docker 镜像）采集，官方文件注释逐条溯源。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
ProjectSend：2.8.0（官方镜像 projectsend/projectsend:2.8.0）
运行时实测：PHP 8.4.27 / Laravel Framework 12.69.3（php artisan about 实测）
数据库：MySQL 8.4；缓存/会话/队列：Redis 7
部署方式：Docker Compose 三服务（部署过程见《ProjectSend 2.8.0 Docker Compose 部署指南》）
服务器地址：http://192.168.1.172:8135（APP_URL 实测值）
配置文件实测位置：容器内 /var/www/html/storage/.env（宿主侧 /srv/projectsend/storage/.env）

二、前置条件

本文是配置专题，不重复部署步骤，但要求读者具备以下两项条件；每项都给出核对命令与实测回显。

一套已运行的 ProjectSend 2.8.0（Compose 部署或 zip 安装均可，本文以 Compose 形态给命令）。核对：

docker compose ps

实测回显（节选 STATUS 列）：

STATUS
Up 10 minutes (healthy)
Up 15 minutes (healthy)
Up 15 minutes

能进入应用命令行（Compose 形态用 docker compose exec app，zip 形态在安装目录直接执行 php artisan）。核对运行时版本：

docker compose exec app php artisan about

实测回显（节选）：

  Application Name ............................................... ProjectSend
  Laravel Version .................................................... 12.69.3
  PHP Version ......................................................... 8.4.27
  Environment ..................................................... production
  Debug Mode ............................................................. OFF
  URL ..................................................... 192.168.1.172:8135
  Timezone ............................................................... UTC
  Locale .................................................................. en

三、参数查看与修改方式

本节先讲清"配置存在哪、谁覆盖谁、怎么改"，否则改了参数不生效是最常见的困惑。ProjectSend 2.8.0 的配置分三层，优先级从高到低：

第 1 层：进程环境变量（Compose environment 注入）。Laravel 框架直接读取环境变量且优先于 .env 文件（官方 entrypoint 注释原文："Laravel reads the environment directly and it wins over .env"）。Compose 部署改这里最直接：编辑 compose.yaml 的 environment: 段后 docker compose up -d 重建。

第 2 层：storage/.env 持久化文件。首次启动时由镜像内 .env.example 复制生成，APP_KEY 写在这里并随 storage 卷持久化。宿主机可直接编辑（实测路径 /srv/projectsend/storage/.env），改完 docker compose restart app 生效。查看当前值：

head -6 /srv/projectsend/storage/.env

实测回显：

# ProjectSend configuration.
#
# Copy this file to `.env` and edit it. INSTALL.md walks through every
# value here; the short version is that you must set APP_URL and the four
# DB_ lines, then run `php artisan key:generate`.

APP_KEY=base64:WaqRc0SY…

（APP_KEY 为敏感值，此处节选，完整值勿外泄。）

第 3 层：Web 系统设置（入库存储）。登录后 System → Settings 的各项（邮件、存储后端、病毒扫描、品牌外观、CAPTCHA 等）保存在数据库 settings 表（键值结构，实测表结构与内容如下）。一旦在界面设置过某项，入库值即优先生效，对应环境变量退化为"仅用于初始化兜底"——官方对病毒扫描地址的注释原文："the address and the switch are both on System → Settings → Virus scanning, and this line is ignored on every later boot"。

docker compose exec db mysql -uroot -pq1w2e3r4 -e "SELECT * FROM projectsend.settings;"

实测回显（全新安装时只有少量键）：

id	key	value	created_at	updated_at
1	applied_version	"2.8.0"	2026-10-31 02:04:38	2026-11-01 02:48:22
2	applied_version_at	"2026-11-01T02:48:22+00:00"	2026-10-31 02:04:38	2026-11-01 02:48:22
3	admin_notification_emails	["admin@example.com"]	2026-11-01 02:48:24	2026-11-01 02:48:24
4	getting_started_pending	true	2026-11-01 02:48:24	2026-11-01 02:48:24

启动脚本 projectsend:seed-settings（每次启动自动执行）只向"从未设置过"的键写入环境变量预置值，永不覆盖界面已设值——这就是"环境变量预置、界面接管"的实现机制。

辅助查看工具：php artisan config:show <配置文件> 可核对运行时实际生效值（示例见 5.3 数据库小节）；php artisan about 的 Drivers 段汇总当前各驱动（实测：Cache redis / Database mysql / Mail smtp / Queue redis / Session redis）。

⚠️ 注意：官方 .env.example 与 entrypoint 注释都明确警告不要执行 php artisan config:cache——缓存配置后 .env 不再被读取，会"静默禁用 TRUSTED_PROXIES"：所有访客看起来都来自代理，登录限速把全体用户当成一个攻击者，下载日志记录错误地址。官方镜像刻意在每次启动时执行缓存清理，就是为了防这个坑。

四、参数总览

下表汇总全部环境变量参数。默认值一列来自官方 .env.example（查询日期 2026-11-01）与镜像 entrypoint 行为；"管理界面"列表示该项是否同时可在 System → Settings 管理。

参数	默认值	作用	管理界面
APP_NAME	ProjectSend	应用名（邮件发件人名等处引用）	部分（品牌设置）
APP_ENV	production	运行环境	否
APP_KEY	首启自动生成	加密密钥	否
APP_DEBUG	false	调试模式	否
APP_URL	https://files.example.com（需改）	对外地址，生成下载链接与邮件链接	否
APP_TIMEZONE	UTC	时区	否
APP_LOCALE / APP_FALLBACK_LOCALE	en	界面语言/回退语言（共 16 种语言可选）	是（用户级）
PROJECTSEND_EDITION	community	运行版本（community/hosted 平台用）	否
PROJECTSEND_FILE_DELIVERY	auto（未设即 auto）	下载投递通道	状态在 System 面板展示
PROJECTSEND_SCANNER_DEFAULT_ADDRESS	未设	首启预置病毒扫描地址	是（Virus scanning）
DB_CONNECTION / DB_HOST / DB_PORT	mysql / 127.0.0.1 / 3306	数据库连接	否
DB_DATABASE / DB_USERNAME / DB_PASSWORD	projectsend / projectsend / 空	库名与凭据	否
SESSION_DRIVER	database	会话存储驱动	否
SESSION_LIFETIME	120	会话有效期（分钟）	否
SESSION_SECURE_COOKIE	注释（关）	HTTPS 站点强制安全 Cookie	否
CACHE_STORE	database	缓存驱动	否
QUEUE_CONNECTION	database	队列驱动	否
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD	127.0.0.1 / 6379 / null	Redis 连接（配合上面三项使用）	否
FILESYSTEM_DISK	local	主存储磁盘（S3 等在界面配置）	是（Storage）
MAIL_MAILER / MAIL_HOST / MAIL_PORT	smtp / 127.0.0.1 / 25	邮件兜底配置	是（Email）
MAIL_USERNAME / MAIL_PASSWORD	空	SMTP 凭据	是（Email）
MAIL_ENCRYPTION	null	SMTP 加密方式	是（Email）
MAIL_FROM_ADDRESS / MAIL_FROM_NAME	files@example.com / ${APP_NAME}	发件人	是（Email）
TRUSTED_PROXIES	未设	可信代理列表（代理后必须设置）	否
LOG_CHANNEL / LOG_STACK	stack / daily	日志通道与栈	否
LOG_DAILY_DAYS	14	滚动日志保留天数	否
LOG_LEVEL	warning	日志级别	否
ADMIN_NAME / ADMIN_EMAIL / ADMIN_PASSWORD	未设	首启自动建管理员（仅无人任何账号时生效）	否

关键解读：APP_URL、DB_*、驱动三件套（SESSION/CACHE/QUEUE）与 TRUSTED_PROXIES 是每次部署必须过目的一组；其余多数有合理默认。

五、核心参数分类详解

5.1 应用基础（APP_*）

本组决定应用身份与运行姿态。APP_NAME 用于界面标题与邮件发件人名兜底（MAIL_FROM_NAME 默认取 ${APP_NAME}）；APP_ENV 生产固定 production；APP_DEBUG 生产必须 false（开启后异常页会暴露路径、配置与环境变量）。APP_URL 是最关键也最易错的一个：ProjectSend 生成给客户的下载链接、密码重置链接都以它为前缀，必须写成客户可达的地址（域名或公网 IP），写成内网地址会导致客户收到打不开的链接。实测环境把 APP_URL 设为 http://192.168.1.172:8135 后，php artisan about 的 URL 行即显示 192.168.1.172:8135（回显见第二章）。

APP_KEY 单独说明：首次启动由 entrypoint 生成并写入 storage/.env（首启日志实测输出 projectsend: generating APP_KEY (first boot, persisted to the storage volume)）。官方注释强调其不可变性——"一个在重启间变化的 key 会使每个会话失效、让所有加密列永久不可读（静默地，因为启动过程不报错）"。换服务器迁移时务必随 storage 卷带走它。

5.2 版本与下载投递通道（PROJECTSEND_*）

PROJECTSEND_EDITION 声明运行版本，社区自托管固定 community（projectsend:status 输出 ProjectSend 2.8.0 (community) 可核对；该值仅在官方托管平台场景才改动）。

PROJECTSEND_FILE_DELIVERY 决定文件下载时字节流怎么走出服务器，是这套系统最影响性能的单个参数：

💡 技术拓展：Web 应用的"文件下载投递"常见三种实现，性能差异巨大——

通道原理 PHP 进程占用适用
X-Accel（nginx）应用只下发内部重定向头，由 nginx 直接读盘发送不占用前置 nginx 的生产环境，最优
mod_xsendfile（Apache/LiteSpeed）同理，由 Apache 模块接管文件流不占用 Apache 环境
PHP 流式字节流全程经 PHP 进程转发整个下载期占用一个 worker 任何环境可用、性能最差

ProjectSend 的 PROJECTSEND_FILE_DELIVERY 取值：auto（默认；跑在 nginx 后自动交给 nginx，其余环境回落 php 流式）、nginx、xsendfile、php。官方注释并提示 xsendfile 需先在 Apache 里 XSendFilePath 放行 storage/app/files，nginx 模式需由前置 nginx 服务 /protected-files/ 路径。当前生效通道可在仪表盘 System 面板查看。

通道	原理	PHP 进程占用	适用
X-Accel（nginx）	应用只下发内部重定向头，由 nginx 直接读盘发送	不占用	前置 nginx 的生产环境，最优
mod_xsendfile（Apache/LiteSpeed）	同理，由 Apache 模块接管文件流	不占用	Apache 环境
PHP 流式	字节流全程经 PHP 进程转发	整个下载期占用一个 worker	任何环境可用、性能最差

本文实测环境为 Compose 直连形态（镜像内置 nginx 在前），未显式设置该参数，即 auto 生效。

PROJECTSEND_SCANNER_DEFAULT_ADDRESS：首启时把病毒扫描地址（如 tcp://clamav:3310）写入 settings 表一次性预置，此后以界面 Virus scanning 页为准、该变量被忽略；与官方模板中可选的 clamav 服务（compose profile scanner）配套使用。

5.3 数据库（DB_*）

六个参数构成一组：连接类型（仅 mysql）、主机、端口、库名、账号、口令。Compose 部署时 DB_HOST 写服务名 db，且必须与 db 服务的 MYSQL_DATABASE/MYSQL_USER/MYSQL_PASSWORD 完全一致。核对运行时生效值：

docker compose exec app php artisan config:show database

实测回显（mysql 连接段节选）：

  connections ⇁ mysql ⇁ driver ......................................... mysql
  connections ⇁ mysql ⇁ host .............................................. db
  connections ⇁ mysql ⇁ port ............................................ 3306
  connections ⇁ mysql ⇁ database ................................. projectsend
  connections ⇁ mysql ⇁ username ................................. projectsend
  connections ⇁ mysql ⇁ password .................................... q1w2e3r4
  connections ⇁ mysql ⇁ charset ...................................... utf8mb4
  connections ⇁ mysql ⇁ collation ......................... utf8mb4_unicode_ci
  connections ⇁ mysql ⇁ strict .......................................... true

（口令为本文系列统一的演示口令。）字符集默认 utf8mb4/utf8mb4_unicode_ci、strict 开启，均无需改动。官方 .env.example 提示：数据库与账号需先行建好，建表由 php artisan migrate 完成（entrypoint 每次启动自动执行）。

5.4 会话、缓存与队列（SESSION_/CACHE_/QUEUE_/REDIS_*）

三个驱动参数是"一组开关"，决定瞬时状态放哪里：

💡 技术拓展：SESSION_DRIVER/CACHE_STORE/QUEUE_CONNECTION 常见取值对比——

取值原理优点代价
database（官方默认）存 MySQL 会话/缓存/队列表零额外组件，备份一套搞定高并发下数据库承压
redis 存 Redis 读写快，队列吞吐好多一个组件要维护
file 存本地文件最简单不适合多实例，队列能力弱

官方 .env.example 原话："The database needs no extra software and is fine for most installs. If you have Redis, switch all three to 'redis' and fill in the REDIS_ lines below — it is faster under load."。本文实测采用 redis 三件套（官方镜像编排也默认带 Redis）。

取值	原理	优点	代价
database（官方默认）	存 MySQL 会话/缓存/队列表	零额外组件，备份一套搞定	高并发下数据库承压
redis	存 Redis	读写快，队列吞吐好	多一个组件要维护
file	存本地文件	最简单	不适合多实例，队列能力弱

REDIS_HOST/REDIS_PORT/REDIS_PASSWORD 仅在驱动切到 redis 后才有意义（Compose 部署写服务名 redis，端口默认 6379）。SESSION_LIFETIME 控制登录态有效期（分钟，默认 120）。切换驱动后必须 docker compose restart app 重启全部进程（supervisord 会在重启时把队列 worker 一并拉起，实测启动日志可见 queue、queue-zips、queue-scans、scheduler 四组 RUNNING）。

5.5 邮件（MAIL_*）

邮件参数在 2.8.0 中定位为兜底配置：官方注释明确"Mail is easier to configure from System → Settings → Email once you are logged in — it has a 'send test' button. These are the fallback until then."。也就是说界面配置一次后入库接管，MAIL_* 不再生效。MAIL_ENCRYPTION 取值 null（明文，仅本机 relay 用）/tls（STARTTLS，587 端口常用）/ssl（465 端口常用）；MAIL_FROM_ADDRESS 是客户收到通知邮件的发件地址，务必用存在回执的域名邮箱以免通知进垃圾箱。此外系统支持 OAuth 邮箱连接（有专门的 projectsend:refresh-mail-oauth-tokens 每日维护任务），同样在界面 Email 设置中配置。

5.6 反向代理与安全（TRUSTED_PROXIES / SESSION_SECURE_COOKIE / APP_DEBUG）

TRUSTED_PROXIES 是安全关键参数。官方注释的逻辑链：应用靠 X-Forwarded-For 头还原访客真实 IP；不设该参数时，凡有代理挡在前面，所有访客都"来自代理 IP"——登录限速把全体用户当一个攻击者、下载日志记错地址；而设成 *（信任任何来源）时，能直连应用端口的人可以伪造任意来源 IP，足以绕过登录锁定与所有按 IP 的限流。因此官方模板的做法是把端口绑到 127.0.0.1（唯有代理能连）并配 TRUSTED_PROXIES: "*"，同时注释强调"Change one and you have to change the other"。生产配置原则：端口绑定收紧到哪里，TRUSTED_PROXIES 就精确写到那个代理的地址/网段，逗号分隔支持 CIDR。

SESSION_SECURE_COOKIE 在整站 HTTPS 后开启，强制会话 Cookie 仅经加密连接传输。APP_DEBUG 见 5.1。

5.7 日志（LOG_*）

默认 LOG_CHANNEL=stack + LOG_STACK=daily：日志按天写入 storage/logs/laravel-YYYY-MM-DD.log 并由 LOG_DAILY_DAYS（默认 14）自动清理，官方注释指出这能让日志"在无人看管时也悄悄清掉旧文件、不会撑爆磁盘"；改成 single 则全部写入单个不滚动的 laravel.log，需要自配 logrotate。LOG_LEVEL 默认 warning。查看实测日志目录：

ls /srv/projectsend/storage/logs/

实测回显（应用运行两天后）：

laravel-2026-10-31.log
laravel-2026-11-01.log

（日志按天滚动、LOG_DAILY_DAYS 天后自动清理；队列 worker 与调度器的输出走进程管理器的标准输出，docker compose logs app 可见——两类日志渠道排障时先查文件、再查容器日志。）

5.8 管理员引导与环境预置（ADMIN_*）

ADMIN_NAME/ADMIN_EMAIL/ADMIN_PASSWORD 三个变量实现无人值守建号，语义是 --if-none：仅当系统里不存在任何账号时生效，已有账号后这三个变量被完全忽略（不会改密码）。两项硬校验实测：口令至少 12 个字符（不足报 The password field must be at least 12 characters.）；口令不得命中公开泄露库（命中报 The given password has appeared in a data leak.）。两项校验失败都会让首启初始化退出、容器重启循环——部署排障见《ProjectSend 2.8.0 Docker Compose 部署指南》第十一章。

六、生产配置模板

以下三个模板覆盖三种典型规模，均以 Compose environment 段形式给出（db/redis 服务的环境变量见部署篇），可直接替换对应段使用。

模板 A：小团队直连（≤50 客户，4GB 内存 / 100GB 磁盘，无反向代理）

    environment:
      APP_URL: http://192.168.1.10:8135      # 客户可达地址
      APP_ENV: production
      APP_DEBUG: "false"
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: projectsend
      DB_USERNAME: projectsend
      DB_PASSWORD: q1w2e3r4
      SESSION_DRIVER: database               # 无 Redis 场景用 database 三件套
      CACHE_STORE: database
      QUEUE_CONNECTION: database
      LOG_STACK: daily
      LOG_DAILY_DAYS: 14

适用说明：默认 database 驱动零额外组件，备份即"storage 目录 + 一份 mysqldump"；50 客户量级压力下官方默认值即够用。

模板 B：中型团队 + 反向代理 + Redis + 对象存储（8GB 内存 / 500GB+ 磁盘，nginx/CDN 在前）

    environment:
      APP_URL: https://files.example.com     # 必须是用户可达域名
      APP_ENV: production
      APP_DEBUG: "false"
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: projectsend
      DB_USERNAME: projectsend
      DB_PASSWORD: q1w2e3r4
      REDIS_HOST: redis
      SESSION_DRIVER: redis                  # Redis 三件套
      CACHE_STORE: redis
      QUEUE_CONNECTION: redis
      SESSION_SECURE_COOKIE: "true"          # 整站 HTTPS 后开启
      TRUSTED_PROXIES: "10.89.0.0/16"        # 精确到代理来源网段
      PROJECTSEND_FILE_DELIVERY: nginx       # 前置 nginx 卸载下载流量
      MAIL_MAILER: smtp
      MAIL_HOST: smtp.example.com
      MAIL_PORT: "587"
      MAIL_ENCRYPTION: tls
      MAIL_FROM_ADDRESS: files@example.com

适用说明：HTTPS + 代理后 TRUSTED_PROXIES 与代理网段必须成对收敛；大文件下载走 nginx 通道，PHP worker 只服务页面与 API；对象存储（S3/GCS）登录后在 System → Settings → Storage 配置，属入库设置无需环境变量。

模板 C：合规场景（病毒扫描 + 邮件审计，8GB 内存起步）

    environment:
      APP_URL: https://files.example.com
      APP_ENV: production
      APP_DEBUG: "false"
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: projectsend
      DB_USERNAME: projectsend
      DB_PASSWORD: q1w2e3r4
      REDIS_HOST: redis
      SESSION_DRIVER: redis
      CACHE_STORE: redis
      QUEUE_CONNECTION: redis
      TRUSTED_PROXIES: "*"
      PROJECTSEND_SCANNER_DEFAULT_ADDRESS: tcp://clamav:3310   # 首启预置，此后界面接管
      ADMIN_NAME: admin
      ADMIN_EMAIL: admin@example.com
      ADMIN_PASSWORD: Q1w2E3r4-doc-2026

适用说明：docker compose --profile scanner up -d 启用官方模板内置的 ClamAV 服务（官方注释预算 1–1.5GB 内存给病毒特征库，首次启动需等特征下载完成）；TRUSTED_PROXIES 取 * 的前提是端口仅回环绑定、唯有代理可达（官方模板默认形态）。

七、常见问题（FAQ）

Q1：改了 compose 里的环境变量但配置没生效？

按第三章三层优先级排查：先 php artisan about 或 config:show 看运行时实际值；若值来自旧启动，docker compose up -d（而非 restart）让环境变量变更触发容器重建；若值来自 settings 表（界面设置过），环境变量本来就不再管该项——去 System → Settings 改。

Q2：执行了 php artisan config:cache 后代理场景行为异常？

这正是官方警告的坑：配置缓存后 .env（与环境变量读取路径）被绕过，TRUSTED_PROXIES 静默失效。官方镜像每次启动都刻意清理配置缓存。解决：php artisan config:clear 后重启，并把这命令从运维手册里删掉。

Q3：APP_KEY 可以换吗？

运行中的安装不可换。key 加密着数据库里的敏感列；换 key 后旧数据解不开且无报错。仅在全新安装时按需注入；迁移服务器随 storage/.env 走。

Q4：ADMIN_PASSWORD 为什么设置了不生效？

两个原因之一：系统已存在任何账号（--if-none 语义，变量被忽略）；或口令未通过 ≥12 字符/泄露库校验导致首启失败。改管理员口令走 Web 界面个人设置；建补充管理员用命令行 projectsend:admin（见《ProjectSend 2.8.0 常用 CLI 命令与工具详解》）。

Q5：SESSION/CACHE/QUEUE 只切了其中一个驱动会怎样？

三者独立生效但建议成组切换：只切队列不切缓存不会报错，但日志、监控会呈现两套存储；官方与官方镜像编排都是三件套统一。切换后重启 app 进程组（supervisord 会同步重启 worker 与调度器）。

Q6：邮件发不出去怎么定位？

先看 System → Settings → Email 的"send test"按钮结果；界面未配置时才轮到 MAIL_* 兜底参数。排查顺序：MAIL_ENCRYPTION 与端口匹配（587+tls / 465+ssl）、发件地址域名信誉、以及容器到 SMTP 服务器的出站连通性。

八、参考链接

官方 .env.example（参数默认值与注释来源）：https://raw.githubusercontent.com/projectsend/projectsend/master/.env.example
官方 compose 模板（TRUSTED_PROXIES/扫描/邮件注释来源）：https://raw.githubusercontent.com/projectsend/projectsend/main/docker/production/compose.example.yaml
官方 INSTALL.md（zip 形态 .env 逐项说明）：https://raw.githubusercontent.com/projectsend/projectsend/master/INSTALL.md
系列文档：《ProjectSend 介绍与选型指南》、《ProjectSend 2.8.0 Docker Compose 部署指南》