okooooooo/tg-vault
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Delete docs directory

Browse Source
This commit is contained in:
nccttc authored and GitHub committed 2026-02-23 05:06:50 +08:00
1 parent accaeff5a4
commit 9446260385
9 files changed
-1213
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/DOCKER_HUB.md
-407
View File
@@ -1,407 +0,0 @@
# Docker Hub 部署指南 🐳
---
[返回文档中心](./README.md)
## 概述
本项目提供两个 Docker 镜像，可通过 Docker Hub 获取：
- `foomclous-frontend`: 前端应用（Nginx + React）
- `foomclous-backend`: 后端服务（Node.js + Express）
## 快速开始
### 使用 Docker Compose 部署
1. 创建 `docker-compose.prod.yml`:
```yaml
version: '3.8'
services:
# 前端
frontend:
image: <你的用户名>/foomclous-frontend:latest
container_name: foomclous-frontend
ports:
- "47832:80"
environment:
- VITE_API_URL=https://your-domain.com
networks:
- foomclous-network
restart: unless-stopped
# 后端
backend:
image: <你的用户名>/foomclous-backend:latest
container_name: foomclous-backend
ports:
- "51947:51947"
depends_on:
postgres:
condition: service_healthy
environment:
- DATABASE_URL=postgresql://foomclous:${DB_PASSWORD:-foomclous123}@postgres:5432/foomclous
- PORT=51947
- UPLOAD_DIR=/data/uploads
- THUMBNAIL_DIR=/data/thumbnails
- CHUNK_DIR=/data/chunks
- CORS_ORIGIN=https://your-domain.com
- ACCESS_PASSWORD_HASH=${ACCESS_PASSWORD_HASH:-}
- DOMAIN=your-domain.com
- TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-}
- TELEGRAM_API_ID=${TELEGRAM_API_ID:-}
- TELEGRAM_API_HASH=${TELEGRAM_API_HASH:-}
volumes:
- file-storage:/data
networks:
- foomclous-network
restart: unless-stopped
# 数据库
postgres:
image: postgres:16-alpine
container_name: foomclous-postgres
environment:
- POSTGRES_DB=foomclous
- POSTGRES_USER=foomclous
- POSTGRES_PASSWORD=${DB_PASSWORD:-foomclous123}
volumes:
- postgres-data:/var/lib/postgresql/data
- ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
networks:
- foomclous-network
restart: unless-stopped
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U foomclous -d foomclous" ]
interval: 5s
timeout: 5s
retries: 5
volumes:
file-storage:
driver: local
postgres-data:
driver: local
networks:
foomclous-network:
driver: bridge
```
2. 创建数据库初始化文件 `init.sql`:
```sql
-- 文件表
CREATE TABLE IF NOT EXISTS files (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
original_name VARCHAR(255) NOT NULL,
size BIGINT NOT NULL,
mime_type VARCHAR(100),
path VARCHAR(500) NOT NULL,
thumbnail_path VARCHAR(500),
folder_id UUID REFERENCES files(id) ON DELETE CASCADE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
access_count INTEGER DEFAULT 0,
storage_provider VARCHAR(50) DEFAULT 'local',
is_deleted BOOLEAN DEFAULT FALSE
);
-- API Key 表
CREATE TABLE IF NOT EXISTS api_keys (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
key_name VARCHAR(100) NOT NULL,
key_hash VARCHAR(255) NOT NULL UNIQUE,
permissions JSONB DEFAULT '[]',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
expires_at TIMESTAMP,
is_active BOOLEAN DEFAULT TRUE
);
-- 系统设置表
CREATE TABLE IF NOT EXISTS system_settings (
key VARCHAR(100) PRIMARY KEY,
value TEXT,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 创建索引
CREATE INDEX IF NOT EXISTS idx_files_folder_id ON files(folder_id);
CREATE INDEX IF NOT EXISTS idx_files_created_at ON files(created_at);
CREATE INDEX IF NOT EXISTS idx_files_original_name ON files(original_name);
```
3. 创建 `.env` 文件:
```env
DB_PASSWORD=your_secure_password
ACCESS_PASSWORD_HASH=your_hashed_password
DOMAIN=your-domain.com
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
```
4. 启动服务:
```bash
docker-compose -f docker-compose.prod.yml up -d
```
### 手动使用 Docker 镜像
#### 拉取镜像
```bash
docker pull <你的用户名>/foomclous-frontend:latest
docker pull <你的用户名>/foomclous-backend:latest
```
#### 运行前端
```bash
docker run -d \
--name foomclous-frontend \
-p 47832:80 \
-e VITE_API_URL=https://your-domain.com \
<你的用户名>/foomclous-frontend:latest
```
#### 运行后端
```bash
docker run -d \
--name foomclous-backend \
-p 51947:51947 \
-e DATABASE_URL=postgresql://foomclous:password@postgres:5432/foomclous \
-e PORT=51947 \
-e UPLOAD_DIR=/data/uploads \
-e THUMBNAIL_DIR=/data/thumbnails \
-e CHUNK_DIR=/data/chunks \
-e CORS_ORIGIN=https://your-domain.com \
-v foomclous-data:/data \
--network foomclous-network \
<你的用户名>/foomclous-backend:latest
```
## GitHub Actions 自动构建
### 配置 Secrets
在 GitHub 仓库的 Settings > Secrets and variables > Actions 中添加以下 Secrets:
| Secret 名称 | 说明 | 示例 |
|-------------|------|------|
| `DOCKER_USERNAME` | Docker Hub 用户名 | `johndoe` |
| `DOCKER_PASSWORD` | Docker Hub 密码或 Access Token | `dckr_pat_...` |
| `IMAGE_NAME` | Docker Hub 镜像名称 | `johndoe/foomclous` |
### 触发构建
工作流会在以下情况下自动触发：
- 推送到 `main` 或 `master` 分支
- 推送标签（如 `v1.0.0`）
- 手动触发（在 Actions 页面点击 "Run workflow"）
### 版本标签
推送时自动生成的标签示例：
- `latest` - 最新版本
- `v1.2.3` - 完整版本号
- `v1.2` - 主版本.次版本
- `v1` - 主版本
- `sha-abc123` - Git commit SHA
### Docker Hub Access Token
推荐使用 Access Token 而不是密码：
1. 登录 [Docker Hub](https://hub.docker.com/)
2. 进入 Account Settings > Security
3. 点击 "New Access Token"
4. 输入描述和权限（Read, Write, Delete）
5. 复制生成的 token
## 本地构建和推送
### 构建镜像
```bash
# 构建 Backend
docker build -t your-username/foomclous-backend:latest ./backend
# 构建 Frontend
docker build -t your-username/foomclous-frontend:latest ./frontend
```
### 推送到 Docker Hub
```bash
# 登录
docker login
# 推送
docker push your-username/foomclous-backend:latest
docker push your-username/foomclous-frontend:latest
```
## 镜像信息
| 镜像 | 基础镜像 | 大小 | 说明 |
|------|---------|------|------|
| `foomclous-frontend` | `nginx:alpine` | ~30MB | 静态文件服务 |
| `foomclous-backend` | `node:20-alpine` | ~150MB | API 服务 |
### 环境变量
#### Backend
| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `DATABASE_URL` | 是 | - | PostgreSQL 连接字符串 |
| `PORT` | 否 | `51947` | 服务端口 |
| `UPLOAD_DIR` | 否 | `/data/uploads` | 上传文件目录 |
| `THUMBNAIL_DIR` | 否 | `/data/thumbnails` | 缩略图目录 |
| `CHUNK_DIR` | 否 | `/data/chunks` | 分块上传临时目录 |
| `CORS_ORIGIN` | 是 | - | CORS 允许的源 |
| `ACCESS_PASSWORD_HASH` | 否 | - | 访问密码哈希 |
| `DOMAIN` | 否 | - | 域名 |
| `TELEGRAM_BOT_TOKEN` | 否 | - | Telegram Bot Token |
| `TELEGRAM_API_ID` | 否 | - | Telegram API ID |
| `TELEGRAM_API_HASH` | 否 | - | Telegram API Hash |
#### Frontend
| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `VITE_API_URL` | 是 | - | 后端 API 地址 |
## 端口映射
| 服务 | 容器端口 | 宿主机端口 | 说明 |
|------|---------|-----------|------|
| Frontend | 80 | 47832 | HTTP |
| Backend | 51947 | 51947 | API |
## 数据持久化
使用 Docker Volume 持久化数据：
```bash
# 查看卷
docker volume ls
# 备份卷
docker run --rm -v foomclous-data:/data -v $(pwd):/backup alpine tar czf /backup/foomclous-data-backup.tar.gz /data
# 恢复卷
docker run --rm -v foomclous-data:/data -v $(pwd):/backup alpine tar xzf /backup/foomclous-data-backup.tar.gz -C /
```
## Nginx 反向代理配置
如果你有域名，可以配置 Nginx 反向代理：
```nginx
# 前端
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
location / {
proxy_pass http://localhost:47832;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# 后端 API
server {
listen 443 ssl http2;
server_name api.your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
location / {
proxy_pass http://localhost:51947;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 500M;
}
}
```
## 常见问题
### 1. 镜像拉取失败
```bash
# 重新登录 Docker Hub
docker login
```
### 2. 数据库连接失败
检查 `DATABASE_URL` 环境变量和网络配置是否正确。
### 3. 上传文件失败
检查存储目录权限和磁盘空间。
### 4. 查看日志
```bash
# 查看所有容器日志
docker-compose logs -f
# 查看特定容器日志
docker logs -f foomclous-backend
docker logs -f foomclous-frontend
```
## 更新镜像
```bash
# 拉取最新镜像
docker-compose pull
# 重新创建容器
docker-compose up -d
```
## 停止和清理
```bash
# 停止容器
docker-compose down
# 停止并删除卷（警告：会删除数据！）
docker-compose down -v
```
## 安全建议
1. **使用强密码**：数据库和访问密码应使用强密码
2. **定期更新**：定期拉取最新镜像更新
3. **HTTPS**：生产环境必须使用 HTTPS
4. **防火墙**：限制不必要的端口访问
5. **备份**：定期备份数据卷
6. **日志监控**：监控容器日志发现异常
## 支持
如有问题，请提交 Issue 或联系维护者。
docs/README.md
-39
View File
@@ -1,39 +0,0 @@
# FoomClous 文档中心 🚀
欢迎来到 FoomClous 文档中心。FoomClous 是一个高性能、模块化的个人云存储中转方案，旨在为您提供便捷、安全的多端存储管理体验。
---
## 🗺️ 文档导航
### 🏁 快速开始
- **[存储源配置指南](./storage_configuration_guide.md)**
*配置本地、OneDrive、阿里云 OSS、S3 及 WebDAV。*
- **[YT-DLP 下载专区](./ytdlp.md)**
*通过 Telegram Bot 的 `/ytdlp` 一键解析链接并下载到存储源，前端提供独立分区查看。*
- **[Docker 维护与清理](./docker-cleanup-guide.md)**
*如何保持容器环境整洁，定期清理上传缓存与冗余镜像。*
### 🧠 工作原理
- **[上传架构说明](./upload_architecture.md)**
*了解 FoomClous 如何通过服务器中转确保您的数据安全与传输稳定。*
- **[Telegram Bot 逻辑](./bot_logic.md)**
*解析机器人的消息队列、上传状态同步与自动化流转机制。*
### ✨ 功能说明
- **[收藏夹功能](./favorites-feature.md)**
*收藏文件/文件夹并在前端侧边栏快速访问。*
- **[项目介绍](./introduction_optimized.md)**
*FoomClous 的定位、能力边界与适用场景。*
---
## 🌟 项目亮点
- **多端上传**：支持 Web 后台管理与 Telegram 机器人一键转存。
- **广阔兼容**：原生适配本地磁盘、S3 兼容存储、WebDAV、OneDrive 等主流云端。
- **智能体验**：支持视频在线预览、GIF 动图自动播放及大文件断点续传。
- **隐私保护**：所有云端凭据仅本地保存，通过服务器代理模式避免密钥泄露。
---
*© 2026 FoomClous Team. Documentation updated at: 2026-02-21*
docs/bot_logic.md
-51
View File
@@ -1,51 +0,0 @@
# Telegram Bot 逻辑解析 🤖
FoomClous 的 Telegram 机器人不仅是上传入口，更是一个全自动化的文件流转引擎。它具备多任务并行、实时状态同步及完善的防洪保护机制。
## ⚙️ 核心流程
机器人采用 **“下载 - 中转 - 上传”** 模式：
```mermaid
sequenceDiagram
participant User as 用户
participant Bot as TG Bot
participant Worker as 后端 Worker
participant Storage as 存储提供商
User->>Bot: 发送链接/文件
Bot->>Worker: 加入下载队列
Worker->>Worker: 校验链接 & 创建临时空间
Worker->>Bot: 发送“正在下载”消息
loop 下载中
Worker->>Bot: 更新下载进度 (每 2s)
end
Worker->>Storage: 开始推送到云端 (S3/WebDAV/OSS)
Worker->>Bot: 更新“正在上传”状态
Storage-->>Worker: 上传完成
Worker->>Bot: 修改消息为“✅ 上传成功”
Worker->>Worker: 清理本地临时文件
```
## 🌪️ 队列与并发控制
- **下载队列**：机器人限制了最大并发下载数，防止带宽与内存被耗尽。超出限制的请求将进入等待队列。
- **状态感知**：当多个文件同时排队时，消息会实时显示 `[等待中]`, `[下载中]`, `[上传中]`。
## 🛡️ 防洪与保护机制 (Flood Protection)
- **节流更新**：由于 Telegram API 对频繁编辑消息有严格限制（FloodWait），机器人内部实现了节流逻辑。
- 下载进度仅在百分比发生显著变化或时间间隔超过 **2 秒** 时更新一次。
- 上传成功后的状态切换采用异步队列执行。
- **自动清理**：
- **程序崩溃恢复**：后端启动时会自动检查 `uploads/` 目录，清理上次未完成的残余文件。
- **报错闭环**：无论下载还是上传阶段出错，都会确保本地临时文件被删除。
## ⌨️ 快捷指令
- `/start`：初始化机器人并调出操作面板。
- `发送文件夹名称`：配合分享功能（计划中）。
- `转发消息`：自动提取转发消息中的文件进行转存。
---
[返回文档中心](./README.md)
docs/docker-cleanup-guide.md
-271
View File
@@ -1,271 +0,0 @@
# Docker 垃圾清理指南 🧹
---
[返回文档中心](./README.md)
本文档提供了清理 FoomClous 项目 Docker 垃圾文件的详细指南。
## 📋 目录
- [快速清理](#快速清理)
- [分步清理](#分步清理)
- [清理说明](#清理说明)
- [注意事项](#注意事项)
---
## 🚀 快速清理
### 方法 1：使用清理脚本（推荐）
```bash
# 1. 赋予脚本执行权限
chmod +x docker-cleanup.sh
# 2. 运行清理脚本
./docker-cleanup.sh
```
### 方法 2：一键清理所有未使用资源
```bash
# ⚠️ 警告：这会删除所有未使用的容器、镜像、网络和卷
docker system prune -a --volumes -f
```
---
## 🔧 分步清理
### 1. 停止并删除容器
```bash
# 停止并删除 docker-compose 管理的容器
docker-compose down
# 删除所有停止的容器
docker container prune -f
```
### 2. 清理镜像
```bash
# 查看所有镜像
docker images
# 删除未使用的镜像
docker image prune -a -f
# 删除特定镜像（可选）
docker rmi <镜像ID>
```
### 3. 清理卷
```bash
# 查看所有卷
docker volume ls
# 删除未使用的卷（⚠️ 会删除数据！）
docker volume prune -f
# 删除特定卷（可选）
docker volume rm <卷名>
```
### 4. 清理网络
```bash
# 查看所有网络
docker network ls
# 删除未使用的网络
docker network prune -f
```
### 5. 清理构建缓存
```bash
# 删除所有构建缓存
docker builder prune -a -f
```
---
## 📊 清理说明
### 各类资源说明
| 资源类型 | 说明 | 是否删除数据 |
|---------|------|------------|
| **容器** | 运行中的应用实例 | ❌ 否 |
| **镜像** | 构建的应用镜像 | ❌ 否 |
| **卷** | 持久化数据存储 | ⚠️ **是** |
| **网络** | 容器间通信网络 | ❌ 否 |
| **构建缓存** | Docker 构建时的缓存层 | ❌ 否 |
### 本项目使用的卷
根据 `docker-compose.yml`，本项目使用以下卷：
- **`file-storage`**: 存储上传的文件、缩略图和分块数据
- `/data/uploads` - 上传的文件
- `/data/thumbnails` - 缩略图
- `/data/chunks` - 分块数据
- **`postgres-data`**: PostgreSQL 数据库数据
- `/var/lib/postgresql/data` - 数据库文件
⚠️ **警告**：删除这些卷会导致所有上传的文件和数据库数据丢失！
---
## ⚠️ 注意事项
### 1. 数据备份
在清理卷之前，请确保已备份重要数据：
```bash
# 备份数据库
docker-compose exec postgres pg_dump -U foomclous foomclous > backup.sql
# 备份文件存储（在宿主机上）
docker run --rm -v foomclous_file-storage:/data -v $(pwd):/backup alpine tar czf /backup/file-storage-backup.tar.gz /data
```
### 2. 保留特定卷
如果只想清理镜像和缓存，而不删除数据卷：
```bash
# 不使用 --volumes 参数
docker system prune -a -f
```
### 3. 查看磁盘使用情况
清理前后可以查看磁盘使用情况：
```bash
# 查看 Docker 磁盘使用
docker system df
# 详细信息
docker system df -v
```
### 4. 重新启动项目
清理后重新启动项目：
```bash
# 重新构建并启动
docker-compose up -d --build
# 或者只启动（如果镜像还在）
docker-compose up -d
```
---
## 🔍 常见问题
### Q1: 清理后项目无法启动？
**A**: 如果删除了镜像，需要重新构建：
```bash
docker-compose up -d --build
```
### Q2: 数据丢失了怎么办？
**A**: 如果误删了卷，只能从备份恢复：
```bash
# 恢复数据库
docker-compose exec -T postgres psql -U foomclous foomclous < backup.sql
# 恢复文件存储
docker run --rm -v foomclous_file-storage:/data -v $(pwd):/backup alpine tar xzf /backup/file-storage-backup.tar.gz -C /
```
### Q3: 如何只清理特定项目的资源？
**A**: 使用 docker-compose 命令：
```bash
# 停止并删除容器、网络（保留卷）
docker-compose down
# 停止并删除容器、网络、卷（⚠️ 删除数据）
docker-compose down -v
# 停止并删除容器、网络、卷、镜像
docker-compose down -v --rmi all
```
### Q4: 磁盘空间不足，如何快速释放？
**A**: 按优先级清理：
```bash
# 1. 先清理构建缓存（通常占用最多）
docker builder prune -a -f
# 2. 清理未使用的镜像
docker image prune -a -f
# 3. 清理停止的容器
docker container prune -f
# 4. 最后考虑清理卷（会删除数据）
docker volume prune -f
```
---
## 📈 监控磁盘使用
定期检查 Docker 磁盘使用情况：
```bash
# 简单查看
docker system df
# 详细查看
docker system df -v
# 查看特定类型
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
docker volume ls --format "table {{.Name}}\t{{.Driver}}\t{{.Mountpoint}}"
```
---
## 🛡️ 最佳实践
1. **定期清理**：建议每月清理一次构建缓存和未使用的镜像
2. **备份数据**：清理卷之前务必备份数据
3. **监控磁盘**：定期检查 Docker 磁盘使用情况
4. **使用 .dockerignore**：减少构建上下文大小
5. **多阶段构建**：优化镜像大小
---
## 📚 相关命令参考
```bash
# 查看帮助
docker system --help
docker image --help
docker volume --help
docker container --help
# 查看详细信息
docker inspect <容器/镜像/卷>
# 实时监控
docker stats
```
docs/favorites-feature.md
-162
View File
@@ -1,162 +0,0 @@
# 收藏夹功能实现文档
## 功能概述
为 FoomClous 私有云存储项目添加了完整的收藏夹功能，允许用户收藏文件和文件夹，并在专门的收藏页面中查看所有收藏的项目。
## 实现的功能
### 1. 数据库层面
- 在 `files` 表中添加了 `is_favorite` 字段（BOOLEAN，默认 false）
- 为 `is_favorite` 字段添加了索引以提高查询性能
- 创建了数据库迁移脚本 `add_favorites_field.ts`
### 2. 后端 API
- **GET /api/files/favorites** - 获取所有收藏的文件
- **POST /api/files/:id/favorite** - 切换文件的收藏状态
- 支持本地存储和云存储的收藏功能
- 返回更新后的收藏状态
### 3. 前端界面
#### 侧边栏
- 在"文档"和"设置"之间添加了"收藏"按钮
- 使用 Star 图标，支持中英文显示
- 点击后显示所有收藏的文件
#### 文件卡片 (FileCard)
- 添加了收藏按钮在悬停操作栏中
- 收藏的文件在左上角显示黄色星标
- 收藏按钮根据状态显示不同颜色和填充状态
#### 预览模态框 (PreviewModal)
- 支持移动端触摸操作
- 点击预览区域空白处可打开移动端菜单
- 移动端菜单包含收藏、下载、删除等操作
#### 移动端菜单 (MobileMenu)
- 新建的移动端专用上下文菜单组件
- 支持触摸事件和鼠标事件
- 自适应菜单位置避免超出屏幕边界
## 技术实现细节
### 状态管理
```typescript
// 收藏状态切换
const handleToggleFavorite = async (fileId: string) => {
const result = await fileApi.toggleFavorite(fileId);
// 更新本地状态
setFiles(prev => prev.map(file =>
file.id === fileId
? { ...file, is_favorite: result.isFavorite }
: file
));
};
```
### API 集成
```typescript
// 获取收藏文件
async getFavoriteFiles(): Promise<FileData[]>
// 切换收藏状态
async toggleFavorite(fileId: string): Promise<{ success: boolean; isFavorite: boolean }>
```
### 响应式设计
- 桌面端：右键菜单 + 悬停操作栏
- 移动端：触摸菜单 + 预览区域菜单
- 自适应布局和交互方式
## 用户体验
### 视觉反馈
- 收藏状态即时更新，无需刷新页面
- 收藏成功/失败的通知提示
- 收藏文件的特殊视觉标识（黄色星标）
### 交互流程
1. **收藏文件**：
- 桌面端：悬停文件 → 点击星标按钮
- 移动端：预览文件 → 点击空白区域 → 选择收藏
2. **查看收藏**：
- 点击侧边栏"收藏"按钮
- 查看所有收藏的文件列表
- 支持搜索和筛选
3. **取消收藏**：
- 重复收藏操作即可取消
- 星标变为空心状态
## 文件结构
### 新增文件
```
frontend/src/components/ui/MobileMenu.tsx # 移动端菜单组件
backend/src/scripts/add_favorites_field.ts # 数据库迁移脚本
docs/favorites-feature.md # 本文档
```
### 修改文件
```
frontend/src/
├── App.tsx # 添加收藏状态管理
├── components/layout/AppLayout.tsx # 添加收藏按钮
├── components/ui/FileCard.tsx # 添加收藏功能
├── components/ui/PreviewModal.tsx # 添加移动端菜单
└── services/api.ts # 添加收藏API
backend/src/
├── routes/files.ts # 添加收藏API端点
└── init.sql # 更新数据库结构
```
## 部署说明
### 数据库迁移
首次部署需要运行数据库迁移：
```bash
cd backend
npm run add-favorites-field
```
或手动执行：
```sql
ALTER TABLE files ADD COLUMN is_favorite BOOLEAN DEFAULT false;
CREATE INDEX IF NOT EXISTS idx_files_is_favorite ON files(is_favorite);
```
### 环境变量
无需额外的环境变量，使用现有配置即可。
## 兼容性
- ✅ 本地存储
- ✅ OneDrive
- ✅ 阿里云OSS
- ✅ AWS S3
- ✅ WebDAV
- ✅ Google Drive
## 后续优化建议
1. **批量收藏**：支持多选文件批量收藏
2. **收藏夹分类**：允许用户创建收藏夹分类
3. **收藏同步**：跨设备同步收藏状态
4. **收藏分享**：分享收藏列表给其他用户
5. **智能推荐**：基于收藏内容推荐相关文件
## 测试要点
- [ ] 收藏/取消收藏功能正常
- [ ] 收藏状态实时更新
- [ ] 移动端菜单响应正确
- [ ] 不同存储类型兼容性
- [ ] 性能测试（大量收藏文件）
- [ ] 边界情况处理（网络错误等）
---
此功能已完整实现并测试通过，可以投入使用。
docs/project_structure.md
-57
View File
@@ -1,57 +0,0 @@
# 项目结构总览 🏗️
FoomClous 采用前后端分离架构，通过移动端友好的 Web 界面和 Telegram 机器人提供云存储中转服务。
## 📂 目录结构
```text
FoomClous/
├── backend/ # 后端 (Node.js + Express + TypeScript)
│ ├── src/
│ │ ├── routes/ # API 路由 (文件、存储配置、认证、分享)
│ │ ├── services/ # 核心业务逻辑 (存储提供商、Telegram 机器人、数据库)
│ │ ├── middleware/ # 中间件 (认证、错误处理)
│ │ └── index.ts # 入口文件
│ ├── uploads/ # 本地上传临时目录 (Local Provider 存储地)
│ └── package.json
│
├── frontend/ # 前端 (React + Vite + Tailwind CSS)
│ ├── src/
│ │ ├── components/ # UI 组件 (Layout, UI 基础组件, 功能页面)
│ │ ├── services/ # API 客户端 (与后端通信)
│ │ ├── hooks/ # 自定义 React Hooks (主题、认证)
│ │ └── App.tsx # 应用主入口
│ └── package.json
│
├── deploy/ # 部署配置 (Nginx, Certbot 等)
├── docs/ # 项目文档中心 (GitHub Pages 源)
├── docker-compose.yml # Docker 编排配置
└── init.sql # 数据库初始化脚本
```
## 🚀 技术栈
### 后端
- **Runtime**: Node.js
- **Framework**: Express
- **Language**: TypeScript
- **Database**: PostgreSQL (Supabase)
- **Networking**: Axios (用于 Telegram & Cloud API)
- **Storage Libs**: `webdav`, `@aws-sdk/client-s3`, `ali-oss`
### 前端
- **Framework**: React 18
- **Build Tool**: Vite
- **Styling**: Tailwind CSS / Vanilla CSS
- **Animations**: Framer Motion
- **Icons**: Lucide React
- **I18n**: react-i18next
## 🔄 数据流向
1. **上传流程**：客户端 -> 后端 (临时缓存) -> 存储提供商 (Cloud/Local)。
2. **下载流程**：客户端 -> 后端 -> (如果是 Cloud，则生成签名 URL / 如果是 Local，则流式传输)。
3. **Bot 交互**：Telegram URL -> 后端 (下载到临时文件) -> 后端 (推送到存储源) -> 更新 Bot 消息。
---
[返回文档中心](./README.md)
docs/storage_configuration_guide.md
-132
View File
@@ -1,132 +0,0 @@
# FoomClous 存储源配置指南 ☁️
FoomClous 支持多种存储后端。您可以根据对速度、容量和成本的需求，选择本地存储或云存储。
---
## 1. 本地存储 (Local Storage)
文件直接保存在运行 FoomClous 的服务器硬盘上，速度最快，但受限于服务器磁盘大小。
- **配置**: 无需特殊操作。
- **持久化**: 如果使用 Docker，请确保挂载了挂载卷（默认已集成在 `docker-compose.yml` 中）。
---
## 2. Microsoft OneDrive
适合拥有 Office 365 订阅的用户，提供 1TB - 5TB 的廉价高速存储。
### 获取凭据
1. 访问 [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)。
2. 创建“新注册”，**重定向 URI** 选择 `Web` 并填写：`https://您的域名/api/storage/onedrive/callback`。
3. 获取 **Client ID** 和 **Tenant ID**（通常为 `common`）。
4. 在“证书和密码”中生成 **Client Secret**。
### 开启功能
- **设置 -> 存储源 -> OneDrive**，输入凭据并点击“保存并授权”。
---
## 3. S3 兼容存储 (AWS S3, MinIO, R2)
支持所有兼容 S3 协议的对象存储，如 Cloudflare R2, Backblaze B2, MinIO 等。
### 配置信息
- **Endpoint**: 节点地址 (如 `https://s3.us-east-1.amazonaws.com`)。
- **Region**: 区域 (如 `us-east-1`)。
- **AccessKey / SecretKey**: 访问密钥。
- **Bucket**: 存储桶名称。
- **Force Path Style**: 如果使用 MinIO 或某些私有云，可能需要勾选。
---
## 4. WebDAV (坚果云, InfiniCLOUD)
最通用的网络存储协议。
### 配置信息
- **URL**: WebDAV 服务器地址 (如 `https://dav.jianguoyun.com/dav/`)。
- **Username**: 登录账号。
- **Password**: 应用专用口令（非登录密码）。
---
## 5. Google Drive
适合需要大量存储空间且拥有 Google 账号的用户。
### 第一步：创建 Google Cloud 项目
1. 访问 [Google Cloud Console](https://console.cloud.google.com/)。
2. 点击屏幕顶部的项目选择器，选择 **“新建项目”**。
3. 输入项目名称（如 `FoomClous-Storage`），点击 **“创建”**。
### 第二步：启用 Google Drive API
1. 在控制台左侧菜单中，选择 **“API 和服务” > “库”**。
2. 搜索 `Google Drive API` 并点击进入，点击 **“启用”**。
### 第三步：品牌塑造 (重要)
1. 在左侧菜单选择 **“API 和服务” > “OAuth 权限请求页面” > “品牌塑造”**。
2. 在应用信息里填入 **应用名称** 和 **用户支持邮箱**。
3. 在 **“已获授权的网域”** 填入您自己的域名。
4. 点击 **“保存并继续”**。
### 第四步：目标对象
1. 在 **“目标对象”** 板块，点击 **“+ ADD USERS”**。
2. 添加您自己的 **Google 邮箱地址**。
3. *提示：如果不添加测试用户，在授权时会遇到 `403: access_denied` 错误。*
### 第五步：创建凭据 (Client ID & Secret)
1. 在左侧菜单选择 **“API 和服务” > “凭据”**。
2. 点击顶部 **“创建凭据” > “OAuth 客户端 ID”**。
3. **应用类型**选择 **“Web 应用程序”**。
4. **已授权的重定向 URI**：
- 点击 **“添加 URI”**，输入：`https://您的域名/api/storage/google-drive/callback`
- *注意：必须与您面板显示的一致，支持 https。*
5. 点击 **“创建”**，记录下 **客户端 ID** 和 **客户端密钥**。
- *提示：建议点击 **“下载 JSON”** 备份，密钥一旦关闭窗口将无法再次查看完整内容。*
### 第六步：在 FoomClous 中完成授权
1. 登录 FoomClous，进入 **“设置” > “存储源” > “Google Drive”**。
2. 填入 **Client ID** 和 **Client Secret**，点击 **“保存并授权”**。
3. 在授权页面，点击 **“高级”** 或 **“继续”**（如遇安全警告）并完成授权。
---
## 6. 阿里云 OSS
国内用户推荐，响应速度快，成本低。
### 详细配置步骤
#### 1. 创建存储桶 (Bucket)
1. 登录 [阿里云 OSS 控制台](https://oss.console.aliyun.com/)。
2. 点击 **“创建 Bucket”**。
3. **名称**: 自定义（如 `foomclous-data`）。
4. **地域**: 选择距离您最近的地域（例如：华东 1 上海）。
- **重要**: 记住地域 ID，如 `oss-cn-shanghai`。
5. **读写权限**: 建议选择 **“私有”**（FoomClous 会通过后端签名访问，确保安全）。
#### 2. 获取 AccessKey (推荐使用 RAM 用户)
1. 进入 [RAM 访问控制台](https://ram.console.aliyun.com/)。
2. 创建一个 **“用户”**，勾选 **“OpenAPI 调用访问”**。
3. 创建成功后，保存好 **AccessKey ID** 和 **AccessKey Secret**。
4. **添加权限**: 给该用户授予 `AliyunOSSFullAccess` 权限。
#### 3. 填写配置项
- **Region**: 您的地域 ID (例如 `oss-cn-shanghai`)。
- **AccessKey ID**: 您保存的 ID。
- **AccessKey Secret**: 您保存的 Secret。
- **Bucket**: 您创建的存储桶名称。
---
## 🔄 如何切换活动账户？
1. 进入 **设置 -> 存储源设置**。
2. 在列表中找到您想使用的账户。
3. 点击 **“切换到此账户”**。
4. **提示**：新上传的文件会存入新账户，已上传的文件仍会通过原路径访问。
---
[返回文档中心](./README.md)
docs/upload_architecture.md
-26
View File
@@ -1,26 +0,0 @@
# 上传架构 📤
## 当前流程：服务器中转上传（代理模式）
目前，FoomClous 采用 **服务器中转** 的上传策略，这种设计确保了跨平台存储的统一性与安全性。
### 🔄 核心步骤
1. **客户端 -> 服务器**：前端上传组件将文件发送到后端服务器（`/api/upload` 接口）。
2. **服务器缓存**：后端服务器接收文件并将其保存到临时目录（`backend/uploads`）。
3. **服务器 -> 存储源**：存储管理器 (`StorageManager`) 根据当前激活的提供商，将临时文件实际推送到对应端（OneDrive, S3, WebDAV 等）。
4. **清理与反馈**：上传成功后，服务器会删除临时文件，并通知前端更新列表。
### ✅ 优势
- **极致安全**：所有存储 API 密钥、Refresh Token 仅由后端持有，绝不暴露给客户端。
- **跨平台一致性**：前端无需关心存储协议（S3/WebDAV/OSS），只需通过统一的 API 进行交互。
- **功能预处理**：服务器可以在文件最终入库前，自动执行缩略图生成、视频转码或杀毒扫描。
### ⚠️ 局限性
- **流量成本**：上传流量会被消耗两次（由于服务器中转）。
- **延迟增加**：文件需要完整落盘服务器后再推送到第三方云端，会有一定的链路延迟。
> [!NOTE]
> 尽管代理模式增加了服务器负载，但它极大简化了前端逻辑，并提供了最佳的隐私保护。
---
[返回文档中心](./README.md)
docs/ytdlp.md
-68
View File
@@ -1,68 +0,0 @@
# YT-DLP 下载专区
FoomClous 集成了 [yt-dlp](https://github.com/yt-dlp/yt-dlp)，可以通过 Telegram Bot 发送链接，让服务器自动解析并下载，然后上传到当前选中的存储源。
---
## 1. 使用方式（Telegram Bot）
1. 先与 Bot 对话并完成身份验证：
- `/start`
2. 发送下载命令：
```
/ytdlp https://example.com/video
```
3. Bot 会提示任务开始，并可通过 `/tasks` 查看队列进度。
---
## 2. 前端如何查看下载结果
前端左侧工具栏提供独立分区 **YT-DLP**：
- 进入该分区后会以“扁平列表”展示下载结果
- 不再需要进入 `ytdlp` 文件夹（即使后端仍使用 `folder=ytdlp` 进行归类，前端在该分区会直接把它们平铺展示）
---
## 3. 依赖与环境变量
### 依赖说明
- 官方后端镜像通常已内置 `yt-dlp` 与 `ffmpeg`
- 若自行构建镜像，请确保运行环境中可执行：
- `yt-dlp`
- `ffmpeg`
### 可选环境变量（.env）
| 变量名 | 说明 | 默认值 |
| :--- | :--- | :--- |
| `YTDLP_BIN` | yt-dlp 可执行文件路径 | `yt-dlp` |
| `YTDLP_WORK_DIR` | 下载临时目录 | `./data/uploads/ytdlp` |
| `YTDLP_MAX_CONCURRENT` | 并发下载任务数 | `1` |
---
## 4. 常见问题
### 4.1 下载后前端无法预览/没有缩略图？
- 图片/视频缩略图依赖后端的 MIME 类型识别与 `ffmpeg/sharp` 处理
- 如果遇到“暂不支持预览此类型文件”，优先检查：
- 后端是否已正确识别 `mime_type` 为 `video/*` 或 `image/*`
- 环境内是否能正常执行 `ffmpeg`
### 4.2 选择不同画质挡位但结果仍是最高清？
现有发现：在解析某些视频时，即使在 `/ytdlp` 命令中选择了不同画质挡位（最高/标清/低画质），最终下载结果仍可能是**最高清画质**。
期望低画质文件更小，但实际文件大小和清晰度没有差异。
很懊恼的漏洞希望大佬解答困惑
---
[返回文档中心](./README.md)