Pterodactyl 1.15.2 配置参数详解

Pterodactyl Panel 1.15.2 配置四层体系(进程环境变量/.env/p:environment:* 命令/Laravel config)详解实测:44 键总览、APP_KEY 与 HASHIDS 风险区、数据库/Redis/邮件/日志逐项参数、p:info 与 config:show 聚合查看、缓存生效机制、生产配置模板与五类排障实录(Ubuntu 22.04 实测,2026-11-03)。

PterodactylPterodactyl面板LaravelPHP 编程2026/11/03

Pterodactyl 1.15.2 配置参数详解

目标:逐项讲清 Pterodactyl Panel 1.15.2 的配置分层(环境变量、.env 文件、p:environment:* 命令、Laravel config/ 文件)与全部关键参数的默认值、生效方式和改动影响。本文档基于 Ubuntu 22.04 服务器上 /app 部署目录的 Panel 1.15.2(PHP 8.3.36 + Laravel 12.64.0 + MariaDB 11.8.9 + Redis 8.10.3)实测整理。

一、环境信息

  • 操作系统:Ubuntu 22.04 LTS(x86_64)
  • 面板版本:Pterodactyl Panel 1.15.2(p:info 实测 Latest Version 1.15.2、Up-to-Date Yes)
  • 应用目录:/app(p:info 显示 Installation Directory /app),配置文件 /app/.env
  • 运行时:PHP 8.3.36、Laravel 12.64.0、Composer 2.10.3
  • 数据库:MariaDB 11.8.9(db:show 实测,面板库 panel 共 35 张表)
  • 缓存/会话/队列后端:Redis 8.10.3
  • Web 服务:nginx + PHP-FPM(监听 80,宿主机映射 8138)
  • 演示账号:admin / q1w2e3r4

💡 说明:本篇聚焦面板侧配置。节点侧 Wings 的配置文件(wings.toml)在节点主机上独立管理,不在本篇范围;面板与节点的通信参数(节点 token、监听端口)见「5.7 面板业务配置」与 CLI 命令篇。部署方式参见 《Pterodactyl Docker Compose 部署指南》,本篇不依赖该篇即可独立阅读。

二、前置条件

  • 已有一台部署好 Panel 1.15.2 的服务器(或已按任何方式装好面板并能访问应用目录)
  • 具备 shell 访问权限,可执行 php artisan 命令:
cd /app && php artisan --version
  • 改配置前建议备份 /app/.env(其中 APP_KEY 丢失不可恢复,见 5.2)

三、参数查看与修改方式

Pterodactyl 的配置有四个来源,优先级从高到低:进程环境变量 → /app/.env → p:environment:* 命令写入的 .env → Laravel config/*.php 默认值。四种查看/修改方式均实测。

3.1 查看进程环境变量(最高优先级)

env | sort

实测回显(节选面板相关变量):

APP_ENVIRONMENT_ONLY=false
APP_ENV=production
APP_SERVICE_AUTHOR=noreply@example.com
APP_TIMEZONE=Asia/Shanghai
APP_URL=http://127.0.0.1:8138
CACHE_DRIVER=redis
DB_DATABASE=panel
DB_HOST=database
DB_PASSWORD=q1w2e3r4
DB_PORT=3306
DB_USERNAME=pterodactyl
HASHIDS_LENGTH=8
MAIL_DRIVER=log
MAIL_FROM=noreply@example.com
QUEUE_DRIVER=redis
REDIS_HOST=cache
SESSION_DRIVER=redis

解说:本实例把配置全部经进程环境变量注入(部署编排的 environment 段),因此 /app/.env 里只有两个键(见 3.2)。环境变量与 .env 同名键冲突时,进程环境变量生效。

3.2 查看 .env 文件

cat /app/.env

实测回显:

APP_KEY=Xxlo1pXG2rakzCEU1bFlwEuTcBZjepTk
HASHIDS_SALT=(@aWpiAA<6GK(OgU*>?e

解说:官方发行包提供 /app/.env.example 模板(44 个键,见第四章总览),但运行中的面板 .env 可以只有这两行——APP_KEY 与 HASHIDS_SALT 是启动器自动生成、且无法从别处推导的两个秘密;其余键都可由环境变量提供。

3.3 用 p:environment:* 命令改配置

面板自带三个配置写入命令,实测 --help:

php artisan p:environment:setup --help
Description:
  Configure basic environment settings for the Panel.

Usage:
  p:environment:setup [options]

Options:
      --new-salt                   Whether or not to generate a new salt for Hashids.
      --author[=AUTHOR]            The email that services created on this instance should be linked to.
      --url[=URL]                  The URL that this Panel is running on.
      --timezone[=TIMEZONE]        The timezone to use for Panel times.
      --cache[=CACHE]              The cache driver backend to use.
      --session[=SESSION]          The session driver backend to use.
      --queue[=QUEUE]              The queue driver backend to use.
      --redis-host[=REDIS-HOST]    Redis host to use for connections.
      --redis-pass[=REDIS-PASS]    Password used to connect to redis.
      --redis-port[=REDIS-PORT]    Port to connect to redis over.
      --settings-ui[=SETTINGS-UI]  Enable or disable the settings UI.
      --telemetry[=TELEMETRY]      Enable or disable anonymous telemetry.
php artisan p:environment:database --help
Description:
  Configure database settings for the Panel.

Usage:
  p:environment:database [options]

Options:
      --host[=HOST]          The connection address for the MySQL server.
      --port[=PORT]          The connection port for the MySQL server.
      --database[=DATABASE]  The database to use.
      --username[=USERNAME]  Username to use when connecting.
      --password[=PASSWORD]  Password to use for this database.
php artisan p:environment:mail --help
Description:
  Set or update the email sending configuration for the Panel.

Usage:
  p:environment:mail [options]

Options:
      --driver[=DRIVER]          The mail driver to use.
      --email[=EMAIL]            Email address that messages from the Panel will originate from.
      --from[=FROM]              The name emails from the Panel will appear to be from.
      --encryption[=ENCRYPTION]  
      --host[=HOST]              
      --port[=PORT]              
      --endpoint[=ENDPOINT]      
      --username[=USERNAME]      
      --password[=PASSWORD]      

解说:这三个命令的本质是改写 /app/.env 对应键(如 p:environment:database --host=10.0.0.5 会把 DB_HOST=10.0.0.5 写进 .env),适合裸机安装场景;改完需重建配置缓存(3.5)才在 Web 侧生效。--settings-ui 控制是否允许在 Web 后台改设置,--telemetry 控制匿名遥测开关(见 5.7)。

3.4 查看 Laravel 配置目录

ls /app/config

实测回显:

activity.php
addons.php
app.php
auth.php
backups.php
broadcasting.php
cache.php
compile.php
cors.php
database.php
egg_features
filesystems.php
fractal.php
hashids.php
hashing.php
http.php
ide-helper.php
javascript.php
logging.php
mail.php
prologue
pterodactyl.php
queue.php
recaptcha.php
sanctum.php
services.php
session.php
trustedproxy.php
view.php

解说:config/*.php 是 Laravel 的键值装配层,绝大多数只是「读环境变量 + 给默认值」的胶水(如 config/database.php 把 DB_HOST 环境变量装配成连接参数),一般不直接改;面板业务参数集中在 pterodactyl.php(备份节流、活动日志保留期等)与 egg_features(Egg 特性开关目录)。可用 config:show 直接查看装配结果(实测节选):

php artisan config:show app
  app ........................................................................  
  name ........................................................... Pterodactyl  
  env ............................................................. production  
  debug ................................................................ false  
  url .................................................. http://127.0.0.1:8138  
  timezone ..................................................... Asia/Shanghai  
  locale .................................................................. en  
  cipher ......................................................... AES-256-CBC  
  key ....................................... Xxlo1pXG2rakzCEU1bFlwEuTcBZjepTk  

💡 说明:cipher 固定为 AES-256-CBC,它依赖 APP_KEY 工作——这解释了 5.2 中 APP_KEY 丢失的严重后果。

3.5 生效方式:配置缓存

php artisan about 实测显示 Config ... NOT CACHED。若执行过 config:cache,.env/环境变量的改动会被冻结进缓存,必须清理后才读到新值:

php artisan config:cache     # 冻结当前配置
php artisan optimize:clear   # 清除全部缓存(改配置后用)

实测回显:

   INFO  Configuration cached successfully.  
   INFO  Clearing cached bootstrap files.  

  config ......................................................... 1.04ms DONE
  cache .......................................................... 3.18ms DONE
  compiled ....................................................... 0.51ms DONE
  events ......................................................... 0.33ms DONE
  routes ......................................................... 0.43ms DONE
  views .......................................................... 3.08ms DONE

3.6 聚合查看:p:info

一条命令核对「合成后的生效配置」:

php artisan p:info

实测回显:

Version Information
===================

Panel Version     1.15.2              
Latest Version    1.15.2              
Up-to-Date        Yes                 
Unique Identifier noreply@example.com 

Application Configuration
=========================

Environment            <1>production         
Debug Mode             <1>No                 
Installation URL       http://127.0.0.1:8138 
Installation Directory /app                  
Timezone               Asia/Shanghai         
Cache Driver           redis                 
Queue Driver           redis                 
Session Driver         redis                 
Filesystem Driver      local                 
Default Theme                                
Proxies                                      

Database Configuration
======================

Driver   mysql       
Host     database    
Port     3306        
Database panel       
Username pterodactyl 

Email Configuration
===================

Driver       log                 
Host         127.0.0.1           
Port         2525                
Username                         
From Address noreply@example.com 
From Name    Pterodactyl Panel   
Encryption   tls                 

解说:<1> 前缀表示该值来自环境配置(而非 .env 文件);Proxies 为空表示未配置可信代理(TRUSTED_PROXIES,置于反向代理之后必须配置,否则活动日志记录到代理 IP)。

四、参数总览

.env.example 模板共 44 行,按功能分组如下(实测 cat /app/.env.example 全文):

APP_ENV=production
APP_DEBUG=false
APP_KEY=
APP_THEME=pterodactyl
APP_TIMEZONE=UTC
APP_URL=http://panel.example.com
APP_LOCALE=en
APP_ENVIRONMENT_ONLY=true

LOG_CHANNEL=daily
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pterodactyl
DB_PASSWORD=

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

CACHE_DRIVER=file
QUEUE_CONNECTION=redis
SESSION_DRIVER=file

HASHIDS_SALT=
HASHIDS_LENGTH=8

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=25
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Pterodactyl Panel"
# You should set this to your domain to prevent it defaulting to 'localhost', causing
# mail servers such as Gmail to reject your mail.
#
# @see: https://github.com/pterodactyl/panel/pull/3110
# MAIL_EHLO_DOMAIN=panel.example.com
分组键模板默认值本篇实例取值
应用基础APP_ENV / APP_DEBUGproduction / falseproduction / 关
应用基础APP_URLhttp://panel.example.comhttp://127.0.0.1:8138
应用基础APP_TIMEZONE / APP_LOCALEUTC / enAsia/Shanghai / en
应用基础APP_THEME / APP_ENVIRONMENT_ONLYpterodactyl / true默认 / false
加密与短 IDAPP_KEY / HASHIDS_SALT / HASHIDS_LENGTH空 / 空 / 8自动生成 / 自动生成 / 8
数据库DB_CONNECTION / DB_HOST / DB_PORT / DB_DATABASE / DB_USERNAME / DB_PASSWORDmysql / 127.0.0.1 / 3306 / panel / pterodactyl / 空database / 3306 / panel / pterodactyl
RedisREDIS_HOST / REDIS_PORT / REDIS_PASSWORD127.0.0.1 / 6379 / nullcache / 默认 / 无
后端驱动CACHE_DRIVER / SESSION_DRIVER / QUEUE_CONNECTIONfile / file / redis全部 redis
邮件MAIL_MAILER 等 8 键smtp + smtp.example.com:25log(只记日志)
日志LOG_CHANNEL / LOG_LEVEL / LOG_DEPRECATIONS_CHANNELdaily / debug / nulldaily / 默认

💡 技术拓展:DB_CONNECTION=mysql 并非「必须用 Oracle MySQL」——Laravel 的 mysql 连接驱动同时兼容 MariaDB。数据库可选方案:MySQL 5.7.22+/8.0、MariaDB 10.2+,或任何协议兼容的托管库;本实例用 MariaDB 11.8.9(db:show 实测)。

五、核心参数分类详解

5.1 应用基础参数

参数默认值详解
APP_ENVproduction运行环境。production 下 artisan 破坏性命令需 --force(实测 php artisan migrate 直接 Command cancelled,加 --force 才执行);local 下会放宽
APP_DEBUGfalse生产必须 false(实测 p:info Debug Mode No)。开启会把异常堆栈直接吐给浏览器,泄露路径与配置
APP_URL无默认(示例值)面板对外 URL。影响所有生成链接、邮件内链、节点回调地址;改后需 config:cache 重建
APP_TIMEZONEUTC面板显示时区(实测 Asia/Shanghai)。只影响展示与计划任务时间解读,不影响数据库存储(UTC)
APP_LOCALEen界面语言;1.15.x 内置多语言包,改后清缓存生效
APP_THEMEpterodactyl前端主题标识,官方默认主题即 pterodactyl
APP_ENVIRONMENT_ONLYtruetrue 时后台设置页只读、仅环境变量可改;本实例设 false 允许 Web 设置页修改(生产建议保持 true 收敛变更入口)
APP_SERVICE_AUTHOR无系统邮件与遥测标识用的服务负责人邮箱(实测 p:info 的 Unique Identifier 即该值)

5.2 加密与短 ID 参数(最高风险区)

参数默认值详解
APP_KEY空(须生成)AES-256-CBC 主密钥。加密数据库中所有敏感字段(节点 token、用户 2FA 密钥、OAuth secret 等)。丢失即不可恢复,只能重置相关数据
HASHIDS_SALT空(须生成)Hashids 盐,决定服务器/用户短 ID(URL 里的 8 位串)。改动会使既有短 ID 链接全部失效
HASHIDS_LENGTH8短 ID 长度。创建面板后不可更改(本实例显式保持 8)

实测本实例 .env 仅存这两个键(见 3.2),即官方安装器行为:php artisan key:generate 生成 APP_KEY,p:environment:setup --new-salt 管理 HASHIDS_SALT。

⚠️ 注意:APP_KEY 变更不报错、不提示,只会让旧密文静默变垃圾。任何自动化重建面板前,先备份 .env。

5.3 数据库参数

参数默认值详解
DB_CONNECTIONmysql连接驱动名(兼容 MariaDB)
DB_HOST127.0.0.1数据库地址(本实例内部服务名 database)
DB_PORT3306端口
DB_DATABASE / DB_USERNAMEpanel / pterodactyl库名与账号,须与数据库侧建库授权一致
DB_PASSWORD空账号口令;与缓存/会话共用 Redis 时注意口令分离

连通性验证实测:

php artisan db:show
  MariaDB ............................................................. 11.8.9  
  Connection ........................................................... mysql  
  Database ............................................................. panel  
  Host .............................................................. database  
  Port .................................................................. 3306  
  Username ....................................................... pterodactyl  
  Tables .................................................................. 35  

⚠️ 实测注意:db:show 末尾可能追加报错 The "intl" PHP extension is required to use the [format] method.——这是格式化「Open Connections」统计需要 PHP intl 扩展,不影响连接本身;装 php8.3-intl 或忽略均可。

5.4 缓存 / 会话 / 队列参数

参数默认值详解
CACHE_DRIVERfile应用缓存后端
SESSION_DRIVERfile登录会话存储
QUEUE_CONNECTIONredis队列后端(邮件、备份回调等异步任务)
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD127.0.0.1 / 6379 / null上述三个驱动指向 Redis 时的连接参数

💡 技术拓展:三类驱动可选后端对比——

后端特点适用
file落盘、零依赖、多进程共享差单机试装(模板默认)
redis内存级、共享一致、可持久化生产标配(官方推荐)
database存面板库,会话表膨胀风险不想多起服务的小规模
array / null进程内存,重启即失仅测试

本实例三者统一 redis(p:info 实测 Cache/Queue/Session Driver 均为 redis)。注意:QUEUE_CONNECTION 必须与常驻 worker 进程用同一后端,否则任务入队无人消费;实测 queue:failed 里能看到两条 redis@standard 通道的失败通知任务(演示环境邮件驱动为 log 时的正常现象)。

Redis 侧验证实测:

redis-cli info server | head -5
redis-cli dbsize
# Server
redis_version:8.10.3
redis_git_sha1:00000000
redis_git_dirty:1
redis_mode:standalone
1

5.5 邮件参数

参数默认值详解
MAIL_MAILERsmtp邮件通道;log 只写日志不发信(演示用),生产用 smtp
MAIL_HOST / MAIL_PORTsmtp.example.com / 25SMTP 服务器;p:info 实测生效值 127.0.0.1:2525(本地测试端口)
MAIL_USERNAME / MAIL_PASSWORD空SMTP 凭据;属系统级真实密钥,不要提交进版本库,用环境变量注入(如 export MAIL_PASSWORD='...' 后由进程环境提供)
MAIL_ENCRYPTIONtls传输加密;null/tls/ssl 三选
MAIL_FROM_ADDRESS / MAIL_FROM_NAMEno-reply@example.com / Pterodactyl Panel发件地址与署名
MAIL_EHLO_DOMAIN注释掉的示例EHLO 主机名。模板注释明确:不设会默认 localhost,Gmail 等运营商会拒信(官方 PR #3110)

💡 技术拓展:MAIL_MAILER 可选通道——smtp(标准投递,生产唯一推荐)、log(写日志,测试/演示)、array(内存,仅测试断言)、sendmail(依赖本机 MTA)。本实例演示环境取 log。

5.6 日志参数

参数默认值详解
LOG_CHANNELdaily日志通道;daily 按日切分(实测日志目录存在 laravel-2026-11-03.log),single 单文件
LOG_LEVELdebug最低记录级别;生产建议 warning 以上控制体量
LOG_DEPRECATIONS_CHANNELnull弃用告警独立通道,null 表示不单独记录

日志目录挂载/备份建议纳入运维清单:按日切分的文件在长期运行实例会累积(实测单日文件约 46KB),LOG_LEVEL=debug 时增长更快。

5.7 面板业务配置(pterodactyl.php 与遥测)

config/pterodactyl.php 承载面板业务参数(备份节流间隔、活动日志保留、API 限速等),配合后台「Settings」页(受 APP_ENVIRONMENT_ONLY 控制)使用。匿名遥测可用 p:telemetry 查看将要上报的全部内容(实测节选):

php artisan p:telemetry
 [INFO] Collecting telemetry data, this may take a while...                     

array:4 [
  "id" => "95711fb7-294c-4350-8f04-c4c5e9e68cb3"
  "panel" => array:3 [
    "version" => "1.15.2"
    "phpVersion" => "8.3.36"
    "drivers" => array:3 [
      "backup" => array:1 ["type" => "wings"]
      "cache" => array:1 ["type" => "redis"]
      "database" => array:2 ["type" => "mysql", "version" => "11.8.9-MariaDB-ubu2404"]
    ]
  ]
  "resources" => array:9 [
    "allocations" => array:2 ["count" => 0, "used" => 0]
    "eggs" => array:1 ["count" => 14]
    "locations" => array:1 ["count" => 2]
    "nests" => array:1 ["count" => 4]
    "nodes" => array:1 ["count" => 2]
    "servers" => array:2 ["count" => 0, "suspended" => 0]
    "users" => array:2 ["count" => 2, "admins" => 1]
  ]
  "nodes" => []
]

解说:遥测只含版本/驱动/资源计数,不含主机名与业务数据;如合规要求禁止外报,用 p:environment:setup --telemetry=false 关闭(或后台设置页)。schedule:list 中可见内置任务 7 5 * * * Collect Telemetry(每周采样一次)。

六、生产配置模板

适用场景:8GB 内存 / 100GB SSD 单机面板,管理 1~5 个 Wings 节点、≤50 台游戏服务器。环境变量清单(部署编排注入或写入 .env):

# ===== 应用 =====
APP_ENV=production
APP_DEBUG=false
APP_URL=https://panel.example.com
APP_TIMEZONE=Asia/Shanghai
APP_LOCALE=zh_CN
APP_ENVIRONMENT_ONLY=true
APP_SERVICE_AUTHOR=ops@example.com

# ===== 加密(务必备份,丢失不可恢复)=====
APP_KEY=<base64:32字节,php artisan key:generate 生成>
HASHIDS_SALT=<随机 20 字符,p:environment:setup --new-salt 生成>
HASHIDS_LENGTH=8

# ===== 数据库 =====
DB_CONNECTION=mysql
DB_HOST=10.0.0.10
DB_PORT=3306
DB_DATABASE=pterodactyl
DB_USERNAME=pterodactyl
DB_PASSWORD=<强口令,经密钥管理注入>

# ===== Redis(缓存/会话/队列统一)=====
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
REDIS_HOST=10.0.0.11
REDIS_PORT=6379
REDIS_PASSWORD=<强口令>

# ===== 邮件(真实 SMTP,凭据用环境变量注入,勿入库)=====
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=465
MAIL_USERNAME=panel@example.com
MAIL_PASSWORD=${SMTP_PASSWORD}
MAIL_ENCRYPTION=ssl
MAIL_FROM_ADDRESS=panel@example.com
MAIL_FROM_NAME="Game Panel"
MAIL_EHLO_DOMAIN=panel.example.com

# ===== 日志 =====
LOG_CHANNEL=daily
LOG_LEVEL=warning

要点解读:

  • APP_ENVIRONMENT_ONLY=true:把变更入口收敛到环境变量/配置管理,防止 Web 页误改。
  • MAIL_PASSWORD=${SMTP_PASSWORD}:系统级真实密钥不落文件,由进程环境注入(export SMTP_PASSWORD='...' 或编排平台 secrets)。
  • LOG_LEVEL=warning:游戏面板日常 INFO 量大(队列/计划任务),降级别控制磁盘。
  • 反代之后部署:追加 TRUSTED_PROXIES 配置(见 3.6 Proxies 字段说明),否则活动日志全是代理 IP。

七、常见问题(FAQ)

Q1:php artisan env:show 报 Command "env:show" is not defined.?

实测复现:

$ php artisan env:show

   ERROR  Command "env:show" is not defined. Did you mean one of these?  

  ⇂ config:show  
  ⇂ db:show

原因:Pterodactyl 是 Laravel 应用,没有 env:show 命令。查看生效配置用 p:info(面板视角)或 config:show app(Laravel 视角),见 3.4/3.6。

Q2:改了 .env 里的 APP_URL 但页面链接没变?

大概率配置被缓存冻结。php artisan about 看 Config ... CACHED 即实锤,执行 php artisan optimize:clear 后重建(实测回显见 3.5)。若 .env 与进程环境变量同名键并存,进程环境变量优先(见 3.1),改 .env 无效——先查编排侧注入。

Q3:p:user:disable2fa 之类的用户参数怎么传?

实测 p:user:disable2fa --help 显示只接受 --email=<邮箱> 选项,无位置参数;传错形态会报 No arguments expected(与 p:user:delete 同类,详见 CLI 命令篇)。

Q4:面板反复重连数据库 / SQLSTATE[...]?

核对 DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD 与数据库侧实际授权;用 php artisan db:show(5.3)验证连通,再查数据库错误日志。db:show 尾部的 intl 报错不影响连接判断。

Q5:想彻底重置短 ID(HASHIDS_SALT)?

php artisan p:environment:setup --new-salt 可生成新盐,但所有既有服务器/用户短 ID URL 立即失效(书签、API 调用方全部要改),生产严禁随意执行。

八、参考链接

Pterodactyl 1.15.2 配置参数详解 - Quzuo