# article

**Repository Path**: zhengbaitech/article

## Basic Information

- **Project Name**: article
- **Description**: 墨阅读书网站,包含用户端和管理端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 墨阅 · 网文平台(读者端 + 管理端)

Web 版网文/小说平台:管理端两级管理(书籍管理 → 章节管理),章节可逐章粘贴/上传创建、单独编辑删除,也支持批量导入整篇自动拆分、多选合并到卷;读者端浏览书库、按卷分组目录、在线阅读。前后端打包在同一个可执行 JAR 中,一条命令即可部署,数据落盘重启不丢。

## 功能

### 读者端(`/`)
- **书库**:卡片式书籍列表(渐变占位封面 + 竖排书名、分类标签、字数、简介、更新时间),按更新时间排序
- **分类筛选 + 搜索**:按书名/作者/简介关键词实时搜索,分类 chips 一键筛选
- **书架**:基于浏览器 localStorage,详情页一键加入/移出
  - **书籍详情**:封面、作者、分类、字数、章节数、简介,「开始阅读 / 继续阅读」(自动定位上次读到的章节)、章节目录(按卷分组展示;超过 30 章折叠,可展开全部)
- **阅读页**(参考主流小说平台):
  - **目录抽屉**(参考主流小说平台):章节**两列网格**排列、卷名分段;**正序/倒序**切换(偏好记忆);**搜索框**——输入文字过滤章节标题、输入章节号回车直接跳转;当前章高亮并自动滚动定位
  - 正文宋体、首行缩进 2em、舒适行距;章节标题居中 + 字数/进度提示
  - **四种背景主题**:白 / 米黄 / 护眼绿 / 夜间;**字号调节** 14–26px,偏好自动记忆
  - 上一章/下一章、键盘 ←/→ 翻章
  - **阅读进度记忆**:按书记录章节 + 滚动位置,刷新/下次进入自动恢复;首页卡片显示「读到 x/y」

### 管理端(`/admin/`)
- **登录验证**:账号密码登录(默认 `admin / admin123`,可在 application.properties 修改),HttpOnly Cookie 会话,7 天有效;所有管理接口经过滤器保护,未登录返回 401
- **书籍管理**(`/admin/`):书籍列表(标题/作者/分类/字数/章节数/更新时间)、搜索、元数据编辑、删除(二次确认)、新窗口预览;添加书籍仅需标题等元数据,章节随后在章节管理中维护
- **章节管理**(`/admin/chapters.html?id=…`):
  - **章节列表**:序号/标题/卷/字数,按卷分组展示(卷分隔行),勾选支持全选
  - **单章添加**:弹窗填写标题/所属卷 + 粘贴正文,或**上传单个 txt 填充本章**(自动识别 UTF-8/GB18030 编码,自动去除文件内的章节标题行);追加到列表末尾
  - **单章编辑/删除**:任意章节可单独修改标题、卷、正文或删除;删除后后续章节自动前移编号
  - **批量导入**:粘贴或上传整篇 txt/md,按「第X章/节/回、序章、楔子、番外」等标题行(或 Markdown 标题)自动拆分为章节后追加
  - **合并到卷**:勾选多个章节 → 输入/选择卷名批量归入;卷名留空即移出卷(未分卷)

## 构建与部署

环境要求:JDK 17+(本机验证使用 JDK 21)、Maven 3.6+。

```bash
mvn package -DskipTests
```

生成可执行 JAR:`target/article.jar`。

```bash
# 默认 8081 端口
java -jar article.jar

# 指定端口
java -jar article.jar --server.port=9000
```

- 读者端:`http://<IP>:<端口>/`
- 管理端:`http://<IP>:<端口>/admin/`(admin / admin123)

### 数据目录与部署配置

文章数据默认保存在**启动目录**下的 `data/articles/*.json`,实时落盘,重启自动加载;无需数据库。部署时数据目录(以及端口、管理端账号)都可另行配置,三种方式任选:

```bash
# 方式一:启动参数
java -jar article.jar --article.data-dir=/var/lib/moyue/data

# 方式二:环境变量(Spring Boot 宽松绑定)
ARTICLE_DATADIR=/var/lib/moyue/data java -jar article.jar

# 方式三:外置配置文件(适合生产:把数据目录、端口、账号集中在一个文件里管理)
java -jar article.jar --spring.config.additional-location=file:/etc/moyue/application.properties
```

外置配置文件里可覆盖的常用项:

```properties
server.port=8081
article.data-dir=/var/lib/moyue/data
admin.username=admin
admin.password=改成强密码
```

> 启动日志会打印 `[ArticleStore] 数据目录: …`(绝对路径),可据此确认落盘位置。静态资源每次协商校验(未变更返回 304),升级 JAR 后浏览器不会使用旧页面。

## 技术栈

- 后端:Spring Boot 3.3(嵌入式 Tomcat),无其他依赖
- 前端:原生 HTML / CSS / JavaScript,无任何第三方依赖,全部静态资源内嵌 JAR
- 存储:文章以 JSON 文件按篇落盘(`data/articles/`),内存全量持有 + 原子写入
- 鉴权:内存 token + HttpOnly Cookie,Servlet Filter 保护 `/api/admin/**`

## API 一览

公开接口(读者端):

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/books?keyword=&category= | 书库列表(不含正文),支持关键词/分类 |
| GET | /api/books/{id} | 书籍详情 + 章节目录 |
| GET | /api/books/{id}/chapters/{index} | 章节正文 |

管理接口(需登录,除 login 外均校验 Cookie):

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/admin/login | 登录 {username, password} |
| POST | /api/admin/logout | 退出登录 |
| GET | /api/admin/books | 书籍列表 |
| GET | /api/admin/books/{id} | 详情(含章节列表,含卷名) |
| POST | /api/admin/books | 创建书籍 {title, author, category, description, content?}(content 可选,传入则整篇拆分) |
| PUT | /api/admin/books/{id} | 更新元数据(content 可选,传入则整篇重新拆分替换全部章节) |
| DELETE | /api/admin/books/{id} | 删除书籍(含全部章节) |
| GET | /api/admin/books/{id}/chapters | 章节列表(序号/标题/卷/字数) |
| GET | /api/admin/books/{id}/chapters/{index} | 单章详情(含正文) |
| POST | /api/admin/books/{id}/chapters | 追加单章 {title, content, volume?} |
| PUT | /api/admin/books/{id}/chapters/{index} | 更新单章(字段可选;volume 空串=未分卷) |
| DELETE | /api/admin/books/{id}/chapters/{index} | 删除单章(后续章节自动重编号) |
| POST | /api/admin/books/{id}/chapters/import | 批量导入 {content}:整篇按标题拆分后追加,返回 added |
| PUT | /api/admin/books/{id}/chapters/volumes | 合并到卷 {indexes:[…], volume}(volume 空串=移出卷) |
| POST | /api/admin/upload | 上传 txt/md(multipart),返回解码文本 |

## 项目结构

```
src/main/java/com/zb/article/
├── ArticleApplication.java        # 启动类
├── config/
│   └── PageConfig.java            # 页面路由:/admin/ 转发 index.html、/book /read 简洁链接
├── model/
│   ├── Article.java               # 文章(含 chapters,字数/章节数派生)
│   └── Chapter.java               # 章节(标题/正文/字数)
├── store/
│   └── ArticleStore.java          # 内存 + JSON 落盘(原子写入,启动加载)
├── util/
│   └── TextUtil.java              # 编码识别(UTF-8/GB18030)、章节切分、字数统计
└── web/
    ├── AuthService.java           # 登录 token(内存,7 天有效)
    ├── AuthFilter.java            # /api/admin/** 鉴权过滤器
    ├── ReaderApiController.java   # 读者端公开接口
    └── AdminApiController.java    # 管理端接口(登录/增删改查/上传)
src/main/resources/static/
├── index.html / js/home.js        # 读者端首页(书库/书架/分类/搜索)
├── book.html / js/book.js         # 书籍详情(目录、开始/继续阅读、书架)
├── read.html / js/read.js         # 阅读页(主题/字号/目录抽屉/进度记忆)
├── css/style.css                  # 读者端全部样式(含响应式)
├── js/common.js                   # 公共工具(API、格式化、书架/进度/偏好、toast)
└── admin/
    ├── index.html                 # 管理端·书籍管理(登录 + 书籍列表/元数据弹窗)
    ├── admin.css / admin.js       # 管理端公共样式与书籍管理逻辑
    ├── chapters.html              # 章节管理(章节列表/单章增删改/单章上传/批量导入/合并到卷)
    └── chapters.js                # 章节管理逻辑
```

### 二次开发提示

- 章节切分规则集中在 `TextUtil.CHAPTER_PATTERN`,调整正则即可支持更多标题格式;
- 管理端账号在 `application.properties` 的 `admin.username` / `admin.password`;
- 新增页面只需在 `static/` 下放文件,`PageConfig` 中按需加一条转发路由。