From bdec081f8d5f6e91fee95be9f63fc17bde289cbc Mon Sep 17 00:00:00 2001 From: XingfenD Date: Thu, 27 Aug 2026 14:44:29 +0800 Subject: [PATCH 1/2] docs: add project documentation files and version constant Add AGENTS.md, docs/ (CHANGELOG, CHANGELOG_webui, README), and pkg/constant/version.go. --- AGENTS.md | 8 +++ docs/CHANGELOG.md | 34 +++++++++++++ docs/CHANGELOG_webui.md | 34 +++++++++++++ docs/README.md | 105 ++++++++++++++++++++++++++++++++++++++++ pkg/constant/version.go | 3 ++ 5 files changed, 184 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/CHANGELOG.md create mode 100644 docs/CHANGELOG_webui.md create mode 100644 docs/README.md create mode 100644 pkg/constant/version.go diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7401b32 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,8 @@ +# AGENTS.md + +## Safety Rules +- Dev branch naming: `{feat|fix|docs|chore}/{branch-name}` (e.g. `feat/file-tag-done`, `fix/tree-render`). +- Before `git commit`: run `git branch --show-current`. If on `master`, do NOT commit — ask user for a branch name (suggest one based on the changes, e.g. `docs/simplify-branch-workflow`), create it, commit there. +- General changes → `docs/CHANGELOG.md`; WebUI changes → `docs/CHANGELOG_webui.md` (files under `web/`). Higher versions on top. +ANGELOG entry format: same entry has English line then Chinese line on consecutive lines (no blank line between them); different entries are separated by a blank line. +- Version control: When bumping a version, update both the changelog and the corresponding version constant: `pkg/constant/version.go` for backend. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..541ba7e --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog / 更新日志 + +All notable changes to this template should be documented in this file. +本模板的重要变更建议统一记录在此文件中。 + +The format loosely follows Keep a Changelog and can be adapted to the team's habits. +本文档参考了 Keep a Changelog 的思路，也可以根据团队习惯调整。 + +## [0.0.1] - 2026-04-28 + +### Added / 新增 + +- Added an English project-template README in `docs/README.md`. +- 在 `docs/README.md` 中补充了英文版项目模板说明。 + +- Added a Chinese project-template README in `docs/README_zh.md`. +- 在 `docs/README_zh.md` 中补充了中文版项目模板说明。 + +- Added guidance for template users on how to rewrite the README for their own project. +- 增加了模板使用者如何把 README 改写为自己项目介绍的说明。 + +- Added a documented repository structure overview based on the current scaffold. +- 基于当前仓库骨架补充了目录结构说明。 + +- Added this changelog file for future template maintenance. +- 新增本更新日志文件，便于后续持续维护模板。 + +### Notes / 说明 + +- The repository currently provides structure and placeholder files rather than a finished implementation. +- 当前仓库主要提供目录结构和占位文件，尚不是一个已完成功能实现的成品项目。 + +- Future updates should record framework selection, startup steps, deployment workflow, and major documentation changes. +- 后续若补充了技术栈、启动流程、部署方式或重要文档内容，建议继续记录在本文件中。 \ No newline at end of file diff --git a/docs/CHANGELOG_webui.md b/docs/CHANGELOG_webui.md new file mode 100644 index 0000000..541ba7e --- /dev/null +++ b/docs/CHANGELOG_webui.md @@ -0,0 +1,34 @@ +# Changelog / 更新日志 + +All notable changes to this template should be documented in this file. +本模板的重要变更建议统一记录在此文件中。 + +The format loosely follows Keep a Changelog and can be adapted to the team's habits. +本文档参考了 Keep a Changelog 的思路，也可以根据团队习惯调整。 + +## [0.0.1] - 2026-04-28 + +### Added / 新增 + +- Added an English project-template README in `docs/README.md`. +- 在 `docs/README.md` 中补充了英文版项目模板说明。 + +- Added a Chinese project-template README in `docs/README_zh.md`. +- 在 `docs/README_zh.md` 中补充了中文版项目模板说明。 + +- Added guidance for template users on how to rewrite the README for their own project. +- 增加了模板使用者如何把 README 改写为自己项目介绍的说明。 + +- Added a documented repository structure overview based on the current scaffold. +- 基于当前仓库骨架补充了目录结构说明。 + +- Added this changelog file for future template maintenance. +- 新增本更新日志文件，便于后续持续维护模板。 + +### Notes / 说明 + +- The repository currently provides structure and placeholder files rather than a finished implementation. +- 当前仓库主要提供目录结构和占位文件，尚不是一个已完成功能实现的成品项目。 + +- Future updates should record framework selection, startup steps, deployment workflow, and major documentation changes. +- 后续若补充了技术栈、启动流程、部署方式或重要文档内容，建议继续记录在本文件中。 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6c4387d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,105 @@ +# 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+ + +### 构建 + +```bash +make build +``` + +该命令会生成名为 `yDropbox` 的静态二进制文件（关闭 CGO）。 + +### 运行 + +```bash +./yDropbox --addr 127.0.0.1:8999 --workspace ./workspace --token YOUR_SECRET_TOKEN +``` + +或使用环境变量提供令牌： + +```bash +export YDROPBOX_TOKEN=YOUR_SECRET_TOKEN +./yDropbox --workspace ./workspace +``` + +启动时会自动创建 `workspace/inbox`、`workspace/outbox` 与 `workspace/.ydropbox` 目录。 + +### 其他命令 + +```bash +make test # 运行测试 (go test ./...) +make vet # 静态检查 (go vet ./...) +make clean # 删除二进制文件 +``` + +## 配置 + +| 参数 / 环境变量 | 说明 | 默认值 | +| ---------------------- | --------------------------------- | ---------------- | +| `--addr` | HTTP 监听地址 | `127.0.0.1:8999` | +| `--workspace` | 工作区目录（文件与数据库存放处） | `./workspace` | +| `--token` / `YDROPBOX_TOKEN` | 访问令牌（必填，用于登录校验） | 无（必须提供） | + +## 使用 + +1. 在浏览器打开 `http:///`，使用启动时的令牌登录。 +2. 在 `inbox` / `outbox` 面板中通过按钮或拖拽上传文件。 +3. 点击下载 / 删除管理文件。 +4. 点击分享生成链接；可在创建时设置密码与过期时间，链接形如 `/s/`。 + +## 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/ # 集成测试 +``` + +## 许可证 + +本项目仅供学习与自用部署场景，请自行负责数据安全与访问控制。 diff --git a/pkg/constant/version.go b/pkg/constant/version.go new file mode 100644 index 0000000..ea8d5e7 --- /dev/null +++ b/pkg/constant/version.go @@ -0,0 +1,3 @@ +package constant + +const Version = "0.1.0" From 4c96bf25be885e2acacb8a9e90ca90b7be464646 Mon Sep 17 00:00:00 2001 From: XingfenD Date: Thu, 27 Aug 2026 14:45:08 +0800 Subject: [PATCH 2/2] go mod tidy --- go.mod | 7 +++++-- go.sum | 30 ++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/go.mod b/go.mod index 9ebd36a..73ffbd4 100644 --- a/go.mod +++ b/go.mod @@ -2,16 +2,19 @@ module yoresee_dropbox go 1.25.0 +require ( + golang.org/x/crypto v0.55.0 + modernc.org/sqlite v1.57.0 +) + require ( github.com/dustin/go-humanize v1.0.1 // indirect github.com/google/uuid v1.6.0 // indirect github.com/mattn/go-isatty v0.0.24 // indirect github.com/ncruces/go-strftime v1.0.0 // indirect github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect - golang.org/x/crypto v0.55.0 // indirect golang.org/x/sys v0.47.0 // indirect modernc.org/libc v1.74.4 // indirect modernc.org/mathutil v1.7.1 // indirect modernc.org/memory v1.11.0 // indirect - modernc.org/sqlite v1.57.0 // indirect ) diff --git a/go.sum b/go.sum index a5efcc8..e2c6978 100644 --- a/go.sum +++ b/go.sum @@ -1,7 +1,11 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY= github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto= +github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo= +github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k= +github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM= github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI= github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A= github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w= @@ -10,13 +14,39 @@ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo= golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M= golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis= +golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ= +golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0= +golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM= +golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q= +golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA= +modernc.org/cc/v4 v4.29.1 h1:MKgdCV3WykTSPqpVrnxdEDS0HEd2FHpKZDzxzU5LyeI= +modernc.org/cc/v4 v4.29.1/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI= +modernc.org/ccgo/v4 v4.34.6 h1:sBgfIwyN0TQ9C5hwIeuqyeAKyMWnbvj2fvpF4L11uzU= +modernc.org/ccgo/v4 v4.34.6/go.mod h1:SZ8YcN9NG7XVsQYdm6jYBvi8PQP1qi+kqB6OhjqI3Fk= +modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM= +modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU= +modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI= +modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito= +modernc.org/gc/v3 v3.1.4 h1:2g65LGVSmFQrXeITAw97x7hCRvZFcyE1uDP+7Vng7JI= +modernc.org/gc/v3 v3.1.4/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY= +modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks= +modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI= modernc.org/libc v1.74.4 h1:fX1Omw4o2/1C2iRkkIsrQTasJQldLhRmuPreXLoWs9k= modernc.org/libc v1.74.4/go.mod h1:eeQAS9W3sZeKYMFubydxJpII9ybHWshk+7or7bLG9co= modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU= modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg= modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI= modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw= +modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg= +modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns= +modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w= +modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE= modernc.org/sqlite v1.57.0 h1:qNQP6xnx5M0ISNtlnxoOX0+cD5bJ0/gr9aMmndFczzg= modernc.org/sqlite v1.57.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ= +modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0= +modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A= +modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y= +modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=