61 lines
8.3 KiB
Markdown
61 lines
8.3 KiB
Markdown
# 架构设计
|
||
|
||
```text
|
||
Gio UI / CLI
|
||
↓ DTO + commands
|
||
Application BrowserManager
|
||
↓ ports
|
||
Platform Windows
|
||
├─ executable discovery
|
||
├─ launcher
|
||
├─ process identity / query
|
||
├─ graceful close / force kill
|
||
├─ Job Object
|
||
├─ profile occupancy inspector
|
||
├─ loopback CDP endpoint inspector
|
||
├─ loopback CDP target reader (read-only `/json/list`)
|
||
├─ remote-debug port allocator
|
||
├─ instance status refresher
|
||
├─ portable config path resolver / legacy migrator
|
||
├─ Windows executable file picker
|
||
└─ notification-area adapter (Windows Shell)
|
||
↓
|
||
Chrome / Edge processes
|
||
```
|
||
|
||
UI/CLI 不直接操作 `exec.Cmd`、Win32 handle 或数据库。Application 层维护实例状态和授权边界；Platform 层只提供系统能力。
|
||
|
||
## 实例身份
|
||
|
||
每个实例至少记录 `instance_id`、browser kind、executable、root PID、user data dir、profile directory、非敏感参数摘要、关联的 loopback CDP 端口、归属（托管或外部关联）、创建时间、状态和退出码。
|
||
|
||
进程身份校验至少比较 PID 存活、executable、命令行中的规范化 `--user-data-dir` 和注册记录。无法确认身份时只能报告 UNKNOWN，不允许关闭。
|
||
|
||
## 生命周期
|
||
|
||
`CREATED -> STARTING -> RUNNING -> STOPPING -> EXITED`；启动失败为 `FAILED`，无法确认的外部实例为 `UNKNOWN`。
|
||
|
||
- Start：规范化路径和参数，先检查 user data dir。未占用时优先从实例持久化的首选端口分配；UI 在启动快照中提供其他 Chub 实例的逻辑预留/实际端口，启动器跳过这些端口后检查 loopback 可用性。注册 pending 后以受控的 `--remote-debugging-address=127.0.0.1` 和 `--remote-debugging-port` 启动，并直接请求该已知端口的 `/json/version` 验证实际端点；发生外部端口冲突且回退成功时才更新当前实例首选端口。
|
||
- 外部关联：目录被占用时只检查该目录中的 `DevToolsActivePort` 和其 loopback `/json/version`；端点与浏览器类型均匹配才报告 `EXTERNAL_ASSOCIATED`，不注册、关闭、重启或强制终止该 PID。无法验证时保持 `UNKNOWN`/占用并拒绝启动。
|
||
- Stop：校验身份，优先窗口关闭/浏览器协议，超时后经明确授权强制终止。
|
||
- Force stop：使用实例 Job Object 或已校验进程树，不按名称全局终止。
|
||
- Restart：旧实例退出或完成超时处理后重新执行同一配置。
|
||
- App shutdown：取消监控，不默认终止用户浏览器。
|
||
- Refresh：以 UI 传入的保存实例快照为范围，在后台读取 Chub registry、对应 profile 占用证据与已知 loopback CDP 端点，返回状态 DTO。刷新不按浏览器进程名或端口范围枚举；结果以实例 ID 与快照版本关联，UI 丢弃已删除或已编辑行的过期结果。
|
||
- Edit：UI 只提交可持久化的实例配置 DTO；运行时 PID、关联端口、占用来源和状态由刷新/启动结果返回，不作为编辑表单保存字段。编辑时保留未公开的非敏感启动选项，活跃或外部关联实例的身份约束字段保持只读。
|
||
- Proxy：本地配置保存稳定 `proxy_id` 指向的代理库项（必填、大小写无关唯一的显示名称与无认证端点）；启动 adapter 在后台解析为当前 `LaunchSpec.ProxyServer` 快照。名称与地址同次校验/保存，`proxy_id` 不因改名或改地址而改变；代理不能含 userinfo，删除被引用项会被拒绝；修改代理只影响后续启动，不影响已运行实例。Gio 列表按当前 `proxy_id` 实时解析名称，不把可变显示名反规范化写入实例配置。
|
||
- New instance default directory：`cmd/chub` 在窗口初始化时通过 platform config 解析实际 `os.Executable()` 的目录，并把 `<exe-dir>\\user_data_dirs\\<stable-instance-id>` 作为 Gio 新建表单的默认值；UI 只使用已提供的字符串，不读取文件或检查权限。实例 ID 必须先于默认目录分配，目录在保存/启动路径中按既有绝对路径与权限规则校验。不能使用当前工作目录，也不能将 `user_data_dirs` 根目录直接分给多个实例。
|
||
- GUI stop：主操作只对 Chub registry 中可验证的托管实例调用 `StopProfile(userDataDir, false)`，随后有限等待 registry 释放。外部关联、占用和未知实例永远不调用停止接口；超时或失败不自动强制关闭。
|
||
- 受管退出监控：仅为当前会话由 Chub 启动并获得进程句柄的实例建立一个 `Wait` 监控任务。退出事件携带实例 ID、启动代次和 PID，UI 仅在三者仍匹配且当前未处于 Chub 请求的停止中时，将运行时状态改为“已退出”并排队显示提示；过期事件、外部实例和应用退出后的监控取消均不得生成意外退出提示。
|
||
- CDP 页面目标查看：UI 仅将当前已保存实例快照交给后台 adapter；adapter 只接受“运行中”或“外部已关联”的有效实际端口，先复核对应 browser kind 的 loopback `/json/version`，再读取同一端口的 `/json/list`。结果 DTO 仅含 target ID、标题、类型和脱敏 URL；UI 以实例 ID、端口和请求代次丢弃过期结果。该链路不建立 WebSocket、不开启页面控制，也不提供物理窗口 ID。
|
||
- 通知区域：Windows platform adapter 在独立原生消息循环中管理一个图标、Tooltip 和原生菜单，向 `cmd/chub` 发送仅含“显示主窗口 / 刷新状态 / 退出应用”的 typed command。应用 coordinator 决定如何显示 Gio 窗口、发起既有刷新或执行退出清理；adapter 不持有浏览器进程句柄，不调用浏览器启动/停止接口。图标状态仅来自非敏感实例计数；Explorer 重启后重新注册，应用结束前删除图标。首版不拦截 Gio 的窗口关闭消息，也不隐藏主窗口。
|
||
- 配置定位与迁移：`config.OpenDefault()` 先用 `os.Executable()` 的目录解析目标 `config.json`，不依赖工作目录。目标文件已存在时直接使用它；目标不存在时仅尝试读取旧 `%APPDATA%\\chub\\config.json`，通过现有 decode/normalize 校验后以 Store 原子写入目标，并把旧文件保留为只读恢复备份。迁移失败不会写入目标、不会删除旧文件、不会回退到 AppData 继续运行；应用层只显示可恢复的启动诊断，不显示配置内容。CLI 与 GUI 共用该入口，避免出现不同配置来源。
|
||
- 浏览器可执行文件选择：`internal/platform/files.ExecutablePicker` 仅负责通过 Windows 原生 `OpenFileDialog` 返回已存在的绝对 `.exe` 路径；Gio shell 通过后台 adapter 调用并以字段和请求代次接收结果，不在 UI frame 中打开对话框或执行系统 I/O。Chrome 与 Edge 各自保存选择中状态和字段级反馈；取消、失败和不合规结果不改写 editor。标准路径搜索沿用独立可取消任务，但成功结果（包括与当前输入相同的确认结果）必须显示在发起字段旁，避免被页面下方的无关状态区遮蔽。
|
||
- Delete instance data：实例删除默认只移除本地配置。用户在确认弹层显式勾选后，Gio shell 以实例 ID、目录快照和请求代次向后台 `InstanceDataDeleter` 发起不可取消的数据删除；执行期间弹层保留并禁用重复/取消操作。`cmd/chub` adapter 在 `RemoveAll` 前重新检查 Chub registry 和 Windows 外部 profile 占用，任一检查失败或发现占用均拒绝；`internal/platform/files.InstanceDataRemover` 只接受绝对、清理后的非卷根目录，并拒绝普通文件、符号链接或重解析点。删除成功后 shell 才删除实例行并持久化配置；任何检查或文件删除失败都保留实例行、配置和目录。该路径不枚举、关闭或接管浏览器进程。
|
||
|
||
Chrome 和 Edge 共用大部分 Chromium 参数，但 executable 默认路径、进程名称和安装方式不同，通过 `BrowserDefinition` 封装差异。CDP 端点只绑定 `127.0.0.1`；端口号和 `/json/version` 是诊断数据，WebSocket URL 不进入持久化、事件或普通 UI 文案。`/json/list` 仅用于只读页面目标信息；URL 在 DTO 边界移除 userinfo、query 和 fragment。
|
||
|
||
## 风险
|
||
|
||
Chromium 可能复用已有进程；浏览器是多进程架构；管理员权限进程可能无法查询；强制终止可能损坏 profile；CDP 端口开放到非 loopback 会形成控制风险，MVP 默认关闭。
|