✅【HelloAGENTS】- ~init：完成
已完成当前仓库知识库初始化，已创建 .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 规则，我只提示，不自动修改
This commit is contained in:
yinjianm
@@ -0,0 +1,29 @@
|
||||
# 模块索引
|
||||
|
||||
> 通过此文件快速定位模块文档
|
||||
|
||||
## 模块清单
|
||||
|
||||
| 模块 | 职责 | 状态 | 文档 |
|
||||
|------|------|------|------|
|
||||
| workspace-root | 管理 monorepo 工作区、共享依赖、补丁与部署编排 | ✅ | [workspace-root.md](./workspace-root.md) |
|
||||
| frontend | 提供终端工作区、设置页和连接管理等 Web 界面 | ✅ | [frontend.md](./frontend.md) |
|
||||
| backend | 提供认证、连接管理、SFTP、通知与 WebSocket 服务 | ✅ | [backend.md](./backend.md) |
|
||||
| remote-gateway | 生成远程桌面令牌并桥接 `guacd` | ✅ | [remote-gateway.md](./remote-gateway.md) |
|
||||
|
||||
## 模块依赖关系
|
||||
|
||||
```text
|
||||
workspace-root → frontend
|
||||
workspace-root → backend
|
||||
workspace-root → remote-gateway
|
||||
frontend → backend
|
||||
frontend → remote-gateway
|
||||
remote-gateway → guacd
|
||||
backend → data(volume)
|
||||
```
|
||||
|
||||
## 状态说明
|
||||
- ✅ 稳定
|
||||
- 🚧 开发中
|
||||
- 📝 规划中
|
||||
@@ -0,0 +1,47 @@
|
||||
# backend
|
||||
|
||||
## 职责
|
||||
|
||||
`packages/backend` 是主后端服务，基于 Express 5、SQLite 和 WebSocket 提供认证、连接管理、SFTP、SSH 挂起、通知、审计、快速命令、主题与外观设置等能力，并负责初始化数据库和共享会话。
|
||||
|
||||
## 接口定义（可选）
|
||||
|
||||
> 模块对外暴露的公共 API 和数据结构
|
||||
|
||||
### 公共 API
|
||||
| 函数/方法 | 参数 | 返回值 | 说明 |
|
||||
|----------|------|--------|------|
|
||||
| `GET /api/v1/status` | 无 | `{ status: string }` | 后端健康检查接口。 |
|
||||
| `/api/v1/auth` 等 REST 路由组 | HTTP 请求体与路径参数 | JSON | 提供认证、连接、SFTP、设置、通知、审计等业务接口。 |
|
||||
| `initializeWebSocket(server, sessionMiddleware)` | HTTP server, session middleware | WebSocket 服务实例 | 在现有 HTTP 服务上挂接 SSH/SFTP/RDP/Docker 等实时会话。 |
|
||||
|
||||
### 数据结构
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `session.userId` | `number` | 登录用户 ID，存入 `express-session`。 |
|
||||
| `session.username` | `string` | 当前登录用户名。 |
|
||||
| `data/.env` / 根 `.env` | 环境变量文件 | 保存部署模式、加密密钥、会话密钥等运行配置。 |
|
||||
|
||||
## 行为规范
|
||||
|
||||
### 启动初始化
|
||||
**条件**: 执行 `packages/backend` 的 `dev`、`build && start` 或容器启动流程。
|
||||
**行为**: 先读取根 `.env` 与 `data/.env`，缺失 `ENCRYPTION_KEY` 或 `SESSION_SECRET` 时自动生成并尝试写回，再初始化数据库。
|
||||
**结果**: 环境变量、数据库和会话存储准备完成后才开始监听 HTTP/WebSocket 服务。
|
||||
|
||||
### 路由与会话
|
||||
**条件**: 应用启动完成并收到前端请求。
|
||||
**行为**: 所有业务接口挂载在 `/api/v1/*` 下，`express-session` 通过文件存储共享登录状态，WebSocket 初始化时复用同一会话中间件。
|
||||
**结果**: REST 与实时会话使用一致的认证上下文。
|
||||
|
||||
### 业务分层
|
||||
**条件**: 维护业务域代码。
|
||||
**行为**: 按 `controller/service/repository/routes` 的分层模式组织连接、通知、设置、快速命令、主题等功能。
|
||||
**结果**: 新增后端能力时应优先延续现有业务域目录结构，而不是在入口文件堆叠逻辑。
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```yaml
|
||||
依赖: workspace-root, sqlite(data), express-session, ssh2, ws
|
||||
被依赖: frontend
|
||||
```
|
||||
@@ -0,0 +1,47 @@
|
||||
# frontend
|
||||
|
||||
## 职责
|
||||
|
||||
`packages/frontend` 是 Vue 3 + Vite 的 Web 客户端，负责登录、初始化设置、连接管理、工作区布局、终端与文件编辑、通知与审计视图，以及对后端 REST/WebSocket 和远程桌面网关的前端集成。
|
||||
|
||||
## 接口定义（可选）
|
||||
|
||||
> 模块对外暴露的公共 API 和数据结构
|
||||
|
||||
### 公共 API
|
||||
| 函数/方法 | 参数 | 返回值 | 说明 |
|
||||
|----------|------|--------|------|
|
||||
| `src/main.ts` 启动流程 | 无 | Vue 应用实例 | 启动时先检查 setup/auth 状态，再挂载路由和应用。 |
|
||||
| `src/router/index.ts` | 路由对象 | Vue Router 实例 | 管理 `/`、`/login`、`/workspace`、`/settings` 等页面与路由守卫。 |
|
||||
| `useWebSocketConnection()` 等 composable | 业务参数 | 响应式状态/方法 | 处理 SSH 会话、文件管理、设置页等前端交互逻辑。 |
|
||||
|
||||
### 数据结构
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `authStore` | Pinia store | 保存 `isAuthenticated`、`needsSetup` 等认证状态。 |
|
||||
| `session.store` | Pinia store | 管理工作区标签、终端、SFTP 与弹窗状态。 |
|
||||
| `connections.store` | Pinia store | 管理连接列表及其与后端的同步。 |
|
||||
|
||||
## 行为规范
|
||||
|
||||
### 应用启动
|
||||
**条件**: 浏览器加载前端入口。
|
||||
**行为**: `main.ts` 先并行拉取 setup 状态与认证状态；若用户已登录，再加载设置和外观数据；最后才注册路由并挂载应用。
|
||||
**结果**: 路由守卫在挂载前即可拿到最新认证状态，避免错误跳转。
|
||||
|
||||
### 路由访问控制
|
||||
**条件**: 用户访问任一路由。
|
||||
**行为**: `router.beforeEach` 根据 `needsSetup` 与 `isAuthenticated` 决定是否重定向到 `/setup`、`/login` 或首页。
|
||||
**结果**: 初始化设置和登录约束由统一路由守卫执行。
|
||||
|
||||
### 工作区交互
|
||||
**条件**: 用户进入 `/workspace` 或相关管理页面。
|
||||
**行为**: 通过组件、Pinia 与 composable 协同管理终端、文件管理、命令历史、布局配置、主题和状态监控。
|
||||
**结果**: 页面逻辑分散在 `views/`、`components/`、`stores/` 与 `composables/`，改动时应优先在对应层级定位。
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```yaml
|
||||
依赖: workspace-root, backend, remote-gateway, vue-router, pinia
|
||||
被依赖: 无
|
||||
```
|
||||
@@ -0,0 +1,47 @@
|
||||
# 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
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
# workspace-root
|
||||
|
||||
## 职责
|
||||
|
||||
管理仓库根目录的 npm workspaces、共享依赖、`patch-package` 补丁应用以及 Docker Compose 部署编排。该模块不是业务运行时服务，但决定了三个子包如何安装、构建和协同运行。
|
||||
|
||||
## 接口定义（可选）
|
||||
|
||||
> 模块对外暴露的公共 API 和数据结构
|
||||
|
||||
### 公共 API
|
||||
| 函数/方法 | 参数 | 返回值 | 说明 |
|
||||
|----------|------|--------|------|
|
||||
| `package.json#workspaces` | `packages/*` | npm workspace 列表 | 声明后端、前端、远程网关三个子包属于同一工作区。 |
|
||||
| `package.json#postinstall` | 无 | shell 命令 | 安装依赖后自动执行 `patch-package`。 |
|
||||
| `docker-compose.yml` | 环境变量、卷、端口映射 | 服务编排 | 统一启动 `frontend`、`backend`、`remote-gateway`、`guacd`。 |
|
||||
|
||||
### 数据结构
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `packages/*` | 目录集合 | Monorepo 子包入口。 |
|
||||
| `patches/` | 目录 | 第三方依赖补丁存放位置。 |
|
||||
| `data/` | 运行时卷目录 | Docker 部署时挂载到后端 `/app/data`。 |
|
||||
|
||||
## 行为规范
|
||||
|
||||
### 依赖安装
|
||||
**条件**: 在仓库根目录执行 `npm install`。
|
||||
**行为**: npm 解析 `workspaces`，统一安装根依赖与子包依赖，并在安装结束后运行 `patch-package`。
|
||||
**结果**: 三个子包共享锁文件与依赖树，补丁在安装阶段自动落地。
|
||||
|
||||
### 容器化部署
|
||||
**条件**: 使用根目录 `docker-compose.yml` 启动服务。
|
||||
**行为**: `frontend` 暴露 `18111:80`，`backend` 读取根 `.env` 并挂载 `./data:/app/data`，`remote-gateway` 依赖 `guacd` 和 `backend`。
|
||||
**结果**: Web 入口、REST API、远程桌面网关与 `guacd` 形成完整运行拓扑。
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```yaml
|
||||
依赖: frontend, backend, remote-gateway, docker-compose, .env
|
||||
被依赖: frontend, backend, remote-gateway
|
||||
```
|
||||
Reference in New Issue
Block a user