Pelican Panel v1.0.0-rc.2 配置参数详解
Pelican Panel v1.0.0-rc.2 三层配置体系（.env/进程环境变量/入口脚本开关）实测详解：p:info 全文解读、参数总览表、APP_URL 派生 Caddy 监听、代理与 TLS 六形态、redis 三驱动、config:cache 官方禁用（动态插件）、生产配置模板与 6 条 FAQ，全部取值为实测值。
Pelican Panel v1.0.0-rc.2 配置参数详解
目标：把 Pelican Panel v1.0.0-rc.2 的配置体系讲透——
.env键位、进程环境变量、启动入口脚本（entrypoint.sh）识别的开关三层，给出每个参数的实测默认值、修改方式与生效验证。本文全部回显为 2026-11-02/03 在 Ubuntu 24.04.5 + PHP 8.5.12 + MariaDB 10.11 + Redis 环境实测；部署过程见 《Pelican Panel Docker Compose 部署指南》。
一、环境信息
| 项目 | 值 |
|---|---|
| 组件 | Pelican Panel v1.0.0-rc.2 |
| 运行时 | PHP 8.5.12 / Laravel 13.38.0 / Filament v5.10.2 / Livewire v4.4.7（php artisan p:info 实测） |
| 程序目录 | /var/www/html（p:info 实测 Installation Directory） |
| 数据目录 | /pelican-data（XDG_DATA_HOME 指定；.env、caddy、database、storage、plugins 均在此） |
| 配置文件 | /pelican-data/.env（webroot /var/www/html/.env 为指向它的符号链接） |
| 数据库 | MariaDB 10.11，库 panel，账号 pelican/q1w2e3r4（演示口令） |
| 缓存/会话/队列 | Redis（redis:alpine） |
| 访问地址 | http://192.168.1.172:8132（APP_URL） |
| 演示账号 | root / q1w2e3r4 |
| 实测日期 | 2026-11-02/03 |
💡 技术拓展：Pelican 的配置面与"裸机 Laravel 应用"不同，官方分发把配置拆成三层——
层 载体 覆盖内容 .env文件/pelican-data/.env仅 APP_KEY/APP_INSTALLED/APP_URL三键（实测）进程环境变量 编排文件 environment:注入DB/Redis/驱动/代理开关等全量 入口脚本开关 entrypoint.sh 识别的变量 迁移行为、Caddy/TLS、可信代理 优先级：entrypoint.sh 源码注释明确"the container environment takes precedence, matching Laravel's own behavior"——同名变量以进程环境变量为准，
.env兜底。本文按这三层逐一展开。
二、前置条件
- 面板已按部署篇完成安装（
APP_INSTALLED=true、迁移 255 条全部 Ran、管理员root已建）； php artisan可用（程序目录/var/www/html下执行，实测）：
$ php artisan --version
Laravel Framework 13.38.0
- 对
/pelican-data/.env有读写权限（面板进程用户www-data，UID 82）； - 数据库与 Redis 连通（
p:infoDrivers 段实测：db=mariadb，cache/queue/session=redis）。
三、参数查看与修改方式
3.1 运行时全景：php artisan p:info
一条命令输出应用、缓存、驱动、Filament、版本全部生效值（实测全文）：
Environment ................................................................
Application Name ................................................... Pelican
Laravel Version .................................................... 13.38.0
PHP Version ......................................................... 8.5.12
Composer Version .................................................... 2.10.3
Environment ..................................................... production
Debug Mode ............................................................. OFF
URL ..................................................... 192.168.1.172:8132
Maintenance Mode ....................................................... OFF
Timezone ............................................................... UTC
Locale .................................................................. en
Installation Directory ....................................... /var/www/html
Cache ......................................................................
Config .......................................................... NOT CACHED
Events .......................................................... NOT CACHED
Routes .......................................................... NOT CACHED
Views ............................................................... CACHED
Drivers ....................................................................
Broadcasting .......................................................... null
Cache ................................................................ redis
Database ........................................................... mariadb
Logs ................................................................. daily
Mail ................................................................... log
Queue ................................................................ redis
Session .............................................................. redis
Storage ....................................................................
public/storage ...................................................... LINKED
Filament ...................................................................
Blade Icons ......................................................... CACHED
Packages filament, forms, notifications, support, tables, actions, infolists, schemas, widgets
Panel Components .................................................... CACHED
Version ............................................................ v5.10.2
Views ........................................................ NOT PUBLISHED
Livewire ...................................................................
Livewire ............................................................ v4.4.7
Spatie Permissions .........................................................
Features Enabled ................................................... Default
Version .............................................................. 8.3.2
Pelican ....................................................................
Latest Version .................................................. 1.0.0-rc.2
Panel Version ................................................... 1.0.0-rc.2
Up-to-Date ............................................................. Yes
解读要点：Config/Events/Routes 三项 NOT CACHED 是官方设计（入口脚本注释：Settings 在 .env 运行时编辑、插件在运行时注册提供者与路由，缓存会把它们冻结到下次重启）；Views CACHED 则由入口脚本每次启动执行 view:cache 生成。
3.2 直接读配置文件
$ cat /pelican-data/.env
APP_KEY=base64:Y/r7AYk2MUDviAR0peoZxNg0sOWCvhMCgM2K5LB0VeA=
APP_INSTALLED=true
APP_URL="http://192.168.1.172:8132"
官方分发形态下 .env 只有这三行——其余键全走进程环境变量注入。分发内置的出厂模板 /var/www/html/.env.example 实测共 6 行（APP_ENV、APP_DEBUG、APP_KEY、APP_URL、APP_INSTALLED、APP_LOCALE），裸机自建 PHP 环境时按它铺全量 .env。
3.3 修改方式与生效验证
| 方式 | 操作 | 生效 |
|---|---|---|
改 .env | 如 sed -i 's/^APP_INSTALLED=false/APP_INSTALLED=true/' /pelican-data/.env（实测用于安装收尾） | 面板进程重启后生效 |
| 改编排环境变量 | 编辑部署篇 compose 的 environment: 后重建面板 | 重建即生效 |
| artisan 命令族 | php artisan p:environment:setup/cache/database/mail/queue/session、p:redis:setup（参数详解见本专栏 《Pelican Panel v1.0.0-rc.2 常用 CLI 命令与工具详解》） | 写 .env/配置后重启生效 |
| 清应用缓存 | php artisan cache:clear | 实测回显 INFO Application cache cleared successfully. |
| 配置缓存 | php artisan config:cache | 被官方禁用，实测回显 WARN Configuration caching has been disabled.（原因见 5.6） |
⚠️ 注意：修改
APP_URL后必须重启面板进程——内置 Caddy 的站点地址与监听端口由APP_URL派生（CADDY_APP_URL），不重启不生效；部署篇 4.8 的 healthcheck 误报就是该机制的直接后果。
四、参数总览
按层分类的全量参数（默认值/实测值均出自部署环境）：
| 分类 | 键 | 实测值（默认） | 说明 |
|---|---|---|---|
| 应用身份 | APP_ENV | production | 运行环境；production 下迁移需 --force |
| 应用身份 | APP_DEBUG | false | 调试开关 |
| 应用身份 | APP_KEY | base64:...（自动生成） | 加密密钥，写入 .env |
| 应用身份 | APP_URL | http://192.168.1.172:8132 | 面板地址，派生 Caddy 站点 |
| 应用身份 | APP_INSTALLED | true | 安装状态机开关 |
| 应用身份 | APP_LOCALE | en（.env.example 默认） | 界面语言 |
| 数据库 | DB_CONNECTION | mariadb | 支持 mysql/mariadb/pgsql |
| 数据库 | DB_HOST/DB_PORT | database/3306 | 连接地址 |
| 数据库 | DB_DATABASE/DB_USERNAME/DB_PASSWORD | panel/pelican/q1w2e3r4 | 库与账号 |
| 驱动 | CACHE_STORE | redis | 缓存驱动 |
| 驱动 | SESSION_DRIVER | redis | 会话驱动 |
| 驱动 | QUEUE_CONNECTION | redis | 队列驱动 |
| 驱动 | REDIS_HOST/REDIS_PORT/REDIS_USER/REDIS_PASS | cache/默认 6379/空/空 | Redis 连接 |
| 邮件 | MAIL_DRIVER | log | 演示环境不发真信 |
| 邮件 | MAIL_HOST/MAIL_PORT/MAIL_USERNAME/MAIL_PASSWORD/MAIL_ENCRYPTION/MAIL_FROM_ADDRESS/MAIL_FROM_NAME | 未设 | SMTP 参数 |
| Web/代理 | BEHIND_PROXY | 未设（false） | 反代模式开关 |
| Web/代理 | TRUSTED_PROXIES | 未设 | 可信代理列表 |
| Web/代理 | ASSET_URL | 未设（BEHIND_PROXY 时=APP_URL） | 资产 URL |
| Web/代理 | LE_EMAIL | 未设 | https 自动证书邮箱 |
| Web/代理 | SKIP_CADDY | 未设（false） | 只跑 php-fpm |
| 运维 | SKIP_MIGRATIONS | 未设（false） | 多副本共库时关闭自动迁移 |
| 数据目录 | XDG_DATA_HOME | /pelican-data | 数据目录 |
五、核心参数分类详解
5.1 应用身份与安装状态机
APP_KEY：入口脚本首启若无则head -c 32 /dev/urandom | base64生成并写入.env（源码实测）。换 key 会使已加密字段（如 API token、OAuth 凭据）不可解，备份.env即备份密钥。APP_INSTALLED：安装状态机的核心。false→ Web 根路径 302 进/installer向导、启动不迁移；true→/installer关闭（实测 404）、启动先nc探库再php artisan migrate --force。实测状态流转见部署篇 4.6。APP_URL：决定站点地址与 Caddy 监听端口（http://host:8132→ 监听 8132）。改端口需同步改编排文件的端口映射，否则页面资源 404。
5.2 数据库连接
DB_CONNECTION 实测取 mariadb；p:environment:database 的 help 证实支持 MySQL/MariaDB/PostgreSQL（--schema 仅 PG 用）。入口脚本在 APP_INSTALLED=true 且非 sqlite 时循环 nc -z -v -w30 "${DB_HOST}" "${DB_PORT}" 等待数据库就绪（实测日志回显 Checking database status. → database (10.89.59.3:3306) open），因此编排层 depends_on 只是第一道保险，真正的就绪判定靠这段等待。
5.3 缓存 / 会话 / 队列三驱动
💡 技术拓展：Laravel 三类驱动的可选项不止 redis——
驱动 键 常见可选 特点 缓存 CACHE_STOREfile/redis/database/arrayfile 零依赖；redis 最快且多副本共享 会话 SESSION_DRIVERfile/redis/database/cookie多副本必须共享存储（redis/database） 队列 QUEUE_CONNECTIONsync/database/redissync 仅适合开发；生产用 redis/database 官方 Compose 形态三者统一
redis（实测p:infoDrivers 段一致），p:redis:setup一条命令即可把三驱动全指到 Redis——本方案因面板可能多副本且队列吞吐要求高，采用 redis。
对应修改命令（参数详解见 CLI 篇）：p:environment:cache、p:environment:session、p:environment:queue 各自带 --driver 与 --redis-host/--redis-user/--redis-pass/--redis-port；p:redis:setup 一次配齐三项。
5.4 Web 服务器与代理开关（入口脚本层）
entrypoint.sh 源码实测逻辑（原文摘录）：
| 场景 | 变量组合 | 脚本行为（实测源码） |
|---|---|---|
| 默认（http 直连） | 仅 APP_URL=http://... | CADDY_APP_URL=${APP_URL}，内置 Caddy 按该地址监听 |
| https + 自动证书 | APP_URL=https://... + LE_EMAIL=you@example.com | CADDY_LE_EMAIL="email ${LE_EMAIL}"，Caddy 走 Let's Encrypt |
| https 但没给邮箱 | APP_URL=https://... 且 LE_EMAIL 空且非反代 | 直接退出 1：when app url is https a lets encrypt email must be set when not behind a proxy |
| 反代终结 TLS | BEHIND_PROXY=true | CADDY_APP_URL=":80"、CADDY_AUTO_HTTPS="auto_https off"、ASSET_URL=${APP_URL} |
| 可信代理 | TRUSTED_PROXIES=10.0.0.1,172.16.0.0/12 | 逗号转空格注入 trusted_proxies static ... 并开启 trusted_proxies_strict |
| 自备 Web | SKIP_CADDY=true | 只起 php-fpm（Starting PHP-FPM only）；内置 healthcheck 的 curl 段也随之跳过（见 healthcheck.sh 的 SKIP_CADDY 判断） |
⚠️ 注意：
TRUSTED_PROXIES同时被入口脚本读入环境（加载列表含此键），Laravel 侧的代理信任与 Caddy 侧的trusted_proxies共用这一个变量，反代场景务必设置，否则日志里客户端 IP 全是代理 IP。
5.5 运维开关
SKIP_MIGRATIONS=true：多副本共库时，从副本关闭启动迁移，避免并发 migrate。实测部署篇"等价单命令"一节回显Skipping migrations (SKIP_MIGRATIONS=true)生效。XDG_DATA_HOME=/pelican-data：把 Laravel storage、caddy 数据、composer 缓存、插件目录收敛到单一数据卷；.env也在其中（webroot.env是符号链接）。- 日志驱动实测
logs=daily（p:info），日志文件落/var/www/html/storage/logs（独立卷pelican-logs），按日切割。
5.6 配置缓存被禁用（重要）
实测 php artisan config:cache：
WARN Configuration caching has been disabled.
Reason: This application uses dynamic plugins. Caching config
prevents /plugins/config/*.php files from being loaded correctly.
入口脚本注释同样说明：config/route/event caches are intentionally NOT built here。这是架构约束不是 bug：插件在运行时注册服务提供者与路由，配置缓存会冻结插件的加载。需要清缓存时用 php artisan cache:clear（实测 INFO Application cache cleared successfully.）。
六、生产配置模板（单机 4GB 内存 / NVMe / 中小服主社群）
适用场景：一台 4GB 内存控制面 + 若干 Wings 节点，域名经 Nginx/Caddy 反代终结 TLS。以进程环境变量清单给出（编排文件 environment: 段等价落位）：
# 应用身份
APP_ENV=production
APP_DEBUG=false
APP_URL=https://panel.example.com # 反代模式，URL 用对外域名
BEHIND_PROXY=true # 内置 Caddy 转 :80 监听、关 auto_https
TRUSTED_PROXIES=127.0.0.1,10.89.59.0/24 # 反代与编排网段
ASSET_URL=https://panel.example.com # BEHIND_PROXY=true 时脚本自动置为 APP_URL
# 数据库（生产口令用强随机值，经编排文件 secrets 或环境注入，勿明文入库）
DB_CONNECTION=mariadb
DB_HOST=database
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pelican
DB_PASSWORD=${PANEL_DB_PASSWORD} # 先 export PANEL_DB_PASSWORD='<强口令>' 再注入
# 三驱动 + Redis
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
REDIS_HOST=cache
REDIS_PORT=6379
# 邮件（生产必须真发信：找回密码/安全告警依赖）
MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=panel@example.com
MAIL_PASSWORD=${SMTP_PASSWORD} # 同上，export 后注入
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=panel@example.com
MAIL_FROM_NAME="Pelican Panel"
# 运维
SKIP_MIGRATIONS=false # 单副本保持默认自动迁移
XDG_DATA_HOME=/pelican-data
解读：4GB 内存下 MariaDB+Redis+PHP-FPM 同机可行（实测本演示栈 838MB 面板 + 459MB 数据库 + 162MB Redis 的磁盘占用，内存占用远低于 4GB）；MAIL_DRIVER 演示用 log，生产务必换 smtp；BEHIND_PROXY=true 时不要再设 LE_EMAIL（证书交给反代）。
七、常见问题
7.1 p:info 显示 Config NOT CACHED，是不是没优化到位？
不是。官方显式禁用配置缓存（动态插件约束，见 5.6），NOT CACHED 才是正确状态；Views/Blade Icons/Panel Components 已 CACHED。
7.2 .env 里加一行 DB_HOST=xx 为什么不生效？
同名变量进程环境变量优先（入口脚本源码：already set in environment, skipping）。官方 Compose 形态 DB 参数在编排 environment: 里，.env 写了也会被跳过。二选一：删掉编排侧的该键，或只改编排侧。
7.3 .env 的值带引号/带 $() 会怎样？
入口脚本加载 .env 特定键时：含 $( 或反引号的行直接跳过（实测源码注释与回显 var in .env may be executable, skipping，防命令注入）；值两侧引号会被 tr -d "\r\"'" 剥掉（兼容 Windows 编辑）。所以 .env 里不要写需要 shell 展开的语法。
7.4 改了 APP_URL 端口后面板打不开
Caddy 站点随 APP_URL 重建监听端口，但编排层端口映射不会自动跟着变。改 APP_URL 端口后需同步修改端口映射并重建面板（实测流程见部署篇 4.6 第 4 步）。
7.5 忘记管理员口令
CLI 路线：php artisan p:user:make 重建管理员（参数见 CLI 篇），或数据库侧用 Hash::make() 生成新哈希回填 users.password（tinker 实测可行：Hash::check('q1w2e3r4', ...) 返回 bool(true) 即验证闭环）。
7.6 界面语言/时区在哪改？
APP_LOCALE（.env.example 默认 en）与 Filament 后台设置页；p:info 实测 Timezone=UTC。中文语言包随主题/语言包机制加载（rc.2 changelog："Always load themes & language packs on all panels"）。
八、参考链接
- 官方仓库：https://github.com/pelican/panel
- 官方 Artisan Commands 文档页（Updated 01/11/2026，本专栏 CLI 篇素材源）
- 官网：https://pelican.dev
- 站内相关：《Pelican Panel 介绍与选型指南》、《Pelican Panel Docker Compose 部署指南》、《Pelican Panel v1.0.0-rc.2 常用 CLI 命令与工具详解》
（全部参数与回显实测日期 2026-11-02/03。）