第15章 在 AWS 或 DigitalOcean 上部署 Pangolin
第15章 在 AWS 或 DigitalOcean 上部署
使用预构建的 AWS 或 DigitalOcean 镜像,几分钟内即可启动自托管的 Pangolin 服务器。
预构建镜像是自托管 Pangolin 最快的方式,内置 Docker、防火墙配置和引导式安装程序。每次安装时都会自动获取最新的 Pangolin 版本,不会从旧版本起步。
Amazon Web Services:每种架构(x86 和 Graviton)各提供一个 AMI,覆盖两个版本。可在启动时通过 user-data 或 CloudFormation 完成全部配置,无需 SSH。
DigitalOcean:Marketplace 一键 droplet。SSH 登录一次,安装向导会引导你完成安装。
开始之前
无论选择哪家服务商,你都需要:
一个你自己控制 DNS 的域名。Pangolin 用一个基础域名(如 example.com)来暴露资源,用一个控制台域名(默认 pangolin.example.com)作为管理界面。
一个用于 Let's Encrypt 证书的邮箱。
指向服务器公网 IP 的 DNS 记录。知道 IP 后就可以创建:
A pangolin.example.com -> <服务器公网 IP> A *.example.com -> <服务器公网 IP>
开放端口:TCP 80 和 443,UDP 51820(sites)和 21820(clients)。两个镜像都已自动放行这些端口。
更多细节见 DNS & Networking,服务器规格选择见 Choosing a VPS。
Amazon Web Services
Pangolin 为每种架构发布一个 Ubuntu 24.04 AMI:
| 架构 | AMI 名称 | 示例实例 | |---|---|---| | x86_64 | pangolin-ubuntu-24.04-amd64-* | t3.small | | arm64 / Graviton | pangolin-ubuntu-24.04-arm64-* | t4g.small |
同一个 AMI 可以安装 Community Edition(默认)或 Enterprise Edition,在配置实例时选择:在 user-data 中设置 PANGOLIN_EDITION、使用 CloudFormation 的 Edition 参数,或在向导中作答。Enterprise Edition 对个人用户和年收入低于 10 万美元的企业免费,详见 Enterprise Edition。
AMI 覆盖所有默认启用的 AWS 区域:美东、美西、加拿大、圣保罗、爱尔兰、伦敦、巴黎、法兰克福、斯德哥尔摩、孟买、东京、首尔、大阪、新加坡和悉尼。
Graviton(t4g)实例性价比最高,t4g.small(2 vCPU、2 GB 内存)能满足大多数部署需求。
查找 AMI
在 AWS Marketplace 搜索 Pangolin 并订阅。列表页会显示各区域的 AMI ID,并支持一键 CloudFormation 启动。
启动和配置
选定一种方式把版本、域名和邮箱传给实例即可。使用 CloudFormation 或 user-data 时,实例会自动完成配置:等待控制台域名解析到自己,然后安装 Pangolin。
在 Marketplace 列表页选择 CloudFormation 启动方式,并填写参数:
- Edition:community(默认)或 enterprise
- BaseDomain 和 LetsEncryptEmail(必填)
- DashboardDomain(可选,默认 pangolin.
该 stack 会创建安全组、实例和 Elastic IP,输出内容包括公网 IP、控制台 URL,以及一条用于打印 setup token 的命令。
所有 user-data 设置
| 设置 | 默认值 | 说明 | |---|---|---| | PANGOLIN_EDITION | community | community 或 enterprise | | PANGOLIN_BASE_DOMAIN | 必填 | 资源使用的基础域名,如 example.com | | PANGOLIN_DASHBOARD_DOMAIN | pangolin.<基础域名> | Pangolin 控制台的域名 | | PANGOLIN_EMAIL | 必填 | Let's Encrypt 邮箱 | | PANGOLIN_INSTALL_GERBIL | true | 启用 WireGuard 隧道,设为 false 可在不使用隧道的情况下运行 Pangolin | | PANGOLIN_ENABLE_IPV6 | auto | Docker 网络的 IPv6。实例有 IPv6 地址时默认开启 | | PANGOLIN_ENABLE_MAXMIND | true | 下载 GeoLite2 地理位置数据库 | | PANGOLIN_SMTP_HOST、PANGOLIN_SMTP_PORT、PANGOLIN_SMTP_USER、PANGOLIN_SMTP_PASS、PANGOLIN_SMTP_NO_REPLY | 关闭 | 邮件(SMTP)。设置 PANGOLIN_SMTP_HOST 后启用 | | PANGOLIN_WAIT_FOR_DNS | true | 安装前等待控制台域名解析到实例 | | PANGOLIN_DNS_TIMEOUT | 1800 | 等待 DNS 的秒数,超时后仍会继续安装 |
如果只设置 PANGOLIN_DASHBOARD_DOMAIN,基础域名会自动取该域名去掉第一级标签的结果(pangolin.example.com → example.com)。
实例上的任何进程都能读取 user-data,建议 SMTP 凭证改为之后在 /opt/pangolin/config/config.yml 中配置。
获取 setup token
安装完成后(通常在 DNS 解析生效后几分钟),无需 SSH 即可读取 setup token:
aws ec2 get-console-output --instance-id i-... --latest --output text | grep 'Setup token'
或者通过 SSH:
pangolin-setup status # waiting-dns | installing | complete | ... sudo pangolin-setup token
然后继续执行 Finish setup。
DigitalOcean
Pangolin (CE) 一键应用基于 Ubuntu 24.04 和 Docker CE,安装过程中会获取最新的 Pangolin 版本。列表名称标注的是 Community Edition,但安装时也可以选择 Enterprise Edition。
创建 droplet
选择靠近用户的区域和至少 1 GB 内存(推荐 2 GB)的套餐,并添加 SSH 密钥以便以 root 登录。在 DigitalOcean Marketplace 打开 Pangolin (CE),点击 Create Pangolin (CE) Droplet。
将 DNS 指向 droplet
复制 droplet 的公网 IP,按"开始之前"所述为控制台域名和 *.<基础域名> 创建 A 记录。
SSH 登录并运行安装
ssh root@
首次登录时安装脚本会自动启动并下载最新安装程序。按 Quick Install Guide 的提示作答:版本、基础域名、控制台域名、Let's Encrypt 邮箱、隧道,以及可选的 SMTP。
复制 setup token
安装完成后会打印 setup token,如需再次查看:
cd /opt/pangolin && docker compose logs pangolin | grep -A2 'SETUP TOKEN'
droplet 已启用 UFW,只放行 22、80、443 端口和 UDP 51820、21820。如需进一步加固,可用 ufw allow from <你的IP> to any port 22 把 SSH 限制为仅你的 IP,或使用 DigitalOcean Cloud Firewall。
完成安装
打开控制台
访问 https://<控制台域名>/auth/initial-setup。
DNS 解析生效后,证书签发可能需要几分钟,浏览器短暂出现证书警告属正常现象。
创建管理员账户
粘贴 setup token,然后输入管理员邮箱和强密码。第一个管理员账户创建后,token 即失效。
激活 Enterprise(如适用)
在 Enterprise Edition 服务器上,打开 Server Admin → License(/admin/license)并输入许可证密钥,详见 Activate a License。
接下来就可以添加 site 并暴露你的第一个资源了。
更新
两个镜像都是用 Docker Compose 把 Pangolin 安装在 /opt/pangolin。升级到新版本请按 How to Update 操作,无需更换镜像。
故障排查
AWS 实例一直在等 DNS
检查控制台域名是否解析到实例的公网 IP:
dig +short pangolin.example.com @1.1.1.1
实例会持续检测,并在 PANGOLIN_DNS_TIMEOUT(默认 30 分钟)后仍继续安装。如果服务器位于负载均衡器后面,请设置 PANGOLIN_WAIT_FOR_DNS=false。可用 sudo tail -f /var/log/pangolin-setup.log 查看进度。
浏览器报证书错误
Let's Encrypt 只有在 DNS 指向服务器且 80 端口可访问后才能签发证书。修复 DNS 或防火墙后,重启 Traefik:
cd /opt/pangolin && sudo docker compose restart traefik
AWS 安装失败
运行 pangolin-setup status 并查看 /var/log/pangolin-setup.log。解决问题后,运行 sudo pangolin-setup 重试。
Sites 无法连接
确认 AWS 安全组(或你添加的 DigitalOcean 防火墙)中 UDP 51820 已放行,客户端还需放行 UDP 21820。
这个页面有帮助吗?