yinjianm
c7a73e3715
已完成当前仓库知识库初始化，已创建 .helloagents/ 目录骨架和首批文档，覆盖根工作区、前端、后端、远程桌面网关四个模块。 已生成入口与上下文文档：INDEX.md、context.md、CHANGELOG.md 已生成模块文档：workspace-root.md、frontend.md、backend.md、remote-gateway.md 已创建空目录：plan/、user/ 验收结果：核心文件存在且非空，目录结构完整，未残留模板级占位骨架 未执行项：configure_codex.py 因当前环境不可用 Python 解释器而跳过，这不影响本次知识库初始化 提示：当前 .gitignore 还没有 .helloagents/ 条目；按 ~init 规则，我只提示，不自动修改
48 lines
2.2 KiB
Markdown
48 lines
2.2 KiB
Markdown
# remote-gateway
|
||
|
||
## 职责
|
||
|
||
`packages/remote-gateway` 是独立的远程桌面网关服务，负责验证 RDP/VNC 连接参数、生成加密 token，并通过 `guacamole-lite` 与 `guacd` 协同提供远程桌面 WebSocket 能力。
|
||
|
||
## 接口定义（可选）
|
||
|
||
> 模块对外暴露的公共 API 和数据结构
|
||
|
||
### 公共 API
|
||
| 函数/方法 | 参数 | 返回值 | 说明 |
|
||
|----------|------|--------|------|
|
||
| `POST /api/remote-desktop/token` | `protocol`, `connectionConfig` | `{ token }` | 校验参数后生成加密远程桌面 token。 |
|
||
| `GuacamoleLite(websocketOptions, guacdOptions, clientOptions)` | 端口、guacd 配置、加密配置 | GuacamoleLite 实例 | 启动远程桌面 WebSocket 网关。 |
|
||
| `gracefulShutdown(signal)` | 进程信号 | 无 | 关闭 HTTP API 与 Guacamole 服务器。 |
|
||
|
||
### 数据结构
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `REMOTE_GATEWAY_API_PORT` | `string \| number` | HTTP API 监听端口，默认 `9090`。 |
|
||
| `REMOTE_GATEWAY_WS_PORT` | `string \| number` | Guacamole WebSocket 监听端口，默认 `8080`。 |
|
||
| `connectionConfig` | JSON 对象 | 包含 `hostname`、`port`、`username`、`password`、分辨率等桌面连接参数。 |
|
||
|
||
## 行为规范
|
||
|
||
### 网关启动
|
||
**条件**: 启动 `remote-gateway` 进程。
|
||
**行为**: 进程启动时生成仅驻留内存的 AES 密钥，构造允许来源列表，并初始化 `GuacamoleLite` 与 API 服务器。
|
||
**结果**: 每次进程重启都会使用新的内存密钥，旧 token 不应跨进程复用。
|
||
|
||
### Token 生成
|
||
**条件**: 客户端请求 `/api/remote-desktop/token`。
|
||
**行为**: 仅接受 `rdp` 或 `vnc`，按协议要求校验 `hostname`、`port`、账号口令等字段，再将连接配置加密为 base64 token。
|
||
**结果**: 前端拿到可交给远程桌面 WebSocket 使用的短期 token。
|
||
|
||
### 优雅退出
|
||
**条件**: 收到 `SIGINT`、`SIGTERM` 或 `SIGUSR2`。
|
||
**行为**: 先关闭 API server，再尝试关闭 Guacamole server，10 秒后仍未完成则强制退出。
|
||
**结果**: 开发环境重启和生产环境停机时尽量减少悬挂连接。
|
||
|
||
## 依赖关系
|
||
|
||
```yaml
|
||
依赖: workspace-root, guacd, guacamole-lite, cors
|
||
被依赖: frontend
|
||
```
|