Pterodactyl Control Panel¶

在这篇文章中

• Pterodactyl 主要功能
• 部署功能
• Pterodactyl 部署后的入门指南
• 创建用户
• 创建 Location
• 创建 Node
• 配置 Allocations
• 安装 Wings
• 故障排除
• 创建 Nest 并添加 Egg
• 创建服务器
• 启动与配置服务器
• 性能检查
• 通过 API 订购 Pterodactyl 服务器

Pterodactyl 主要功能¶

Pterodactyl 是一个现代化的游戏服务器管理解决方案，结合了以下特性：

• 支持 50 多款游戏：提供现成的模板，用于快速安装热门游戏服务器。自动配置软件、依赖项和启动参数，支持游戏版本选择和自定义模板添加。
• 精确的资源管理：控制服务器之间的 RAM、CPU、磁盘空间和优先级分配。防止过载，按配额分配资源，并使用 SWAP 内存以确保稳定性。
• 可靠的自动备份：提供灵活的定时备份功能，支持数据选择（整个服务器或关键文件）。备份可以存储在本地或云端 (S3, FTP, GDrive)，具备加密功能并支持即时恢复。
• 高效的多服务器能力：每个服务器都在隔离的 Docker 容器中运行。自动在节点间分配负载，分配无冲突的端口，并允许对相关服务器进行分组。
• 灵活的多用户访问：通过基于角色的模型（预设角色 + 自定义角色）管理权限，拥有 50 多种细粒度权限。支持临时访问、操作审计和双重身份验证 (2FA)。
• 实时管理控制台：通过带有交互式终端（类似于 SSH）的 Web 界面提供完全控制。包含彩色格式化、命令历史记录、快速操作按钮和事件通知。
• 实时统计监控：显示资源使用图表（CPU、RAM、磁盘、网络）和游戏指标（在线玩家、TPS、Ping 值）。允许创建自定义仪表板、配置警报并将数据导出为 CSV。
• 简化的 Mod/插件管理：提供内置商店用于自动安装 Mod、版本和依赖项管理。包含具有语法高亮和更新通知的可视化配置编辑器。
• 自动更新：确保系统不间断运行。按计划**更新游戏服务器**，具备测试模式并在出错时回滚。通过一条命令 (php artisan p:upgrade)即可**更新控制面板**，在不丢失数据的情况下检查兼容性并迁移数据库。自动更新 Wings 守护进程，保持与不同 Linux 发行版的兼容性。

部署功能¶

主要系统组件：¶

配置文件¶

自动安装内容¶

Playbook 会自动安装并配置：

• Pterodactyl Panel - 带有 Web 界面的中央管理面板；
• MariaDB - 用于存储所有系统数据的数据库；
• Redis - 用于缓存和任务队列；
• NGINX - 与 Docker 容器协同工作的 Web 服务器，用于自动化 SSL 证书管理 (Certbot)；
• PHP + PHP-FPM - 用于 Laravel 应用程序运行；
• Certbot - 用于自动获取 SSL 证书；
• Systemd services - pteroq (队列处理)、cron tasks (调度器)。

需要额外安装的内容¶

要运行游戏服务器，你需要：

• Wings - 在 Docker 容器中物理启动并管理游戏服务器的守护进程。

Wings 被安装在计划运行游戏服务器的每台机器（节点）上。这可以是安装了 Panel 的同一台服务器（“全能型”配置），也可以是独立的专用服务器（分布式架构）。

系统要求¶

对于 Panel (Control Panel)¶

最低要求：

• 处理器：2+ 核心；
• 内存：2 GB RAM（建议 4 GB 以确保稳定运行）；
• 磁盘：20 GB SSD（建议 40+ GB 用于日志和备份）；
• OS：Ubuntu 22.04 LTS (Jammy) - 为了实现自动安装，必须使用此版本。

软件（自动安装）：

• PHP + PHP-FPM;
• MariaDB 10.6+;
• Redis 7.0+;
• NGINX;
• Composer 2;
• Certbot (用于 SSL);
• Docker (已预装在镜像中)。

网络要求：

• 已开放端口：80 (HTTP), 443 (HTTPS);
• 静态 IP 地址或域名；若要通过 Let's Encrypt 自动获取 SSL 证书，需要一个 hostkey.com 域名的有效 FQDN；
• 稳定的互联网连接。

对于 Node (运行游戏服务器的节点)¶

对于同时运行 5-10 个游戏服务器：

• 处理器：4+ 核心（高性能游戏建议使用 6-8 核）；
• 内存：8 GB RAM（根据游戏需求，建议 12-16 GB）；
• 磁盘：50 GB SSD（对于带有 Mod 的多服务器，建议 100+ GB）；
• OS：Ubuntu 20.04/22.04, Debian 10/11, CentOS ⅞ (任何支持 Docker 的 Linux)。
• 软件：
  • Docker (已预装在镜像中);
  • Wings (需要安装)。

网络要求：

• 已开放端口：
  • 8080 - Wings API (与 Panel 通信);
  • 12333 - SSL 连接 Wings/Daemon;
  • 2022 - SFTP (向游戏服务器上传文件);
  • 25565-25665 - 游戏端口范围 (单独配置);
• 带宽良好的稳定互联网连接；
• 低延迟以获得流畅的游戏体验。

"All-in-One" 配置 (单台服务器运行 Panel + Wings)¶

对于测试或小型项目，你可以使用一台服务器：

• 处理器：4+ 核心;
• 内存：8 GB RAM (最低 6 GB);
• 磁盘：60 GB SSD (建议 100+ GB);
• OS：Ubuntu 22.04 LTS。

在此配置中，一台服务器运行以下内容：

• Pterodactyl Panel (Web 界面);
• Wings (服务器启动守护进程);
• 数据库和缓存;
• Docker 容器中的游戏服务器。

Pterodactyl 部署后的入门指南¶

支付订单后，您将收到注册邮箱发送的通知，告知您的服务器已准备就绪。邮件中将包含 VPS IP 地址以及用于连接的登录名和密码。我们公司的客户可以通过 in the servers and API control panel — Invapi 管理硬件。

您可以在服务器控制面板的 Configuration >> Tags 选项卡中或通过邮件找到授权数据：

• Link: 在 webpanel 标签中；若要访问管理面板 (admin panel)，请在主链接后添加 /admin；
• Login: admin;
• Password: 服务器部署完成并准备好运行后，通过邮件发送到您的地址。

首次登录¶

1. 打开 Web 浏览器并导航至您的 Pterodactyl 面板地址

2. 点击 Login:

   

3. 成功授权后，您将被带到面板主页。

4. 若要访问管理面板 (admin panel)，点击 按钮：

   

创建用户¶

1. 在管理面板的左侧菜单中，点击 Users 部分名称；

2. 点击右上角的 Create New 按钮：

   

3. 填写必填字段：

   • Username: 用户名;
   • Email: 用户邮箱地址;
   • First Name: 名;
   • Last Name: 姓;
   • Password: 密码 (至少 8 个字符，必须包含大小写字母和数字);
4. 如有需要，在 Administrator 行选择 Yes 以授予管理员权限；

5. 点击 Create User:

   

创建 Location¶

1. 在左侧菜单中，选择 Locations；

2. 点击右上角的 Create New 按钮：

   

3. 填写字段：

   • Short Code: 短代码 (例如 "US1", "EU1")；
   • Description: 位置描述 (例如 "Data center in the USA")；

4. 点击 Create:

   

创建 Node¶

创建 Node 前的准备工作¶

在创建 Node 之前，请确保：

• 服务器已安装 Docker (HOSTKEY 镜像中已预装);
• 您拥有该 Node 的 IP 地址或域名;
• 防火墙已开放 8080 (Wings API) 和 12333 (Wings/Daemon SSL 通信) 端口。

在 Panel 中创建 Node¶

1. 在管理面板的左侧菜单中，选择 Nodes；

2. 点击右上角的 Create New 按钮：

   

3. 填写 basic settings (基本设置)：

   • Name: 唯一的 Node 名称 (例如 hostkey-us-node1)；
   • Location: 选择之前创建的 Location；
   • Public: 如果该 Node 对用户可见，请勾选此框；
   • FQDN: 指定面板域名 (例如 pterodactyl50514.hostkey.in) 或 IP 地址；
   • Communicate Over SSL: 如果 Panel 使用 HTTPS，请勾选此框；
   • Behind Proxy: 如果 Node 不在代理服务器后，请保持禁用状态。

4. 配置 resource settings (资源设置)：

   • Daemon Server File Directory: /var/lib/pterodactyl/volumes (请勿更改);
   • Total Memory: 以 MB 为单位指定可用 RAM (例如，对于 6GB 的服务器，考虑到预留空间，填写 4608)；
   • Memory Over-Allocation: 指定为 0 (不进行内存超额分配)；
   • Total Disk Space: 以 MB 为单位指定可用磁盘空间 (例如，对于 120GB 的磁盘，考虑到预留空间，填写 102400)；
   • Disk Over-Allocation: 指定为 0 (不进行磁盘超额分配)；
   • Daemon Port: 8080 (保持默认);
   • Daemon SFTP Port: 2022 (保持默认)。

   

5. 点击 Create Node 按钮。

    Name: hostkey-us-node1
    Location: US1
    Public: ☑
    FQDN: pterodactyl50514.hostkey.in
    Communicate Over SSL: ☑
    Behind Proxy: ☐


    Total Memory: 4608 MB (为系统预留 1.5GB)
    Memory Over-Allocation: 0
    Total Disk Space: 102400 MB (为系统预留 20GB)
    Disk Over-Allocation: 0

配置 Allocations¶

创建 Node 后，您需要配置 Allocations —— 这些是可分配给游戏服务器的 IP 地址和端口组合。

1. 创建 Node 后，其页面会自动打开。导航至 Allocation 选项卡；

2. 在 Assign New Allocations 部分 (右侧)，填写字段：

   • IP Address: 输入服务器 IP 地址；
   • IP Alias: 指定描述 (例如 Main IP) 或留空；
   • Ports: 指定端口范围 (例如 Minecraft 服务器使用 25565-25570)。

3. 点击绿色的 Submit 按钮：

   

4. 创建的 Allocations 将出现在 Existing Allocations 表格（左侧）中。每一行代表一个独立的 IP:port 组合，可以分配给游戏服务器。

   

安装 Wings¶

通过 SSH 连接到服务器并执行以下命令：

为配置创建目录：

mkdir -p /etc/pterodactyl

curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64"

chmod u+x /usr/local/bin/wings

wings version

应显示 Wings 版本（例如 wings vv1.12.1）。

通过 Auto-Deploy 配置 Wings (推荐)¶

1. 在管理面板中，进入已创建 Node 的 Configuration 选项卡；

2. 在 Auto-Deploy 部分 (右侧)，点击 Generate Token 按钮：

   

3. 复制生成的命令。它看起来像这样：

       cd /etc/pterodactyl && wings configure --panel-url https://your-domain.com --token TOKEN --node 1
   

   

4. 在服务器上执行复制的命令：

       cd /etc/pterodactyl && wings configure --panel-url https://pterodactyl50514.hostkey.in --token TOKEN --node 1
   

   应出现消息：Successfully configured wings.

5. 验证创建的配置：

       cat /etc/pterodactyl/config.yml
   

创建 systemd 服务¶

为 Wings 的自动启动创建 systemd 服务：

cat > /etc/systemd/system/wings.service <<'EOF'
[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
EOF

启动 Wings¶

重新加载 systemd 配置

systemctl daemon-reload

systemctl enable --now wings

systemctl status wings

状态应显示 Active: active (running)。

运行检查¶

检查 Wings 日志：

journalctl -u wings -n 50

日志中应包含以下消息：

• fetching list of servers from API - Wings 已连接到 Panel；
• configuring internal webserver - Wings Web 服务器已启动；
• sftp server listening for connections - SFTP 服务器正在工作。

验证服务器目录创建情况：

ls -la /var/lib/pterodactyl/volumes/

在管理面板中检查状态¶

1. 打开管理面板：https://your-domain.com/admin;
2. 导航至：Admin > Nodes > 您的 Node;
3. 刷新页面 (F5);
4. 右上角应显示绿色的 Online 状态指示器；
5. 在 About 选项卡上，应显示资源信息 (CPU、RAM、Disk)。

故障排除¶

Node 显示 Offline 状态¶

检查 Wings 状态：

systemctl status wings

如果 Wings 未运行，请启动它：

systemctl start wings

检查错误日志：

journalctl -u wings -n 100

常见问题：

1. Wings 无法连接到 Panel：

   • 检查配置中的 Panel URL：cat /etc/pterodactyl/config.yml | grep remote;
   • 确保 Panel 可访问：curl -I https://your-domain.com.

2. 8080 端口被防火墙拦截：

   • 检查端口：netstat -tulpn | grep 8080;
   • 开放端口：ufw allow 8080/tcp.

3. SSL 问题：

   • 如果 Panel 使用 HTTPS，Wings 也必须支持 SSL；
   • 检查 /etc/pterodactyl/config.yml 中的 SSL 设置。

手动配置 (备选方法)¶

如果 Auto-Deploy 不起作用，您可以手动配置 Wings：

1. 在管理面板中，进入该 Node 的 Configuration 选项卡；
2. 从左侧文本框复制配置文件内容；

3. 在服务器上创建配置文件：

   nano /etc/pterodactyl/config.yml
   

4. 粘贴复制的配置并保存 (Ctrl+X，然后 Y，再按 Enter)；

5. 重启 Wings：systemctl restart wings;
6. 检查状态：systemctl status wings.

创建 Nest 并添加 Egg¶

创建 Nest¶

1. 在左侧菜单中，选择 Nests 部分；

2. 点击右上角的 Create New 按钮：

3. 填写字段：

   • Name: Nest 名称 (例如 "Minecraft")；
   • Description: Nest 描述；

4. 点击 Save:

   

下载现成的 Egg¶

1. 打开网站 https://pelican-eggs.github.io/;

2. 找到所需的游戏：

   • 在 Game Eggs 部分，选择一个类别 (例如 Minecraft)；
   • 找到所需的服务器类型 (例如 Paper, Vanilla, Forge)；

3. 点击服务器名称以打开 GitHub 页面；

4. 找到 egg-name.json 文件 (例如 egg-paper.json)；

5. 点击该文件，然后点击右上角的 Raw 按钮；

6. 保存文件 (Ctrl+S 或右键 > Save as)。

将 Egg 导入 Panel¶

1. 在管理面板中，进入 Nests 部分；

2. 点击右上角的 Import Egg 按钮：

   

3. 点击 Choose File 并选择下载的 .json 文件；

4. 点击 Import:

   

Egg 将连同所有设置、Docker 镜像和变量一起被导入。

验证导入的 Egg¶

1. 在 Egg 列表中，找到已导入的项目 (例如 Paper)；

2. 点击它以查看设置；

3. 确保以下内容已填写：

   • Docker Images: 可用镜像列表；
   • Install Script: 服务器安装脚本；
   • Variables: 环境变量 (版本、设置)。

   

   

创建服务器¶

1. 在左侧菜单中，选择 Servers；

2. 点击右上角的 Create New 按钮：

   

3. 填写创建表单：

Core Details (核心详情):

• Server Name: 服务器名称 (例如 Test Minecraft Server)；
• Server Owner: 从列表中选择所有者用户；
• Server Description: 描述 (可选)；
• Start Server when Installed: 保持勾选状态。

Allocation Management (分配管理):

• Node: 选择已创建的 Node；
• Default Allocation: 从列表中选择 IP 地址:端口；
• Additional Allocations: 留空。

Application Feature Limits (应用功能限制):

• Database Limit: 0;
• Allocation Limit: 0;
• Backup Limit: 0.

Resource Management (资源管理):

• CPU Limit: 0 (无限制);
• Memory: 2048 MiB (起始为 2GB);
• Swap: 0 MiB;
• Disk Space: 5120 MiB (5GB);
• Block IO Weight: 500;
• Enable OOM Killer: 保持禁用。

Nest Configuration (Nest 配置):

• Nest: Minecraft;
• Egg: Paper (不是 Sponge!)；
• Docker Image: Java 21;

• Service Variables: 使用默认值。

• 点击页面底部的 Create Server 按钮；

• 等待安装完成 (状态从 Installing 变为 Offline)：

启动与配置服务器¶

1. 安装完成后，从列表打开服务器 (Admin > Servers):

   

2. 进入用户面板 (不带 /admin)，以服务器所有者身份登录；

3. 点击 Start 按钮：

   

4. 首次启动时，会弹出许可协议窗口：

   

5. 点击 I Accept 以接受 Minecraft EULA；

6. 等待服务器启动 (状态将变为 Running):

   

性能检查¶

在浏览器中打开（将 IP 替换为您自己的）：

https://api.mcsrvstat.us/3/<IP address>:25565

连接地址：

<IP address>:25565

通过 API 订购 Pterodactyl 服务器¶

要使用 API 安装此软件，请遵循 这些说明。