docs: rewrite project readmes

README.md

@@ -1,38 +1,92 @@
 # MediaStationGo
 
-> 轻量、漂亮、NAS 友好的私人媒体中心。Go 单二进制后端 + React 前端，覆盖媒体库管理、刮削、播放、订阅下载、Emby API 兼容、AI 搜索与推荐。
+<p align="center">
+  <img src="web/public/favicon.svg" width="96" height="96" alt="MediaStationGo Logo" />
+</p>
 
-[English](README_EN.md) · [Docker 部署](#docker-部署推荐) · [一键脚本](#一键脚本部署) · [开发构建](#开发与构建)
+<h3 align="center">轻量、漂亮、NAS 友好的私人媒体中心</h3>
 
-## 亮点
+<p align="center">
+  <strong>Go 单二进制后端 · React 现代化前端 · Docker 一键部署 · Emby API 兼容 · 多源刮削 · PT 订阅下载</strong>
+</p>
 
-- **现代 UI**：统一浅色高级视觉方案，首页聚焦「本周力荐 / 继续观看 / 最近入库」，媒体库页按电影、剧集、动漫、综艺等分类展示，并自动用库内海报生成文件夹封面。
-- **媒体库扫描与整理**：递归扫描、ffprobe 元数据、季/集识别、综艺按节目/季/集展示、重复扫描去重、本地 NFO/图片优先。
-- **多源刮削**：TMDb、TheTVDB、Bangumi、豆瓣、Fanart.tv、JavDB/JavBus 成人内容页面直爬补全；优先读取本地 NFO、poster、fanart、DMM/JAV 图片。
-- **播放体验**：直链播放、Range 拖动、HLS 转码、外挂字幕、播放历史、继续观看、外部播放器入口。
-- **外部客户端兼容**：提供 Emby/Jellyfin 风格 API，便于 Infuse、VidHub、SenPlayer 等客户端访问。
-- **PT 与下载**：站点管理、M-Team `x-api-key`、跨站搜索、订阅、qBittorrent 下载、下载后智能分类整理。
-- **AI 助手**：OpenAI 兼容接口，支持自然语言搜索、智能推荐；后台 API 配置实时生效。
-- **部署简单**：裸机一键脚本、Docker Compose、多架构镜像构建/推送脚本。
+<p align="center">
+  <a href="README_EN.md">English</a> ·
+  <a href="#quick-start">快速开始</a> ·
+  <a href="#docker-compose-deploy">Docker 部署</a> ·
+  <a href="#screenshots">界面预览</a> ·
+  <a href="https://mgo.3jzs.com">在线演示</a>
+</p>
 
-## 功能模块
+<p align="center">
+  <img alt="Go" src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white" />
+  <img alt="React" src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=111827" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript&logoColor=white" />
+  <img alt="Docker" src="https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white" />
+  <img alt="License" src="https://img.shields.io/badge/License-GPL--3.0-blue?style=flat-square" />
+  <img alt="Use" src="https://img.shields.io/badge/Use-Non--Commercial-orange?style=flat-square" />
+</p>
+
+---
+
+## ✨ 项目简介
+
+MediaStationGo 是一个面向个人、家庭 NAS 与影音爱好者的开源媒体中心。它把「媒体库管理、自动刮削、在线播放、外部客户端兼容、PT 站点检索、订阅下载、AI 推荐」放进一个轻量的 Go 服务里，配合 React 前端提供统一、简洁、漂亮的三端体验。
+
+它适合这些场景：
+
+- 家里有 NAS / Windows 主机 / Linux 小主机，希望统一管理电影、剧集、动漫、综艺、成人内容。
+- 想使用 TMDb、豆瓣、Bangumi、TheTVDB、Fanart、JavBus/JavDB 等多源元数据补全海报、简介、分季分集信息。
+- 想把 PT 站点搜索、订阅、下载器、下载后整理集中到一个 Web 面板中。
+- 想让 Infuse、VidHub、SenPlayer 等外部客户端通过 Emby 风格接口访问媒体库。
+- 想要一个部署简单、便于二次开发、不会把密钥和私有 Token 暴露到前端的开源项目。
+
+> 当前项目仍在快速迭代中，建议固定镜像版本部署，并定期备份 `/data` 目录。
+
+---
+
+## 🌱 开源承诺
+
+MediaStationGo 采用完全开源路线，核心媒体库、刮削、播放、订阅、下载、外部客户端兼容与运维能力均在本仓库持续迭代。项目参考了 MoviePilot 等优秀开源项目在「站点聚合、订阅下载、媒体整理、Emby/Jellyfin 客户端兼容」上的产品思路，但本项目会保持独立实现，不直接复制不兼容代码。
+
+本项目当前基础许可证为 `GPL-3.0`，欢迎基于 GPL-3.0 协议参与改造、适配站点、提交刮削规则与优化 UI。项目作者同时倡议：本项目面向个人学习、家庭 NAS、自建影音与非商业场景使用，未经作者明确书面许可，不得将本项目或其衍生版本用于商业售卖、商业托管、付费 SaaS、预装售卖设备、闭源二次分发或其他商业化牟利用途。
+
+> 说明：GPL-3.0 是自由软件许可证，其正式授权范围以仓库 [LICENSE](LICENSE) 文件为准；上方「非商用承诺」表达项目维护者的使用边界与商业合作要求。如需商业合作、企业部署或二次发行，请先联系作者获得额外授权。
+
+---
+
+## 🚀 在线演示
+
+- 演示站：[https://mgo.3jzs.com](https://mgo.3jzs.com)
+- 默认账号：`admin`
+- 默认密码：`admin123`
+
+> 演示环境仅用于功能体验，请勿上传真实隐私信息或配置私人 API Key。
+
+---
+
+## 🧭 功能总览
 
 | 模块 | 能力 |
 | --- | --- |
-| 媒体库 | 电影、电视剧、动漫、综艺、音乐、成人内容；自动封面、合集分季分集 |
-| 刮削 | 本地 NFO/图片优先，TMDb/TheTVDB/Bangumi/豆瓣/Fanart/JavBus/JavDB 补全 |
-| 播放 | 直链、HLS、字幕、续播、外部播放器、历史与收藏 |
-| 发现 | TMDb / 豆瓣 / Bangumi 推荐入口，多源发现与订阅 |
-| 下载 | qBittorrent、PT 站点、RSS/搜索订阅、自动整理 |
-| 兼容 | Emby API、DLNA、外部客户端与三端 UI |
-| 运维 | 任务、统计、存储、重复文件、回收站、NFO 导出 |
-| AI | OpenAI 兼容 Base URL/API Key，智能搜索与推荐 |
+| 媒体库 | 电影、电视剧、动漫、综艺、音乐、成人内容；支持文件夹封面、合集、季、集展示 |
+| 扫描识别 | 递归扫描、ffprobe 探测、文件名解析、季集识别、综艺节目识别、重复扫描去重 |
+| 本地元数据 | 优先读取 NFO、poster、fanart、season poster、episode image、本地成人影片图片 |
+| 在线刮削 | TMDb、TheTVDB、Bangumi、豆瓣、Fanart.tv、JavBus/JavDB 页面直爬补全 |
+| 播放体验 | 直链播放、HTTP Range 拖动、HLS 转码、外挂字幕、播放进度、继续观看、外部播放器 |
+| 发现与搜索 | TMDb / 豆瓣 / Bangumi 多源推荐，智能搜索，详情页订阅入口 |
+| PT 站点 | 站点管理、M-Team API Token、站点搜索、种子链接解析、下载器联动 |
+| 订阅下载 | RSS / 站点搜索订阅，分辨率/质量/特效/发布组/排除词规则，洗版开关与优先级 |
+| 下载中心 | qBittorrent 任务状态、速度、进度、上传下载体积、小卡片海报展示、私有 URL 脱敏 |
+| 外部兼容 | Emby/Jellyfin 风格 API，兼容 Infuse、VidHub、SenPlayer 等外部客户端 |
+| AI 能力 | OpenAI Compatible API 配置，AI 搜索、推荐、运维助手 |
+| 运维工具 | 运行状态、任务队列、重复文件、回收站、文件管理、存储配置、通知渠道 |
 
-**演示站**
+---
 
-[**Demo**](https://mgo.3jzs.com) 账号 ：admin 密码：admin123
+<a id="screenshots"></a>
 
-## 界面预览
+## 🖼️ 界面预览
 
 > 以下截图使用 Codex 内置浏览器从当前运行实例采集，并已对个人媒体内容、本地路径、账号信息、API Key/Token/密钥等敏感信息做图像级打码处理。
 
@@ -98,43 +152,174 @@
 
 </details>
 
-## Docker 部署（推荐）
+---
+
+## 🧱 技术栈
+
+| 层级 | 技术 | 说明 |
+| --- | --- | --- |
+| 后端语言 | Go 1.25+ | 单二进制部署，启动快，资源占用低 |
+| Web 框架 | Gin | REST API、鉴权中间件、静态资源托管 |
+| 数据库 | SQLite + GORM | 适合个人/NAS 场景，数据文件易备份 |
+| 前端框架 | React 18 + TypeScript | 组件化 UI，类型安全 |
+| 构建工具 | Vite | 前端快速开发与生产打包 |
+| 样式系统 | Tailwind CSS | 统一浅色高级视觉方案与响应式布局 |
+| 状态管理 | Zustand | 轻量全局状态与鉴权状态维护 |
+| 播放链路 | HTML5 Video / HLS / FFmpeg | 直链、Range、HLS 转码、字幕 |
+| 元数据 | TMDb / 豆瓣 / Bangumi / TheTVDB / Fanart / JavBus / JavDB | 多源补全海报、简介、评分、分季分集 |
+| 下载联动 | qBittorrent / PT Site Adapter | 站点搜索、订阅、下载任务展示与脱敏 |
+| 外部兼容 | Emby-style API / DLNA | 面向外部播放器与三端客户端 |
+| 部署 | Docker / Docker Compose / Shell / PowerShell | NAS、Linux、Windows 均可部署 |
+| CI/CD | GitHub Actions / GHCR | 多架构镜像与 Release 包自动发布 |
+
+---
+
+<a id="quick-start"></a>
+
+## 📦 快速开始
+
+<a id="docker-compose-deploy"></a>
+
+### Docker Compose 部署（推荐）
+
+Docker 是最稳定、最容易迁移的部署方式。默认会创建四类目录：
+
+| 宿主机目录 | 容器目录 | 作用 |
+| --- | --- | --- |
+| `./data` | `/data` | 数据库、JWT secret、运行时配置，必须备份 |
+| `./cache` | `/cache` | 海报、背景图、刮削缓存、转码缓存 |
+| `./media` | `/media` | 媒体库根目录，默认只读挂载 |
+| `./downloads` | `/downloads` | 订阅/站点下载保存目录 |
 
 ```bash
 git clone https://github.com/ShukeBta/MediaStationGo.git
 cd MediaStationGo
-cp config.example.yaml config.yaml
+
+docker compose pull
 docker compose up -d
 ```
 
-默认地址：`http://<服务器IP>:18080`
+启动后访问：
 
-默认账号：`admin` / `admin123`
-
-> 首次登录后请立即修改管理员密码，并在「媒体与用户」中添加媒体目录。
-
-### docker-compose 关键挂载
-
-```yaml
-volumes:
-  - ./data:/data
-  - ./cache:/cache
-  - ./media:/media:ro
+```text
+http://<服务器IP>:18080
 ```
 
-可通过环境变量覆盖默认路径和端口：
+默认账号：
+
+```text
+用户名：admin
+密码：admin123
+```
+
+> 首次登录后请立即修改管理员密码。
+
+### 固定版本部署
+
+建议生产环境固定版本，避免 `latest` 自动变化：
 
 ```bash
-MEDIASTATION_HTTP_PORT=18080 MEDIASTATION_MEDIA_DIR=/your/media/path docker compose up -d
+cat > .env <<'EOF'
+MEDIASTATION_IMAGE_TAG=MediaStationGo-v0.0.4
+MEDIASTATION_HTTP_PORT=18080
+MEDIASTATION_MEDIA_DIR=/mnt/nas/media
+MEDIASTATION_DOWNLOAD_DIR=/mnt/nas/downloads
+MEDIASTATION_DATA_DIR=./data
+MEDIASTATION_CACHE_DIR=./cache
+TZ=Asia/Shanghai
+EOF
+
+docker compose up -d
 ```
 
-### 硬件转码
+### 媒体库路径怎么填
 
-- Intel QSV/VAAPI：挂载 `/dev/dri:/dev/dri`
-- NVIDIA NVENC：宿主机安装 NVIDIA Container Toolkit，并启用 `gpus: all`
-- 软件转码：无需额外配置
+如果 compose 中这样挂载：
 
-## 一键脚本部署
+```yaml
+- /mnt/nas/media:/media:ro
+- /mnt/nas/downloads:/downloads
+```
+
+那么在 Web 管理页面中添加媒体库时应填写容器内路径，例如：
+
+| 类型 | 推荐路径 |
+| --- | --- |
+| 电影 | `/media/Movies` |
+| 剧集 | `/media/TV` |
+| 动漫 | `/media/Anime` |
+| 综艺 | `/media/Variety` |
+| 成人内容 | `/media/Adult` |
+| 下载入库 | `/downloads/Movies`、`/downloads/TV` 等 |
+
+### 下载器路径怎么填
+
+如果 qBittorrent 也运行在 Docker 中，必须让 qBittorrent 与 MediaStationGo 看到同一份下载目录。
+
+建议统一约定：
+
+```text
+宿主机：/mnt/nas/downloads
+MediaStationGo 容器：/downloads
+qBittorrent 容器：/downloads
+```
+
+订阅保存路径可填写：
+
+```text
+/downloads/Movies
+/downloads/TV
+/downloads/Anime
+/downloads/Variety
+```
+
+---
+
+## 🐳 Docker Compose 配置示例
+
+项目已内置详细注释版 `docker-compose.yml`，可直接使用。常用变量如下：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `MEDIASTATION_IMAGE_TAG` | `latest` | 镜像标签，建议固定为 Release 版本 |
+| `MEDIASTATION_HTTP_PORT` | `18080` | 宿主机访问端口 |
+| `MEDIASTATION_DATA_DIR` | `./data` | 数据持久化目录 |
+| `MEDIASTATION_CACHE_DIR` | `./cache` | 图片和转码缓存目录 |
+| `MEDIASTATION_MEDIA_DIR` | `./media` | 媒体库宿主机目录 |
+| `MEDIASTATION_DOWNLOAD_DIR` | `./downloads` | 下载保存宿主机目录 |
+| `PUID` / `PGID` | `1000` / `1000` | Linux/NAS 文件权限映射 |
+| `TZ` | `Asia/Shanghai` | 容器时区 |
+
+查看日志：
+
+```bash
+docker logs -f mediastation-go
+```
+
+更新镜像：
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+停止服务：
+
+```bash
+docker compose down
+```
+
+备份数据：
+
+```bash
+tar -czf mediastationgo-data-backup.tgz ./data
+```
+
+---
+
+## 🖥️ 一键脚本部署
+
+如果不想使用 Docker，也可以裸机运行。脚本会自动构建前端、编译后端、启动服务并检查健康状态。
 
 ### Linux / macOS
 
@@ -153,78 +338,127 @@ cd MediaStationGo
 .\scripts\deploy.ps1 -Port 18080 -DataDir D:\MediaStationGo\data -CacheDir D:\MediaStationGo\cache
 ```
 
-脚本会自动：
+脚本执行内容：
 
 1. 安装前端依赖并构建 `web/dist`
 2. 编译 Go 服务端到 `bin/`
-3. 创建数据与缓存目录
+3. 创建数据目录和缓存目录
 4. 停止旧进程并启动新进程
-5. 调用 `/api/health` 做健康检查
+5. 请求 `/api/health` 验证服务状态
 
-## Docker 镜像打包与推送
+---
 
-默认推送到 `ghcr.io/shukebta/mediastation-go:latest`：
+## 🧩 Release 包部署
+
+每个 Release 会提供多平台压缩包：
+
+| 平台 | 包名示例 |
+| --- | --- |
+| Linux x86_64 | `MediaStationGo-v0.0.4-linux-amd64.tar.gz` |
+| Linux ARM64 | `MediaStationGo-v0.0.4-linux-arm64.tar.gz` |
+| Windows x86_64 | `MediaStationGo-v0.0.4-windows-amd64.zip` |
+| macOS Intel | `MediaStationGo-v0.0.4-darwin-amd64.tar.gz` |
+| macOS Apple Silicon | `MediaStationGo-v0.0.4-darwin-arm64.tar.gz` |
+
+部署步骤：
 
 ```bash
-docker login ghcr.io
-IMAGE=ghcr.io/shukebta/mediastation-go TAG=latest ./scripts/docker-build-push.sh
+# Linux 示例
+tar -xzf MediaStationGo-v0.0.4-linux-amd64.tar.gz
+cd MediaStationGo-v0.0.4-linux-amd64
+MEDIASTATION_APP_PORT=18080 ./mediastation-go
 ```
 
 Windows：
 
 ```powershell
-docker login ghcr.io
-.\scripts\docker-build-push.ps1 -Image ghcr.io/shukebta/mediastation-go -Tag latest
+Expand-Archive .\MediaStationGo-v0.0.4-windows-amd64.zip
+cd .\MediaStationGo-v0.0.4-windows-amd64
+$env:MEDIASTATION_APP_PORT = "18080"
+.\mediastation-go.exe
 ```
 
-仅本地构建不推送：
+> Release 二进制默认监听 `8080`，如果希望和 Docker 示例保持一致，请按上方设置 `MEDIASTATION_APP_PORT=18080`。
 
-```bash
-PUSH=0 TAG=dev ./scripts/docker-build-push.sh
-```
+---
 
-```powershell
-.\scripts\docker-build-push.ps1 -Tag dev -Load
-```
-
-## 开发与构建
+## 🛠️ 本地开发
 
 ### 环境要求
 
-| 组件 | 版本 |
-| --- | --- |
-| Go | 1.25+ |
-| Node.js | 20+ |
-| FFmpeg / ffprobe | 推荐安装 |
-| Docker | 可选 |
+| 组件 | 版本 | 用途 |
+| --- | --- | --- |
+| Go | 1.25+ | 后端编译与测试 |
+| Node.js | 20+ | 前端构建 |
+| FFmpeg / ffprobe | 推荐安装 | 媒体探测与转码 |
+| Docker | 可选 | 容器部署与多架构镜像 |
+| qBittorrent | 可选 | 下载器联动测试 |
 
 ### 本地构建
 
 ```bash
 cp config.example.yaml config.yaml
-cd web && npm ci && npm run build
+cd web
+npm ci
+npm run build
 cd ..
 go build -o bin/mediastation-go ./cmd/server
 ./bin/mediastation-go
 ```
 
+Windows：
+
+```powershell
+Copy-Item config.example.yaml config.yaml
+Set-Location web
+npm ci
+npm run build
+Set-Location ..
+go build -o bin\mediastation-go.exe .\cmd\server
+.\bin\mediastation-go.exe
+```
+
 ### 常用命令
 
 ```bash
 make build       # 构建前后端
-make test        # Go 测试
+make test        # 运行 Go 测试
+make smoke       # 冒烟测试
 make docker      # docker compose up -d
 make deploy      # Linux 一键部署
 make docker-push # buildx 多架构推送
 ```
 
-Windows 可直接使用：
+---
 
-```powershell
-.\scripts\deploy.ps1
+## 🏗️ 项目结构
+
+```text
+MediaStationGo/
+├── cmd/server/                 # 服务入口
+├── internal/
+│   ├── config/                  # 配置加载与默认值
+│   ├── database/                # SQLite 初始化与迁移
+│   ├── handler/                 # HTTP API / Emby API / 管理接口
+│   ├── middleware/              # 鉴权、权限、日志中间件
+│   ├── model/                   # GORM 数据模型
+│   ├── repository/              # 数据访问层
+│   └── service/                 # 扫描、刮削、播放、下载、订阅等业务逻辑
+├── web/
+│   ├── public/                  # favicon 等静态资源
+│   ├── src/                     # React 页面、组件、API、状态管理
+│   └── dist/                    # 前端构建产物，默认不入库
+├── scripts/                     # 部署、打包、Docker 构建脚本
+├── docs/                        # 设计文档、截图与架构说明
+├── docker-compose.yml           # 默认 Docker Compose 部署文件
+├── Dockerfile                   # 多阶段镜像构建
+├── config.example.yaml          # 配置模板
+└── README.md / README_EN.md     # 项目文档
 ```
 
-## 配置说明
+---
+
+## ⚙️ 配置说明
 
 配置优先级从低到高：
 
@@ -232,57 +466,311 @@ Windows 可直接使用：
 2. `config.yaml`
 3. `config/*.yaml`
 4. `MEDIASTATION_` 环境变量
-5. 后台数据库配置（API Key、站点、下载器等运行时配置）
+5. 后台数据库运行时配置
 
 常用环境变量：
 
 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
-| `MEDIASTATION_APP_PORT` | `8080` | Web 服务端口 |
-| `MEDIASTATION_APP_DATA_DIR` | `./data` | 数据目录 |
-| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite 数据库 |
-| `MEDIASTATION_APP_WEB_DIR` | `./web/dist` | 前端静态资源 |
-| `MEDIASTATION_CACHE_CACHE_DIR` | `./cache` | 图片/转码缓存 |
-| `MEDIASTATION_SECRETS_JWT_SECRET` | 自动生成 | JWT 与密钥加密种子 |
+| `MEDIASTATION_APP_HOST` | `0.0.0.0` | 服务监听地址 |
+| `MEDIASTATION_APP_PORT` | `8080` | 服务监听端口 |
+| `MEDIASTATION_APP_WEB_DIR` | `./web/dist` | 前端静态资源目录 |
+| `MEDIASTATION_APP_DATA_DIR` | `./data` | 程序数据目录 |
+| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite 数据库路径 |
+| `MEDIASTATION_CACHE_CACHE_DIR` | `./cache` | 图片/转码缓存目录 |
+| `MEDIASTATION_SECRETS_JWT_SECRET` | 自动生成 | JWT 和敏感配置加密种子 |
+| `MEDIASTATION_APP_CORS_ORIGINS` | 空 | 额外允许的跨域来源 |
 
-## API 与外部服务
+后台可运行时配置：
 
-在「外部 API 配置」中可配置：
+- API Key：TMDb、Bangumi、TheTVDB、Fanart、OpenAI Compatible 等。
+- 站点：M-Team、NexusPHP、Unit3D、自定义 RSS 等。
+- 下载器：qBittorrent、Transmission、Aria2。
+- 通知渠道：Telegram、Bark、Webhook、Email 等。
+- 播放配置、权限配置、调度任务、存储配置。
 
-- TMDb：影视元数据
-- Bangumi：番剧与动漫
-- TheTVDB：剧集补充
-- Fanart.tv：高清艺术图
-- OpenAI Compatible：AI 搜索/推荐
-- Adult/JAV：JavBus/JavDB 页面直爬，不需要 API
+---
 
-M-Team 站点请使用「控制台 → 实验室 → 存取令牌」生成 API Access Token，并通过 `x-api-key` 使用；不要使用 Cookie 调用开放 API。
+## 🔍 刮削与元数据策略
 
-## 隐私与仓库安全
+MediaStationGo 的刮削顺序尽量避免重复请求和错误覆盖：
 
-项目默认忽略以下个人/运行数据：
+1. 优先读取本地 NFO、poster、fanart、season poster、episode image。
+2. 根据文件名识别电影、剧集、动漫、综艺、成人内容。
+3. 使用 TMDb / TheTVDB / Bangumi / 豆瓣补全缺失元数据。
+4. 使用 Fanart.tv 补充更高清的艺术图。
+5. 成人内容优先读取本地 NFO 与图片，再通过 JavBus/JavDB 等公开页面补全。
+6. 已有本地元数据不会被无意义重复刮削覆盖。
+
+推荐目录结构：
+
+```text
+/media/Movies/Inception (2010)/Inception (2010).mkv
+/media/TV/Some Show/Season 01/Some Show S01E01.mkv
+/media/Anime/Anime Title/Season 01/Anime Title S01E01.mkv
+/media/Variety/Show Name/Season 2026/Show Name S2026E01.mkv
+/media/Adult/ABCD-123/ABCD-123.mp4
+```
+
+本地图片常见命名：
+
+```text
+poster.jpg
+fanart.jpg
+folder.jpg
+season01-poster.jpg
+S01E01-thumb.jpg
+movie.nfo
+tvshow.nfo
+episode.nfo
+```
+
+---
+
+## 🔎 发现、搜索与订阅下载
+
+### 多源发现
+
+精彩发现支持：
+
+- TMDb：趋势、热门电影、热门剧集、高分电影。
+- 豆瓣：热门电影、高分电影、热门剧集。
+- Bangumi：每日放送、动漫条目。
+
+### 智能搜索
+
+智能搜索会同时考虑：
+
+- 本地媒体库已有内容。
+- TMDb / 豆瓣 / Bangumi 等在线结果。
+- 可订阅关键词与媒体类型。
+
+### 订阅规则
+
+订阅支持以下规则：
+
+| 规则 | 说明 |
+| --- | --- |
+| 媒体类型 | 电影、剧集、动漫、综艺，支持自动识别 |
+| 搜索模式 | 标题关键词或 IMDB ID |
+| 分辨率 | 自动择优、2160p、1080p、720p |
+| 质量 | REMUX、BluRay、WEB-DL、HDTV 等 |
+| 特效 | HDR、Dolby Vision、Atmos 等 |
+| 发布组 | 白名单发布组 |
+| 排除词 | 排除 CAM、TS、枪版等低质资源 |
+| 洗版 | 默认关闭，可按分辨率、质量、特效、做种数优先 |
+
+下载与订阅卡片只展示安全标题、海报、进度、速度、体积等信息，不展示原始种子 URL，避免多用户场景泄露私人 Tracker Token。
+
+---
+
+## 🔌 外部客户端与 Emby 兼容
+
+项目提供 Emby/Jellyfin 风格 API，用于外部客户端连接：
+
+```text
+http://<服务器IP>:18080
+```
+
+可尝试的客户端：
+
+- Infuse
+- VidHub
+- SenPlayer
+- 其他支持 Emby/Jellyfin 服务器的播放器
+
+建议检查：
+
+1. Docker 端口是否映射为 `18080:8080`。
+2. 防火墙是否允许局域网访问 `18080`。
+3. 账号密码是否正确。
+4. 反向代理是否正确转发 `/api`、视频流和 Range 请求。
+
+### 与 MoviePilot 的功能参考关系
+
+MediaStationGo 在外部客户端兼容与媒体生态联动上参考了 MoviePilot 的成熟产品路径：通过统一媒体库、订阅下载、下载后整理和 Emby/Jellyfin 兼容接口，把 Web 管理端与 Infuse、VidHub、SenPlayer 等客户端串起来。本项目的目标不是替代 Emby/Jellyfin，而是在轻量 Go 服务中提供足够常用的媒体浏览、播放、海报墙、剧集分季分集、播放进度和外部客户端访问能力。
+
+当前兼容重点：
+
+- 媒体库、合集、季、集的层级输出。
+- 海报、背景图、简介、年份、评分等基础元数据输出。
+- 视频流地址、HTTP Range、播放进度与继续观看。
+- 外部客户端登录、媒体浏览和播放所需的 Emby/Jellyfin 风格接口。
+
+仍在持续补齐：
+
+- 更完整的 Emby/Jellyfin 设备能力协商。
+- 更细的转码 Profile 与字幕能力声明。
+- 多用户权限、媒体库过滤与播放历史同步。
+- 与订阅下载、自动整理、洗版规则之间的闭环联动。
+
+> MoviePilot 项目使用 GPL-3.0 许可，本项目只参考其公开产品思路与交互路径，不复制私有数据、密钥、站点账号或不兼容实现。
+
+---
+
+## 🧠 AI 与外部服务配置
+
+在后台「外部 API 配置」中可配置：
+
+| 服务 | 作用 |
+| --- | --- |
+| TMDb | 电影、剧集、海报、背景图、简介 |
+| Bangumi | 动漫、番剧、中文条目 |
+| TheTVDB | 剧集季集补充 |
+| Fanart.tv | 高清 Logo、背景图、艺术图 |
+| 豆瓣 | 中文影视搜索与推荐补充 |
+| OpenAI Compatible | AI 搜索、推荐、运维助手 |
+
+M-Team 建议使用 API Access Token：
+
+```text
+控制台 → 实验室 → 存取令牌
+HTTP Header: x-api-key
+```
+
+不建议使用 Cookie 调用开放 API，避免账号风险。
+
+---
+
+## 🧪 构建、打包与发布
+
+### Docker 镜像
+
+默认镜像：
+
+```text
+ghcr.io/shukebta/mediastation-go:latest
+ghcr.io/shukebta/mediastation-go:MediaStationGo-v0.0.4
+```
+
+Linux/macOS 推送：
+
+```bash
+docker login ghcr.io
+IMAGE=ghcr.io/shukebta/mediastation-go TAG=MediaStationGo-v0.0.4 ./scripts/docker-build-push.sh
+```
+
+Windows 推送：
+
+```powershell
+docker login ghcr.io
+.\scripts\docker-build-push.ps1 -Image ghcr.io/shukebta/mediastation-go -Tag MediaStationGo-v0.0.4
+```
+
+仅本地构建：
+
+```powershell
+.\scripts\docker-build-push.ps1 -Tag dev -Load
+```
+
+### Release 包
+
+```bash
+VERSION=MediaStationGo-v0.0.4 ./scripts/package-release.sh
+```
+
+GitHub Actions 会在推送 `MediaStationGo-v*` 标签时自动生成 Release 包和 SHA256 校验文件。
+
+> 如果 Release 开启 immutable，不应覆盖同名资产；工作流已设置 `overwrite_files: false`，避免重跑时删除旧资产失败。
+
+---
+
+## 🔐 隐私与安全
+
+默认不会提交以下数据：
 
 - `data/`、`cache/`、`logs/`
 - `.tmp-deploy-data/`、`.tmp-deploy-server.*`
+- `.mediastation.pid`
 - `config.yaml`、`.env*`
 - `*.db`、`*.db-wal`、`*.log`
 - `web/dist/`、`node_modules/`、`bin/`
+- API Key、Cookie、Token、密码、证书等敏感文件
 
-推送代码前建议执行：
+提交前建议检查：
 
 ```bash
 git status --short
-git ls-files | grep -E 'data/|cache/|\\.db|\\.log|jwt_secret|config.yaml|\\.env' || true
+git ls-files | grep -E 'data/|cache/|\.db|\.log|jwt_secret|config.yaml|\.env|token|apikey|password' || true
 ```
-## 开发群组
 
-# TG https://t.me/MediaStationGo 
-## 赞赏
-<img width="200" height="200" alt="微信图片_20260528191337_3_983" src="https://github.com/user-attachments/assets/d6077de5-8305-400d-8b82-470ef05d926e" />
+---
 
-  请作者吃桶泡面
+## ❓ 常见问题
 
-## Star History
+### Q: Docker 部署后浏览器打不开？
+
+检查容器状态和端口：
+
+```bash
+docker ps
+docker logs -f mediastation-go
+```
+
+确认访问的是宿主机端口，例如 `http://192.168.1.4:18080`。
+
+### Q: 外部客户端提示服务器未响应？
+
+优先检查防火墙、Docker 端口映射、反向代理和局域网 IP。容器内监听 `8080`，宿主机默认映射为 `18080`。
+
+### Q: 媒体库没有海报？
+
+请确认：
+
+1. 本地是否有 `poster.jpg`、`fanart.jpg`、NFO。
+2. TMDb / Bangumi / 豆瓣是否可连接。
+3. 代理是否正确配置。
+4. 媒体文件名是否包含清晰标题、年份、季集信息。
+
+### Q: 下载任务为什么不显示原始链接？
+
+PT 下载 URL 常包含私有 Token。下载中心和订阅管理会主动隐藏原始 URL，只显示安全标题、海报、速度、进度、体积等信息。
+
+### Q: 可以只保留哪个 Docker 包？
+
+保留 `ghcr.io/shukebta/mediastation-go` 即可；旧的 `mediastationgo` 包可以删除，避免用户拉错镜像。
+
+---
+
+## 🗺️ 路线图
+
+- 更完整的 Emby/Jellyfin 客户端兼容。
+- 更强的成人内容本地元数据和公开页面补全。
+- 更细粒度的订阅洗版和下载后整理规则。
+- 更完善的移动端/电视端交互。
+- 插件化站点适配器和通知渠道。
+- 更完整的端到端测试与截图自动化。
+
+---
+
+## 🤝 贡献
+
+欢迎提交 Issue、Pull Request、站点适配、刮削规则、UI 改进与文档修正。
+
+建议贡献前先运行：
+
+```bash
+go test ./...
+cd web && npm run build
+```
+
+---
+
+## 👥 开发群组
+
+- Telegram：<https://t.me/MediaStationGo>
+
+---
+
+## 🍜 赞赏
+
+如果这个项目节省了你的时间，欢迎请作者吃桶泡面。
+
+<img width="200" height="200" alt="微信赞赏码" src="https://github.com/user-attachments/assets/d6077de5-8305-400d-8b82-470ef05d926e" />
+
+---
+
+## ⭐ Star History
 
 <a href="https://www.star-history.com/?repos=ShukeBta%2FMediaStationGo&type=date&legend=top-left">
  <picture>
@@ -292,6 +780,17 @@ git ls-files | grep -E 'data/|cache/|\\.db|\\.log|jwt_secret|config.yaml|\\.env'
  </picture>
 </a>
 
-## 许可证
+---
 
-本项目遵循 `GPL-3.0` 许可证。详见 [LICENSE](LICENSE)。
+## 📄 许可证与非商用声明
+
+本项目基础许可证遵循 `GPL-3.0`，详见 [LICENSE](LICENSE)。项目维护者同时声明并倡议：
+
+- 本项目主要面向个人学习、家庭 NAS、自建影音、非商业研究与社区共建场景。
+- 未经作者明确书面许可，不得将本项目或衍生版本用于商业售卖、商业托管、付费 SaaS、预装售卖设备、闭源二次分发或其他商业化牟利用途。
+- 如需商业合作、企业内部部署、定制开发、集成发行或商业授权，请先联系作者确认授权边界。
+- 若 README 的非商用声明与 `GPL-3.0` 正式许可文本存在解释差异，代码授权以 [LICENSE](LICENSE) 文件为准，商业使用请额外取得作者许可。
+
+---
+
+<p align="center">Made with ❤️ by ShukeBta</p>

README_EN.md

@@ -1,70 +1,325 @@
 # MediaStationGo
 
-> A lightweight, polished, NAS-friendly private media center. Go single-binary backend + React frontend for library management, scraping, playback, subscriptions, downloads, Emby-compatible APIs, AI search, and recommendations.
+<p align="center">
+  <img src="web/public/favicon.svg" width="96" height="96" alt="MediaStationGo Logo" />
+</p>
 
-[中文](README.md) · [Docker Deploy](#docker-deploy-recommended) · [One-Click Scripts](#one-click-deploy-scripts) · [Development](#development-and-build)
+<h3 align="center">A lightweight, polished, NAS-friendly private media center</h3>
 
-## Highlights
+<p align="center">
+  <strong>Go single-binary backend · React frontend · Docker-first deployment · Emby-compatible APIs · Multi-source metadata · PT subscriptions</strong>
+</p>
 
-- **Modern UI**: A unified bright premium visual system. The home page focuses on Featured, Continue Watching, and Recently Added. The library page groups movies, series, anime, variety shows, and music with automatically generated cover-folder cards.
-- **Library scanning and organization**: Recursive scanning, ffprobe metadata, season/episode recognition, variety-show grouping by show/season/episode, duplicate prevention, and local NFO/image-first metadata.
-- **Multi-source scraping**: TMDb, TheTVDB, Bangumi, Douban, Fanart.tv, and adult metadata enrichment from JavDB/JavBus pages. Local NFO, poster, fanart, DMM/JAV images are always preferred.
-- **Playback experience**: Direct streaming, HTTP Range seeking, HLS transcoding, external subtitles, watch history, Continue Watching, and external-player entry points.
-- **External client compatibility**: Emby/Jellyfin-style APIs for Infuse, VidHub, SenPlayer, and other third-party clients.
-- **PT and downloads**: Site management, M-Team `x-api-key`, cross-site search, subscriptions, qBittorrent downloads, and intelligent post-download organization.
-- **AI assistant**: OpenAI-compatible endpoint configuration for natural-language search and recommendations. Admin-side API settings take effect at runtime.
-- **Simple deployment**: Bare-metal one-click scripts, Docker Compose, and multi-architecture Docker image build/push scripts.
+<p align="center">
+  <a href="README.md">中文</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#docker-compose-deploy">Docker Deploy</a> ·
+  <a href="#screenshots">Screenshots</a> ·
+  <a href="https://mgo.3jzs.com">Live Demo</a>
+</p>
 
-## Feature Modules
+<p align="center">
+  <img alt="Go" src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white" />
+  <img alt="React" src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=111827" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript&logoColor=white" />
+  <img alt="Docker" src="https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white" />
+  <img alt="License" src="https://img.shields.io/badge/License-GPL--3.0-blue?style=flat-square" />
+  <img alt="Use" src="https://img.shields.io/badge/Use-Non--Commercial-orange?style=flat-square" />
+</p>
 
-| Module | Capabilities |
+---
+
+## ✨ Overview
+
+MediaStationGo is an open-source media center for personal libraries, family NAS setups, and home-theater enthusiasts. It combines library management, metadata scraping, web playback, third-party client compatibility, PT site search, subscription-based downloads, and AI-assisted recommendations into one lightweight Go service with a polished React interface.
+
+It is designed for users who want to:
+
+- Manage movies, TV shows, anime, variety shows, adult content, and music from one place.
+- Prefer local NFO/images first, then enrich missing metadata from TMDb, Douban, Bangumi, TheTVDB, Fanart, JavBus, and JavDB.
+- Search PT sites, subscribe to resources, enqueue downloads, and organize completed files from one panel.
+- Connect external clients such as Infuse, VidHub, SenPlayer, and other Emby/Jellyfin-compatible apps.
+- Deploy easily on NAS, Windows, Linux, macOS, or Docker without leaking private tracker tokens to the frontend.
+
+> The project is under active development. For production use, pin a release image tag and back up `/data` regularly.
+
+---
+
+## 🌱 Open Source Promise
+
+MediaStationGo follows a fully open-source path. The core media library, metadata scraping, playback, subscriptions, downloads, external-client compatibility, and operations features are developed in this repository. The project learns from excellent open-source projects such as MoviePilot in areas like site aggregation, subscription downloads, post-download organization, and Emby/Jellyfin client compatibility, while keeping MediaStationGo as an independent implementation and avoiding incompatible code reuse.
+
+The current base license is `GPL-3.0`, and contributions are welcome under that license: site adapters, scraping rules, UI improvements, documentation, and bug fixes all help the project grow. The maintainers also state the intended usage boundary: MediaStationGo is provided for personal learning, home NAS, self-hosted media, and non-commercial scenarios. Without explicit written permission from the author, do not use this project or derivative versions for commercial resale, paid hosting, paid SaaS, pre-installed commercial devices, closed-source redistribution, or other profit-oriented commercial use.
+
+> Note: GPL-3.0 is a free software license, and the formal grant is defined by the repository [LICENSE](LICENSE) file. The non-commercial commitment above expresses the maintainer's intended usage boundary and commercial cooperation requirements. For commercial cooperation, enterprise deployment, or redistribution, contact the author for additional authorization first.
+
+---
+
+## 🚀 Live Demo
+
+- Demo: [https://mgo.3jzs.com](https://mgo.3jzs.com)
+- Username: `admin`
+- Password: `admin123`
+
+> The demo is for feature preview only. Do not store private API keys, tracker tokens, or personal media information there.
+
+---
+
+## 🧭 Feature Overview
+
+| Area | Capabilities |
 | --- | --- |
-| Libraries | Movies, TV, anime, variety, music, adult content; automatic covers and season/episode grouping |
-| Scraping | Local NFO/images first, then TMDb/TheTVDB/Bangumi/Douban/Fanart/JavBus/JavDB enrichment |
-| Playback | Direct play, HLS, subtitles, resume, external players, history, favorites |
-| Discovery | TMDb / Douban / Bangumi recommendation sources and subscription entry points |
-| Downloads | qBittorrent, PT sites, RSS/search subscriptions, automatic organization |
-| Compatibility | Emby API, DLNA-ready structure, external clients, responsive three-end UI |
-| Operations | Tasks, statistics, storage, duplicate files, recycle bin, NFO export |
-| AI | OpenAI-compatible Base URL/API Key, smart search, recommendations |
+| Libraries | Movies, TV, anime, variety, music, adult content; folder covers, series, seasons, and episodes |
+| Scanning | Recursive scanning, ffprobe probing, filename parsing, season/episode recognition, duplicate prevention |
+| Local metadata | NFO, poster, fanart, season poster, episode image, local adult artwork first |
+| Online metadata | TMDb, TheTVDB, Bangumi, Douban, Fanart.tv, JavBus/JavDB page scraping |
+| Playback | Direct streaming, HTTP Range seeking, HLS transcoding, external subtitles, progress, resume, external players |
+| Discovery | TMDb / Douban / Bangumi recommendation rails and subscription entry points |
+| PT sites | Site management, M-Team API token, cross-site search, download URL resolution |
+| Subscriptions | RSS/search subscriptions, resolution/quality/effects/release-group rules, wash toggle and priorities |
+| Downloads | qBittorrent task cards, status, speed, progress, uploaded/downloaded size, private URL redaction |
+| Compatibility | Emby-style APIs for Infuse, VidHub, SenPlayer, and similar clients |
+| Operations | Runtime status, task queue, duplicate files, recycle bin, file manager, storage settings, notifications |
+| AI | OpenAI-compatible API settings, AI search, recommendations, and operations assistant |
 
-## Docker Deploy (Recommended)
+---
+
+<a id="screenshots"></a>
+
+## 🖼️ Screenshots
+
+> Screenshots below were captured from a running local instance. Personal media, local paths, accounts, API keys, tokens, and secrets have been visually redacted.
+
+<details open>
+<summary><strong>Core Experience</strong></summary>
+
+| Login & Home | Library Overview |
+| --- | --- |
+| <img src="docs/screenshots/00-login.jpg" alt="Login" width="100%"> | <img src="docs/screenshots/01-home.jpg" alt="Home" width="100%"> |
+| Libraries | Library Detail |
+| <img src="docs/screenshots/02-libraries.jpg" alt="Libraries" width="100%"> | <img src="docs/screenshots/03-library-detail.jpg" alt="Library Detail" width="100%"> |
+| Poster Wall | Media Detail |
+| <img src="docs/screenshots/04-poster-wall.jpg" alt="Poster Wall" width="100%"> | <img src="docs/screenshots/05-media-detail.jpg" alt="Media Detail" width="100%"> |
+| Player | Discover |
+| <img src="docs/screenshots/06-player.jpg" alt="Player" width="100%"> | <img src="docs/screenshots/07-discover.jpg" alt="Discover" width="100%"> |
+| Smart Search | DLNA Cast |
+| <img src="docs/screenshots/08-search.jpg" alt="Smart Search" width="100%"> | <img src="docs/screenshots/09-dlna.jpg" alt="DLNA" width="100%"> |
+
+</details>
+
+<details>
+<summary><strong>Personal Space & Playback</strong></summary>
+
+| AI Assistant | Favorites |
+| --- | --- |
+| <img src="docs/screenshots/10-ai.jpg" alt="AI Assistant" width="100%"> | <img src="docs/screenshots/11-favourites.jpg" alt="Favorites" width="100%"> |
+| Playlists | Watch History |
+| <img src="docs/screenshots/12-playlists.jpg" alt="Playlists" width="100%"> | <img src="docs/screenshots/13-history.jpg" alt="Watch History" width="100%"> |
+| Profile | Downloads |
+| <img src="docs/screenshots/14-profile.jpg" alt="Profile" width="100%"> | <img src="docs/screenshots/15-downloads.jpg" alt="Downloads" width="100%"> |
+
+</details>
+
+<details>
+<summary><strong>Downloads, Subscriptions & Sites</strong></summary>
+
+| Download Clients | Subscriptions |
+| --- | --- |
+| <img src="docs/screenshots/16-download-clients.jpg" alt="Download Clients" width="100%"> | <img src="docs/screenshots/17-subscriptions.jpg" alt="Subscriptions" width="100%"> |
+| Site Search | Sites & Downloaders |
+| <img src="docs/screenshots/18-site-search.jpg" alt="Site Search" width="100%"> | <img src="docs/screenshots/20-sites.jpg" alt="Sites" width="100%"> |
+
+</details>
+
+<details>
+<summary><strong>Administration & Operations</strong></summary>
+
+| Media & Users | Tools |
+| --- | --- |
+| <img src="docs/screenshots/19-admin.jpg" alt="Admin" width="100%"> | <img src="docs/screenshots/21-tools.jpg" alt="Tools" width="100%"> |
+| Storage & Files | Runtime Status |
+| <img src="docs/screenshots/22-storage.jpg" alt="Storage" width="100%"> | <img src="docs/screenshots/23-stats.jpg" alt="Stats" width="100%"> |
+| Settings | Tasks |
+| <img src="docs/screenshots/24-settings.jpg" alt="Settings" width="100%"> | <img src="docs/screenshots/25-tasks.jpg" alt="Tasks" width="100%"> |
+| Duplicates | Recycle Bin |
+| <img src="docs/screenshots/26-duplicates.jpg" alt="Duplicates" width="100%"> | <img src="docs/screenshots/27-recycle.jpg" alt="Recycle Bin" width="100%"> |
+| Scheduler | File Manager |
+| <img src="docs/screenshots/28-scheduler.jpg" alt="Scheduler" width="100%"> | <img src="docs/screenshots/29-files.jpg" alt="Files" width="100%"> |
+| STRM | Storage Config |
+| <img src="docs/screenshots/30-strm.jpg" alt="STRM" width="100%"> | <img src="docs/screenshots/31-storage-config.jpg" alt="Storage Config" width="100%"> |
+| Notifications | Operations Assistant |
+| <img src="docs/screenshots/32-notify-channels.jpg" alt="Notifications" width="100%"> | <img src="docs/screenshots/33-assistant.jpg" alt="Operations Assistant" width="100%"> |
+
+</details>
+
+---
+
+## 🧱 Tech Stack
+
+| Layer | Technology | Notes |
+| --- | --- | --- |
+| Backend | Go 1.25+ | Single-binary deployment, low resource usage |
+| Web framework | Gin | REST APIs, auth middleware, static file serving |
+| Database | SQLite + GORM | Simple backup and migration for personal/NAS usage |
+| Frontend | React 18 + TypeScript | Typed component-based UI |
+| Build tool | Vite | Fast frontend development and production builds |
+| Styling | Tailwind CSS | Unified bright visual system and responsive layout |
+| State | Zustand | Lightweight auth and permission state |
+| Playback | HTML5 Video / HLS / FFmpeg | Direct play, Range seek, HLS transcoding, subtitles |
+| Metadata | TMDb / Douban / Bangumi / TheTVDB / Fanart / JavBus / JavDB | Posters, backdrops, descriptions, ratings, episode metadata |
+| Downloads | qBittorrent / PT site adapters | Search, subscriptions, task cards, private URL redaction |
+| Compatibility | Emby-style API / DLNA | External clients and player integrations |
+| Deployment | Docker / Docker Compose / Shell / PowerShell | NAS, Linux, Windows, and macOS friendly |
+| CI/CD | GitHub Actions / GHCR | Multi-arch Docker images and release packages |
+
+---
+
+<a id="quick-start"></a>
+
+## 📦 Quick Start
+
+<a id="docker-compose-deploy"></a>
+
+### Docker Compose (Recommended)
+
+Docker is the most stable and portable deployment option. The default compose file creates four main mounts:
+
+| Host path | Container path | Purpose |
+| --- | --- | --- |
+| `./data` | `/data` | Database, JWT secret, runtime settings. Back this up. |
+| `./cache` | `/cache` | Posters, backdrops, scraping cache, transcoding cache |
+| `./media` | `/media` | Media library root, mounted read-only by default |
+| `./downloads` | `/downloads` | Subscription/site download target |
 
 ```bash
 git clone https://github.com/ShukeBta/MediaStationGo.git
 cd MediaStationGo
-cp config.example.yaml config.yaml
+
+docker compose pull
 docker compose up -d
 ```
 
-Default URL: `http://<server-ip>:18080`
+Open:
 
-Default account: `admin` / `admin123`
-
-> Change the administrator password immediately after the first login, then add media folders from the admin UI.
-
-### Key docker-compose Mounts
-
-```yaml
-volumes:
-  - ./data:/data
-  - ./cache:/cache
-  - ./media:/media:ro
+```text
+http://<server-ip>:18080
 ```
 
-Override the default port and media path with environment variables:
+Default account:
+
+```text
+Username: admin
+Password: admin123
+```
+
+> Change the administrator password immediately after first login.
+
+### Pin a Release Version
+
+For production, pin a specific release tag instead of using `latest`:
 
 ```bash
-MEDIASTATION_HTTP_PORT=18080 MEDIASTATION_MEDIA_DIR=/your/media/path docker compose up -d
+cat > .env <<'EOF'
+MEDIASTATION_IMAGE_TAG=MediaStationGo-v0.0.4
+MEDIASTATION_HTTP_PORT=18080
+MEDIASTATION_MEDIA_DIR=/mnt/nas/media
+MEDIASTATION_DOWNLOAD_DIR=/mnt/nas/downloads
+MEDIASTATION_DATA_DIR=./data
+MEDIASTATION_CACHE_DIR=./cache
+TZ=Asia/Shanghai
+EOF
+
+docker compose up -d
 ```
 
-### Hardware Transcoding
+### Media Library Paths
 
-- Intel QSV/VAAPI: mount `/dev/dri:/dev/dri`
-- NVIDIA NVENC: install NVIDIA Container Toolkit on the host and enable `gpus: all`
-- Software transcoding: no additional setup required
+If your compose mounts are:
 
-## One-Click Deploy Scripts
+```yaml
+- /mnt/nas/media:/media:ro
+- /mnt/nas/downloads:/downloads
+```
+
+then add libraries in the web UI using container paths:
+
+| Type | Recommended path |
+| --- | --- |
+| Movies | `/media/Movies` |
+| TV | `/media/TV` |
+| Anime | `/media/Anime` |
+| Variety | `/media/Variety` |
+| Adult | `/media/Adult` |
+| Downloaded media | `/downloads/Movies`, `/downloads/TV`, etc. |
+
+### Download Client Paths
+
+If qBittorrent also runs in Docker, make sure qBittorrent and MediaStationGo share the same host directory and use consistent container paths.
+
+Recommended mapping:
+
+```text
+Host: /mnt/nas/downloads
+MediaStationGo container: /downloads
+qBittorrent container: /downloads
+```
+
+Subscription save paths can then be:
+
+```text
+/downloads/Movies
+/downloads/TV
+/downloads/Anime
+/downloads/Variety
+```
+
+---
+
+## 🐳 Docker Compose Configuration
+
+The repository includes a heavily commented `docker-compose.yml`. Common variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `MEDIASTATION_IMAGE_TAG` | `latest` | Image tag. Pin a release for production. |
+| `MEDIASTATION_HTTP_PORT` | `18080` | Host access port |
+| `MEDIASTATION_DATA_DIR` | `./data` | Persistent data directory |
+| `MEDIASTATION_CACHE_DIR` | `./cache` | Image and transcoding cache |
+| `MEDIASTATION_MEDIA_DIR` | `./media` | Host media library root |
+| `MEDIASTATION_DOWNLOAD_DIR` | `./downloads` | Host download target |
+| `PUID` / `PGID` | `1000` / `1000` | Linux/NAS file permission mapping |
+| `TZ` | `Asia/Shanghai` | Container timezone |
+
+View logs:
+
+```bash
+docker logs -f mediastation-go
+```
+
+Update:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Stop:
+
+```bash
+docker compose down
+```
+
+Back up data:
+
+```bash
+tar -czf mediastationgo-data-backup.tgz ./data
+```
+
+---
+
+## 🖥️ One-Click Deployment Scripts
+
+If you do not want Docker, run MediaStationGo directly on the host. The scripts build the frontend, compile the backend, start the service, and verify `/api/health`.
 
 ### Linux / macOS
 
@@ -83,59 +338,83 @@ cd MediaStationGo
 .\scripts\deploy.ps1 -Port 18080 -DataDir D:\MediaStationGo\data -CacheDir D:\MediaStationGo\cache
 ```
 
-The scripts automatically:
+The scripts will:
 
 1. Install frontend dependencies and build `web/dist`
-2. Compile the Go server into `bin/`
+2. Compile the Go backend into `bin/`
 3. Create data and cache directories
-4. Stop any previously started process
-5. Start the service and verify `/api/health`
+4. Stop any previous process and start a new one
+5. Verify the service through `/api/health`
 
-## Docker Image Build and Push
+---
 
-The default image is `ghcr.io/shukebta/mediastation-go:latest`:
+## 🧩 Release Package Deployment
+
+Each release provides multi-platform archives:
+
+| Platform | Package example |
+| --- | --- |
+| Linux x86_64 | `MediaStationGo-v0.0.4-linux-amd64.tar.gz` |
+| Linux ARM64 | `MediaStationGo-v0.0.4-linux-arm64.tar.gz` |
+| Windows x86_64 | `MediaStationGo-v0.0.4-windows-amd64.zip` |
+| macOS Intel | `MediaStationGo-v0.0.4-darwin-amd64.tar.gz` |
+| macOS Apple Silicon | `MediaStationGo-v0.0.4-darwin-arm64.tar.gz` |
+
+Linux example:
 
 ```bash
-docker login ghcr.io
-IMAGE=ghcr.io/shukebta/mediastation-go TAG=latest ./scripts/docker-build-push.sh
+tar -xzf MediaStationGo-v0.0.4-linux-amd64.tar.gz
+cd MediaStationGo-v0.0.4-linux-amd64
+MEDIASTATION_APP_PORT=18080 ./mediastation-go
+```
+
+Windows example:
+
+```powershell
+Expand-Archive .\MediaStationGo-v0.0.4-windows-amd64.zip
+cd .\MediaStationGo-v0.0.4-windows-amd64
+$env:MEDIASTATION_APP_PORT = "18080"
+.\mediastation-go.exe
+```
+
+> Release binaries listen on `8080` by default. Set `MEDIASTATION_APP_PORT=18080` as shown above if you want the same port as the Docker examples.
+
+---
+
+## 🛠️ Local Development
+
+### Requirements
+
+| Component | Version | Purpose |
+| --- | --- | --- |
+| Go | 1.25+ | Backend build and tests |
+| Node.js | 20+ | Frontend build |
+| FFmpeg / ffprobe | Recommended | Media probing and transcoding |
+| Docker | Optional | Container deployment and multi-arch builds |
+| qBittorrent | Optional | Download integration testing |
+
+### Build Locally
+
+```bash
+cp config.example.yaml config.yaml
+cd web
+npm ci
+npm run build
+cd ..
+go build -o bin/mediastation-go ./cmd/server
+./bin/mediastation-go
 ```
 
 Windows:
 
 ```powershell
-docker login ghcr.io
-.\scripts\docker-build-push.ps1 -Image ghcr.io/shukebta/mediastation-go -Tag latest
-```
-
-Build locally without pushing:
-
-```bash
-PUSH=0 TAG=dev ./scripts/docker-build-push.sh
-```
-
-```powershell
-.\scripts\docker-build-push.ps1 -Tag dev -Load
-```
-
-## Development and Build
-
-### Requirements
-
-| Component | Version |
-| --- | --- |
-| Go | 1.25+ |
-| Node.js | 20+ |
-| FFmpeg / ffprobe | Recommended |
-| Docker | Optional |
-
-### Local Build
-
-```bash
-cp config.example.yaml config.yaml
-cd web && npm ci && npm run build
-cd ..
-go build -o bin/mediastation-go ./cmd/server
-./bin/mediastation-go
+Copy-Item config.example.yaml config.yaml
+Set-Location web
+npm ci
+npm run build
+Set-Location ..
+go build -o bin\mediastation-go.exe .\cmd\server
+.\bin\mediastation-go.exe
 ```
 
 ### Common Commands
@@ -143,18 +422,42 @@ go build -o bin/mediastation-go ./cmd/server
 ```bash
 make build       # Build frontend and backend
 make test        # Run Go tests
+make smoke       # Smoke test
 make docker      # docker compose up -d
 make deploy      # Linux one-click deploy
 make docker-push # Multi-arch buildx push
 ```
 
-Windows users can run:
+---
 
-```powershell
-.\scripts\deploy.ps1
+## 🏗️ Repository Layout
+
+```text
+MediaStationGo/
+├── cmd/server/                 # Server entry point
+├── internal/
+│   ├── config/                  # Config loading and defaults
+│   ├── database/                # SQLite initialization and migrations
+│   ├── handler/                 # HTTP API, Emby API, admin endpoints
+│   ├── middleware/              # Auth, permission, logging middleware
+│   ├── model/                   # GORM models
+│   ├── repository/              # Data access layer
+│   └── service/                 # Scanner, scraper, playback, downloads, subscriptions
+├── web/
+│   ├── public/                  # favicon and static public assets
+│   ├── src/                     # React pages, components, API clients, stores
+│   └── dist/                    # Frontend build output, ignored by git
+├── scripts/                     # Deploy, package, Docker scripts
+├── docs/                        # Design docs, screenshots, architecture notes
+├── docker-compose.yml           # Default Docker Compose deployment
+├── Dockerfile                   # Multi-stage image build
+├── config.example.yaml          # Config template
+└── README.md / README_EN.md     # Documentation
 ```
 
-## Configuration
+---
+
+## ⚙️ Configuration
 
 Configuration precedence, from low to high:
 
@@ -162,49 +465,329 @@ Configuration precedence, from low to high:
 2. `config.yaml`
 3. `config/*.yaml`
 4. `MEDIASTATION_` environment variables
-5. Runtime settings stored in the database, such as API keys, sites, and download clients
+5. Runtime settings stored in the database
 
-Common environment variables:
+Common variables:
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `MEDIASTATION_APP_PORT` | `8080` | Web service port |
-| `MEDIASTATION_APP_DATA_DIR` | `./data` | Data directory |
-| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite database path |
+| `MEDIASTATION_APP_HOST` | `0.0.0.0` | Listen address |
+| `MEDIASTATION_APP_PORT` | `8080` | Listen port |
 | `MEDIASTATION_APP_WEB_DIR` | `./web/dist` | Frontend static bundle |
+| `MEDIASTATION_APP_DATA_DIR` | `./data` | App data directory |
+| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite database path |
 | `MEDIASTATION_CACHE_CACHE_DIR` | `./cache` | Image/transcode cache |
-| `MEDIASTATION_SECRETS_JWT_SECRET` | Auto-generated | JWT and encryption seed |
+| `MEDIASTATION_SECRETS_JWT_SECRET` | Auto-generated | JWT and encrypted settings seed |
+| `MEDIASTATION_APP_CORS_ORIGINS` | empty | Extra CORS origins |
 
-## APIs and External Services
+Runtime settings from the admin UI:
 
-Configure external services from the admin UI:
+- API keys: TMDb, Bangumi, TheTVDB, Fanart, OpenAI Compatible.
+- Sites: M-Team, NexusPHP, Unit3D, custom RSS.
+- Download clients: qBittorrent, Transmission, Aria2.
+- Notifications: Telegram, Bark, Webhook, Email.
+- Playback profiles, permissions, scheduler tasks, storage settings.
 
-- TMDb: movie and TV metadata
-- Bangumi: anime and series metadata
-- TheTVDB: additional TV metadata
-- Fanart.tv: high-resolution artwork
-- OpenAI Compatible: AI search and recommendations
-- Adult/JAV: JavBus/JavDB page scraping, no API key required
+---
 
-For M-Team, generate an API Access Token from `Control Panel → Lab → Access Token` and send it as `x-api-key`. Do not use cookies for the open API.
+## 🔍 Metadata Strategy
 
-## Privacy and Repository Safety
+MediaStationGo avoids unnecessary repeated scraping and tries not to overwrite good local metadata:
 
-The project ignores personal and runtime data by default:
+1. Read local NFO, poster, fanart, season poster, and episode images first.
+2. Parse media type, title, year, season, and episode from file paths.
+3. Fill missing data through TMDb, TheTVDB, Bangumi, and Douban.
+4. Use Fanart.tv for higher-quality artwork when available.
+5. Adult content prefers local NFO/images, then enriches from public JavBus/JavDB pages.
+6. Existing local metadata is not blindly overwritten.
+
+Recommended layout:
+
+```text
+/media/Movies/Inception (2010)/Inception (2010).mkv
+/media/TV/Some Show/Season 01/Some Show S01E01.mkv
+/media/Anime/Anime Title/Season 01/Anime Title S01E01.mkv
+/media/Variety/Show Name/Season 2026/Show Name S2026E01.mkv
+/media/Adult/ABCD-123/ABCD-123.mp4
+```
+
+Common local artwork names:
+
+```text
+poster.jpg
+fanart.jpg
+folder.jpg
+season01-poster.jpg
+S01E01-thumb.jpg
+movie.nfo
+tvshow.nfo
+episode.nfo
+```
+
+---
+
+## 🔎 Discovery, Search & Subscriptions
+
+### Multi-source discovery
+
+Discover supports:
+
+- TMDb: trending, popular movies, popular TV, top-rated movies.
+- Douban: hot movies, top movies, hot TV.
+- Bangumi: calendar and anime entries.
+
+### Smart search
+
+Smart search can combine:
+
+- Existing local library content.
+- Online results from TMDb, Douban, and Bangumi.
+- Subscription keywords and media types.
+
+### Subscription rules
+
+| Rule | Description |
+| --- | --- |
+| Media type | Movie, TV, anime, variety, or auto-detect |
+| Search mode | Keyword or IMDB ID |
+| Resolution | Best, 2160p, 1080p, 720p |
+| Quality | REMUX, BluRay, WEB-DL, HDTV |
+| Effects | HDR, Dolby Vision, Atmos |
+| Release groups | Preferred release groups |
+| Exclude words | Filter CAM, TS, low-quality releases |
+| Wash | Disabled by default; can prioritize resolution, quality, effects, or seeders |
+
+Download and subscription cards show only safe display metadata such as title, poster, speed, progress, and size. Raw torrent URLs are hidden to prevent tracker token leaks in multi-user deployments.
+
+---
+
+## 🔌 External Clients & Emby Compatibility
+
+MediaStationGo exposes Emby/Jellyfin-style APIs for clients such as:
+
+- Infuse
+- VidHub
+- SenPlayer
+- Other Emby/Jellyfin-compatible players
+
+Server URL:
+
+```text
+http://<server-ip>:18080
+```
+
+If a client cannot connect, check:
+
+1. Docker port mapping, typically `18080:8080`.
+2. Firewall access from LAN to port `18080`.
+3. Username/password.
+4. Reverse proxy handling of `/api`, video streams, and Range requests.
+
+### Functional Reference to MoviePilot
+
+For external-client compatibility and media workflow integration, MediaStationGo references MoviePilot's mature product direction: a unified media library, subscription downloads, post-download organization, and Emby/Jellyfin-compatible APIs that connect the Web management interface with clients such as Infuse, VidHub, and SenPlayer. MediaStationGo does not aim to replace Emby/Jellyfin; instead, it provides the common browsing, playback, poster wall, season/episode hierarchy, progress tracking, and external-client access capabilities inside a lightweight Go service.
+
+Current compatibility focus:
+
+- Library, collection, season, and episode hierarchy output.
+- Basic metadata output such as posters, backdrops, descriptions, year, and ratings.
+- Stream URLs, HTTP Range support, playback progress, and resume.
+- Emby/Jellyfin-style endpoints required for external-client login, browsing, and playback.
+
+Still being improved:
+
+- More complete Emby/Jellyfin device capability negotiation.
+- More detailed transcoding profiles and subtitle capability declarations.
+- Multi-user permissions, library filtering, and playback-history synchronization.
+- Closed-loop integration with subscriptions, post-download organization, and upgrade rules.
+
+> MoviePilot is licensed under GPL-3.0. MediaStationGo references its public product ideas and interaction patterns only, and does not copy private data, secrets, tracker accounts, or incompatible implementations.
+
+---
+
+## 🧠 AI and External Services
+
+Configure external services in the admin UI:
+
+| Service | Purpose |
+| --- | --- |
+| TMDb | Movie/TV posters, backdrops, descriptions |
+| Bangumi | Anime and Chinese anime metadata |
+| TheTVDB | Additional TV/season/episode metadata |
+| Fanart.tv | High-quality logos and artwork |
+| Douban | Chinese movie/TV search and recommendation supplement |
+| OpenAI Compatible | AI search, recommendations, operations assistant |
+
+For M-Team, use an API Access Token:
+
+```text
+Control Panel → Lab → Access Token
+HTTP Header: x-api-key
+```
+
+Avoid using cookies for open API calls to reduce account risk.
+
+---
+
+## 🧪 Build, Package and Publish
+
+### Docker image
+
+Default images:
+
+```text
+ghcr.io/shukebta/mediastation-go:latest
+ghcr.io/shukebta/mediastation-go:MediaStationGo-v0.0.4
+```
+
+Linux/macOS push:
+
+```bash
+docker login ghcr.io
+IMAGE=ghcr.io/shukebta/mediastation-go TAG=MediaStationGo-v0.0.4 ./scripts/docker-build-push.sh
+```
+
+Windows push:
+
+```powershell
+docker login ghcr.io
+.\scripts\docker-build-push.ps1 -Image ghcr.io/shukebta/mediastation-go -Tag MediaStationGo-v0.0.4
+```
+
+Local build only:
+
+```powershell
+.\scripts\docker-build-push.ps1 -Tag dev -Load
+```
+
+### Release packages
+
+```bash
+VERSION=MediaStationGo-v0.0.4 ./scripts/package-release.sh
+```
+
+GitHub Actions automatically builds release packages and SHA256 checksums when a `MediaStationGo-v*` tag is pushed.
+
+> If immutable releases are enabled, same-name assets should not be overwritten. The workflow uses `overwrite_files: false` to avoid deleting immutable assets on reruns.
+
+---
+
+## 🔐 Privacy and Safety
+
+The repository ignores personal/runtime data by default:
 
 - `data/`, `cache/`, `logs/`
-- `.tmp-deploy-data/`, `.tmp-deploy-server.*`, `.mediastation.pid`
+- `.tmp-deploy-data/`, `.tmp-deploy-server.*`
+- `.mediastation.pid`
 - `config.yaml`, `.env*`
 - `*.db`, `*.db-wal`, `*.log`
 - `web/dist/`, `node_modules/`, `bin/`
+- API keys, cookies, tokens, passwords, certificates, and secret files
 
-Before pushing code, run:
+Before pushing, run:
 
 ```bash
 git status --short
-git ls-files | grep -E 'data/|cache/|\\.db|\\.log|jwt_secret|config.yaml|\\.env' || true
+git ls-files | grep -E 'data/|cache/|\.db|\.log|jwt_secret|config.yaml|\.env|token|apikey|password' || true
 ```
 
-## License
+---
 
-This project is licensed under `GPL-3.0`. See [LICENSE](LICENSE) for details.
+## ❓ FAQ
+
+### The Docker deployment starts but the browser cannot open the site.
+
+Check container status and logs:
+
+```bash
+docker ps
+docker logs -f mediastation-go
+```
+
+Use the host port, usually `http://<server-ip>:18080`.
+
+### External clients report that the server does not respond.
+
+Check firewall rules, Docker port mappings, reverse proxy configuration, and LAN access to `18080`. The container listens on `8080`; the host default is `18080`.
+
+### Posters are missing.
+
+Check:
+
+1. Local `poster.jpg`, `fanart.jpg`, and NFO files.
+2. TMDb / Bangumi / Douban connectivity.
+3. Proxy settings if the host is behind a restricted network.
+4. Whether file names contain clear title, year, season, and episode information.
+
+### Why are raw download URLs hidden?
+
+PT download URLs often include private tokens. Download and subscription views intentionally hide raw URLs and only show safe metadata such as title, poster, speed, progress, and size.
+
+### Which Docker package should be kept?
+
+Keep `ghcr.io/shukebta/mediastation-go`. The old `mediastationgo` package can be removed to avoid users pulling the wrong image.
+
+---
+
+## 🗺️ Roadmap
+
+- Broader Emby/Jellyfin client compatibility.
+- Stronger adult metadata handling from local files and public pages.
+- More granular subscription wash and post-download organization rules.
+- Better mobile and TV interaction patterns.
+- Plugin-style site adapters and notification providers.
+- More end-to-end tests and automated screenshot generation.
+
+---
+
+## 🤝 Contributing
+
+Issues, pull requests, site adapters, scraping rules, UI improvements, and documentation fixes are welcome.
+
+Before submitting changes, please run:
+
+```bash
+go test ./...
+cd web && npm run build
+```
+
+---
+
+## 👥 Developer Group
+
+- Telegram: <https://t.me/MediaStationGo>
+
+---
+
+## 🍜 Donation
+
+If MediaStationGo saves you time, feel free to buy the author a bowl of noodles.
+
+<img width="200" height="200" alt="WeChat Donation QR" src="https://github.com/user-attachments/assets/d6077de5-8305-400d-8b82-470ef05d926e" />
+
+---
+
+## ⭐ Star History
+
+<a href="https://www.star-history.com/?repos=ShukeBta%2FMediaStationGo&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=ShukeBta/MediaStationGo&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=ShukeBta/MediaStationGo&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=ShukeBta/MediaStationGo&type=date&legend=top-left" />
+ </picture>
+</a>
+
+---
+
+## 📄 License and Non-Commercial Statement
+
+This project uses `GPL-3.0` as its base license. See [LICENSE](LICENSE) for details. The maintainers also state and request the following usage boundary:
+
+- The project is intended for personal learning, home NAS, self-hosted media, non-commercial research, and community collaboration.
+- Without explicit written permission from the author, do not use this project or derivative versions for commercial resale, paid hosting, paid SaaS, pre-installed commercial devices, closed-source redistribution, or other profit-oriented commercial use.
+- For commercial cooperation, enterprise deployment, custom development, integrated redistribution, or commercial authorization, contact the author first to confirm the authorization scope.
+- If there is any interpretive difference between the README non-commercial statement and the formal `GPL-3.0` license text, the code license is governed by [LICENSE](LICENSE); commercial usage should additionally obtain author permission.
+
+---
+
+<p align="center">Made with ❤️ by ShukeBta</p>