118 lines
3.8 KiB
Markdown
118 lines
3.8 KiB
Markdown
# reg 调用流程说明
|
||
|
||
## 概述
|
||
|
||
`reg` 接口（`POST /api/sandbox/config/reg`）用于同步本地配置到后端，并获取最新的服务器配置（`serverHost`/`serverPort`）。**所有启动服务的场景都必须先调用 reg，返回后再启动服务**，确保 lanproxy 使用最新的代理服务器地址。
|
||
|
||
---
|
||
|
||
## 统一流程
|
||
|
||
```
|
||
reg 调用 → mcpProxy → agent → fileServer → lanproxy
|
||
```
|
||
|
||
**核心原则**：reg 必须在 lanproxy 启动之前完成，因为 lanproxy 依赖 reg 返回的 `serverHost`/`serverPort`。
|
||
|
||
---
|
||
|
||
## 各场景流程
|
||
|
||
| 场景 | 触发位置 | 流程 |
|
||
|------|----------|------|
|
||
| **登录** | `ClientPage.handleLogin` | `loginAndRegister` → **reg** → mcpProxy → agent → fileServer → lanproxy |
|
||
| **启动全部** | `ClientPage.handleStartAll` | **reg** → mcpProxy → agent → fileServer → lanproxy |
|
||
| **手动启动单个** | `ClientPage.handleStartServiceManual` | 直接启动指定服务（不调用 reg） |
|
||
| **自动重连** | `App.tsx autoReconnect` | **reg** → mcpProxy → agent → fileServer → lanproxy |
|
||
| **退出登录** | `ClientPage.handleLogout` | 不调用 reg，停止所有服务 |
|
||
|
||
**说明**：手动启动单个服务时不调用 reg，因为用户通常在已登录状态下操作，配置已是最新。
|
||
|
||
---
|
||
|
||
## 代码位置
|
||
|
||
| 场景 | 文件 | 函数 |
|
||
|------|------|------|
|
||
| 登录 | `src/renderer/components/pages/ClientPage.tsx` | `handleLogin` |
|
||
| 启动全部 | `src/renderer/components/pages/ClientPage.tsx` | `handleStartAll` |
|
||
| 手动启动单个 | `src/renderer/components/pages/ClientPage.tsx` | `handleStartServiceManual` |
|
||
| 自动重连 | `src/renderer/App.tsx` | `autoReconnect` (useEffect) |
|
||
| reg 实现 | `src/renderer/services/core/auth.ts` | `syncConfigToServer` |
|
||
| 服务启动 | `src/renderer/components/pages/ClientPage.tsx` | `handleStartService` |
|
||
|
||
---
|
||
|
||
## reg 接口参数
|
||
|
||
```typescript
|
||
interface ClientRegisterParams {
|
||
username: string;
|
||
password: string; // 手动登录时传入，自动认证时为空字符串
|
||
savedKey?: string; // 持久化密钥，跨会话有效（用于自动认证）
|
||
deviceId?: string;
|
||
sandboxConfigValue: {
|
||
hostWithScheme: string;
|
||
agentPort: number; // 从 step1_config 读取
|
||
vncPort: number;
|
||
fileServerPort: number; // 从 step1_config 读取
|
||
apiKey?: string;
|
||
maxUsers?: number;
|
||
};
|
||
}
|
||
```
|
||
|
||
**注意**：密码不持久化保存。首次登录后，后续自动认证仅依赖 `savedKey`。
|
||
|
||
## reg 接口返回
|
||
|
||
```typescript
|
||
interface ClientRegisterResponse {
|
||
id: number;
|
||
configKey: string;
|
||
serverHost?: string; // lanproxy 连接地址
|
||
serverPort?: number; // lanproxy 连接端口
|
||
online: boolean;
|
||
name: string;
|
||
token?: string; // webview cookie 同步用
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 状态管理
|
||
|
||
### Loading 状态
|
||
|
||
- **不使用全局 loading**（已移除 `regSyncing` 状态和 "正在同步配置..." overlay）
|
||
- 使用服务项局部 loading（`startingServices` Set），覆盖 reg + 启动整个流程
|
||
|
||
### 防止重复启动
|
||
|
||
- 登录流程调用 `onLoginStarted()` 设置内存变量 `loginStartedRef.current = true`
|
||
- App.tsx 自动重连检查该内存变量，若为 true 则跳过（同一会话内有效，不持久化）
|
||
|
||
---
|
||
|
||
## 失败处理
|
||
|
||
| 场景 | reg 失败时行为 |
|
||
|------|---------------|
|
||
| 登录 | 继续启动服务（使用本地已保存配置） |
|
||
| 启动全部 | 继续启动服务（使用本地已保存配置） |
|
||
| 手动启动单个 | 不调用 reg，直接启动 |
|
||
| 自动重连 | 显示 notification，使用本地配置尝试启动 |
|
||
|
||
**设计原则**：reg 失败不应阻止服务启动，允许用户在离线环境下使用。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [review-reg-and-autoreconnect.md](./review-reg-and-autoreconnect.md) - 历史代码审查记录
|
||
|
||
---
|
||
|
||
*最后更新：2026-03-19*
|