sftp-manager/docs/13-部署与测试.md

# 模块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文件管理系统开发完成！**