AirScan-QR 二维码流文件传输工具技术分析
一、项目概述
1. 项目简介
A. 核心定位
AirScan-QR 是一款专为物理隔离环境及跨端受限网络设计的高效文件传输方案。它通过动态二维码序列流，利用屏幕与摄像头的视觉链路，打破物理边界与网络协议限制。
B. 项目价值
解决在无法连接互联网、禁用 U 盘、或无法建立局域网共享的场景下的数据传输痛点。项目已在 GitHub 获得 156 个 Star、20 个 Fork，证明了其解决实际问题的有效性。
C. 技术特点
- 纯前端实现，零服务器依赖
- 单 HTML 文件架构，便于离线部署
- 基于二维码流的视觉传输协议
- 支持跨平台、跨设备互传
二、核心应用场景
1. 物理隔离环境
A. 封闭开发/实验室环境
从物理隔离的内网 PC 中取出日志、代码片段或小文件，无需通过 USB 等物理介质。
B. 安全隔离场景
在高安全要求的环境下，通过视觉链路进行数据交换，不产生网络连接记录。
2. 跨设备互传
A. 手机与手机之间
Android 与 iOS 设备之间，无需蓝牙或 WiFi，开码即传。
B. 跨操作系统
不同操作系统之间的文件互传，不受协议兼容性限制。
3. 远程桌面穿透
A. VPN 穿透
直接通过摄像头扫描远程桌面窗口中的二维码，将文件从远程服务器传输到本地 PC。
B. 虚拟机文件提取
从虚拟机屏幕中提取文件，无需配置共享文件夹或网络。
4. 无痕传输
A. 隐私保护
无需安装驱动，无需注册账号，所有逻辑在浏览器本地执行。
B. 零日志残留
不经过中转服务器，不留物理传输痕迹。
三、技术架构
1. 系统架构
graph LR
A[发送端] -->|屏幕显示| B[二维码流]
B -->|摄像头识别| C[接收端]
subgraph 发送流程
A1[文件选择] --> A2[Base64编码]
A2 --> A3[切片分段]
A3 --> A[动态帧率]
end
subgraph 接收流程
C --> C1[索引校验]
C1 --> C2[分片重组]
C2 --> C3[自动下载]
end
2. 二维码流水线协议
A. 协议格式
TaskID | FileName | TotalFrames | CurrentIndex | DataPayload
B. 协议组成
- TaskID：唯一任务标识符
- FileName：原始文件名（支持超长文件名及后缀名）
- TotalFrames：总帧数
- CurrentIndex：当前帧索引
- DataPayload：实际数据载荷
C. 数据编码流程
- 文件读取为二进制数据
- 转换为 Base64 编码
- 按单帧容量切片（200-800 Byte 可调）
- 生成二维码序列流
3. 核心技术组件
A. 二维码生成与识别
基于 qrious 库的优化算法，支持高效二维码编码与解码。
B. 帧率控制
支持 1-30 FPS 动态帧率调节，根据环境光照和扫描端性能自适应调整。
C. 分片重组机制
通过数组索引重组分片，确保文件合并顺序 100% 准确。
四、功能特性
1. 高速流传输
A. 动态帧率调节
根据环境条件实时调整播放速度，平衡传输效率与识别准确率。
B. 单帧容量可调
支持 200-800 Byte 单帧容量调节，适配不同性能的扫描端设备。
2. 智能补帧机制
A. 缺失帧矩阵可视化
实时显示传输过程中的缺失帧，方便用户了解传输状态。
B. 单点重传
点击特定缺失帧即可进行单点重传，攻克环境光干扰导致的跳帧难题。
3. 元数据保留
A. 文件名还原
支持超长文件名及后缀名的无损还原。
B. 文件完整性
通过索引校验确保文件完整性，接收后可直接使用。
4. 用户体验优化
A. 响应式设计
基于 Tailwind CSS 构建，适配手机与 PC 端。
B. 深色模式支持
自动适配系统主题，支持深色模式。
五、版本说明
1. 正式版（index.html）
A. 技术路线
单码循环播放传文件。
B. 支持功能
- 摄像头扫码
- PC 跨应用扫码
C. 适用场景
通用文件传输场景，稳定可靠。
2. 喷泉版（airscan-fountain.html）
A. 技术路线
四码同传技术，实现了喷泉码。
B. 技术优势
- 解决丢帧需要重传的问题
- 极大提升传输效率
- 并行传输多个数据分片
C. 已解决问题
感谢 @YILS-LIN 解决简单文本导致卡死的问题。
六、部署与使用
1. 快速上手
A. 手机与手机互传
- 两台设备均访问 https://topcss.github.io/AirScan-QR/
- 发送方点击选择文件，设置帧率，开始广播
- 接收方点击开始扫描，对准发送方屏幕
- 完成后自动触发下载
B. PC 与手机互传
- 内网 PC 打开项目（可通过 HTML 离线文件）
- 发送方选择文件并广播
- 手机扫码接收，实现文件出网
C. 远程 PC 与本机 PC
- 在远程窗口中运行发送端并显示二维码
- 本机 PC 接收时，选择屏幕录制，选择对应的应用窗口
- 即可接收文件
2. 部署方式
A. 在线访问
通过 GitHub Pages 直接使用，无需任何配置。
B. 本地携带
右键另存为 index-embedded.html，嵌入式单文件版本，放入 U 盘随身携带。
C. 内网分发
直接将 HTML 文件部署在内网静态服务器或共享文件夹中。
D. HTTPS 服务器
项目提供 https_server.py，可在本地快速启动 HTTPS 服务。
七、技术原理深度分析
1. 视觉传输协议
A. 协议设计思路
将文件数据编码为视觉信号（二维码），通过摄像头捕获并解码，实现数据传输。
B. 传输效率优化
- 动态帧率：根据识别成功率自动调整
- 分片大小：根据设备性能选择最优值
- 并行传输：喷泉版支持四码同传
2. 容错机制
A. 索引校验
每帧数据包含索引信息，接收端按索引重组，确保顺序正确。
B. 缺失重传
可视化缺失帧，支持单点重传，提高传输可靠性。
C. 数据校验
通过 TaskID 确保数据包属于同一传输任务。
3. 安全性分析
A. 零服务器架构
所有数据处理在浏览器本地完成，不经过中转服务器。
B. 隐私保护
无需账号注册，不记录传输日志。
C. 局限性
视觉传输可能被现场监控设备捕获，敏感数据需谨慎使用。
八、技术亮点与创新
1. 极简架构
A. 单文件设计
index-embedded.html 将所有代码内联，真正的单文件应用。
B. 零依赖部署
无需安装任何依赖或插件，浏览器直接运行。
2. 跨平台兼容性
A. 设备无关性
只要有屏幕和摄像头的设备即可使用。
B. 操作系统无关性
不依赖特定操作系统或网络协议。
3. 喷泉码实现
A. 技术创新
四码同传技术，大幅提升传输效率。
B. 工程挑战
解决了简单文本导致卡死的问题，体现技术攻坚能力。
九、应用前景
1. 企业内网环境
A. 安全数据交换
在物理隔离的内外网之间进行安全数据交换。
B. 应急传输
在网络故障或设备故障时的应急数据传输方案。
2. 个人使用场景
A. 跨设备互传
手机、平板、电脑之间的快速文件分享。
B. 无网络环境
出差、旅行等无网络环境下的文件传输。
3. 特殊行业应用
A. 军工、政府
高安全要求环境下的数据交换。
B. 实验室、研发
物理隔离环境下的数据提取。
十、项目生态
1. 开源协议
MIT License，允许自由使用、修改和分发。
2. 社区贡献
A. 待解决问题
项目发出召集令，邀请开发者共同挑战视觉传输效率极限。
B. 贡献者
- Jack/topcss：项目发起者
- @YILS-LIN：解决喷泉版卡死问题
3. 技术栈
A. 前端
- HTML（99.8%）
- Tailwind CSS：UI 框架
- qrious：二维码生成库
B. 后端辅助
- Python（0.2%）：HTTPS 服务器脚本
十一、总结与展望
1. 技术价值
AirScan-QR 通过创新的视觉传输方案，解决了特定场景下的文件传输难题。其零服务器、单文件、跨平台的设计理念，为受限环境下的数据交换提供了优雅的解决方案。
2. 创新亮点
- 喷泉码四码同传技术
- 智能补帧机制
- 动态帧率调节
- 零依赖单文件架构
3. 发展方向
A. 传输效率优化
继续探索视觉传输的效率极限，提升传输速度。
B. 适用场景扩展
拓展更多应用场景，如大文件传输、流媒体传输等。
C. 用户体验改进
优化界面交互，提升易用性。