> 风之谷家庭服务器系列 · 第 1 篇

## 前言

家里攒了不少电子书，手机阅读 App 广告满天飞，网盘看小说还要会员。干脆自己搭一个：一台旧电脑 + Python 标准库，做一个本地"私人 Kindle"，支持 EPUB / TXT，手机电脑都能开，还能听书。

本篇讲服务端，**全程零第三方依赖**。

![md1-1-书架.png](https://developer.qcloudimg.com/http-save/yehe-12646891/ca414a6d2427d877eec1ba88e8416b45.png)

*书架页：封面、搜索、阅读进度都在这*

## 一、总体架构：端口探测 + 多线程

核心思路：`ThreadingTCPServer` + 每次请求从磁盘读 HTML——这样改前端完全不用重启服务。

```python
class ThreadingServer(socketserver.ThreadingTCPServer):
    daemon_threads = True
    allow_reuse_address = False   # Windows 上必须是 False！

def serve():
    # 端口探测：已有实例则直接退出，防双开
    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    probe.settimeout(1)
    if probe.connect_ex(("127.0.0.1", PORT)) == 0:
        print("服务已在运行，本次启动自动退出")
        return
    probe.close()
    httpd = ThreadingServer(("", PORT), Handler)
    httpd.serve_forever()
```

**踩过的坑**：Windows 下 `allow_reuse_address=True` 并不是"端口复用"，而是允许**两个进程绑同一个端口**——连接会被随机掐断，症状是"网页时好时坏"，非常迷惑。改成 `False` 后世界清净。这条在 Linux 上行为还不一样，跨平台部署的同学注意。

## 二、EPUB 元数据：zipfile + ElementTree 就够了

EPUB 本质是个 zip 包。解析链路：`META-INF/container.xml` → 找到 OPF 文件路径 → 读取 title / creator / 封面图。三十来行代码，不用装任何第三方库：

```python
with zipfile.ZipFile(path) as z:
    # container.xml 里取 rootfile 的 full-path，再读 OPF
    opf = ET.fromstring(z.read(opf_path))
    for el in opf.iter():
        tag = el.tag.split("}")[-1]   # 去掉 XML 命名空间前缀
        if tag == "title":
            title = (el.text or "").strip()
```

注意 `el.tag` 是带命名空间的（形如 `{urn:oasis:names:tc:opendocument...}title`），`split("}")[-1]` 一刀切干净，比写正则优雅。

封面图从 OPF manifest 里按 id 找到 href，从 zip 里抽出来缓存到本地，书架就有脸了。

![md1-2-阅读页.png](https://developer.qcloudimg.com/http-save/yehe-12646891/103e63e79fab669f89a78fccecc34806.png)

*EPUB 分章阅读页*

## 三、TXT 编码：一条兜底链

中文 TXT 十有八九是 GBK 系，还有 Big5 的古籍。按固定顺序尝试解码，稳：

```python
def decode_txt(b):
    for enc in ("utf-8-sig", "gb18030", "big5"):
        try:
            return b.decode(enc)
        except UnicodeDecodeError:
            pass
    return b.decode("utf-8", "replace")
```

服务端统一转成 UTF-8 再发给前端，前端就完全不用关心编码了。

## 四、前端三个血泪坑（epub.js）

1. **引错文件**：`lib/index.min.js` 是 CommonJS 版本，浏览器直接报 `exports is not defined`。必须用 `dist/epub.min.js`。
2. **URL 必须带 .epub 后缀**：`ePub("/api/book/abc")` 会被当成"解包目录"去请求 `/META-INF/container.xml`，得到 404。改成 `/api/book/abc/book.epub`，服务端忽略多余的路径段即可。
3. **调试技巧**：内容渲染在 iframe 里，报错外层看不见。往 `document.title` / `data-*` 属性写"探针"值再 dump DOM，比断点调试快得多。

![md1-3-书架整页.png](https://developer.qcloudimg.com/http-save/yehe-12646891/d5808247f7835cbe455ef1461b7a2a87.png)

*整屏书架（响应式，手机电脑同一套）*

## 结语

最后成型：书架（封面/搜索/进度）、EPUB 分章阅读、TXT 双正则切章（网文"第X章"+古籍"学而第一"）、白黄黑三主题、进度本地恢复，全部装进一个单文件 HTML。

**下篇预告**：《网页听书零成本：Web Speech API 逐句朗读 + 自动翻页》——听书功能一个 API Key 都不用申请。

家里攒了不少电子书，手机阅读 App 广告满天飞，网盘看小说还要会员。干脆自己搭一个：一台旧电脑 + Python 标准库，做一个本地"私人 Kindle"，支持 EPUB / TXT，手机电脑都能开，还能听书。

100 行 Python，我从零搭了个家庭私人书屋（EPUB / TXT / 听书全支持）

人工智能

搭建零依赖本地电子书服务器：用旧电脑+Python标准库实现私人Kindle，支持EPUB/TXT在线阅读与听书。重点解决Windows端口复用坑、EPUB元数据解析、TXT多编码识别，前端采用epub.js并避开三个典型错误。响应式书架含封面搜索进度，全程无第三方依赖。

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

100 行 Python，我从零搭了个家庭私人书屋（EPUB / TXT / 听书全支持）-腾讯云开发者社区-腾讯云

100 行 Python，我从零搭了个家庭私人书屋（EPUB / TXT / 听书全支持）

100 行 Python，我从零搭了个家庭私人书屋（EPUB / TXT / 听书全支持）

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐