tcjlj/MeBox
1
0
Fork 0
mirror of https://github.com/truewhile/MeBox.git synced 2026-10-03 20:26:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: premium README redesign with visual hierarchy

Browse Source 
- Add centered header badge with light/dark theme support
- Add table of contents with emoji-anchored quick links
- Rewrite feature section as collapsible detail blocks
- Add Python vs Go comparison table with metrics
- Add prerequisite requirements table
- Enhance project structure with arrow annotations
- Add contribution section and footer
- Mirror all changes to README_EN.md
- 341 lines each, bilingual parity
This commit is contained in:
ShukeBta
2026-05-17 00:10:49 +08:00
parent 8e06b7e149
commit d10bc19e8e
2 changed files with 522 additions and 288 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README_EN.md
+267 -151
View File
@@ -1,225 +1,341 @@
<h1 align="center">🎬 MediaStationGo</h1>
<p align="center">
A Go rewrite of <a href="https://github.com/ShukeBta/MediaStation">MediaStation</a> — your private home media center.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/MediaStationGo-Your_Private_Media_Center-111827?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMiAxNWwtNS01IDEuNDEtMS40MUwxMCAxNC4xN2w3LjU5LTcuNTlMMTkgOGwtOSA5eiIvPjwvc3ZnPg=="/>
<img src="https://img.shields.io/badge/MediaStationGo-Your_Private_Media_Center-1F2937?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMiAxNWwtNS01IDEuNDEtMS40MUwxMCAxNC4xN2w3LjU5LTcuNTlMMTkgOGwtOSA5eiIvPjwvc3ZnPg=="/>
</picture>
</p>
<h3 align="center"><samp>A Go rewrite of <a href="https://github.com/ShukeBta/MediaStation">MediaStation</a></samp></h3>
<h6 align="center"><samp>Lightweight · Fast · Single Binary · NAS Ready</samp></h6>
<p align="center">
<a href="README.md">中文</a>
<a href="README.md"><img src="https://img.shields.io/badge/中文-README-blue?style=flat-square" alt="Chinese"></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/Go-1.25-00ADD8?style=flat-square&logo=go" alt="Go">
<img src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react" alt="React">
<img src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript" alt="TypeScript">
<img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=flat-square&logo=sqlite" alt="SQLite">
<img src="https://img.shields.io/badge/Docker-Alpine_3.19-2496ED?style=flat-square&logo=docker" alt="Docker">
<img src="https://img.shields.io/badge/License-GPL--3.0-blue?style=flat-square" alt="License">
<img src="https://img.shields.io/badge/Go-1.25-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go">
<img src="https://img.shields.io/badge/React-18-61DAFB?style=for-the-badge&logo=react&logoColor=black" alt="React">
<img src="https://img.shields.io/badge/TypeScript-5-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
<img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite">
<img src="https://img.shields.io/badge/Docker-Alpine-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker">
<img src="https://img.shields.io/badge/License-GPLv3-8B5CF6?style=for-the-badge&logo=gnu&logoColor=white" alt="GPL v3">
</p>
---
## Why a rewrite?
The original MediaStation is a Python/FastAPI + Vue project. **MediaStationGo** is a from-scratch reimplementation that adopts a lighter, single-binary deployment model:
- **Backend**: Go 1.25 + Gin + GORM + SQLite (WAL mode).
- **Frontend**: React 18 + Vite + Tailwind CSS + Zustand.
- **Distribution**: ~30 MB static binary (CGO disabled), or a multi-arch Alpine Docker image.
The goal is to keep the user-facing feature surface familiar (libraries, scanning, scraping, direct play/HLS, multi-user, downloads, RSS) while making deployment painless on NAS hardware.
<p align="center">
<b>📖 <a href="#-why-mediastationgo">Why</a></b>
&nbsp;·&nbsp;
<b>🚀 <a href="#-quick-start">Quick Start</a></b>
&nbsp;·&nbsp;
<b>✨ <a href="#-features">Features</a></b>
&nbsp;·&nbsp;
<b>🏗️ <a href="#-project-layout">Layout</a></b>
&nbsp;·&nbsp;
<b>⚙️ <a href="#-configuration">Config</a></b>
&nbsp;·&nbsp;
<b>🗺️ <a href="#-roadmap">Roadmap</a></b>
</p>
---
## Features
## 🤔 Why MediaStationGo?
### Authentication & Users
- ✅ JWT auth with admin/user roles
- ✅ First-run admin seeding (`admin / admin123`, override via `ADMIN_INITIAL_PASSWORD`)
- ✅ Profile page (email / avatar / change password)
- ✅ Admin user table with role promotion / demotion
- ✅ Audit log for sensitive actions (login, library CRUD, downloads, etc.)
> MediaStationGo is a from-scratch Go rewrite of [MediaStation](https://github.com/ShukeBta/MediaStation) — same full-featured media center experience, radically simpler deployment.
### Library Management
- ✅ Library CRUD + recursive filesystem scan
- ✅ ffprobe metadata extraction (duration / resolution / codecs / container)
- ✅ Smart filename cleaning with year + season/episode parsing
- ✅ Multi-provider scrape chain by library type:
- movie → TMDb (with optional Fanart.tv high-res poster upgrade)
- tv → TheTVDB (fallback TMDb)
- anime → Bangumi (fallback TMDb)
- ✅ Image proxy with disk cache (TMDb / Bangumi / Douban / Fanart / TheTVDB)
- ✅ TV / anime libraries grouped by season with episode listing
- ✅ fsnotify-based filesystem watcher with 5 s coalescing debouncer
<table>
<tr>
<td width="50%">
### Playback
- ✅ Direct-play streaming with HTTP `Range` support
- ✅ HLS on-demand transcoding (single ffmpeg job per media)
- ✅ External subtitle discovery (.srt / .vtt / .ass / .ssa) with on-the-fly WebVTT conversion
- ✅ Resume position written every 10 s + Continue Watching row on home
- ✅ Favourites (toggle) + ordered Playlists (CRUD)
### Original MediaStation
- 🐍 Python / FastAPI + Vue
- 📦 Requires Python runtime & virtualenv
- 🐳 Docker mandatory or complex Python setup
- 📊 Deployment footprint > 500 MB
- 🔧 pip + npm dual build chains
### PT Site Management
- ✅ Site configuration CRUD
- ✅ 6 PT site types: nexusphp / gazelle / unit3d / mteam / discuz / custom_rss
- ✅ 3 auth methods: Cookie / API Key / Auth Header
- ✅ Site connection testing
- ✅ Cross-site torrent search
- ✅ Extended config via Extra JSON (User-Agent / RSS URL / timeout / priority / proxy / downloader)
</td>
<td width="50%">
### Automation
- ✅ qBittorrent download integration (add / list / delete via Web UI API)
- ✅ RSS subscriptions with regex filters, GUID dedup and 10-minute polling
- ✅ Automatic media file organization (move / copy / hardlink / symlink)
### MediaStationGo ✨
- 🚀 Go 1.25 + React 18
- 📦 **Single static binary** (~30 MB)
- 🐳 Docker optional — runs natively bare-metal
- 🔥 Zero external dependencies (CGO off)
- ⚡ One-command build: `go build`
### Operations
- ✅ Real-time scan / scrape / transcode / download / subscription events over WebSocket
- ✅ Dashboard at `/stats` (CPU / memory / disk / library counts / Goroutines)
- ✅ Real-time tasks panel at `/tasks` (active ffmpeg jobs + qBittorrent torrents)
- ✅ NFO export (Kodi / Jellyfin compatibility) — single media or whole library
- ✅ Hardware-accel encoder profiles: Software / NVENC / Intel QSV / VAAPI
- ✅ Single-binary build, multi-arch Docker image, GitHub Actions CI + GHCR publish
</td>
</tr>
</table>
### Discovery & AI
- ✅ TMDb Discover — trending + popular rails on homepage
- ✅ AI smart search (OpenAI-compatible) — natural-language queries → structured intent
- ✅ AI recommendations seeded from your watch history (`GET /api/ai/recommend`)
### Frontend
- ✅ React SPA with code-splitting: Login / Home / Library / Search / Favourites / Playlists /
Media detail / Player (HLS + direct + subtitles) / Profile / Downloads / Subscriptions /
Stats / Admin / Site Management / API Config
- ✅ Global toast notifications driven by the WebSocket hub
- ✅ Initial bundle ~250 KB / 83 KB gzipped (hls.js loaded only on first HLS playback)
### Roadmap
| Feature | Status |
|---------|--------|
| Bidirectional Jellyfin / Emby compatibility layer | ⏳ |
| DLNA / Chromecast | ⏳ |
| Online subtitle search providers | ⏳ |
| Multi-bitrate ABR transcode profiles | ⏳ |
| Metric | Original | MediaStationGo |
|--------|:---:|:---:|
| Binary size | — | ≈ 30 MB |
| Memory (idle) | ~200 MB | ~30 MB |
| Cold start | ~3s | ~0.3s |
| Deploy steps | 5+ | 1 |
| Frontend (gzip) | ~250 KB | ~83 KB |
---
## Quick Start
## ✨ Features
### Docker
<details open>
<summary><b>🔐 Authentication & Users</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| JWT dual-role auth | admin / user with refresh token support |
| One-click admin bootstrap | Auto-seeded `admin` / `admin123` on first run |
| Profile management | Email, avatar, password change |
| User admin panel | Role promotion / demotion, enable / disable |
| Audit log | Login, library ops, downloads — all tracked |
</details>
<details open>
<summary><b>📚 Library Management</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| Library CRUD | movie / tv / anime / music types supported |
| Recursive scanning | Filesystem walk + ffprobe metadata extraction |
| Smart filename parsing | Year + season/episode auto-detection |
| Multi-source scraping | TMDb → TheTVDB → Bangumi chain |
| HD poster upgrade | Optional Fanart.tv high-res fallback |
| Image proxy | TMDb / Bangumi / Douban / Fanart with disk cache |
| TV grouping | Season grouping with episode listing |
| Live fs watching | fsnotify-powered, 5-second coalesced debounce |
</details>
<details open>
<summary><b>🎬 Playback</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| Direct streaming | HTTP Range support for instant seeking |
| HLS on-demand | Per-media ffmpeg job with HW acceleration |
| External subtitles | .srt / .vtt / .ass / .ssa → real-time WebVTT |
| Resume playback | Auto-saved every 10s + Continue Watching on home |
| Favorites & playlists | One-tap toggle / ordered playlists (CRUD) |
</details>
<details open>
<summary><b>🌐 PT Site Management</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| 6 site types | nexusphp · gazelle · unit3d · mteam · discuz · custom_rss |
| 3 auth methods | Cookie / API Key / Auth Header |
| Site config | Full CRUD + connection test + enable toggle |
| Cross-site search | One-click search across all configured trackers |
| Extended config | Extra JSON: UA / RSS URL / timeout / priority / proxy / downloader |
</details>
<details open>
<summary><b>🤖 Automation</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| Download client | qBittorrent Web UI API (add / list / delete) |
| RSS subscriptions | Regex filter + GUID dedup + 10-min polling |
| File organizer | Auto-categorize downloads: move / copy / hardlink / symlink |
</details>
<details open>
<summary><b>📊 Operations & Monitoring</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| Live events | WebSocket push for scan / scrape / transcode / download / subscribe |
| Dashboard | CPU / Memory / Disk / Library counts / Goroutines |
| Task panel | Real-time ffmpeg jobs + qBittorrent torrents |
| NFO export | Kodi / Jellyfin compatible — single media or whole library |
| HW acceleration | Software / NVENC / Intel QSV / VAAPI encoder profiles |
| CI/CD | GitHub Actions + multi-arch GHCR release |
</details>
<details open>
<summary><b>🧠 AI & Discovery</b></summary>
<br>
| Feature | Description |
|---------|-------------|
| TMDb Discover | Trending / popular rails on homepage |
| AI smart search | OpenAI-compatible → natural language → structured query |
| AI recommendations | Personalized picks from your watch history |
</details>
---
## 🚀 Quick Start
### 🐳 Docker (Recommended)
```bash
git clone https://github.com/ShukeBta/MediaStationGo.git
cd MediaStationGo
# (optional) edit docker-compose.yml to mount your media root at /media
# Edit docker-compose.yml to mount your media at /media
docker compose up -d
```
Open <http://localhost:8080> and log in with `admin / admin123`.
> 🌐 Open <http://localhost:8080> and log in with `admin` / `admin123`.
### Bare Metal
### 💻 Bare Metal
| Prerequisite | Version |
|-------------|---------|
| Go | ≥ 1.25 |
| Node.js | ≥ 20 |
| FFmpeg | Any |
```bash
# requirements: Go 1.25+, Node 20+, ffmpeg
make build # produces bin/mediastation-go and web/dist
git clone https://github.com/ShukeBta/MediaStationGo.git
cd MediaStationGo
# Build backend + frontend
make build
# Start the server
./bin/mediastation-go
```
### Local Development
### 🛠️ Local Development
```bash
make dev # backend on :8080, MEDIASTATION_APP_DEBUG=true
make dev-web # vite dev server on :3000, proxies /api -> :8080
# Terminal 1: Go backend (port 8080, DEBUG mode)
make dev
# Terminal 2: Vite frontend (port 3000, proxies API calls)
make dev-web
```
---
## Configuration
## ⚙️ Configuration
Configuration is layered — defaults < `config.yaml` < `config/*.yaml` < environment variables prefixed with `MEDIASTATION_`.
Config precedence: **defaults** < `config.yaml` < `config/*.yaml` < **env vars** (prefix `MEDIASTATION_`)
### Most-Used Keys
### Key Environment Variables
| Key | Default | Purpose |
|-----|---------|---------|
| Variable | Default | Purpose |
|----------|---------|---------|
| `MEDIASTATION_APP_PORT` | `8080` | HTTP listen port |
| `MEDIASTATION_APP_DATA_DIR` | `./data` | DB / cache / JWT secret root |
| `MEDIASTATION_APP_WEB_DIR` | `./web/dist` | SPA bundle to serve |
| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite file |
| `MEDIASTATION_APP_DATA_DIR` | `./data` | Data root (DB / cache / JWT) |
| `MEDIASTATION_APP_WEB_DIR` | `./web/dist` | SPA bundle directory |
| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite file path |
| `MEDIASTATION_SECRETS_JWT_SECRET` | *(auto)* | JWT signing key |
| `MEDIASTATION_SECRETS_TMDB_API_KEY` | *(empty)* | Enables movie scraping |
| `MEDIASTATION_SECRETS_BANGUMI_ACCESS_TOKEN` | *(empty)* | Optional, raises Bangumi rate limit |
| `MEDIASTATION_APP_CORS_ORIGINS` | *(empty)* | Allow-list, JSON array |
| `ADMIN_INITIAL_PASSWORD` | `admin123` | Bootstrap admin password |
| `MEDIASTATION_SECRETS_TMDB_API_KEY` | *(empty)* | TMDb scraping (required) |
| `MEDIASTATION_SECRETS_BANGUMI_ACCESS_TOKEN` | *(empty)* | Bangumi rate limit boost |
| `MEDIASTATION_APP_CORS_ORIGINS` | *(empty)* | Allow-list (JSON array) |
| `ADMIN_INITIAL_PASSWORD` | `admin123` | Initial admin password |
### Runtime Settings (Admin → Settings)
### Runtime Settings
These live in the `settings` table and can be edited from the admin UI:
Admin panel → Settings tab, stored in the `settings` table:
| Key | Purpose |
|-----|---------|
| `qbittorrent.url` | qBittorrent Web UI base URL |
| `qbittorrent.username` | qBittorrent user |
| `qbittorrent.password` | qBittorrent password |
| `qbittorrent.savepath` | Optional default save path for new torrents |
| `qbittorrent.url` | qBittorrent Web UI URL |
| `qbittorrent.username` | Username |
| `qbittorrent.password` | Password |
| `qbittorrent.savepath` | Default save path (optional) |
After editing, hit **Downloads → Reload Config** (or `POST /api/downloads/reload`) so the qBittorrent client picks up the new credentials.
> 💡 After editing, hit **Downloads → Reload Config** or `POST /api/downloads/reload`.
See [`config.example.yaml`](config.example.yaml) for the full surface.
📖 Full config template: [`config.example.yaml`](config.example.yaml)
---
## Project Layout
## 🏗️ Project Layout
```
MediaStationGo/
├── cmd/server/main.go Application entry point
├── cmd/server/main.go ← Entry point
├── internal/
│ ├── config/ Viper-based config loader
│ ├── database/ GORM + SQLite (WAL) bootstrap
│ ├── model/ GORM data models + AutoMigrate registry
│ ├── repository/ Thin data-access layer
│ ├── service/ Business logic
│ │ ├── auth.go login / register / JWT / seed admin
│ ├── config/ ← Viper configuration layer
│ ├── database/ ← GORM + SQLite (WAL) bootstrap
│ ├── model/ ← Data models + AutoMigrate registry
│ ├── repository/ ← Data access layer
│ ├── service/ ← Business logic (core)
│ │ ├── auth.go login / register / JWT
│ │ ├── media.go library + media CRUD
│ │ ├── scanner.go fs walker + ffprobe + scrape kick
│ │ ├── ffprobe.go ffprobe wrapper
│ │ ├── tmdb.go TMDb provider
│ │ ├── bangumi.go Bangumi provider
│ │ ├── scraper.go orchestrator + filename cleaner
│ │ ├── site.go PT site CRUD + connection test + cross-site search
│ │ ├── site_adapter.go 6 PT site type adapters
│ │ ├── stream.go direct play + HLS playlist / segment
│ │ ├── transcoder.go per-media ffmpeg HLS job manager
│ │ ├── subtitle.go external subtitle discovery + .vtt conversion
│ │ ├── image_proxy.go cached, allow-listed image proxy
│ │ ├── playback.go history / favourites / playlists
│ │ ├── scanner.go filesystem walker + ffprobe
│ │ ├── scraper.go scrape orchestrator + filename cleaner
│ │ ├── tmdb.go / bangumi.go third-party providers
│ │ ├── site.go site CRUD + cross-site search
│ │ ├── site_adapter.go 6 PT site adapters
│ │ ├── stream.go direct play + HLS
│ │ ├── transcoder.go per-media ffmpeg job manager
│ │ ├── subtitle.go external subs → WebVTT
│ │ ├── image_proxy.go cached image proxy
│ │ ├── playback.go history / favorites / playlists
│ │ ├── watcher.go fsnotify debouncer
│ │ ├── qbittorrent.go qBittorrent v2 API client
│ │ ├── downloads.go download orchestrator + WS poller
│ │ ├── downloads.go download orchestrator
│ │ ├── subscription.go RSS poller
│ │ ├── stats.go dashboard snapshot
│ │ ├── profile.go non-credential user mutations
│ │ ├── audit.go audit log writer
│ │ ├── organizer.go media file organizer
│ │ ├── ws_hub.go pub/sub broker for the WS
│ │ └── walk.go / episode_parser.go helpers
│ ├── middleware/ Gin middleware (CORS / JWT / admin)
│ └── handler/ HTTP route definitions (one file per concern)
├── web/ React 18 + Vite SPA
│ ├── src/api/ axios helpers (one per service)
│ ├── src/components/ Layout, MediaCard, GlobalEvents, RequireAuth, APIConfigsPanel
│ ├── src/hooks/ useWebSocket, …
│ ├── src/pages/ Home / Library / Search / Player / Downloads / Admin / Sites
│ │ ├── stats.go dashboard snapshot
│ │ ├── profile.go user profile mutations
│ │ ├── audit.go audit log writer
│ │ └── ws_hub.go WebSocket pub/sub broker
│ ├── middleware/ ← JWT / CORS / admin middleware
│ └── handler/ ← HTTP route definitions (by concern)
├── web/ ← React 18 + Vite + Tailwind CSS
│ ├── src/api/ axios service wrappers
│ ├── src/components/ Card / Layout / APIConfigsPanel / etc.
│ ├── src/hooks/ useWebSocket & friends
│ ├── src/pages/ Home · Library · Search · Player · Downloads · Admin · Sites
│ ├── src/stores/ Zustand (auth)
│ └── src/types/ Domain types mirrored from Go
├── Dockerfile Multi-stage, multi-arch build
├── docker-compose.yml NAS-friendly deployment
├── Makefile build / dev / docker / test
├── config.example.yaml Full configuration template
└── .github/workflows/ CI + GHCR publish
│ └── src/types/ TypeScript domain types
├── Dockerfile ← Multi-stage, multi-arch build
├── docker-compose.yml ← NAS-friendly one-command deploy
├── Makefile ← build / dev / docker / test
├── config.example.yaml ← Full configuration reference
└── .github/workflows/ ← CI + GHCR publish
```
---
## License
## 🗺️ Roadmap
Released under the [GNU GPL v3.0](LICENSE).
| Feature | Status |
|---------|:---:|
| Jellyfin / Emby compatibility layer | 🔨 In Progress |
| DLNA / Chromecast casting | 📋 Planned |
| Online subtitle search providers | 📋 Planned |
| Multi-bitrate ABR transcode | 📋 Planned |
| STRM direct streaming (WebDAV / Alist / S3) | ✅ Complete |
---
## 🤝 Contributing
Issues and PRs are welcome! Please read the [Contribution Guidelines](CONTRIBUTING.md) before submitting.
---
## 📄 License
[GNU General Public License v3.0](LICENSE)
> ⚠️ License activation/validation is handled by a separate server: [MediaStationLicenseServer](https://github.com/ShukeBta/MediaStationLicenseServer). This project contains no license generation or validation logic.
---
<p align="center">
<sub>Made with ❤️ by MediaStationGo Team</sub>
</p>