# eh-FM

**Repository Path**: MISSMYSEIF/eh-fm

## Basic Information

- **Project Name**: eh-FM
- **Description**: 一款FM
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EH-FM

> 音频/播客内容管理平台 —— 支持音频上传、频道/专辑/分类管理、评论、收藏、播放历史、搜索与后台 RBAC。

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Backend](https://img.shields.io/badge/Backend-Spring%20Boot%203.2-brightgreen.svg)](#)
[![Frontend](https://img.shields.io/badge/Frontend-Vue%203-brightgreen.svg)](#)
[![DB](https://img.shields.io/badge/Database-SQLite%20%2F%20MySQL-blue.svg)](#)

## 功能特性

- 用户体系：注册、登录（JWT）、个人信息与密码管理
- 内容管理：音频、专辑、频道、多级分类的增删改查
- **AI 摘要**：音频详情页自动生成导听摘要（OpenAI 兼容 LLM 可配，未配置自动本地降级，结果缓存）
- 播放器：全局常驻（倍速、±15 秒快进快退、睡眠定时器、键盘快捷键、锁屏媒体控制）、**播放队列插播**
- 自由标签：音频/专辑/频道可自由打标，列表与搜索支持按标签过滤
- 互动：评论（支持回复、表情与快捷回复、**点赞**）、收藏、**频道订阅推送**（订阅频道更新后站内通知，支持全局开关与按频道免打扰）、播放历史、搜索历史
- 个性化推荐：基于播放历史/收藏的协同过滤推荐流（冷启动回退热门）
- 播放进度可视化：列表/搜索结果卡片按已听时长渲染进度条，当前曲目播放时实时跟随
- 音频批量导入：后台拖拽本地目录/多选文件，自动过滤音频、解析时长、可编辑标题后串行导入并逐条反馈结果
- 移动端深度适配：底部 Tab 导航 + 迷你播放条 + 全屏「正在播放」，安全区/`dvh`/触屏反馈，渲染级切换而非仅响应式
- 播放器：全局播放控制，**播放列表支持拖拽排序**（原生 HTML5 drag/drop，无第三方依赖）；**倍速播放**（0.75x~2.0x）、**±15s 快进快退**、**睡眠定时器**（15/30/60/90 分钟自动暂停）、**键盘快捷键**（Space/←→/↑↓）、**系统级播控**（Media Session：锁屏/蓝牙耳机）、音量/模式/倍速本地持久化
- 文件存储：基于 MinIO 的对象存储，图片/头像上传前校验真实文件头
- 后台管理：RBAC 角色权限、审计日志
- 多数据库：**默认 SQLite（零外部依赖）**，可切换 MySQL
- 限流与安全：Redis 接口限流、CORS 可配置、存储型 XSS 防护
- API 文档自动化：SpringDoc OpenAPI 从代码生成 Swagger UI 与 `/v3/api-docs`（含前台/后台分组），替代手写接口清单

## 技术栈

| 层 | 技术 |
| --- | --- |
| 后端 | Spring Boot 4.1（Java 17）、MyBatis-Plus 3.5、JJWT 0.12、MinIO SDK、Spring Data Redis |
| 前端 | Vue 3、Vite 6、Element Plus、Pinia、Vue Router、Axios |
| 存储 | SQLite（默认）/ MySQL；MinIO（文件）；Redis（限流/缓存） |

## 快速开始

### 1. 启动依赖（Redis + MinIO）

```bash
docker compose up -d
```

### 2. 构建（本机一次性完成，脚本不负责编译）

```bash
mvn -f eh-fm-server package -DskipTests
npm -C eh-fm-web install
```

### 3. 一键启动 / 停止（Windows）

```bat
start.bat   :: 启动后端(8080) 与前端(3000)
stop.bat    :: 停止服务并关闭容器
```

手动方式：

```bash
mvn -f eh-fm-server spring-boot:run     # 后端，默认 SQLite
npm -C eh-fm-web run dev                # 前端
```

### 默认管理员账号

| 账号 / 手机号 | 密码 |
| --- | --- |
| `admin` | `admin123`（仅 dev 默认；prod 经 `ADMIN_INIT_PASSWORD` 注入） |

该账号在后端首次启动时自动初始化（已存在则跳过），拥有全部后台权限。prod profile 强制要求 `ADMIN_INIT_PASSWORD` 环境变量，未设置时启动即失败。

## API 文档（自动生成）

接口文档由 **SpringDoc OpenAPI** 从代码自动生成，不再手工维护接口清单（`docs/api/api-reference.md` 已改为「自动生成 + 语义补充」入口）：

| 入口 | 地址 |
| --- | --- |
| Swagger UI（交互式调试） | http://localhost:8080/swagger-ui.html |
| OpenAPI 规范 JSON（全部 / 前台 / 后台） | `/v3/api-docs`、`/v3/api-docs/front`、`/v3/api-docs/admin` |
| OpenAPI 规范 YAML | `/v3/api-docs.yaml` |

登录后点击 Swagger UI 右上角 **Authorize** 填入 `token` 即可调试受保护接口（无需手写 `Bearer` 前缀）。
归档导出：`scripts/export-openapi.sh`（Windows：`scripts\export-openapi.bat`）。
生产 profile 默认关闭文档，需临时查看时设置 `SPRINGDOC_ENABLED=true`。

## 多数据库

- **默认即 SQLite**：项目根目录生成 `ehfm.db` 文件，无需任何数据库服务。
- 切换 MySQL：启动时指定 profile `mysql` 或 `prod`（见 [docs/integrations/database.md](docs/integrations/database.md)）。

## 项目结构

```
eh-fm/
├─ eh-fm-server/        # 后端（Spring Boot）
├─ eh-fm-web/           # 前端（Vue 3）
├─ docs/                # 文档（分类存放，详见下方）
├─ tests/               # Python 集成测试
├─ docker-compose.yml   # 本地依赖服务
├─ start.bat / stop.bat # Windows 一键脚本
├─ LICENSE              # MIT
└─ README.md / README.en.md
```

## 测试

- 后端单测：`mvn -f eh-fm-server test`（259 项，离线可跑）
- 前端单测：`npm -C eh-fm-web run test`（60 项）
- 端到端集成测试：见 [tests/README.md](tests/README.md)（需本地起全部依赖，使用真实数据）

## 文档

完整文档位于 [`docs/`](docs/README.md)，按主题分类：

- 快速开始 / 环境要求：`docs/getting-started/`
- 架构 / 数据模型：`docs/architecture/`
- 第三方集成（MinIO / Redis / 数据库 / JWT）与**二次开发教程**：`docs/integrations/`、`docs/guides/`
- 部署、API 参考（自动生成）、安全审计：`docs/deployment/`、`docs/api/`、`docs/SECURITY.md`
- 变更日志（版本+日期）：`docs/CHANGELOG.md`

## 部署

生产建议 MySQL + 反向代理（Nginx）。详见 [docs/deployment/deploy.md](docs/deployment/deploy.md)。

## 安全说明

- 生产环境务必通过环境变量覆盖 `JWT_SECRET`、`MINIO_*`、`DB_PASSWORD` 等密钥。
- 默认管理员密码：dev 默认 `admin123`；prod 必须通过 `ADMIN_INIT_PASSWORD` 环境变量注入（未设置启动失败），上线后请尽快修改密码。
- 依赖版本与安全建议见 [docs/SECURITY.md](docs/SECURITY.md)。

## 许可证

本项目基于 [MIT](LICENSE) 许可证开源。