68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# Hearth Server 示例
|
||
|
||
Hearth 启动器的 webAPP / 卡片下发服务端示例。**本质是纯静态文件**，无需后端逻辑。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
Hearth_Server/
|
||
├── manifest.json # webAPP 清单（客户端启动时拉取）
|
||
├── apps/<id>/index.html # 各 webAPP 入口页
|
||
├── icons/<id>.svg # 图标
|
||
├── offlines/<id>.zip # 可选离线包（整站资源打成 zip）
|
||
└── cards/
|
||
├── catalog.json # 首页卡片目录
|
||
└── <id>/card.html # 单个卡片
|
||
```
|
||
|
||
## 快速启动（测试用）
|
||
|
||
```bash
|
||
cd ~/Project/Hearth_Server
|
||
python3 -m http.server 8080
|
||
```
|
||
|
||
然后在 Hearth 设置页 →「webAPP 服务器地址」填 `http://<本机IP>:8080`。
|
||
|
||
## 正式部署
|
||
|
||
- nginx：`location / { root /path/to/Hearth_Server; }`
|
||
- 或传云对象存储（OSS/COS）+ CDN，整个目录原样上传
|
||
|
||
## 更新流程
|
||
|
||
1. 改 webAPP 资源（`apps/` 下的文件）
|
||
2. 改 `manifest.json` 的 `version`（+1）
|
||
3. 客户端「检查更新」或重启即可拉取
|
||
|
||
## manifest.json 字段
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `version` | 清单版本号，客户端据此判断更新 |
|
||
| `apps[].id` | 唯一 id |
|
||
| `apps[].name` | 显示名 |
|
||
| `apps[].icon` | 图标地址（建议 SVG） |
|
||
| `apps[].url` | 入口页地址（相对地址即可） |
|
||
| `apps[].offline.package` | 可选离线包 zip 路径 |
|
||
| `apps[].offline.version` | 离线包版本 |
|
||
|
||
## 离线包
|
||
|
||
- 把某个 webAPP 的**全部资源**（`apps/<id>/` 下所有文件，含子目录）打成 zip，放 `offlines/<id>.zip`
|
||
- zip 内需**包含 index.html**（作为离线入口）
|
||
- 生成示例：`cd apps/demo && zip -r ../../offlines/demo.zip .`
|
||
|
||
## 离线包使用与版本管理
|
||
|
||
- **下载时机**：客户端拉取清单时**只同步列表，不自动下载程序包**；只有首次点开某 webAPP 时才下载（显示进度覆盖层）。
|
||
- **本地优先**：下载后解压到本地目录，之后点开直接本地加载；**服务端删除该离线包不影响本地运行**。
|
||
- **手动导入**：长按 webAPP 卡片 →「导入离线包」→ 选择本地 zip（适用于无服务器或离线分发场景）。
|
||
- **版本更新**：
|
||
- `manifest.json` 里把 `offline.version` 升版本后，客户端列表该 webAPP 显示「**可更新**」标签（**不强制**，点开仍运行本地旧版）。
|
||
- 长按卡片弹出菜单：
|
||
- `更新离线包`（删除本地并重新下载，显示版本 x → y）
|
||
- `删除本地包`
|
||
- `属性`（查看本地 / 云端版本号）
|
||
- 云端版本号 ≤ 本地版本号时不提示更新。
|