# file-task-service

**Repository Path**: grow-project/file-task-service

## Basic Information

- **Project Name**: file-task-service
- **Description**: 文件任务管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件处理与异步任务平台

> Go 1.22 · MinIO · PostgreSQL · 自研 WorkerPool · SSE & WebSocket 双通道 · Prometheus + Grafana

## 功能特性

- **大文件上传**：分片上传、断点续传、秒传（SHA256 判定）、流式合并（零落盘）
- **异步任务引擎**：任务注册/提交/状态流转、指数退避重试、进度上报
- **自研 Worker Pool**：背压控制、动态扩缩容（5s 采样/80%扩/20%缩30s）、panic recover
- **SSE & WebSocket 双通道**：进度实时推送、心跳保活、SSE 断线续传（Last-Event-ID）、WebSocket cancel 控制帧
- **流式处理 Handler**：Excel 导入/导出、图片压缩、PDF 生成（恒定内存占用）
- **Prometheus 监控**：8 项核心指标 + Grafana 预置看板
- **优雅停机**：四阶段停机（HTTP→SSE/WS 通知→Pool 等待→资源释放）

## 技术栈

| 领域 | 技术 | 版本 |
|------|------|------|
| HTTP 框架 | Gin | v1.9+ |
| 数据库驱动 | pgx | v5 |
| 数据库迁移 | golang-migrate | v4 |
| 对象存储 | minio-go | v7 |
| WebSocket | gorilla/websocket | v1.5 |
| Excel 处理 | excelize | v2 |
| 图片处理 | golang.org/x/image | - |
| PDF 生成 | gofpdf | - |
| 指标 | prometheus/client_golang | v1 |
| 配置 | viper | v1 |
| 日志 | log/slog | 标准库 |

## 快速开始

### 前置条件

- Go 1.22+
- Docker & Docker Compose
- Make（可选）

### 一键启动

```bash
docker-compose up -d
```

服务启动后：
- API: http://localhost:8080
- MinIO Console: http://localhost:9001 (minioadmin/minioadmin)
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3000 (admin/admin)

### 本地开发

```bash
# 启动依赖服务
docker-compose up -d postgres minio mc-init

# 运行服务
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=file_task
export DB_USER=file_task
export DB_PASSWORD=file_task_pass
export MINIO_ENDPOINT=localhost:9000
export MINIO_ACCESS_KEY=minioadmin
export MINIO_SECRET_KEY=minioadmin
export MINIO_USE_SSL=false

go run cmd/server/main.go
```

## API 接口

### 上传

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/upload/init | 初始化上传（含秒传判定） |
| PUT | /api/v1/upload/chunk | 上传分片（幂等） |
| POST | /api/v1/upload/complete | 触发流式合并 |
| GET | /api/v1/upload/:uploadID/status | 查询上传状态 |

### 任务

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/tasks | 提交异步任务 |
| GET | /api/v1/tasks/:taskID | 查询任务状态 |
| POST | /api/v1/tasks/:taskID/cancel | 取消任务 |

### 进度推送

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/tasks/:taskID/events | SSE 进度订阅 |
| GET | /api/v1/tasks/:taskID/ws | WebSocket 进度订阅 |

### 其他

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /health | 健康检查 |
| GET | /metrics | Prometheus 指标 |

## 使用示例

### 大文件上传

```bash
# 1. 初始化上传
curl -X POST http://localhost:8080/api/v1/upload/init \
  -H "Content-Type: application/json" \
  -d '{"fileName":"report.xlsx","fileSize":104857600,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}'

# 2. 上传分片
curl -X PUT http://localhost:8080/api/v1/upload/chunk \
  -F "uploadID=<uploadID>" \
  -F "index=0" \
  -F "file=@chunk_0.bin"

# 3. 触发合并
curl -X POST http://localhost:8080/api/v1/upload/complete \
  -H "Content-Type: application/json" \
  -d '{"uploadID":"<uploadID>"}'
```

### 提交异步任务

```bash
# Excel 导入
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"taskType":"excel_import","payload":{"filePath":"uploads/xxx/report.xlsx","sheet":"Sheet1"}}'

# 图片压缩
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"taskType":"image_compress","payload":{"filePath":"uploads/xxx/photo.png","width":800,"quality":80}}'
```

### SSE 进度订阅

```bash
curl -N http://localhost:8080/api/v1/tasks/<taskID>/events
```

## 项目结构

```
file-task-service/
├── cmd/server/main.go              # 入口
├── internal/
│   ├── config/config.go            # 配置加载
│   ├── handler/                    # HTTP Handler + 路由
│   ├── service/                    # 业务服务（Upload/TaskEngine）
│   ├── pool/                       # 自研 Worker Pool
│   ├── progress/                   # ProgressHub + SSE/WS
│   ├── handlerimpl/                # 流式处理 Handler
│   ├── store/                      # PostgreSQL + MinIO 存储
│   ├── middleware/                  # 中间件
│   ├── shutdown/manager.go         # 优雅停机
│   └── metrics/                    # Prometheus 指标
├── pkg/logger/                     # slog 日志
├── migrations/                     # 数据库迁移
├── monitoring/                     # Prometheus + Grafana 配置
├── docker-compose.yml
├── Dockerfile
└── docs/                           # 设计文档
```

## Prometheus 指标

| 指标 | 类型 | 说明 |
|------|------|------|
| ftp_task_queue_length | Gauge | 任务队列长度 |
| ftp_worker_pool_size | Gauge | Worker 数量 |
| ftp_task_duration_seconds | Histogram | 任务执行耗时 |
| ftp_task_total | Counter | 任务总数 |
| ftp_task_retry_total | Counter | 任务重试次数 |
| ftp_upload_chunk_bytes | Counter | 上传字节数 |
| ftp_active_streams | Gauge | 活跃 SSE/WS 连接数 |
| ftp_progress_dropped_total | Counter | 丢弃的进度事件数 |

## 验收标准

- [x] 5GB 文件断点续传 + 二次秒传命中
- [x] 200 并发 Excel 导入，Pool 8→32 扩容曲线可见
- [x] `kill -TERM` 60s 内退出，长连接收到 shutdown
- [x] `go test -bench` 输出自研 vs ants 对比表

## 非目标

- 不做鉴权（`X-User-ID` header 占位）
- 不做分布式 / 多节点
- 不做前端 UI

## License

MIT