nccttc / FoomClous

FoomClous FoomClous 是一款高性能、极简主义的个人私有云存储解决方案。支持大文件切片上传、实时图片预览、视频流播放，并提供强大的 API 支持（如 Telegram Bot 集成）。 --- 🚀 快速部署 (Docker Compose) 这是最简单、最推荐的方式。 • 克隆仓库 • 配置环境变量 • 构建并启动 (⚠️ 重要) 由于 是**构建时**变量，你需要在构建前端镜像时指定你的 API 地址： > [!IMPORTANT] > 必须在 时通过 传入，运行时的 无法影响它。 --- 🛠️ 环境变量配置 在启动前，请确保设置好以下核心变量（建议放入 文件）： | 变量名 | 说明 | 示例 | | :--- | :--- | :--- | | | 前端访问后端的地址 (域名或 IP:端口) | | | | 数据库密码 | | | | 允许跨域的来源 | | | | 应用域名 | | | | (可选) 访问密码的 Hash | | | | (可选) Telegram Bot Token | | | | (可选) Telegram API ID | | | | (可选) Telegram API Hash | | --- 🤖 Telegram Bot 配置指南 集成 Telegram Bot 后，你可以通过聊天窗口直接上传文件、管理云端数据。 • 获取 Bot Token • 在 Telegram 中搜索 @BotFather 并开始对话。 • 发送 命令，按照提示为你的机器人起个名字。 • 成功后，BotFather 会发给你一串 (例如 )。 • 将此 Token 填入 的 。 • 获取 API ID 和 API Hash *如果你需要使用更高级的 TDLib 或特定接口功能，请按以下步骤操作：* • 访问 my.telegram.org 并登录你的 Telegram 账号。 • 进入 。 • 创建一个新的应用（App title 和 Short name 可随意填写）。 • 复制 和 。 • 分别填入 的 和 。 --- 🤖 Telegram Bot 可用命令 配置完成后，你可以向 Bot 发送以下命令： | 命令 | 描述 | | :--- | :--- | | | 验证身份并开始使用 Bot | | | 获取详细帮助信息与使用说明 | | | 配置或准备双重验证 (TOTP) | | | 查看当前服务器磁盘与存储统计 | | | 查看最近上传的文件列表 | | | 查看当前传输任务队列 (包含下载进度) | | | 删除指定文件 (支持 ID 前缀) | | | 解析视频链接并下载到存储源 (yt-dlp) | > [!TIP] > **多文件上传优化**: 当后台下载文件数量达到 **9** 个及以上时，Bot 会自动进入**静默模式**，在后台排队处理以避免刷屏，你可以随时使用 查看实时进度。 📥 视频下载命令 ( ) 通过集成 yt-dlp，你可以直接在 Telegram Bot 中发送视频链接，让服务器自动解析并下载到当前存储源。 **依赖说明**： • 官方后端镜像已内置 与 ，无需额外安装。 • 若自行构建镜像，请确保 Dockerfile 中已安装 可执行文件。 **环境变量**（ 可选）： | 变量名 | 说明 | 默认值 | | :--- | :--- | :--- | | | yt-dlp 可执行文件路径 | （使用系统 PATH） | | | 下载临时目录 | | | | 并发下载任务数 | | **使用方法**： • 在 Telegram 私聊中向 Bot 发送： • Bot 会回复“开始解析并下载…”表示任务已创建。 • 下载完成后自动上传到当前存储源，并回复： • ✅ 成功： • ❌ 失败： **注意事项**： • 仅支持单个链接，不支持播放列表。 • 需要已通过 验证身份。 • 链接必须以 或 开头。 • 下载后的文件会自动入库并生成缩略图，在前端 文件夹中可见。 --- 🔐 安全与访问控制 如果设置了 ，访问网页和 API 将需要输入密码。本应用目前使用 **SHA-256** 算法进行哈希。 > [!CAUTION] >注：因TGbot键盘只支持四位数字，所以密码长度限制为四位数字，且不能包含特殊字符，请在生成密码时注意。 如何生成密码哈希值？ 你可以使用以下任一简单命令生成（将 替换为你想设的密码）： Node.js (推荐，跨平台) 如果你已经安装了 Node.js，直接运行： Linux/macOS (Git Bash) PowerShell (Windows) 将生成的 64 位字符串填入 文件的 即可。 🔐 双重验证 (Two-Factor Authentication) FoomClous 已内置支持 TOTP 双重验证（如 Google Authenticator）。 • **Web 端**：在“个人设置”中通过扫码激活。 • **Telegram Bot**：发送 即可获取设置二维码，直接在对话框输入验证码即可激活。 • **安全性**：启用后，登录网页和使用 Bot 均需二次验证。 --- 🌐 反向代理建议 (Reverse Proxy) 如果你使用 Nginx 或 NPM 部署，请参考以下映射关系： | 访问域名 | 协议 | 转发至宿主机 IP:端口 | 说明 | | :--- | :--- | :--- | :--- | | | HTTPS | | **前端/网页入口** | | | HTTPS | | **后端/API 接口** | > [!CAUTION] > 开启 HTTPS 后， 中的所有 URL 必须以 开头，否则浏览器会拦截资源。 📦 Docker 镜像说明 > [!WARNING] > Docker Hub 上的公共前端镜像 ( ) 使用默认 API 地址编译。 > **生产环境请务必使用 自行构建前端镜像。** 后端镜像可以直接使用： • **后端 API:** • **数据库:** --- 🔄 维护与更新 • 更新项目 要获取最新功能的代码并更新服务器，请在项目目录下运行： • 清理 Docker 资源 频繁构建可能会占用较多磁盘空间，可以使用以下命令清理废弃的镜像、容器和网络： --- ✨ 功能特性 • 📦 **极速上传**: 支持大文件切片、断点续传。 • 🖼️ **智能预览**: 图片与视频自动生成缩略图（WebP）、视频实时流播放。 • 🤖 **Bot 友好**: 提供完善的外部 API，轻松集成 Telegram 等机器人。 • 🌍 **多语言**: 内置 i18n 系统，支持中英文切换。 • 🐳 **全容器化**: 一键水平扩展，部署极其简单。 --- 📂 项目结构 --- --- --- 📄 开源协议 基于 MIT License 开源。 --- 2026