1. 文件放在哪#

我把它和备份数据放在同一个文件夹，这样备份盘自己就是完整的（脚本 + 数据 + 清单）：

1
F:\电脑备份文件夹\CloudFlare-ImgBed\telegram\
2
  backup-imgbed.bat        ← 双击这个
3
  backup-imgbed.mjs        ← 主脚本
4
  backup-config.json       ← 配置（记住域名/用户名/备份目录，不含密码）
5
  backup-config.example.json
6
  备份说明.md              ← 随脚本附带的简版说明
7
  blog\   music\   ...     ← 备份出来的文件（与图床目录一致）
8
  _备份清单.jsonl
9
  _备份汇总.json
10
  _备份失败.txt
11
  _图床数据库备份.json

2. 双击运行#

双击 backup-imgbed.bat，依次回答：

1
想只备份某个目录吗？可以输入目录名，例如 涂装项目 （直接回车 = 备份全部文件）: ← 回车
2
管理员用户名（直接回车使用 admin）: ← 回车（或填你的用户名）
3
管理员密码: ← 输入密码（不显示字符，正常）

第一次运行会问域名和备份目录，之后会记住（不含密码），下次直接回车即可。

3. 开始前的自检信息#

下载开始前，它会先告诉你这次要处理多少文件：

1
图床文件清单读取完成，共 2908 条（来自数据库记录）
2
共 2908 个文件，合计约 4.7 GB（按上传时大小估算）
3
预计耗时约 6 分 27 秒（粗略估计，取决于网络与图床负载）

觉得不合适可以当场 Ctrl+C，什么都不会写坏。想只看规模不下载，加 --dry-run。

4. 运行中的进度#

1
[1234/2908] 42.4%  成功 1231 跳过 3 失败 0  480.2 MB  已用 2 分 41 秒  剩余约 3 分 38 秒  blog/article/p069_2.webp

剩余时间按”已用时间 ÷ 已完成数量”实时推算，跑一会儿就准了。

5. 跑完之后#

1
==================== 备份结束 ====================
2
文件总数   : 2908
3
  新下载   : 1791
4
  已存在跳过 : 1117
5
  失败     : 0
6
数据总量   : 4.70 GB
7
耗时       : 12 分 4 秒
8
备份目录   : F:\电脑备份文件夹\CloudFlare-ImgBed\telegram
9
文件清单   : _备份清单.jsonl
10
数据库备份 : _图床数据库备份.json（2908 条记录、4 项设置）
11
==================================================

有失败文件时，最后会多一行提示，并生成 _备份失败.txt。

目录结构#

1
F:\电脑备份文件夹\CloudFlare-ImgBed\telegram\
2
  blog\article\p069_2.webp        ← 和链接 /file/blog/article/p069_2.webp 一一对应
3
  blog\album\武侠风\11.webp
4
  music\...
5
  待上传\...

路径规则：图床里的文件夹 + 列表里显示的文件名。所以你在图床后台看到什么名字，备份下来就是什么名字。

四个清单文件#

_备份清单.jsonl 的字段（排查问题时常用）：

1
{
2
  "id": "blog/article/p069_2.webp",
3
  "fileName": "p069_2.webp",
4
  "directory": "blog/article/",
5
  "localPath": "blog/article/p069_2.webp",
6
  "bytes": 24040,
7
  "uploadedSizeBytes": 24040,
8
  "fileType": "image/webp",
9
  "channel": "TelegramNew",
10
  "tgFileId": "AgACAgUAAyEGAATr1aaP...",
11
  "status": "ok",
12
  "note": "文件名含 Windows 不允许的字符，已自动替换"
13
}

status 有三种：ok（本次下载）、skipped（已存在跳过）、failed（失败）。

配置文件#

backup-config.json（交互运行时自动生成，不写密码）：

1
{
2
  "baseUrl": "https://img.tsh520.cn",
3
  "username": "tianshihao2003",
4
  "password": "",
5
  "token": "",
6
  "outDir": "F:\\电脑备份文件夹\\CloudFlare-ImgBed\\telegram",
7
  "nameMode": "display",
8
  "concurrency": 3,
9
  "dir": "",
10
  "channel": "",
11
  "checksum": false
12
}

dir 为空 = 备份全部；填了目录名 = 只备份该目录。改这个文件即可调整默认行为。

1. 只读#

脚本只调用两个接口：

• GET /api/manage/batch/list —— 读数据库里的文件记录（清单来源）
• GET /file/<路径> —— 下载文件本体

不调用任何删除、重命名、移动接口，也不修改图床设置。跑一百次也不会把图床搞乱。

2. 下载顺序：先匿名，再管理员#

每个文件先按普通访客身份请求（能命中 Cloudflare 缓存，更快）；如果返回”访问受限”（文件被设为屏蔽、或图床开了白名单模式），自动改用管理员身份重新请求。所以被屏蔽的文件也能备份下来。

3. 断点续传的判定规则#

一个文件被跳过，需要同时满足：

1. _备份清单.jsonl 里上次记录的状态是成功/跳过
2. 本地文件还在
3. 本地文件的字节数与上次下载记录完全一致
4. 图床上那条记录没变（TG 文件 ID 和上传大小都没变）

只要有一条不满足就会重新下载并覆盖。所以：

• 删掉本地文件 → 会重新下
• 本地文件损坏、被改过 → 会重新下
• 图床上同一条路径重新上传过（内容变了）→ 会重新下
• 清单文件丢了 → 退化为按大小比对（可能与图床记录的大小有偏差，会重下一遍，之后恢复正常）

4. 不会留下半截文件#

每个文件先写成 xxx.part，下载完整（字节数与服务器声明一致）才改名为正式文件。断网、关机、Ctrl+C 都不会留下损坏的文件。失败时 .part 会被清理。

5. 清单文件不会无限膨胀#

运行中按行追加（保证中断也不丢进度），跑完会按记录去重重写一遍，永远保持”一个文件一行”。

6. Windows 相关的细节处理#

• 文件名里的 Windows 非法字符（<>:"/\|?*）自动替换为 _
• 结尾的点和空格自动去掉；CON、PRN 等保留名自动加前缀
• 超长文件名自动截断并加哈希后缀
• 路径超过 260 字符时自动加 \\?\ 前缀（Windows 长路径）

1. ⚠️ 图床的”索引”是不完整的，必须直接读数据库#

这是最坑的一个。图床后台的文件列表、搜索、目录树都依赖一个叫”索引”的东西，而索引可能只覆盖一部分文件。我的图床当时索引里只有 877 条记录，数据库里却有 2908 条——差了 2000 多个文件。

如果按索引备份，会静默漏掉 69% 的文件，而且看不出任何异常：清单读取成功、下载成功、汇总显示”全部完成”。

所以脚本现在直接读数据库记录（/api/manage/batch/list，也就是管理端”备份数据”按钮用的那个接口）。运行时你会看到：

1
图床文件清单读取完成，共 2908 条（来自数据库记录）

万一数据库接口读不到，会退回索引，并明确警告：

1
注意：这次用的是图床索引，而图床索引可能不完整（会漏掉文件）。
2
建议先到图床管理端执行一次「重建索引」，然后再跑备份。

建议：顺手在图床管理端点一次「重建索引」，否则网页端管理文件时也会漏（列表、搜索、目录树都会少文件）。

2. ⚠️ 在”只备份哪个目录”这一步输入的内容会被记住#

脚本会把这次的选择写进配置，下次作为默认值。好处是不用每次重输；坏处是输错了也会被记住，下次直接回车就只备份那个目录。

现在的处理：清单读取成功后才保存设置；如果那个目录下没找到任何文件，会明确提示并且不保存：

1
目录「xxx」下没有找到任何文件。
2
目录名要和图床里的文件夹名完全一致（区分大小写），比如 涂装项目；不确定就先直接回车备份全部。
3
本次不会保存设置，避免把输错的目录名记下来。

想改回备份全部：运行时在提示后输入一个 -，或把配置里的 dir 改成 ""。

3. 画质：备份到的是”图床现在能给你的那份”#

图床上传时，图片走的是 Telegram 的”发送图片”接口，会被 Telegram 压缩一次。所以备份下来的就是图床现在能提供的内容（和你从图片链接下载到的完全一样），已经被压掉的原始画质找不回来。

想保留原图，上传时要走”文件”方式（?serverCompress=false），这样 Telegram 会原样保存。

大文件（超过 16 MB）图床会切成 16 MB 分片存储，下载时图床自动拼回，不受 Telegram 机器人 20 MB 下载限制的影响。

4. 极少数老记录可能下不动#

• 早期（旧版 Telegram 渠道）上传的、单个文件超过 20 MB 的记录，Telegram 机器人接口不给下载，会记进失败清单
• 路径里含逗号的记录，图床的 /file/ 接口会把逗号当目录分隔符，无法定位，会直接记进失败清单（不会写错文件）

这两类都会出现在 _备份失败.txt 里并写明原因，不会静默跳过。

5. 同目录重名文件#

图床里同一个文件夹下可能有两条记录显示名相同（比如两个 小柠檬2.0.9.apk）。脚本会把其中一个自动改用内部路径名（带时间戳那种），避免互相覆盖，并在清单的 note 里注明。

6. 别把备份放在图床会读到的位置#

--out 指向的目录会被写入文件，如果恰好是图床的同步目录可能造成循环。放在独立的备份盘即可。

相关文章#

• CloudFlare-ImgBed 博客教程
• CloudFlare-ImgBed系列-WebDAV + WinSCP 本地备份教程
• CloudFlare-ImgBed系列-随机图 API 使用指南
• 记录博客文件的最佳存储方式