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

先看数据
| 项目 | 值 |
|---|---|
| 仓库 | 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、图片压缩裁剪、格式转换、防盗链、高可用——这些得自己在外面加。
安装部署
环境准备
- Node.js 20+;
- 一个 Telegram Bot(找 @BotFather 拿 Token);
- 一个专门存文件的 Telegram Channel,把 Bot 拉进去并给发布消息权限;
- 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 时按三条来:
/api/files/private-content/前缀 → 绕过缓存(Cloudflare 配Bypass cache);/api/files/content/<token>/(download|preview|thumbnail)→ 允许长期缓存(Cloudflare 配Eligible for cache,Edge TTL 可设一年);- 别覆盖应用返回的
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 条滚动加载,后端排序;
- 暗色模式、目录面包屑、加载骨架、空状态、失败重试。
图片上传后网格和列表视图懒加载缩略图,加载失败自动回退到文件图标。
常见坑与注意事项
ADMIN_TOKEN别留空。默认全员匿名可写,公网暴露就是给任何人开写权限。- 50 MiB / 20 MiB 是硬墙。别指望改环境变量突破,也别把它当大文件网盘。
- 数据库必须备份。SQLite 数据卷(Compose 方案下叫
tgfs_data,直接运行方案下叫mifun_storage_data)存着全部元数据和映射,丢了它,Telegram 里的文件等于失联。 - 别跑
docker compose down -v,会连数据卷一起删。 - 公共链接是 Bearer 凭证。拿到
contentToken链接的人都能读,包括隐藏位置的文件。 - 私有内容的 CDN 绕过规则要反复确认。共享缓存存了私有内容 = 鉴权失效。
- SQLite 只支持单实例,别让多个容器共享同一个 SQLite 文件;要多实例上 MySQL。
- Watchtower 慎开,挂载 Docker Socket 权限过高。
- Demo 站不保证稳定,作者已注明转到备用服务器、不为联通质量负责,别当生产依赖。
- 删除不彻底。逻辑删除 + 频道消息保留,需要彻底清理时得额外操作。
常见问题
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
有问题或想补充的,写在下面 · 选中正文文字再点「报告错误」会自动引用- 鸿
白嫖飞机资源