From 8b5de63ae97b9ce4113931171b48df2d19a10829 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E5=91=98=E9=98=BF=E6=B1=9F=28Relakkes?= =?UTF-8?q?=29?= Date: Sun, 10 May 2026 01:15:50 +0800 Subject: [PATCH] Document opt-in H5 browser access The desktop docs now explain the intended H5 setup path for personal and team use: enable H5 in Settings, generate a one-time token, configure allowed origins, and use LAN or a reverse proxy to open the mobile browser chat surface. Constraint: H5 is opt-in browser access, not a public multi-tenant auth system. Rejected: Hide the setup details in the implementation spec only | users need operational guidance for token handling, CORS, and reverse proxy routing. Confidence: high Scope-risk: narrow Directive: Keep this page aligned with Settings labels and the token/CORS behavior before documenting broader public hosting. Tested: bun run check:docs Tested: Live local smoke with temporary HOME: /health 200, H5 verify without token 401, H5 verify with token 200, configured Origin echoed by CORS. --- docs/.vitepress/config.mts | 1 + docs/desktop/06-h5-access.md | 89 ++++++++++++++++++++++++++++++++++++ docs/desktop/index.md | 4 ++ 3 files changed, 94 insertions(+) create mode 100644 docs/desktop/06-h5-access.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index f45a1290..4a1d44e8 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -91,6 +91,7 @@ const zhSidebar = [ { text: '架构设计', link: '/desktop/02-architecture' }, { text: '功能详解', link: '/desktop/03-features' }, { text: '安装与构建', link: '/desktop/04-installation' }, + { text: 'H5 访问', link: '/desktop/06-h5-access' }, ], }, { diff --git a/docs/desktop/06-h5-access.md b/docs/desktop/06-h5-access.md new file mode 100644 index 00000000..46425205 --- /dev/null +++ b/docs/desktop/06-h5-access.md @@ -0,0 +1,89 @@ +# H5 访问 + +H5 访问是一个可选的个人/团队使用入口。开启后，你可以把桌面端使用的本地服务通过局域网或自己的反向代理暴露出去，然后在手机浏览器里打开同一套聊天 UI。 + +它不是公开 SaaS 登录系统。任何拿到 H5 Token 的人，都可以访问当前桌面端服务暴露的核心聊天能力，所以只应该在你可控的网络、域名和团队范围内使用。 + +## 开启方式 + +1. 在桌面端打开 `设置 -> General -> H5 访问`。 +2. 打开 `启用 H5 访问`。 +3. 点击生成或重新生成 Token。 +4. 立即复制生成的 Token。Token 原文只显示一次；丢失后只能重新生成。 +5. 按你的访问方式填写允许来源： + - 局域网访问：例如 `http://192.168.1.20:5173` + - 反向代理访问：例如 `https://cc.example.com` +6. 如果你使用固定域名，可以填写公开访问地址，设置页会据此生成 H5 URL。 + +H5 设置保存到 `~/.claude/cc-haha/settings.json`。系统只保存 Token 哈希，不保存 Token 明文。 + +## 访问地址 + +浏览器入口使用前端地址加 `serverUrl` 参数： + +```text +https://cc.example.com/?serverUrl=https%3A%2F%2Fcc-api.example.com +``` + +如果前端和后端由同一个反向代理路径提供，可以把 `serverUrl` 指向同一个公开服务根地址。 + +首次打开时，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 的第一版优先保证聊天主流程： + +- 会话列表通过抽屉打开，默认收起。 +- 聊天区是主界面。 +- 输入框、发送/停止、附件和权限按钮使用手机可点的尺寸。 +- `@` 文件菜单会适配手机宽度。 +- Workspace 面板和底部 Terminal 面板在手机宽度下不作为主流程显示。 + +桌面端和 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 | diff --git a/docs/desktop/index.md b/docs/desktop/index.md index 41ca79ab..d5a388bd 100644 --- a/docs/desktop/index.md +++ b/docs/desktop/index.md @@ -24,6 +24,10 @@ 下载安装、macOS/Windows 常见问题、Web UI 模式。 +### [H5 访问](./06-h5-access.md) + +面向个人和团队的可选浏览器访问：开启 H5、生成 Token、配置允许来源、通过局域网或反向代理在手机上访问聊天界面。 + --- ## 快速开始