FilePizza 浏览器文件传输从跑通到能上线的分阶段通关路径【免费下载链接】filepizza:pizza: Peer-to-peer file transfers in your browser项目地址: https://gitcode.com/GitHub_Trending/fi/filepizzaFilePizza 是一个基于 Next.js 15 和 WebRTC 构建的 P2P 文件传输服务文件在上传方与下载方浏览器之间直连传输不落服务器并自带密码保护、多文件打 zip、流式下载等能力。本文按阶段拆解它从跑起来到可上线的几处隐患帮你把一个能交付的 FilePizza 部署出来。一、项目全景功能模块一览WebRTC 直连传输基于 PeerJS文件从浏览器到浏览器直传服务端只做信令与通道元数据短链/长链通道体系每次传输生成 8 位短链和 4 词长链TTL 默认 1 小时存于 Redis 或内存密码保护与举报上传可加密码锁/reported页面处理违规链接举报流式下载Service Worker StreamSaver 把 WebRTC 数据流直接落盘不占浏览器内存多文件 zip一次传多个文件时下载方收到流式打包的 zip暗色模式与移动端next-themes View TransitionsMobile Safari 可用最小可运行命令git clone https://gitcode.com/GitHub_Trending/fi/filepizza cd filepizza pnpm install pnpm dev # 打开 http://localhost:3000环境要求Node v18包管理器必须用 pnpm仓库强制npm/yarn 不被支持要做全链路 WebRTC 测试Redis coturn时运行pnpm dev:full会自动拉起对应容器。先说结论跑通≠能上线。下面按配置与凭据、数据与权限、构建与环境、体验与一致性四个阶段拆雷。二、分阶段排雷阶段 A 配置与凭据环境变量是唯一入口生产 compose 引用了.env仓库却不带模板你会看到什么照文档换成生产部署后docker compose -f docker-compose.production.yml up直接报env file .env not found。定位docker-compose.production.yml 的 filepizza 服务声明了env_file: - .env但仓库里既没有.env也没有任何示例文件。全部可用变量清单在 README.md 的 Configuration 小节REDIS_URL、COTURN_ENABLED、TURN_HOST、TURN_REALM、STUN_SERVER、PEERJS_HOST、PEERJS_PATH。处理办法在 compose 文件旁手动创建.env按清单填写。只部署单实例、暂不开 TURN 时最小配置是REDIS_URL加COTURN_ENABLEDfalse。验证执行docker compose -f docker-compose.production.yml config输出里能看到你设置的环境变量且无报错即通过。信令默认走公有云0.peerjs.com不过中转服务器只对文件本身成立你会看到什么README 强调data is never stored in an intermediary server但你不设置PEERJS_HOST时PeerJS 的信令双方发现彼此、交换连接参数的那一步不含文件数据实际走公有 PeerJS 云。网络环境对公有云不友好时连接会一直握手不上。定位src/app/api/ice/route.ts 中peerjsHost process.env.PEERJS_HOST || 0.peerjs.com默认值就是公有云。处理办法自建 PeerJS 服务器并把PEERJS_HOST/PEERJS_PATH指向它仓库提供了pnpm start:peerjs脚本运行./bin/peerjs.js。验证启动服务后执行curl -X POST http://localhost:3000/api/ice确认返回的host是你自建地址而非0.peerjs.com。阶段 B 数据与权限存储选型决定链接活不活得过重启进程一重启链接全灭默认是内存存储你会看到什么开发机上刚生成的链接还正常重启服务后访问直接 404多实例部署时链接时灵时不灵。定位src/channel.ts 的getOrCreateChannelRepo()只有两种实现——设置了process.env.REDIS_URL时用RedisChannelRepo并打印[ChannelRepo] Using Redis storage否则用MemoryChannelRepo打印[ChannelRepo] Using in-memory storage。链接 slug 到上传者 PeerID 的映射和 TTL 全存在这里。处理办法生产部署必须设REDIS_URL。docker-compose.production.yml 已内置 redis 服务并配好REDIS_URLredis://redis:6379保留即可。验证启动服务后在日志里确认出现Using Redis storage生成一个链接重启容器再用新浏览器窗口打开链接仍能解析。开发环境 NAT 穿透失效TURN 中继端口全被注释掉了你会看到什么两个用户跨网络传输一个公司内网、一个手机热点时双向干等连不上同一套配置放生产却正常。定位docker-compose.yml 中 coturn 服务的# Relay Ports一行和49152-65535/udp端口段全部被注释启动命令也没有--min-port/--max-port而 docker-compose.production.yml 开放了60000-60128/udp并带对应参数。TURN 是中继服务器中继端口不开放打洞失败后这条兜底路径就断了。处理办法跨网络实测请用pnpm dev:fullpackage.json 中它会拉起同一份 dev compose并在你自己的部署副本里参照生产 compose 补上中继端口段。验证docker compose logs coturn观察跨网传输时是否出现中继端口分配记录或用手机热点 办公室网络实测一次成功。阶段 C 构建与环境镜像、构建与启动链路redis:latest和 coturn 镜像不锁版本今天能构建明天可能翻车你会看到什么第一次构建部署一切正常几周后重跑pnpm docker:build行为不一致或拉到的新镜像直接不兼容。定位两份 compose 文件里 redis 写的是image: redis:latestcoturn 写的是image: coturn/coturn隐式 latest第三方镜像不锁版本构建不可复现。处理办法在自己的部署副本里把验证过的版本固定下来如redis:7-alpine加 coturn 的具体版本号并记录进部署文档。验证执行docker compose config --images确认所有镜像都解析为具体版本 tag。构建后不懂 standalone 就启不起来你会看到什么pnpm build之后你习惯性地next start可容器入口却是node server.js两条启动路径并不等价目录结构对不上。定位next.config.js 设置output: standalone构建产物是一个自带server.js、不依赖完整 node_modules 的最小服务器package.json 的 build 脚本额外执行cp -r public .next/standalone/与cp -r .next/static .next/standalone/.next/Dockerfile 的 runner 阶段只拷贝这三部分且以非 root 的USER node运行。处理办法生产启动路径不要走next start要么直接node .next/standalone/server.js要么以 Dockerfile 为唯一参照。验证执行pnpm docker:build pnpm docker:up然后curl http://localhost:8080确认返回 200。阶段 D 体验与一致性开发行为与生产行为对齐开发环境看到重复的两条连接生产只有一条你会看到什么pnpm dev时上传方和下载方建立 peer 连接会重复控制台看到重复的 connect 事件、进度条抖动切到生产构建就正常了。定位next.config.js 刻意设置reactStrictMode: false注释写明原因——uploader 和 downloader 都用 useEffect 监听 PeerJS 事件StrictMode 在开发模式的双重调用会把连接创建两次。处理办法保留该配置不要为了开发更严格随手改回 true确需开启时先参考 src/hooks/useUploaderChannel.ts 的写法把事件订阅收敛到每个连接只订一次。验证pnpm dev后开上传页与下载页各一个窗口在控制台确认 PeerJS 连接只建立一次。上传者一走链接立即变孤儿你会看到什么传输完成后上传者关闭页面别人再用同一链接发起新下载立刻失败容易被当成 bug 上报。定位这是项目定位而非缺陷——文件本体只存在于上传者机器README.md FAQ 明确写了关闭浏览器后 URLs will no longer work。另外通道 TTL 默认 1 小时src/config.ts 中channel.ttl: 60 * 60即使上传方还在链接超时也会失效可通过/api/renew接口续期。处理办法在产品文案里明确告知请保持页面开启直到传输完成需要更长有效期就调用 renew 时传入 TTL 参数。验证生成链接后关掉上传窗口确认新窗口打开链接不可用再保留上传页、调/api/renew续期确认原到期时间点后链接仍可用。三、上线自检表检查项怎么做通过标准.env配齐按 README 变量清单填写REDIS_URL、COTURN_ENABLED等docker compose -f docker-compose.production.yml config无报错且值符合预期PeerJS 自建部署 PeerJS 并设置PEERJS_HOST/PEERJS_PATHPOST /api/ice返回host为自建地址Redis 生效查看服务启动日志输出[ChannelRepo] Using Redis storage链接存活重启生成链接 → 重启容器 → 打开链接链接仍可解析NAT 穿透跨网实测并查 coturn 日志跨网传输成功日志有中继端口分配镜像版本锁定副本中固定 redis/coturn tagdocker compose config --images全部为具体版本standalone 启动链路pnpm docker:build pnpm docker:upcurl http://localhost:8080返回 200全量 CI 自检pnpm cilint、format、type-check、单测、构建、e2e、docker 构建全部通过按这四个阶段过一遍FilePizza 就从本地 demo 变成了链接不过夜消失、跨网可穿透、构建可复现的可交付状态。过程中你摸熟的环境变量单一配置入口、状态存储单一事实源、镜像锁版本、开发生产行为对齐这几套方法在任何自托管部署场景都能直接复用。【免费下载链接】filepizza:pizza: Peer-to-peer file transfers in your browser项目地址: https://gitcode.com/GitHub_Trending/fi/filepizza创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考