你的私人家庭影音中心 | Your Personal Home Media Center
快速开始 •
English •
配置 •
API •
开发
一个基于 Go + React 构建的轻量级家庭媒体服务器，类似 Emby / Jellyfin，专为 NAS 部署优化。
单二进制 + SQLite，Docker 一键启动，零配置即可使用。
A lightweight home media server built with Go + React , similar to Emby / Jellyfin, optimized for NAS deployment.
Single binary + SQLite, one-click Docker startup, zero configuration required.
中文
English
自动扫描目录中的视频文件（MKV / MP4 / AVI / MOV / WebM 等 9 种格式）
使用 FFprobe 自动提取视频编码、分辨率、时长等元数据
自动发现同目录下的外挂字幕文件（SRT / ASS / SSA / VTT / SUB）
支持自动发现海报图片（同名 JPG/PNG/WebP、poster、cover、folder）
支持 NFO 文件解析（优先读取本地 NFO 元数据和图片）
媒体库级别高级设置：最小文件过滤、元数据语言、成人内容控制
实时文件监控（基于 fsnotify），新增/修改/删除文件自动同步
启动时自动清理孤立数据，保持数据一致性
直接播放 — MP4 / WebM / M4V 等浏览器兼容格式零延迟直接播放，支持 Range 请求HLS 转码播放 — MKV / AVI 等不兼容格式自动按需转码为 HLS 自适应流，支持多码率（360p / 480p / 720p / 1080p）智能模式选择 — 前端自动检测文件格式，优先直接播放，不兼容时走 HLS 转码全功能播放器控制栏：播放/暂停、进度拖动、音量调节、全屏、画质切换
键盘快捷键：空格/K 播放暂停、←→ 快进快退、↑↓ 音量、F 全屏、M 静音
视频书签功能：在任意时间点添加书签和备注，快速跳转
自动检测可用硬件加速方式（启动时检测 FFmpeg 编码器能力）
支持 Intel QSV / VAAPI / NVIDIA NVENC / 软件编码（libx264 兜底）
可配置转码预设和并发任务数，NAS 低功耗设备友好
转码缓存机制，相同质量只需转码一次
转码任务监控与取消
项目采用 Provider Chain（多数据源调度链） 架构，按优先级自动调度多个数据源：
优先级
数据源
说明
10
TMDb 主数据源，电影/剧集元数据
20
豆瓣 补充源，TMDb 失败或信息不完整时自动回落
25
TheTVDB 剧集增强源，获取电视剧集的详细元数据
30
Bangumi 动画专项源，番剧/动画元数据
50
Fanart.tv 图片增强源，高质量 ClearLogo、背景图、光碟封面
100
AI 兜底源，当所有传统数据源失败时用 AI 生成简介和标签
自动匹配电影/剧集，获取海报、简介、评分、类型标签
剧集合集级刮削 — 以合集名称搜索，元数据自动同步到各集
支持从文件名智能提取搜索关键词和年份
自动清理文件名中的 BluRay / x264 / 1080p 等标记
API Key 可在管理后台在线配置，无需重启
刮削任务管理 — 批量创建/执行/翻译刮削任务，支持进度追踪和历史记录手动元数据匹配 — 管理员可手动搜索并匹配 TMDb / Bangumi / 豆瓣 / TheTVDB 元数据，匹配后自动同步标题元数据编辑 — 支持在线编辑媒体/剧集的标题、简介、评分等信息图片管理 — 支持上传、URL 设置、TMDb 图片选择三种方式更换海报/背景图
基于文件夹的剧集自动识别（每个子目录 = 一部剧集）
支持常见剧集命名格式：S01E01 / 1x01 / 第01集 / EP01 / Episode 01 / E01
自动提取季号（Season）和集号（Episode）
支持 Season XX / S01 / 第1季 / Specials 目录结构
支持层级目录（剧集名/Season XX/视频文件）和扁平化目录
自动创建剧集合集条目，保持播放顺序
季视图和全部剧集视图两种浏览模式
剧集详情页（Banner + 海报 + 简介 + 季切换 + 集列表）
下一集查询接口（用于连续播放）
自动扫描外挂字幕文件（SRT / ASS / SSA / VTT / SUB）
读取视频内嵌字幕轨道信息（通过 FFprobe）
按需提取内嵌字幕为 WebVTT 格式供浏览器使用
从文件名自动检测字幕语言（中 / 英 / 日 / 韩等）
在线字幕搜索与自动下载
家庭成员独立账号，支持管理员/普通用户角色
每用户独立的观看历史、播放进度记录
每用户独立的收藏夹
自定义播放列表（创建、添加、排序、删除）
播放进度自动上报（每 15 秒），换设备续播
细粒度权限控制 — 按用户设置可访问的媒体库、内容分级限制、每日观看时长内容分级 — 支持 G / PG / PG-13 / R / NC-17 分级标记评论与评分 — 用户可对媒体发表评论和打分
扫描进度实时推送（新发现文件数、当前处理文件名）
元数据刮削进度实时推送（当前/总数、成功/失败计数、进度条）
转码进度实时推送（百分比进度 + FFmpeg 转码速度）
自动重连机制（断线后 3 秒自动重连，最多 10 次）
心跳保活（Ping/Pong，60 秒超时断开）
活动日志流（管理后台实时展示最近操作记录）
集成 LLM（大语言模型），支持 OpenAI / DeepSeek / 通义千问 / Ollama 等 OpenAI 兼容 API：
AI 智能搜索 — 自然语言查询转结构化搜索参数（如"找一部关于太空的科幻片"）AI 推荐理由 — 为推荐结果生成个性化推荐文案AI 元数据增强 — 当传统数据源全部失败时，用 AI 生成简介和标签AI 文件重命名 — 智能分析文件名并生成规范化重命名建议AI 助手 — 管理后台内置 AI 对话助手，支持自然语言操作媒体库
分析错误分类的文件
执行批量重分类操作
操作可撤销
结果缓存机制，避免重复调用
可配置月度预算上限、并发数、请求间隔
基于观看历史、收藏、类型偏好的个性化推荐
相似媒体推荐
AI 增强推荐理由（可选）
DLNA / Chromecast 设备发现与控制
投屏会话管理（播放/暂停/停止/进度控制）
用户观影时长统计
按日期维度的观看数据
管理员可查看任意用户的统计数据
文件浏览与详情查看（列表/网格双视图）
批量导入/删除文件
文件重命名（模板/预览/AI 生成）
文件级别刮削
操作日志记录
分享管理 — 创建/管理媒体分享链接，支持密码保护和过期时间标签管理 — 自定义标签体系，批量标签操作批量移动 — 跨媒体库批量移动文件匹配规则 — 自定义文件名匹配规则
提供 Emby 兼容 API 接口，支持第三方客户端接入
JWT Token 认证，支持 Token 刷新
请求头 Bearer Token + URL Query Token 双模式（视频流场景兼容）
CORS 跨域中间件（支持多源配置、* 通配）
管理员权限独立守护（中间件级别）
bcrypt 密码加密存储
访问日志记录（登录、播放、管理操作等）
安全中间件（请求头安全加固）
仪表板 — CPU / 内存 / 协程数 / Go 版本 / 硬件加速状态 / 实时系统监控媒体库管理 — CRUD + 一键扫描 + 重建索引 + 高级设置WebSocket 实时进度面板 — 扫描/刮削/转码进度条实时更新活动日志流 — 最近操作实时滚动展示转码任务监控 — 状态、进度、速度、取消用户管理 — 列表、删除、权限设置API Key 在线配置 — TMDb / Bangumi / TheTVDB / Fanart.tv 配置 / 修改 / 清除 / 掩码展示系统全局设置 — 在线修改系统参数定时任务管理 — 创建/编辑/删除定时扫描/刮削/清理任务（支持 Cron 表达式）批量操作 — 批量扫描、批量刮削刮削数据管理 — 刮削任务 CRUD、批量执行、翻译、导出、统计影视文件管理 — 文件浏览、导入、重命名、AI 重命名AI 管理 — AI 状态查看、配置修改、连接测试、缓存管理、错误日志AI 助手 — 自然语言对话式媒体库管理数据备份与恢复 — JSON/ZIP 导出、导入恢复文件系统浏览 — 服务器端目录浏览（用于媒体库路径选择）分享管理 — 创建和管理分享链接标签管理 — 自定义标签体系管理直播源管理 — IPTV 直播源配置与管理WebSocket 连接状态指示器
支持中文（zh-CN）、英文（en-US）、日文（ja-JP）三种语言
前端界面语言一键切换
后端单二进制，无外部依赖（除 FFmpeg）
SQLite 数据库 + WAL 模式（高性能单文件存储，可配置 busy_timeout 和 cache_size）
Docker 多阶段构建，最小运行镜像（Alpine 3.19）
支持环境变量 / 配置文件 / 分片配置 / 命令行多种配置方式
前端构建产物内嵌，单端口同时服务 API + 静态文件
健康检查内置
资源限制友好（Docker 内存限制 512M-2G）
支持 PUID/PGID 自定义运行用户（NAS 场景兼容）
┌─────────────────────────────────────────────────────────────────┐
│ 客户端（浏览器） │
│ React 18 + TypeScript + Tailwind CSS + Zustand + HLS.js │
└──────────────────────────────┬──────────────────────────────────┘
│ HTTP / WebSocket
▼
┌─────────────────────────────────────────────────────────────────┐
│ Gin HTTP Server (:8080) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ 静态文件 │ │ API 路由 │ │ WebSocket│ │ CORS/JWT/Admin│ │
│ │ (前端) │ │ (REST) │ │ (实时) │ │ 中间件 │ │
│ └──────────┘ └────┬─────┘ └────┬─────┘ └──────────────┘ │
└─────────────────────┼─────────────┼─────────────────────────────┘
│ │
┌───────▼─────────────▼───────┐
│ Handler 层 │
│ Auth / Media / Series / │
│ Stream / Admin / AI / │
│ Pulse / V4 Features / ... │
└───────────┬─────────────────┘
│
┌───────────▼─────────────────┐
│ Service 层 │
│ ┌─────────────────────────┐ │
│ │ Provider Chain │ │
│ │ TMDb → 豆瓣 → TheTVDB │ │
│ │ → Bangumi → Fanart → AI│ │
│ └─────────────────────────┘ │
│ Scanner / Transcode / │
│ Recommend / Scheduler / │
│ FileWatcher / Monitor / │
│ Pulse / EmbyCompat / ... │
└───────────┬─────────────────┘
│
┌───────────▼─────────────────┐
│ Repository 层 │
│ (GORM 数据访问) │
└───────────┬─────────────────┘
│
┌───────────▼─────────────────┐
│ SQLite (WAL 模式) │
│ 30+ 张表，自动迁移 │
└─────────────────────────────┘
分层架构说明：
层级
职责
目录
Handler HTTP 请求处理、参数校验、响应格式化
internal/handler/
Service 核心业务逻辑、跨模块协调
internal/service/
Repository 数据库 CRUD、查询构建
internal/repository/
Model GORM 数据模型定义、自动迁移
internal/model/
Config 多层配置加载（默认值 → 文件 → 分片 → 环境变量）
internal/config/
Middleware JWT 认证、CORS、管理员权限、安全头
internal/middleware/
页面
路由
说明
首页
/继续观看 + 最近添加 + 智能推荐 + 轮播
媒体库
/library/:id按媒体库浏览内容（支持剧集合集视图）
剧集详情
/series/:id剧集合集页，季视图/全部视图切换
媒体详情
/media/:id海报、简介、评分、编码信息、播放按钮、评论
播放器
/play/:id全屏沉浸式播放，支持直接播放/HLS 双模式
搜索
/search关键词搜索 + AI 智能搜索
收藏夹
/favorites收藏的媒体列表
观看历史
/history观看记录，支持清除
播放列表
/playlists自定义播放列表管理
播放统计
/stats个人观影统计数据
个人资料
/profile用户信息管理
管理后台
/admin系统状态、媒体库管理、用户管理、配置管理
文件管理
/files影视文件浏览、导入、重命名（含刮削任务 Tab）
家庭空间
/family家庭群组、媒体分享、互动推荐
直播
/liveIPTV 直播源管理与播放
云同步
/sync多设备数据同步与配置管理
Pulse 动态
/pulse社区动态流、观影活动
登录
/login用户认证
# 1. 克隆项目cd nowen-video
# 2. 修改 docker-compose.yml 中的媒体目录挂载路径# 将 /volume1/Media 改为你的实际媒体目录# 3. 修改 JWT Secret（重要！）# 编辑 docker-compose.yml 中的 NOWEN_SECRETS_JWT_SECRET# 4. 启动# 5. 访问 http://你的NAS地址:8080# 默认管理员: admin / admin123# docker-compose.yml 中设置 PUID/PGID 匹配宿主机媒体目录权限environment :
- PUID=1000 # 通过 `id` 命令查看实际 UIDPGID=1000 # 通过 `id` 命令查看实际 GID# 如需硬件加速转码，取消注释设备映射devices :
- /dev/dri:/dev/dri # 前置要求: Go 1.22+, Node.js 20+, FFmpeg# 1. 安装依赖cd web && npm install && cd ..
# 2. 启动后端（开发模式）# 或: NOWEN_DEBUG=true go run ./cmd/server# 3. 启动前端（另一个终端）# 或: cd web && npm run dev# 4. 访问 http://localhost:3000 （Vite 自动代理 API 到 :8080）# 默认管理员: admin / admin123# 一键构建（前端 + 后端）# 或分步构建：cd web && npm run build && cd ..
CGO_ENABLED=1 go build -o bin/nowen-video ./cmd/server
# 运行# 构建镜像.
# 或使用 docker-compose# 构建并启动# 停止配置按以下优先级加载（从低到高），高优先级覆盖低优先级：
1. 内置默认值 → 零配置可运行
2. 主配置文件 → config.yaml（支持旧版扁平格式和新版嵌套格式）
3. 分片配置文件 → config/ 目录（按模块分类管理）
4. 环境变量 → NOWEN_ 前缀，如 NOWEN_APP_PORT=8080
推荐使用 config/ 目录下的分片配置文件，便于分类管理和安全隔离：
文件
说明
config/database.yaml数据库连接参数
config/secrets.yamlJWT 密钥、第三方 API 密钥（⚠️ 勿提交到 Git）
config/app.yaml应用运行环境配置
config/logging.yaml日志记录设置
config/cache.yaml缓存配置参数
config/ai.yamlAI 功能配置
配置项
环境变量
默认值
说明
app.portNOWEN_APP_PORT8080服务端口
app.debugNOWEN_APP_DEBUGfalse调试模式
app.envNOWEN_APP_ENVproduction运行环境
app.data_dirNOWEN_APP_DATA_DIR./data数据目录
app.web_dirNOWEN_APP_WEB_DIR./web/dist前端静态文件目录
app.ffmpeg_pathNOWEN_APP_FFMPEG_PATHffmpegFFmpeg 路径
app.ffprobe_pathNOWEN_APP_FFPROBE_PATHffprobeFFprobe 路径
app.hw_accelNOWEN_APP_HW_ACCELauto硬件加速模式
app.vaapi_deviceNOWEN_APP_VAAPI_DEVICE/dev/dri/renderD128VAAPI 设备路径
app.transcode_presetNOWEN_APP_TRANSCODE_PRESETveryfast转码预设
app.max_transcode_jobsNOWEN_APP_MAX_TRANSCODE_JOBS2最大并发转码数
app.cors_originsNOWEN_APP_CORS_ORIGINS[]CORS 允许源列表
配置项
环境变量
默认值
说明
database.db_pathNOWEN_DATABASE_DB_PATH./data/nowen.dbSQLite 数据库路径
database.wal_modeNOWEN_DATABASE_WAL_MODEtrueWAL 模式
database.busy_timeoutNOWEN_DATABASE_BUSY_TIMEOUT5000繁忙超时（ms）
database.cache_sizeNOWEN_DATABASE_CACHE_SIZE-20000缓存大小（负数为 KB）
database.max_open_connsNOWEN_DATABASE_MAX_OPEN_CONNS1最大打开连接数
database.max_idle_connsNOWEN_DATABASE_MAX_IDLE_CONNS1最大空闲连接数
配置项
环境变量
默认值
说明
secrets.jwt_secretNOWEN_SECRETS_JWT_SECRET(需修改) JWT 签名密钥
secrets.tmdb_api_keyNOWEN_SECRETS_TMDB_API_KEY(空) TMDb API Key
secrets.tmdb_api_proxyNOWEN_SECRETS_TMDB_API_PROXY(空) TMDb API 代理地址
secrets.tmdb_image_proxyNOWEN_SECRETS_TMDB_IMAGE_PROXY(空) TMDb 图片代理地址
secrets.bangumi_access_tokenNOWEN_SECRETS_BANGUMI_ACCESS_TOKEN(空) Bangumi Access Token
secrets.thetvdb_api_keyNOWEN_SECRETS_THETVDB_API_KEY(空) TheTVDB API Key
secrets.fanart_tv_api_keyNOWEN_SECRETS_FANART_TV_API_KEY(空) Fanart.tv API Key
配置项
环境变量
默认值
说明
logging.levelNOWEN_LOGGING_LEVELinfo日志级别
logging.formatNOWEN_LOGGING_FORMATconsole输出格式 (json/console)
logging.output_pathNOWEN_LOGGING_OUTPUT_PATH(stdout) 日志输出路径
logging.enable_rotationNOWEN_LOGGING_ENABLE_ROTATIONfalse启用日志轮转
logging.max_size_mbNOWEN_LOGGING_MAX_SIZE_MB100单文件最大 MB
logging.max_age_daysNOWEN_LOGGING_MAX_AGE_DAYS30最大保留天数
logging.max_backupsNOWEN_LOGGING_MAX_BACKUPS10最大保留个数
配置项
环境变量
默认值
说明
cache.cache_dirNOWEN_CACHE_CACHE_DIR./cache缓存目录
cache.max_disk_usage_mbNOWEN_CACHE_MAX_DISK_USAGE_MB0最大磁盘占用（0=不限）
cache.ttl_hoursNOWEN_CACHE_TTL_HOURS0缓存过期时间（0=不过期）
cache.auto_cleanupNOWEN_CACHE_AUTO_CLEANUPfalse自动清理
cache.cleanup_interval_minNOWEN_CACHE_CLEANUP_INTERVAL_MIN60清理间隔（分钟）
配置项
环境变量
默认值
说明
ai.enabledNOWEN_AI_ENABLEDfalseAI 总开关
ai.providerNOWEN_AI_PROVIDERopenaiLLM 提供商
ai.api_baseNOWEN_AI_API_BASEhttps://api.openai.com/v1API 地址
ai.api_keyNOWEN_AI_API_KEY(空) API 密钥
ai.modelNOWEN_AI_MODELgpt-4o-mini模型名称
ai.timeoutNOWEN_AI_TIMEOUT30请求超时（秒）
ai.enable_smart_searchNOWEN_AI_ENABLE_SMART_SEARCHtrue智能搜索
ai.enable_recommend_reasonNOWEN_AI_ENABLE_RECOMMEND_REASONtrue推荐理由
ai.enable_metadata_enhanceNOWEN_AI_ENABLE_METADATA_ENHANCEtrue元数据增强
ai.monthly_budgetNOWEN_AI_MONTHLY_BUDGET0月度预算（0=不限）
ai.cache_ttl_hoursNOWEN_AI_CACHE_TTL_HOURS168缓存时间（小时）
ai.max_concurrentNOWEN_AI_MAX_CONCURRENT3最大并发数
# OpenAIai :
provider : " openai" api_base : " https://api.openai.com/v1" model : " gpt-4o-mini" # DeepSeekai :
provider : " deepseek" api_base : " https://api.deepseek.com/v1" model : " deepseek-chat" # 通义千问ai :
provider : " qwen" api_base : " https://dashscope.aliyuncs.com/compatible-mode/v1" model : " qwen-turbo" # Ollama（本地部署）ai :
provider : " ollama" api_base : " http://localhost:11434/v1" model : " llama3"
方法
路径
说明
POST
/api/auth/login用户登录
POST
/api/auth/register用户注册
认证管理
方法
路径
说明
POST
/api/auth/refresh刷新 Token
媒体库
方法
路径
说明
GET
/api/libraries获取媒体库列表
POST
/api/libraries创建媒体库 🔒
PUT
/api/libraries/:id更新媒体库 🔒
POST
/api/libraries/:id/scan扫描媒体库 🔒
POST
/api/libraries/:id/reindex重建索引 🔒
DELETE
/api/libraries/:id删除媒体库 🔒
媒体内容
方法
路径
说明
GET
/api/media媒体列表（分页）
GET
/api/media/:id媒体详情
GET
/api/media/recent最近添加
GET
/api/media/recent/aggregated最近添加（聚合剧集）
GET
/api/media/recent/mixed最近添加（混合视图）
GET
/api/media/aggregated媒体列表（聚合剧集）
GET
/api/media/mixed媒体列表（混合视图）
GET
/api/media/continue继续观看
GET
/api/media/:id/poster获取海报图片
GET
/api/media/:id/persons获取演职人员
剧集合集
方法
路径
说明
GET
/api/series剧集合集列表（分页）
GET
/api/series/:id剧集合集详情（含所有剧集）
GET
/api/series/:id/seasons季列表（季视图）
GET
/api/series/:id/seasons/:season指定季的剧集列表
GET
/api/series/:id/next下一集（连续播放）
GET
/api/series/:id/poster剧集海报
GET
/api/series/:id/backdrop剧集背景图
流媒体 / 字幕 / 搜索 / 推荐
方法
路径
说明
GET
/api/stream/:id/info获取播放信息
GET
/api/stream/:id/direct直接播放视频文件
GET
/api/stream/:id/master.m3u8HLS 主播放列表
GET
/api/stream/:id/:quality/:segmentHLS 分片
GET
/api/subtitle/:id/tracks字幕轨道列表
GET
/api/subtitle/:id/extract/:index提取内嵌字幕
GET
/api/subtitle/external获取外挂字幕文件
GET
/api/search关键词搜索
GET
/api/search/advanced高级搜索
GET
/api/search/mixed混合搜索（电影+剧集）
GET
/api/ai/searchAI 智能搜索
GET
/api/recommend个性化推荐
GET
/api/recommend/similar/:mediaId相似媒体推荐
用户 / 收藏 / 历史 / 播放列表 / 书签 / 评论 / 统计
方法
路径
说明
GET
/api/users/me当前用户信息
PUT
/api/users/me/progress/:mediaId更新播放进度
GET
/api/users/me/progress/:mediaId获取播放进度
GET/POST/DELETE
/api/users/me/favorites收藏管理
GET
/api/users/me/favorites/:mediaId/check检查是否已收藏
GET/DELETE
/api/users/me/history观看历史
GET/POST
/api/playlists播放列表列表/创建
GET/DELETE
/api/playlists/:id播放列表详情/删除
POST/DELETE
/api/playlists/:id/items/:mediaId添加/移除项目
POST
/api/bookmarks创建书签
GET
/api/bookmarks用户书签列表
GET
/api/bookmarks/media/:mediaId媒体书签列表
PUT/DELETE
/api/bookmarks/:id更新/删除书签
GET
/api/media/:id/comments评论列表
POST
/api/media/:id/comments发表评论
DELETE
/api/comments/:id删除评论
POST
/api/stats/playback记录播放统计
GET
/api/stats/me个人统计
投屏 / WebSocket
方法
路径
说明
GET
/api/cast/devices设备列表
POST
/api/cast/devices/refresh刷新设备
POST
/api/cast/start开始投屏
GET
/api/cast/sessions会话列表
POST
/api/cast/sessions/:sessionId/control控制投屏
DELETE
/api/cast/sessions/:sessionId停止投屏
GET
/api/wsWebSocket 实时通知
用户与系统管理
方法
路径
说明
GET
/api/admin/users用户列表
DELETE
/api/admin/users/:id删除用户
GET
/api/admin/system系统信息
GET
/api/admin/metrics系统监控指标
GET
/api/admin/logs访问日志
GET
/api/admin/fs/browse文件系统浏览
GET
/api/admin/stats/:userId用户统计
转码 / 配置 / 定时任务 / 批量操作
方法
路径
说明
GET
/api/admin/transcode/status转码任务状态
POST
/api/admin/transcode/:taskId/cancel取消转码任务
GET/PUT/DELETE
/api/admin/settings/tmdbTMDb API Key 配置
GET/PUT/DELETE
/api/admin/settings/bangumiBangumi 配置
GET/PUT
/api/admin/settings/system系统全局设置
GET/POST
/api/admin/tasks任务列表/创建
PUT/DELETE
/api/admin/tasks/:id更新/删除任务
POST
/api/admin/tasks/:id/run立即执行任务
POST
/api/admin/batch/scan批量扫描
POST
/api/admin/batch/scrape批量刮削
元数据管理 / 图片管理
方法
路径
说明
GET
/api/admin/metadata/search搜索元数据
POST
/api/admin/media/:mediaId/match匹配元数据
POST
/api/admin/media/:mediaId/unmatch取消匹配
PUT
/api/admin/media/:mediaId/metadata编辑元数据
DELETE
/api/admin/media/:mediaId删除媒体
POST
/api/admin/series/:seriesId/match匹配剧集元数据
POST
/api/admin/series/:seriesId/scrape刮削剧集元数据
PUT
/api/admin/series/:seriesId/metadata编辑剧集元数据
DELETE
/api/admin/series/:seriesId删除剧集
GET/PUT/DELETE
/api/admin/permissions/:userId用户权限管理
GET/PUT
/api/admin/rating/:mediaId内容分级管理
GET
/api/admin/images/tmdb搜索 TMDb 图片
POST
/api/admin/media/:mediaId/image/upload上传媒体图片
POST
/api/admin/media/:mediaId/image/urlURL 设置图片
POST
/api/admin/media/:mediaId/image/tmdbTMDb 图片设置
POST
/api/admin/series/:seriesId/image/*剧集图片管理
Bangumi / 刮削 / 文件管理 / AI / 备份
方法
路径
说明
GET
/api/admin/metadata/bangumi/search搜索 Bangumi
GET
/api/admin/metadata/bangumi/subject/:subjectId获取条目详情
POST
/api/admin/media/:mediaId/match/bangumi匹配 Bangumi
POST
/api/admin/series/:seriesId/match/bangumi剧集匹配 Bangumi
GET/POST
/api/admin/scrape/tasks刮削任务列表/创建
POST
/api/admin/scrape/tasks/batch批量创建任务
GET/PUT/DELETE
/api/admin/scrape/tasks/:id任务详情/更新/删除
POST
/api/admin/scrape/tasks/:id/scrape执行刮削
POST
/api/admin/scrape/tasks/:id/translate翻译任务
POST
/api/admin/scrape/batch/*批量刮削/翻译/删除
POST
/api/admin/scrape/export导出任务
GET
/api/admin/scrape/statistics刮削统计
GET
/api/admin/scrape/history刮削历史
GET
/api/admin/files文件列表
GET
/api/admin/files/:id文件详情
POST
/api/admin/files/import导入文件
POST
/api/admin/files/import/batch批量导入
GET
/api/admin/files/scan扫描目录
PUT/DELETE
/api/admin/files/:id更新/删除文件
POST
/api/admin/files/rename/*重命名（预览/执行/AI）
GET
/api/admin/files/rename/templates重命名模板
GET
/api/admin/files/stats文件统计
GET
/api/admin/files/logs操作日志
GET
/api/admin/ai/statusAI 状态
PUT
/api/admin/ai/config更新 AI 配置
POST
/api/admin/ai/test测试 AI 连接
GET/DELETE
/api/admin/ai/cacheAI 缓存管理
GET
/api/admin/ai/errorsAI 错误日志
POST
/api/admin/backup/json导出 JSON
POST
/api/admin/backup/zip导出 ZIP
POST
/api/admin/backup/import导入备份
GET
/api/admin/backup/list备份列表
AI 助手
方法
路径
说明
POST
/api/admin/assistant/chatAI 对话
POST
/api/admin/assistant/execute执行 AI 操作
POST
/api/admin/assistant/undo/:opId撤销操作
GET
/api/admin/assistant/session/:sessionId获取会话
DELETE
/api/admin/assistant/session/:sessionId删除会话
GET
/api/admin/assistant/history操作历史
GET
/api/admin/assistant/misclassification分析错误分类
POST
/api/admin/assistant/reclassify重新分类
🔒 = 需要管理员权限
系统共包含 30+ 张数据表 ，使用 GORM 自动迁移：
┌─────────────┐ ┌─────────────┐ ┌───────────────┐
│ User │ │ Library │ │ Series │
├─────────────┤ ├─────────────┤ ├───────────────┤
│ id │ │ id │◄────│ library_id │
│ username │ │ name │ │ title │
│ password │ │ path │ │ orig_title │
│ role │ │ type │ │ folder_path │
│ avatar │ │ last_scan │ │ poster_path │
│ │ │ prefer_nfo │ │ backdrop_path │
│ │ │ min_file_sz │ │ overview │
│ │ │ metadata_ │ │ rating │
│ │ │ lang │ │ genres │
│ │ │ enable_file │ │ tmdb_id │
│ │ │ _watch │ │ douban_id │
│ │ │ │ │ bangumi_id │
│ │ │ │ │ season_count │
│ │ │ │ │ episode_count │
└──────┬──────┘ └─────────────┘ └───────┬───────┘
│ │
│ ┌───────┴───────┐
│ │ Media │
│ ├───────────────┤
│ │ library_id │
│ │ series_id │
│ │ title │
│ │ file_path │
│ │ media_type │ ← movie/episode
│ │ season_num │
│ │ episode_num │
│ │ video_codec │
│ │ resolution │
│ │ duration │
│ │ poster_path │
│ │ overview │
│ │ rating │
│ │ tmdb_id │
│ └───────┬───────┘
│ │
│ ┌──────────────────┐ │
├──│ WatchHistory │───────────────────┘
│ │ position/duration│
│ │ completed │
│ └──────────────────┘
│
│ ┌──────────────────┐ ┌────────────────┐
├──│ Favorite │ │ PlaylistItem │
│ │ media_id │ │ media_id │
│ └──────────────────┘ │ sort_order │
│ └────────┬───────┘
│ ┌──────────────────┐ │
├──│ Playlist │──────────────┘
│ │ name │
│ └──────────────────┘
│
│ ┌──────────────────┐ ┌────────────────┐
├──│ Bookmark │ │ Comment │
│ │ media_id │ │ media_id │
│ │ position/title │ │ content/rating │
│ └──────────────────┘ └────────────────┘
│
│ ┌──────────────────┐ ┌────────────────┐
├──│ PlaybackStats │ │ UserPermission │
│ │ media_id/date │ │ allowed_libs │
│ │ watch_minutes │ │ max_rating │
│ └──────────────────┘ │ daily_limit │
│ └────────────────┘
│
└──────────────────────
┌──────────────────┐ ┌────────────────┐
│ Person │ │ MediaPerson │
│ name/orig_name │◄────│ media_id │
│ profile_url │ │ series_id │
│ tmdb_id │ │ role/character │
└──────────────────┘ └────────────────┘
┌──────────────────┐ ┌────────────────┐
│ TranscodeTask │ │ ContentRating │
│ media_id/quality │ │ media_id │
│ status/progress │ │ level (G~NC17) │
└──────────────────┘ └────────────────┘
┌──────────────────┐ ┌────────────────┐
│ ScheduledTask │ │ AccessLog │
│ type/schedule │ │ user_id/action │
│ target_id │ │ resource/ip │
│ enabled/status │ └────────────────┘
└──────────────────┘
┌──────────────────┐ ┌────────────────┐
│ ScrapeTask │ │ ScrapeHistory │
│ url/source │ │ task_id/action │
│ status/progress │ │ detail │
│ result_* │ └────────────────┘
│ translated_* │
└──────────────────┘
┌──────────────────┐
│ SystemSetting │
│ key/value (KV) │
└──────────────────┘
nowen-video/
├── cmd/server/main.go # Go 入口（路由注册、依赖注入）
├── internal/
│ ├── config/
│ │ └── config.go # 多层配置加载
│ ├── handler/ # HTTP 处理器层（33 个文件）
│ │ ├── handler.go # Handler 聚合与初始化
│ │ ├── auth.go # 登录 / 注册
│ │ ├── media.go # 媒体列表 / 详情 / 搜索 / 聚合视图
│ │ ├── series.go # 剧集合集列表 / 详情 / 季视图 / 下一集
│ │ ├── library.go # 媒体库 CRUD + 扫描 + 重建索引
│ │ ├── stream.go # 直接播放 / HLS 流 / 海报
│ │ ├── subtitle.go # 字幕轨道 / 提取 / 外挂
│ │ ├── metadata.go # 元数据刮削
│ │ ├── admin.go # 系统管理入口
│ │ ├── admin_media.go # 管理员媒体操作
│ │ ├── admin_metadata.go # 管理员元数据搜索
│ │ ├── admin_system.go # 系统设置 / 监控 / 任务 / 权限管理
│ │ ├── ai.go # AI 智能搜索 / 配置管理
│ │ ├── ai_assistant.go # AI 助手对话 / 操作执行
│ │ ├── ai_scene.go # AI 场景识别 / 章节 / 精彩片段
│ │ ├── recommend.go # 智能推荐
│ │ ├── cast.go # 投屏控制
│ │ ├── bookmark.go # 视频书签
│ │ ├── comment.go # 评论评分
│ │ ├── stats.go # 播放统计
│ │ ├── playlist.go # 播放列表
│ │ ├── user.go # 用户信息 / 进度 / 收藏 / 历史
│ │ ├── scrape_manager.go # 刮削任务管理
│ │ ├── file_manager.go # 影视文件管理
│ │ ├── notification.go # 智能通知系统
│ │ ├── cloud_sync.go # 云端同步
│ │ ├── family_social.go # 家庭社交互动
│ │ ├── live.go # 实时直播
│ │ ├── pulse.go # Pulse 动态
│ │ ├── emby_compat.go # Emby 兼容 API
│ │ ├── v2_handlers.go # V2 扩展处理器
│ │ ├── v4_features.go # V4 功能（分享/标签/匹配规则）
│ │ └── ws.go # WebSocket 入口
│ ├── middleware/
│ │ ├── middleware.go # JWT 认证 / CORS / 管理员权限
│ │ └── security.go # 安全头中间件
│ ├── model/ # GORM 数据模型（30+ 张表）
│ │ ├── model.go # 核心模型定义
│ │ ├── scrape_task.go # 刮削任务模型
│ │ └── v3_models.go # V3 扩展模型
│ ├── repository/ # 数据访问层（14 个文件）
│ │ ├── repository.go # 数据访问层聚合
│ │ ├── repo_admin.go # 管理员数据访问
│ │ ├── repo_media.go # 媒体数据访问
│ │ ├── repo_series.go # 剧集数据访问
│ │ ├── repo_person.go # 演职人员数据访问
│ │ ├── repo_social.go # 社交互动数据访问
│ │ ├── repo_stats.go # 统计数据访问
│ │ ├── repo_user.go # 用户数据访问
│ │ ├── repo_library.go # 媒体库数据访问
│ │ ├── repo_cache.go # 缓存数据访问
│ │ ├── repo_pulse.go # Pulse 数据访问
│ │ ├── repo_v4.go # V4 功能数据访问
│ │ ├── scrape_task.go # 刮削任务数据访问
│ │ └── v3_repository.go # V3 扩展数据访问
│ └── service/ # 业务逻辑层（67 个文件）
│ ├── service.go # 服务聚合与依赖注入
│ ├── auth.go # JWT 认证服务
│ ├── media.go # 媒体查询服务
│ ├── series.go # 剧集合集服务
│ ├── scanner.go # 文件扫描 + FFprobe + 剧集识别
│ ├── stream.go # 流媒体服务
│ ├── transcode.go # FFmpeg 转码（硬件加速）
│ ├── metadata.go # TMDb 元数据集成
│ ├── metadata_provider.go # Provider Chain 多数据源调度
│ ├── douban.go # 豆瓣元数据刮削
│ ├── bangumi.go # Bangumi 动画元数据
│ ├── thetvdb.go # TheTVDB 剧集元数据
│ ├── fanart.go # Fanart.tv 图片增强
│ ├── nfo.go # NFO 文件解析
│ ├── ai.go # AI 服务
│ ├── ai_assistant.go # AI 助手服务
│ ├── ai_metadata.go # AI 元数据增强
│ ├── ai_recommend.go # AI 推荐理由
│ ├── ai_search.go # AI 智能搜索
│ ├── ai_scene.go # AI 场景识别服务
│ ├── recommend.go # 推荐算法服务
│ ├── cast.go # 投屏服务
│ ├── library.go # 媒体库管理
│ ├── playlist.go # 播放列表服务
│ ├── bookmark.go # 书签服务
│ ├── comment.go # 评论服务
│ ├── permission.go # 权限管理服务
│ ├── scheduler.go # 定时任务调度
│ ├── monitor.go # 系统监控服务
│ ├── file_watcher.go # 文件监听服务
│ ├── file_manager.go # 文件管理服务
│ ├── scrape_manager.go # 刮削管理服务
│ ├── scrape_delay.go # 刮削延迟控制
│ ├── backup.go # 数据备份与恢复
│ ├── webhook.go # Webhook 通知
│ ├── vfs.go # 虚拟文件系统
│ ├── stats.go # 播放统计
│ ├── thumbnail.go # 缩略图生成
│ ├── user.go # 用户服务
│ ├── user_profile.go # 多用户配置文件服务
│ ├── ws_hub.go # WebSocket Hub
│ ├── offline_download.go # 离线下载服务
│ ├── abr.go # 自适应码率转码服务
│ ├── plugin.go # 插件系统服务
│ ├── music.go # 音乐库服务
│ ├── photo.go # 图片库服务
│ ├── federation.go # 多服务器联邦服务
│ ├── family_social.go # 家庭社交互动服务
│ ├── live.go # 实时直播服务
│ ├── cloud_sync.go # 云端同步服务
│ ├── subtitle_search.go # 字幕在线搜索服务
│ ├── batch_metadata.go # 批量元数据编辑服务
│ ├── notification.go # 智能通知服务
│ ├── pulse.go # Pulse 动态服务
│ ├── emby_compat.go # Emby 兼容服务
│ ├── v4_features.go # V4 功能服务
│ ├── errors.go # 错误定义
│ └── *_test.go # 测试文件（8 个）
├── web/ # React 前端
│ ├── src/
│ │ ├── App.tsx # 路由配置（18 个页面路由）
│ │ ├── api/
│ │ │ ├── client.ts # Axios 客户端配置
│ │ │ └── index.ts # API 封装
│ │ ├── components/ # 通用组件（32 个文件）
│ │ │ ├── Layout.tsx # 布局框架
│ │ │ ├── Sidebar.tsx # 侧边栏导航
│ │ │ ├── VideoPlayer.tsx # 视频播放器
│ │ │ ├── HeroCarousel.tsx # 首页轮播
│ │ │ ├── MediaCard.tsx # 媒体卡片
│ │ │ ├── AIAssistant.tsx # AI 助手面板
│ │ │ ├── CreateShareDialog.tsx# 创建分享对话框
│ │ │ └── ... # 更多组件
│ │ ├── components/admin/ # 管理后台子组件（11 个文件）
│ │ │ ├── DashboardTab.tsx # 仪表板
│ │ │ ├── ShareManager.tsx # 分享管理
│ │ │ ├── TagManager.tsx # 标签管理
│ │ │ ├── MatchRulesTab.tsx # 匹配规则
│ │ │ ├── LiveSourcesTab.tsx # 直播源管理
│ │ │ └── ... # 更多管理组件
│ │ ├── components/media/ # 媒体详情子组件
│ │ ├── components/file-manager/ # 文件管理子组件（9 个文件）
│ │ ├── hooks/
│ │ │ └── useWebSocket.ts # WebSocket Hook
│ │ ├── pages/ # 19 个页面
│ │ │ ├── HomePage.tsx # 首页
│ │ │ ├── SeriesDetailPage.tsx # 剧集详情
│ │ │ ├── FileManagerPage.tsx # 文件管理
│ │ │ ├── PulsePage.tsx # Pulse 动态
│ │ │ └── ... # 更多页面
│ │ ├── stores/ # Zustand 状态管理
│ │ ├── types/
│ │ │ └── index.ts # TypeScript 类型定义
│ │ ├── i18n/ # 国际化（zh-CN / en-US / ja-JP）
│ │ └── lib/
│ │ └── motion.ts # 动画工具
│ ├── tailwind.config.js # 暗色主题 Tailwind 配置
│ ├── vite.config.ts # Vite 配置
│ └── index.html # HTML 入口
├── config/ # 分片配置文件目录
├── Dockerfile # 多阶段构建（Node → Go → Alpine）
├── docker-compose.yml # NAS 部署配置
├── Makefile # 构建命令
├── go.mod / go.sum # Go 依赖管理
└── .gitignore # Git 忽略规则
工具
版本要求
说明
Go
1.22+
后端编译（需要 CGO_ENABLED=1）
Node.js
20+
前端构建
FFmpeg
最新稳定版
视频转码和元数据提取
FFprobe
随 FFmpeg 安装
视频信息探测
命令
说明
make build构建前端 + 后端
make build-server仅构建后端
make build-web仅构建前端
make dev开发模式运行后端
make dev-web开发模式运行前端
make run生产模式构建并运行
make dockerDocker 构建并启动
make docker-stopDocker 停止
make clean清理构建产物和缓存
make install-web安装前端依赖
make tidyGo 依赖整理
graph LR
A[修改代码] --> B{前端 or 后端?}
B -->|前端| C[Vite HMR 自动刷新]
B -->|后端| D[重启 go run]
C --> E[浏览器自动更新]
D --> F[API 代理到 :8080]
E --> G[测试验证]
F --> G
Loading
后端（Go）：
遵循标准的三层架构：Handler → Service → Repository
Handler 层只做参数校验和响应格式化，不包含业务逻辑
Service 层包含核心业务逻辑，通过依赖注入获取 Repository
Repository 层封装所有数据库操作
使用 zap.SugaredLogger 进行日志记录
所有 ID 使用 UUID（github.com/google/uuid）
数据库模型使用 GORM 标签定义
前端（React + TypeScript）：
使用 @/ 路径别名（映射到 web/src/）
状态管理使用 Zustand（轻量级）
样式使用 Tailwind CSS（暗色主题优先）
API 调用统一封装在 api/index.ts
类型定义集中在 types/index.ts
组件按功能分目录：components/、components/media/、components/admin/、components/file-manager/
开启 Debug 模式 ：设置 NOWEN_APP_DEBUG=true，启用详细日志WebSocket 调试 ：浏览器开发者工具 → Network → WS 标签页查看实时消息数据库调试 ：使用 SQLite 客户端直接查看 data/nowen.db转码调试 ：查看 cache/transcode/ 目录下的转码输出API 调试 ：Vite 开发服务器自动代理 /api 到后端
组件
技术
版本
语言
Go
1.22
Web 框架
Gin
1.9.1
ORM
GORM + SQLite (WAL)
1.25.7
认证
golang-jwt/jwt/v5
5.2.0
WebSocket
gorilla/websocket
1.5.3
日志
Uber Zap
1.27.0
配置
Spf13 Viper
1.18.2
文件监听
fsnotify
1.7.0
UUID
google/uuid
1.6.0
密码加密
golang.org/x/crypto (bcrypt)
0.21.0
转码引擎
FFmpeg + FFprobe
—
组件
技术
版本
框架
React + TypeScript
React 18.3 / TS 5.4
构建工具
Vite
5.3.1
CSS 框架
Tailwind CSS
3.4.4
状态管理
Zustand
4.5.2
播放器
HLS.js
1.5.11
HTTP 客户端
Axios
1.7.2
路由
React Router
6.23.1
动画
Framer Motion
12.38.0
图标库
Lucide React
0.379.0
消息提示
React Hot Toast
2.6.0
工具库
clsx
2.1.1
组件
技术
版本
容器
Docker (Alpine)
3.19
编排
Docker Compose
3.8
模式
适用场景
FFmpeg 编码器
典型设备
auto自动检测（推荐）
—
任何设备
qsvIntel 核显
h264_qsv群晖 NAS (Celeron / Pentium / Core)
vaapiLinux 通用
h264_vaapiLinux 带 Intel/AMD GPU
nvencNVIDIA 独显
h264_nvenc有 NVIDIA 显卡的服务器
none纯软件编码
libx264无硬件加速设备（兜底）
设置方式：配置 app.hw_accel: auto 自动检测，或手动指定具体模式。
Docker 部署时需在 docker-compose.yml 中添加设备映射：
devices :
- /dev/dri:/dev/dri
版本
目标
状态
v0.1
核心播放功能（直接播放 + HLS 转码）
✅ 已完成
v0.2
剧集合集 + 多数据源刮削
✅ 已完成
v0.3
多用户 + 权限 + WebSocket 实时通知
✅ 已完成
v0.4
AI 智能功能 + Provider Chain
✅ 已完成
v0.5
文件管理 + AI 助手 + 刮削管理
✅ 已完成
v0.6
V2 功能（多用户配置/离线下载/ABR/插件/音乐/图片/联邦）
✅ 已完成
v0.7
V3 功能（AI 场景/家庭社交/直播/云同步）
✅ 已完成
v0.8
入口整合优化 + 多语言国际化
✅ 已完成
v0.9
V4 功能（分享管理/标签管理/匹配规则/Pulse 动态/Emby 兼容）
✅ 已完成
v1.0
生产就绪版本（稳定性 + 性能优化 + 移动端适配）
🔄 进行中
MIT
