Skip to content

WiFi 局域网传输(wifi-bridge) ​

wifi-bridge 是框架的可选 feature:在设备上起一个 HTTP 服务,让同一局域网内的电脑 用浏览器上传/查看文件。它只负责传输——文件落盘、任务状态、HTTP 服务、Web 页面; 上传后的业务处理(入库、解析、刷新 UI)由各项目自己写。

名字叫 wifi-bridge,不绑定任何业务。它只做文件传输与落盘,不关心文件是什么类型。


一、启用 ​

生成项目时加 --features:

bash
# 生成时就带上(默认 core 模式,项目自包含)
node scripts/create.mjs ../my-app --features wifi-bridge

# 默认值来自 app.config.json 的 generator.features
#   "generator": { "features": ["wifi-bridge", "privacy-consent"] }

generator.features 是生成时字段:已经生成过的项目改它不会生效,要重新生成; 命令行 --features 优先于 app.config.json,传了就完全按参数走。

create.mjs 会自动做这些事:

注入点内容
rust/Cargo.toml加 aura-wifi-bridge 依赖(按 core / link 模式写成对应形式)
rust/src/lib.rs在 build_router() 里注册 /wifi/start、/wifi/stop、/wifi/status,首次调用时懒安装 WifiBridge(此时平台已是真实平台)
wifi-web/独立的 Vite 工程(默认 Vue3,--web react 可换 React),根路径 / 的页面就是它的产物
rust/build.rs把 wifi-web/dist 编译进二进制,生成 web_assets.rs 供 BridgeOptions.web_assets 使用
android/.../WifiTransferService.kt前台服务类(PARTIAL_WAKE_LOCK + HIGH_PERF WifiLock + 常驻通知)
android/.../AndroidManifest.xmlACCESS_WIFI_STATE / FOREGROUND_SERVICE / FOREGROUND_SERVICE_SPECIAL_USE / POST_NOTIFICATIONS 权限 + <service> 声明

不开这个 feature 时,上述占位符都会替换成空内容,不留下任何依赖或死代码。

Web 端的框架用 --web 指定:

bash
node scripts/create.mjs ../my-app --features wifi-bridge            # 默认 vue
node scripts/create.mjs ../my-app --features wifi-bridge --web react
node scripts/create.mjs ../my-app --features wifi-bridge --web none # 不要 wifi-web/,用内置兜底页

二、跑通 ​

dev 模式(桌面) ​

bash
pnpm install
pnpm dev:rust          # 终端 A:aura-dev-server(3456)
pnpm dev:frontend      # 终端 B:前端

调用 POST /dispatch {"path":"/wifi/start","params":{"port":30000}} 启动传输服务, 然后用浏览器打开 http://127.0.0.1:30000(根路径就是传输页)。

dev 模式下 main.rs 会把真实的 HostPlatform 注入 router, 所以上传目录与真机一致,落在 ~/.<slug>/uploads。

改 Web 页面时不用重新编译 Rust(先按上面的方式把传输服务起来):

bash
pnpm dev:wifi-web     # Vite dev server(5173),/bridge 代理到 http://127.0.0.1:30000

代理目标可用 BRIDGE_TARGET 覆盖,例如真机调试时:

bash
BRIDGE_TARGET=http://192.168.1.23:30000 pnpm dev:wifi-web

wifi-web/vite.config.ts 里的 base: './' 不要改成 /:产物在根路径和 /bridge/ 下都要能加载。

真机(Android) ​

  1. 手机与电脑连同一个 WiFi;
  2. App 内先调 /wifi/start(或由你自己的界面按钮触发);
  3. BridgeStatus.url 返回的形如 http://192.168.x.x:30000;
  4. 电脑浏览器直接打开这个地址(根路径就是传输页,不用再补 /bridge/)。

url 是用 UDP 探测本机出口网卡得到的。若探测到的是模拟器网段(10.0.2.x 等), 框架会回退显示 127.0.0.1;真机上正常是局域网 IP。


三、Web 页面 ​

页面是一个独立的 Vite 工程(项目根目录的 wifi-web/),不是塞在 Rust 里的字符串,默认挂在根路径 /。 Vue 模板栈:Vue3 + vue-router(hash 模式)+ Tailwind CSS 3。

wifi-web/
├── index.html
├── vite.config.ts      ← base: './',dev 时 /bridge 代理到传输服务
├── tailwind.config.js  ← brand 色取自框架配置,content 覆盖 index.html + src
├── postcss.config.js
└── src/
    ├── main.ts
    ├── App.vue         ← 顶栏 + 导航 + <router-view>
    ├── router/index.ts ← /(传输)与 /tasks(任务)
    ├── pages/
    │   ├── TransferPage.vue   ← 服务开关、地址、拖拽上传、最近接收
    │   └── TasksPage.vue      ← 全部接收记录、清空
    ├── api.ts          ← 所有 /bridge/* 请求集中在这里
    ├── format.ts       ← 文件大小 / 状态文案
    └── style.css       ← Tailwind 指令 + 基础样式

React 模板(--web react)是同样的页面结构,导航用 useState 切换,不引入路由库。

初始页面包含:

  • 启动 / 停止服务、显示当前状态与地址
  • 拖拽或点击上传(支持多选)
  • 最近任务列表(文件名、状态、已接收字节、详情),每 2 秒自动刷新

构建与嵌入:

bash
pnpm build:wifi-web    # wifi-web/ 产出 dist/
cargo build            # rust/build.rs 生成 web_assets.rs,把 dist 编译进二进制
  • rust/build.rs 递归收集 wifi-web/dist,生成 include_bytes! 列表;wifi-web/dist 变化会触发重编。
  • lib.rs 里 BridgeOptions { web_assets: Some(web_assets::WEB_ASSETS) } 把它交给服务端。
  • 服务端按扩展名设置 Content-Type;index.html 用 no-cache,assets/* 用一年强缓存。
  • 未命中的路径回退到 index.html(SPA 兜底),显式 API 路由优先于静态资源。
  • 没生成 wifi-web/(--web none)时 web_assets: None,服务端用内置兜底页 WEB_INDEX。

Web 端与 App 前端(frontend/)彼此独立:wifi-web/ 只被浏览器访问,走普通 HTTP + fetch, 不经过 Lynx、不经过 bridge 协议。


四、HTTP API(传输侧) ​

所有路径都以 prefix 为前缀,默认 /bridge。

方法路径说明
GET/管理页面(/bridge/ 同样可用,兼容旧地址)
GET/bridge/status服务状态 + 任务列表
POST/bridge/uploadmultipart 上传(字段名任意,取文件的 filename)
GET/bridge/tasks仅任务列表
POST/bridge/tasks/clear清空任务记录(不删文件)
POST/bridge/start?port=30000在服务内部重启传输服务(一般用不到,正常走 aura 的 /wifi/start)
POST/bridge/stop停止服务

行为细节:

  • 大小限制:单次请求 body 上限默认 512MB,可用 BridgeOptions.max_upload_bytes 调整。 超限时在读取 body 之前就返回 413,body 是 { "ok": false, "error": "本次上传 x MB,超过单次上限 y MB;请分批上传" }。
  • 同源校验:写操作(POST)会校验 Origin 与 Host 是否同源,跨站页面发起的请求返回 403; curl / 原生客户端不带 Origin,正常放行。不提供跨域 CORS。
  • 文件名净化:只取 basename,丢弃路径分隔符、控制字符与隐藏文件名, 杜绝 ../ 或绝对路径写出上传目录。
  • 同名文件:不覆盖,用 create_new 原子占用 book.epub → book_1.epub → book_2.epub; 两个同名文件同时上传也不会互相覆盖。
  • 扩展名白名单:BridgeOptions.allowed_extensions 为空表示不限制;非空时不在名单内的文件会被拒绝并在结果里标 ok: false。
  • 流式落盘:边收边写,不把整个文件读进内存;写入失败会删除半截文件并把任务标为 error。
  • 失败响应:所有接口出错都返回 { "ok": false, "error": "可读原因" }, 例如端口被占用是 409 + 端口 30000 启动失败:…,客户端直接把 error 展示给用户即可。
  • 上传结果:{ "files": [{ "filename", "ok", "size", "path" }] },失败项带 reason。

status 返回结构 ​

json
{
  "running": true,
  "url": "http://192.168.1.23:30000",
  "upload_dir": "/data/user/0/com.acme.app/files/uploads",
  "allowed_extensions": [],
  "max_upload_bytes": 536870912,
  "tasks": [
    {
      "id": "0f1e...",
      "filename": "demo.epub",
      "received_bytes": 1048576,
      "status": "done",
      "detail": "/data/.../uploads/demo.epub",
      "created_at": 1763000000000
    }
  ]
}

max_upload_bytes 供页面提示「单次最大多少」,避免前端把上限写死成 512MB。 status 取值:uploading / done / error。


五、Rust API ​

rust
use aura_wifi_bridge::{WifiBridge, BridgeOptions};
use aura_platform::Platform;

// 1) 进程内初始化一次(重复调用无效)
WifiBridge::install(
    aura.platform().clone(),
    BridgeOptions {
        upload_dir: aura.platform().app_paths().data_dir.join("uploads"),
        allowed_extensions: vec!["epub".into(), "pdf".into(), "txt".into()], // 空 = 不限制
        max_tasks: 50,                 // 任务记录上限,超出丢弃最旧的
        prefix: "/bridge".into(),      // 路由前缀
    },
);

// 2) 启停(start 非阻塞,内部起独立线程跑 tokio)
WifiBridge::start(30000)?;   // 已在运行时直接返回 Ok
WifiBridge::stop();

// 3) 查询
let running = WifiBridge::is_running();
let status = WifiBridge::status();     // -> BridgeStatus

业务侧回写任务状态 ​

框架不知道你的业务是否处理成功。上传落盘后任务状态是 done(表示传输完成), 如果你要做二次处理,可以自己维护状态:

rust
// 处理成功 / 失败后回写(只改内存里的任务记录)
WifiBridge::complete_task(&task_id, "已导入书库");
WifiBridge::fail_task(&task_id, "格式不支持");

目前没有"上传完成自动回调"钩子;业务侧要么轮询 WifiBridge::status().tasks, 要么在 /bridge/tasks 之外自己加一个路由做增量拉取。


六、App 内入口(框架已内置) ​

开启 feature 后,设置页会自动出现「WiFi 传输」:

  • 开关:调 /wifi/start、/wifi/stop
  • 运行中显示 http://<局域网IP>:30000
  • 已接收文件列表,2 秒轮询一次

页面在 frontend/src/components/WifiTransferPage.tsx,入口在 App.tsx 的 SettingsPage,是否显示由 create.mjs 注入的 __WIFI_BRIDGE__ 决定。

需要自己写界面时,直接用普通 aura 路由:

tsx
import { createBridgeClient } from '@aura/bridge-client';

const bridge = createBridgeClient({ bridgePort: 3456 });

// 启动
const res = await bridge.call<{ ok: boolean; url: string }>('/wifi/start', { port: 30000 });

// 查询
const status = await bridge.call<{
  running: boolean;
  url: string | null;
  upload_dir: string;
  allowed_extensions: string[];
  tasks: Array<{ id: string; filename: string; status: string; received_bytes: number }>;
}>('/wifi/status');

// 停止
await bridge.call('/wifi/stop');

把 status.url 显示成二维码/文本,用户扫码或手输到电脑浏览器即可。


七、后台运行与退出(Android) ​

WiFi 传输跑在 App 进程里,切后台后系统可能冻结/回收,所以框架内置了一个前台服务 (WifiTransferService.kt):PARTIAL_WAKE_LOCK + HIGH_PERF WifiLock,并挂一条常驻通知。

链路已经接好,项目侧不用写代码:

text
/wifi/start → WifiBridge::start
            → Platform::set_transfer_server_active(true, Some(url))
            → aura-native 通过 JNI 调 com.aura.runtime.NativeBridge.onTransferServerActive
            → App.kt 注册的钩子 → WifiTransferService.start(ctx, url)

/wifi/stop 走同一条链路收掉服务,通知随之消失。

用户侧行为:

操作结果
传输页「停止传输」服务停掉,页面原地刷新状态
传输页「停止并退出」服务停掉并返回上一页
直接返回(←)服务继续在后台跑,通知栏保留地址
通知栏「停止传输」不打开 App 也能停掉服务
设置页「WiFi 传输」右侧显示「运行中」,离开传输页后仍可看到
其他页面内容区左下角浮出「● 传输中」胶囊,点击直接回到传输页

Android 13+ 会在用户开启传输的那一刻申请通知权限(此时已同意隐私政策,不会在冷启动就弹)—— 后台标识就是那条通知,没有权限等于看不到状态。

服务用 START_NOT_STICKY:进程被杀后不会复活出一条没有对应 HTTP 服务的假通知。

鸿蒙走的是同一套平台能力,实现方式换成「长时任务」:

text
/wifi/start → Platform::set_transfer_server_active(true, url)
            → AuraHost.transfer_server 回调(C ABI)
            → aura_napi.cpp 投递到 ArkTS → EntryAbility.startTransferTask(url)
            → backgroundTaskManager.startBackgroundRunning(DATA_TRANSFER)

需要在 module.json5 里声明 ohos.permission.KEEP_BACKGROUND_RUNNING 并给 Ability 配 backgroundModes: ["dataTransfer"](框架模板已带),系统会在任务中心/通知栏显示后台任务。 没有该权限时 startBackgroundRunning 会失败,代码里静默降级为前台可用。

iOS 做不到真正的后台常驻:系统不允许本地 HTTP 服务长期后台运行, beginBackgroundTask 只能争取约 30 秒,之后进程被挂起、端口失效。 所以 iOS 目前保持空实现,业务上应提示用户「保持 App 在前台完成传输」。


八、已知限制 ​

限制说明
无鉴权局域网内任何人可访问,仅适合可信网络
无断点续传大文件中断需重传
任务只存在内存进程重启后任务记录清空(已落盘的文件还在)
上传完成无事件推送需业务侧轮询或自行加钩子
dev 模式目录在临时目录NullPlatform → $TMPDIR/aura/uploads
iOS 无法后台常驻系统限制,beginBackgroundTask 只能争取约 30 秒

九、和 reader 实现的区别 ​

框架版本是从 reader-app 的 WiFi 文件传输里剥掉业务得到的:

reader 有框架有没有
上传 + 文件落盘✅ 保留
任务进度与状态✅ 保留
Web 管理页✅ 保留(独立的 wifi-web Vite 工程,纯上传/列表)
Android 前台服务类✅ 保留(需手动接线)
书架 / 文件夹 / 章节 / 阅读进度 / 备份 / 在线阅读路由❌ 业务,不进框架
上传后自动解析并入库❌ 业务,由各项目实现

lynx-aura · 跨平台本地应用开发框架