用 Teemii + cpolar 搭建随身私人漫画库：Docker 部署与内网穿透实践

1. 项目缘起与整体设计思路

1.1 从"漫荒"到私人藏书库的一次实践

我猜很多人跟我一样，收藏了一堆漫画资源，散落在硬盘、网盘、旧手机里，想找个系列的时候翻半天，想用平板看却找不到合适的工具，平台上的资源今天还在明天就下架。所谓的"漫荒"，很多时候不是没有漫画看，而是东西太多太乱，真正想看的看不了。

这其实是一个典型的"本地资源管理"问题。光是"能存"解决不了问题，核心痛点在于三点：统一的元数据整理、跨设备可访问、良好的阅读体验。我一开始也试过一些现成的方案，要么是商业软件收费太高，要么是数据格式绑死，还有的在移动端体验极差。

后来我决定自己动手，用Teemii搭配cpolar，整套搭建下来之后，效果出乎意料地好。这套组合最终解决的是三个层面的问题：Teemii负责把散乱的文件变成可检索、可分类、可阅读的数字书架；cpolar负责把本地服务安全地映射到公网，让我在外面也能连回家里的服务器；最后的成果就是一个"随身私人漫画库"。这套思路不挑平台，Windows、Linux、群晖都能用，对硬件要求也不高。

1.2 方案选型背后的关键考量

做方案选型的时候，我列过一个需求清单，每条都对应一个现实痛点：

选Teemii是因为它本身就是开源的，Docker 部署足够轻量，数据都落在自己的存储里，不存在平台突然停止服务、数据被绑定的问题。选cpolar则是因为它的配置简单，认证之后一行命令就能把本地端口暴露出去，而且免费档位对个人用途来说完全够用。

也有朋友问我，为什么不用公网 IP + 端口映射？很简单，大部分家庭宽带没有固定公网IP，而且改路由、申请备案这套流程对于普通用户来说太不友好了。cpolar 这类内网穿透方案，本质上是借助一条加密隧道，把本地服务安全地接到一个公网入口上，省去了复杂的网络配置。

2. Teemii 核心功能与部署实操

2.1 用 Docker 五分钟拉起 Teemii 服务

我平时部署东西的习惯是能容器化就容器化，Teemii 官方也推荐用 Docker 方式运行。你只需要准备一台常开的机器——哪怕是淘汰下来的旧笔记本或者小主机，问题都不大。整体的安装思路是：装 Docker，写好 compose 文件，拉镜像起容器，完事。

下面是一份我实际在用的docker-compose.yml，关键参数都标注了用途：

version: "3.8" services: teemii: image: teemii/teemii:latest # 官方镜像，amd64/arm64都覆盖 container_name: teemii restart: unless-stopped ports: - "127.0.0.1:3000:3000" # 仅本机映射，后续用cpolar暴露 volumes: - ./data:/app/data # 数据库与配置数据 - ./library:/app/library # 漫画根目录，也可以改成你实际的漫画存放路径 environment: - PUID=1000 # 非 root 运行，避免权限问题 - PGID=1000 - TZ=Asia/Shanghai # 时区，影响日志和元数据时间

有一个细节值得展开说：端口映射我特意绑定了 127.0.0.1，而不是 0.0.0.0。这意味着 Teemii 只接受本机访问。这样做的考虑很简单——在没有额外鉴权的情况下，直接把一个 Web 服务暴露在整个局域网里，等于在自家 WiFi 上开了个后门，任何人连上网络都能打开你的书架。所以我把公网入口完全交给 cpolar 管理，本地端口不裸奔。这是很多教程不会告诉你的细节，但非常关键。

执行docker compose up -d之后，浏览器访问http://localhost:3000，首次打开会进入初始化引导，它会让你设置管理员账号、指定漫画存储路径。这一步不用多想，按向导走就行，完成后整个服务就已经跑起来了。

2.2 目录结构与数据组织策略

Teemii 的数据目录结构并不复杂，但组织方式直接影响后续管理效率。我见过有人把所有漫画往一个文件夹里一丢，几万张图片混在一起，结果光扫描就花了几个小时。合理的做法是建立"按作者/作品名/卷册"的层级目录：

library/ ├── 作者A/ │ ├── 作品X/ │ │ ├── Vol_001.cbz │ │ └── Vol_002.cbz │ └── 作品Y/ │ ├── 第01话/ │ │ ├── page_001.jpg │ │ └── page_002.jpg └── 作者B/ └── 作品Z/ └── 第01话.cbr

我对目录的组织建议是：保持清晰、稳定的层级结构，命名尽量规范，比如"作品名 + 卷册号"。Teemii 扫描的时候会把目录结构和文件名作为重要依据，如果命名太随意，刮削和匹配的成功率会明显下降。这一步做好，后面省的是成倍的时间。

扫描操作在界面的"藏书管理"入口里，点击扫描之后，Teemii 会读取目录结构，识别漫画格式，并生成一个基础的数据库条目。扫描速度取决于文件数量和存储介质，机械硬盘几千个文件大概要几分钟，SSD 上基本一分钟内搞定。

2.3 元数据刮削与多来源匹配机制

Teemii 的元数据刮削机制，是它跟"普通的文件管理器"拉开差距的地方。它并不是简单地拿文件名充作标题，而是会尝试从多个在线数据源去匹配作品封面、作者、简介、标签和章节信息。我之前手动整理书籍信息时，每本书要花一两分钟去查资料、找封面，而 Teemii 的效率则明显高出一个量级。

实际使用中我发现，匹配成功率受文件名规范程度影响极大。比如你给一个文件命名为1，它可能什么都匹配不出来；命名为作品名 Vol. 01或者作品名 第01话，成功率就很高。如果某个条目匹配错了，界面上也提供了手动修正入口，可以搜索到正确的作品然后关联。这个功能我实测下来确实顺手，整个元数据整理环节的体验称得上顺畅。

还有一个彩蛋——Teemii 会为一些匹配不到元数据的中文作品保留本地信息，也就是它会读取文件内部自带的书签或压缩包注释，生成一个最小可用的条目。不至于因为刮削失败就变成"孤儿文件"，这个兜底策略很踏实。

3. 数据存储、阅读体验与特色功能实践

3.1 数据库方案：轻量但不简单的数据底座

聊到数据存储，Teemii 默认采用 SQLite，这一点我觉得非常务实。有些同类系统上来就要求 PostgreSQL、MySQL，对一个几百本漫画的家庭库来说明显是杀鸡用牛刀。SQLite 单文件存储、备份整体拷贝即可，而且 99% 的查询场景响应都在毫秒级。

实际过程中唯一需要留意的，是数据库文件所在目录的写入权限问题。之前我在群晖上遇到过容器内 UID 和宿主机不一致，导致服务时不时报只读错误的情况。解决方法也很简单——在 compose 里把PUID和PGID设为宿主机上对应目录所有者的 UID/GID，重启容器就能解决。

如果后期漫画量真的涨到万册级别，SQLite 的写入并发可能会有瓶颈，但对于个人使用完全够用。真要追求更夸张的规模，Teemii 的架构也支持接入外部数据库，不过那是极少数人的需求了。

3.2 阅读器：多端一致性的核心体验

阅读器的体验直接决定这套系统的实用价值。Teemii 的 Web 阅读器在桌面浏览器、平板、手机浏览器上都能跑，响应式布局做得比较细。我在 iPad 和安卓平板上都实测过，纵向滚动模式和双页阅读模式都表现稳定。

有一个细节必须提一下：阅读进度同步是基于服务端的会话记录，不是本地缓存。也就是说，你在手机上读到第15页，关闭之后到电脑上打开，进度会从第15页继续。这背后的逻辑是，Teemii 把阅读状态保存在数据库里，任何终端都从服务端读取状态。这个功能解决了我在多个设备之间来回切换的阅读连续性痛点。

3.3 导入工具的实战经验

大多数人是已经有存量文件，才想到搭私人漫画库。Teemii 的导入模块我用过几次之后，总结了一个批量导入的高效流程：

1. 推荐优先采用标准压缩格式（CBZ/CBR），如果手头是散图，建议批量压成 CBZ 再入库。这样传输、读取效率都会提升。
2. 如果文件命名混乱，建议先做一次批量重命名，再去扫描。可以借助一些批量重命名工具，把01_001这样的名字整理成作品名_第01话_01的体力活交给工具完成。
3. 比较推荐的扫描策略是"分卷扫描"，即目录层级很深的藏书，先扫顶层，确认子结构正确，再继续往下扫。一次扫全盘容易引发大量重复匹配请求，拖慢速度。

批量导入时，Teemii 的扫描模块还会生成一份导入报告，包含失败条目和原因。我在使用中发现，绝大多数失败都源于文件名里的特殊字符，比如中文冒号、问号、引号等。遇到这种情况，批量清理文件名特殊字符，然后重新扫描即可。

4. cpolar 内网穿透与随身访问配置

4.1 为什么选择 cpolar 做远程访问层

服务搭好了，书也整理好了，如果只能在家里访问，那就还差一口气。我个人的需求是：通勤路上用手机看，午休时用公司电脑看一两话，如果窝在咖啡馆，也希望打开平板就能连回家。这就意味着必须有一个稳定的远程访问链路。

cpolar 这类工具的核心原理，是借助部署在公网的跳板服务器建立一条数据隧道，将本地某个端口（这里是 3000）映射成一个公网可访问的域名地址。关键在于，数据流虽然经过第三方服务器，但隧道本身带有加密，而且 Teemii 的数据始终保存在本地，不经过任何第三方存储。这跟把漫画传到公共网盘完全是两回事——后者你的数据在别人服务器上，前者只是数据流的搬运通道。

选 cpolar 还有一个现实原因：配置成本低。认证之后它会分配一个随机域名，免费档足够个人日常使用。付费档可以固定域名、增加带宽和隧道数量，等确认自己能稳定用下来再考虑也不迟。

4.2 从安装到映射的完整实操流程

cpolar 的安装方式覆盖主流平台，我这里以 Linux 服务端为例，说明完整的配置流程：

# 安装（Debian/Ubuntu 系） curl -L https://cpolar.cn/static/downloads/install-release.sh | sudo bash # 查看版本确认安装成功 cpolar version # 认证（token 在 cpolar 网页后台的“认证”页面获取） cpolar authtoken xxxxxxxxxxxxxxxx # 启动一个隧道，映射本地 3000 端口到公网 cpolar http 3000

执行完成之后，终端会输出一段公网访问地址，把地址直接在手机浏览器打开，就能看到 Teemii 的登录界面了。这里面有几个值得注意的细节：

第一，cpolar 的免费隧道地址每次重启都会变化。如果你只是偶尔用用，这个缺点还能接受；如果每天都依赖它访问，建议使用固定域名方案。固定域名之后，域名不变，访问体验会稳定很多。

第二，建议在守护进程里托管 cpolar，而不是把它挂在一个会话终端里。官方提供了 systemd 服务，可以这样启用：

systemctl enable cpolar systemctl start cpolar

或者直接用cpolar start tunnel_name --log stdout这样的后台模式。这样做的意义在于，服务器重启之后 cpolar 会自动恢复，你不需要再跑到机房或者远程 SSH 登录去手动拉起隧道。

第三，隧道协议的选型。cpolar 支持 HTTP 和 TCP 两种隧道。对漫画库这种 Web 应用，HTTP 隧道就够用了。如果你后续想加一些其他协议的本地服务（比如 SSH 访问家里的 NAS），才需要考虑 TCP 隧道。

4.3 访问链路安全加固的实操经验

把服务暴露到公网，就意味着任何人拿到这个域名都有可能访问。所以有一件事必须做：不要用 Teemii 的默认管理员口令。你初始化时设的密码强度直接决定整套系统的安全上限。

我实际使用的加固策略包括三层：

• 首层是 Teemii 自带的账号密码登录，这是第一道防线。
• 第二层是使用 cpolar 的访问控制功能，为公网域名额外加一层访问凭证，即使有人拿到了域名，也需要通过这层验证才能看到登录页。
• 第三层是设备终端层面的习惯：离开时随手退出登录，不在公共电脑上勾选"记住我"。

还有一个你们可能会忽略的细节：Teemii 的管理端和阅读端是同一套服务，没有独立的访客模式。所以如果分享给朋友看书架上的某些作品，这意味着对方会拥有完整的管理权限。我的建议是，要么只分享给绝对信任的人，要么在服务端再跑一个只读的独立实例指向另一个书库。我个人在实践中倾向于只在家庭可信网络内分享，公网访问则只留给自己使用。

安全这个环节马虎不得，毕竟一旦被攻破，受影响的不是一部漫画的事情，而是你整个家庭网络。

5. 常见问题排查与体验优化实录

5.1 问题速查表：部署、导入、访问全链路

我在整个搭建过程中踩过不少坑，有一些问题非常典型，几乎每个新手都会遇到。我把它们整理成了一张速查表：

5.2 一个印象深刻的实战排障过程

我印象比较深的是一次奇怪的访问故障：白天在公司用手机访问正常，晚上回家连上 WiFi 反而打不开了。排查了半天，发现问题根本不在 Teemii 和 cpolar 上——是家里 WiFi 路由器开了 AP 隔离，导致局域网内的设备无法互访，而我的手机恰好优先走了局域网 IP 去访问服务器。

这个案例的启发是：远程访问链路有问题，不一定出在远端，很多"打不开"的问题根源在本地网络。排查顺序非常重要，我会按"先本地后公网"的顺序推进：先确认本地http://localhost:3000是否正常，再确认局域网 IP 能否访问，最后才检查公网隧道状态。这样能快速定位绝大多数故障。

5.3 性能调优：给机械硬盘环境的建议

如果你像我一样，漫画库存放在 NAS 的机械硬盘上，扫描和缩略图生成会比较慢。Teemii 处理缩略图的机制是，扫描时生成封面预览缓存，但如果文件很多，第一次扫描会持续较长时间。我的建议是启用扫描任务的优先级机制，把需要优先看的作品放到高层级目录，第一轮扫描先覆盖这些，其余的慢慢来。

另一个优化方向是存储规划：将系统数据（数据库和缩略图缓存）放在 SSD，漫画原文件放在机械硬盘，两者通过目录挂载组合起来。Teemii 支持的./data和./library分离设计，正好方便这样操作。扫描速度和封面临时读取速度会显著提升，而大文件读取延迟则被机械硬盘容量优势摊平了。

6. 从实践出发的几条维护心得

整套系统稳定运行几个月之后，我总结了几条维护经验，不一定适用于所有人，但如果你想长期依赖"私人随身漫画库"，这些建议值得参考：

关于备份策略。Teemii 的核心数据其实就是数据库和配置目录，它们加起来可能只有几十兆。我每天用定时任务把data目录打包上传到独立的存储空间，同时在本地留一份快照。漫画原文件则不再重复备份——它们本身就是从多个来源整理出来的，丢了之后重新下载的成本远大于备份成本。这个取舍思路适用于任何个人服务：优先保护不可再生的数据，可再生的资源以重建代替备份。

关于内容来源的合规性。搭建私人漫画库的前提是对自己收藏的资源有清晰的版权边界，合理合法地使用技术工具，不传播、不分享受版权保护的资源。我个人只将这套系统用于管理个人合法获取的内容，并强烈建议所有读者都以此为前提。技术在搭建过程中是中性的，使用者的自觉才是底线所在。

关于服务更新。Teemii 迭代节奏比较快，我基本上每个月会拉一次新镜像，更新之前先看更新日志确认有没有破坏性变更。方法很简单：docker compose pull之后docker compose up -d，不到两分钟就能完成。cpolar 则不用频繁更新，只要隧道状态正常就别手痒去动它。

最后聊一个使用习惯上的体会："随身漫画库"的价值，不在于囤了多少书，而在于想看的时候三秒钟内就能打开。Teemii 把整理和检索的问题解决得很彻底，cpolar 把访问半径扩大到了任何有网络的地方。整个过程里，最大的成就感不是技术跑通了，而是那些躺在旧硬盘里吃灰的漫画，终于在手机和平板上"活"了过来。