206 lines
7.3 KiB
Markdown
206 lines
7.3 KiB
Markdown
# AGENTS 指南（ssh-manager）
|
||
|
||
本文件面向在本仓库工作的自动化 coding agents。
|
||
目标：快速、安全、风格一致地完成改动。
|
||
|
||
## 1) 仓库概览
|
||
|
||
- Monorepo：`backend`（Spring Boot 2.7 + Java 8）+ `frontend`（Vue 3 + TS + Vite）
|
||
- 默认后端端口：`48080`（见 `backend/src/main/resources/application.yml`）
|
||
- 前端开发端口：`5173`，通过 Vite 代理 `/api` 和 `/ws`
|
||
- 数据库：H2 文件库（`./data/sshmanager`）
|
||
- 认证：JWT（HTTP Header Bearer + WebSocket query token）
|
||
|
||
## 2) 环境与依赖
|
||
|
||
- JDK：8+
|
||
- Maven：3.6+
|
||
- Node.js：18+
|
||
- npm：与 `frontend/package-lock.json` 配套
|
||
|
||
## 3) 常用命令（构建 / 检查 / 测试）
|
||
|
||
### 3.1 后端（在 `backend/` 目录）
|
||
|
||
- 启动开发服务：`mvn spring-boot:run`
|
||
- 打包：`mvn package`
|
||
- 仅运行测试：`mvn test`
|
||
- 跳过测试打包：`mvn -DskipTests package`
|
||
- 运行单个测试类：`mvn -Dtest=ConnectionServiceTest test`
|
||
- 运行单个测试方法：`mvn -Dtest=ConnectionServiceTest#shouldCreateConnection test`
|
||
|
||
说明：
|
||
- 当前仓库可能暂无 `src/test` 用例；上述命令是 Maven 标准入口。
|
||
- 新增测试时优先使用 Surefire 默认命名约定（`*Test`、`*Tests`）。
|
||
|
||
### 3.2 前端（在 `frontend/` 目录）
|
||
|
||
- 安装依赖：`npm install`
|
||
- 启动开发服务：`npm run dev`
|
||
- 生产构建：`npm run build`
|
||
- 本地预览构建产物：`npm run preview`
|
||
|
||
说明：
|
||
- 当前 `package.json` 未配置独立 lint/test script。
|
||
- `npm run build` 会先执行 `vue-tsc -b`，可视为类型检查关卡。
|
||
|
||
### 3.3 Docker（在仓库根目录）
|
||
|
||
- 构建镜像：`docker compose -f docker/docker-compose.yml build`
|
||
- 前台运行：`docker compose -f docker/docker-compose.yml up`
|
||
- 后台运行：`docker compose -f docker/docker-compose.yml up -d`
|
||
|
||
## 4) 单测执行策略（重点）
|
||
|
||
- 后端单测首选：`mvn -Dtest=类名#方法名 test`
|
||
- 多方法可用逗号：`mvn -Dtest=ClassTest#testA,testB test`
|
||
- 若测试依赖 Spring 上下文，优先在类级隔离，避免全量启动过慢
|
||
- 修改 Service/Controller 后，至少补一条对应单元或集成测试（若仓库开始建设测试）
|
||
- 前端若后续引入 Vitest，建议约定：
|
||
- 全量：`npm run test`
|
||
- 单文件：`npm run test -- src/views/ConnectionsView.test.ts`
|
||
- 单用例：`npm run test -- -t "case name"`
|
||
|
||
## 5) 代码风格总则
|
||
|
||
- 小步提交：改动聚焦，避免“顺手重构”无关文件
|
||
- 保持现有技术栈，不随意引入新框架/重依赖
|
||
- 默认不修改对外 API 语义；若必须修改，同步更新调用侧
|
||
- 安全优先：严禁提交真实密钥、密码、token、私钥
|
||
- 可观测性：失败路径要返回可诊断信息（但不能泄露敏感数据）
|
||
|
||
## 6) 后端风格（Java / Spring）
|
||
|
||
### 6.1 导入与结构
|
||
|
||
- 包名固定前缀：`com.sshmanager`
|
||
- import 分组遵循现有习惯：
|
||
- 先项目内 `com.sshmanager...`
|
||
- 再第三方/框架 `org...` / `javax...`
|
||
- 最后 `java...`
|
||
- 避免通配符 import（`*`）
|
||
|
||
### 6.2 格式与命名
|
||
|
||
- 4 空格缩进，左花括号同行
|
||
- 类名 `PascalCase`，方法/变量 `camelCase`
|
||
- Controller 以 `*Controller`，Service 以 `*Service`，Repository 以 `*Repository`
|
||
- DTO 放 `dto` 包，实体放 `entity` 包
|
||
- 常量使用 `UPPER_SNAKE_CASE`
|
||
|
||
### 6.3 类型与注解
|
||
|
||
- Java 8 语法兼容（不要引入更高版本语法特性）
|
||
- 优先构造器注入（本仓库已有统一做法）
|
||
- 合理使用 Lombok（当前主要在 Entity 使用）
|
||
- 对外接口返回 `ResponseEntity<...>` 保持一致
|
||
|
||
### 6.4 异常与错误处理
|
||
|
||
- 与现有代码一致：业务错误返回 JSON（`message` 或 `error` 字段）
|
||
- 鉴权失败返回 401；参数错误返回 400；服务异常返回 500
|
||
- 记录日志时避免输出明文凭据（password/privateKey/passphrase/token）
|
||
- SFTP 相关改动需考虑并发安全：`ChannelSftp` 非线程安全
|
||
|
||
### 6.5 安全相关
|
||
|
||
- JWT 校验逻辑位于过滤器与握手流程，改动需覆盖 HTTP + WS 场景
|
||
- 允许跨域来源在 `SecurityConfig` 中集中维护
|
||
- 加密逻辑统一走 `EncryptionService`，禁止绕过直接落库明文
|
||
|
||
## 7) 前端风格（Vue 3 / TS / Tailwind）
|
||
|
||
### 7.1 导入与模块组织
|
||
|
||
- 使用 `<script setup lang="ts">`
|
||
- import 优先级参考现有文件：
|
||
- Vue 核心库
|
||
- 路由 / store
|
||
- 本地 API / type / 组件
|
||
- 图标或其他第三方
|
||
- 相对路径保持简洁，避免无必要跨层引用
|
||
|
||
### 7.2 格式与命名
|
||
|
||
- 2 空格缩进
|
||
- TypeScript 与 Vue 脚本保持“无分号 + 单引号”风格
|
||
- 组件文件名 `PascalCase.vue`
|
||
- store 命名：`useXxxStore`
|
||
- 方法变量 `camelCase`，常量 `UPPER_SNAKE_CASE`
|
||
|
||
### 7.3 类型与状态
|
||
|
||
- API 类型定义集中在 `frontend/src/api/*.ts`
|
||
- 对可空值显式标注（如 `Connection | null`）
|
||
- Pinia store 负责状态与数据同步，视图层尽量避免重复请求逻辑
|
||
- 新增接口先补类型，再写调用
|
||
|
||
### 7.4 UI 与交互
|
||
|
||
- 延续 Tailwind 工具类写法，不引入额外 CSS 框架
|
||
- 保持现有深色主题语言（`slate/cyan`）与可访问性属性（如 `aria-label`）
|
||
- 交互失败要有可感知反馈（至少日志或错误提示）
|
||
- 注意终端/SFTP页面的响应性能，避免不必要重渲染
|
||
|
||
## 8) 提交前自检清单
|
||
|
||
- 后端改动：至少运行 `mvn test`（若存在测试）或最小可行编译验证
|
||
- 前端改动：运行 `npm run build`（包含 `vue-tsc`）
|
||
- 手工验证登录流程、连接列表、终端或 SFTP 关键路径（按改动范围）
|
||
- 检查未提交敏感信息与本地配置
|
||
- 仅提交与需求直接相关的文件
|
||
|
||
## 9) 文档与规则文件检查结果
|
||
|
||
- `AGENTS.md`：本文件为新建（仓库根目录）
|
||
- Cursor 规则：未发现 `.cursor/rules/` 或 `.cursorrules`
|
||
- Copilot 规则：未发现 `.github/copilot-instructions.md`
|
||
|
||
若未来新增上述规则文件，agents 必须先读取并将其视为高优先级约束。
|
||
|
||
## 10) 近期修复记录（2026-03-11）
|
||
|
||
### 10.1 Docker 启动失败修复
|
||
|
||
**问题现象**
|
||
```text
|
||
Could not resolve placeholder 'SSHMANAGER_JWT_SECRET'
|
||
Encryption key must be 32 bytes (256 bits)
|
||
No qualifying bean of type 'ExecutorService' available: expected single matching bean but found 2
|
||
```
|
||
|
||
**修复措施**
|
||
1. **`application.yml`** - 为安全配置添加空字符串默认值
|
||
```yaml
|
||
sshmanager:
|
||
encryption-key: ${SSHMANAGER_ENCRYPTION_KEY ""}
|
||
jwt-secret: ${SSHMANAGER_JWT_SECRET ""}
|
||
```
|
||
|
||
2. **`docker-compose.yml`** - 提供有效的默认密钥（仅用于开发/测试）
|
||
```yaml
|
||
environment:
|
||
- SSHMANAGER_JWT_SECRET=ssh-manager-prod-jwt-secret-20240311
|
||
- SSHMANAGER_ENCRYPTION_KEY=MLVt7pE35KULIppEiit0doUMvSjozZJ037oNGeXjhVA=
|
||
```
|
||
> 注：`MLVt7pE35KULIppEiit0doUMvSjozZJ037oNGeXjhVA=` 是通过 `openssl rand -base64 32` 生成的有效 32 字节 AES-256 密钥
|
||
|
||
3. **`TerminalWebSocketHandler.java`** - 解决依赖注入歧义
|
||
```java
|
||
import org.springframework.beans.factory.annotation.Qualifier;
|
||
|
||
public TerminalWebSocketHandler(
|
||
// ... 其他参数
|
||
@Qualifier("terminalWebSocketExecutor") ExecutorService executor) {
|
||
}
|
||
```
|
||
|
||
**验证结果**
|
||
```
|
||
Started SshManagerApplication in 3.469 seconds (JVM running for 3.836)
|
||
```
|
||
|
||
**注意事项**
|
||
- **生产环境部署时必须修改** `SSHMANAGER_JWT_SECRET` 和 `SSHMANAGER_ENCRYPTION_KEY`
|
||
- 建议取消 `docker-compose.yml` 中 `volumes` 注释以持久化 H2 数据库文件
|