Initial commit

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 10:10:11 +08:00
commit 14289beb66
45 changed files with 15479 additions and 0 deletions
--- a/docs/13-部署与测试.md
+++ b/docs/13-部署与测试.md
@@ -0,0 +1,788 @@
+# 模块13：部署与测试
+
+---
+
+## 🎨 UI设计系统概览
+
+> **完整设计系统文档请参考：** `UI设计系统.md`
+
+### 核心设计原则
+- **现代简约**：界面清晰，层次分明
+- **专业高效**：减少操作步骤，提升工作效率
+- **一致性**：统一的视觉语言和交互模式
+- **可访问性**：符合WCAG 2.1 AA标准
+
+### 关键设计令牌
+
+**颜色系统：**
+- 主色：`#0d6efd`（操作按钮、选中状态）
+- 成功：`#198754`（连接成功状态）
+- 危险：`#dc3545`（删除操作、错误提示）
+- 深灰：`#212529`（导航栏背景）
+- 浅灰：`#e9ecef`（工具栏背景）
+
+**字体系统：**
+- 字体族：系统字体栈（-apple-system, Segoe UI, Roboto等）
+- 正文：14px，行高1.5
+- 标题：20-32px，行高1.2-1.4
+- 小号文字：12px（文件大小、日期等）
+
+**间距系统：**
+- 基础单位：8px
+- 标准间距：16px（1rem）
+- 组件内边距：8px-16px
+
+**组件规范：**
+- 导航栏：高度48px，深色背景
+- 工具栏：浅灰背景，按钮间距8px
+- 文件项：最小高度44px，悬停效果150ms
+- 按钮：圆角4px，过渡150ms
+
+**交互规范：**
+- 悬停效果：150ms过渡
+- 触摸目标：最小44x44px
+- 键盘导航：Tab、Enter、Delete、F2、F5、Esc
+- 焦点状态：2px蓝色轮廓
+
+**响应式断点：**
+- 移动端：< 768px（双面板垂直排列）
+- 平板：768px - 1024px
+- 桌面：> 1024px（标准布局）
+
+---
+
+## 13.1 部署说明
+
+### 13.1.1 本地运行
+
+**环境要求：**
+- JDK 8或更高版本
+- Maven 3.6+
+- 8080端口未被占用
+
+**启动步骤：**
+
+1. **克隆或下载项目**
+   ```bash
+   cd sftp-manager
+   ```
+
+2. **编译项目**
+   ```bash
+   mvn clean install
+   ```
+
+3. **运行项目**
+   ```bash
+   mvn spring-boot:run
+   ```
+
+4. **访问应用**
+   ```
+   http://localhost:8080/sftp-manager
+   ```
+
+5. **访问H2控制台（可选）**
+   ```
+   http://localhost:8080/sftp-manager/h2-console
+   JDBC URL: jdbc:h2:file:./data/sftp-manager
+   用户名: sa
+   密码: (留空)
+   ```
+
+### 13.1.2 打包部署
+
+**打包命令：**
+```bash
+mvn clean package
+```
+
+打包完成后，在 `target` 目录下会生成 `sftp-manager-1.0.0.jar`
+
+**运行JAR包：**
+```bash
+java -jar target/sftp-manager-1.0.0.jar
+```
+
+**自定义端口：**
+```bash
+java -jar target/sftp-manager-1.0.0.jar --server.port=8081
+```
+
+**后台运行（Linux）：**
+```bash
+nohup java -jar target/sftp-manager-1.0.0.jar > app.log 2>&1 &
+```
+
+**Windows服务部署（可选）：**
+
+使用 [WinSW](https://github.com/winsw/winsw) 将JAR包注册为Windows服务。
+
+1. 下载WinSW.exe，重命名为 `sftp-manager.exe`
+2. 创建配置文件 `sftp-manager.xml`：
+   ```xml
+   <service>
+     <id>sftp-manager</id>
+     <name>SFTP Manager</name>
+     <description>SFTP文件管理系统</description>
+     <executable>java</executable>
+     <arguments>-jar "C:\path\to\sftp-manager-1.0.0.jar"</arguments>
+     <logpath>C:\logs\sftp-manager</logpath>
+   </service>
+   ```
+3. 安装服务：
+   ```bash
+   sftp-manager.exe install
+   sftp-manager.exe start
+   ```
+
+### 13.1.3 Docker部署
+
+**Dockerfile：**
+```dockerfile
+FROM openjdk:8-jdk-alpine
+
+VOLUME /tmp
+ARG JAR_FILE=target/sftp-manager-1.0.0.jar
+
+COPY ${JAR_FILE} app.jar
+
+ENTRYPOINT ["java","-jar","/app.jar"]
+```
+
+**构建镜像：**
+```bash
+docker build -t sftp-manager:1.0.0 .
+```
+
+**运行容器：**
+```bash
+docker run -d -p 8080:8080 --name sftp-manager sftp-manager:1.0.0
+```
+
+**Docker Compose（推荐）：**
+
+```yaml
+version: '3'
+services:
+  sftp-manager:
+    build: .
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./data:/app/data
+      - ./logs:/app/logs
+    environment:
+      - SPRING_PROFILES_ACTIVE=prod
+    restart: always
+```
+
+启动：
+```bash
+docker-compose up -d
+```
+
+### 13.1.4 生产环境配置
+
+**外部配置文件（application-prod.yml）：**
+
+```yaml
+server:
+  port: 80
+  tomcat:
+    max-threads: 200
+    accept-count: 100
+
+spring:
+  datasource:
+    url: jdbc:h2:file:/var/data/sftp-manager
+    username: ${DB_USERNAME:sa}
+    password: ${DB_PASSWORD:}
+    hikari:
+      maximum-pool-size: 10
+      minimum-idle: 5
+
+  jpa:
+    hibernate:
+      ddl-auto: update
+    show-sql: false
+
+  servlet:
+    multipart:
+      max-file-size: 500MB
+      max-request-size: 2GB
+
+app:
+  sftp:
+    session-timeout: 60000
+    connection-timeout: 30000
+    max-retries: 5
+
+logging:
+  file:
+    name: /var/log/sftp-manager/app.log
+  level:
+    root: INFO
+    com.sftp.manager: INFO
+```
+
+**启动命令：**
+```bash
+java -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=prod
+```
+
+**环境变量配置：**
+
+```bash
+export DB_USERNAME=admin
+export DB_PASSWORD=secret
+export SERVER_PORT=80
+java -jar target/sftp-manager-1.0.0.jar
+```
+
+## 13.2 测试指南
+
+### 13.2.1 功能测试清单
+
+#### 连接管理测试
+
+- [ ] 建立SFTP连接（密码认证）
+- [ ] 建立SFTP连接（密钥认证）
+- [ ] 断开连接
+- [ ] 保存连接配置
+- [ ] 加载保存的连接
+- [ ] 删除连接配置
+- [ ] 同时连接多个SFTP服务器
+
+**测试步骤：**
+
+1. **测试密码认证**
+   - 点击"连接管理"
+   - 点击"添加连接"
+   - 输入连接信息（主机、端口、用户名、密码）
+   - 点击"保存"
+   - 在列表中点击"连接"
+   - 验证是否连接成功
+
+2. **测试密钥认证**
+   - 准备SSH私钥文件
+   - 创建连接，填写私钥路径和私钥密码
+   - 测试连接
+
+3. **测试多连接**
+   - 创建多个连接配置
+   - 分别连接到不同的SFTP服务器
+   - 验证同时连接多个服务器
+
+#### 文件浏览测试
+
+- [ ] 浏览本地文件系统
+- [ ] 浏览SFTP服务器文件
+- [ ] 进入子目录
+- [ ] 返回上级目录
+- [ ] 直接输入路径跳转
+- [ ] 刷新文件列表
+
+**测试步骤：**
+
+1. **测试本地文件浏览**
+   - 切换到"本地文件"模式
+   - 浏览不同目录
+   - 进入子目录
+   - 点击"↑"返回上级目录
+
+2. **测试SFTP文件浏览**
+   - 切换到"SFTP服务器"模式
+   - 连接到SFTP服务器
+   - 浏览远程文件
+   - 验证文件信息显示正确
+
+#### 文件操作测试
+
+- [ ] 上传单个文件到SFTP
+- [ ] 批量上传文件
+- [ ] 从SFTP下载文件
+- [ ] 删除本地文件
+- [ ] 删除SFTP文件
+- [ ] 删除目录（递归）
+- [ ] 批量删除
+- [ ] 重命名文件
+- [ ] 重命名目录
+- [ ] 新建文件夹
+
+**测试步骤：**
+
+1. **测试上传**
+   - 在左面板选择本地文件
+   - 在右面板连接SFTP服务器
+   - 选择文件，点击"传输到右侧"
+   - 验证文件上传成功
+   - 测试大文件上传
+
+2. **测试下载**
+   - 在左面板连接SFTP服务器
+   - 在右面板选择本地目录
+   - 选择文件，点击"传输到右侧"
+   - 验证文件下载成功
+
+3. **测试删除**
+   - 选择单个文件，点击"删除"
+   - 确认删除
+   - 验证文件已删除
+   - 测试批量删除
+   - 测试目录删除
+
+4. **测试重命名**
+   - 选择文件，点击"重命名"
+   - 输入新文件名
+   - 验证重命名成功
+   - 测试非法文件名
+
+5. **测试新建文件夹**
+   - 点击"新建文件夹"
+   - 输入文件夹名称
+   - 验证文件夹创建成功
+   - 测试非法文件夹名
+
+#### 跨面板操作测试
+
+- [ ] 本地 → SFTP传输
+- [ ] SFTP → 本地传输
+- [ ] SFTP → SFTP传输
+- [ ] 本地 → 本地传输
+- [ ] 拖拽传输
+
+**测试步骤：**
+
+1. **测试本地到SFTP传输**
+   - 左面板：本地文件
+   - 右面板：SFTP服务器
+   - 左面板选择文件
+   - 点击"传输到右侧"
+   - 验证传输成功
+
+2. **测试SFTP到SFTP传输**
+   - 左面板：SFTP服务器A
+   - 右面板：SFTP服务器B
+   - 左面板选择文件
+   - 点击"传输到右侧"
+   - 验证文件传输成功
+
+3. **测试拖拽传输**
+   - 左面板选择文件
+   - 拖拽到右面板
+   - 验证传输成功
+
+#### 模式切换测试
+
+- [ ] 左面板本地/SFTP切换
+- [ ] 右面板本地/SFTP切换
+- [ ] 双SFTP模式
+- [ ] 双本地模式
+- [ ] 混合模式（左本地右SFTP、左SFTP右本地）
+
+**测试步骤：**
+
+1. **测试模式切换**
+   - 左面板切换到SFTP模式
+   - 验证连接选择器显示
+   - 连接到SFTP服务器
+   - 切换回本地模式
+   - 验证连接选择器隐藏
+
+2. **测试混合模式**
+   - 左面板：本地
+   - 右面板：SFTP
+   - 测试文件传输
+   - 切换模式
+   - 左面板：SFTP
+   - 右面板：本地
+   - 测试文件传输
+
+### 13.2.2 边界条件测试
+
+#### 大文件测试
+
+- [ ] 上传大于100MB的文件
+- [ ] 下载大于100MB的文件
+- [ ] 断点续传测试
+
+**测试步骤：**
+
+1. 创建一个500MB的测试文件
+2. 上传到SFTP服务器
+3. 验证上传进度显示
+4. 验证文件完整性（MD5校验）
+
+#### 特殊文件名测试
+
+- [ ] 中文文件名
+- [ ] 空格文件名
+- [ ] 特殊字符文件名
+- [ ] 超长文件名
+
+**测试步骤：**
+
+1. 创建以下测试文件：
+   - `测试文件.txt`
+   - `test file.txt`
+   - `test@file.txt`
+   - `test.file.name.txt`
+   - `a` (256字符).txt
+
+2. 测试上传、重命名、删除操作
+
+#### 权限测试
+
+- [ ] 无权限文件操作
+- [ ] 只读文件上传
+- [ ] 受保护目录访问
+
+**测试步骤：**
+
+1. 创建只读文件
+2. 尝试修改文件
+3. 验证错误提示
+
+#### 异常情况测试
+
+- [ ] 网络中断
+- [ ] 服务器断开
+- [ ] 连接超时
+- [ ] 磁盘空间不足
+
+**测试步骤：**
+
+1. 在传输过程中断开网络
+2. 验证错误提示
+3. 恢复网络连接
+4. 验证是否可以重新连接
+
+### 13.2.3 性能测试
+
+#### 测试指标
+
+- 文件上传/下载速度
+- 目录列表加载时间
+- 同时操作多个连接的响应时间
+- 内存占用
+
+#### 测试工具
+
+**Apache JMeter：**
+
+1. 创建测试计划
+2. 添加HTTP请求采样器
+3. 配置并发用户数
+4. 运行测试
+5. 查看结果
+
+**Postman：**
+
+1. 创建Collection
+2. 添加请求
+3. 配置环境变量
+4. 运行测试
+5. 查看结果
+
+**性能测试示例：**
+
+```bash
+# 使用ab工具测试并发性能
+ab -n 1000 -c 100 http://localhost:8080/sftp-manager/api/connection/list
+```
+
+### 13.2.4 安全测试
+
+#### SQL注入测试
+
+```bash
+# 测试参数注入
+curl -X POST http://localhost:8080/sftp-manager/api/files/list \
+  -H "Content-Type: application/json" \
+  -d '{"sessionId":"local","path":"C:/test'; DROP TABLE connections;--"}'
+```
+
+#### XSS测试
+
+```bash
+# 测试XSS攻击
+curl -X POST http://localhost:8080/sftp-manager/api/connection/save \
+  -H "Content-Type: application/json" \
+  -d '{"name":"<script>alert(1)</script>","host":"test","port":22,"username":"test"}'
+```
+
+#### 路径遍历测试
+
+```bash
+# 测试路径遍历
+curl -X POST http://localhost:8080/sftp-manager/api/files/list \
+  -H "Content-Type: application/json" \
+  -d '{"sessionId":"local","path":"../../../etc/passwd"}'
+```
+
+## 13.3 常见问题排查
+
+### 13.3.1 问题排查清单
+
+| 问题 | 可能原因 | 解决方案 |
+|------|---------|---------|
+| 无法连接SFTP服务器 | 网络问题、服务器地址错误 | 检查网络、验证服务器地址和端口 |
+| 文件上传失败 | 权限不足、磁盘空间不足 | 检查权限、清理磁盘空间 |
+| 文件列表加载慢 | 网络延迟、文件数量多 | 增加超时时间、实现分页 |
+| 连接频繁断开 | 防火墙设置、超时设置 | 调整防火墙、增加超时时间 |
+| 内存占用过高 | 大文件操作、连接过多 | 增加JVM内存、限制并发数 |
+
+### 13.3.2 日志分析
+
+**查看应用日志：**
+```bash
+tail -f logs/sftp-manager.log
+```
+
+**查看错误日志：**
+```bash
+tail -f logs/sftp-manager-error.log
+```
+
+**搜索特定错误：**
+```bash
+grep "ERROR" logs/sftp-manager.log
+```
+
+### 13.3.3 性能优化
+
+**JVM参数优化：**
+```bash
+java -Xms512m -Xmx2g -XX:+UseG1GC -jar sftp-manager-1.0.0.jar
+```
+
+**数据库优化：**
+```yaml
+spring:
+  datasource:
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 10
+      connection-timeout: 30000
+      idle-timeout: 600000
+      max-lifetime: 1800000
+```
+
+**文件上传优化：**
+```yaml
+spring:
+  servlet:
+    multipart:
+      max-file-size: 500MB
+      max-request-size: 2GB
+      file-size-threshold: 10MB
+```
+
+## 13.4 监控与维护
+
+### 13.4.1 应用监控
+
+**Actuator集成：**
+
+添加依赖：
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-actuator</artifactId>
+</dependency>
+```
+
+配置：
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: always
+```
+
+访问端点：
+- 健康检查：http://localhost:8080/sftp-manager/actuator/health
+- 应用信息：http://localhost:8080/sftp-manager/actuator/info
+- 性能指标：http://localhost:8080/sftp-manager/actuator/metrics
+
+### 13.4.2 定期维护任务
+
+**日志清理：**
+```bash
+# 清理30天前的日志
+find logs/ -name "*.log" -mtime +30 -delete
+```
+
+**数据库备份：**
+```bash
+# 备份H2数据库
+cp data/sftp-manager.mv.db backup/sftp-manager-$(date +%Y%m%d).mv.db
+```
+
+**临时文件清理：**
+```bash
+# 清理临时文件
+find /tmp -name "sftp-manager-*" -mtime +1 -delete
+```
+
+### 13.4.3 自动化部署脚本
+
+**部署脚本（deploy.sh）：**
+```bash
+#!/bin/bash
+
+APP_NAME="sftp-manager"
+JAR_FILE="${APP_NAME}-1.0.0.jar"
+PID_FILE="${APP_NAME}.pid"
+LOG_FILE="${APP_NAME}.log"
+
+# 停止服务
+stop() {
+    if [ -f $PID_FILE ]; then
+        PID=$(cat $PID_FILE)
+        kill $PID
+        rm $PID_FILE
+        echo "服务已停止"
+    fi
+}
+
+# 启动服务
+start() {
+    nohup java -jar $JAR_FILE --spring.profiles.active=prod > $LOG_FILE 2>&1 &
+    echo $! > $PID_FILE
+    echo "服务已启动"
+}
+
+# 重启服务
+restart() {
+    stop
+    sleep 2
+    start
+}
+
+case "$1" in
+    start)
+        start
+        ;;
+    stop)
+        stop
+        ;;
+    restart)
+        restart
+        ;;
+    *)
+        echo "Usage: $0 {start|stop|restart}"
+        exit 1
+esac
+
+exit 0
+```
+
+**使用方法：**
+```bash
+chmod +x deploy.sh
+./deploy.sh start
+./deploy.sh stop
+./deploy.sh restart
+```
+
+## 实施步骤
+
+1. **本地测试**：在本地环境完成所有功能测试
+
+2. **打包部署**：打包应用并部署到测试环境
+
+3. **集成测试**：在测试环境进行完整的集成测试
+
+4. **性能测试**：使用测试工具进行性能测试
+
+5. **安全测试**：进行安全漏洞扫描
+
+6. **生产部署**：部署到生产环境
+
+7. **监控配置**：配置监控和告警
+
+## 注意事项
+
+1. **备份**：部署前做好数据备份
+2. **回滚**：准备回滚方案
+3. **监控**：部署后密切监控
+4. **文档**：及时更新部署文档
+5. **测试**：充分测试后再部署
+
+## 附录
+
+### A. 环境变量参考
+
+| 环境变量 | 说明 | 默认值 |
+|---------|------|--------|
+| SERVER_PORT | 服务端口 | 8080 |
+| DB_USERNAME | 数据库用户名 | sa |
+| DB_PASSWORD | 数据库密码 | 空 |
+| SPRING_PROFILES_ACTIVE | 激活的配置文件 | dev |
+| LOG_LEVEL | 日志级别 | INFO |
+
+### B. 端口占用检查
+
+```bash
+# Linux/Mac
+lsof -i :8080
+
+# Windows
+netstat -ano | findstr :8080
+```
+
+### C. 常用命令
+
+```bash
+# 查看进程
+ps aux | grep sftp-manager
+
+# 杀死进程
+kill -9 <PID>
+
+# 查看日志
+tail -f logs/sftp-manager.log
+
+# 查看端口
+netstat -tlnp | grep 8080
+```
+
+---
+
+## 项目完成清单
+
+### 核心功能
+- [x] 项目初始化与基础配置
+- [x] 数据模型设计
+- [x] 连接管理功能
+- [x] 文件浏览功能
+- [x] 文件上传下载功能
+- [x] 文件删除功能
+- [x] 文件重命名功能
+- [x] 新建文件夹功能
+- [x] 双面板UI界面设计
+- [x] 模式切换功能
+- [x] API接口设计规范
+- [x] 错误处理与日志
+- [x] 部署与测试
+
+### 技术实现
+- [x] Spring Boot后端
+- [x] JSch SFTP客户端
+- [x] H2嵌入式数据库
+- [x] Bootstrap 5前端
+- [x] jQuery JavaScript库
+- [x] RESTful API
+- [x] 全局异常处理
+- [x] 操作日志记录
+- [x] Docker支持
+
+---
+
+**恭喜！SFTP文件管理系统开发完成！**