Files

liumangmang 80fc5c8a0f feat: 增强 Transfers 页面文件浏览功能

- 在 SftpFilePickerModal 中添加搜索功能
- 添加显示/隐藏文件切换按钮（参考 SftpView）
- Remote->Many 模式下目标连接列表自动排除源连接
- 全选功能自动排除源连接
- 添加空状态提示信息
- 优化用户体验和交互逻辑

2026-03-12 17:45:07 +08:00

7.5 KiB

Raw Blame History

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) Makefile 快捷命令（仓库根目录）

make build：构建 Docker 镜像
make up：构建并后台启动服务
make down：停止并移除服务
make restart：重启服务
make logs：查看服务日志
make ps：查看服务状态

10) 文档与规则文件检查结果

AGENTS.md：本文件（仓库根目录）
Cursor 规则：未发现 .cursor/rules/ 或 .cursorrules
Copilot 规则：未发现 .github/copilot-instructions.md

若未来新增上述规则文件，agents 必须先读取并将其视为高优先级约束。

11) 近期修复记录

11.1 Docker 启动失败修复

问题现象

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

修复措施

application.yml - 为安全配置添加空字符串默认值

sshmanager:
  encryption-key: ${SSHMANAGER_ENCRYPTION_KEY ""}
  jwt-secret: ${SSHMANAGER_JWT_SECRET ""}

docker-compose.yml - 提供有效的默认密钥（仅用于开发/测试）
```
environment:
  - SSHMANAGER_JWT_SECRET=ssh-manager-prod-jwt-secret-20240311
  - SSHMANAGER_ENCRYPTION_KEY=MLVt7pE35KULIppEiit0doUMvSjozZJ037oNGeXjhVA=
```
注：MLVt7pE35KULIppEiit0doUMvSjozZJ037oNGeXjhVA= 是通过 openssl rand -base64 32 生成的有效 32 字节 AES-256 密钥

TerminalWebSocketHandler.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 数据库文件

7.5 KiB Raw Blame History Unescape Escape