yoresee_dropbox/docs

yDropbox

yDropbox 是一个自托管的轻量级文件存储服务（灵感来自 Dropbox），使用 Go 编写，编译为单一静态二进制文件，零外部依赖。它提供一个 Web 界面用于上传、管理、下载文件，并支持通过受密码保护和可过期的分享链接将文件分享给他人。

特性

• 单一二进制文件：使用 modernc.org/sqlite（纯 Go 实现的 SQLite），无需 CGO，无需外部数据库或运行时依赖。
• 工作区（Workspace）模型：文件存储在工作区下的 inbox/ 与 outbox/ 两个目录中，文件元数据保存在 .ydropbox/db.sqlite。
• 磁盘扫描同步：内置扫描器每 10 秒扫描工作区目录，将磁盘上的新增文件登记进数据库，并移除已被删除文件的元数据。这意味着你也可以直接把文件放进目录，它们会被自动纳入管理。
• 令牌认证：服务端通过访问令牌（--token 或环境变量 YDROPBOX_TOKEN）保护，Web 端登录后使用 HttpOnly、Secure 的会话 Cookie。
• 分享链接：可为任意文件生成公开分享链接，支持可选密码保护与过期时间。
• 基础防护：登录与分享密码均带有失败次数限制（5 次失败后锁定 60 秒），分享密码使用 bcrypt 哈希存储。
• 现代 Web UI：基于 Alpine.js 的前端，支持拖拽上传、Toast 提示与响应式布局。

构建与运行

前置要求

• Go 1.25+

构建

make build

该命令会生成名为 yDropbox 的静态二进制文件（关闭 CGO）。

运行

./yDropbox --addr 127.0.0.1:8999 --workspace ./workspace --token YOUR_SECRET_TOKEN

或使用环境变量提供令牌：

export YDROPBOX_TOKEN=YOUR_SECRET_TOKEN
./yDropbox --workspace ./workspace

启动时会自动创建 workspace/inbox、workspace/outbox 与 workspace/.ydropbox 目录。

其他命令

make test    # 运行测试 (go test ./...)
make vet     # 静态检查 (go vet ./...)
make clean   # 删除二进制文件

Docker 部署

项目提供了 Dockerfile 与 docker-compose.yml，将编译产物打包为单一镜像（前端资源已通过 go:embed 内嵌，SQLite 为纯 Go 实现，镜像无外部依赖）。

使用 Docker Compose（推荐）

cp .env.example .env
# 编辑 .env，设置 YDROPBOX_TOKEN 为一个高强度随机字符串
docker compose up -d --build

服务启动后监听 8999 端口，文件与数据库持久化在名为 ydropbox-data 的卷中。

仅使用 Docker

docker build -t ydropbox .
docker run -d --name ydropbox \
  -p 8999:8999 \
  -e YDROPBOX_TOKEN=YOUR_SECRET_TOKEN \
  -v "$(pwd)/workspace:/app/workspace" \
  ydropbox

注意：必须通过 -e YDROPBOX_TOKEN=... 或 --token 提供访问令牌，否则服务启动会失败（与本地运行一致）。

配置

参数 / 环境变量	说明	默认值
--addr	HTTP 监听地址	127.0.0.1:8999
--workspace	工作区目录（文件与数据库存放处）	./workspace
--token / YDROPBOX_TOKEN	访问令牌（必填，用于登录校验）	无（必须提供）

使用

1. 在浏览器打开 http://<addr>/，使用启动时的令牌登录。
2. 在 inbox / outbox 面板中通过按钮或拖拽上传文件。
3. 点击下载 / 删除管理文件。
4. 点击分享生成链接；可在创建时设置密码与过期时间，链接形如 /s/<token>。

HTTP API

所有受保护接口均需在请求中携带登录后获得的 ydropbox_session Cookie。

方法	路径	说明
POST	/api/login	使用令牌登录（{"token": "..."}）
POST	/api/logout	注销当前会话
POST	/api/upload	上传文件（multipart/form-data 字段 file）
GET	/api/files?dir=inbox|outbox	列出指定目录下的文件
GET	/api/files/{id}/download	下载指定文件
DELETE	/api/files/{id}	删除指定文件
POST	/api/files/{id}/share	创建分享链接（可选 password、expires_in_hours）
GET	/api/shares	列出所有分享链接
DELETE	/api/shares/{id}	删除指定分享链接
GET	/s/{token}	访问分享链接（受密码保护时显示表单）
POST	/s/{token}	提交分享链接密码

限制说明

• 单次上传文件大小上限为 100 MiB。
• 会话有效期为 7 天，登录失败 5 次后锁定 60 秒。
• 分享链接过期后再次访问会被自动删除。

项目结构

cmd/ydropbox/main.go      # 程序入口、命令行参数解析
internal/app/             # 应用装配（数据库、扫描器、HTTP 服务）
internal/server/          # HTTP 路由、认证、文件与分享处理、中间件
internal/store/           # SQLite 存储层（文件与分享元数据）
internal/scanner/         # 工作区目录扫描与元数据同步
web/                      # 前端静态资源（HTML/CSS/JS，Alpine.js）
tests/                    # 集成测试

许可证

本项目仅供学习与自用部署场景，请自行负责数据安全与访问控制。