From 929914575d9c342c1bf57459a332085c1048d5a9 Mon Sep 17 00:00:00 2001 From: congruity <1151207663@qq.com> Date: Sat, 27 Jun 2026 12:12:53 +0800 Subject: [PATCH] readme --- README.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a23ac0b --- /dev/null +++ b/README.md @@ -0,0 +1,153 @@ +# 墨香阁 · 小说阅读 + +> 一个轻量的个人电子书阅读应用。后端基于 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 + +仅供个人学习与使用。