# novel

**Repository Path**: yanyong1/novel

## Basic Information

- **Project Name**: novel
- **Description**: 个人使用的小说阅读
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 墨卷小说阅读平台

一个使用 **Umi + Ant Design** 与 **FastAPI** 构建的小说阅读平台。读者可以浏览、搜索、阅读和收藏作品；作者可创建作品与章节并提交审核；编辑审核内容；管理员管理用户、角色、菜单、分类、推荐及系统配置。

## 数据存储说明

- PostgreSQL：唯一业务数据库，章节正文保存在 `chapters.content`（`TEXT`）中，并以原始 UTF-8 文本写入和读取。
- Elasticsearch：可选搜索服务；未启用时，书城搜索自动回退到 PostgreSQL 查询。
- Docker Compose 使用命名卷保存 PostgreSQL 和 Elasticsearch 数据，重新构建镜像不会删除业务数据。

## Docker Compose 编排构建（推荐）

### 1. 准备配置

```powershell
cd C:\code\myself\novel\infra
Copy-Item .env.example .env
```

编辑 `infra/.env`，至少替换：

- `POSTGRES_PASSWORD`：使用 URL 安全字符组成的数据库密码。
- `JWT_SECRET`：长度不少于 32 字节的随机密钥。

`infra/.env` 已被 Git 忽略，不得提交真实密码或密钥。

### 2. 构建并启动核心服务

```powershell
docker compose --env-file .env up -d --build
```

该命令会按依赖顺序启动：

1. PostgreSQL 健康检查通过；
2. FastAPI 初始化数据库结构、基础账号和系统数据；
3. 管理后台与读者站完成健康检查并对外提供服务。

| 服务 | 地址 |
| --- | --- |
| API | `http://localhost:9000` |
| 管理后台 | `http://localhost:9001` |
| 读者站 | `http://localhost:9002` |

管理后台和读者站都通过 Nginx 将 `/api` 同源代理到 FastAPI，登录 Cookie 不需要跨域配置。

### 3. 可选：启用 Elasticsearch

```powershell
docker compose --env-file .env -f docker-compose.yml -f docker-compose.search.yml --profile search up -d --build
```

启用后 Elasticsearch 地址为 `http://localhost:9200`，API 会使用 `novel_books` 索引；不启用时继续使用 PostgreSQL 搜索。

### 4. 查看状态和日志

```powershell
docker compose --env-file .env ps
docker compose --env-file .env logs -f api
docker compose --env-file .env logs -f admin-web reader-web
```

使用搜索编排时，状态、日志和停止命令都应同时带上两个 Compose 文件和 `--profile search`。

### 5. 重新构建或停止

```powershell
# 代码更新后重新构建并滚动启动
docker compose --env-file .env up -d --build

# 停止并移除容器，保留数据库卷
docker compose --env-file .env down
```

只有明确需要清空 Docker 数据库和搜索索引时才执行以下命令：

```powershell
docker compose --env-file .env down -v
```

> `down -v` 会永久删除 Compose 命名卷中的全部数据，无法恢复。

## 阿里云 ECS 部署

Alibaba Cloud Linux 3/4、宿主机 PostgreSQL、2 核 2GB 的部署方式请参阅 [阿里云 ECS 部署手册](docs/ecs-deployment.md)。ECS 专用编排不会启动 PostgreSQL 或 Elasticsearch，真实密钥只保存在未提交的 `infra/.env.ecs`。

## 本地开发运行

### 一键启动

在已完成 Python 虚拟环境、依赖安装和 `services/api/.env` 配置后，双击根目录 `start.bat`，或执行：

```powershell
.\start.bat
```

该脚本会分别启动 API、管理后台和读者站，地址为 `http://localhost:9000`、`http://localhost:9001` 和 `http://localhost:9002`。前端使用已安装的本地 `@umijs/max` CLI，需要 Node.js 20。

### 手动启动后端

需要 Python 3.11+：

```powershell
cd C:\code\myself\novel\services\api
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env
uvicorn app.main:app --reload --port 9000
```

### 手动启动前端

管理后台和读者站均使用 Node.js 20 与 pnpm：

```powershell
cd C:\code\myself\novel\apps\admin-web
pnpm install
pnpm dev

cd C:\code\myself\novel\apps\reader-web
pnpm install
pnpm dev
```

## 基础账号

全新数据库首次启动时会创建以下本地基础账号：

| 身份 | 用户名 | 初始密码 |
| --- | --- | --- |
| 读者 | `reader` | `123456` |
| 作者 | `author` | `123456` |
| 编辑 | `editor` | `123456` |
| 管理员 | `admin` | `123456` |

这些账号仅用于本地初始化；部署到可公开访问的环境前必须修改密码或替换账号。

## 验证

```powershell
cd C:\code\myself\novel\services\api
pytest

cd C:\code\myself\novel\apps\reader-web
pnpm test
pnpm build

cd C:\code\myself\novel\apps\admin-web
pnpm test
pnpm build
```

## 主要 API 分组

- `/api/v1/auth`：注册、登录、刷新令牌、当前身份和个人资料。
- `/api/v1/books`：书城、搜索、榜单、详情、目录、阅读、书架和进度。
- `/api/v1/author`：作者作品、章节与审核提交。
- `/api/v1/editor`：作品和章节审核。
- `/api/v1/admin`：用户、角色、菜单、分类、推荐、系统配置、内容治理和审计日志。
- `/api/v1/openapi.json`：自动生成的接口定义。