mirror of
https://git.fightbot.fun/hxuanyu/FileRelay.git
synced 2026-02-15 06:01:43 +08:00
168 lines
6.5 KiB
Markdown
168 lines
6.5 KiB
Markdown
# FileRelay - 文件暂存柜
|
||
|
||
[](https://github.com/hanxuanyu/FileRelay/actions/workflows/build.yml)
|
||
[](https://github.com/hanxuanyu/FileRelay/actions/workflows/release.yml)
|
||
[](https://github.com/hanxuanyu/FileRelay/actions/workflows/docker-publish.yml)
|
||
|
||
中文 | [English](README_en.md)
|
||
|
||
---
|
||
|
||
FileRelay 是一个简单高效、自托管的文件暂存柜系统，旨在为您提供便捷的临时文件分享和中转服务。
|
||
|
||
### 🚀 主要特性
|
||
|
||
- **临时分享**：上传文件或文本，生成唯一取件码，方便在不同设备间快速传输。
|
||
- **多数据库支持**：支持 SQLite, MySQL 和 PostgreSQL，默认为 SQLite 开箱即用，生产环境可无缝切换至 MySQL 或 PostgreSQL。
|
||
- **多种存储后端**：支持本地磁盘存储、Amazon S3（及兼容 S3 的服务）以及 WebDAV 存储。
|
||
- **灵活的过期策略**：支持按时间过期和按下载次数过期（需在管理后台配置或手动清理）。
|
||
- **取件保护**：支持自定义取件码长度，内置尝试次数限制防暴力破解。
|
||
- **管理后台**：内置美观的管理界面，支持：
|
||
- 动态修改系统配置。
|
||
- 实时查看和管理上传批次。
|
||
- API Token 管理（支持权限细分：上传、取件、管理）。
|
||
- **高性能**：采用 Go 语言编写，内存占用极低，支持高并发访问。
|
||
- **易于部署**：支持单一二进制文件运行，前端资源已嵌入，无需额外配置 Web 服务器。
|
||
|
||
### 🛠️ 技术栈
|
||
|
||
- **后端**: Go 1.24+ (Gin, GORM)
|
||
- **数据库**: SQLite, MySQL, PostgreSQL (支持多种数据库，灵活扩展)
|
||
- **前端**: Vue 3 + TailwindCSS (位于 `webapp` 目录)，已通过 `embed` 嵌入二进制。
|
||
- **文档**: 集成 Swagger UI。
|
||
|
||
### 🏗️ 开发与构建
|
||
|
||
#### 环境要求
|
||
|
||
- **Go**: 1.24 或更高版本
|
||
- **Node.js**: 20 或更高版本 (用于前端构建)
|
||
- **npm**: 随 Node.js 安装
|
||
|
||
#### 本地开发
|
||
|
||
1. **前端开发**:
|
||
```bash
|
||
cd webapp
|
||
npm install
|
||
npm run dev
|
||
```
|
||
前端开发服务器默认运行在 `http://localhost:5173`。
|
||
|
||
2. **后端开发**:
|
||
```bash
|
||
# 返回项目根目录
|
||
go run main.go -config config/config.yaml
|
||
```
|
||
|
||
#### 完整构建
|
||
|
||
项目提供了自动化的构建脚本，会自动完成前端构建、资源嵌入以及 Go 编译：
|
||
|
||
- **Windows (CMD)**: `scripts\build.bat`
|
||
- **Windows (PowerShell)**: `.\scripts\build.ps1`
|
||
- **Linux/macOS**: `chmod +x scripts/build.sh && ./scripts/build.sh`
|
||
|
||
构建产物将存放在 `output` 目录下。
|
||
|
||
### 📦 快速开始
|
||
|
||
#### 1. 获取程序
|
||
|
||
您可以从 Release 页面下载对应平台的二进制文件，或者按照上述“完整构建”步骤自行编译。
|
||
|
||
#### 2. 配置文件
|
||
|
||
在运行之前，请根据需求修改 `config/config.yaml`。详细配置说明请参考 [docs/config_specification.md](docs/config_specification.md)。
|
||
|
||
主要配置项包括：
|
||
- 存储类型 (`local`, `s3`, `webdav`)。
|
||
- 管理员密码哈希。
|
||
- 数据库配置 (`type`, `host`, `port`, `user`, `password`, `dbname` 等)。系统支持自动迁移，首次连接新数据库时将自动创建表结构。此外，`scripts/sql/` 目录下也提供了各数据库的初始化 SQL 脚本供参考。
|
||
|
||
#### 3. 运行
|
||
|
||
```bash
|
||
./filerelay -config config/config.yaml
|
||
```
|
||
|
||
### 🐳 Docker 部署
|
||
|
||
我们提供了 Docker 和 Docker Compose 支持，实现一键部署：
|
||
|
||
#### 使用 Docker 镜像 (推荐)
|
||
|
||
如果您不想自行构建，可以直接从 Docker Hub 拉取已构建好的镜像：
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name filerelay \
|
||
-p 8080:8080 \
|
||
-v $(pwd)/data:/app/data \
|
||
-v $(pwd)/config:/app/config \
|
||
hxuanyu521/filerelay:latest
|
||
```
|
||
|
||
**提示：**
|
||
- 如果您需要使用自定义的 Web 页面（外置前端资源），可以将资源目录挂载到容器内，并通过环境变量 `FR_WEB_PATH` 指定路径。例如：
|
||
`-v $(pwd)/my-web:/app/my-web -e FR_WEB_PATH=/app/my-web`
|
||
- 默认情况下，程序会优先寻找 `FR_WEB_PATH`（或配置文件中的 `web.path`）指定的外部资源，若找不到则使用内置的嵌入资源。
|
||
|
||
#### 使用 Docker Compose
|
||
|
||
1. 确保已安装 Docker 和 Docker Compose。
|
||
2. 在项目根目录下运行：
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
程序默认会在当前目录下的 `./data` 文件夹中持久化存储数据、日志、数据库和配置。
|
||
|
||
#### 环境变量控制
|
||
|
||
支持通过环境变量覆盖配置文件中的关键项，方便在 Docker 环境下动态调整：
|
||
|
||
| 环境变量 | 说明 | 默认值 |
|
||
| :--- | :--- | :--- |
|
||
| **站点设置** | | |
|
||
| `FR_SITE_NAME` | 站点名称 | 文件暂存柜 |
|
||
| `FR_SITE_BASE_URL` | 站点外部访问地址 (用于生成分享链接) | (空) |
|
||
| `FR_SITE_PORT` | 服务监听端口 | 8080 |
|
||
| **安全设置** | | |
|
||
| `FR_SECURITY_JWT_SECRET` | JWT 签名密钥 | file-relay-secret |
|
||
| **上传设置** | | |
|
||
| `FR_UPLOAD_MAX_SIZE` | 单个文件最大大小 (MB) | 100 |
|
||
| `FR_UPLOAD_RETENTION_DAYS` | 文件最大保留天数 | 30 |
|
||
| **数据库设置** | | |
|
||
| `FR_DB_TYPE` | 数据库类型 (sqlite, mysql, postgres) | sqlite |
|
||
| `FR_DB_PATH` | SQLite 数据库文件路径 | data/file_relay.db |
|
||
| `FR_DB_HOST` | 数据库主机地址 (MySQL/Postgres) | (空) |
|
||
| `FR_DB_PORT` | 数据库端口 (MySQL/Postgres) | (空) |
|
||
| `FR_DB_USER` | 数据库用户名 (MySQL/Postgres) | (空) |
|
||
| `FR_DB_PASSWORD` | 数据库密码 (MySQL/Postgres) | (空) |
|
||
| `FR_DB_NAME` | 数据库名称 (MySQL/Postgres) | (空) |
|
||
| **存储设置** | | |
|
||
| `FR_STORAGE_TYPE` | 存储类型 (local, s3, webdav) | local |
|
||
| `FR_STORAGE_LOCAL_PATH` | 本地存储路径 | data/storage_data |
|
||
| **日志设置** | | |
|
||
| `FR_LOG_LEVEL` | 日志级别 (debug, info, warn, error) | info |
|
||
| `FR_LOG_FILE_PATH` | 日志文件路径 | data/logs/app.log |
|
||
| **Web 设置** | | |
|
||
| `FR_WEB_PATH` | 外部 Web 静态资源路径 | web |
|
||
|
||
程序启动后，您可以通过以下地址访问（默认端口 8080）：
|
||
- **Web 界面**: `http://localhost:8080`
|
||
- **管理后台**: `http://localhost:8080/admin` (前端路由)
|
||
- **API 文档**: `http://localhost:8080/swagger/index.html`
|
||
|
||
### 📖 接口说明
|
||
|
||
FileRelay 提供了丰富的 API 接口，支持通过 API Token 进行集成。
|
||
|
||
- **上传**: `POST /api/batches`
|
||
- **取件**: `GET /api/batches/:pickup_code`
|
||
- **下载**: `GET /api/files/:file_id/download`
|
||
|
||
详细接口定义请参考内置的 Swagger 文档。
|