Coolify 4.4.6 配置参数详解

目标：逐项讲清 Coolify 4.4.6 的配置入口与参数体系——.env 环境变量（APP_/DB_/REDIS_/PUSHER_/ROOT_* 等）的实测默认值、生效方式、修改流程，以及平台内部按源码实查的扩展变量族，并给出生产配置模板。全部默认值与回显取自运行中的 4.4.6 实例（标注实测性：运行实例实查 / 源码默认值实查），查询日期 2026-10-21。

一、环境信息

二、前置条件

1. 已按 《Coolify 4.4.6 Docker Compose 部署指南》第四章或第五章完成部署并能登录控制台（本文命令均在部署机 /data/coolify/source 目录下执行）。
2. 理解 Coolify 的单一配置入口：.env 文件同时承担「编排插值」与「应用配置注入」两个角色，所有参数修改都围绕它进行。
3. 演示用命令中的账号为 root / q1w2e3r4（示例口令，生产请使用自己的强口令）。

三、参数查看与修改方式

3.1 查看生效配置

方式一：直接查看配置文件（密钥类值由安装时 openssl 自动生成，各实例不同）：

cd /data/coolify/source
grep -vE '=base64:|^$' .env | sed 's/=.*PASSWORD=.*/=<自动生成>/'

💡 说明：.env 中 APP_ID、APP_KEY、DB_PASSWORD、REDIS_PASSWORD、PUSHER_APP_ID/KEY/SECRET 均为安装时随机生成的实例级密钥，查看时注意不要外泄；上面命令把密钥值做了遮蔽处理。

方式二：平台自带的应用信息总览（Laravel 标准 about 命令，实测节选）：

docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml exec coolify php artisan about

  Application Name ................................................... Coolify
  Laravel Version .................................................... 12.69.3
  PHP Version ......................................................... 8.4.23
  Environment ..................................................... production
  Debug Mode ............................................................. OFF
  Maintenance Mode ....................................................... OFF

  Cache ......................................................................
  Config .............................................................. CACHED
  Events .............................................................. CACHED
  Routes .............................................................. CACHED
  Views ............................................................... CACHED

  Drivers ....................................................................
  Broadcasting ........................................................ reverb
  Cache ................................................................ redis
  Database ............................................................. pgsql
  Logs ........................................................ stack / single
  Mail ................................................................. array
  Queue ................................................................ redis
  Session ........................................................... database

  Sentry .....................................................................
  Enabled ........................................................ MISSING DSN
  Release .............................................................. 4.4.6

💡 说明：Drivers 段即核心运行时参数的生效结果——广播走 Reverb（实时通信）、缓存与队列走 Redis、元数据库 pgsql、会话走 database；Config CACHED 表示配置已缓存，修改 .env 后必须重建服务（见 3.2）才能生效。

方式三：关键探针验证：

curl -s http://localhost:8000/api/health

OK

3.2 修改参数的标准流程

.env 为只读挂载且配置已缓存，标准修改流程是「改文件 → 重建编排 → 验证」三步，以把 Web 端口改为 8400 为例：

cd /data/coolify/source
echo 'APP_PORT=8400' >> .env
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml down --remove-orphans
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans --wait --wait-timeout 60
curl -s http://localhost:8400/api/health

OK

⚠️ 注意：down 会中断控制台约 1 分钟，已部署的应用不受影响；APP_PORT 同时决定编排端口映射（${APP_PORT:-8000}:8080），改完同步调整防火墙放行。

3.3 升级对配置的保护

重跑官方安装脚本升级时，.env 先备份后合并，已有键保留原值、新键追加（脚本内 awk -F '=' '!seen[$1]++'），实测回显：

 - Creating backup of existing .env file to .env-20261021-080354
 - Merging .env.production values into .env
 - .env file merged successfully

因此手工追加的参数（APP_PORT、AUTOUPDATE 等）不会被官方模板覆盖；升级前也可手工再备份一份 cp .env .env.bak-$(date +%F)。

四、参数总览

按作用域分组的参数全景（实测性标注：「实例」= 运行实例 .env 实查；「源码」= 平台源码 config 默认值实查，未出现在实例 .env 中、按默认生效）：

💡 说明：Coolify 的参数体系分两层——.env 里显式出现的是「部署必需层」（约 20 个变量）；其余百余个是「可选调优层」，有默认值、不写即按默认生效，需要时追加进 .env 即可。

五、核心参数分类详解

5.1 应用核心（APP_*）

5.2 元数据库（DB_*）

5.3 队列缓存（REDIS_*）

5.4 实时通信（PUSHER_*）

💡 说明：控制台的实时日志、部署状态推送都走这条通道，PUSHER_BACKEND_PORT 与对外映射不一致会表现为「部署日志不动」。实时通信兼容 Pusher 协议，是 4.4 版起内置于主服务的组件（4.4 之前独立部署、由 soketi 占位服务兼容）。

5.5 管理员与登录（ROOT_*）

⚠️ 注意：三项仅在首次初始化时生效；运行后改密码用内置命令 php artisan root:reset-password（交互式，实测见命令篇），或控制台个人设置页修改。本文口令 q1w2e3r4 为演示值，生产务必替换强口令。

5.6 版本与仓库（REGISTRY_URL / LATEST_IMAGE / COOLIFY_VERSION）

5.7 Docker 网络地址池（DOCKER_ADDRESS_POOL_*）

💡 说明：Coolify 会为目标服务器上每个应用/服务创建独立网络，地址池决定可用网络数量；与既有网络环境冲突时用 DOCKER_POOL_FORCE_OVERRIDE=true 强制覆盖（脚本头注释变量，实测告警回显见部署篇问题 3）。

5.8 安装脚本行为变量（AUTOUPDATE / DOCKER_POOL_FORCE_OVERRIDE）

5.9 API 与限流（API_RATE_LIMIT）

5.10 SSH 连接族（SSH_*）

💡 说明：SSH 是平台驱动目标服务器的唯一通道，构建慢、部署中途断开等问题优先检查 SSH_COMMAND_TIMEOUT；批量部署大量小任务时调大 SSH_MUX_PERSIST_TIME 可减少重复握手。

5.11 队列与后台任务（HORIZON_* / SCHEDULED_JOBS_DISPATCH_MODE）

5.12 会话与日志（SESSION_* / LOG_*）

5.13 平台内部扩展变量清单（源码实查，按前缀分组）

以下变量均自 4.4.6 运行实例源码 /var/www/html/config/ 逐项枚举（2026-10-21 实查），未在实例 .env 显式出现时按源码默认生效。列出前缀族与用途，供按需追加：

六、生产配置模板

适用场景：8GB 内存 / 4 核 / NVMe SSD，承载中小团队十余个应用的通用生产配置。在部署篇方案 A/B 完成后，向 /data/coolify/source/.env 追加：

# —— 在部署机 /data/coolify/source/.env 追加 ——
# 对外端口（默认 8000，按需调整）
APP_PORT=8000
# 关闭自动升级，升级改窗口期手工执行
AUTOUPDATE=false
# 版本锁定（与官方发布同步手动推进）
LATEST_IMAGE=4.4.6
COOLIFY_VERSION=4.4.6
# API 自动化限流（有外部系统轮询调用时调高）
API_RATE_LIMIT=300
# 队列并发（默认 4，多应用并行部署可提到 8）
HORIZON_MAX_PROCESSES=8
# SSH 长构建超时（默认 3600，大型构建放宽）
SSH_COMMAND_TIMEOUT=7200

追加后执行 3.2 节三步流程重建生效。关键取舍：关 AUTOUPDATE 换升级可控（平台重启自选窗口）；HORIZON_MAX_PROCESSES 与内存预算线性相关（每进程为常驻工作进程）；其余保持默认——实测默认值已覆盖单机绝大多数场景，只加有明确理由的参数。

七、常见问题

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

主服务配置已缓存（about 实测 Config CACHED），且 .env 为只读挂载——改完必须执行 3.2 节的 down + up 重建编排；只 restart 不重建不换挂载内容同样不够。

Q2：APP_KEY 能换吗？

不能随意换。它是全平台加密根密钥，更换后既有会话、加密凭据不可解。仅在全新部署初始化前生成一次；误删后无外部备份时无法恢复，只能重建实例。

Q3：DB_USERNAME 可以改成自己的名字吗？

不要改。官方编排以该值初始化元数据库（POSTGRES_USER: ${DB_USERNAME}），改值会导致库初始化与连接不一致、平台起不来（脚本源码注释原文标注「Causes issues: database "random-user" does not exist」）。

Q4：想把元数据库迁到外接数据库集群怎么办？

填 DB_HOST/DB_PORT 指向外部地址并保证 DB_USERNAME/DB_PASSWORD/DB_DATABASE 与外库一致，同时在编排侧停用内置 postgres 服务；读写分离另有 DB_READ_HOST/DB_WRITE_HOST 族支持（源码实查）。迁移前先做元数据备份。

Q5：API 调用返回 429 太频繁？

调大 API_RATE_LIMIT（源码默认 200/分钟）并重建；请求方可复用 Token 减少握手。API 完整实测见命令篇。

八、参考链接

1. 本专栏部署篇（.env 生成与修改流程的完整实测）：《Coolify 4.4.6 Docker Compose 部署指南》
2. 本专栏认知篇：《Coolify 介绍与选型指南》
3. 本专栏命令篇（artisan 命令与 REST API 实测）：《Coolify 4.4.6 常用 CLI 命令与工具详解》
4. 官方文档站：https://coolify.io/docs （查询日期 2026-10-21）
5. 参数默认值取证来源：4.4.6 运行实例 /var/www/html/config/ 源码实查（2026-10-21）