中文

游戏服务器

安装 Pterodactyl 面板和 Wings

在您的 Linux 服务器上安装 Pterodactyl:面板、数据库、HTTPS、Docker、Wings、节点、端口、分配、第一个游戏服务器、更新和故障排除。

阅读约 12 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何在您的 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.您的域名.com

KVM 和 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-server

Debian 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-server

Ubuntu 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-server

Ubuntu 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-server

Composer 和检查

在所有系统上,安装 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 ping

php -v 应显示 8.3 版本,redis-cli ping 应返回 PONG。

步骤 3:创建数据库

生成一个密码并妥善保存:

终端
openssl rand -base64 24

打开 MariaDB。如果提示输入密码而您没有设置过,请按回车键。

终端
mariadb -u root -p
SQL
CREATE 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 wings
终端
chmod 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.conf
Nginx
server {
    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:在面板中创建节点

在面板的管理页面中:

  1. 打开 Locations,点击 Create New 并创建一个位置,例如 fr
  2. 打开 Nodes,然后点击 Create New
  3. 填写表单:
字段 值
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 留出余量。

  1. 创建完成后,打开该节点的 Configuration 选项卡,并复制显示的代码块
  2. 将其粘贴到服务器上,然后保护该文件,因为其中包含一个秘密令牌:
终端
nano /etc/pterodactyl/config.yml
chmod 600 /etc/pterodactyl/config.yml

Generate 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.target
终端
systemctl 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 进行测试:

  1. 按照创建 Garry's Mod 服务器中的说明创建 GSLT 令牌
  2. 打开 Servers,然后点击 Create New
  3. 填写名称、所有者、节点和一个空闲的分配
  4. 设置内存、磁盘和处理器的限制
  5. 选择 nest Source Engine 和 egg Garrys Mod
  6. 在 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 up

Wings

正在运行的游戏服务器不受影响。请将 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 检查服务。

官方资源