安装 Pterodactyl 面板和 Wings
在您的 Linux 服务器上安装 Pterodactyl:面板、数据库、HTTPS、Docker、Wings、节点、端口、分配、第一个游戏服务器、更新和故障排除。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何在您的 Linux 服务器上安装 Pterodactyl,通过网页界面管理您的游戏服务器。内容涵盖面板、Wings、HTTPS、端口、分配以及第一个游戏服务器。
HostMyServers 不提供托管式游戏主机服务:您需要自行安装和管理 Pterodactyl。本指南依据 1.x 稳定分支的项目官方文档。
订购服务器
Pterodactyl 可运行在 VPS 或专用服务器上:
请为面板、Docker 以及您打算运行的所有游戏服务器预留资源。
工作原理
| 组件 | 作用 |
|---|---|
| 面板 | PHP 网页应用:账户、服务器、权限。它使用 MariaDB 和 Redis |
| Wings | 安装在每台托管游戏的机器上的服务。它控制 Docker |
| 节点 | 运行 Wings、并已在面板中登记的机器 |
| 分配 | 分配给某个游戏服务器的 IP 地址和端口组合 |
| Egg | 描述如何安装和启动某个游戏的模板 |
本指南将面板和 Wings 安装在同一台机器上。若要把 Wings 放在另一台机器上,请在那台机器上执行步骤 9 至 13,在其上开放节点端口,并使用 certbot certonly --standalone 获取其证书,因为那里不需要网页服务器。
前提条件
- 一台 64 位服务器,系统为 Debian 12 或 13,或 Ubuntu 22.04 或 24.04
root访问权限或具有sudo权限的用户- 两个指向该服务器的子域名,并带有 DNS
A记录:panel.您的域名.com和node1.您的域名.com - 与 Docker 兼容的虚拟化
检查虚拟化类型和 DNS:
systemd-detect-virt
getent hosts panel.您的域名.com node1.您的域名.comKVM 和 none(物理机)均可。使用 openvz 或 lxc 时,Wings 很可能无法工作。
以下命令以 root 身份执行。请使用以下命令登录会话:
sudo -i使用的端口
| 端口 | 协议 | 服务 | 访问 |
|---|---|---|---|
| 22 | TCP | SSH | 管理 |
| 80 | TCP | Nginx、Let's Encrypt 验证和重定向 | 公开 |
| 443 | TCP | HTTPS 面板 | 公开 |
| 8080 | TCP | Wings API,供面板和浏览器使用 | 公开 |
| 2022 | TCP | Wings SFTP,用于服务器文件 | 公开 |
| 分配 | TCP 和 UDP | 游戏,例如 27015 至 27020 |
公开 |
MariaDB(3306)和 Redis(6379)仅限本地:请不要开放它们。
步骤 1:开放端口
使用 UFW 时,请在启用防火墙之前先允许 SSH;如果您更改过 SSH 端口,请相应调整:
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8080/tcp
ufw allow 2022/tcp
ufw enable
ufw status使用 iptables 或 nftables 时,请开放相同的 TCP 端口。安装 Docker 之后,请不要保存整个规则集,因为 Docker 会向其中添加自己的规则:请将您的规则添加到您的配置文件中。
步骤 2:安装面板依赖项
面板需要 PHP 8.2 或 8.3(推荐 8.3)、MariaDB 10.2 或更高版本、Redis、一个网页服务器和 Composer 2。请只运行与您的系统对应的代码块。
Debian 13
apt update
apt install -y curl ca-certificates gnupg2 sudo lsb-release
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/sury-php.list
curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/sury-keyring.gpg
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverDebian 12
apt update
apt install -y curl ca-certificates gnupg2 sudo lsb-release
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/sury-php.list
curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/sury-keyring.gpg
curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverUbuntu 24.04
apt update
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverUbuntu 22.04
apt update
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverComposer 和检查
在所有系统上,安装 Composer,启用 Redis,并检查版本:
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
systemctl enable --now redis-server
php -v
composer --version
mariadb --version
redis-cli pingphp -v 应显示 8.3 版本,redis-cli ping 应返回 PONG。
步骤 3:创建数据库
生成一个密码并妥善保存:
openssl rand -base64 24打开 MariaDB。如果提示输入密码而您没有设置过,请按回车键。
mariadb -u root -pCREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'GeneratedPassword';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
exit步骤 4:下载面板
mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/download/v1.15.2/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/步骤 5:配置面板
安装 PHP 依赖项并生成加密密钥:
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force
grep APP_KEY /var/www/pterodactyl/.env然后运行配置向导:
php artisan p:environment:setup
php artisan p:environment:database
php artisan p:environment:mail| 问题 | 建议的回答 |
|---|---|
| Egg Author Email | 您的电子邮件地址 |
| Application URL | https://panel.您的域名.com |
| Application Timezone | Europe/Paris 或您所在的时区 |
| Cache Driver、Session Driver 和 Queue Driver | redis |
| Enable UI based settings editor? | yes |
| Enable sending anonymous telemetry data? | 由您决定 |
| Redis Host 和端口 | 127.0.0.1 和 6379,默认的本地安装不设密码 |
| Database Host 和 Database Port | 127.0.0.1 和 3306 |
| Database Name | panel |
| Database Username | pterodactyl |
| Database Password | 步骤 3 中的密码 |
对于电子邮件,项目建议使用 SMTP 服务器,而不是 PHP 的内部发送。面板的遥测数据是匿名的,并已由项目文档说明。
创建数据表,然后创建您的管理员账户。迁移可能需要较长时间:请不要中断它。
php artisan migrate --seed --force
php artisan p:user:make
chown -R www-data:www-data /var/www/pterodactyl/*对 Is this user an administrator? 这个问题回答 yes。密码至少要有 8 个字符,并包含大写字母、小写字母和数字。
步骤 6:启用后台任务
打开 root 的 crontab:
crontab -e添加这一行:
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1创建队列服务:
nano /etc/systemd/system/pteroq.service# Pterodactyl Queue Worker File
# ----------------------------------
[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service
[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s
[Install]
WantedBy=multi-user.target启用它并检查其状态:
systemctl daemon-reload
systemctl enable --now pteroq.service
systemctl is-active pteroq.service该命令应返回 active。
步骤 7:获取 HTTPS 证书
面板和 Wings 各自需要一个证书。如果面板使用 HTTPS,Wings 也必须使用。
apt install -y certbot python3-certbot-nginx
certbot certonly --nginx -d panel.您的域名.com
certbot certonly --nginx -d node1.您的域名.com创建一个脚本,将续期后的证书应用到 Nginx 和 Wings:
nano /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh#!/bin/bash
systemctl reload nginx
systemctl try-restart wingschmod 750 /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh
certbot renew --dry-run重启 Wings 不会停止正在运行的游戏服务器。续期测试应无错误地完成。
步骤 8:配置 Nginx
删除默认站点,并创建面板的站点:
rm /etc/nginx/sites-enabled/default
nano /etc/nginx/sites-available/pterodactyl.confserver {
listen 80;
server_name panel.您的域名.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name panel.您的域名.com;
root /var/www/pterodactyl/public;
index index.php;
access_log /var/log/nginx/pterodactyl.app-access.log;
error_log /var/log/nginx/pterodactyl.app-error.log error;
# allow larger file uploads and longer script runtimes
client_max_body_size 100m;
client_body_timeout 120s;
sendfile off;
ssl_certificate /etc/letsencrypt/live/panel.您的域名.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/panel.您的域名.com/privkey.pem;
ssl_session_cache shared:SSL:10m;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
ssl_prefer_server_ciphers on;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header X-Robots-Tag none;
add_header Content-Security-Policy "frame-ancestors 'self'";
add_header X-Frame-Options DENY;
add_header Referrer-Policy same-origin;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param PHP_VALUE "upload_max_filesize = 100M \n post_max_size=100M";
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param HTTP_PROXY "";
fastcgi_intercept_errors off;
fastcgi_buffer_size 16k;
fastcgi_buffers 4 16k;
fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;
include /etc/nginx/fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}启用该站点:
ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
nginx -t
systemctl restart nginx打开 https://panel.您的域名.com,并使用步骤 5 中创建的账户登录。浏览器中的小锁图标应显示为有效。
步骤 9:安装 Docker
Wings 在 Docker 容器中运行每个游戏服务器。请按照安装 Docker Engine 和 Docker Compose指南安装 Docker Engine,然后确认它会随系统启动:
systemctl enable --now docker
docker info --format '{{.ServerVersion}}'如果 docker info 显示 WARNING: No swap limit support,并且您的内核版本低于 6.1,请在 /etc/default/grub 的 GRUB_CMDLINE_LINUX_DEFAULT 中添加 swapaccount=1,运行 update-grub 并重启。此设置是可选的。
步骤 10:安装 Wings
mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/download/v1.13.5/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
wings version此命令固定使用 v1.13.5 版本,即撰写时最新的 1.x 版本。安装之前,请查看 Wings 的版本。
步骤 11:在面板中创建节点
在面板的管理页面中:
- 打开 Locations,点击 Create New 并创建一个位置,例如
fr - 打开 Nodes,然后点击 Create New
- 填写表单:
| 字段 | 值 |
|---|---|
| Name | node1 |
| Location | 刚创建的位置 |
| FQDN | node1.您的域名.com |
| Communicate Over SSL | Use SSL Connection |
| Behind Proxy | Not Behind Proxy |
| Daemon Server File Directory | /var/lib/pterodactyl/volumes |
| Total Memory | 为游戏预留的内存,单位为 MiB |
| Memory Over-Allocation | 0 |
| Total Disk Space | 为游戏预留的磁盘,单位为 MiB |
| Disk Over-Allocation | 0 |
| Daemon Port | 8080 |
| Daemon SFTP Port | 2022 |
请为系统、面板、MariaDB 和 Docker 留出余量。
- 创建完成后,打开该节点的 Configuration 选项卡,并复制显示的代码块
- 将其粘贴到服务器上,然后保护该文件,因为其中包含一个秘密令牌:
nano /etc/pterodactyl/config.yml
chmod 600 /etc/pterodactyl/config.ymlGenerate Token 按钮还会提供一条命令,由它为您写入该文件。
步骤 12:启动 Wings
请先在前台运行 Wings,以便查看可能出现的错误:
wings --debug当它无错误运行后,使用 Ctrl+C 停止它,然后创建其服务:
nano /etc/systemd/system/wings.service[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
Requires=docker.service
PartOf=docker.service
[Service]
User=root
WorkingDirectory=/etc/pterodactyl
LimitNOFILE=4096
PIDFile=/var/run/wings/daemon.pid
ExecStart=/usr/local/bin/wings
Restart=on-failure
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s
[Install]
WantedBy=multi-user.targetsystemctl daemon-reload
systemctl enable --now wings
systemctl is-active wings
curl https://node1.您的域名.com:8080服务必须为 active。curl 命令应返回一条 JSON 消息,提示缺少授权:这证明 API 有响应且证书有效。在 Nodes 中,该节点应显示一个绿色的心形图标。
步骤 13:创建分配
查看服务器的 IP 地址:
hostname -I | awk '{print $1}'在 Nodes 中,打开您的节点,然后打开 Allocation 选项卡。在 Assign New Allocations 中:
- IP Address:刚才查到的地址,切勿使用
127.0.0.1 - IP Alias:可选,例如
node1.您的域名.com - Ports:一个端口或一个范围,例如
27015-27020
每个游戏服务器至少需要一个分配。Wings 会以 TCP 和 UDP 发布每一个分配。
步骤 14:创建第一个服务器
面板提供了适用于 Minecraft、Rust、Source 游戏和语音服务器的 Egg。使用 Garry's Mod 进行测试:
- 按照创建 Garry's Mod 服务器中的说明创建 GSLT 令牌
- 打开 Servers,然后点击 Create New
- 填写名称、所有者、节点和一个空闲的分配
- 设置内存、磁盘和处理器的限制
- 选择 nest Source Engine 和 egg Garrys Mod
- 在 Steam Account Token 中填入您的令牌,然后确认
安装过程会下载 Docker 镜像和游戏文件。然后在界面中打开该服务器,并点击 Start。当控制台进入在线状态时,服务器即已就绪。
检查安装
| 检查项 | 预期结果 |
|---|---|
systemctl is-active nginx php8.3-fpm mariadb redis-server pteroq wings docker |
每个服务均为 active |
https://panel.您的域名.com |
登录页面,证书有效 |
| Nodes | 节点上显示绿色心形图标 |
| 服务器控制台 | 实时显示日志 |
端口 2022 上的 SFTP |
可访问服务器的文件 |
| 连接游戏 | 服务器在其分配上有响应 |
备份
每次更新之前都要备份,并在服务器之外保留一份副本:
install -d -m 700 /root/pterodactyl-backups
DATE=$(date +%F_%H-%M)
mariadb-dump --single-transaction panel | gzip > /root/pterodactyl-backups/panel_$DATE.sql.gz
tar -czf /root/pterodactyl-backups/files_$DATE.tar.gz -C / var/www/pterodactyl etc/pterodactyl etc/nginx/sites-available/pterodactyl.conf
ls -lh /root/pterodactyl-backups这些归档文件包含机密信息,其中有 APP_KEY 和 Wings 的令牌。游戏数据另外存放在 /var/lib/pterodactyl/volumes 中,而通过面板创建的备份存放在 /var/lib/pterodactyl/backups 中。复制某个游戏服务器的文件之前,请先将其停止,以获得一致的副本。
更新
面板
请先备份,然后将 v1.15.2 替换为最新的 1.x 版本。请不要用这些步骤升级到 2.0,也不要在不指定版本的情况下使用 php artisan p:upgrade:升级到 2.0 有其专门的流程。
cd /var/www/pterodactyl
php artisan down
curl -L https://github.com/pterodactyl/panel/releases/download/v1.15.2/panel.tar.gz | tar -xzv
chmod -R 755 storage/* bootstrap/cache
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan view:clear
php artisan config:clear
php artisan migrate --seed --force
chown -R www-data:www-data /var/www/pterodactyl/*
php artisan queue:restart
php artisan upWings
正在运行的游戏服务器不受影响。请将 v1.13.5 替换为所需的版本:
cp -p /usr/local/bin/wings /usr/local/bin/wings.bak
systemctl stop wings
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/download/v1.13.5/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
systemctl restart wings回滚
恢复面板
请将 DATE 替换为您的归档文件的时间戳。这些命令会先检查两个归档文件,然后替换文件和数据库。自备份以来所做的更改会丢失。
tar -tzf /root/pterodactyl-backups/files_DATE.tar.gz > /dev/null
gunzip -t /root/pterodactyl-backups/panel_DATE.sql.gz
cd /var/www/pterodactyl
php artisan down
cd /
rm -rf /var/www/pterodactyl
tar -xzf /root/pterodactyl-backups/files_DATE.tar.gz -C / var/www/pterodactyl
mariadb -e 'DROP DATABASE panel; CREATE DATABASE panel;'
gunzip -c /root/pterodactyl-backups/panel_DATE.sql.gz | mariadb panel
cd /var/www/pterodactyl
php artisan config:clear
php artisan view:clear
php artisan queue:restart
php artisan up请务必将 .env 文件与数据库一起恢复,因为其中包含 APP_KEY。上面的归档文件已包含它。
恢复 Wings
systemctl stop wings
cp -p /usr/local/bin/wings.bak /usr/local/bin/wings
systemctl start wings故障排除
查看日志
tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log
journalctl -u wings -n 100 --no-pager
journalctl -u pteroq -n 50 --no-pager
tail -n 50 /var/log/nginx/pterodactyl.app-error.log节点一直显示红色,或控制台显示连接错误
- 使用
systemctl status wings检查 Wings,然后停止它并运行wings --debug - 将
/etc/pterodactyl/config.yml与节点的 Configuration 选项卡进行比对 - 检查端口
8080和2022是否已开放 - 测试
curl https://node1.您的域名.com:8080 - 检查面板和 Wings 是否都使用 HTTPS,并且证书有效
- 对这些域名禁用广告拦截器
- 如果您使用 Cloudflare,请对这些 DNS 记录禁用代理
nginx: [emerg] cannot load certificate
指定的证书不存在,或域名不匹配。请使用 certbot certificates 列出可用的证书。
the "listen ... http2" directive is deprecated
这只是新版本 Nginx 的警告,不影响运行。
502 Bad Gateway
PHP-FPM 没有响应。请检查 systemctl status php8.3-fpm 以及路径 /run/php/php8.3-fpm.sock。
failed to open stream: Permission denied
面板的文件不属于正确的用户:
chown -R www-data:www-data /var/www/pterodactyl/*SQLSTATE[HY000] [1045] Access denied for user 'pterodactyl'
密码或主机不匹配。请使用 127.0.0.1 作为主机,并重新运行 php artisan p:environment:database。
The MAC is invalid
.env 文件中的 APP_KEY 密钥与用于加密数据的密钥不一致。请恢复原来的密钥。没有它,这些数据无法恢复。
启动 Wings 时出现 bind: address already in use
另一个服务占用了该端口。请使用 ss -ltnp | grep -E ':8080|:2022' 找出它。
游戏服务器无法访问互联网
容器默认使用 DNS 1.1.1.1 和 1.0.0.1。如果这些地址在您的网络中被屏蔽,请在 /etc/pterodactyl/config.yml 的 docker 部分中替换它们,然后重启 Wings。
计划任务不执行
请使用 crontab -l 检查 crontab 中的那一行,然后使用 journalctl -xeu pteroq 和 systemctl restart pteroq 检查服务。