VPS 搭建 Pangolin（2026）：Docker、Newt 内网穿透、Traefik HTTPS、身份验证与备份

Pangolin 是一套自托管的安全访问平台。公网 VPS 负责域名入口、TLS 证书、身份验证和访问规则，内网机器运行 Newt，并主动向 VPS 建立加密隧道。因为连接由内向外发起，家庭宽带不需要公网 IPv4，也不必在路由器上开放业务端口。

典型用途包括：

• 给家庭 NAS、相册、Home Assistant 或监控面板提供 HTTPS 域名；
• 给客户或同事临时分享某个内网站点，并设置登录或过期链接；
• 在多处家庭、办公室和云主机之间建立站点连接；
• 用统一控制台管理公开 Web 资源、私有资源和访问策略；
• 替换“FRP + Nginx + Certbot + Authelia”这类需要自行组合的方案。

它不等于 VPN，也不适合所有应用。只想让自己的设备组成私网，可以看 NetBird 自托管组网教程；只需要简单、低依赖的端口转发，FRP 内网穿透教程更直接。

如果最看重免维护和全球边缘网络，可优先考虑 Cloudflare Tunnel 隐藏源站教程。如果要掌握入口服务器、域名和访问数据，同时希望少拼几套组件，Pangolin 更合适。

公开 Web 资源的完整路径是：

浏览器
  ↓ HTTPS
公网 VPS：Traefik + Pangolin + Gerbil
  ↓ 加密隧道
Newt 所在内网机器
  ↓ LAN
NAS / Home Assistant / 内网站点

浏览器下载 10GB 文件，VPS 通常既要从 Newt 隧道接收数据，又要向访问者发送数据。不同厂商可能只计出站，也可能双向计费，不能只看套餐上写的“流量”二字；购买前应确认计费方向、超额价格和端口限速。

持续带宽可以这样估算：

计算公式是 Mbps × 1,000,000 ÷ 8 × 2,592,000 秒。这是连续跑满 30 天的十进制结果，不包含协议开销；实际还会受到 TLS、WireGuard、重传和访问峰值影响。

Pangolin 官方给出的最低配置是 1 vCPU、1GB 内存和 8GB SSD，推荐配置是 2 vCPU、2GB 内存和 20GB SSD。实际选购可以按下面判断：

VPS 位置应尽量靠近主要访问者，同时保证 VPS 到家庭宽带的回程不差。用户在亚洲、VPS 在欧洲、家庭服务又在亚洲，会形成明显绕路。

本文示例使用：

• Pangolin 基础域名：example.com；
• 管理后台：pangolin.example.com；
• 对外资源：nas.example.com；
• VPS 公网 IP：203.0.113.10；
• 安装目录：/opt/pangolin。

把示例值替换成自己的真实信息。官方推荐为基础域名添加通配符 A 记录，这样后续新增资源不必逐个改 DNS：

Type: A
Name: *
Value: 203.0.113.10
Proxy: DNS only

也可以只为 pangolin.example.com、nas.example.com 分别创建 A 记录，暴露面更清晰。只有 VPS 真正配置了可用 IPv6 时才添加 AAAA；错误的 AAAA 常导致部分网络访问超时或证书申请失败。

先检查解析和端口占用：

dig +short A pangolin.example.com
dig +short A nas.example.com

sudo ss -lntup | grep -E ':(22|80|443|51820|21820)\b' || true

Pangolin 默认需要：

• 80/TCP：HTTP 跳转和 ACME 证书验证；
• 443/TCP：Dashboard、公开资源和 HTTPS；
• 51820/UDP：Newt 站点隧道；
• 21820/UDP：Pangolin 客户端隧道；
• 22/TCP：VPS 的 SSH 管理，只允许自己的管理 IP。

如果只发布 Newt 后面的公开 Web 服务、不使用 Pangolin 客户端，21820/UDP 可能暂时用不到；本文仍按官方快速安装要求开放，跑通后可结合实际功能和日志收紧。

在 Ubuntu 24.04 上安装 Docker、Compose v2 和常用工具：

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl jq docker.io docker-compose-v2
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

退出 SSH 并重新登录，让用户组生效。然后检查：

docker version
docker compose version
docker run --rm hello-world

本文使用 docker compose，不是旧版 docker-compose。如果 80/443 已被 Nginx、Caddy 或其他 Traefik 占用，先决定由谁统一接管入口，不要让两套代理同时绑定同一端口。需要单独管理传统反向代理时，可参考 Nginx Proxy Manager 部署教程。

先在 VPS 厂商的安全组或云防火墙放行 80/TCP、443/TCP、51820/UDP、21820/UDP，并把 22/TCP 限制到自己的固定公网 IP。再配置系统 UFW：

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow from YOUR_ADMIN_IP to any port 22 proto tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw allow 21820/udp
sudo ufw enable
sudo ufw status numbered

YOUR_ADMIN_IP 必须替换，不能原样复制。启用前保留当前 SSH 会话，并确认厂商网页控制台可用；若误封 SSH，按 UFW 锁机恢复清单处理。

Docker 会管理自己的 iptables/nftables 规则。UFW 不是错误端口映射的保险，部署后仍要用 docker compose ps、ss 和外部扫描确认公网入口。

官方快速安装支持 Ubuntu 20.04+ 和 Debian 11+。生产机器不要直接把未知网络脚本送进 shell；先保存、查看，再执行：

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/pangolin
cd /opt/pangolin

curl -fsSLo get-installer.sh \
  https://static.pangolin.net/get-installer.sh
less get-installer.sh
bash ./get-installer.sh
sudo ./installer

安装器把 Compose 文件和配置写入当前目录，所以先进入 /opt/pangolin 很重要。交互过程按下面选择：

1. Edition 选择 Community；
2. Base domain 填 example.com；
3. Dashboard domain 填 pangolin.example.com；
4. Let's Encrypt email 填长期可用邮箱；
5. Tunneling/Gerbil 选择启用；
6. 没有 SMTP 服务时先跳过邮件配置，后台跑通后再补。

截至本文日期，最新稳定版为 1.22.2，但不要只凭文章里的版本号做升级。安装后读取实际服务和镜像：

cd /opt/pangolin
docker compose config --services
docker compose config --images
docker compose ps

docker compose config --quiet 只验证 Compose 能否解析，不代表容器健康：

docker compose config --quiet
docker compose logs --tail=150

安装器完成后会显示一次性初始设置地址，形式类似：

https://pangolin.example.com/auth/initial-setup?token=ONE_TIME_TOKEN

在可信电脑上立即打开，创建第一个管理员。不要把完整 URL 发到聊天群、工单或公开截图里，因为查询参数中的 token 相当于一次性凭据。

初次登录后建议马上做这些检查：

1. 管理后台能通过有效 HTTPS 打开；
2. 浏览器证书中的域名与 pangolin.example.com 一致；
3. 管理员使用独立强密码；
4. 日常账号和管理员账号分开；
5. 如果接入外部身份提供商，保留一个已经验证可用的应急管理员。

从本地检查 TLS 和响应头：

curl -I https://pangolin.example.com
openssl s_client \
  -connect pangolin.example.com:443 \
  -servername pangolin.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

Pangolin 里的 Site 代表一个需要接入的网络位置，例如家里、办公室或另一家云平台。先在 Dashboard 创建 Site，再复制它生成的 Newt ID、Secret 和 Endpoint。

在能访问目标服务的 Linux 主机上安装 Newt。最好选择长期在线、网络稳定的机器；它不一定是 NAS 本身，也可以是同一局域网里的小主机：

curl -fsSLo get-newt.sh https://static.pangolin.net/get-newt.sh
less get-newt.sh
sudo bash ./get-newt.sh
rm -f get-newt.sh

不要把 Secret 直接写进文章、截图或 shell history。使用 root 可读的环境文件：

sudo install -d -m 0700 /etc/newt
sudo install -m 0600 /dev/null /etc/newt/newt.env
sudoedit /etc/newt/newt.env

填入 Dashboard 为这个 Site 生成的真实值：

NEWT_ID=REPLACE_WITH_SITE_ID
NEWT_SECRET=REPLACE_WITH_SITE_SECRET
PANGOLIN_ENDPOINT=https://pangolin.example.com

创建 systemd 服务：

sudoedit /etc/systemd/system/newt.service

内容如下：

[Unit]
Description=Pangolin Newt Tunnel Client
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=root
Group=root
EnvironmentFile=/etc/newt/newt.env
ExecStart=/usr/local/bin/newt
Restart=always
RestartSec=2
UMask=0077
PrivateTmp=true

[Install]
WantedBy=multi-user.target

加载并启动：

sudo systemctl daemon-reload
sudo systemctl enable --now newt
sudo systemctl status newt --no-pager
sudo journalctl -u newt -n 100 --no-pager

回到 Dashboard，Site 应显示在线。Newt 是向外建立连接，家用路由器通常不需要开放入站端口；但家庭网络必须允许它访问 Pangolin Endpoint 的 HTTPS 和所需 UDP 隧道端口。

假设 NAS 管理页面在 192.168.1.20:5000，计划通过 nas.example.com 访问。在 Pangolin 中创建 Public Resource：

Resource type: Public
Domain: nas.example.com
Site: Home
Target hostname/IP: 192.168.1.20
Target port: 5000
Target method: HTTP

这里的 Target 是 Newt 所在网络能访问的地址，不是 VPS 能访问的地址，也不是容器里的 localhost。如果后端自己提供 HTTPS，就按证书和协议情况选择 HTTPS；不要看到公网入口是 HTTPS，就误把内网 HTTP 目标也填成 HTTPS。

保存后先从 Newt 主机验证后端：

curl -I http://192.168.1.20:5000
nc -vz 192.168.1.20 5000

再从外部网络检查：

curl -I https://nas.example.com

首次测试建议使用手机蜂窝网络，而不是仍在家庭 Wi-Fi 内测试，避免路由器的 NAT 回环行为干扰判断。

Public Resource 默认可以使用 Pangolin 平台身份认证。NAS、Home Assistant、管理后台和开发环境都不应仅靠“域名很难猜”来保护。

推荐顺序是：

1. 保持平台 SSO/认证开启；
2. 创建用户或角色，只允许需要的人访问；
3. 对临时访客使用有期限的 Share Link 或一次性验证方式；
4. 分享完成后主动撤销链接；
5. 定期查看长期不用的用户、角色和资源。

访问控制规则一般包含 Allow、Deny 和 Pass to authentication。写规则时先用测试账号验证，特别注意 Allow 规则可能绕过认证流程；不要为了排障留下全网段、全用户的永久放行。

公开 HTTP 资源适合浏览器应用，因为可以在入口做身份验证。裸 TCP/UDP 资源没有同等的 Web 身份上下文，不要把 NAS 管理端口、数据库或 SSH 随意作为公开端口发布。需要这类访问时，优先使用 Pangolin Private Resource、NetBird/WireGuard 私网，或严格限制源地址。

SMTP 可用于邀请、通知和账户流程，但不是首次跑通隧道的前提。建议先完成下面这条最小闭环：

Dashboard 可登录
→ Site 在线
→ Newt 日志正常
→ 一个测试资源可访问
→ 身份认证生效
→ 备份可恢复

然后再接入 SMTP、OIDC 或其他身份提供商。一次引入太多外部依赖，遇到登录循环时很难判断是 DNS、Cookie、回调地址、邮件服务还是隧道本身的问题。

配置外部身份提供商时，回调 URL 必须与浏览器实际访问域名、协议完全一致，并确保反向代理正确传递 Host 和 X-Forwarded-Proto。修改前保留本地管理员会话，修改后用无痕窗口测试。

官方升级文档明确要求更新前备份 config 目录。安装器还会生成 docker-compose.yml 等部署文件，恢复时同样需要，所以本文一起备份。

先查看实际文件，不要猜路径：

cd /opt/pangolin
find . -maxdepth 2 -type f -printf '%P\n' | sort
docker compose config --images

为保证 SQLite 或其他本地数据一致，短暂停止服务再打包：

cd /opt/pangolin
sudo docker compose down

sudo tar \
  --numeric-owner \
  -czf "/root/pangolin-backup-$(date +%F-%H%M%S).tar.gz" \
  config docker-compose.yml

sudo docker compose up -d
docker compose ps

如果实际安装器还生成了 .env、额外 Compose 文件或证书目录，把它们加入备份，但不要盲目打包整个 /opt。备份包可能包含数据库、密钥、SMTP 密码和令牌，权限应设为 600，并复制到另一台机器或对象存储：

sudo chmod 600 /root/pangolin-backup-*.tar.gz
sudo sha256sum /root/pangolin-backup-*.tar.gz

真正的备份必须经过恢复演练。至少在隔离 VPS 上验证压缩包可解压、Compose 能解析、使用原版本镜像能启动；不要等主机损坏后才第一次测试。

Pangolin 1.22 引入了新的功能和数据变化，官方特别提醒更新前备份，部分迁移可能让降级困难。升级时不要只运行 docker compose pull 就结束：

cd /opt/pangolin

sudo docker compose down
sudo cp -a config "config.before-upgrade-$(date +%F-%H%M%S)"
sudo cp -a docker-compose.yml \
  "docker-compose.yml.before-upgrade-$(date +%F-%H%M%S)"

sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=200

正式操作前先阅读目标版本 Release Notes，并按官方更新文档同步 Pangolin、Gerbil、Traefik/Badger 等相关组件版本。不要只改一个镜像，也不要把网上旧教程的版本组合覆盖到当前配置。

升级后的验收至少包括：

• Dashboard 登录正常；
• Site 和 Newt 重新上线；
• 公开资源能访问且证书有效；
• 身份规则仍会拦截未授权用户；
• 分享链接的过期与撤销正常；
• 备份文件不在公开 Web 目录中。

如果数据库迁移已经执行，简单换回旧镜像未必能回滚。稳妥做法是恢复升级前的配置和数据快照，再使用与快照匹配的完整镜像版本。

502 通常说明公网入口和 Pangolin 已经工作，但 Newt 到后端目标失败。按路径从近到远排查：

1. 在 Newt 主机执行 curl -I http://目标IP:端口；
2. 确认 Resource 选择了正确 Site；
3. 确认 Target method 是 HTTP 还是 HTTPS；
4. 检查后端是否只监听 127.0.0.1；
5. 检查 NAS/服务器防火墙是否允许 Newt 主机访问；
6. 查看 Newt 和 VPS 端容器日志。

# Newt 主机
ip route
curl -v http://192.168.1.20:5000/
sudo journalctl -u newt -n 200 --no-pager

# Pangolin VPS
cd /opt/pangolin
docker compose ps
docker compose logs --since=15m

如果 Target 写成 localhost，它指向 Newt 主机本身，不会自动指向 NAS。Docker 后端也要注意容器网络和宿主机地址的区别。

先看服务和环境文件权限：

sudo systemctl status newt --no-pager
sudo journalctl -u newt -n 200 --no-pager
sudo stat -c '%a %U:%G %n' /etc/newt/newt.env

常见原因有：

• Site ID 或 Secret 复制错误、含多余空格；
• Endpoint 域名解析到旧 IP；
• VPS 云防火墙漏开 51820/UDP；
• 家庭网络阻断 UDP，或上游网络对隧道流量不稳定；
• VPS 与 Newt 主机时间偏差过大；
• 升级时服务端和 Newt 版本组合不兼容。

继续检查解析、时间和基本 HTTPS：

getent ahosts pangolin.example.com
curl -I https://pangolin.example.com
timedatectl status

不要在群里粘贴完整 Newt 启动命令或环境文件。若 Secret 已经进入公开日志，立即在 Dashboard 轮换凭据，而不是只删消息。

证书问题优先检查 DNS 和 80/443，而不是重装容器：

dig +short A pangolin.example.com
dig +short AAAA pangolin.example.com
curl -I http://pangolin.example.com
sudo ss -lntp | grep -E ':(80|443)\b'

cd /opt/pangolin
docker compose logs --since=30m | grep -iE 'acme|certificate|challenge|error'

确认：

• A 记录指向当前 VPS；
• 不存在错误 AAAA；
• 云安全组和 UFW 同时允许 80/443；
• 没有旧 Nginx/Caddy 抢占端口；
• CDN 代理没有改写挑战请求；
• Let's Encrypt 邮箱和域名填写正确。

不要连续重试证书申请。频繁失败可能触发 CA 速率限制，先修正根因再重启相关服务。

登录后又回到登录页，通常与域名、HTTPS、Cookie 或外部身份提供商回调不一致有关。用无痕窗口测试，并检查浏览器实际地址是否与 Pangolin 配置完全一致。

如果某个资源完全没有出现登录页：

1. 检查该 Public Resource 是否启用平台认证；
2. 检查是否存在范围过大的 Allow/bypass 规则；
3. 使用未登录浏览器和蜂窝网络复测；
4. 查看访问规则的匹配顺序和对象；
5. 关闭临时放行规则后再次验证。

测试安全规则时，不能只用管理员自己的已登录浏览器。管理员可能已有 Cookie、角色和额外权限，容易得到错误结论。

• A/AAAA 记录与 VPS 实际地址一致；
• 80/TCP、443/TCP、51820/UDP、21820/UDP 的开放范围已确认；
• SSH 只允许管理 IP，并准备好网页控制台；
• Dashboard 和资源域名使用有效 HTTPS；
• Newt 环境文件权限为 600，凭据未进入仓库或聊天记录；
• 后端只允许必要的局域网来源访问；
• Public Resource 保持身份认证，没有长期全放行规则；
• 分享链接设置过期时间，用完后撤销；
• 已按实际访问量估算 VPS 月流量与端口带宽；
• 升级前备份配置、数据和版本信息；
• 备份已离机保存并做过恢复演练；
• 从外部网络测试登录、资源访问和拒绝规则。

Pangolin 的价值不只是“把内网端口转出来”，而是把域名 HTTPS、Newt 隧道、用户身份、资源权限和临时分享放进一套可自托管系统。它比纯 FRP 更完整，也比全托管 Tunnel 多了入口控制权，代价是你要承担 VPS 流量、版本升级、备份和安全维护。

轻量使用可以从 2 核 2GB、20GB SSD 和 1TB 月流量起步；相册、文件与视频场景先按持续带宽计算月流量。部署时先跑通 Dashboard、Site、Newt 和一个受认证保护的 Web 资源，再逐步接入 SMTP、外部身份提供商和更多网络能力，排障会简单很多。

官方资料：

• Pangolin Self-host Quick Install
• DNS and Networking
• Choosing a VPS
• Install a Newt Site
• How to Update Pangolin
• Pangolin Releases