go-simple-upload-server

镜像概述和主要用途

go-simple-upload-server 是一个用Golang编写的轻量级HTTP服务器，主要用途是存储文件制品。它提供简单的文件上传、下载功能，并支持基于token的认证机制，适用于个人文件存储、小型团队共享或CI/CD制品暂存等场景。

核心功能和特性

• 文件操作：支持通过POST /upload上传文件（自动命名）、PUT /files/:path指定路径上传，以及GET /files/:path下载文件
• 认证控制：基于token的访问控制，区分只读令牌（允许GET/HEAD）和读写令牌（允许POST/PUT/GET/HEAD）
• 灵活配置：支持命令行参数或配置文件设置，包括监听地址、文档根目录、最大上传大小、文件命名策略等
• CORS支持：默认启用跨域资源共享，便于前端应用集成
• 安全控制：可配置为只读模式（仅提供下载功能）

使用场景和适用范围

• 个人文件临时存储或共享
• 小型团队内部文件交换
• CI/CD流程中构建制品的临时存储
• 前端应用的简单文件上传后端

使用方法和配置说明

命令行参数

基本使用示例

简单启动（无认证）

docker run -p 8080:8080 -v ./data:/data go-simple-upload-server -addr 0.0.0.0:8080 -document_root /data

启用认证（带读写令牌）

docker run -p 8080:8080 -v ./data:/data go-simple-upload-server \
  -addr 0.0.0.0:8080 \
  -document_root /data \
  -enable_auth \
  -read_write_tokens "rw_token1,rw_token2" \
  -read_only_tokens "ro_token1"

认证机制

默认无需认证，启用认证需设置-enable_auth=true，并配置令牌：

• 只读令牌（read_only_tokens）：允许执行GET（下载）、HEAD（检查文件存在）操作
• 读写令牌（read_write_tokens）：允许所有只读操作及POST（上传）、PUT（指定路径上传）操作

认证方式：

• 通过Authorization: Bearer <TOKEN>请求头传递
• 或通过token=<TOKEN>查询参数传递（请求头优先级更高）

认证失败响应：401 Unauthorized，响应体为{"ok": false, "error": "unauthorized"}

TLS支持

v2版本移除了内置TLS支持，建议通过反向代理（如Nginx）实现HTTPS。

API文档

POST /upload

上传文件，服务器自动生成文件名（基于命名策略）

请求

• Content-Type：multipart/form-data
• 参数：

  名称	是否必填	类型	描述	默认值
  file	是	Form Data	文件内容	-
  overwrite	否	boolean	是否允许覆盖已有文件	false

响应

• 成功：201 Created，Content-Type: application/json

  {"ok": true, "path": "/files/<filename>"}
  

• 失败：409 Conflict（文件已存在且未允许覆盖）

示例

curl -F "file=@localfile.txt" http://localhost:8080/upload

PUT /files/:path

上传文件并指定存储路径（忽略原始文件名）

请求

• 参数：

  名称	是否必填	类型	描述	默认值
  :path	是	URL路径	服务器存储路径（如/docs/report.pdf）	-
  file	是	Form Data	文件内容	-
  overwrite	否	boolean	是否允许覆盖已有文件	false

响应

• 成功：201 Created，Content-Type: application/json

  {"ok": true, "path": "/files/<path>"}
  

• 失败：409 Conflict（文件已存在且未允许覆盖）

示例

curl -X PUT -F "file=@localfile.txt" http://localhost:8080/files/docs/report.pdf

GET /files/:path

下载指定路径的文件

请求

• 参数：

  名称	是否必填	类型	描述
  path	是	URL路径	文件存储路径

响应

• 成功：200 OK，响应体为文件内容（Content-Type自动推断）
• 失败：404 Not Found（文件不存在）

示例

curl http://localhost:8080/files/docs/report.pdf -o downloaded.pdf

HEAD /files/:path

检查文件是否存在（仅返回响应头，无响应体）

请求

• 参数：path（URL路径，文件存储路径）

响应

• 成功：200 OK（文件存在）
• 失败：404 Not Found（文件不存在）

示例

curl -I http://localhost:8080/files/docs/report.pdf

OPTIONS /files/:path 和 OPTIONS /upload

CORS预检请求（无需认证，始终返回204 No Content）

注意

• 不支持 OPTIONS * HTTP/1.1 格式请求
• 即使文件不存在，OPTIONS /files/:path 仍返回 204 No Content

测试

本地测试

# 运行所有测试（含端到端测试）
go test ./...

# 使用真实文件系统测试（需确保文档根目录为空）
TEST_WITH_REAL_FS="./testdata" go test ./...

# 测试远程服务器（需提前清空目标服务器文档根目录）
TEST_TARGET_ADDR="localhost:8080" go test ./...

Docker Compose测试

# 运行端到端测试
docker compose -f docker-compose.e2e.yml run --rm test

# 测试完成后清理
docker compose -f docker-compose.e2e.yml down --rmi local --volumes