154 lines
4.6 KiB
Markdown
154 lines
4.6 KiB
Markdown
# 墨香阁 · 小说阅读
|
||
|
||
> 一个轻量的个人电子书阅读应用。后端基于 Spring Boot + MongoDB，前端为内置的 PWA（可「添加到主屏幕」当作原生 App 使用），适合部署在 NAS、轻量服务器等小内存设备上。
|
||
|
||
## 功能特性
|
||
|
||
- 📚 **书库浏览**：关键词 / 标签搜索、搜索建议、热门标签、随机推荐
|
||
- 📖 **沉浸阅读**：章节翻页、上一章 / 下一章、阅读进度记忆
|
||
- ⭐ **个人书架**：收藏小说，一键查看是否已收藏
|
||
- 🔖 **书签**：按小说记录书签位置
|
||
- 🕘 **阅读历史**：自动记录最近阅读
|
||
- 📱 **PWA 支持**：Service Worker 离线缓存、可安装到手机主屏
|
||
- 📑 **接口文档**：内置 Swagger UI，方便调试
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| 运行环境 | Java 8 |
|
||
| 框架 | Spring Boot 2.7.18 |
|
||
| 数据库 | MongoDB（Spring Data MongoDB） |
|
||
| 模板引擎 | Thymeleaf |
|
||
| 接口文档 | springdoc-openapi-ui 1.7.0 |
|
||
| 工具 | Lombok |
|
||
| 前端 | 原生 HTML / CSS / JavaScript + PWA |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/
|
||
├── java/com/novelreader/
|
||
│ ├── NovelReaderApplication.java # 启动类
|
||
│ ├── config/ # MongoDB 索引等配置
|
||
│ ├── controller/ # REST 接口 + 页面路由
|
||
│ ├── service/ # 业务逻辑
|
||
│ ├── repository/ # MongoDB 数据访问
|
||
│ ├── model/ # 数据库实体（novelDO / chapterDO / ...）
|
||
│ └── dto/ # 传输对象
|
||
└── resources/
|
||
├── application.yml # 配置文件
|
||
├── templates/index.html # 单页应用入口
|
||
└── static/ # css / js / manifest / service worker
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- JDK 8、Maven 3.6+
|
||
- 一个可访问的 MongoDB 实例
|
||
|
||
### 本地运行
|
||
|
||
1. 修改 `src/main/resources/application.yml` 中的 MongoDB 连接：
|
||
|
||
```yaml
|
||
spring:
|
||
data:
|
||
mongodb:
|
||
uri: mongodb://用户名:密码@地址:端口/数据库名
|
||
```
|
||
|
||
2. 启动：
|
||
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
3. 打开浏览器访问 `http://localhost:8080`。
|
||
|
||
### 打包
|
||
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
java -jar target/server-0.0.1-SNAPSHOT.jar
|
||
```
|
||
|
||
## 数据模型
|
||
|
||
应用读取 MongoDB 中已有的小说数据，主要集合：
|
||
|
||
- **novelDO**：小说信息（`name`、`author`、`cover`、`status`、`synopsis`、`tags` 等）
|
||
- **chapterDO**：章节内容（`novelId`、`index`、`title`、`content`）
|
||
|
||
书架、书签、历史等用户数据存储在各自对应的集合中。
|
||
|
||
## API 概览
|
||
|
||
接口文档（Swagger UI）：启动后访问 `http://localhost:8080/swagger-ui.html`
|
||
|
||
| 模块 | 前缀 | 说明 |
|
||
|------|------|------|
|
||
| 小说 | `/api/novels` | 搜索、详情、搜索建议、章节列表、热门标签、随机推荐 |
|
||
| 章节 | `/api/chapters` | 按 ID / 小说获取章节，首章、上一章、下一章 |
|
||
| 书架 | `/api/shelf` | 收藏列表、添加、移除、是否已收藏 |
|
||
| 历史 | `/api/history` | 历史列表、上报阅读记录、删除 |
|
||
| 书签 | `/api/bookmarks` | 书签列表、新增、删除 |
|
||
|
||
## Docker 部署
|
||
|
||
项目提供多阶段构建的 `Dockerfile` 与 `docker-compose.yml`，适合在 NAS 上一键部署。
|
||
|
||
### 使用 docker-compose（推荐）
|
||
|
||
1. 修改 `docker-compose.yml` 中的 MongoDB 地址与内存参数：
|
||
|
||
```yaml
|
||
environment:
|
||
- SPRING_DATA_MONGODB_URI=mongodb://你的MongoDB地址:端口/数据库名
|
||
- JAVA_OPTS=-Xms128m -Xmx256m -XX:+UseG1GC
|
||
- TZ=Asia/Shanghai
|
||
```
|
||
|
||
2. 构建并启动：
|
||
|
||
```bash
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
3. 查看日志 / 状态：
|
||
|
||
```bash
|
||
docker-compose logs -f
|
||
docker-compose ps
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `SPRING_DATA_MONGODB_URI` | MongoDB 连接地址 | `mongodb://192.168.18.100:38403/novel` |
|
||
| `JAVA_OPTS` | JVM 参数 | `-Xms128m -Xmx256m -XX:+UseG1GC` |
|
||
| `TZ` | 时区 | `Asia/Shanghai` |
|
||
|
||
### 内存调优建议
|
||
|
||
根据设备可用内存调整 `JAVA_OPTS`：
|
||
|
||
| 可用内存 | 推荐参数 |
|
||
|----------|----------|
|
||
| 1GB | `-Xms128m -Xmx256m` |
|
||
| 2GB | `-Xms256m -Xmx512m` |
|
||
| 4GB+ | `-Xms512m -Xmx1024m` |
|
||
|
||
> 另提供 `Dockerfile.china`（国内镜像加速）与 `Dockerfile.simple`（基于已有 jar 的精简构建）两种变体，可按需选用。
|
||
|
||
## 安装到手机
|
||
|
||
部署成功后，在手机浏览器（iOS 用 Safari）打开 `http://服务器IP:8080`，点击「分享 → 添加到主屏幕」，即可像原生 App 一样使用。
|
||
|
||
## License
|
||
|
||
仅供个人学习与使用。
|