54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# JianF Nav Sync — 浏览器扩展
|
||
|
||
将浏览历史同步到自建导航门户，按总访问频次自动排序「常用服务」与「历史访问」。
|
||
|
||
## 安装
|
||
|
||
### Chrome / Edge（MV3）
|
||
|
||
1. 打开 `chrome://extensions/`
|
||
2. 开启右上角「开发者模式」
|
||
3. 点「加载已解压的扩展程序」，选择本目录的 `chrome/` 文件夹
|
||
4. Edge 同理：`edge://extensions/`
|
||
|
||
### Firefox（MV2）
|
||
|
||
1. 打开 `about:debugging#/runtime/this-firefox`
|
||
2. 点「临时加载附加组件」，选择本目录 `firefox/` 下的 `manifest.json`
|
||
3. 长期使用：`web-ext build` 打包后到 `about:addons` 安装
|
||
|
||
### iOS / 手机浏览器
|
||
|
||
系统浏览器扩展 API 不适用于 iOS Safari 普通网页。可用备选：
|
||
- iOS Safari Web Extension（需 Xcode 工程封装）
|
||
- Android 上使用 Kiwi / Yandex 等支持 MV3 的浏览器加载 `chrome/`
|
||
|
||
## 配置（点击扩展图标）
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| 导航服务地址 | 你的门户根地址，如 `https://nav.example.com`（不要带 `/search` 等路径） |
|
||
| 同步令牌 | 服务端环境变量 `NAVI_SYNC_TOKEN` 的值（**服务端开启鉴权时必填**） |
|
||
| 设备名称 | 可选，留空则自动检测。**Firefox 版**按 UA 识别（desktop-firefox / mobile-* / desktop-edge 等）；**Chrome 版**的 MV3 service worker 里没有 `navigator`，只能回退为 `desktop-browser`（需要区分设备时请手填） |
|
||
|
||
## 行为
|
||
|
||
- **每 30 秒**用 `chrome.history.search` 拉取最近 2 小时新记录（不依赖 onVisited 事件，MV3 休眠也可靠）
|
||
- 本地过滤：搜索引擎域名、`/search?q=` 结果页、`chrome://`、`about:` 等一律**不上传**
|
||
- 同一网址 10 分钟内去重、同批 URL 去重
|
||
- **仅在有待同步数据时发 POST**（无空轮询）
|
||
- 同步失败自动保留队列，下轮重试
|
||
- 上报带 `Authorization: Bearer <token>`；门户「常用服务/历史访问」按 `total_visits` 自动更新
|
||
|
||
## 技术细节
|
||
|
||
- Chrome/Edge: Manifest V3，service worker + `chrome.alarms`(最小周期 30s)
|
||
- Firefox: Manifest V2，event page（`persistent: true`）+ `browser.alarms`
|
||
- 存储: `storage.local`（pending 队列 + 配置）
|
||
- API: `history.search` + `alarms` + `runtime.onMessage`
|
||
- `visit_count` 上报的是 **Chrome/Firefox history API 的绝对累计值**，不是增量。
|
||
服务端（`history-server`）按设备取绝对值再求和，所以重复上报不会把计数放大。
|
||
- 两个目录的 `background.js` **不是同一份文件**：Firefox 额外做设备名识别
|
||
（MV2 常驻后台，`navigator` 可用），并过滤 `moz-extension://`。
|
||
改动时两边都要改，但不要直接整份覆盖。
|