# H5 访问

H5 访问是 Gaster Code 桌面端的可选远程入口。开启后，你可以把本机服务通过局域网或自己的反向代理暴露给手机浏览器，使用同一套聊天 UI 继续处理会话。

它不是公开 SaaS 登录系统。任何拿到 H5 Token 的人，都可以访问当前桌面端服务暴露的核心聊天能力，所以只应该在可信网络、可信域名或可信团队范围内使用。

## 开启方式

1. 打开 `设置 -> 通用 -> H5 访问`。
2. 开启 `启用 H5 访问`。
3. 生成或重新生成 Token。
4. 立即复制生成的 Token。Token 明文只显示一次；丢失后只能重新生成。
5. 按访问方式填写允许来源：
   - 局域网访问：例如 `http://192.168.1.20:5174`
   - 反向代理访问：例如 `https://gaster.example.com`
6. 如果使用固定域名，可以填写公开访问地址，设置页会据此生成 H5 URL。

H5 设置保存到 `~/.claude/gaster-code/settings.json`。系统只保存 Token 哈希，不保存 Token 明文。

## 访问地址

浏览器入口使用前端地址加 `serverUrl` 参数：

```text
https://gaster.example.com/?serverUrl=https%3A%2F%2Fgaster-api.example.com
```

首次打开时，H5 页面会要求输入：

| 字段 | 说明 |
|------|------|
| Server URL | 桌面端服务或反向代理后的后端地址 |
| H5 Token | 设置页生成的 Token |

验证成功后，浏览器会把 Server URL 和 Token 保存在当前浏览器的 `localStorage`，之后自动携带 REST `Authorization` 和 WebSocket `token` 参数。

## 推荐部署

### 局域网

适合个人手机测试：

1. 让后端监听局域网地址，或由你自己的代理转发到本机端口。
2. 在设置页把手机浏览器打开的前端来源加入允许来源。
3. 手机和电脑连接同一个可信网络。
4. 手机打开 H5 URL，输入 Token。

### 反向代理

适合小团队访问：

1. 使用 HTTPS 域名代理前端静态资源和后端 API。
2. 把前端来源加入 H5 允许来源，不要使用通配来源。
3. 确保 `/api/*`、`/proxy/*` 和 `/ws/*` 都转发到桌面端服务。
4. WebSocket 代理需要支持协议升级。
5. 只把域名和 Token 分享给可信成员。

## 手机体验范围

H5 第一版优先保证聊天主流程：

- 会话列表通过抽屉打开，默认收起。
- 聊天区是主界面。
- 输入框、发送/停止、附件和权限按钮使用手机可点的尺寸。
- `@` 文件菜单适配手机宽度。
- 模型、权限、项目、分支和 worktree 选择器在窄屏使用底部弹层。

桌面端和 Tauri 应用仍保留原来的布局和交互。

## 安全注意

- H5 默认关闭。
- Token 明文只出现一次。
- 远程 API、代理接口和 WebSocket 都需要 H5 Token。
- CORS 只允许设置页配置的来源。
- 禁用 H5 或重新生成 Token 后，旧 Token 会失效。
- 不要把 H5 公开暴露后再把 Token 发到公开渠道。

## 排查

| 现象 | 处理 |
|------|------|
| 页面提示需要 Token | 在设置页复制最新 Token，重新输入 |
| Token 无效 | 重新生成 Token，并更新手机浏览器里保存的 Token |
| 无法连接 Server URL | 检查后端地址、端口、防火墙和反向代理 |
| 浏览器被 CORS 拦截 | 把当前前端来源加入 H5 允许来源 |
| WebSocket 连接失败 | 检查反向代理是否转发 `/ws/*` 并启用 WebSocket upgrade |
