docs: add project documentation files and version constant
Add AGENTS.md, docs/ (CHANGELOG, CHANGELOG_webui, README), and pkg/constant/version.go.
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
- 后续若补充了技术栈、启动流程、部署方式或重要文档内容，建议继续记录在本文件中。
|
||||
@@ -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.
|
||||
- 后续若补充了技术栈、启动流程、部署方式或重要文档内容，建议继续记录在本文件中。
|
||||
+105
@@ -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://<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/ # 集成测试
|
||||
```
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目仅供学习与自用部署场景，请自行负责数据安全与访问控制。
|
||||
@@ -0,0 +1,3 @@
|
||||
package constant
|
||||
|
||||
const Version = "0.1.0"
|
||||
Reference in New Issue
Block a user