一个轻量级、可自托管的对象存储系统，可作为 文件图床

用户144533902428
55 阅读6分钟

Go-Storage 📦

一个轻量级、可自托管的对象存储系统，可作为 文件图床后台 使用，支持：

  • 文件上传、下载、删除；
  • 匿名与 UUID 权限控制；
  • 临时凭证 (STS)；
  • 数据库索引（BadgerDB）；
  • 异步同步机制；
  • 完整日志与 Debug 输出。

下载地址：pan.quark.cn/s/66a1df286…

上传文件 c4d5a1123d9e1a0f4b1f067b93804747.png

文件列表

def7b11775c28efb1b5cc213e869de70.png

🚀 快速开始

🔥运行

go run main.go --port=8088 --data=./data --debug --log

或编译为可执行文件：

go build -o go-storage main.go
./go-storage --data=./data --log --debug

⚙️启动参数

参数名默认值说明
--port8088监听端口
--data./data数据根目录（自动创建 storage0、logs、database,config ）
--logfalse是否启用日志文件输出（开启后写入 data/logs/access_YYYYMMDD.log ）
--debugfalse打印详细调试信息
--overwritefalse上传同名文件时是否覆盖
--uuid空指定主 UUID，拥有所有权限
--configconfig/uuid.jsonUUID 配置文件（若不存在会自动创建）
--access-R--匿名权限（格式为 4 位 LRWD）
--sts-exp30临时凭证有效期（分钟）
--webfalse开启WebUI
--web-routefalse开启WebUI Route， 开启SSR/SPA 路由 未知路由返回 index.html
--version-输出版本号并退出
--help-打印帮助信息

🚥权限说明（--access）

权限采用 4 位字符串，分别代表：

位含义示例
L列表权限/api/v1/list
R读取权限下载文件、查看元数据
W写入权限上传文件
D删除权限删除文件/文件夹

示例：

LRWD：拥有全部权限；
L---：仅能列出文件；
-R--：仅能读取文件；
----：完全禁用匿名访问。

权限机制

  • 通过--uuid传入的uuid拥有完全API权限，包含LRWD
  • 通过--config指定配置文件，首次运行程序会自动创建，里边包含[{"00000000-0000-0000-0000-00000000000":"LRWD"}]
  • 可指定多个uuid，每个uuid可单独设置权限，列表权限查询所有文件列表，文件不与uuid绑定，操作权限对应所有文件

📡 API 接口文档

通用说明 • 所有接口返回格式：

{
  "err": 0,
  "data": {...},
  "msg": "ok"
}
  • 当字段为 null 时自动省略。
  • 认证方式：可携带 Authorization: Bearer <token> 访问。

1️⃣ 上传文件

PUT /api/v1/storage/{key}

示例

curl -X PUT http://localhost:8088/api/v1/storage/video/demo.mp4 \
     -H "Content-Type: video/mp4" \
     --data-binary @demo.mp4

成功返回

{
  "err": 0,
  "data": {
    "uuid": "c5e00371-a7ac-4ffd-9030-6e910cdb11e2",
    "key": "video/demo.mp4",
    "url": "/video/demo.mp4"
  },
  "msg": "ok"
}

🚩但是在浏览器中，可能无法获取改PUT请求的返回值，不过不用担心，可通过GET请求获取上传结果

GET /api/v1/storage/{key}

示例

curl -X GET http://localhost:8088/api/v1/storage/video/demo.mp4

成功返回

{
  "err": 0,
  "data": {
    "uuid": "c5e00371-a7ac-4ffd-9030-6e910cdb11e2",
    "key": "video/demo.mp4",
    "url": "/video/demo.mp4",
    "meta":{
      "uuid": "c5e00371-a7ac-4ffd-9030-6e910cdb11e2",
      "original_name": "data.m2a",
      "size": 173997,
      "content_type": "audio/mpeg",
      "feature_code": "video/demo.mp4",
      "created_at": "2025-10-25T22:17:30.845152+08:00"
    }
  },
  "msg": "ok"
}

2️⃣ 获取文件

GET /uuid 或 /key

示例，以下两种URL请求文件，两种方式同等功效

curl http://localhost:8088/c5e00371-a7ac-4ffd-9030-6e910cdb11e2
curl http://localhost:8088/video/demo.mp4

3️⃣ 删除文件或目录

DELETE /uuid 或 /key

示例

curl -X DELETE http://localhost:8088/api/v1/storage/video/demo.mp4

成功返回：

{"err":0,"msg":"deleted"}

4️⃣ 列出文件（数据库索引）

GET /api/v1/list

示例

curl http://localhost:8088/api/v1/list

返回：

{
  "err": 0,
  "data": [
    {"uuid":"c5e00371-a7ac-4ffd-9030-6e910cdb11e2","path":"video/demo.mp4"}
  ],
  "msg": "ok"
}

⸻

5️⃣ 同步数据库与文件系统

GET /api/v1/sync
  • 异步执行：立即返回上次结果；
  • 若同步任务已在执行，返回错误提示。

示例

curl http://localhost:8088/api/v1/sync

返回：

{
  "err": 0,
  "data": {"added": 2, "removed": 1, "latest": "2025-10-25T19:50:00+08:00"},
  "msg": "sync started"
}

6️⃣ 申请临时凭证（STS）

POST /api/v1/sts

请求

{"uuid": "c5e00371-a7ac-4ffd-9030-6e910cdb11e2"}

响应

{
  "err": 0,
  "data": {
    "token": "uuid|1735000000.abc123...",
    "expires_at": 1735000000
  },
  "msg": "ok"
}

🌰携带凭证请求API示例

请根据请求详细参数替换为自己熟悉的语言，以下演示为curl请求

🔓sts 授权

curl -X \
 POST http://localhost:8088/api/v1/sts \
 -d '{"uuid":"4d7d9dd0-d555-4d52-9528-97f51579fd84"}' \
 -i

📋list 文件与数据库

curl -X \
GET "http://localhost:8088/api/v1/list" \
 -H "Authorization: Bearer 4d7d9dd0-d555-4d52-9528-97f51579fd84|1761386903.ca4fbfd23c3202652c0a93363c6cf2e05547dc8182ed823e835d2a41abe5b20b" \
-i

🚀put 文件到服务器

curl -X \
PUT "http://localhost:8088/api/v1/storage/video/demo.mp4" \
 --data-binary "@demo.mp4" \
 -H "Authorization: Bearer 4d7d9dd0-d555-4d52-9528-97f51579fd84|1761386903.ca4fbfd23c3202652c0a93363c6cf2e05547dc8182ed823e835d2a41abe5b20b" \
 -i

🗑️delete 文件或文件夹

curl -X \
DELETE "http://localhost:8088/video/demo.mp4" \
 -H "Authorization: Bearer 4d7d9dd0-d555-4d52-9528-97f51579fd84|1761386903.ca4fbfd23c3202652c0a93363c6cf2e05547dc8182ed823e835d2a41abe5b20b" \
-i

🔄sync 文件与数据库

curl -X \
GET "http://localhost:8088/api/v1/sync" \
 -H "Authorization: Bearer 4d7d9dd0-d555-4d52-9528-97f51579fd84|1761386903.ca4fbfd23c3202652c0a93363c6cf2e05547dc8182ed823e835d2a41abe5b20b" \
-i

🧰 日志与 Debug

功能 参数 输出示例

访问日志    --log  [INFO 2025-10-25 19:50:00] 127.0.0.1 PUT /api/v1/storage/video/demo.mp4 12ms
调试模式    --debug    [DEBUG 2025-10-25 19:50:01] handlePut: wrote 1024 bytes to ...

日志文件默认写入：

data/logs/access_YYYYMMDD.log

📦 部署建议

生产环境推荐

  • 使用 systemd 或 supervisord 守护运行；
  • 使用 nginx 反向代理并启用 HTTPS；
  • 定期执行 /api/v1/sync 保持索引一致；
  • 日志文件可定期清理或使用 logrotate；
  • Badger 数据库建议使用 SSD 磁盘存储。

🌲目录结构

data/
 ├── storage0/      # 文件存储目录
 ├── database/      # BadgerDB 数据库
 ├── logs/          # 访问日志
 └── config/
      └── uuid.json # UUID 权限配置

🧪 性能与限制

项目说明
数据库BadgerDB 内嵌键值数据库，支持百万级条目
同步异步执行，不阻塞请求
文件删除文件夹删除将异步清理关联条目
并发适合中小规模图床或内部文件系统
大文件支持至单机 IO 极限（推荐 < 2GB）

🏷️ License

MIT License © 2025 Designed & Developed by qiaofu

avatar
文章
阅读
粉丝