FoomClous
FoomClous 是一款高性能、极简主义的个人私有云存储解决方案。支持大文件切片上传、实时图片预览、视频流播放，并提供强大的 API 支持（如 Telegram Bot 集成）。
🚀 快速部署 (Docker Compose)
这是最简单、最推荐的方式。
1. 克隆仓库
git clone https://github.com/nccttc/foomclous.git
cd foomclous
2. 配置环境变量
cp .env.example .env
vi .env # 修改 DB_PASSWORD, CORS_ORIGIN 等
也可进入服务器 /root/foomclous 目录下修改 .env 文件
3. 构建并启动 (⚠️ 重要)
由于 VITE_API_URL 是构建时变量，你需要在构建前端镜像时指定你的 API 地址：
# 构建前端 (将 YOUR_API_URL 替换为你的实际地址)
docker build --build-arg VITE_API_URL=https://your-api.example.com -t foomclous-frontend ./frontend
# 构建后端
docker build -t foomclous-backend ./backend
# 启动服务
docker compose -f docker-compose.prod.yml up -d
Important
VITE_API_URL必须在docker build时通过--build-arg传入，运行时的.env无法影响它。
🛠️ 环境变量配置
在启动前，请确保设置好以下核心变量（建议放入 .env 文件）：
| 变量名 | 说明 | 示例 |
|---|---|---|
VITE_API_URL |
前端访问后端的地址 (域名或 IP:端口) | https://api.yourdomain.com |
DB_PASSWORD |
数据库密码 | mypassword123 |
CORS_ORIGIN |
允许跨域的来源 | https://cloud.yourdomain.com |
DOMAIN |
应用域名 | yourdomain.com |
ACCESS_PASSWORD_HASH |
(可选) 访问密码的 Hash | sha256_hash_here... |
TELEGRAM_BOT_TOKEN |
(可选) Telegram Bot Token | 123456:ABC-DEF... |
TELEGRAM_API_ID |
(可选) Telegram API ID | 123456 |
TELEGRAM_API_HASH |
(可选) Telegram API Hash | abcdef123456... |
🤖 Telegram Bot 配置指南
集成 Telegram Bot 后，你可以通过聊天窗口直接上传文件、管理云端数据。
1. 获取 Bot Token (必选)
- 在 Telegram 中搜索 @BotFather 并开始对话。
- 发送
/newbot命令，按照提示为你的机器人起个名字。 - 成功后，BotFather 会发给你一串
HTTP API TOKEN(例如123456:ABC-DEF...)。 - 将此 Token 填入
.env的TELEGRAM_BOT_TOKEN。
2. 获取 API ID 和 API Hash (可选，增强功能)
如果你需要使用更高级的 TDLib 或特定接口功能，请按以下步骤操作：
- 访问 my.telegram.org 并登录你的 Telegram 账号。
- 进入
API development tools。 - 创建一个新的应用（App title 和 Short name 可随意填写）。
- 复制
App api_id和App api_hash。 - 分别填入
.env的TELEGRAM_API_ID和TELEGRAM_API_HASH。
🤖 Telegram Bot 可用命令
配置完成后，你可以向 Bot 发送以下命令：
| 命令 | 描述 |
|---|---|
/start |
验证身份并开始使用 Bot |
/help |
获取帮助信息与使用说明 |
/storage |
查看当前存储空间统计 |
/list |
查看最近上传的文件列表 |
/tasks |
查看当前任务队列状态 (包含下载进度、历史记录) |
/delete <文件名> |
删除指定文件 (需完全匹配文件名) |
Tip
多文件上传优化: 当一次性转发超过 9 个文件时，Bot 会自动进入静默模式，在后台排队处理以避免刷屏，你可以随时使用
/tasks查看实时进度。
🔐 安全与访问控制
如果设置了 ACCESS_PASSWORD_HASH，访问网页和 API 将需要输入密码。本应用目前使用 SHA-256 算法进行哈希。
Caution
注：因TGbot键盘只支持四位数字，所以密码长度限制为四位数字，且不能包含特殊字符，请在生成密码时注意。
如何生成密码哈希值？
你可以使用以下任一简单命令生成（将 your_password 替换为你想设的密码）：
Node.js (推荐，跨平台)
如果你已经安装了 Node.js，直接运行：
node -e "console.log(require('crypto').createHash('sha256').update('your_password').digest('hex'))"
Linux/macOS (Git Bash)
echo -n "your_password" | sha256sum | awk '{print $1}'
PowerShell (Windows)
[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes("your_password"))).Replace("-", "").ToLower()
将生成的 64 位字符串填入 .env 文件的 ACCESS_PASSWORD_HASH 即可。
🌐 反向代理建议 (Reverse Proxy)
如果你使用 Nginx 或 NPM 部署，请参考以下映射关系：
| 访问域名 | 协议 | 转发至宿主机 IP:端口 | 说明 |
|---|---|---|---|
cloud.example.com |
HTTPS | 127.0.0.1:47832 |
前端/网页入口 |
api.example.com |
HTTPS | 127.0.0.1:51947 |
后端/API 接口 |
Caution
开启 HTTPS 后，
.env中的所有 URL 必须以https://开头，否则浏览器会拦截资源。
📦 Docker 镜像说明
Warning
Docker Hub 上的公共前端镜像 (
cxaryoro/foomclous-frontend) 使用默认 API 地址编译。 生产环境请务必使用--build-arg VITE_API_URL=...自行构建前端镜像。
后端镜像可以直接使用：
- 后端 API:
cxaryoro/foomclous-backend:latest - 数据库:
postgres:16-alpine
🔄 维护与更新
1. 更新项目
要获取最新功能的代码并更新服务器，请在项目目录下运行：
# 进入项目目录
cd /root/foomclous
# 拉取最新代码
git pull origin main
# 重新构建并启动（自动应用改动）
docker compose up -d --build
2. 清理 Docker 资源
频繁构建可能会占用较多磁盘空间，可以使用以下命令清理废弃的镜像、容器和网络：
docker system prune -f
✨ 功能特性
- 📦 极速上传: 支持大文件切片、断点续传。
- 🖼️ 智能预览: 图片与视频自动生成缩略图（WebP）、视频实时流播放。
- 🤖 Bot 友好: 提供完善的外部 API，轻松集成 Telegram 等机器人。
- 🌍 多语言: 内置 i18n 系统，支持中英文切换。
- 🐳 全容器化: 一键水平扩展，部署极其简单。
📂 项目结构
FoomClous/
├── frontend/ # React 网页前端
├── backend/ # Node.js API 服务
├── init.sql # 数据库初始化脚本
└── docker-compose.prod.yml # 生产环境部署配置
📄 开源协议
基于 MIT License 开源。