FileStore Server

Gin + MinIO + MySQL + Redis

基于 Go 的轻量级网盘服务，支持文件上传/下载、分片上传与断点续传、用户认证、基于 hash 的秒传去重。

English | MIT License

---

功能特性

• 文件管理 — 上传、下载、查询、重命名、软删除（100MB 大小限制）
• 分片上传 — 大文件分片、断点续传、自动合并、基于 hash 的秒传去重
• 用户认证 — 注册/登录，bcrypt 密码哈希，Cookie 会话（SameSite=Strict），24h Token 自动过期
• 存储后端 — 优先 MinIO（S3 兼容），初始化失败时自动回退到本地文件存储
• 安全防护 — 路径穿越防护、IP 令牌桶限流（5 req/s，burst 10）、输入校验、安全随机 Token
• 可观测性 — 结构化 JSON 日志（log/slog）、健康检查端点（Redis ping）、优雅关闭

快速开始

Docker 部署（推荐）

git clone git@github.com:jay77721/FileStore-server.git
cd filestore-server
docker compose up -d

服务启动后访问：

服务	地址	说明
应用	http://localhost:8080	主服务
MinIO 控制台	http://localhost:9001	用户名/密码：minioadmin / minioadmin

MySQL、Redis、MinIO 均由 Docker Compose 自动初始化与配置。

手动部署

环境要求： Go 1.25+、MySQL、Redis、MinIO（可选）

# 1. 安装依赖
go mod tidy

# 2. 设置环境变量
export MYSQL_DSN="root:root@tcp(127.0.0.1:3306)/fileserver?charset=utf8mb4&parseTime=True&loc=Local"
export REDIS_ADDR="127.0.0.1:6379"
export MINIO_ENDPOINT="127.0.0.1:9000"
export MINIO_ACCESS_KEY="minioadmin"
export MINIO_SECRET_KEY="minioadmin"
export MINIO_BUCKET="filestore"

# 3. 初始化数据库
mysql -u root -p fileserver < migrations/000001_init_schema.up.sql
mysql -u root -p fileserver < migrations/000002_add_indexes.up.sql

# 4. 启动
go run main.go

配置

环境变量	默认值	说明
SERVER_ADDR	:8080	HTTP 监听地址
MYSQL_DSN	root:root@tcp(127.0.0.1:3306)/fileserver?...	MySQL 连接字符串
REDIS_ADDR	127.0.0.1:6379	Redis 地址
REDIS_PASS	（空）	Redis 密码
REDIS_DB	0	Redis DB 编号
UPLOAD_DIR	./uploads	文件存储目录
CHUNK_DIR	./chunks	分片临时目录
MINIO_ENDPOINT	minio:9000	MinIO 服务地址（空=跳过 MinIO）
MINIO_ACCESS_KEY	minioadmin	MinIO Access Key
MINIO_SECRET_KEY	minioadmin	MinIO Secret Key
MINIO_BUCKET	filestore	MinIO 存储桶名称
MINIO_USE_SSL	false	是否启用 SSL

服务会优先尝试连接 MinIO。若 MINIO_ENDPOINT 为空或 MinIO 初始化失败，自动回退到 UPLOAD_DIR 本地存储。

API 接口

文件操作（需认证）

方法	路由	说明
POST	/file/upload	上传文件（支持秒传）
GET	/file/meta	按 hash 获取文件元数据
GET	/file/query	查询当前用户所有文件
GET	/file/download	按 hash 下载文件
POST	/file/update	重命名文件
POST	/file/delete	软删除文件

分片上传（需认证）

方法	路由	说明
POST	/file/upload/chunk	上传单个分片
GET	/file/upload/status	查询已上传的分片索引
POST	/file/upload/merge	合并分片为完整文件

用户操作

方法	路由	需认证	限流	说明
POST	/user/signup	×	✓	注册
POST	/user/signin	×	✓	登录，返回 Token
GET	/user/info	✓	×	获取用户信息

系统

方法	路由	说明
GET	/healthz	健康检查（Redis ping）

使用示例

# 注册
curl -X POST -d "username=test&password=123456" http://localhost:8080/user/signup

# 登录（Cookie 保存在本地，后续请求自动携带）
curl -X POST -F "username=test&password=123456" http://localhost:8080/user/signin

# 上传文件
curl -X POST -F "file=@./test.txt" -b "username=test;token=YOUR_TOKEN" \
  http://localhost:8080/file/upload

# 下载文件
curl -b "username=test;token=YOUR_TOKEN" \
  "http://localhost:8080/file/download?filehash=HASH" -o output.txt

架构

存储层

支持两级存储后端，通过 storage.Storage 接口抽象：

• MinIO — S3 兼容对象存储，Docker 部署时自动启动，生产推荐
• Local — 本地文件系统，MinIO 不可用时自动回退

认证流程

1. 用户 POST /user/signin 提交凭证
2. 服务端验证 bcrypt 密码哈希，生成 64 位随机 Token
3. Token 存入 tbl_user_token 表，设置 24h 过期
4. 写入 Set-Cookie 响应头（SameSite=Strict）
5. 后续请求通过 AuthMiddleware 从 Cookie 提取 Token 校验

分片上传流程

1. 客户端将文件切分为多个分片
2. 逐个 POST /file/upload/chunk，Redis 记录已上传索引
3. 客户端 GET /file/upload/status 查询已上传分片
4. 全部上传完成后 POST /file/upload/merge 触发合并
5. 服务端按顺序拼接分片为完整文件，落盘到存储后端
6. 清理临时分片文件

项目结构

filestore-server/
├── main.go                # 入口、路由注册、优雅关闭
├── config/
│   └── config.go          # 环境变量配置
├── db/
│   ├── mysql/
│   │   └── conn.go        # MySQL 连接池
│   ├── file.go            # tbl_file CRUD
│   └── user.go            # tbl_user / tbl_user_token CRUD
├── handler/
│   ├── handler.go         # 文件上传/下载/查询/删除 + 分片上传
│   ├── user.go            # 注册/登录 + bcrypt
│   ├── auth.go            # 认证中间件（Cookie session）
│   └── ratelimit.go       # IP 限流中间件
├── meta/
│   └── filemeta.go        # 文件元数据结构 + MySQL 桥接
├── rd/
│   └── redis.go           # Redis 连接 + hash 缓存
├── storage/
│   ├── storage.go         # Storage 接口定义
│   ├── minio.go           # MinIO 对象存储实现
│   └── local.go           # 本地文件存储实现
├── util/
│   ├── util.go            # SHA1、MD5、文件哈希、路径工具
│   ├── chunk.go           # Redis 分片追踪
│   └── resp.go            # JSON 响应辅助
├── migrations/            # SQL 迁移脚本
├── static/view/           # 前端 HTML 页面
├── uploads/               # 文件存储目录
├── chunks/                # 分片临时目录
├── Dockerfile             # 多阶段构建
└── docker-compose.yml     # Docker Compose 编排

测试

go test ./...           # 运行全部测试
go test ./util/...      # 工具包测试
go test ./handler/...   # Handler 测试

测试覆盖：

• util/ — SHA1、MD5、文件操作、路径工具、响应辅助
• handler/ — HTTP 响应、状态码、JSON 格式、认证中间件

技术栈

组件	选型	说明
HTTP 框架	Gin	高性能，社区活跃
存储	MySQL + Redis + MinIO	关系库 + 缓存 + 对象存储
认证	bcrypt + Cookie/Session	密码哈希，Token 会话
日志	log/slog	结构化 JSON 输出
部署	Docker Compose	一键启动所有依赖

许可证

MIT