主题
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.xml | ACCESS_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)
- 手机与电脑连同一个 WiFi;
- App 内先调
/wifi/start(或由你自己的界面按钮触发); BridgeStatus.url返回的形如http://192.168.x.x:30000;- 电脑浏览器直接打开这个地址(根路径就是传输页,不用再补
/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/upload | multipart 上传(字段名任意,取文件的 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 前台服务类 | ✅ 保留(需手动接线) |
| 书架 / 文件夹 / 章节 / 阅读进度 / 备份 / 在线阅读路由 | ❌ 业务,不进框架 |
| 上传后自动解析并入库 | ❌ 业务,由各项目实现 |