个人数字漫画库搭建：CBZ命名、ComicInfo元数据与Docker服务端

1. 先想清楚：个人数字漫画库到底该建成什么样

做个人数字漫画库这件事，我前后折腾了差不多三年，从最早的“一个文件夹塞满 zip 就算完事”，到后来被乱码、封面错位、章节顺序乱掉折磨得不行，再到现在这套跑了一年多基本不用管的方案，中间踩的坑够写半本笔记。这篇就按我自己的实际做法，把个人数字漫画库从规划、命名规范、归档流水线到服务端部署、长期维护整条链路讲透。你如果是刚入门的小白，照着目录结构和命名规则先跑通最小闭环就行；如果你已经有一堆散乱文件、正在找一套能长期维护的整理方式，可以直接跳到第 2、3 节看具体模板和脚本。

先把范围说清楚，避免误会：这里讲的“下载器”指的是把你本机上已经拥有的、来源合法的漫画文件（自己购买后导出的、作者公开授权的、公有领域作品等）整理成结构化数字漫画库，不是去破解谁的付费内容，也不涉及绕过任何平台限制。这一条是底线，也是这套方案能长期活下去的前提——一个靠在灰色地带打游击的库，架构做得再漂亮也没有意义。所以下文所有技术点都围绕“本地文件治理”展开：目录怎么分层、元数据怎么写、压缩包怎么打、服务端怎么扫、备份怎么做。

1.1 三个几乎人人都会踩的误区

第一个误区是把“能看”当成“能维护”。很多人一开始就是把文件往一个目录里一扔，阅读器直接读文件夹，短期确实爽，几百个文件之后开始崩：同一部作品多个版本混在一起、章节号有的写 01 有的写 1 有的写“第1话”、封面图被当成正文页排在第一章。等到上千个文件时，你想重命名都不敢动，因为阅读器的阅读进度是按文件路径记的，一动全丢。

第二个误区是迷信“全自动抓取”。市面上各种所谓一键抓取工具，最大的问题不是抓不到，而是抓完之后文件结构一塌糊涂，还夹带一堆重复条目。我自己的经验是：抓取环节越“聪明”，后面清洗的成本越高。真正省时间的做法是把规范定死，让所有环节都往规范上靠，而不是让工具自由发挥。

第三个误区是容量规划想当然。一卷漫画打成 CBZ 之后，普通清晰度大概 40–120 MB，高清版本能到 200–400 MB。你以为 2TB 硬盘够用，实际上按 500 部、每部 15 卷、每卷 80 MB 算，已经接近 600 GB，加上重复版本、未整理缓存、缩略图，实际占用往往要到估算值的 1.5 倍。后面扩容涉及 raid、迁移、重新索引，都是麻烦事，一开始就该把余量留出来。

1.2 方案选型：文件夹、压缩包还是服务端

这三种形态我全用过，下面这张表是我用血泪换来的对比，建议你直接按自己的规模对号入座。

我最终的结论是混合方案：磁盘上以 CBZ 作为存储单元，目录里放ComicInfo.xml作为元数据，再挂一个轻量服务端做索引和阅读入口。好处是即使服务端哪天挂了，你的文件本身是完全自解释的——换个阅读器、换台机器，扫一遍照样能用。这一点非常重要，任何依赖单一软件私有数据库的方案，我都不建议作为唯一真相来源。

1.3 一个容易被忽略的前置决定：清晰度分级

我强烈建议你在动手整理前，先定下清晰度分级策略，否则后面一定会出现同一部作品三个版本、占了三份空间的局面。我的做法是：

• archive 层：只保留一套你认定的最佳版本，长期不动，作为冷备份。
• working 层：日常阅读用的版本，允许压到原分辨率的 70% 左右，肉眼几乎无差。
• thumb 层：只存封面和缩略图，供书架页快速加载。

分级之后，磁盘占用能压下来三成以上，而且扫描索引的速度会明显变快，因为服务端只需要读 working 层。这个决定越早做越省事，等库建到一半再改，等于把已有文件全部重跑一遍流水线。

2. 目录与命名：让库能被机器读懂的地基

这一节是全篇最无聊但最值钱的部分。我见过太多人卡在“章节顺序乱”这个坑里，其实根因只有一个：目录和文件名没有统一规则，导致排序退化成字符串比较，10排在2前面。把地基打好，后面所有环节都省力。

2.1 一套能长期用的目录模板

我的目录分三层，作者/作品/卷，不按年份也不按题材分层，因为题材是多元的（一部作品可以既算悬疑又算科幻），而作者相对稳定。具体长这样：

/comics ├── archive/ # 冷备份层，不参与日常扫描 │ └── <作者名>/<作品名>/<作品名> - v001.cbz ├── library/ # 主力库，服务端只扫这里 │ └── <作者名>/ │ └── <作品名>/ │ ├── ComicInfo.xml # 作品级元数据（可选） │ ├── cover.jpg │ ├── <作品名> - v001.cbz │ └── <作品名> - v002.cbz ├── thumbs/ # 生成的缩略图缓存 └── inbox/ # 待整理区，放新来的散文件

几个关键设计意图解释一下。inbox单独放是有必要的：新下载或新导出的文件先丢进去，跑完流水线才进library，这样主力库永远处于“干净状态”，服务端扫描不会因为半个残包而报错。archive与library分离，则是为了让备份策略可以差异化——archive 层一个月同步一次就够，library 层可以每天增量。

thumbs独立目录而不是塞进作品目录，是为了避免服务端扫描时把缓存图误当成漫画页。这个坑我踩过，某个阅读器把cover.jpg当成了第一章的第一页，导致每部作品点进去第一张永远是封面，看着极其别扭。

2.2 命名规则与字符处理

命名规则我定了四条，简单粗暴但有效：

1. 卷号一律三位数字补零，v001、v012，超过 999 卷用四位，全库统一，不许混。
2. 作品名里禁止出现\ / : * ? " < > |以及换行，遇到就替换成中划线。
3. 空格统一成半角空格，全角括号统一成半角，避免同作品出现两种写法被识别成两部。
4. 不在文件名里写作者和题材，那些交给元数据和目录层级，文件名只保留“作品名 + 卷号”。

关于第 3 条，我吃过一次很隐蔽的亏：某部作品有一半文件是全角括号（，另一半是半角(，服务端匹配算法直接把同一部作品拆成了两个条目，封面墙上出现两个一模一样的封面。排查了半小时才发现是一个字符的差别。后来我写了个校验脚本，扫全库做 Unicode 归一化（NFKC），把全角字母数字标点统一成半角，问题再没复发。

字符处理这块还有一个细节值得单独提：中文名建议直接保留中文，不要强行转拼音。早期我为了“跨平台安全”把作者名全转成拼音，结果自己都认不出来，也没法跟元数据里的原名对上。现在主流文件系统对 UTF-8 支持都没问题，保留原文反而最稳。

2.3 元数据文件怎么写才不白写

压缩包本身不带结构化信息，所以每卷旁边放一个ComicInfo.xml是性价比最高的做法——它是通用格式，绝大多数阅读器和服务端都认。最小可用版本长这样：

<?xml version="1.0" encoding="utf-8"?> <ComicInfo> <Series>示例作品名</Series> <Number>3</Number> <Volume>3</Volume> <Title>第三卷</Title> <Writer>示例作者</Writer> <Publisher>示例出版方</Publisher> <Genre>悬疑,科幻</Genre> <LanguageISO>zh</LanguageISO> <PageCount>186</PageCount> <Summary>这里是简介，一两句话即可。</Summary> </ComicInfo>

这里最容易出错的是<Number>和<Volume>。有些阅读器读 Number 排序，有些读 Volume，还有的把两者拼起来。我的经验是两个字段填同一个值，且必须是纯数字，不要写“第3话”“Vol.3”这类混合文本，否则排序必乱。至于<PageCount>，填错的影响比你想的大：部分服务端会拿它校验文件完整性，写错了会被判定为“损坏条目”直接跳过，非常难排查。

注意：ComicInfo.xml放在压缩包外部和放进压缩包内部都可以，但同一部作品不要两种方式混用。我的做法是统一放外部，因为改起来不用重打包，代价是目录里多一层文件——这个取舍我认为完全值得。

3. 归档流水线：把散乱文件变成标准条目

有了目录和命名规则，接下来就是把inbox里的散文件加工成标准条目。这一步我用一个 Python 脚本串起来，逻辑不复杂但细节很多。下面按环节讲。

3.1 批量打包与环境准备

先讲依赖。打包用标准库zipfile就够，不需要额外装东西；图片处理用 Pillow 生成封面和缩略图；校验用hashlib。整个环境一条命令搞定：

python3 -m venv venv source venv/bin/activate pip install pillow

打包的核心注意事项有三个。第一，压缩包里第一层直接是图片，不要再套一层目录。有些工具会把整个文件夹塞进去，结果阅读器打开后显示一个空目录，用户以为文件坏了。第二，图片排序必须按自然序而不是字典序，否则第 2 页会排到第 10 页后面，这个错误极其常见。第三，不要存储绝对路径，否则解压出来会带一长串目录层级。

下面这段是我实际在用的打包函数，做了自然序排序和路径扁平化：

import re import zipfile from pathlib import Path IMG_EXT = {".jpg", ".jpeg", ".png", ".webp"} def natural_key(name: str): # 把文件名切成"文本/数字"片段，数字按数值比较 return [int(t) if t.isdigit() else t.lower() for t in re.split(r"(\d+)", name)] def pack_volume(src_dir: Path, out_file: Path): pages = [p for p in src_dir.iterdir() if p.suffix.lower() in IMG_EXT] if not pages: raise ValueError(f"目录内没有图片: {src_dir}") pages.sort(key=lambda p: natural_key(p.name)) with zipfile.ZipFile(out_file, "w", zipfile.ZIP_DEFLATED) as zf: for idx, page in enumerate(pages, start=1): # 重命名为 001.jpg 这种纯数字序，彻底摆脱原文件名 arcname = f"{idx:03d}{page.suffix.lower()}" zf.write(page, arcname=arcname)

用纯数字重命名是一个我强烈推荐的做法：原文件名经常带作者、站点前缀、看似随机的一串字符，留着只会干扰阅读器和人工排查。打包时统一改成001.jpg这种序，排序问题从这个环节就彻底消灭了。

批量处理时我还加了两个保护：inbox里的目录处理完就移到_done子目录而不是删除，出了问题时还能回滚；打包前先检查目标文件是否存在，存在就跳过，这样整个脚本可以反复跑而不会重复劳动，也就是常说的幂等。

3.2 封面抽取与缩略图

封面选取有个小技巧：从第 3–8 页里挑一张，而不是第 1 页。第 1 页通常是扉页或者版式信息，当封面用很难看。如果你有作品级的cover.jpg就优先用它，没有就用启发式挑一张。

from PIL import Image def make_thumb(src: Path, dst: Path, width: int = 400): with Image.open(src) as im: im = im.convert("RGB") ratio = width / im.width size = (width, max(1, int(im.height * ratio))) im.resize(size, Image.LANCZOS).save(dst, "JPEG", quality=85)

缩略图宽度我定在 400px。为什么不是更小？因为书架页封面卡片常见的显示宽度在 180–260px，考虑到高分屏 2 倍缩放，400px 是甜点值，再小就发虚，再大是浪费。质量参数 85 也是一个经验值，往下压到 70 会出现明显色带，往上到 95 文件体积翻倍但肉眼无感。

提示：缩略图生成这一步建议单独跑，不要在打包主流程里做。因为缩略图是“可重建”的缓存，打包是“一次性”的加工，混在一起会让主流程变慢，一旦缩略图出错还要连带重打包。

3.3 校验、去重与断点续传

去重我用的不是文件名比对，而是内容哈希。原因很现实：同一卷经常有多个来源，文件名完全不同，只有内容能说明它们是不是同一个东西。

import hashlib def file_sha1(path: Path, chunk: int = 1 << 20) -> str: h = hashlib.sha1() with path.open("rb") as f: while True: block = f.read(chunk) if not block: break h.update(block) return h.hexdigest()

这里有个性能细节：几万卷全量算 SHA-1 会跑很久，我的折中方案是先按「文件大小 + 前 1MB 哈希 + 后 1MB 哈希」做快速指纹，只有指纹撞了才做全量哈希。实测这一步能把去重环节从几十分钟压到几分钟。这个思路本质上就是 rsync 那一套滚动校验的思想，只是简化了。

校验环节我会顺手记录一份清单文件：

find library -name "*.cbz" -print0 \ | xargs -0 -n1 -P4 sha1sum > manifest.sha1

-P4是并发数，按你的 CPU 核数调，不要无脑拉满，机械硬盘上并发太高反而会掉速。清单文件的价值在于：以后每次迁移、备份、恢复之后，跑一遍sha1sum -c就知道有没有文件损坏，比一个一个点开看可靠得多。

断点续传这块，如果你的文件来自本地导入，其实用不上；但如果你是把大量文件从旧盘搬到新盘，我建议用rsync -a --partial --info=progress2，中断了直接重跑，它只会补差异部分。这个习惯帮我省掉过两次因为移动硬盘接触不良导致的重传。

4. 服务端搭建：把文件夹变成可检索的书架

到这一步你的库已经是“结构化的”了，但还只是一堆文件。要获得封面墙、跨设备阅读进度同步、按标签检索这些体验，需要挂一个漫画库管理服务。市面上有几个开源方案，我用的是容器化部署，下面讲通用做法，具体镜像按你选的方案替换占位符即可。

4.1 部署与卷挂载

# docker-compose.yml services: comic-shelf: image: <your-comic-shelf-image>:latest container_name: comic-shelf restart: unless-stopped ports: - "127.0.0.1:8848:8080" environment: - TZ=Asia/Shanghai - LIBRARY_PATH=/data/library - THUMB_PATH=/data/thumbs volumes: - ./data:/config - /mnt/comics/library:/data/library:ro - /mnt/comics/thumbs:/data/thumbs mem_limit: 1g

三个地方值得展开。端口绑定成127.0.0.1而不是0.0.0.0，是为了默认不对外暴露，需要远程访问时再通过反向代理加认证，这个顺序千万别反过来——先暴露后补认证，中间那段时间就是裸奔。library 挂成只读:ro，是因为服务端只应该读，任何写操作都应该走你的流水线，这样能防住“服务端误改文件结构”这类事故。mem_limit 设 1g是因为扫描大库时内存会短时冲高，不设上限某些方案会直接吃掉整机内存。

首次启动后进管理页，把库路径指到/data/library，语言设成中文，扫描模式选“按目录 + 元数据”。这里有个开关叫“优先使用元数据文件”，一定要打开，否则前面辛苦写的ComicInfo.xml就白费了。

4.2 扫描、匹配与阅读端接入

首次扫描速度取决于库的规模。我的库大约 1.2 万卷，第一次扫描跑了将近 40 分钟，主要时间花在解压读首图、生成缩略图上。第二次增量扫描就很快，几分钟搞定。这里有个经验：扫描期间不要同时往 library 里写文件，否则容易扫出半个条目，表现为“封面是灰的、点进去报错”。如果你的流水线是定时跑的，把扫描任务安排在流水线结束之后。

匹配环节是最容易出问题的。服务端会尝试把“目录名 + 文件名”解析成“作品 + 卷号”，规则定得越规整，匹配成功率越高。我当年的匹配率只有 70% 左右，改了命名规则之后稳定在 99% 以上，剩下的 1% 基本都是特装版、番外篇这类非常规条目，手动指定一下就行，不用追求 100%。

阅读端接入按设备来：桌面浏览器直接访问，体验完整；手机端用支持 OPDS 协议的阅读器，填上服务地址就能浏览；电子墨水设备建议关掉缩略图墙，只看列表，刷新会快很多。阅读进度同步依赖服务端的账号体系，所以哪怕只给自己用，也建议开一个账号而不是开匿名访问，否则多设备之间的进度就会打架。

4.3 权限与远程访问的安全边界

这块我说得直白一点：个人漫画库没有任何理由暴露在公网上。它既没有强认证，也通常没有做过安全加固，暴露出去等于把自己家书架门敞开。我的做法是只在内网可达，出门在外需要看的时候走一层带认证的反向代理，并且把访问限制在固定的几个 IP 段。

具体三条措施：

• 反向代理层开启 HTTP 基本认证，密码用长随机串，别用你能记得住的那种。
• 关掉服务端的“注册”功能，只保留你手动创建的账号。
• 定期看一眼访问日志，出现异常的高频请求就说明有问题，赶紧换凭证。

注意：所有关于“远程访问”的配置，我只在自己可控的内网和自有设备之间做。任何涉及第三方服务、共享账号、公共入口的做法，我都建议你绕开——不是因为技术上做不到，而是风险收益比太差，一个漫画库不值得冒那个险。

5. 常见问题排查实录

这一节是我这几年攒下来的问题清单，按出现频率排序，基本都是我自己或者身边朋友真实遇到过的。

5.1 扫描不到新加的卷、章节顺序错乱

扫描不到最常见的原因有三个：权限、路径、命名。

先看权限。容器内进程的 UID 和宿主机文件的属主不一致时，表现为“目录能列出来但文件读不了”，日志里通常是permission denied。解决办法是把容器的运行用户固定成宿主机的 UID，或者干脆把库目录的组权限放开到读。

再看路径。宿主机路径写成相对路径、软链接指向库外、挂载点写错一个字母，都会导致扫不到。排查命令很简单：

docker exec -it comic-shelf ls -l /data/library | head

容器里能不能看到文件，一眼就清楚，不用猜。

最后看命名。如果文件名里出现了全角字符、连续多个空格、卷号没有补零，匹配算法可能认不出来。我一般直接跑一遍归一化脚本，把全库文件名按 NFKC 标准化、多空格压成一个、卷号补齐三位，八成问题当场解决。

章节顺序错乱几乎百分百是排序字段填了混合文本。检查两处：ComicInfo.xml里的Number是不是纯数字；压缩包内图片是不是001.jpg这种纯数字序。两处都规范了还乱，那就是阅读器自身的排序设置问题，去设置里把它从“按文件名”改成“按卷号”。

5.2 中文乱码与封面错位

中文乱码分两种。一种是压缩包内的文件名乱码，根因是老式 zip 用 GBK 编码存文件名，而现代工具按 UTF-8 读。解决办法是打包时统一用 UTF-8，或者在解压工具里指定编码。另一种是元数据乱码，通常是 XML 头部少了encoding="utf-8"声明，加上就好。

封面错位这个坑我印象最深。表现是 A 作品的封面显示成了 B 作品的图。根因是缩略图缓存按“作品名哈希”命名，而我的库里有两部同名不同作者的作品，哈希撞了。修复方案是把缓存键改成“作者 + 作品名”的组合，跑一遍重建就好。

还有一个变体是“封面是纯黑或纯白”。这通常是从第 1 页抽封面抽到了空白页，改成从第 3–8 页抽即可。

5.3 性能问题与索引膨胀

库大了之后会出现两个症状：书架页加载慢、内存占用高。

加载慢先看缩略图。如果每次进书架都在现生成缩略图，那必然慢。确认缩略图目录是真的落盘了、并且有缓存，通常能解决八成问题。其次是分页，把每页条目数从 100 降到 30，加载体感会好很多。

内存高要看扫描策略。有些方案会在启动时全量读元数据进内存，几万卷下来就是几百 MB 起步。解决办法一是限制扫描深度，二是把 archive 层排除在扫描范围外——反正那层是冷备份，不需要索引。

6. 长期维护：备份、扩容与后续能扩展的方向

库建起来只是开始，真正决定它能不能活过三年的，是维护策略。我在这上面栽过最狠的一次是硬盘故障，丢了一百多卷没备份的整理成果，重做花了整整两个周末。

6.1 备份：3-2-1 落到具体动作

原则大家都知道，难的是落到可执行的动作。我现在的做法是：

• 本地一份：主库所在磁盘，每天凌晨跑一次清单校验，发现异常立即告警。
• 本地另一块盘一份：每周日增量同步，只同步 library 层，用rsync -a --delete，同步完跑sha1sum -c验证。
• 异地一份：每月把 archive 层的压缩包同步到一块移动硬盘，放在另一个物理位置。

同步脚本我写得很朴素，但加了两个保护：同步前先比对清单，如果发现源端文件数量比上次少了 5% 以上，直接中止并告警——这能防住“误删目录后被同步把备份也删了”的经典事故。另一个保护是同步日志留 30 天，出问题时能倒查是哪次操作引入的。

6.2 扩容时的迁移顺序

扩容不是把盘插上就完事。我的迁移顺序是：先停服务端，再做块级或文件级复制，复制完做清单校验，校验通过才改挂载路径，最后启动服务端做一次全量重扫。这个顺序里最容易被跳过的是“清单校验”，但恰恰是它救过我一次——某次复制过程中有个大文件截断了，sha1sum -c直接报出来，避免了带着坏文件上线。

另外提醒一句：扩容时尽量保持目录层级不变。如果非要改结构，改完必须重扫并重建缩略图，否则缓存键全对不上，封面墙会一片空白。

6.3 后续可以往上加的东西

这套东西跑稳之后，我陆续加了几个小功能，性价比都很高。一个是全文检索，把作品简介和标签导进一个轻量搜索引擎，找“某类题材里评分高的”特别方便。一个是阅读统计，记录每部作品读到哪一卷，配合进度同步，换设备无感衔接。还有一个是自动标签，用简单的关键词匹配从简介里抽题材标签，准确率一般但省事，抽错了手动改一下就行。

我自己在实际操作中的体会是：这套方案的价值不在于技术多先进，而在于每一层都是可替换、可回滚的。文件是标准的，元数据是通用的，服务端挂了换个方案重扫就行，备份是能验证的。先把地基和流水线做扎实，剩下的都是锦上添花；反过来，地基没打好就急着上花活，最后大概率是推倒重来。