# webview-shell

**Repository Path**: wyr233/webview-shell

## Basic Information

- **Project Name**: webview-shell
- **Description**: 自建网页变成手机App的三件套：安卓壳、单文件手机页面、零依赖Node后端
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 自建网页 → 手机 App 三件套

把**你自己的网页服务**变成手机上的 App：有推送通知、能调相机、零第三方依赖。
本仓库包含三个配合使用的部分——**可以只用其中一个，也可以三个一起用**。

```
android/   Android 壳（Kotlin + WebView）：独立图标、全屏、相册相机、推送长连接
server/    后端（Node 原生、零 npm 依赖）：AI 陪聊接口 + 记忆库 + 图床，SSE 流式转发
web/       前端（单文件 HTML）：手机端聊天界面，零构建、零框架
```

> **适合谁**：有自建服务（NAS 面板、自托管聊天、个人助手）想在手机上当 App 用，又不想上架商店。
> **不适合谁**：要上架应用商店的项目——这套东西的定位就是**侧载自用**。

---

## 三个部分各解决什么

| 目录 | 解决 | 亮点 |
| --- | --- | --- |
| **`android/`** | "网页套壳"没手感、收不到通知 | 零依赖手写 WebSocket、`specialUse` 前台服务、国产 ROM 保活引导页、Android 15 键盘避让 |
| **`server/`** | 没有后端、聊天记录留不住、模型接口不想暴露给前端 | 441 行零依赖 Node：SSE 流式、多模态（手机发图直接喂模型）、内容寻址图床、**可选**的记忆库检索与写卡 |
| **`web/`** | 想要手机优先的聊天界面，但不想上构建工具 | 单文件 1300 行：流式渲染、发图压缩、亮暗双主题、零依赖 |

**配合关系**（也可以只取其一）：

```
android/ 壳  ──加载──▶  web/ 页面  ──调用──▶  server/ 接口  ──▶  你的模型 API
   │                                              │
   └────── WebSocket 推送（server 广播）◀──────────┘
```

---

## 快速开始（选你要的部分）

### 只想要 Android 壳
看 [`android/README.md`](android/README.md)——**第 1 步是替换占位符**（站点地址、包名、应用名），否则打开是白屏。

### 只想要后端 + 前端
```bash
cd server
export DEEPSEEK_API_KEY=你的key          # 或改成别的兼容 OpenAI 协议的接口
export PORT=8000 DATA_DIR=./data
node server.mjs                          # 零依赖，不用 npm install

# 前端是纯静态：把 web/index.html 用任何静态服务器托管，或用 nginx
```
前端里要改的地方（站点地址、API 路径）写在 [`web/README.md`](web/README.md)。

### 三个一起用（完整体验）
1. 起后端（`server/`），配好 API key 与数据目录
2. 部署前端（`web/`）到你的域名或服务器，确认浏览器能正常聊天
3. 编译壳（`android/`），把 `AppInfo.SITE_URL` 指向你的前端地址
4. 推送需要服务端配合广播（见 [`android/_PUSH_RESEARCH.md`](android/_PUSH_RESEARCH.md)）

---

## 这套东西的"真价值"在哪

代码量不大（合计约 4000 行），但**踩过的坑都留在里面了**：

| 文档 | 里面有什么 |
| --- | --- |
| [`android/_PUSH_RESEARCH.md`](android/_PUSH_RESEARCH.md) | 推送方案调研：国产 ROM 只给上架应用推送权限、`dataSync` 前台服务 6 小时超时陷阱、自建 WebSocket 与厂商通道的取舍 |
| [`android/_BUILD_ENV_REPORT.md`](android/_BUILD_ENV_REPORT.md) | Android SDK 国内下载的可行路径、AGP 与 Gradle 版本兼容矩阵、PowerShell 脚本 BOM 陷阱 |
| [`android/README.md`](android/README.md) | WebView 的三大坑与现成解法 + **Known Issues**（某些 WebView 不保存 cookie 的真实案例） |

---

## 已知问题

**1. 某些 WebView 不保存服务器下发的 cookie**
实测机型上出现过：登录接口返回 200 且带 `Set-Cookie`，但紧接着页面请求就没带上 → 页面反复喊"登录过期"。
本仓库的缓解手段（原生自己登录 + `CookieManager.setCookie` 主动种 cookie + 页面注入凭证）写在 `android/README.md` 的 Known Issues 里。
**注意**：如果你只做浏览器访问，不受此影响。

**2. 长连接会被系统掐**
息屏、切网、省电策略都会断长连接，这是手机常态。壳里的处理是"安静重连"（指数退避 + 单连接锁 + 失败不刷通知）。

**3. 各厂商后台限制**
壳内引导页列了 vivo / 小米 / 华为 / 联想的设置路径，但无法保证 100% 保活——这是国产 ROM 的现实。

---

## 许可

MIT。随便用、随便改、随便商用，出事别找我 🙂

> 所有个人标识（域名、包名、账号、密钥、服务器路径）在开源前都已替换为**占位符**，
> 用之前请按各目录 README 的"占位符表"替换成你自己的。