# home-theater **Repository Path**: creative-space_2/home-theater ## Basic Information - **Project Name**: home-theater - **Description**: 家庭影院 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-30 - **Last Updated**: 2026-03-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 家庭影院系统 基于 Spring Cloud Alibaba 的微服务架构家庭影院系统，提供完整的媒体管理、播放控制、智能相册等功能。 ## 技术栈 ### 后端框架 - **Spring Boot 3.2.0** - 核心框架 - **Spring Cloud 2023.0.0** - 微服务框架 - **Spring Cloud Alibaba 2023.0.0.0-RC1** - Alibaba 微服务生态 - **MyBatis Plus 3.5.5** - ORM 框架 ### 中间件 - **Nacos** - 服务注册与配置中心 - **Sentinel** - 流量治理、限流降级 - **Redis** - 缓存、分布式锁 - **MySQL 8.0** - 关系型数据库 ### 核心技术 - **FFmpeg** - 视频转码、媒体处理 - **DLNA/UPnP** - 设备发现与推送 - **OpenCV** - 图像识别、人脸识别 - **TMDB/豆瓣** - 媒体元数据刮削 ## 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 客户端层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ TV 端 │ │ 移动端 │ │ PC 端 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ API 网关层 │ │ api-gateway (端口：9000) │ │ IP 检查 │ 设备鉴权 │ 请求限流 │ 日志统一 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 微服务层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │用户设备服务 │ │ 存储服务 │ │ 媒体服务 │ │ │ │ (9001) │ │ (9002) │ │ (9003) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │播放转码服务 │ │ 相册服务 │ │ DLNA 发现服务 │ │ │ │ (9004) │ │ (9005) │ │ (9006) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ │ │ │ 定时任务服务 │ │ │ │ (9007) │ │ │ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 数据存储层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ MySQL │ │ Redis │ │ NAS │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 服务说明 ### 1. API 网关 (api-gateway) - **端口**: 9000 - **职责**: - 统一内网访问入口 - 内网域名路由 - 设备鉴权 - 请求限流 - 日志统一管理 - 禁止外网非法访问 - **家庭适配**: - 仅允许家庭内网 IP 段（192.168.x.x）访问 - 支持内网穿透安全校验 ### 2. 用户设备权限服务 (user-device-service) - **端口**: 9001 - **职责**: - 家庭多账号管理（管理员 / 成员 / 访客） - 设备绑定（电视、手机、电脑） - 权限管控（访客仅看相册，成员可看全部） - 设备上下线监听 - **家庭适配**: - 无需复杂注册，WiFi 自动识别家庭设备 - 一键绑定，访客模式限时访问 - **数据库**: 存储用户信息、设备列表、权限配置、家庭组信息 ### 3. 存储对接服务 (storage-service) - **端口**: 9002 - **职责**: - 统一对接 NAS 存储（NFS/SMB/WebDAV） - 本地硬盘对接 - 文件上传、下载、分片存储 - 文件去重、目录管理 - 屏蔽底层存储差异 - **家庭适配**: - 手机相册自动备份入口 - NAS 目录自动挂载 - 文件路径统一映射 - 支持断点续传 ### 4. 智能媒体服务 (media-service) - **端口**: 9003 - **职责**: - 全自动媒体刮削 - 视频元数据解析 - 海报/封面/字幕下载 - 电影/剧集/动漫/家庭录像自动分类 - 媒体信息管理 - **家庭适配**: - 定时扫描 NAS 新增视频 - 自动匹配 TMDB/豆瓣信息 - 生成影院级海报墙 - 支持手动修正信息 - **核心功能**: 4K 视频编码检测、音轨/字幕解析、剧集分集整理、媒体标签分类 ### 5. 播放控制转码服务 (play-transcode-service) - **端口**: 9004 - **职责**: - 播放进度持久化 - 多端进度同步 - 电视端遥控控制（播放/暂停/选集/音量） - 4K 智能转码 - 流媒体推送 - **家庭适配**: - 根据终端设备性能自动转码适配 - 新电视直放原盘，老设备转码流畅播放 - 进度实时同步至 Redis - **核心功能**: DLNA/AirPlay 推送、流媒体地址生成、转码任务调度、播放记录管理 ### 6. 智能相册服务 (album-service) - **端口**: 9005 - **职责**: - 照片自动整理 - EXIF 信息读取 - AI 人脸识别 - 地点聚类 - 时间线生成 - 照片瘦身 - 电视相册屏保接口 - **家庭适配**: - 家人照片自动分组 - 按年月/地点展示 - 支持照片分享 - 电视端轮播播放 - **核心功能**: 人像检索、照片备份校验、相册创建、幻灯片播放接口 ### 7. 设备发现服务 (dlna-discovery-service) - **端口**: 9006 - **职责**: - 内网自动发现电视、投影、音响等设备 - 无需手动配置 IP - 一键推送播放 - **家庭适配**: - 回家连 WiFi，手机自动扫描可播放设备 - 一键推送到电视 ### 8. 定时任务服务 (task-service) - **端口**: 9007 - **职责**: - NAS 文件定时扫描 - 相册自动备份同步 - 媒体库定时更新 - 转码任务清理 - 日志清理 - **家庭适配**: - 深夜低负载时执行扫描、转码任务 - 不影响白天使用 ## 快速开始 ### 环境要求 - JDK 17+ - Maven 3.8+ - Docker & Docker Compose - NAS 存储（可选） ### 部署步骤 #### 1. 克隆项目 ```bash git clone https://gitee.com/your-repo/home-theater.git cd home-theater ``` #### 2. 配置环境变量 ```bash cp .env.example .env # 编辑 .env 文件，配置实际的环境参数 vim .env ``` #### 3. 启动依赖服务 ```bash docker-compose up -d nacos mysql redis sentinel ``` 等待服务启动完成（约 1-2 分钟） #### 4. 初始化数据库 将 SQL 脚本复制到 MySQL 容器并执行： ```bash docker cp user-device-service/src/main/resources/sql/init.sql hometheater-mysql:/docker-entrypoint-initdb.d/ ``` #### 5. 启动所有微服务 ```bash docker-compose up -d ``` #### 6. 查看服务状态 ```bash docker-compose ps ``` #### 7. 访问控制台 - Nacos 控制台：http://localhost:8848/nacos - Sentinel 控制台：http://localhost:8718 - API 文档：http://localhost:9000/doc.html ## 配置说明 ### TMDB API Key 申请 1. 访问 https://www.themoviedb.org/settings/api 2. 注册账号并申请 API Key 3. 将 API Key 填入 `.env` 文件的 `TMDB_API_KEY` 配置项 ### NAS 存储挂载 修改 `docker-compose.yml` 中的存储卷映射： ```yaml volumes: - /your/nas/path:/mnt/nas/home-theater ``` ### FFmpeg 硬件加速 根据 CPU 类型选择硬件加速方式： - Intel: `HWACCEL_METHOD=vaapi` - NVIDIA: `HWACCEL_METHOD=nvenc` - Intel QuickSync: `HWACCEL_METHOD=qsv` - 禁用：`HWACCEL_METHOD=disabled` ## API 文档 各服务的 API 文档通过 Knife4j 提供，访问格式： ``` http://gateway-host:port/doc.html ``` 例如： - 用户服务：http://localhost:9001/doc.html - 存储服务：http://localhost:9002/doc.html - 媒体服务：http://localhost:9003/doc.html ## 开发指南 ### 本地开发环境 1. 启动 Nacos、MySQL、Redis 2. 修改各服务的 `bootstrap.yml` 配置 3. 运行各服务的 Application 主类 ### 模块依赖关系 ``` common-module (公共模块) ├── api-gateway ├── user-device-service ├── storage-service ├── media-service ├── play-transcode-service ├── album-service ├── dlna-discovery-service └── task-service ``` ## 常见问题 ### Q1: 外网无法访问？ A: 系统默认只允许内网 IP 访问（192.168.x.x），如需外网访问需要： 1. 配置内网穿透（如 frp、ngrok） 2. 在网关服务中修改 IP 检查过滤规则 ### Q2: 转码速度慢？ A: 优化建议： 1. 启用硬件加速（VA-API/NVENC/QSV） 2. 增加转码线程数 3. 降低转码质量要求 ### Q3: 设备无法被发现？ A: DLNA 发现需要： 1. 确保设备和服务器在同一局域网 2. 检查防火墙是否开放 1900 端口 3. Docker 需要使用 host 网络模式 ## 许可证 MIT License ## 联系方式 - 项目地址：https://gitee.com/your-repo/home-theater - Issue 反馈：https://gitee.com/your-repo/home-theater/issues