黑海洋 黑海洋 WIKI

米饭云盘(mifun-storage):把 Telegram 频道当硬盘,零成本自建个人图床

资源 · 约 20 分钟 · 黑海洋 · 4,343 · 1 条评论

摘要:米饭云盘是一个把文件二进制存在 Telegram Channel、本地只存元数据的轻量存储系统,主打个人图床 / Markdown 图床。上传下载全程走 Node.js Stream,不落临时文件,官方宣称"无限容量、不占本机与服务器空间"。本文梳理它的真实能力边界、50 MiB / 20 MiB 硬限制、Docker 部署、图床外链、缓存与鉴权配置,以及上手前必须知道的几个坑。

标签:自建图床 Telegram 对象存储 Docker Markdown图床 开源

建议 slug:mifun-storage-telegram-picture-bed

米饭云盘 Web 文件管理器界面:macOS 风格浅色窗口,左侧为存储位置与八色快捷标签,顶部有网格/列表切换、名称排序、管理员登录、暗色模式和搜索框,主区域以网格展示文件夹与文件,底部显示"已加载 13/13 个项目,共 18 MB"

先看数据

项目 值
仓库 AndySkaura/mifun-storage
Star / Fork 287 / 30
许可 MIT
主语言 TypeScript(后端 Fastify 5 + Prisma 6;GitHub 页面显示 HTML 是因 web/ 下含前端页面)
建库 / 最后推送 2026-07-27 / 2026-11-16
Node 要求 Node.js 20+
核心依赖 Fastify 5 · Prisma 6 · grammY 1.45(Telegram Bot)· SQLite / MySQL 8.x · Tailwind CSS · ECharts · sharp
在线 Demo p.kuraa.cc(作者标注为备用服务器,不为联通质量负责)
Docker 镜像 andyskaura/mifun-storage

项目 2026 年 7 月才建库,不到四个月攒到近 300 星,迭代活跃。这是新项目,生产环境用之前先把数据备份方案想清楚。

它到底解决了什么

自建图床的老问题:图存自己服务器,要买硬盘、要防丢、要扛流量。米饭云盘的思路是把这个负担整体外包给 Telegram:

  • 文件二进制只存 Telegram Channel,你的服务器不存一个字节的图片本体;
  • SQLite / MySQL 只存目录结构、文件元数据和 Telegram 映射(哪个文件对应哪条频道消息);
  • 上传下载用 Node.js Stream 边收边转,不写本地临时文件;
  • 对外暴露一个 Finder 风格的 Web 文件管理器,用起来像网盘。

结果就是:机器只要跑得住一个 Node 进程,容量随 Telegram 频道走。对个人博客、Markdown 笔记、论坛配图这类"文件多、单个小、访问量不高"的场景,这套模型很省事。

先泼一盆冷水:它不是完整网盘。没有多用户、没有分享系统、没有去重、没有细粒度权限体系。定位就是单人 / 小团队自用的低并发图床与小文件归档工具。

能力边界:这几条限制绕不过去

单文件大小是 Telegram Bot API 定的,不是本项目定的:

方向 上限 说明
上传 50 MiB 对应 MAX_UPLOAD_SIZE=52428800
下载 20 MiB 对应 MAX_DOWNLOAD_SIZE=20971520,超限返回 DOWNLOAD_FILE_TOO_LARGE

把环境变量调大没用,官方 Bot API 就是这条线。真要突破,得自己再部署一套 Telegram Bot API Server 并改造项目的 Telegram 接入层——成本和复杂度都上一个量级,作者明确说这不是项目初衷。环境变量只建议按实际需求调小。

另外几条要记牢:

  • "无限上传"指的是频道可持续存,不是承诺无限容量、无限可用性或服务等级;
  • 元数据(目录 / 标签 / 映射)依赖本地 SQLite 或 MySQL,这部分丢了文件就找不回来了,数据库必须备份;
  • 不适合高并发网盘、多人协作、频繁随机读写的对象存储场景。
  • 不提供 CDN、图片压缩裁剪、格式转换、防盗链、高可用——这些得自己在外面加。

安装部署

环境准备

  1. Node.js 20+;
  2. 一个 Telegram Bot(找 @BotFather 拿 Token);
  3. 一个专门存文件的 Telegram Channel,把 Bot 拉进去并给发布消息权限;
  4. Channel ID,形如 -1001234567890。

默认内置 SQLite,data/mifun-storage.db 自动建表,不用装数据库。要接已有 MySQL 8.x 时再配置 DATABASE_URL。

方式一:Docker Compose(推荐)

mkdir mifun-storage && cd mifun-storage
curl -O https://raw.githubusercontent.com/AndySkaura/mifun-storage/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/AndySkaura/mifun-storage/main/.env.example

编辑 .env,至少填这两项:

TELEGRAM_BOT_TOKEN=1234567890:你的真实token
TELEGRAM_STORAGE_CHAT_ID=-1001234567890

不用外部 MySQL 就保持 DATABASE_URL 留空。然后启动:

docker compose up -d
docker compose ps
docker compose logs -f tgfs

访问 http://localhost:3000。

日常运维命令:

# 重启 / 停止 / 启动
docker compose restart
docker compose stop
docker compose start

# 手动更新到最新版本
docker compose pull && docker compose up -d
docker image prune -f

# 删除容器和网络,但保留 SQLite 数据
docker compose down

docker compose down -v 千万别跑——-v 会连 SQLite 数据卷一起删掉。

Compose 里还带了一个可选的 Watchtower 自动更新配置,默认不启动。它要挂载 Docker Socket,等于把宿主机 Docker 管理权限交给容器,只适合可信镜像,不需要就别开:

docker compose --profile auto-update up -d

方式二:直接用 Docker 镜像

curl -o .env https://raw.githubusercontent.com/AndySkaura/mifun-storage/main/.env.example
# 填好 Telegram 配置后
docker run -d \
  --name mifun-storage \
  --restart unless-stopped \
  --env-file .env \
  -e HOST=0.0.0.0 \
  -v mifun_storage_data:/app/data \
  -p 3000:3000 \
  andyskaura/mifun-storage:latest

注意更新方式:docker restart 不会更新镜像,光 docker pull 也不会替换正在跑的容器。得停掉、删掉、再用新镜像重建。重建不会删 mifun_storage_data 卷。

方式三:源码本地运行

cp .env.example .env
# 编辑 .env,填 Telegram 配置
npm install
npm run dev          # 开发模式,默认 http://localhost:3000

生产模式:

npm run build
npm start

如果配了 MySQL,首次部署和每次 Schema 变更后都要跑一次迁移:

npm run prisma:deploy

关键环境变量

变量 默认值 作用
PORT / HOST 3000 / 0.0.0.0 监听地址
SITE_URL 空 生成 /about 页的 Canonical、OG、robots.txt、sitemap.xml 绝对地址
ABOUT_ENABLED true 设 false 关闭统计页与统计 API,并隐藏首页统计入口
DATABASE_URL 空 留空用 SQLite;MySQL 8.x 连接串
TELEGRAM_BOT_TOKEN 必填 Bot Token
TELEGRAM_STORAGE_CHAT_ID 必填 存储频道 ID
ADMIN_TOKEN 空 管理员凭证,留空 = 关闭鉴权(见下文安全提醒)
MAX_UPLOAD_SIZE 52428800 上传上限,只建议调小
MAX_DOWNLOAD_SIZE 20971520 下载上限,只建议调小

当作图床用:拿到长期稳定的外链

图片上传成功后,响应里有个 contentToken——这是该文件长期稳定的随机访问凭证。拼出图片地址:

https://你的域名/api/files/content/<contentToken>/preview

原图、缩略图、下载各有入口:

# 内联预览(图片可直接 <img> 引用)
curl http://localhost:3000/api/files/content/<contentToken>/preview

# JPEG 缩略图
curl -o thumbnail.jpg http://localhost:3000/api/files/content/<contentToken>/thumbnail

# 下载原图
curl -OJ http://localhost:3000/api/files/content/<contentToken>/download

contentToken 是 128 bit 随机生成的 22 位 Base64URL 字符串,不暴露递增文件 ID,方便配长期 CDN 缓存。Web 管理器里对图片双击可全屏预览、右键复制的就是这个公共链接。

上传本身也支持 API:

curl -X POST http://localhost:3000/api/files/upload \
  -F 'parentId=1' \
  -F 'file=@./example.png'

想保持真正的流式上传,multipart 字段按 parentId → 可选 thumbnail → file 顺序发。缩略图必须是 < 200 KiB、最大边 ≤ 320px 的 JPEG。网页端上传图片时浏览器会自动生成缩略图一起存进 Telegram。

缓存与 CDN:一条配错就出安全事故

这是整套系统里最需要认真对待的部分。公共内容和私有内容必须走两套规则:

内容类型 路径前缀 缓存策略
公共内容 /api/files/content/... 可长期缓存;撤销链接时要主动 purge
私有内容 /api/files/private-content/... 禁止共享缓存,且必须转发 Authorization 头

Nginx 参考配置:

# 私有内容:保留鉴权头,禁用共享缓存
location ^~ /api/files/private-content/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header Authorization $http_authorization;
    proxy_cache off;
}

# 公共内容:由应用返回长期缓存响应头
location ~ ^/api/files/content/[A-Za-z0-9_-]+/(download|preview|thumbnail)$ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
}

用 CDN 时按三条来:

  1. /api/files/private-content/ 前缀 → 绕过缓存(Cloudflare 配 Bypass cache);
  2. /api/files/content/<token>/(download|preview|thumbnail) → 允许长期缓存(Cloudflare 配 Eligible for cache,Edge TTL 可设一年);
  3. 别覆盖应用返回的 private、no-store、Vary: Authorization 响应头。

私有内容响应带 Cache-Control: private, max-age=31536000, immutable(允许浏览器本地长期保存)和 Cloudflare-CDN-Cache-Control: no-store(禁止 CDN 缓存)。私有链接一旦被共享缓存记住,等于鉴权形同虚设。

管理员鉴权与存储位置

管理员 Token

ADMIN_TOKEN 留空 = 关闭鉴权,所有人匿名可写。生产环境务必设置:

openssl rand -hex 32

配置后,删除项目、管理存储位置属于管理员操作,请求头带:

Authorization: Bearer <ADMIN_TOKEN>

上传、建文件夹、复制粘贴允许匿名。Web 管理器右上角"管理员登录"验证成功后,Token 只存在当前标签页的 sessionStorage,关标签页即失效。别把 Token 塞进 URL 或下载链接。

存储位置

存储位置是相互独立的一级空间,类似多个磁盘分区,迁移时会建默认的 mifun-storage 并把已有文件归入其中。管理员可为每个位置设置匿名权限:

  • hidden:无密码时匿名用户不可见;设密码后显示锁定状态,解锁可读;
  • read:匿名可浏览、搜索、预览、下载、按标签筛选,不能写入;
  • write:匿名还能上传、建文件夹、粘贴、改标签。

几点细节:

  • 密码用带随机盐的 scrypt 哈希存储,接口只返回 hasPassword;
  • 解锁令牌只存当前标签页 sessionStorage,改密码会立即使旧令牌失效;
  • 删除存储位置不递归删内容,只有空位置才允许删除;
  • 切到 hidden 会清掉已有密码。

公共 contentToken 链接不受存储位置密码保护:任何拿到链接的人都能读到对应文件,包括 hidden 位置里的。把它当成"持有即授权"的 Bearer 凭证对待。删除文件或从页面移除链接,不会自动清除 CDN 已缓存的响应,要立即失效得同时 purge CDN URL。

API 速查

所有 ID 和文件大小都以字符串返回,避免 JavaScript 处理 MySQL BIGINT 时精度丢失。

功能 方法与路径
健康检查 GET /health
创建目录 POST /api/files/folder {"name":"docs","parentId":null}
根目录列表 GET /api/files
子目录列表 GET /api/files?parentId=1
全局搜索 GET /api/files/search?q=关键词
单个条目 GET /api/files/:id
上传 POST /api/files/upload(multipart)
下载 / 预览 / 缩略图 GET /api/files/content/<token>/{download,preview,thumbnail}
私有内容 GET /api/files/private-content/<token>?m=p(需 Bearer Token)
逻辑删除 DELETE /api/files/:id
复制 POST /api/files/:id/copy {"parentId":1}
标签 GET /api/tags、PUT /api/files/:id/tags、GET /api/files/by-tag/:tag
存储位置 GET/POST/PATCH/DELETE /api/storage-locations[...]

列表 / 搜索 / 标签筛选都支持分页排序:offset(默认 0)、limit(默认 50,最大 100)、sortBy(name/updatedAt/size)、sortOrder(asc/desc)。响应带 pagination 字段。

删除是逻辑删除:只写 files.deleted_at,不删 Telegram 频道里的消息,也不删 telegram_files 映射。想真正清理频道得手动处理。

复制几乎零成本:文件复制只新建一条虚拟文件记录,复用原有的 Telegram chat_id/message_id/file_id,不调用 Telegram API、不产生新频道消息。文件夹会递归复制,但不能粘到自己或自己的子目录里;复制出来的项目不继承标签。

Web 文件管理器

根目录 / 就是 Finder 风格管理器,功能相当全:

  • 双击打开文件夹 / 下载文件,双击图片站内全屏预览;
  • 拖拽框选、⌘/Ctrl+点击 多选、Shift+点击 范围选择;
  • 多选后可直接把文件流式写入本地目录,不走浏览器下载管理器;
  • 右键新建文件夹、复制、粘贴、上传、移到废纸篓;
  • 八色标签(红橙黄绿蓝紫粉灰)+ 侧边栏筛选;
  • 快捷键 ⌘C / ⌘V / ⇧⌘C(复制下载链接)/ ⇧⌘N / ⌘U;
  • 拖入本地文件直接上传,显示按大小加权的总进度和每个文件的分阶段状态;
  • 300ms 防抖的后端全局搜索,列表每页 50 条滚动加载,后端排序;
  • 暗色模式、目录面包屑、加载骨架、空状态、失败重试。

图片上传后网格和列表视图懒加载缩略图,加载失败自动回退到文件图标。

常见坑与注意事项

  1. ADMIN_TOKEN 别留空。默认全员匿名可写,公网暴露就是给任何人开写权限。
  2. 50 MiB / 20 MiB 是硬墙。别指望改环境变量突破,也别把它当大文件网盘。
  3. 数据库必须备份。SQLite 数据卷(Compose 方案下叫 tgfs_data,直接运行方案下叫 mifun_storage_data)存着全部元数据和映射,丢了它,Telegram 里的文件等于失联。
  4. 别跑 docker compose down -v,会连数据卷一起删。
  5. 公共链接是 Bearer 凭证。拿到 contentToken 链接的人都能读,包括隐藏位置的文件。
  6. 私有内容的 CDN 绕过规则要反复确认。共享缓存存了私有内容 = 鉴权失效。
  7. SQLite 只支持单实例,别让多个容器共享同一个 SQLite 文件;要多实例上 MySQL。
  8. Watchtower 慎开,挂载 Docker Socket 权限过高。
  9. Demo 站不保证稳定,作者已注明转到备用服务器、不为联通质量负责,别当生产依赖。
  10. 删除不彻底。逻辑删除 + 频道消息保留,需要彻底清理时得额外操作。

常见问题

Q:真的"无限容量"吗? A:不是字面意义的无限。文件存 Telegram 频道,容量取决于频道和账号的实际状况,单个文件还卡在 50 MiB / 20 MiB。项目文档自己也在 FAQ 里澄清了这一点。

Q:服务器需要多大硬盘? A:几乎不占。只存 SQLite / MySQL 元数据,图片本体全在 Telegram。

Q:能当公共图床给很多人用吗? A:不建议。没有 CDN、防盗链、高可用和限流,定位是个人或小团队低并发自用。流量大了自己在外面套 CDN。

Q:图片链接会失效吗? A:contentToken 是长期稳定的。但如果对应 Telegram 消息被删、频道出问题,或数据库映射丢了,链接就废了。撤销链接后记得 purge CDN。

Q:支持 OCIR / 图床快捷上传工具吗? A:项目提供标准 HTTP 上传 API(POST /api/files/upload),支持 multipart。能否对接第三方工具取决于那款工具是否支持自定义上传接口,项目本身没做专门适配。

Q:许可证允许商用吗? A:MIT,允许商用和二次开发,需保留版权与许可声明。

小结

米饭云盘把"自建图床"里最重的两块——存储和流量——甩给 Telegram,自己只做一个轻量的元数据 + 流式转发层。这个取舍很聪明:部署极轻、单个文件不占本地磁盘、图床外链稳定且适合 CDN 缓存。适合博客配图、笔记外链、截图归档这类低并发小文件场景。

代价是能力边界清晰:文件大小卡死、没有多用户和完整权限、CDN 缓存规则配错会出安全问题、元数据备份是自己的事。把它当"个人图床 + 小文件归档工具"用,别当全能网盘,这套方案就值。

项目地址:https://github.com/AndySkaura/mifun-storage 在线 Demo:https://p.kuraa.cc

相关文档

评论与补充1

有问题或想补充的,写在下面 · 选中正文文字再点「报告错误」会自动引用
  • 鸿
    鸿蒙#1Chrome 148 · Windows 10/11
    白嫖飞机资源
就事论事,别发广告 · 正常评论