PairDrop 局域网跨端快传搭建指南

导读：在多设备办公与日常生活中，跨平台传输文件向来是痛点最为集中的场景：苹果生态的 AirDrop 无法跨到 Windows 与安卓；微信传输助学会强行压缩大图且有文件大小限制；插拔 U 盘效率低下；而公共快传服务（如 Snapdrop 公共站）频繁遭遇 WebRTC 节点失联、信令服务器超时与隐私外泄隐患。
本文将带你使用 Docker 自建开源的 PairDrop 跨平台快传服务，攻克 WebRTC 加密信道强制 HTTPS 门槛、Nginx WebSocket 长连接保活、跨网段 STUN 穿透与 PWA 离线应用化四大核心避坑点，实现 iOS、Android、Windows、Mac、Linux 全端免装 App、局域网直连千兆拉满的无感隔空投送！

🎯 核心目标与收益

完成本教程后，你将获得以下物理级体验：

全平台免装客户端：任何设备只要打开浏览器输入你的私有网址，瞬间化身 AirDrop 接收端与发送端；
WebRTC 点对点极速直连（P2P）：局域网内传输流量不经过外网服务器，直接走局域网千兆/万兆内网传输，实测速度可达 80MB/s~110MB/s（跑满千兆网卡），几秒传输数 GB 高清大文件；
隐私绝对安全：文件在端到端通过 DTLS 加密传输，你的 VPS 或内网服务器仅作为轻量信令协调中枢，不留存任何传输数据；
跨网段临时配对（公网可用）：不仅支持同 Wi-Fi 自动发现，还支持通过 6 位配对码 或 二维码 实现手机流量与电脑宽带的跨网段安全穿透互传。

🖥️ 基础环境与全局变量定义

在开始配置前，先集中定义涉及的核心变量。请根据你的实际域名和网络拓扑替换对应值：

BASH

# ================= 全局参数定义 =================
DOMAIN="drop.0000996.xyz"        # PairDrop 对外访问的公网域名 (已解析至服务器)
DATA_DIR="/opt/pairdrop"         # 配置文件与数据挂载根目录
PORT="3000"                      # 容器内部监听端口 (本地回环暴露)
# ================================================

💻 第一步：宿主机目录规划与 Docker Compose 编排

PairDrop 本身非常轻量（基于 Node.js 构建），内存开销通常不足 50MB。其核心配置通过环境变量传入。

1. 创建规范目录

🖥️ 【服务器窗口】

BASH

sudo mkdir -p /opt/pairdrop
cd /opt/pairdrop

2. 编写 `docker-compose.yml`

在 compose 配置中，有两项关键配置决定了体验稳定性：

WS_FALLBACK=true：当 WebRTC P2P 遭遇严苛对称型 NAT 无法直接打洞时，自动降级为通过 WebSocket 中继传输，保证“只要连上就绝不丢包或失败”；
RTC_CONFIG：配置可靠的公共 STUN 服务器，帮助处于路由器 NAT 后面的设备快速发现各自的内网直连通信地址。

🖥️ 【服务器窗口】

BASH

sudo tee /opt/pairdrop/docker-compose.yml << 'EOF'
version: '3.8'

services:
  pairdrop:
    image: lscr.io/linuxserver/pairdrop:latest
    container_name: pairdrop
    restart: always
    ports:
      - "127.0.0.1:3000:3000"  # 仅绑定本地回环，强制交由 Nginx 代理 HTTPS
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      # --- WebRTC 与信令连接策略 ---
      - WS_FALLBACK=true        # P2P 穿透失败时允许信令中继降级传输
      - RATE_LIMIT=false        # 私有实例建议关闭频率限制，保障内网并发吞吐
      # --- STUN 穿透节点 (协助识别内网路由与对端直连) ---
      - RTC_CONFIG=[{"urls":["stun:stun.l.google.com:19302","stun:stun1.l.google.com:19302","stun:stun.cloudflare.com:3478"]}]
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "2"
EOF

3. 点火启动容器

🖥️ 【服务器窗口】

BASH

cd /opt/pairdrop
sudo docker compose up -d

4. 实时核验容器存活状态

🖥️ 【服务器窗口】

BASH

sudo docker compose ps

核验标准：pairdrop 状态必须显示为 Up，本地端口绑定为 127.0.0.1:3000。

💻 第二步：Nginx 反向代理与 HTTPS 强制开启（核心避坑）

致命红线：现代移动端（特别是 iOS Safari 与 Android Chrome）出于隐私安全策略，强制要求 WebRTC 运行在安全上下文（Secure Context）中！
如果使用不安全的 http:// 访问，浏览器会直接封锁 WebRTC P2P 数据通道与剪贴板 API，导致设备之间在页面上显示“找不到任何同伴（Peer）”。

必须使用 Nginx / OpenResty 配置强制 HTTPS，并正确注入 WebSocket 协议升级标头。

1. Nginx 生产反代块配置

在宿主机 /etc/nginx/conf.d/pairdrop.conf（或 1Panel / 宝塔对应站点配置）中写入：

🖥️ 【服务器窗口】

NGINX

server {
    listen 80;
    server_name drop.0000996.xyz;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name drop.0000996.xyz;

    # SSL 证书配置路径
    ssl_certificate     /etc/nginx/ssl/drop.0000996.xyz.crt;
    ssl_certificate_key /etc/nginx/ssl/drop.0000996.xyz.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # 允许传输超大文件缓冲调优
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 核心：必须开启 WebSocket 协议升级，否则信令断联导致搜不到设备
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 延长超时时间，防止超大文件在握手时被 Nginx 提前切断
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

2. 测试配置并重载

🖥️ 【服务器窗口】

BASH

sudo nginx -t && sudo systemctl reload nginx

📱 第三步：多端实战体验与原生 App 化（PWA）

配置完成后，使用任意设备浏览器打开你的专属网址：https://drop.0000996.xyz。

1. 局域网同 Wi-Fi 自动秒配对

用电脑浏览器（Chrome / Edge）打开 https://drop.0000996.xyz；
用手机（iPhone / 安卓）连接同一个 Wi-Fi，同样打开该网页；
页面雷达波浪动效瞬间收缩，两端屏幕上会立刻浮现出对方的趣味代号图标（如“蓝色的刺猬”、“红色的狐狸”）；
点击设备图标 ➔ 选择文件或直接拖拽文件进网页 ➔ 对方设备弹窗确认 ➔ 秒级完成直连传输！

2. 跨网络配对（手机 5G 流量 ➔ 办公室电脑）

如果两台设备不在同一个路由器局域网下：

点击页面右上角的 「配对（Pair Devices）」 按钮；
页面会生成一个临时的 6 位数字配对码 与 二维码；
另一台设备在页面输入配对码或用微信/相机扫码，两台设备立刻建立起一条虚拟专属加密通道，实现跨外网点对点互传！

3. 一秒变身原生手机 App（PWA 渐进式应用）

你根本不需要去 App Store 或应用商店下载任何第三方软件：

iPhone / iPad：在 Safari 浏览器中点击底部 「分享」 按钮 ➔ 点击 「添加到主屏幕」；
Android：在 Chrome / 夸克中点击右上角三点 ➔ 点击 「安装应用」 或 「添加到主屏幕」；
桌面上会直接生成一个名为 PairDrop 的原生独立图标，点开全屏沉浸式运行，没有地址栏与返回键，体验完全媲美系统级 AirDrop！

🔍 验证测试：阶梯核实验收

1. WebSocket 信令状态真实审计

在电脑浏览器中按 F12 打开开发者工具（DevTools），进入 「Network（网络）」 ➔ 「WS」 面板并刷新网页：

💻 【你自己的电脑】

查看是否有与 /peerjs 或 websocket 的活跃握手；
状态码（Status）必须显示为 101 Switching Protocols；
检查消息流（Messages），两端连接时会周期性交换 ping/pong 心跳包，确认信令通道 100% 存活。

2. P2P 局域网传输吞吐实测

在同局域网下，找一个 1GB~3GB 的大视频文件进行拖拽发送：

观察传输进度条与耗时，正常 Wi-Fi 6 / 千兆交换机环境下，1GB 视频通常在 10~15 秒 内极速完成传输；
登录服务器查看网络流量监控，会发现服务器公网带宽几乎为零，证明流量纯走局域网内网点对点直连，未消耗任何云服务器流量！

🚨 翻车急救站（常见避坑 FAQ）

Q1：连在同一个 Wi-Fi 下，为什么两台设备互相看不到？

核心排查：
1. AP 隔离机制（最常见）：部分家用或公司企业级路由器开启了 「AP 隔离（AP Isolation / Guest Network）」，禁止同一个 Wi-Fi 内的设备互相通信。进入路由器后台关闭「AP 隔离」即可；
2. 双频分流：一台连了 2.4G Wi-Fi，另一台连了 5G Wi-Fi，虽然同一个路由器但处于不同子网段。此时直接使用右上角的 「6 位配对码」 即可瞬间连接。

Q2：提示“WebRTC not supported or secure context required”？

根因：没有使用 HTTPS 访问。现代浏览器禁止在非安全 HTTP 环境下调用 WebRTC 数据通道。
自愈方案：严格通过配置好的域名 https://drop.0000996.xyz 访问，确保地址栏显示安全小锁。

Q3：大文件传输卡在 99% 失败？

自愈方案：
检查 Nginx 反代配置中的 proxy_read_timeout 是否过短，或者 client_max_body_size 限制了包体大小。确保配置了 proxy_read_timeout 600s; 并将包体大小限制关闭。

📋 毕业打钩自检清单

Docker 容器成功启动，127.0.0.1:3000 端口健康监听
域名绑定并配置有效 SSL 证书，全站强制 301 重定向至 HTTPS
Nginx 成功注入 WebSocket 协议头（Upgrade & Connection），心跳 101 Switching Protocols 验证通过
手机与电脑同时打开页面，设备代号雷达秒级互相点亮
局域网拖拽实测传输大文件，带宽跑满内网吞吐且不消耗云服务器外网流量
手机成功添加到主屏幕（PWA），点击桌面图标实现独立全屏运行

# 🎯 核心目标与收益

# 🖥️ 基础环境与全局变量定义

# 💻 第一步：宿主机目录规划与 Docker Compose 编排

# 1. 创建规范目录

# 2. 编写 docker-compose.yml

# 3. 点火启动容器

# 4. 实时核验容器存活状态

# 💻 第二步：Nginx 反向代理与 HTTPS 强制开启（核心避坑）

# 1. Nginx 生产反代块配置

# 2. 测试配置并重载

# 📱 第三步：多端实战体验与原生 App 化（PWA）

# 1. 局域网同 Wi-Fi 自动秒配对

# 2. 跨网络配对（手机 5G 流量 ➔ 办公室电脑）

# 3. 一秒变身原生手机 App（PWA 渐进式应用）

# 🔍 验证测试：阶梯核实验收

# 1. WebSocket 信令状态真实审计

# 2. P2P 局域网传输吞吐实测

# 🚨 翻车急救站（常见避坑 FAQ）

# Q1：连在同一个 Wi-Fi 下，为什么两台设备互相看不到？

# Q2：提示“WebRTC not supported or secure context required”？

# Q3：大文件传输卡在 99% 失败？

# 📋 毕业打钩自检清单

🎨 选择精选主题配色

🎯 核心目标与收益

🖥️ 基础环境与全局变量定义

💻 第一步：宿主机目录规划与 Docker Compose 编排

1. 创建规范目录

2. 编写 `docker-compose.yml`

3. 点火启动容器

4. 实时核验容器存活状态

💻 第二步：Nginx 反向代理与 HTTPS 强制开启（核心避坑）

1. Nginx 生产反代块配置

2. 测试配置并重载

📱 第三步：多端实战体验与原生 App 化（PWA）

1. 局域网同 Wi-Fi 自动秒配对

2. 跨网络配对（手机 5G 流量 ➔ 办公室电脑）

3. 一秒变身原生手机 App（PWA 渐进式应用）

🔍 验证测试：阶梯核实验收

1. WebSocket 信令状态真实审计

2. P2P 局域网传输吞吐实测

🚨 翻车急救站（常见避坑 FAQ）

Q1：连在同一个 Wi-Fi 下，为什么两台设备互相看不到？

Q2：提示“WebRTC not supported or secure context required”？

Q3：大文件传输卡在 99% 失败？

📋 毕业打钩自检清单