基于Docker部署SoNovel：构建私有小说库的全栈实践指南

你是否曾为寻找一本心仪的小说在各大网站间反复切换忍受着广告弹窗、阅读限制和格式错乱或者你是否担心某天收藏的小说链接失效精心整理的阅读记录无处可寻对于深度阅读爱好者来说一个纯净、稳定、完全由自己掌控的私人小说库不仅是便利更是一种数字资产的“安全感”。今天要介绍的SoNovel正是一个能解决上述所有痛点的开源小说神器。它不是一个简单的阅读器而是一个集成了小说搜索、在线阅读、内容下载、本地管理于一体的全栈解决方案。更重要的是通过Docker部署你可以在自己的服务器、NAS甚至家用电脑上用极低的成本和门槛搭建一个永不消失的私人图书馆。这篇文章要解决的远不止“如何安装一个软件”。我们将深入探讨为什么在云服务唾手可得的今天自建小说库仍有不可替代的价值SoNovel 的核心设计解决了哪些传统阅读方式的顽疾以及如何通过 Docker 这一“标准化集装箱”让一个包含前后端、数据库的复杂应用在十分钟内从零跑通。如果你符合以下任一情况这篇文章将为你提供一条清晰的实践路径技术爱好者想用 Docker 练手部署一个有趣又有用的完整项目。小说重度用户受够了平台限制渴望一个干净、无干扰、可永久保存的阅读环境。数据囤积党有强烈的数据主权意识希望将喜欢的文字内容本地化存档。个人开发者对 SoNovel 的架构感兴趣或许能从中获得灵感。接下来我们将从 SoNovel 的核心价值讲起一步步完成 Docker 环境准备、项目部署、功能体验并深入分析其配置、常见问题及最佳实践最终让你拥有一个 7x24 小时在线的私人小说库。1. SoNovel 是什么它解决了什么真问题在深入部署之前我们必须先理解 SoNovel 的定位。它不是一个“又一个小说网站源码”而是一个面向个人的小说内容聚合与管理中间件。传统在线阅读的痛点平台依赖性强小说存放在第三方服务器平台关闭或书籍下架内容即消失。体验割裂广告、会员弹窗、格式不统一打断阅读沉浸感。数据孤岛在不同平台上的书架、阅读进度、笔记无法互通。格式限制通常只能在线看难以导出为 ePub、TXT 等通用格式进行存档或在其他设备阅读。SoNovel 的核心解决方案统一搜索入口聚合了多个公开的小说源站你只需要在 SoNovel 里搜索一次它帮你并行查询多个源站返回最全的结果。内容本地化搜索到的小说可以直接在线阅读。更重要的是你可以一键将整本书或指定章节下载到你的服务器本地生成标准 ePub 或 TXT 文件。从此这本书就真正属于你了。纯净阅读器提供基于 Web 的阅读界面无任何广告支持字体、背景、进度保存等个性化设置。Docker 化部署这是降低使用门槛的关键。SoNovel 将前端Vue、后端Spring Boot、数据库MySQL/PostgreSQL等所有组件打包成 Docker 镜像和编排文件。你不需要分别安装配置 Node.js、Java、MySQL只需要安装 Docker然后一条命令即可启动整个系统。所以SoNovel 的真正价值在于它通过技术手段将互联网上分散、不稳定的小说资源抓取、转换并固化到你个人可控的存储中同时提供了一个优雅的管理和消费界面。这本质上是一种“数据归档”和“体验优化”的行为。2. 核心概念与架构解析要更好地使用和运维 SoNovel了解其核心组件和工作原理很有必要。2.1 核心组件一个标准的 SoNovel 部署包含以下服务前端 (Frontend)通常是一个基于 Vue.js 或 React 的单页面应用SPA。负责提供用户界面包括搜索框、书架、阅读器、设置页面等。用户通过浏览器访问的就是它。后端 API (Backend)通常基于 Java (Spring Boot) 或 Python (FastAPI) 构建。它是系统的“大脑”负责处理业务逻辑接收前端的搜索请求、调用爬虫模块、管理书籍和章节信息、处理下载任务、与数据库交互等。数据库 (Database)用于持久化存储数据。主要存储用户信息如果支持多用户。书籍元数据书名、作者、封面、简介。书架信息。阅读进度。下载任务记录。系统配置。爬虫/解析器 (Crawler/Parser)这是 SoNovel 的“手”和“眼睛”。它内置于后端或作为独立微服务负责根据规则去第三方小说网站抓取网页、解析 HTML 结构提取出纯净的正文、章节标题等信息。这是技术核心也是容易因网站改版而失效的部分。2.2 数据流与工作原理用户搜索在前端输入书名 - 前端请求后端 API - 后端调用爬虫模块并发查询多个预配置的“源站”即小说网站。结果聚合爬虫从各源站获取搜索结果列表书名、作者、链接后端去重、排序后返回给前端展示。书籍详情用户点击某本书 - 前端请求书籍详情 - 后端爬虫访问该书籍目录页解析出所有章节列表并返回。在线阅读用户点击某章节 - 前端请求章节内容 - 后端爬虫访问章节页解析出正文并可能进行格式清洗去广告、优化段落然后返回给前端阅读器渲染。内容下载用户触发下载 - 后端创建下载任务 - 爬虫按顺序抓取所有章节内容 - 后端将内容组装、格式化为 ePub/TXT 文件 - 文件存储在服务器指定目录如./downloads- 前端提供下载链接。2.3 Docker 在其中的角色Docker 将上述所有组件前端、后端、数据库以及它们的运行环境Node.js 运行时、JVM、MySQL 服务分别封装成独立的容器Container。通过docker-compose.yml文件定义它们之间的关系谁依赖谁、如何通信、端口映射、数据卷挂载。环境隔离你的宿主机不需要安装 Java、Node.js避免了环境冲突。一键部署docker-compose up -d命令就能按定义好的顺序启动所有服务。易于迁移整个应用可以轻松地从你的电脑迁移到云服务器或 NAS。版本管理可以方便地切换或升级 SoNovel 的版本。理解了这个架构在后续部署和排错时你就能清楚地知道问题可能出在哪个环节。3. 环境准备安装 Docker 与 Docker Compose这是所有步骤的基础。我们将分别介绍在LinuxUbuntu/CentOS和Windows上的安装方法。请根据你的系统选择。3.1 Linux 系统安装以 Ubuntu 22.04 为例通过 SSH 连接到你的 Linux 服务器或打开终端。步骤一卸载旧版本如有sudo apt-get remove docker docker-engine docker.io containerd runc步骤二安装依赖包并添加 Docker 官方 GPG 密钥sudo apt-get update sudo apt-get install \ ca-certificates \ curl \ gnupg \ lsb-release sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg步骤三设置稳定版仓库echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null步骤四安装 Docker Enginesudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin步骤五验证安装sudo docker --version sudo docker compose version # 注意这是插件版的 docker compose不是独立的 docker-compose如果看到版本号输出说明 Docker 和 Compose 插件安装成功。步骤六可选但推荐将当前用户加入 docker 组避免每次命令都要加sudo。sudo groupadd docker # 如果 docker 组已存在会提示可忽略 sudo usermod -aG docker $USER newgrp docker # 刷新组权限或直接退出终端重新登录 docker run hello-world # 测试无需 sudo 运行容器如果看到 “Hello from Docker!” 等信息说明配置成功。3.2 Windows 系统安装对于 Windows 10/11 专业版、企业版或教育版推荐使用Docker Desktop。步骤一开启 Hyper-V 和容器功能搜索“启用或关闭 Windows 功能”。勾选Hyper-V和容器两个选项点击确定重启电脑。如果找不到 Hyper-V可能是因为你的 Windows 版本是家庭版需要额外步骤如安装 WSL2或使用 Docker Toolbox已过时。建议升级系统或考虑在 Linux 虚拟机中部署。步骤二下载并安装 Docker Desktop访问 Docker 官网下载 Docker Desktop for Windows 安装包。运行安装程序按照向导完成安装。安装过程中会要求重启。重启后在开始菜单找到 Docker Desktop 并运行。首次启动需要接受服务条款等待 Docker 服务启动完成系统托盘会出现鲸鱼图标。步骤三验证安装打开 PowerShell 或命令提示符CMDdocker --version docker compose version同样看到版本号即表示成功。步骤四配置镜像加速国内用户强烈建议为了提升拉取镜像的速度需要配置国内镜像源。右键点击系统托盘 Docker 图标 - Settings (设置)。选择 Docker Engine。在配置 JSON 文件中添加或修改registry-mirrors项。例如使用阿里云镜像需先登录阿里云容器镜像服务获取专属加速地址{ registry-mirrors: [ https://your-id.mirror.aliyuncs.com ] }点击 “Apply Restart”。3.3 安装总结与常见问题Linux 虚拟化支持如果在虚拟机或云服务器上安装请确保 BIOS/固件中已开启虚拟化支持如 Intel VT-x/AMD-V。对于大多数云服务器此项默认开启。Windows 家庭版可先安装 WSL2 (Windows Subsystem for Linux 2)然后在 WSL2 的 Linux 发行版中安装 Docker。Docker Desktop 支持与 WSL2 集成。端口冲突确保 SoNovel 将要使用的端口如 80, 8080, 3306在宿主机上没有其他程序占用。环境准备好后我们就可以进入核心的部署环节了。4. 获取与部署 SoNovelSoNovel 是一个开源项目代码通常托管在 GitHub 或 Gitee 上。部署的核心是获取其docker-compose.yml配置文件。4.1 获取部署文件假设项目仓库地址为https://github.com/your-name/SoNovel请替换为实际仓库地址。我们通过 Git 克隆或直接下载配置文件。方法一使用 Git推荐# 克隆整个仓库包含源码便于后续自定义 git clone https://github.com/your-name/SoNovel.git cd SoNovel # 查看目录结构通常部署文件在根目录或 docker/ 目录下 ls -la方法二直接下载编排文件如果只需要部署可以直接下载docker-compose.yml和可能需要的环境变量文件.env。# 创建一个专用目录 mkdir -p ~/sonovel cd ~/sonovel # 使用 curl 下载假设文件直链已知 curl -O https://raw.githubusercontent.com/your-name/SoNovel/main/docker-compose.yml curl -O https://raw.githubusercontent.com/your-name/SoNovel/main/.env.example cp .env.example .env # 复制一份作为自定义配置4.2 解析 docker-compose.yml在启动前理解这个文件至关重要。一个典型的 SoNoveldocker-compose.yml可能如下所示version: 3.8 services: mysql: image: mysql:8.0 container_name: sonovel-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-sonovel123} MYSQL_DATABASE: sonovel MYSQL_USER: sonovel MYSQL_PASSWORD: ${DB_PASSWORD:-sonovel123} volumes: - ./data/mysql:/var/lib/mysql - ./config/mysql/conf.d:/etc/mysql/conf.d ports: - 3306:3306 networks: - sonovel-network backend: image: your-name/sonovel-backend:latest container_name: sonovel-backend restart: unless-stopped depends_on: - mysql environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/sonovel?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai SPRING_DATASOURCE_USERNAME: sonovel SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD:-sonovel123} # 其他后端配置... volumes: - ./downloads:/app/downloads # 挂载下载目录 - ./logs/backend:/app/logs ports: - 8080:8080 networks: - sonovel-network frontend: image: your-name/sonovel-frontend:latest container_name: sonovel-frontend restart: unless-stopped depends_on: - backend environment: VITE_API_BASE_URL: http://backend:8080/api # 前端调用后端的地址容器内网络 ports: - 80:80 networks: - sonovel-network networks: sonovel-network: driver: bridge volumes: mysql-data:关键点解读服务定义定义了三个服务mysql,backend,frontend。镜像来源image字段指定了每个服务使用的 Docker 镜像。你需要确认这些镜像在 Docker Hub 或其它仓库中是否可用。有时项目需要你自己构建镜像。环境变量environment部分用于配置服务。${DB_PASSWORD:-sonovel123}表示优先使用.env文件中定义的DB_PASSWORD变量如果未定义则使用默认值sonovel123。务必修改默认密码数据持久化volumes将容器内的目录如/var/lib/mysql,/app/downloads挂载到宿主机的目录如./data/mysql,./downloads。这样即使容器删除数据也不会丢失。网络所有服务加入自定义的sonovel-network使得它们可以通过服务名如mysql,backend相互访问。端口映射ports将容器端口映射到宿主机端口。例如80:80表示访问宿主机的 80 端口就等于访问前端容器的 80 端口。4.3 自定义配置 (.env 文件)编辑项目目录下的.env文件这是集中管理配置的地方。# .env 文件示例 # 数据库配置 DB_ROOT_PASSWORDYourStrongRootPassword123! DB_PASSWORDYourStrongDBPassword456! # 后端服务配置示例 BACKEND_PORT8080 JWT_SECRETYourVeryLongAndComplexJwtSecretKeyHere # 前端服务配置示例 FRONTEND_PORT80 # 下载路径相对于宿主机 DOWNLOAD_PATH./downloads安全提醒务必修改所有默认密码和密钥使用强密码。4.4 启动 SoNovel 服务一切就绪后在包含docker-compose.yml的目录下执行启动命令# 在后台启动所有服务 docker compose up -d-d参数代表“detached”让服务在后台运行。执行后Docker 会执行以下操作检查本地是否存在所需的镜像如mysql:8.0,your-name/sonovel-backend:latest如果不存在则从 Docker Hub 拉取。按照依赖顺序depends_on创建并启动容器。创建网络和数据卷。查看服务状态docker compose ps你应该看到三个服务的状态都是Up。查看实时日志可用于排错# 查看所有服务日志 docker compose logs -f # 查看特定服务日志如后端 docker compose logs -f backend5. 访问与初步配置5.1 访问 SoNovel根据docker-compose.yml中的端口映射前端界面打开浏览器访问http://你的服务器IP地址或http://localhost如果在本机部署。你应该能看到 SoNovel 的首页。后端 API通常可以通过http://你的服务器IP地址:8080访问后端提供的 API 文档如 Swagger UI但这取决于项目是否开启。5.2 初始化与登录首次访问系统可能会引导你进行初始化设置如创建管理员账户。请按照页面提示操作。如果项目默认提供了账户如 admin/admin请务必在登录后第一时间修改密码。5.3 配置小说源关键步骤SoNovel 的核心功能依赖于“小说源”。这些源是预定义的规则告诉爬虫如何去特定网站抓取数据。登录后在管理界面或设置页面找到“源管理”、“书源配置”或类似选项。项目初始可能内置了一些源也可能需要你手动导入。开源社区通常会维护一个书源 JSON 列表。你可以从项目的 Wiki、Issues 或相关社区找到最新的书源分享链接。格式通常是一个 JSON 数组包含多个源的名称、URL、解析规则等。在 SoNovel 界面中选择“导入书源”粘贴 JSON 内容或上传文件。导入后尝试搜索一本你知道的小说测试源是否有效。注意小说网站经常改版书源可能会失效。维护有效的书源是持续使用 SoNovel 的一个小成本。活跃的社区是获取更新书源的最佳途径。6. 核心功能体验与代码级解析让我们通过一个完整的用户旅程体验 SoNovel 的核心功能并理解其背后的技术实现。6.1 搜索与发现在首页搜索框输入“诡秘之主”。点击搜索后前端会向后端发送一个 API 请求。前端伪代码逻辑// 假设在 Vue 组件中 async searchNovel(keyword) { this.loading true; try { const response await axios.get(/api/search?keyword${encodeURIComponent(keyword)}); this.searchResults response.data; // 假设返回 { books: [...] } } catch (error) { console.error(搜索失败:, error); this.$message.error(搜索失败请检查网络或源站); } finally { this.loading false; } }后端处理流程接收/api/search请求解析关键词。从数据库或配置中加载所有启用的“书源”。并发抓取为每个书源启动一个异步任务使用 HTTP 客户端如 OkHttp, HttpClient访问该源站的搜索接口或模拟搜索页面并携带关键词。解析 HTML使用 JsoupJava或 BeautifulSoupPython等库根据该书源的预定义规则CSS 选择器、XPath解析返回的 HTML提取书籍列表书名、作者、链接、最新章节等。结果聚合与去重将所有源站的结果收集起来根据书名和作者进行去重和排序如按来源权重、更新时间。将处理后的列表返回给前端。6.2 书籍详情与目录获取点击搜索结果中的某本书进入详情页。前端会请求书籍详情和目录。async fetchBookDetail(bookId, sourceUrl) { const response await axios.get(/api/book/detail, { params: { bookId, source: sourceUrl } }); this.bookInfo response.data.info; this.chapters response.data.chapters; // 章节列表 }后端会根据sourceUrl找到对应的书源规则然后访问该书的目录页。解析出所有章节的标题和 URL。可能将书籍元信息封面、简介、作者和章节列表缓存到数据库中以减少对源站的重复请求。返回结构化的数据。6.3 在线阅读点击某一章节阅读器页面会请求章节内容。async fetchChapterContent(chapterUrl, source) { const response await axios.get(/api/chapter/content, { params: { chapterUrl, source } }); this.content response.data.content; this.title response.data.title; // 渲染到阅读器组件 }后端爬虫的工作访问chapterUrl。根据书源规则定位正文所在的 HTML 元素如div#content。内容清洗移除无关元素广告、推荐阅读、脚本、样式标签、净化 HTML 标签、统一段落格式。可能进行简繁转换、修正错别字等后处理。将纯净的文本或 HTML 返回。6.4 整本下载核心价值实现在书籍详情页点击“下载全书”或类似按钮。async downloadBook(bookId, format epub) { const response await axios.post(/api/book/download, { bookId, format, // 可能包含章节范围 }, { responseType: blob }); // 重要请求二进制流 // 创建下载链接 const url window.URL.createObjectURL(new Blob([response.data])); const link document.createElement(a); link.href url; link.setAttribute(download, 《${this.bookInfo.name}》.${format}); document.body.appendChild(link); link.click(); link.remove(); window.URL.revokeObjectURL(url); }后端处理下载是一个异步任务接收下载请求验证参数。在数据库中创建一个“下载任务”记录状态为“处理中”。启动异步任务如通过Async注解或消息队列 a. 根据书源依次抓取所有章节内容可能需控制并发速度避免被封 IP。 b. 将所有章节内容、书籍元数据、封面图片等收集齐全。 c. 调用 EPUB/TXT 生成库如 Java 的epublibPython 的EbookLib按照标准格式组装文件。 d. 将生成的文件写入到挂载的卷目录如/app/downloads/《诡秘之主》.epub。 e. 更新数据库中的任务状态为“完成”并记录文件路径。前端可以轮询任务状态完成后即可通过另一个 API如/api/download/file/{taskId}获取到实际的文件。这就是 SoNovel 的核心闭环从互联网抓取 - 清洗 - 聚合 - 本地化存储。7. 高级配置与最佳实践部署成功只是第一步要让 SoNovel 稳定、安全、高效地运行还需要进行一些配置和优化。7.1 数据持久化与备份这是最重要的实践确保你的数据数据库、下载的小说文件在容器重建后不会丢失。检查 volumes 挂载确认docker-compose.yml中已将关键数据目录挂载到宿主机。./data/mysql:/var/lib/mysql数据库文件。./downloads:/app/downloads下载的小说文件。定期备份编写脚本定期备份./data和./downloads目录到其他存储或云盘。# 简单备份脚本示例 backup.sh #!/bin/bash BACKUP_DIR/path/to/your/backup PROJECT_DIR/home/user/sonovel DATE$(date %Y%m%d_%H%M%S) tar -czf $BACKUP_DIR/sonovel_backup_$DATE.tar.gz -C $PROJECT_DIR data downloads # 可以添加命令将备份文件上传到云存储 echo Backup completed: $BACKUP_DIR/sonovel_backup_$DATE.tar.gz使用crontab -e设置定时任务例如每周日凌晨3点执行0 3 * * 0 /bin/bash /path/to/backup.sh7.2 配置更新与版本升级SoNovel 项目会持续更新修复 bug 或增加新功能。拉取最新镜像cd ~/sonovel docker compose pull # 拉取 docker-compose.yml 中定义的最新镜像重启服务docker compose up -d # 使用新镜像重新创建容器数据库迁移如果新版本包含数据库结构变更后端服务启动时通常会通过 Flyway 或 Liquibase 等工具自动执行迁移脚本。确保在升级前备份数据库。回滚如果新版本有问题可以修改docker-compose.yml中的镜像标签回退到旧版本然后重新docker compose up -d。7.3 安全加固修改默认密码再次强调修改.env文件中的DB_ROOT_PASSWORD、DB_PASSWORD、JWT_SECRET等。限制访问防火墙如果部署在公网服务器使用防火墙如ufw只开放必要的端口如 80, 443。sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable反向代理不要直接将 Docker 容器的端口如 8080映射到公网。使用 Nginx 或 Caddy 作为反向代理绑定域名并配置 SSL 证书HTTPS。# Nginx 配置示例 (部分) server { listen 80; server_name novel.yourdomain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name novel.yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:80; # 指向 SoNovel 前端容器的宿主机端口 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 可选将 /api 代理到后端 # location /api { # proxy_pass http://localhost:8080; # } }定期更新关注项目安全更新及时升级镜像。7.4 性能优化调整爬虫速率在 SoNovel 的后端配置中通常可以设置请求延迟避免对源站造成过大压力也降低 IP 被封的风险。数据库优化对于书籍和章节数据量非常大的情况可以考虑为频繁查询的字段如书名、作者添加数据库索引。这可能需要你直接操作 MySQL 容器。docker exec -it sonovel-mysql mysql -u sonovel -p # 进入 MySQL 后 USE sonovel; CREATE INDEX idx_book_name ON book(name); CREATE INDEX idx_book_author ON book(author);资源限制在docker-compose.yml中可以为容器设置资源限制防止某个服务耗尽主机资源。services: backend: # ... 其他配置 deploy: resources: limits: cpus: 1.0 memory: 1G reservations: cpus: 0.5 memory: 512M8. 常见问题与排查思路部署和使用过程中你可能会遇到一些问题。以下是常见问题的排查指南。问题现象可能原因排查方式解决方案访问http://IP显示连接失败或无法访问1. 容器未成功启动。2. 端口被占用或防火墙阻止。3. 前端容器构建/运行失败。1.docker compose ps查看容器状态。2.docker compose logs frontend查看前端日志。3.netstat -tlnp | grep :80检查端口占用。4.sudo ufw status检查防火墙。1. 根据日志修复错误后重启。2. 修改docker-compose.yml中的端口映射如改为8081:80。3. 关闭防火墙或放行端口。前端能打开但搜索无结果或报错1. 后端服务未启动或异常。2. 数据库连接失败。3. 书源配置错误或全部失效。4. 网络问题导致无法访问源站。1.docker compose logs backend查看后端日志重点关注启动错误和数据库连接。2. 进入后端容器docker exec -it sonovel-backend sh尝试curl一个书源网站看网络是否通。3. 在前端检查书源管理测试单个书源。1. 检查.env中的数据库连接参数。2. 更新书源列表。3. 如果服务器在国内确保其能访问境外网站某些源站在外网。或寻找国内可用的书源。下载任务一直“处理中”或失败1. 下载目录挂载权限问题。2. 爬虫被源站屏蔽返回403/429。3. 生成 EPUB 文件的库依赖缺失。1.docker compose logs backend查看下载任务的具体错误。2. 检查宿主机./downloads目录的读写权限。3. 在日志中查看抓取章节时的 HTTP 状态码。1. 确保./downloads目录存在且 Docker 进程有写权限chmod 777 downloads或调整目录所有者。2. 在后端配置中增加请求延迟、使用随机 User-Agent。3. 检查后端镜像是否包含所有必要的依赖。数据库连接错误1. MySQL 容器启动失败。2. 密码错误。3. 后端连接字符串配置错误。1.docker compose logs mysql查看数据库日志。2. 进入 MySQL 容器验证密码docker exec -it sonovel-mysql mysql -u root -p。3. 检查后端环境变量SPRING_DATASOURCE_URL中的主机名是否为mysql容器服务名。1. 检查./data/mysql目录权限首次启动确保目录为空或正确初始化。2. 核对.env与docker-compose.yml中的密码变量名是否一致。3. 确保后端服务depends_on了 mysql并且网络配置正确。容器频繁重启1. 应用程序崩溃如 OOM。2. 健康检查失败。3. 依赖服务如数据库未就绪。1.docker compose ps查看重启次数和状态。2.docker inspect container_id查看退出原因。3.docker compose logs --tail100 service_name查看崩溃前的日志。1. 调整容器的内存限制见 7.4。2. 在docker-compose.yml中为后端添加restart: on-failure:5等策略。3. 确保使用depends_on并考虑使用healthcheck确保启动顺序。通用排查命令docker compose logs -f [service]实时查看服务日志。docker exec -it [container_name] sh进入容器内部。docker compose restart [service]重启单个服务。docker compose down docker compose up -d彻底停止并重新启动所有服务不会删除数据卷。9. 总结从工具到理念通过 Docker 部署 SoNovel你收获的不仅仅是一个私人小说库。这个实践过程是一次完整的、微缩版的现代应用部署演练理解容器化价值你亲身体验了 Docker 如何将复杂的多服务应用标准化、隔离化实现“一次构建处处运行”。掌握服务编排通过docker-compose.yml你定义了服务间的依赖、网络和数据流这是理解微服务架构的基础。直面真实问题从环境配置、网络调试、权限设置到故障排查你解决的问题正是运维工作中的日常。践行数据主权你将原本散落在互联网各处的数据通过技术手段归档到本地这是对数字时代“所有权”的一次具体实践。SoNovel 本身可能随着时间推移其内置的书源会失效但其架构思想和实现模式具有参考价值。你可以举一反三扩展思路能否为其添加音频朗读功能TTS能否集成 Calibre 进行更专业的电子书管理能否开发手机客户端技术深化研究其爬虫规则引擎学习如何编写一个健壮的解析器。分析其前后端分离的 API 设计。学习它如何使用异步任务处理耗时操作如下载。运维进阶尝试使用 Kubernetes 来管理 SoNovel实现高可用和自动伸缩。或者将其与自动化工具如 Watchtower集成实现自动更新。最后请记住技术是工具目的是服务于人。在享受自建服务带来的自由和掌控感的同时也请尊重版权合理使用。将 SoNovel 作为个人学习、研究和存档的工具避免用于任何商业或侵权用途。现在你的私人小说库已经上线。是时候去下载那些你一直想珍藏的故事了。如果在部署过程中遇到任何问题回顾本文的“常见问题”部分或者去该项目的开源社区寻找答案和同好。祝你阅读愉快