chore: bump version to 0.0.57 [skip ci]

VERSION

@@ -1 +1 @@
-0.0.52
+0.0.57

go.mod

@@ -68,6 +68,7 @@ require (
 	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.11 // indirect
+	github.com/ulikunitz/xz v0.5.12 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	golang.org/x/arch v0.3.0 // indirect

go.sum

@@ -152,6 +152,8 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU=
 github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
+github.com/ulikunitz/xz v0.5.12 h1:37Nm15o69RwBkXM0J6A5OlE67RZTfzUxTj8fB3dfcsc=
+github.com/ulikunitz/xz v0.5.12/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=

internal/handler/admin.go

@@ -3,6 +3,7 @@ package handler
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"net/http"
 	"strings"
@@ -27,6 +28,9 @@ func listUsersHandler(svc *service.Container) gin.HandlerFunc {
 		if svc.Sessions != nil {
 			svc.Sessions.ApplyToUsers(c.Request.Context(), users)
 		}
+		for i := range users {
+			users[i].PopulateComputedFields()
+		}
 		c.JSON(http.StatusOK, users)
 	}
 }
@@ -188,19 +192,77 @@ func updateUserStatusHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
-		if req.IsActive {
-			_ = svc.Repo.UserDevice.SetKickedByUser(c.Request.Context(), userID, false)
-		} else {
-			_ = svc.Repo.UserDevice.SetKickedByUser(c.Request.Context(), userID, true)
+			if req.IsActive {
+				_ = svc.Repo.UserDevice.SetKickedByUser(c.Request.Context(), userID, false)
+			} else {
+				_ = svc.Repo.UserDevice.SetKickedByUser(c.Request.Context(), userID, true)
+			}
+			updated, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+			updated.PopulateComputedFields()
+			c.JSON(http.StatusOK, updated)
+		}
+	}
+
+	type adminUpdateUserLibrariesReq struct {
+		AllowedLibraryIDs *[]string `json:"allowed_library_ids"`
+	}
+
+	func updateUserLibrariesHandler(svc *service.Container) gin.HandlerFunc {
+		return func(c *gin.Context) {
+			var req adminUpdateUserLibrariesReq
+			if err := c.ShouldBindJSON(&req); err != nil {
+				c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+				return
+			}
+			userID := c.Param("id")
+			user, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+			if user == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+				return
+			}
+
+			var rawJSON string
+			if req.AllowedLibraryIDs != nil && len(*req.AllowedLibraryIDs) > 0 {
+				var cleanIDs []string
+				for _, id := range *req.AllowedLibraryIDs {
+					trimmed := strings.TrimSpace(id)
+					if trimmed != "" {
+						cleanIDs = append(cleanIDs, trimmed)
+					}
+				}
+				if len(cleanIDs) > 0 {
+					data, err := json.Marshal(cleanIDs)
+					if err != nil {
+						c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+						return
+					}
+					rawJSON = string(data)
+				}
+			}
+
+			updates := map[string]any{"allowed_library_ids": rawJSON}
+			if err := svc.Repo.User.UpdateFields(c.Request.Context(), userID, updates); err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+
+			updated, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+			if err != nil || updated == nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to reload user"})
+				return
+			}
+			updated.PopulateComputedFields()
+			c.JSON(http.StatusOK, updated)
 		}
-		updated, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
-		if err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-			return
-		}
-		c.JSON(http.StatusOK, updated)
 	}
-}
 
 func annotateProtectedUsers(ctx context.Context, svc *service.Container, users []model.User) error {
 	firstAdmin, err := svc.Repo.User.FirstAdmin(ctx)

internal/handler/admin_test.go

@@ -3,6 +3,7 @@ package handler
 import (
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 
 	"github.com/gin-gonic/gin"
@@ -43,7 +44,92 @@ func TestDeleteUserRefusesRecentRealtimeSession(t *testing.T) {
 	if w.Code != http.StatusConflict {
 		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
 	}
-	if found, _ := repos.User.FindByID(t.Context(), viewer.ID); found == nil {
-		t.Fatal("recent realtime user should not be deleted")
+		if found, _ := repos.User.FindByID(t.Context(), viewer.ID); found == nil {
+			t.Fatal("recent realtime user should not be deleted")
+		}
+	}
+
+func TestUpdateUserLibraries(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	user := model.User{Base: model.Base{ID: "u1"}, Username: "alice", PasswordHash: "x", Role: "user", IsActive: true}
+	lib1 := model.Library{Base: model.Base{ID: "lib-1"}, Name: "电影", Type: "movie", Path: "/movie"}
+	lib2 := model.Library{Base: model.Base{ID: "lib-2"}, Name: "剧集", Type: "tv", Path: "/tv"}
+	lib3 := model.Library{Base: model.Base{ID: "lib-3"}, Name: "动漫", Type: "anime", Path: "/anime"}
+	if err := repos.DB.Create(&user).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.DB.Create(&[]model.Library{lib1, lib2, lib3}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	svc := &service.Container{Repo: repos}
+	router := gin.New()
+	router.PATCH("/admin/users/:id/libraries", updateUserLibrariesHandler(svc))
+
+	// 1. 设置限制为 lib-1 和 lib-2
+	body := `{"allowed_library_ids":["lib-1","lib-2"]}`
+	req := httptest.NewRequest(http.MethodPatch, "/admin/users/u1/libraries", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body = %s", w.Code, w.Body.String())
+	}
+
+	found, err := repos.User.FindByID(t.Context(), "u1")
+	if err != nil || found == nil {
+		t.Fatal("user not found")
+	}
+	allowed := found.DecodeAllowedLibraryIDs()
+	if len(allowed) != 2 || allowed[0] != "lib-1" || allowed[1] != "lib-2" {
+		t.Fatalf("expected [lib-1, lib-2], got %v", allowed)
+	}
+
+	// 验证可见性
+	vis := service.UserDefaultMediaVisibility(t.Context(), repos, "u1")
+	if len(vis.AllowedLibraryIDs) != 2 {
+		t.Fatalf("expected 2 allowed libraries, got %v", vis.AllowedLibraryIDs)
+	}
+	if !service.LibraryVisibleForUser(t.Context(), repos, lib1, vis) {
+		t.Fatal("lib1 should be visible")
+	}
+	if !service.LibraryVisibleForUser(t.Context(), repos, lib2, vis) {
+		t.Fatal("lib2 should be visible")
+	}
+	if service.LibraryVisibleForUser(t.Context(), repos, lib3, vis) {
+		t.Fatal("lib3 should not be visible")
+	}
+
+	// 2. 清空限制，恢复全部可见
+	bodyEmpty := `{"allowed_library_ids":[]}`
+	reqEmpty := httptest.NewRequest(http.MethodPatch, "/admin/users/u1/libraries", strings.NewReader(bodyEmpty))
+	reqEmpty.Header.Set("Content-Type", "application/json")
+	wEmpty := httptest.NewRecorder()
+	router.ServeHTTP(wEmpty, reqEmpty)
+
+	if wEmpty.Code != http.StatusOK {
+		t.Fatalf("status = %d body = %s", wEmpty.Code, wEmpty.Body.String())
+	}
+
+	foundReset, _ := repos.User.FindByID(t.Context(), "u1")
+	if len(foundReset.DecodeAllowedLibraryIDs()) != 0 {
+		t.Fatalf("expected nil or empty, got %v", foundReset.DecodeAllowedLibraryIDs())
+	}
+
+	visReset := service.UserDefaultMediaVisibility(t.Context(), repos, "u1")
+	if len(visReset.AllowedLibraryIDs) != 0 {
+		t.Fatalf("expected no library restrictions, got %v", visReset.AllowedLibraryIDs)
+	}
+	if !service.LibraryVisibleForUser(t.Context(), repos, lib3, visReset) {
+		t.Fatal("lib3 should now be visible")
 	}
 }

internal/handler/auth.go

@@ -89,6 +89,7 @@ func meHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 			return
 		}
+		u.PopulateComputedFields()
 		c.JSON(http.StatusOK, u)
 	}
 }

internal/handler/routes_admin.go

@@ -22,6 +22,10 @@ func registerAdminRoutes(api *gin.RouterGroup, cfg *config.Config, svc *service.
 	registerAdminStrmRoutes(admin, svc)
 	registerAdminScraperRoutes(admin, svc)
 	registerAdminDatabaseRoutes(admin, svc)
+
+	// FFmpeg/FFprobe 工具：状态查询 + 一键下载安装（自动匹配当前平台）。
+	admin.GET("/tools/ffmpeg/status", ffToolsStatusHandler(svc))
+	admin.POST("/tools/ffmpeg/install", ffToolsInstallHandler(svc))
 }
 
 func registerAdminScraperRoutes(admin *gin.RouterGroup, svc *service.Container) {
@@ -92,6 +96,7 @@ func registerAdminUserRoutes(admin *gin.RouterGroup, svc *service.Container) {
 	admin.PATCH("/users/:id/password", resetUserPasswordHandler(svc))
 	admin.PATCH("/users/:id/status", updateUserStatusHandler(svc))
 	admin.PATCH("/users/:id/role", adminUpdateRoleHandler(svc))
+	admin.PATCH("/users/:id/libraries", updateUserLibrariesHandler(svc))
 	admin.DELETE("/users/:id", deleteUserHandler(svc))
 	admin.GET("/settings", listSettingsHandler(svc))
 	admin.PUT("/settings", updateSettingHandler(svc))

internal/handler/routes_authenticated_core.go

@@ -39,6 +39,7 @@ func registerAuthedLibraryRoutes(authed *gin.RouterGroup, svc *service.Container
 
 func registerAuthedMediaRoutes(authed *gin.RouterGroup, svc *service.Container) {
 	authed.GET("/media/:id", getMediaHandler(svc))
+	authed.GET("/media/:id/episodes", listMediaEpisodesHandler(svc))
 	authed.GET("/media", searchMediaHandler(svc))
 	authed.PATCH("/media/:id/metadata", middleware.AdminRequired(), updateMediaMetadataHandler(svc))
 	authed.POST("/media/:id/scrape", middleware.AdminRequired(), scrapeOneHandler(svc))

internal/handler/series.go

@@ -128,3 +128,19 @@ func listLibrarySeriesEpisodesHandler(svc *service.Container) gin.HandlerFunc {
 		c.JSON(http.StatusOK, gin.H{"items": items, "total": len(items)})
 	}
 }
+
+func listMediaEpisodesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		id := c.Param("id")
+		if id == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "id is required"})
+			return
+		}
+		items, err := svc.Media.ListMediaEpisodes(c.Request.Context(), id, mediaVisibilityForRequest(c, svc))
+		if err != nil {
+			writeInternalOrCanceled(c, err)
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"items": items, "total": len(items)})
+	}
+}

internal/handler/subtitles.go

@@ -31,7 +31,7 @@ func serveSubtitleHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		c.Header("Content-Type", "text/vtt; charset=utf-8")
-		c.Header("Cache-Control", "public, max-age=3600")
+		c.Header("Cache-Control", "no-cache, no-store, must-revalidate")
 		if err := svc.Subtitle.Serve(c.Request.Context(), c.Param("id"), path, c.Writer); err != nil {
 			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
 			return

internal/handler/system_handler.go

@@ -1,144 +0,0 @@
-// Package handler — system tools detection.
-package handler
-
-import (
-	"net/http"
-	"os/exec"
-	"strings"
-
-	"github.com/gin-gonic/gin"
-	"go.uber.org/zap"
-
-	"github.com/ShukeBta/MMTL/internal/config"
-	"github.com/ShukeBta/MMTL/internal/service"
-)
-
-// SystemHandler handles system-related endpoints.
-type SystemHandler struct {
-	cfg *config.Config
-	log *zap.Logger
-	svc *service.Container
-}
-
-// NewSystemHandler is the constructor.
-func NewSystemHandler(cfg *config.Config, log *zap.Logger, svc *service.Container) *SystemHandler {
-	return &SystemHandler{cfg: cfg, log: log, svc: svc}
-}
-
-// ToolStatus represents the detection status of a system tool.
-type ToolStatus struct {
-	Name        string `json:"name"`
-	DisplayName string `json:"display_name"`
-	ConfigKey   string `json:"config_key"`
-	Path        string `json:"path,omitempty"`
-	Detected    bool   `json:"detected"`
-	Version     string `json:"version,omitempty"`
-}
-
-// GetToolsStatus returns the status of system tools.
-func (h *SystemHandler) GetToolsStatus(c *gin.Context) {
-	tools := []ToolStatus{
-		{Name: "ffprobe", DisplayName: "FFprobe", ConfigKey: "app.ffprobe_path"},
-		{Name: "ffmpeg", DisplayName: "FFmpeg", ConfigKey: "app.ffmpeg_path"},
-	}
-
-	for i := range tools {
-		// Check configured path first
-		var configuredPath string
-		switch tools[i].ConfigKey {
-		case "app.ffprobe_path":
-			configuredPath = h.cfg.App.FFprobePath
-			if configuredPath == "" {
-				configuredPath = "ffprobe"
-			}
-		case "app.ffmpeg_path":
-			configuredPath = h.cfg.App.FFmpegPath
-			if configuredPath == "" {
-				configuredPath = "ffmpeg"
-			}
-		}
-
-		// Try to find the tool
-		path, err := exec.LookPath(configuredPath)
-		if err == nil {
-			tools[i].Detected = true
-			tools[i].Path = path
-			// Try to get version
-			tools[i].Version = getToolVersion(path)
-		}
-	}
-
-	c.JSON(http.StatusOK, gin.H{
-		"tools": tools,
-	})
-}
-
-// getToolVersion attempts to get the version of a tool.
-func getToolVersion(path string) string {
-	out, err := exec.Command(path, "-version").Output()
-	if err != nil {
-		return ""
-	}
-
-	// Extract first line as version info
-	lines := strings.Split(string(out), "\n")
-	if len(lines) > 0 {
-		return strings.TrimSpace(lines[0])
-	}
-	return ""
-}
-
-// InstallTools attempts to auto-install system tools (ffmpeg/ffprobe)
-func (h *SystemHandler) InstallTools(c *gin.Context) {
-	h.log.Info("Received tools auto-install request")
-
-	// Call service layer to auto-install
-	ffprobePath, ffmpegPath := service.AutoInstallFFmpeg(h.log, h.cfg)
-
-	result := gin.H{
-		"installed": ffprobePath != "" || ffmpegPath != "",
-	}
-
-	if ffprobePath != "" {
-		result["ffprobe_path"] = ffprobePath
-		result["ffprobe_installed"] = true
-	}
-	if ffmpegPath != "" {
-		result["ffmpeg_path"] = ffmpegPath
-		result["ffmpeg_installed"] = true
-	}
-
-	// Re-detect tool status
-	tools := []ToolStatus{
-		{Name: "ffprobe", DisplayName: "FFprobe", ConfigKey: "app.ffprobe_path"},
-		{Name: "ffmpeg", DisplayName: "FFmpeg", ConfigKey: "app.ffmpeg_path"},
-	}
-
-	for i := range tools {
-		var configuredPath string
-		switch tools[i].ConfigKey {
-		case "app.ffprobe_path":
-			configuredPath = h.cfg.App.FFprobePath
-			if configuredPath == "" {
-				configuredPath = "ffprobe"
-			}
-		case "app.ffmpeg_path":
-			configuredPath = h.cfg.App.FFmpegPath
-			if configuredPath == "" {
-				configuredPath = "ffmpeg"
-			}
-		}
-
-		path, err := exec.LookPath(configuredPath)
-		if err == nil {
-			tools[i].Detected = true
-			tools[i].Path = path
-			tools[i].Version = getToolVersion(path)
-		}
-	}
-
-	result["tools"] = tools
-
-	h.log.Info("Tool installation completed", zap.Any("result", result))
-	c.JSON(http.StatusOK, result)
-}

internal/handler/tools_ffmpeg.go

@@ -0,0 +1,38 @@
+// Package handler — FFmpeg/FFprobe 工具安装端点。
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/ShukeBta/MMTL/internal/service"
+)
+
+// ffToolsStatusHandler 返回 ffmpeg/ffprobe 当前安装状态
+// （GET /api/admin/tools/ffmpeg/status）。
+func ffToolsStatusHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.FFTools == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "FFmpeg 工具服务不可用"})
+			return
+		}
+		c.JSON(http.StatusOK, svc.FFTools.Status(c.Request.Context()))
+	}
+}
+
+// ffToolsInstallHandler 触发后台下载安装（POST /api/admin/tools/ffmpeg/install）。
+// 自动匹配当前运行环境（OS+架构），安装到 data/tools/ffmpeg/ 并把路径写入设置。
+func ffToolsInstallHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.FFTools == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "FFmpeg 工具服务不可用"})
+			return
+		}
+		if err := svc.FFTools.StartInstall(c.Request.Context()); err != nil {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, svc.FFTools.Status(c.Request.Context()))
+	}
+}

internal/handler/visibility.go

@@ -32,7 +32,14 @@ func mediaVisibilityForRequest(c *gin.Context, svc *service.Container) service.M
 		return visibility
 	}
 	visibility.IncludeNSFW = adultEnabled && profile.AllowAdult && !userHidesAdult
-	visibility.AllowedLibraryIDs = profileAllowedLibraryIDs(*profile)
+	profileAllowed := profileAllowedLibraryIDs(*profile)
+	if len(profileAllowed) > 0 {
+		if len(visibility.AllowedLibraryIDs) > 0 {
+			visibility.AllowedLibraryIDs = service.IntersectStrings(visibility.AllowedLibraryIDs, profileAllowed)
+		} else {
+			visibility.AllowedLibraryIDs = profileAllowed
+		}
+	}
 	if !visibility.IncludeNSFW {
 		visibility.HiddenLibraryIDs = service.AdultLibraryIDs(c.Request.Context(), svc.Repo)
 	} else {

internal/model/user.go

@@ -1,6 +1,10 @@
 package model
 
-import "time"
+import (
+	"encoding/json"
+	"strings"
+	"time"
+)
 
 // User 是本地账户。第一个注册的管理员（或种子管理员）获得 "admin" 角色；
 // 其他所有用户默认为 "user"。
@@ -17,6 +21,10 @@ type User struct {
 	ForcePasswordReset bool       `gorm:"default:false" json:"force_password_reset"`
 	IsActive           bool       `gorm:"default:true" json:"is_active"`
 	LastLoginAt        *time.Time `json:"last_login_at,omitempty"`
+	// AllowedLibraryIDs 存储管理员为该用户指定的受限可访问媒体库 ID 列表（JSON 字符串）。
+	// 为空时代表不限制（全库可访问）。
+	AllowedLibraryIDs   string     `gorm:"type:text" json:"-"`
+	AllowedLibraryList []string   `gorm:"-" json:"allowed_library_ids,omitempty"`
 	// ExpiredAt is the account expiry time. Nil means the account never
 	// expires. When set and in the past, the account is treated as expired
 	// (login blocked) until an admin or a redemption code renews it.
@@ -31,3 +39,30 @@ type User struct {
 	RealtimeOnline      bool       `gorm:"-" json:"realtime_online,omitempty"`
 	RealtimeDeviceCount int        `gorm:"-" json:"realtime_device_count,omitempty"`
 }
+
+// DecodeAllowedLibraryIDs 解析 AllowedLibraryIDs 字段。
+func (u *User) DecodeAllowedLibraryIDs() []string {
+	if u == nil || strings.TrimSpace(u.AllowedLibraryIDs) == "" {
+		return nil
+	}
+	var ids []string
+	if err := json.Unmarshal([]byte(u.AllowedLibraryIDs), &ids); err != nil {
+		return nil
+	}
+	var out []string
+	for _, id := range ids {
+		trimmed := strings.TrimSpace(id)
+		if trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+// PopulateComputedFields 填充非 DB 虚拟计算字段（如 AllowedLibraryList）。
+func (u *User) PopulateComputedFields() {
+	if u == nil {
+		return
+	}
+	u.AllowedLibraryList = u.DecodeAllowedLibraryIDs()
+}

internal/service/emby_media_sources.go

@@ -199,7 +199,9 @@ func (e *EmbyService) appendSubtitleStreams(ctx context.Context, streams []map[s
 	if e == nil || e.subtitle == nil || m == nil {
 		return streams
 	}
-	tracks, err := e.subtitle.Discover(ctx, m.ID)
+	// Emby 字幕只列表外挂字幕文件：云盘/strm 媒体的容器内嵌字幕不做服务端
+	// 提取，客户端直连播放直链时自行解析。
+	tracks, err := e.subtitle.DiscoverExternalOnly(ctx, m.ID)
 	if err != nil || len(tracks) == 0 {
 		return streams
 	}

internal/service/emby_playback.go

@@ -32,6 +32,9 @@ func (e *EmbyService) PlaybackInfo(ctx context.Context, mediaID, userID string)
 // so the DeliveryUrl advertised in MediaStreams lines up exactly with the
 // served track: subtitles start at 1 when no audio stream is present, otherwise
 // at 2 (after Video 0 + Audio 1).
+//
+// 只服务外挂字幕文件（DiscoverExternalOnly）：云盘/strm 媒体的容器内嵌字幕
+// 不做服务端提取，客户端直连播放直链时自行解析。
 func (e *EmbyService) ServeSubtitleStream(ctx context.Context, w io.Writer, mediaID, indexStr string, userID string) error {
 	if e == nil || e.subtitle == nil {
 		return ErrSubtitleUnavailable
@@ -44,7 +47,7 @@ func (e *EmbyService) ServeSubtitleStream(ctx context.Context, w io.Writer, medi
 	if err != nil || index < 1 {
 		return ErrSubtitleNotFound
 	}
-	tracks, err := e.subtitle.Discover(ctx, m.ID)
+	tracks, err := e.subtitle.DiscoverExternalOnly(ctx, m.ID)
 	if err != nil || len(tracks) == 0 {
 		return ErrSubtitleNotFound
 	}
@@ -74,7 +77,7 @@ func (e *EmbyService) SubtitleStreamCodec(ctx context.Context, mediaID, indexStr
 	if err != nil || index < 1 {
 		return ""
 	}
-	tracks, err := e.subtitle.Discover(ctx, m.ID)
+	tracks, err := e.subtitle.DiscoverExternalOnly(ctx, m.ID)
 	if err != nil || len(tracks) == 0 {
 		return ""
 	}

internal/service/ffmpeg_auto_install.go

@@ -1,196 +1,358 @@
 package service
 
 import (
+	"archive/tar"
 	"context"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"time"
 
+	"github.com/ulikunitz/xz"
 	"go.uber.org/zap"
 
 	"github.com/ShukeBta/MMTL/internal/config"
 )
 
-// AutoInstallFFmpeg is only called by the admin tool-install endpoint. The
-// server must not auto-download or keep ffmpeg/ffprobe running during startup.
-func AutoInstallFFmpeg(log *zap.Logger, cfg *config.Config) (ffprobePath, ffmpegPath string) {
-	// 1. 优先使用配置 / PATH / 本机常见软件目录中的现有工具。
-	if path, err := resolveLocalExecutable(cfg.App.FFprobePath, "ffprobe"); err == nil {
-		ffprobePath = path
-		cfg.App.FFprobePath = path
-		log.Info("found local ffprobe", zap.String("path", path))
-	}
-	if path, err := resolveLocalExecutable(cfg.App.FFmpegPath, "ffmpeg"); err == nil {
-		ffmpegPath = path
-		cfg.App.FFmpegPath = path
-		log.Info("found local ffmpeg", zap.String("path", path))
-	}
-	if ffprobePath != "" || ffmpegPath != "" {
-		return ffprobePath, ffmpegPath
-	}
+// ffmpegDownloadTarget 描述某个平台对应的官方构建下载源。
+type ffmpegDownloadTarget struct {
+	Label    string   // 展示名，如 "Windows x86_64"
+	Kind     string   // 压缩包类型：zip / tar.xz
+	Archives []string // 依次尝试的下载地址（主源 + 备用源）
+}
 
-	// 2. 检查默认安装位置。
-	defaultDir := getDefaultInstallDir()
-	ffprobeDefault := filepath.Join(defaultDir, "bin", "ffprobe.exe")
-	ffmpegDefault := filepath.Join(defaultDir, "bin", "ffmpeg.exe")
-
-	if _, err := os.Stat(ffprobeDefault); err == nil {
-		log.Info("在默认位置找到 ffprobe", zap.String("path", ffprobeDefault))
-		return ffprobeDefault, ffmpegDefault
-	}
-
-	// 3. 尝试自动安装。
-	log.Warn("未找到 ffmpeg/ffprobe，尝试自动安装...")
-	installed, err := tryAutoInstall(log, defaultDir)
-	if err != nil {
-		log.Error("自动安装失败，请手动安装 ffmpeg", zap.Error(err))
-		return "", ""
-	}
-
-	if installed {
-		if _, err := os.Stat(ffprobeDefault); err == nil {
-			log.Info("自动安装成功", zap.String("path", ffprobeDefault))
-			// 更新配置
-			updateConfigPaths(cfg, ffprobeDefault, ffmpegDefault)
-			return ffprobeDefault, ffmpegDefault
+// ffmpegTargetForPlatform 按当前运行环境（OS+架构）选择下载源。
+func ffmpegTargetForPlatform() (*ffmpegDownloadTarget, error) {
+	switch runtime.GOOS {
+	case "windows":
+		switch runtime.GOARCH {
+		case "amd64":
+			return &ffmpegDownloadTarget{
+				Label: "Windows x86_64",
+				Kind:  "zip",
+				Archives: []string{
+					"https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip",
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip",
+				},
+			}, nil
+		case "386":
+			return &ffmpegDownloadTarget{
+				Label: "Windows x86",
+				Kind:  "zip",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win32-gpl.zip",
+				},
+			}, nil
+		}
+	case "linux":
+		switch runtime.GOARCH {
+		case "amd64":
+			return &ffmpegDownloadTarget{
+				Label: "Linux x86_64",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl.tar.xz",
+					"https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz",
+				},
+			}, nil
+		case "arm64":
+			return &ffmpegDownloadTarget{
+				Label: "Linux ARM64",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxarm64-gpl.tar.xz",
+					"https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-arm64-static.tar.xz",
+				},
+			}, nil
+		case "arm":
+			return &ffmpegDownloadTarget{
+				Label: "Linux ARM (32 位)",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxarmhf-gpl.tar.xz",
+				},
+			}, nil
+		case "loong64":
+			return &ffmpegDownloadTarget{
+				Label: "Linux LoongArch64",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxloongarch64-gpl.tar.xz",
+				},
+			}, nil
+		}
+	case "darwin":
+		switch runtime.GOARCH {
+		case "amd64":
+			return &ffmpegDownloadTarget{
+				Label: "macOS x86_64",
+				Kind:  "zip",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-osx64-gpl.zip",
+				},
+			}, nil
+		case "arm64":
+			return &ffmpegDownloadTarget{
+				Label: "macOS Apple Silicon",
+				Kind:  "zip",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-osxarm64-gpl.zip",
+				},
+			}, nil
 		}
 	}
-
-	return "", ""
+	return nil, fmt.Errorf("暂不支持自动下载的平台 %s/%s，请手动填写 ffmpeg/ffprobe 路径", runtime.GOOS, runtime.GOARCH)
 }
 
-// getDefaultInstallDir 返回默认安装目录
-func getDefaultInstallDir() string {
-	exePath, err := os.Executable()
+// installFFmpegTools 按平台下载并安装 ffmpeg/ffprobe 到 data/tools/ffmpeg/，
+// 返回两个可执行文件的绝对路径。progress 用于回传阶段消息（UI 展示）。
+func installFFmpegTools(ctx context.Context, log *zap.Logger, cfg *config.Config, progress func(string)) (ffmpegPath, ffprobePath string, err error) {
+	target, err := ffmpegTargetForPlatform()
 	if err != nil {
-		return "./tools/ffmpeg"
+		return "", "", err
 	}
-	exeDir := filepath.Dir(exePath)
-	return filepath.Join(exeDir, "tools", "ffmpeg")
-}
-
-// tryAutoInstall 尝试自动下载并安装 ffmpeg
-func tryAutoInstall(log *zap.Logger, installDir string) (bool, error) {
-	if runtime.GOOS == "windows" {
-		return downloadFFmpegWindows(log, installDir)
-	}
-
-	return false, fmt.Errorf("不支持的操作系统: %s", runtime.GOOS)
-}
-
-// downloadFFmpegWindows 下载 Windows 版本的 ffmpeg
-func downloadFFmpegWindows(log *zap.Logger, installDir string) (bool, error) {
-	log.Info("开始下载 ffmpeg...")
-
-	// 创建安装目录
+	installDir := filepath.Join(cfg.App.DataDir, "tools", "ffmpeg")
 	if err := os.MkdirAll(installDir, 0o750); err != nil {
-		return false, fmt.Errorf("创建安装目录失败: %w", err)
+		return "", "", fmt.Errorf("创建安装目录失败: %w", err)
 	}
 
 	tempDir, err := os.MkdirTemp("", "mmtl-ffmpeg-*")
 	if err != nil {
-		return false, fmt.Errorf("创建临时目录失败: %w", err)
+		return "", "", fmt.Errorf("创建临时目录失败: %w", err)
 	}
 	defer os.RemoveAll(tempDir)
 
-	// 下载 URL (使用 gyani.org 的静态构建)
-	arch := "win64"
-	if !is64Bit() {
-		arch = "win32"
+	progress("下载 " + target.Label + " 版本…")
+	archivePath := filepath.Join(tempDir, "ffmpeg-archive."+target.Kind)
+	if err := downloadFFmpegArchive(ctx, log, target.Archives, archivePath); err != nil {
+		return "", "", err
 	}
 
-	// 先尝试从 gyan.dev 下载（更可靠）
-	downloadURL := fmt.Sprintf("https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip")
+	progress("解压…")
+	extractDir := filepath.Join(tempDir, "extract")
+	if err := extractFFmpegArchive(target.Kind, archivePath, extractDir); err != nil {
+		return "", "", fmt.Errorf("解压失败: %w", err)
+	}
 
-	log.Info("下载 ffmpeg", zap.String("url", downloadURL))
+	exeSuffix := ""
+	if runtime.GOOS == "windows" {
+		exeSuffix = ".exe"
+	}
+	srcFFmpeg, srcFFprobe, err := locateFFmpegBinaries(extractDir, exeSuffix)
+	if err != nil {
+		return "", "", err
+	}
 
-	// 使用 Go 下载
-	zipPath := filepath.Join(tempDir, "ffmpeg.zip")
-	if err := downloadFile(log, downloadURL, zipPath); err != nil {
-		// 尝试备用 URL
-		backupURL := fmt.Sprintf("https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-%s-gpl.zip", arch)
-		log.Info("尝试备用下载地址", zap.String("url", backupURL))
-		if err2 := downloadFile(log, backupURL, zipPath); err2 != nil {
-			return false, fmt.Errorf("下载失败: %v, %v", err, err2)
+	progress("安装到 data 目录…")
+	ffmpegPath = filepath.Join(installDir, "ffmpeg"+exeSuffix)
+	ffprobePath = filepath.Join(installDir, "ffprobe"+exeSuffix)
+	if err := copyFileMode(srcFFmpeg, ffmpegPath); err != nil {
+		return "", "", fmt.Errorf("复制 ffmpeg 失败: %w", err)
+	}
+	if err := copyFileMode(srcFFprobe, ffprobePath); err != nil {
+		_ = os.Remove(ffmpegPath)
+		return "", "", fmt.Errorf("复制 ffprobe 失败: %w", err)
+	}
+
+	// 验证两个工具都能运行（失败则回滚，避免留下坏文件）。
+	for _, bin := range []string{ffmpegPath, ffprobePath} {
+		cmd := exec.CommandContext(ctx, bin, "-version") // #nosec G204 -- bin 是安装目录中刚写入的固定文件名。
+		if out, verr := cmd.Output(); verr != nil {
+			_ = os.Remove(ffmpegPath)
+			_ = os.Remove(ffprobePath)
+			return "", "", fmt.Errorf("安装后 %s 无法运行：%v", filepath.Base(bin), verr)
+		} else if log != nil {
+			log.Info("ffmpeg 工具安装验证通过", zap.String("bin", filepath.Base(bin)),
+				zap.String("version", strings.TrimSpace(strings.SplitN(string(out), "\n", 2)[0])))
 		}
 	}
-
-	// 解压
-	log.Info("解压 ffmpeg...")
-	extractDir := filepath.Join(tempDir, "extract")
-	if err := unzip(log, zipPath, extractDir); err != nil {
-		return false, fmt.Errorf("解压失败: %w", err)
-	}
-
-	packageRoot, err := findFFmpegPackageRoot(extractDir)
-	if err != nil {
-		return false, err
-	}
-	if err := copyDirContents(packageRoot, installDir); err != nil {
-		return false, fmt.Errorf("复制 ffmpeg 文件失败: %w", err)
-	}
-
-	ffmpegBin := filepath.Join(installDir, "bin", "ffmpeg.exe")
-	ffprobeBin := filepath.Join(installDir, "bin", "ffprobe.exe")
-	if _, err := os.Stat(ffmpegBin); err != nil {
-		return false, fmt.Errorf("安装后未找到 ffmpeg: %w", err)
-	}
-	if _, err := os.Stat(ffprobeBin); err != nil {
-		return false, fmt.Errorf("安装后未找到 ffprobe: %w", err)
-	}
-
-	log.Info("ffmpeg 安装完成", zap.String("dir", installDir))
-	return true, nil
+	progress("安装完成")
+	return ffmpegPath, ffprobePath, nil
 }
 
-// downloadFile 下载文件
-func downloadFile(log *zap.Logger, url, filepath string) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
-	defer cancel()
+// downloadFFmpegArchive 按顺序尝试下载源，全部失败才返回错误。
+func downloadFFmpegArchive(ctx context.Context, log *zap.Logger, urls []string, dest string) error {
+	var lastErr error
+	for i, u := range urls {
+		if i > 0 && log != nil {
+			log.Warn("ffmpeg 主下载源不可用，切换备用源", zap.String("url", u))
+		}
+		if err := downloadFFmpegFile(ctx, log, u, dest); err != nil {
+			lastErr = err
+			if log != nil {
+				log.Warn("ffmpeg 下载失败", zap.String("url", u), zap.Error(err))
+			}
+			continue
+		}
+		return nil
+	}
+	return fmt.Errorf("所有下载源均失败：%v", lastErr)
+}
 
-	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+// downloadFFmpegFile 下载单个归档文件（最多 10 分钟，限制大小上限）。
+func downloadFFmpegFile(ctx context.Context, log *zap.Logger, url, dest string) error {
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return err
 	}
-
+	req.Header.Set("User-Agent", "MMTL/ffmpeg-installer ("+runtime.GOOS+"/"+runtime.GOARCH+")")
 	resp, err := http.DefaultClient.Do(req)
 	if err != nil {
 		return err
 	}
 	defer resp.Body.Close()
-
 	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("下载失败，HTTP 状态码: %d", resp.StatusCode)
+		return fmt.Errorf("下载失败，HTTP 状态码 %d", resp.StatusCode)
 	}
-
-	out, err := os.Create(filepath) // #nosec G304 -- filepath is generated by the installer under its temporary download directory.
+	out, err := os.Create(dest) // #nosec G304 -- dest 是安装器在临时目录下生成的文件。
 	if err != nil {
 		return err
 	}
 	defer out.Close()
-
-	_, err = io.Copy(out, resp.Body)
-	return err
+	n, err := io.Copy(out, io.LimitReader(resp.Body, 500<<20+1)) // 归档上限 500MB
+	if err != nil {
+		return err
+	}
+	if n > 500<<20 {
+		return fmt.Errorf("归档文件过大（>500MB）: %s", url)
+	}
+	if log != nil {
+		log.Info("ffmpeg 归档下载完成", zap.String("url", url), zap.Int64("bytes", n))
+	}
+	return nil
 }
 
-// updateConfigPaths 更新配置文件中的路径
-func updateConfigPaths(cfg *config.Config, ffprobePath, ffmpegPath string) {
-	cfg.App.FFprobePath = ffprobePath
-	cfg.App.FFmpegPath = ffmpegPath
-
-	// 保存到配置文件
-	// 这里需要调用 config 包的保存函数
-	log := zap.L().Named("config")
-	log.Info("已更新 ffmpeg 路径配置",
-		zap.String("ffprobe", ffprobePath),
-		zap.String("ffmpeg", ffmpegPath))
+// extractFFmpegArchive 按类型解压 zip 或 tar.xz。
+func extractFFmpegArchive(kind, archivePath, destDir string) error {
+	switch kind {
+	case "zip":
+		return unzip(nil, archivePath, destDir)
+	case "tar.xz":
+		return untarXZ(archivePath, destDir)
+	default:
+		return fmt.Errorf("不支持的归档类型: %s", kind)
+	}
 }
 
-// is64Bit 检查是否为 64 位系统
-func is64Bit() bool {
-	return true // 简化处理，假设为 64 位
+// untarXZ 解压 .tar.xz 归档（GNU tar + xz 流式解压，纯 Go 无外部依赖），
+// 路径安全校验与 ZIP 解压一致。
+func untarXZ(archivePath, destDir string) error {
+	if err := os.MkdirAll(destDir, 0o750); err != nil {
+		return err
+	}
+	destRoot, err := filepath.Abs(destDir)
+	if err != nil {
+		return err
+	}
+	f, err := os.Open(archivePath) // #nosec G304 -- archivePath 是安装器在临时目录下生成的文件。
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	xzReader, err := xz.NewReader(f)
+	if err != nil {
+		return err
+	}
+	tr := tar.NewReader(xzReader)
+	var totalWritten int64
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		target, err := safeZipTarget(destRoot, hdr.Name) // 与 ZIP 相同的路径穿越防护
+		if err != nil {
+			return err
+		}
+		switch hdr.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(target, 0o750); err != nil {
+				return err
+			}
+		case tar.TypeReg, tar.TypeRegA:
+			if err := os.MkdirAll(filepath.Dir(target), 0o750); err != nil {
+				return err
+			}
+			dst, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, os.FileMode(hdr.Mode).Perm())
+			if err != nil {
+				return err
+			}
+			written, copyErr := io.Copy(dst, io.LimitReader(tr, maxFFmpegZipEntryBytes+1))
+			totalWritten += written
+			closeErr := dst.Close()
+			if copyErr != nil {
+				return copyErr
+			}
+			if closeErr != nil {
+				return closeErr
+			}
+			if written > maxFFmpegZipEntryBytes || totalWritten > maxFFmpegZipTotalBytes {
+				return fmt.Errorf("tar 内容过大: %s", hdr.Name)
+			}
+		default:
+			// 符号链接/设备等一律跳过（静态构建不会依赖它们）。
+			continue
+		}
+	}
+}
+
+// locateFFmpegBinaries 在解压目录中查找 ffmpeg/ffprobe 可执行文件（兼容
+// 不同构建包的目录布局：gyan 的 bin/、BtbN/johnvansickle 的根目录等）。
+func locateFFmpegBinaries(root, exeSuffix string) (ffmpeg, ffprobe string, err error) {
+	wantFFmpeg := "ffmpeg" + strings.ToLower(exeSuffix)
+	wantFFprobe := "ffprobe" + strings.ToLower(exeSuffix)
+	err = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		switch strings.ToLower(d.Name()) {
+		case wantFFmpeg:
+			if ffmpeg == "" {
+				ffmpeg = path
+			}
+		case wantFFprobe:
+			if ffprobe == "" {
+				ffprobe = path
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return "", "", fmt.Errorf("扫描解压目录失败: %w", err)
+	}
+	if ffmpeg == "" || ffprobe == "" {
+		return "", "", fmt.Errorf("解压内容中未找到 ffmpeg/ffprobe 可执行文件")
+	}
+	return ffmpeg, ffprobe, nil
+}
+
+// copyFileMode 复制文件并赋予可执行权限。
+func copyFileMode(src, dst string) error {
+	in, err := os.Open(src) // #nosec G304 -- src 来自解压目录遍历结果。
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+	out, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o755)
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		_ = out.Close()
+		return err
+	}
+	return out.Close()
 }

internal/service/ffmpeg_install_archive.go

@@ -41,7 +41,9 @@ func unzip(log *zap.Logger, zipPath, destDir string) error {
 		}
 		info := file.FileInfo()
 		if info.Mode()&os.ModeSymlink != 0 {
-			log.Warn("跳过 ZIP 符号链接", zap.String("name", file.Name))
+			if log != nil {
+				log.Warn("跳过 ZIP 符号链接", zap.String("name", file.Name))
+			}
 			continue
 		}
 		if info.IsDir() {
@@ -110,93 +112,3 @@ func safeZipTarget(destRoot, name string) (string, error) {
 	return targetAbs, nil
 }
 
-func findFFmpegPackageRoot(root string) (string, error) {
-	var ffmpegPath string
-	var ffprobePath string
-
-	err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
-		if err != nil {
-			return err
-		}
-		if d.IsDir() {
-			return nil
-		}
-
-		switch strings.ToLower(d.Name()) {
-		case "ffmpeg.exe":
-			ffmpegPath = path
-		case "ffprobe.exe":
-			ffprobePath = path
-		}
-		return nil
-	})
-	if err != nil {
-		return "", fmt.Errorf("扫描解压目录失败: %w", err)
-	}
-	if ffmpegPath == "" || ffprobePath == "" {
-		return "", fmt.Errorf("解压后未找到 ffmpeg/ffprobe 可执行文件")
-	}
-
-	return filepath.Dir(filepath.Dir(ffmpegPath)), nil
-}
-
-func copyDirContents(srcDir, dstDir string) error {
-	entries, err := os.ReadDir(srcDir)
-	if err != nil {
-		return err
-	}
-
-	for _, entry := range entries {
-		srcPath := filepath.Join(srcDir, entry.Name())
-		dstPath := filepath.Join(dstDir, entry.Name())
-		if err := copyTree(srcPath, dstPath); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func copyTree(srcPath, dstPath string) error {
-	info, err := os.Stat(srcPath)
-	if err != nil {
-		return err
-	}
-
-	if info.IsDir() {
-		if err := os.MkdirAll(dstPath, info.Mode()); err != nil {
-			return err
-		}
-		entries, err := os.ReadDir(srcPath)
-		if err != nil {
-			return err
-		}
-		for _, entry := range entries {
-			if err := copyTree(filepath.Join(srcPath, entry.Name()), filepath.Join(dstPath, entry.Name())); err != nil {
-				return err
-			}
-		}
-		return nil
-	}
-
-	in, err := os.Open(srcPath) // #nosec G304 -- srcPath is produced by walking the validated extracted ffmpeg package tree.
-	if err != nil {
-		return err
-	}
-	defer in.Close()
-
-	if err := os.MkdirAll(filepath.Dir(dstPath), 0o750); err != nil {
-		return err
-	}
-
-	out, err := os.Create(dstPath) // #nosec G304 -- dstPath is generated under the configured ffmpeg install directory.
-	if err != nil {
-		return err
-	}
-	defer out.Close()
-
-	if _, err := io.Copy(out, in); err != nil {
-		return err
-	}
-
-	return out.Close()
-}

internal/service/ffmpeg_status.go

@@ -1,57 +0,0 @@
-package service
-
-import (
-	"bytes"
-	"os"
-	"os/exec"
-	"runtime"
-)
-
-// CheckFFmpegStatus 检查 ffmpeg/ffprobe 状态 (供 API 使用)
-func CheckFFmpegStatus(ffprobePath, ffmpegPath string) map[string]interface{} {
-	status := map[string]interface{}{
-		"ffprobe_installed": false,
-		"ffmpeg_installed":  false,
-		"auto_installable":  runtime.GOOS == "windows",
-	}
-
-	if ffprobePath != "" {
-		if _, err := os.Stat(ffprobePath); err == nil {
-			status["ffprobe_installed"] = true
-			status["ffprobe_path"] = ffprobePath
-
-			// 获取版本
-			cmd := exec.Command(ffprobePath, "-version")
-			out, err := cmd.Output()
-			if err == nil {
-				// 提取版本信息（第一行）
-				lines := bytes.Split(out, []byte("\n"))
-				if len(lines) > 0 {
-					version := string(bytes.TrimSpace(lines[0]))
-					status["ffprobe_version"] = version
-					status["ffprobe_security"] = EvaluateFFmpegSecurity(version)
-				}
-			}
-		}
-	}
-
-	if ffmpegPath != "" {
-		if _, err := os.Stat(ffmpegPath); err == nil {
-			status["ffmpeg_installed"] = true
-			status["ffmpeg_path"] = ffmpegPath
-
-			cmd := exec.Command(ffmpegPath, "-version")
-			out, err := cmd.Output()
-			if err == nil {
-				lines := bytes.Split(out, []byte("\n"))
-				if len(lines) > 0 {
-					version := string(bytes.TrimSpace(lines[0]))
-					status["ffmpeg_version"] = version
-					status["ffmpeg_security"] = EvaluateFFmpegSecurity(version)
-				}
-			}
-		}
-	}
-
-	return status
-}

internal/service/ffmpeg_tools.go

@@ -0,0 +1,211 @@
+// Package service — ffmpeg/ffprobe 自动下载安装。
+//
+// FFmpegToolsService 负责「一键下载」：点击后按当前运行平台（OS+架构）选择
+// 官方构建包（Windows: gyan.dev / BtbN；Linux: BtbN / johnvansickle；
+// macOS: BtbN），下载解压 ffmpeg/ffprobe 到 data 目录（data/tools/ffmpeg/），
+// 并把绝对路径写入设置（ffmpeg.path / ffprobe.path），系统随即使用安装的
+// 工具，无需手动填写路径。
+package service
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+	"github.com/ShukeBta/MMTL/internal/repository"
+)
+
+// FFmpegToolsService 管理 ffmpeg/ffprobe 的自动下载安装状态（单飞：同一时间
+// 只允许一个安装任务）。
+type FFmpegToolsService struct {
+	cfg  *config.Config
+	log  *zap.Logger
+	repo *repository.Container
+
+	mu      sync.Mutex
+	running bool
+	msg     string    // 最近阶段/结果消息
+	errMsg  string    // 最近一次失败原因
+	started time.Time // 最近一次安装开始时间
+	done    time.Time // 最近一次安装结束时间
+}
+
+// NewFFmpegToolsService 构造工具安装服务。
+func NewFFmpegToolsService(cfg *config.Config, log *zap.Logger, repo *repository.Container) *FFmpegToolsService {
+	return &FFmpegToolsService{cfg: cfg, log: log, repo: repo}
+}
+
+// ffmpegInstallDir 返回 data 目录下的安装位置。
+func (s *FFmpegToolsService) ffmpegInstallDir() string {
+	return filepath.Join(s.cfg.App.DataDir, "tools", "ffmpeg")
+}
+
+// installedBinaries 检查安装目录中是否已存在 ffmpeg/ffprobe 可执行文件。
+func (s *FFmpegToolsService) installedBinaries() (ffmpeg, ffprobe string) {
+	exe := ""
+	if runtime.GOOS == "windows" {
+		exe = ".exe"
+	}
+	ffmpeg = filepath.Join(s.ffmpegInstallDir(), "ffmpeg"+exe)
+	ffprobe = filepath.Join(s.ffmpegInstallDir(), "ffprobe"+exe)
+	if _, err := os.Stat(ffmpeg); err != nil {
+		return "", ""
+	}
+	if _, err := os.Stat(ffprobe); err != nil {
+		return "", ""
+	}
+	return ffmpeg, ffprobe
+}
+
+// ffToolVersion 取工具第一行版本信息。
+func ffToolVersion(path string) string {
+	if path == "" {
+		return ""
+	}
+	out, err := exec.Command(path, "-version").Output() // #nosec G204 -- path 来自配置/安装目录中的已知工具。
+	if err != nil {
+		return ""
+	}
+	line := strings.SplitN(strings.TrimSpace(string(out)), "\n", 2)
+	if len(line) == 0 || strings.TrimSpace(line[0]) == "" {
+		return ""
+	}
+	return strings.TrimSpace(line[0])
+}
+
+// ffToolInfo 是单个工具的安装状态（返回给前端展示）。
+type ffToolInfo struct {
+	Installed bool   `json:"installed"`
+	Path      string `json:"path,omitempty"`
+	Version   string `json:"version,omitempty"`
+}
+
+// Status 返回当前安装状态（供 GET /api/admin/tools/ffmpeg/status 使用）。
+func (s *FFmpegToolsService) Status(ctx context.Context) map[string]any {
+	s.mu.Lock()
+	running, msg, errMsg, started, done := s.running, s.msg, s.errMsg, s.started, s.done
+	s.mu.Unlock()
+
+	startedAt, doneAt := "", ""
+	if !started.IsZero() {
+		startedAt = started.Format(time.RFC3339)
+	}
+	if !done.IsZero() {
+		doneAt = done.Format(time.RFC3339)
+	}
+
+	out := map[string]any{
+		"installing":  running,
+		"message":     msg,
+		"error":       errMsg,
+		"started_at":  startedAt,
+		"finished_at": doneAt,
+		"install_dir": s.ffmpegInstallDir(),
+	}
+	target, targetErr := ffmpegTargetForPlatform()
+	if targetErr != nil {
+		out["target"] = map[string]any{"label": targetErr.Error()}
+	} else {
+		out["target"] = map[string]any{
+			"os":    runtime.GOOS,
+			"arch":  runtime.GOARCH,
+			"label": target.Label,
+		}
+	}
+	// 报告「系统当前实际会使用」的工具：优先已生效配置（安装完成会把设置指到
+	// data 目录），其次 PATH / 常见目录。
+	ffmpegPath, ferr := resolveLocalExecutable(s.cfg.App.FFmpegPath, "ffmpeg")
+	ffprobePath, perr := resolveLocalExecutable(s.cfg.App.FFprobePath, "ffprobe")
+	out["ffmpeg"] = ffToolInfo{Installed: ferr == nil, Path: ffmpegPath, Version: ffToolVersion(ffmpegPath)}
+	out["ffprobe"] = ffToolInfo{Installed: perr == nil, Path: ffprobePath, Version: ffToolVersion(ffprobePath)}
+	return out
+}
+
+// StartInstall 启动后台安装（幂等）。正在安装时返回错误；data 目录已有完整
+// 工具时直接应用路径设置并返回（无需重新下载）。
+func (s *FFmpegToolsService) StartInstall(ctx context.Context) error {
+	s.mu.Lock()
+	if s.running {
+		s.mu.Unlock()
+		return errors.New("工具正在安装中，请稍候")
+	}
+	if ffmpeg, ffprobe := s.installedBinaries(); ffmpeg != "" && ffprobe != "" {
+		s.mu.Unlock()
+		s.setMessage("检测到已安装，直接应用配置")
+		if err := s.applyInstalledPaths(ctx, ffmpeg, ffprobe); err != nil {
+			return err
+		}
+		return nil
+	}
+	s.running = true
+	s.errMsg = ""
+	s.started = time.Now()
+	s.mu.Unlock()
+
+	s.setMessage("准备下载…")
+	go s.runInstall()
+	return nil
+}
+
+// runInstall 在后台执行下载、解压、验证与配置落盘。
+func (s *FFmpegToolsService) runInstall() {
+	defer func() {
+		s.mu.Lock()
+		s.running = false
+		s.done = time.Now()
+		s.mu.Unlock()
+	}()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
+	defer cancel()
+
+	ffmpegPath, ffprobePath, err := installFFmpegTools(ctx, s.log, s.cfg, s.setMessage)
+	if err != nil {
+		s.mu.Lock()
+		s.errMsg = err.Error()
+		s.msg = "安装失败"
+		s.mu.Unlock()
+		s.log.Error("ffmpeg 工具安装失败", zap.Error(err))
+		return
+	}
+	if err := s.applyInstalledPaths(ctx, ffmpegPath, ffprobePath); err != nil {
+		s.mu.Lock()
+		s.errMsg = "安装完成，但写入设置失败：" + err.Error()
+		s.msg = "安装完成，设置写入失败"
+		s.mu.Unlock()
+		s.log.Error("写入 ffmpeg 工具路径设置失败", zap.Error(err))
+		return
+	}
+	s.setMessage("安装完成")
+	s.log.Info("ffmpeg 工具安装完成",
+		zap.String("ffmpeg", ffmpegPath), zap.String("ffprobe", ffprobePath))
+}
+
+// applyInstalledPaths 把安装后的路径写入设置表并热应用到运行配置。
+func (s *FFmpegToolsService) applyInstalledPaths(ctx context.Context, ffmpeg, ffprobe string) error {
+	if s.repo != nil && s.repo.Setting != nil {
+		if err := s.repo.Setting.Set(ctx, "ffmpeg.path", ffmpeg); err != nil {
+			return err
+		}
+		if err := s.repo.Setting.Set(ctx, "ffprobe.path", ffprobe); err != nil {
+			return err
+		}
+	}
+	ApplyRuntimeSetting(s.cfg, "ffmpeg.path", ffmpeg)
+	ApplyRuntimeSetting(s.cfg, "ffprobe.path", ffprobe)
+	return nil
+}
+
+func (s *FFmpegToolsService) setMessage(msg string) {
+	s.mu.Lock()
+	s.msg = msg
+	s.mu.Unlock()
+}

internal/service/ffmpeg_tools_test.go

@@ -0,0 +1,81 @@
+package service
+
+import (
+	"context"
+	"runtime"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+)
+
+func TestFFmpegTargetForPlatform(t *testing.T) {
+	target, err := ffmpegTargetForPlatform()
+	switch runtime.GOOS {
+	case "windows", "linux", "darwin":
+		if err != nil {
+			t.Fatalf("supported platform %s/%s should resolve a target: %v", runtime.GOOS, runtime.GOARCH, err)
+		}
+		if target == nil || target.Label == "" || len(target.Archives) == 0 {
+			t.Fatalf("target incomplete: %#v", target)
+		}
+		if target.Kind != "zip" && target.Kind != "tar.xz" {
+			t.Fatalf("unexpected archive kind: %s", target.Kind)
+		}
+		for _, u := range target.Archives {
+			if !strings.HasPrefix(u, "https://") {
+				t.Fatalf("archive url not https: %s", u)
+			}
+		}
+	default:
+		if err == nil {
+			t.Fatalf("unsupported platform %s/%s should fail", runtime.GOOS, runtime.GOARCH)
+		}
+	}
+}
+
+func TestSafeZipTargetRejectsTraversal(t *testing.T) {
+	root := t.TempDir()
+	for _, name := range []string{"../evil", "..\\evil", "/etc/passwd", "a/../../evil"} {
+		if _, err := safeZipTarget(root, name); err == nil {
+			t.Fatalf("expected traversal rejection for %q", name)
+		}
+	}
+	if _, err := safeZipTarget(root, "bin/ffmpeg.exe"); err != nil {
+		t.Fatalf("valid relative path should pass: %v", err)
+	}
+}
+
+func TestFFmpegToolsStatusNoPanic(t *testing.T) {
+	svc := NewFFmpegToolsService(&config.Config{}, zap.NewNop(), nil)
+	st := svc.Status(context.Background())
+	for _, key := range []string{"installing", "message", "error", "install_dir", "target", "ffmpeg", "ffprobe"} {
+		if _, ok := st[key]; !ok {
+			t.Fatalf("status missing key %q: %#v", key, st)
+		}
+	}
+	ffmpeg, ok := st["ffmpeg"].(ffToolInfo)
+	if !ok {
+		t.Fatalf("ffmpeg field not ffToolInfo: %T", st["ffmpeg"])
+	}
+	if ffmpeg.Installed {
+		t.Fatalf("empty config should not report installed ffmpeg: %#v", st)
+	}
+}
+
+func TestStartInstallRejectsConcurrent(t *testing.T) {
+	svc := NewFFmpegToolsService(&config.Config{App: config.AppConfig{DataDir: t.TempDir()}}, zap.NewNop(), nil)
+	// 不真实运行：直接占用 running 标记模拟进行中的安装。
+	svc.mu.Lock()
+	svc.running = true
+	svc.mu.Unlock()
+	if err := svc.StartInstall(context.Background()); err == nil {
+		t.Fatalf("second install while running should be rejected")
+	}
+	svc.mu.Lock()
+	svc.running = false
+	svc.mu.Unlock()
+}
+

internal/service/media_series.go

@@ -2,6 +2,8 @@ package service
 
 import (
 	"context"
+	"errors"
+	"path/filepath"
 	"regexp"
 	"sort"
 	"strings"
@@ -75,6 +77,74 @@ func (s *MediaService) ListLibrarySeriesEpisodes(ctx context.Context, libraryID,
 	return out, nil
 }
 
+func (s *MediaService) ListMediaEpisodes(ctx context.Context, mediaID string, visibility MediaVisibility) ([]model.Media, error) {
+	target, err := s.repo.Media.FindByID(ctx, mediaID)
+	if err != nil {
+		return nil, err
+	}
+	if target == nil {
+		return nil, errors.New("media not found")
+	}
+	if !visibility.Allows(target) {
+		return nil, errors.New("media not found")
+	}
+	if target.LibraryID == "" {
+		return []model.Media{*target}, nil
+	}
+	rows, _, err := s.listAllMediaVisible(ctx, target.LibraryID, visibility)
+	if err != nil {
+		return nil, err
+	}
+	if len(rows) == 0 {
+		return []model.Media{*target}, nil
+	}
+
+	resolver := newMediaSeriesKeyResolver(rows)
+	targetKey := resolver.key(*target)
+
+	out := make([]model.Media, 0)
+	if targetKey != "" {
+		for _, row := range rows {
+			if resolver.key(row) == targetKey {
+				out = append(out, row)
+			}
+		}
+	}
+
+	// 如果没有聚合到多集，尝试同父目录匹配
+	if len(out) <= 1 && target.Path != "" {
+		targetDir := filepath.Dir(strings.ReplaceAll(target.Path, "\\", "/"))
+		dirMatches := make([]model.Media, 0)
+		for _, row := range rows {
+			if row.Path != "" && filepath.Dir(strings.ReplaceAll(row.Path, "\\", "/")) == targetDir {
+				dirMatches = append(dirMatches, row)
+			}
+		}
+		if len(dirMatches) > 1 {
+			out = dirMatches
+		}
+	}
+
+	if len(out) == 0 {
+		out = []model.Media{*target}
+	}
+
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].SeasonNum != out[j].SeasonNum {
+			return out[i].SeasonNum < out[j].SeasonNum
+		}
+		if out[i].EpisodeNum != out[j].EpisodeNum {
+			return out[i].EpisodeNum < out[j].EpisodeNum
+		}
+		if out[i].Path != out[j].Path {
+			return out[i].Path < out[j].Path
+		}
+		return out[i].CreatedAt.Before(out[j].CreatedAt)
+	})
+
+	return out, nil
+}
+
 func (s *MediaService) listAllMediaVisible(ctx context.Context, libraryID string, visibility MediaVisibility) ([]model.Media, int64, error) {
 	const pageSize = 2000
 	var all []model.Media

internal/service/service.go

@@ -62,6 +62,7 @@ type Container struct {
 		Danmaku          *DanmakuService
 		Strm             *StrmService
 		Database         *DatabaseAdminService
+		FFTools          *FFmpegToolsService
 
 		stopCtx    context.Context
 	stopCancel context.CancelFunc

internal/service/service_builder.go

@@ -111,6 +111,8 @@ func (b *serviceContainerBuilder) initContentServices() {
 	b.c.Profile = NewProfileService(b.log, b.repos)
 	b.c.Audit = NewAuditService(b.log, b.repos)
 	b.c.Strm = NewStrmService(b.cfg, b.log, b.repos, b.c.Crypto)
+	// ffmpeg/ffprobe 一键下载安装（data/tools/ffmpeg/）。
+	b.c.FFTools = NewFFmpegToolsService(b.cfg, b.log, b.repos)
 	// 弹幕 hash 识别需要把 strm 指向解析成可拉取的直链/本地路径。
 	b.c.Danmaku.SetStrmResolver(b.c.Strm.ResolvePlay)
 }

internal/service/strm_play.go

@@ -116,6 +116,64 @@ func (s *StrmService) resolveLocalPlay(ctx context.Context, rawPath string) (*St
 	return nil, errors.New("文件不在任何本地同步目录内")
 }
 
+// ResolvePlayTarget 解析媒体行固化的播放目标（STRMURL 或 .strm 文件内容）为
+// 可播放结果，供弹幕 hash、内嵌字幕提取等「先解析直链再读取远端」的场景复用。
+// 支持：
+//   - /api/strm/play/{provider}/video{ext}?acct=..&pickcode=.. （常规格式，含账号）
+//   - /api/cloud/play/{type}?ref=.. （旧格式，无账号 → 取该类型第一个启用账号）
+//   - 绝对 http(s) 链接（直接透传）
+//   - 其余协议（webdav:// 等）返回错误，由调用方决定是否静默跳过
+func (s *StrmService) ResolvePlayTarget(ctx context.Context, raw string) (*StrmPlayResult, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil, errors.New("空播放目标")
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		return nil, fmt.Errorf("解析播放目标失败: %w", err)
+	}
+	lowerPath := strings.ToLower(u.Path)
+	switch {
+	case strings.HasPrefix(lowerPath, "/api/strm/play/"):
+		segs := strings.Split(strings.TrimPrefix(u.Path, "/api/strm/play/"), "/")
+		if len(segs) < 1 || strings.TrimSpace(segs[0]) == "" {
+			return nil, errors.New("无效的 strm 播放地址")
+		}
+		return s.ResolvePlay(ctx, segs[0], u.Query())
+	case strings.HasPrefix(lowerPath, "/api/cloud/play/"):
+		typ := strings.TrimSpace(strings.TrimPrefix(u.Path, "/api/cloud/play/"))
+		acct, err := s.firstEnabledAccountOf(ctx, typ)
+		if err != nil || acct == nil {
+			return nil, errors.New("没有可用的网盘账号，无法解析直链")
+		}
+		q := u.Query()
+		q.Set("acct", acct.ID)
+		return s.ResolvePlay(ctx, typ, q)
+	case u.Scheme == "http" || u.Scheme == "https":
+		return &StrmPlayResult{RedirectURL: raw}, nil
+	default:
+		return nil, fmt.Errorf("不支持的播放目标协议: %s", u.Scheme)
+	}
+}
+
+// firstEnabledAccountOf 返回指定提供方第一个凭据可用的启用账号。
+func (s *StrmService) firstEnabledAccountOf(ctx context.Context, provider string) (*model.StrmAccount, error) {
+	accounts, err := s.repo.StrmAccount.List(ctx)
+	if err != nil {
+		return nil, err
+	}
+	for i := range accounts {
+		a := &accounts[i]
+		if !a.Enabled || a.Provider != provider {
+			continue
+		}
+		if _, err := s.providerFor(ctx, a); err == nil {
+			return a, nil
+		}
+	}
+	return nil, nil
+}
+
 // ProxyDirect 反向代理渲染直链内容（保留 Range 请求头以支持拖动播放）。
 func (s *StrmService) ProxyDirect(ctx context.Context, w http.ResponseWriter, r *http.Request, link *cloud.DirectLink) error {
 	if link == nil || link.URL == "" {

internal/service/subtitle.go

@@ -1,8 +1,8 @@
 // Package service — subtitle handling.
 //
-// SubtitleService finds external subtitle files next to a media file AND
-// embedded text subtitle tracks inside the media container, exposing both as
-// WebVTT so the browser <track> element can load them directly.
+// SubtitleService finds external subtitle files next to a media file and
+// exposes them as WebVTT so the browser <track> element can load them
+// directly, or as the original bytes for Emby/Jellyfin clients.
 //
 // External-subtitle discovery rules (matching the legacy Python defaults):
 //
@@ -12,25 +12,17 @@
 //     ?lang=zh / ?lang=en.
 //
 // Supported extensions: .srt, .ass, .ssa, .vtt.
-//
-// Embedded subtitles are probed with ffprobe and exposed as
-// path "embedded:<stream-index>"; the browser endpoint extracts the stream
-// via ffmpeg into a cached .vtt file.
 package service
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"os"
-	"os/exec"
 	"path/filepath"
 	"regexp"
-	"strconv"
 	"strings"
-	"time"
 
 	"go.uber.org/zap"
 
@@ -71,6 +63,16 @@ var extToCodec = map[string]string{
 // relative; the caller should prepend /api/subtitles/<media_id>?path=...
 // when serializing for the frontend.
 func (s *SubtitleService) Discover(ctx context.Context, mediaID string) ([]SubtitleTrack, error) {
+	return s.discover(ctx, mediaID)
+}
+
+// DiscoverExternalOnly 只返回媒体旁边的外挂字幕文件，不含容器内嵌字幕轨。
+// Emby 字幕接口（/Videos/:id/Subtitles/...）用。
+func (s *SubtitleService) DiscoverExternalOnly(ctx context.Context, mediaID string) ([]SubtitleTrack, error) {
+	return s.discover(ctx, mediaID)
+}
+
+func (s *SubtitleService) discover(ctx context.Context, mediaID string) ([]SubtitleTrack, error) {
 	m, err := s.repo.Media.FindByID(ctx, mediaID)
 	if err != nil {
 		return nil, err
@@ -118,94 +120,9 @@ func (s *SubtitleService) Discover(ctx context.Context, mediaID string) ([]Subti
 			})
 		}
 	}
-
-	// 容器内嵌文本字幕轨（MKV/MP4 等封装内的字幕流）：本地真实文件才可
-	// 探测提取；cloud:// 与 .strm 媒体跳过。探测失败静默忽略（无 ffprobe
-	// 或没有字幕流都属正常）。
-	if embedded, ok := s.discoverEmbeddedTracks(ctx, m.Path); ok {
-		tracks = append(tracks, embedded...)
-	}
 	return tracks, nil
 }
 
-// embeddedCodecOK 只暴露可提取为 WebVTT 的文本字幕编解码器；位图字幕
-// （PGS/DVDSUB/DVBSUB）浏览器无法渲染，跳过。
-func embeddedCodecOK(codec string) bool {
-	switch strings.ToLower(codec) {
-	case "subrip", "srt", "mov_text", "text", "webvtt", "ass", "ssa", "ttml", "sami":
-		return true
-	default:
-		return false
-	}
-}
-
-// ffprobeSubtitleStream 是 ffprobe -show_streams 输出的字幕流字段。
-type ffprobeSubtitleStream struct {
-	Index int               `json:"index"`
-	Codec string            `json:"codec_name"`
-	Tags  map[string]string `json:"tags"`
-}
-
-type ffprobeSubtitleContainer struct {
-	Streams []ffprobeSubtitleStream `json:"streams"`
-}
-
-// discoverEmbeddedTracks 用 ffprobe 探测媒体容器内的文本字幕轨。
-// 返回 (tracks, ok)：ok=false 表示该媒体不适用（非本地文件/ffprobe 不可用）。
-func (s *SubtitleService) discoverEmbeddedTracks(ctx context.Context, mediaPath string) ([]SubtitleTrack, bool) {
-	if strings.HasPrefix(strings.ToLower(strings.TrimSpace(mediaPath)), "cloud://") ||
-		strings.HasSuffix(strings.ToLower(strings.TrimSpace(mediaPath)), ".strm") {
-		return nil, false
-	}
-	bin, err := resolveLocalExecutable(s.cfg.App.FFprobePath, "ffprobe")
-	if err != nil {
-		return nil, false
-	}
-	if _, err := os.Stat(mediaPath); err != nil {
-		return nil, false
-	}
-
-	probeCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
-	defer cancel()
-	cmd := exec.CommandContext(probeCtx, bin, // #nosec G204 -- bin resolved by resolveLocalExecutable; args are fixed probes.
-		"-v", "error",
-		"-select_streams", "s",
-		"-show_entries", "stream=index,codec_name:stream_tags=language,title",
-		"-of", "json",
-		"--", mediaPath,
-	)
-	out, err := cmd.Output()
-	if err != nil {
-		return nil, false
-	}
-	var container ffprobeSubtitleContainer
-	if err := json.Unmarshal(out, &container); err != nil {
-		return nil, false
-	}
-
-	tracks := make([]SubtitleTrack, 0, len(container.Streams))
-	for _, stream := range container.Streams {
-		if !embeddedCodecOK(stream.Codec) {
-			continue
-		}
-		lang := strings.ToLower(strings.TrimSpace(stream.Tags["language"]))
-		if lang == "" {
-			lang = "und"
-		}
-		label := stream.Tags["title"]
-		if label == "" {
-			label = lang
-		}
-		tracks = append(tracks, SubtitleTrack{
-			Lang:  lang,
-			Label: "内置字幕 · " + label,
-			Path:  "embedded:" + strconv.Itoa(stream.Index),
-			Codec: stream.Codec,
-		})
-	}
-	return tracks, true
-}
-
 // langTag matches the .zh / .zh-cn / .chs language sub-extensions.
 var langTag = regexp.MustCompile(`(?i)\.([a-z]{2,3}(?:[-_][a-z]{2,4})?)$`)
 
@@ -222,18 +139,13 @@ func detectLang(name, base string) string {
 }
 
 // Serve writes the subtitle file as WebVTT (.vtt). SRT/SSA files are
-// converted minimally on the fly; embedded container tracks (path
-// "embedded:<index>") are extracted via ffmpeg into a cached .vtt.
-// Returns ErrSubtitleNotFound when the path is rejected (path traversal /
-// not in the media directory).
+// converted minimally on the fly. Returns ErrSubtitleNotFound when the
+// path is rejected (path traversal / not in the media directory).
 func (s *SubtitleService) Serve(ctx context.Context, mediaID, sub string, w io.Writer) error {
 	m, err := s.repo.Media.FindByID(ctx, mediaID)
 	if err != nil || m == nil {
 		return errors.New("media not found")
 	}
-	if strings.HasPrefix(sub, "embedded:") {
-		return s.ServeEmbeddedToVTT(ctx, m.Path, sub, w)
-	}
 	abs, err := filepath.Abs(sub)
 	if err != nil {
 		return err
@@ -266,81 +178,6 @@ func (s *SubtitleService) Serve(ctx context.Context, mediaID, sub string, w io.W
 	return err
 }
 
-// embeddedSubtitleCachePath 内嵌字幕提取后的 WebVTT 缓存路径
-// （按媒体路径哈希 + 轨道号定位，跨媒体互不干扰）。
-func (s *SubtitleService) embeddedSubtitleCachePath(mediaPath string, idx int) string {
-	hash := fmt.Sprintf("%x", fnvHash(mediaPath))
-	return filepath.Join(s.cfg.Cache.CacheDir, "subs", hash, fmt.Sprintf("s%d.vtt", idx))
-}
-
-// ServeEmbeddedToVTT 把容器内第 idx 个字幕轨提取为 WebVTT 输出。
-// 提取结果缓存在 cache 目录，媒体文件更新（mtime 变化）后自动重新提取。
-func (s *SubtitleService) ServeEmbeddedToVTT(ctx context.Context, mediaPath, streamRef string, w io.Writer) error {
-	idx, err := strconv.Atoi(strings.TrimPrefix(streamRef, "embedded:"))
-	if err != nil || idx < 0 {
-		return errors.New("invalid embedded subtitle index")
-	}
-	ffmpegBin, err := resolveLocalExecutable(s.cfg.App.FFmpegPath, "ffmpeg")
-	if err != nil {
-		return fmt.Errorf("ffmpeg 不可用，无法提取内嵌字幕：%w", err)
-	}
-	info, err := os.Stat(mediaPath)
-	if err != nil {
-		return errors.New("media file not found")
-	}
-
-	cachePath := s.embeddedSubtitleCachePath(mediaPath, idx)
-
-	if cached, statErr := os.Stat(cachePath); statErr == nil && !info.ModTime().After(cached.ModTime()) {
-		f, openErr := os.Open(cachePath) // #nosec G304 -- cachePath is generated under the cache dir.
-		if openErr == nil {
-			defer f.Close()
-			_, copyErr := io.Copy(w, f)
-			return copyErr
-		}
-	}
-
-	// 缓存未命中或媒体已更新：ffmpeg 提取到临时文件后原子改名。
-	if err := os.MkdirAll(filepath.Dir(cachePath), 0o750); err != nil {
-		return err
-	}
-	tmp := cachePath + ".tmp"
-	extractCtx, cancel := context.WithTimeout(ctx, 60*time.Second)
-	defer cancel()
-	cmd := exec.CommandContext(extractCtx, ffmpegBin, // #nosec G204 -- bin resolved by resolveLocalExecutable; args fixed extraction.
-		"-v", "error", "-y",
-		"-i", mediaPath,
-		"-map", "0:s:"+strconv.Itoa(idx),
-		"-f", "webvtt",
-		tmp,
-	)
-	if out, runErr := cmd.CombinedOutput(); runErr != nil {
-		_ = os.Remove(tmp)
-		return fmt.Errorf("提取内嵌字幕失败（轨道 %d，可能为位图字幕或轨道无效）：%s", idx, strings.TrimSpace(string(out)))
-	}
-	if err := os.Rename(tmp, cachePath); err != nil {
-		_ = os.Remove(tmp)
-		return err
-	}
-	f, err := os.Open(cachePath) // #nosec G304 -- cachePath is generated under the cache dir.
-	if err != nil {
-		return err
-	}
-	defer f.Close()
-	_, err = io.Copy(w, f)
-	return err
-}
-
-// fnvHash 简单 32 位 FNV-1a 哈希，用于生成稳定的缓存子目录名。
-func fnvHash(s string) uint32 {
-	var h uint32 = 2166136261
-	for i := 0; i < len(s); i++ {
-		h ^= uint32(s[i])
-		h *= 16777619
-	}
-	return h
-}
-
 // ServeRaw writes the subtitle file in its original format without any
 // WebVTT conversion. Emby/Jellyfin clients advertise the source codec (ASS,
 // subrip, etc.) in MediaStreams, then fetch the subtitle bytes via the
@@ -368,4 +205,4 @@ func (s *SubtitleService) ServeRaw(ctx context.Context, mediaID, sub string, w i
 	defer f.Close()
 	_, err = io.Copy(w, f)
 	return err
-}
+}

internal/service/visibility.go

@@ -50,7 +50,20 @@ func UserDefaultMediaVisibility(ctx context.Context, repo *repository.Container,
 		visibility.IncludeNSFW = false
 	}
 	visibility.HiddenLibraryIDs = hiddenAdultLibraryIDs(ctx, repo, visibility.IncludeNSFW)
-	if userID == "" || repo.PlayProfile == nil {
+	if userID == "" {
+		return visibility
+	}
+
+	if repo.User != nil {
+		user, err := repo.User.FindByID(ctx, userID)
+		if err == nil && user != nil && user.Role != "admin" {
+			if userAllowed := user.DecodeAllowedLibraryIDs(); len(userAllowed) > 0 {
+				visibility.AllowedLibraryIDs = userAllowed
+			}
+		}
+	}
+
+	if repo.PlayProfile == nil {
 		return visibility
 	}
 	rows, err := repo.PlayProfile.ListByUser(ctx, userID)
@@ -62,13 +75,44 @@ func UserDefaultMediaVisibility(ctx context.Context, repo *repository.Container,
 			continue
 		}
 		visibility.IncludeNSFW = visibility.IncludeNSFW && row.AllowAdult
-		visibility.AllowedLibraryIDs = DecodeAllowedLibraryIDs(row.AllowedLibraryIDs)
+		profileAllowed := DecodeAllowedLibraryIDs(row.AllowedLibraryIDs)
+		if len(profileAllowed) > 0 {
+			if len(visibility.AllowedLibraryIDs) > 0 {
+				visibility.AllowedLibraryIDs = IntersectStrings(visibility.AllowedLibraryIDs, profileAllowed)
+			} else {
+				visibility.AllowedLibraryIDs = profileAllowed
+			}
+		}
 		visibility.HiddenLibraryIDs = hiddenAdultLibraryIDs(ctx, repo, visibility.IncludeNSFW)
 		break
 	}
 	return visibility
 }
 
+// IntersectStrings 计算两个字符串切片的交集。
+func IntersectStrings(a, b []string) []string {
+	if len(a) == 0 {
+		return b
+	}
+	if len(b) == 0 {
+		return a
+	}
+	set := make(map[string]struct{}, len(b))
+	for _, s := range b {
+		set[s] = struct{}{}
+	}
+	var out []string
+	for _, s := range a {
+		if _, ok := set[s]; ok {
+			out = append(out, s)
+		}
+	}
+	if len(out) == 0 {
+		return []string{"__no_access__"}
+	}
+	return out
+}
+
 // DecodeAllowedLibraryIDs normalises a PlayProfile allowed-library JSON string.
 func DecodeAllowedLibraryIDs(raw string) []string {
 	if strings.TrimSpace(raw) == "" {

web/src/api/admin.ts

@@ -79,6 +79,9 @@ export const adminAPI = {
   setUserStatus: (id: string, isActive: boolean) =>
     api.patch<User>(`/admin/users/${id}/status`, { is_active: isActive }).then((r) => r.data),
 
+  updateUserLibraries: (id: string, allowedLibraryIDs: string[] | null) =>
+    api.patch<User>(`/admin/users/${id}/libraries`, { allowed_library_ids: allowedLibraryIDs }).then((r) => r.data),
+
   deleteUser: (id: string) => api.delete(`/admin/users/${id}`).then((r) => r.data),
 
   listSettings: () => api.get<Setting[]>('/admin/settings').then((r) => r.data),

web/src/api/library.ts

@@ -197,6 +197,9 @@ export const mediaAPI = {
 
   get: (id: string) => api.get<Media>(`/media/${id}`).then((r) => r.data),
 
+  getEpisodes: (id: string) =>
+    api.get<{ items: Media[]; total: number }>(`/media/${id}/episodes`).then((r) => r.data),
+
   updateMetadata: (id: string, payload: MediaMetadataUpdate) =>
     api.patch<Media>(`/media/${id}/metadata`, payload, { timeout: LONG_REQUEST_TIMEOUT }).then((r) => r.data),
 

web/src/api/tools.ts

@@ -67,6 +67,24 @@ export interface OrganizeResultSummary {
   }>
 }
 
+export interface FFmpegToolInfo {
+  installed: boolean
+  path?: string
+  version?: string
+}
+
+export interface FFmpegToolsStatus {
+  installing?: boolean
+  message?: string
+  error?: string
+  started_at?: string
+  finished_at?: string
+  install_dir?: string
+  target?: { os?: string; arch?: string; label?: string }
+  ffmpeg?: FFmpegToolInfo
+  ffprobe?: FFmpegToolInfo
+}
+
 export const toolsAPI = {
   organizeMedia: (mediaID: string, opts?: OrganizeOverrides) =>
     api
@@ -102,6 +120,14 @@ export const toolsAPI = {
       .post<{ message: string }>('/admin/notify/test', { title, body })
       .then((r) => r.data),
 
+  // ffToolsStatus 查询 ffmpeg/ffprobe 的安装状态（路径/版本/是否正在安装）。
+  ffToolsStatus: () =>
+    api.get<FFmpegToolsStatus>('/admin/tools/ffmpeg/status').then((r) => r.data),
+
+  // installFFTools 触发后台下载安装 ffmpeg/ffprobe（自动匹配当前平台）。
+  installFFTools: () =>
+    api.post<FFmpegToolsStatus>('/admin/tools/ffmpeg/install').then((r) => r.data),
+
   // repairAndRescrapeAll 触发「全库修复+重刮」：先从媒体路径中的
   // {tmdb-N}/{bangumi-N} 占位符回填缺失/错误的外部 ID，再批量重刮整库。
   // 后端异步执行，立即返回；进度通过 WS "scrape" topic 推送。

web/src/components/AdminUserLibrariesDialog.tsx

@@ -0,0 +1,330 @@
+import { useEffect, useState } from 'react'
+import toast from 'react-hot-toast'
+import {
+  Check,
+  CheckSquare,
+  Film,
+  FolderLock,
+  Layers,
+  Loader2,
+  Square,
+  Tv,
+  X,
+} from 'lucide-react'
+
+import { adminAPI } from '../api/admin'
+import { libraryAPI } from '../api/library'
+import type { Library, User } from '../types'
+import { libraryDisplayPath } from '../pages/libraryDisplayModel'
+
+type AdminUserLibrariesDialogProps = {
+  user: User | null
+  isOpen: boolean
+  onClose: () => void
+  onSaved: (updatedUser: User) => void
+}
+
+export function AdminUserLibrariesDialog({
+  user,
+  isOpen,
+  onClose,
+  onSaved,
+}: AdminUserLibrariesDialogProps) {
+  const [loading, setLoading] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [libraries, setLibraries] = useState<Library[]>([])
+  const [mode, setMode] = useState<'all' | 'custom'>('all')
+  const [selectedIDs, setSelectedIDs] = useState<Set<string>>(new Set())
+
+  useEffect(() => {
+    if (!isOpen || !user) return
+
+    setLoading(true)
+    libraryAPI
+      .list({ includeHidden: true })
+      .then((libs) => {
+        setLibraries(libs ?? [])
+      })
+      .catch(() => {
+        toast.error('加载媒体库列表失败')
+      })
+      .finally(() => {
+        setLoading(false)
+      })
+
+    const initialIDs = user.allowed_library_ids ?? []
+    if (initialIDs.length > 0) {
+      setMode('custom')
+      setSelectedIDs(new Set(initialIDs))
+    } else {
+      setMode('all')
+      setSelectedIDs(new Set())
+    }
+  }, [isOpen, user])
+
+  if (!isOpen || !user) return null
+
+  const toggleLibrary = (libID: string) => {
+    setSelectedIDs((prev) => {
+      const next = new Set(prev)
+      if (next.has(libID)) {
+        next.delete(libID)
+      } else {
+        next.add(libID)
+      }
+      return next
+    })
+  }
+
+  const handleSelectAll = () => {
+    setSelectedIDs(new Set(libraries.map((l) => l.id)))
+  }
+
+  const handleSelectNone = () => {
+    setSelectedIDs(new Set())
+  }
+
+  const handleSave = async () => {
+    setSaving(true)
+    try {
+      let payloadIDs: string[] | null = null
+      if (mode === 'custom') {
+        const arr = Array.from(selectedIDs)
+        // 如果勾选了全部，或者勾选为空
+        if (arr.length === 0) {
+          toast.error('请至少选择一个媒体库，或切换为“允许访问全部媒体库”')
+          setSaving(false)
+          return
+        }
+        if (arr.length < libraries.length) {
+          payloadIDs = arr
+        }
+      }
+
+      const updated = await adminAPI.updateUserLibraries(user.id, payloadIDs)
+      toast.success(
+        payloadIDs && payloadIDs.length > 0
+          ? `已成功配置用户【${user.username}】仅可访问 ${payloadIDs.length} 个媒体库`
+          : `已恢复用户【${user.username}】全库访问权限`,
+      )
+      onSaved(updated)
+      onClose()
+    } catch (err: unknown) {
+      const msg =
+        (err as { response?: { data?: { error?: string } } })?.response?.data?.error ??
+        '保存配置失败'
+      toast.error(msg)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4 backdrop-blur-sm animate-in fade-in-0"
+      onClick={onClose}
+    >
+      <div
+        className="w-full max-w-xl overflow-hidden rounded-3xl border border-white/70 bg-white shadow-2xl transition-all"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between border-b border-sand-100 p-5">
+          <div className="flex items-center gap-3">
+            <div className="flex h-10 w-10 items-center justify-center rounded-2xl bg-brand-50 text-brand-600">
+              <FolderLock size={20} />
+            </div>
+            <div>
+              <h3 className="font-display text-lg font-bold text-ink-600">
+                配置媒体库访问权限
+              </h3>
+              <p className="text-xs text-sand-500">
+                用户：<span className="font-semibold text-ink-600">{user.username}</span>
+                {user.role === 'admin' && (
+                  <span className="ml-2 rounded-full bg-amber-50 px-2 py-0.5 text-[10px] font-semibold text-amber-600 border border-amber-200">
+                    管理员拥有所有库访问权限
+                  </span>
+                )}
+              </p>
+            </div>
+          </div>
+          <button
+            onClick={onClose}
+            className="rounded-xl p-2 text-sand-500 hover:bg-sand-100 hover:text-ink-600 transition-colors"
+          >
+            <X size={18} />
+          </button>
+        </div>
+
+        {/* Content */}
+        <div className="p-5 space-y-4 max-h-[65vh] overflow-y-auto">
+          {/* 模式选择 */}
+          <div className="grid grid-cols-2 gap-3">
+            <button
+              type="button"
+              onClick={() => setMode('all')}
+              className={`flex items-center gap-3 rounded-2xl border p-3.5 text-left transition-all ${
+                mode === 'all'
+                  ? 'border-brand-400 bg-brand-50/70 text-brand-800 shadow-sm ring-1 ring-brand-400'
+                  : 'border-sand-200 bg-white text-ink-600 hover:border-sand-300 hover:bg-sand-50/50'
+              }`}
+            >
+              <div
+                className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-xl ${
+                  mode === 'all' ? 'bg-brand-500 text-white' : 'bg-sand-100 text-sand-500'
+                }`}
+              >
+                <Layers size={16} />
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="text-xs font-bold">全部媒体库 (默认)</div>
+                <div className="text-[11px] text-sand-500">用户可访问系统所有已建媒体库</div>
+              </div>
+            </button>
+
+            <button
+              type="button"
+              onClick={() => {
+                setMode('custom')
+                if (selectedIDs.size === 0) {
+                  setSelectedIDs(new Set(libraries.map((l) => l.id)))
+                }
+              }}
+              className={`flex items-center gap-3 rounded-2xl border p-3.5 text-left transition-all ${
+                mode === 'custom'
+                  ? 'border-brand-400 bg-brand-50/70 text-brand-800 shadow-sm ring-1 ring-brand-400'
+                  : 'border-sand-200 bg-white text-ink-600 hover:border-sand-300 hover:bg-sand-50/50'
+              }`}
+            >
+              <div
+                className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-xl ${
+                  mode === 'custom' ? 'bg-brand-500 text-white' : 'bg-sand-100 text-sand-500'
+                }`}
+              >
+                <FolderLock size={16} />
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="text-xs font-bold">指定可访问媒体库</div>
+                <div className="text-[11px] text-sand-500">仅允许访问管理员勾选的媒体库</div>
+              </div>
+            </button>
+          </div>
+
+          {/* 媒体库列表 */}
+          {mode === 'custom' && (
+            <div className="space-y-2 pt-2 border-t border-sand-100 animate-in fade-in-0 duration-200">
+              <div className="flex items-center justify-between text-xs text-sand-500 px-1">
+                <span>
+                  已选择{' '}
+                  <strong className="text-brand-600">{selectedIDs.size}</strong> /{' '}
+                  {libraries.length} 个媒体库
+                </span>
+                <div className="flex items-center gap-2">
+                  <button
+                    type="button"
+                    onClick={handleSelectAll}
+                    className="inline-flex items-center gap-1 text-[11px] font-semibold text-brand-600 hover:text-brand-700"
+                  >
+                    <CheckSquare size={13} />
+                    全选
+                  </button>
+                  <span>·</span>
+                  <button
+                    type="button"
+                    onClick={handleSelectNone}
+                    className="inline-flex items-center gap-1 text-[11px] font-semibold text-sand-500 hover:text-sand-700"
+                  >
+                    <Square size={13} />
+                    全不选
+                  </button>
+                </div>
+              </div>
+
+              {loading ? (
+                <div className="flex items-center justify-center py-12 text-sand-500 text-xs gap-2">
+                  <Loader2 size={16} className="animate-spin text-brand-500" />
+                  正在加载媒体库…
+                </div>
+              ) : libraries.length === 0 ? (
+                <div className="py-10 text-center text-xs text-sand-500 bg-sand-50/50 rounded-2xl">
+                  暂无可用媒体库
+                </div>
+              ) : (
+                <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+                  {libraries.map((lib) => {
+                    const isChecked = selectedIDs.has(lib.id)
+                    const isTv =
+                      lib.type === 'tv' || lib.type === 'anime' || lib.type === 'variety'
+                    return (
+                      <div
+                        key={lib.id}
+                        onClick={() => toggleLibrary(lib.id)}
+                        className={`group flex cursor-pointer items-center justify-between rounded-xl border p-3 transition-all ${
+                          isChecked
+                            ? 'border-brand-300 bg-brand-50/40 shadow-xs'
+                            : 'border-sand-200 bg-white hover:border-sand-300 hover:bg-sand-50/40'
+                        }`}
+                      >
+                        <div className="flex min-w-0 items-center gap-2.5">
+                          <div
+                            className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-lg ${
+                              isChecked
+                                ? 'bg-brand-500 text-white'
+                                : 'bg-sand-100 text-sand-500 group-hover:text-sand-700'
+                            }`}
+                          >
+                            {isTv ? <Tv size={15} /> : <Film size={15} />}
+                          </div>
+                          <div className="min-w-0 flex-1">
+                            <p className="truncate text-xs font-semibold text-ink-600">
+                              {lib.name}
+                            </p>
+                            <p
+                              className="truncate text-[10px] text-sand-500"
+                              title={lib.path}
+                            >
+                              {lib.type} · {libraryDisplayPath(lib.path)}
+                            </p>
+                          </div>
+                        </div>
+                        <div
+                          className={`flex h-5 w-5 shrink-0 items-center justify-center rounded-md border transition-colors ${
+                            isChecked
+                              ? 'border-brand-500 bg-brand-500 text-white'
+                              : 'border-sand-300 bg-white group-hover:border-sand-400'
+                          }`}
+                        >
+                          {isChecked && <Check size={12} className="stroke-[3]" />}
+                        </div>
+                      </div>
+                    )
+                  })}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-end gap-2.5 border-t border-sand-100 bg-sand-50/60 px-5 py-3.5">
+          <button
+            type="button"
+            onClick={onClose}
+            className="rounded-xl border border-sand-200 bg-white px-4 py-2 text-xs font-semibold text-ink-600 hover:bg-sand-100 transition-colors"
+          >
+            取消
+          </button>
+          <button
+            type="button"
+            disabled={saving || loading}
+            onClick={handleSave}
+            className="neon-button inline-flex items-center gap-2 px-5 py-2 text-xs font-semibold disabled:opacity-50"
+          >
+            {saving && <Loader2 size={13} className="animate-spin" />}
+            <span>保存配置</span>
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

web/src/components/ExternalPlayerButton.tsx

@@ -42,6 +42,7 @@ export function ExternalPlayerButton({
     <>
       <button
         type="button"
+        title={compact ? '使用外部播放器播放' : undefined}
         disabled={loading}
         onClick={(event) => {
           event.preventDefault()
@@ -50,7 +51,7 @@ export function ExternalPlayerButton({
         }}
         className={
           compact
-            ? 'rounded-lg border border-primary-400/35 bg-white px-2 py-1 text-xs font-semibold text-brand-500 hover:bg-primary-400/10 disabled:opacity-50'
+            ? 'shrink-0 inline-flex items-center rounded-lg border border-primary-400/35 bg-white px-2 py-1 text-xs font-semibold text-brand-500 hover:bg-primary-400/10 disabled:opacity-50 transition-colors whitespace-nowrap'
             : 'btn-outline border-brand-500/30 px-5 text-[#c9954a] hover:border-brand-500 hover:bg-brand-50'
         }
       >

web/src/components/FFToolsPanel.tsx

@@ -0,0 +1,154 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import toast from 'react-hot-toast'
+import { CheckCircle2, Download, Loader2, XCircle } from 'lucide-react'
+
+import { toolsAPI, type FFmpegToolInfo, type FFmpegToolsStatus } from '../api/tools'
+
+// FFToolsPanel 展示 ffmpeg/ffprobe 的安装状态，并提供「一键下载安装」：
+// 后端自动匹配当前运行环境（OS + 架构），下载到 data 目录并写入设置，
+// 无需手动填写路径。
+export function FFToolsPanel({ onInstalled }: { onInstalled?: () => void }) {
+  const [status, setStatus] = useState<FFmpegToolsStatus | null>(null)
+  const [working, setWorking] = useState(false)
+  const pollingRef = useRef(false)
+
+  const load = useCallback(async () => {
+    try {
+      setStatus(await toolsAPI.ffToolsStatus())
+    } catch {
+      // 网络波动时保持旧状态，不打断页面
+    }
+  }, [])
+
+  useEffect(() => {
+    load().catch(() => undefined)
+  }, [load])
+
+  const installing = Boolean(status?.installing)
+
+  // 安装进行中：轮询状态直到结束，完成后刷新设置页（路径字段自动填入）。
+  useEffect(() => {
+    if (!installing || pollingRef.current) return
+    pollingRef.current = true
+    const timer = window.setInterval(async () => {
+      try {
+        const next = await toolsAPI.ffToolsStatus()
+        setStatus(next)
+        if (!next.installing) {
+          window.clearInterval(timer)
+          pollingRef.current = false
+          if (next.error) {
+            toast.error(`FFmpeg 下载安装失败：${next.error}`)
+          } else {
+            toast.success('FFmpeg / FFprobe 下载安装完成，系统已自动使用')
+            onInstalled?.()
+          }
+        }
+      } catch {
+        // 轮询失败继续等下一轮
+      }
+    }, 1500)
+    return () => {
+      window.clearInterval(timer)
+      pollingRef.current = false
+    }
+  }, [installing, onInstalled])
+
+  const install = async () => {
+    setWorking(true)
+    try {
+      const next = await toolsAPI.installFFTools()
+      setStatus(next)
+      if (next.error && !next.installing) {
+        toast.error(next.error)
+      } else if (next.installing) {
+        toast('开始下载，完成后自动生效')
+      } else {
+        toast.success('已检测到可用工具')
+        onInstalled?.()
+      }
+    } catch (err) {
+      toast.error(
+        (err as { response?: { data?: { error?: string } } })?.response?.data?.error ??
+          (err as { message?: string })?.message ??
+          '启动下载失败',
+      )
+    } finally {
+      setWorking(false)
+    }
+  }
+
+  const busy = working || installing
+  const targetLabel = status?.target?.label ?? '当前平台'
+  const ffmpegInstalled = Boolean(status?.ffmpeg?.installed)
+  const ffprobeInstalled = Boolean(status?.ffprobe?.installed)
+
+  return (
+    <div className="glass-panel space-y-3">
+      <div className="flex items-center justify-between gap-3">
+        <div>
+          <div className="font-display text-lg font-bold text-ink-600">FFmpeg / FFprobe 工具</div>
+          <div className="text-xs text-sand-500">
+            当前平台：{targetLabel} · 安装目录：
+            <span className="font-mono">{status?.install_dir ?? '…'}</span>
+          </div>
+        </div>
+        <button
+          type="button"
+          onClick={install}
+          disabled={busy}
+          className="neon-button shrink-0 disabled:opacity-50"
+        >
+          {busy ? <Loader2 size={16} className="animate-spin" /> : <Download size={16} />}
+          {busy ? '下载安装中…' : '下载并安装'}
+        </button>
+      </div>
+
+      <div className="grid gap-2 md:grid-cols-2">
+        <ToolRow name="FFmpeg" info={status?.ffmpeg} />
+        <ToolRow name="FFprobe" info={status?.ffprobe} />
+      </div>
+
+      {(status?.message || status?.error) && (
+        <div
+          className={
+            status?.error
+              ? 'rounded-xl bg-red-50 px-3 py-2 text-xs text-red-600'
+              : 'rounded-xl bg-sand-100/70 px-3 py-2 text-xs text-sand-500'
+          }
+        >
+          {status?.error || status?.message}
+        </div>
+      )}
+
+      {!ffmpegInstalled || !ffprobeInstalled ? (
+        <div className="text-xs text-sand-500">
+          未检测到可用工具。点击「下载并安装」后，服务端会自动匹配当前系统下载对应版本，安装完成后无需手动填写路径。
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+function ToolRow({ name, info }: { name: string; info?: FFmpegToolInfo }) {
+  return (
+    <div className="flex items-center gap-2 rounded-xl border border-gray-200 bg-white/70 px-3 py-2">
+      {info?.installed ? (
+        <CheckCircle2 size={16} className="shrink-0 text-green-500" />
+      ) : (
+        <XCircle size={16} className="shrink-0 text-red-400" />
+      )}
+      <div className="min-w-0">
+        <div className="text-sm font-medium text-ink-600">
+          {name} {info?.installed ? '' : '（未安装）'}
+        </div>
+        {info?.installed && (
+          <div className="truncate font-mono text-[11px] text-ink-50" title={info.path}>
+            {info.path}
+          </div>
+        )}
+        {info?.version && <div className="truncate text-[11px] text-sand-500">{info.version}</div>}
+      </div>
+    </div>
+  )
+}

web/src/components/MediaSortDropdown.tsx

@@ -0,0 +1,128 @@
+import { useEffect, useRef, useState } from 'react'
+import { ArrowDown, ArrowUp, ArrowUpDown, Check, Shuffle } from 'lucide-react'
+
+import {
+  SORT_OPTIONS,
+  type SortField,
+  type SortOption,
+  type SortOrder,
+} from '../utils/mediaSort'
+
+type MediaSortDropdownProps = {
+  value: SortField
+  order: SortOrder
+  onChange: (field: SortField, order: SortOrder) => void
+  onReshuffle?: () => void
+  className?: string
+}
+
+export function MediaSortDropdown({
+  value,
+  order,
+  onChange,
+  onReshuffle,
+  className = '',
+}: MediaSortDropdownProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  const dropdownRef = useRef<HTMLDivElement>(null)
+
+  const currentOption = SORT_OPTIONS.find((opt) => opt.id === value) ?? SORT_OPTIONS[0]
+
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false)
+      }
+    }
+    if (isOpen) {
+      document.addEventListener('mousedown', handleClickOutside)
+    }
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside)
+    }
+  }, [isOpen])
+
+  const handleSelect = (option: SortOption) => {
+    if (option.id === 'random') {
+      if (value === 'random') {
+        onReshuffle?.()
+      } else {
+        onChange('random', 'desc')
+      }
+      setIsOpen(false)
+      return
+    }
+
+    if (value === option.id) {
+      // 再次点击相同项：切换升降序
+      const nextOrder: SortOrder = order === 'asc' ? 'desc' : 'asc'
+      onChange(option.id, nextOrder)
+    } else {
+      // 点击新项：应用默认排序方向
+      onChange(option.id, option.defaultOrder)
+    }
+    setIsOpen(false)
+  }
+
+  return (
+    <div className={`relative inline-block text-left ${className}`} ref={dropdownRef}>
+      <button
+        type="button"
+        onClick={() => setIsOpen((prev) => !prev)}
+        className="inline-flex h-9 items-center gap-1.5 rounded-xl border border-sand-200 bg-white/90 px-3 py-1.5 text-xs font-semibold text-ink-600 shadow-sm transition-all hover:border-brand-300 hover:bg-brand-50/50 hover:text-brand-700"
+        title="更改排序方式"
+      >
+        <ArrowUpDown size={14} className="text-sand-500" />
+        <span>排序: {currentOption.label}</span>
+        {value === 'random' ? (
+          <Shuffle size={12} className="text-brand-600" />
+        ) : order === 'asc' ? (
+          <ArrowUp size={13} className="text-brand-600 font-bold" />
+        ) : (
+          <ArrowDown size={13} className="text-brand-600 font-bold" />
+        )}
+      </button>
+
+      {isOpen && (
+        <div className="absolute right-0 z-50 mt-1.5 w-52 origin-top-right rounded-2xl border border-sand-200/80 bg-white/95 p-1.5 shadow-xl backdrop-blur-md transition-all animate-in fade-in-0 zoom-in-95">
+          <div className="px-2.5 py-1.5 text-[11px] font-bold text-sand-500 border-b border-sand-100">
+            排序方式
+          </div>
+          <div className="max-h-80 overflow-y-auto py-1 space-y-0.5">
+            {SORT_OPTIONS.map((option) => {
+              const isSelected = value === option.id
+              return (
+                <button
+                  key={option.id}
+                  type="button"
+                  onClick={() => handleSelect(option)}
+                  className={`flex w-full items-center justify-between rounded-xl px-3 py-2 text-xs font-medium transition-colors ${
+                    isSelected
+                      ? 'bg-brand-50 text-brand-700 font-semibold'
+                      : 'text-ink-600 hover:bg-sand-50 hover:text-brand-600'
+                  }`}
+                >
+                  <div className="flex items-center gap-2">
+                    {isSelected && <Check size={13} className="text-brand-600" />}
+                    <span className={isSelected ? '' : 'pl-5'}>{option.label}</span>
+                  </div>
+                  {isSelected && (
+                    <div className="flex items-center text-brand-600">
+                      {option.id === 'random' ? (
+                        <Shuffle size={13} />
+                      ) : order === 'asc' ? (
+                        <ArrowUp size={14} className="stroke-[2.5]" />
+                      ) : (
+                        <ArrowDown size={14} className="stroke-[2.5]" />
+                      )}
+                    </div>
+                  )}
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

web/src/components/PlayerControls.tsx

@@ -2,12 +2,15 @@ import { useEffect, useRef, useState } from 'react'
 import {
   Captions,
   CaptionsOff,
+  ListVideo,
   Maximize,
   MessageSquareText,
   Minimize,
   Pause,
   PictureInPicture,
   Play,
+  SkipBack,
+  SkipForward,
   Volume2,
   VolumeX,
 } from 'lucide-react'
@@ -34,6 +37,15 @@ type PlayerControlsProps = {
   danmakuOpen: boolean
   danmakuEnabled: boolean
   onToggleDanmaku: () => void
+  hasPrevEpisode?: boolean
+  hasNextEpisode?: boolean
+  onPrevEpisode?: () => void
+  onNextEpisode?: () => void
+  prevEpisodeTitle?: string
+  nextEpisodeTitle?: string
+  playlistOpen?: boolean
+  hasPlaylist?: boolean
+  onTogglePlaylist?: () => void
 }
 
 export function PlayerControls({
@@ -44,6 +56,15 @@ export function PlayerControls({
   danmakuOpen,
   danmakuEnabled,
   onToggleDanmaku,
+  hasPrevEpisode = false,
+  hasNextEpisode = false,
+  onPrevEpisode,
+  onNextEpisode,
+  prevEpisodeTitle,
+  nextEpisodeTitle,
+  playlistOpen = false,
+  hasPlaylist = false,
+  onTogglePlaylist,
 }: PlayerControlsProps) {
   const video = () => videoRef.current
   const container = () =>
@@ -69,6 +90,7 @@ export function PlayerControls({
   const isScrubbingRef = useRef(false)
   const subtitleMenuOpenRef = useRef(false)
   const danmakuOpenRef = useRef(false)
+  const playlistOpenRef = useRef(false)
 
   useEffect(() => {
     controlsHoveredRef.current = controlsHovered
@@ -86,6 +108,10 @@ export function PlayerControls({
     danmakuOpenRef.current = danmakuOpen
   }, [danmakuOpen])
 
+  useEffect(() => {
+    playlistOpenRef.current = playlistOpen
+  }, [playlistOpen])
+
   // 点击控制栏外部时关闭字幕菜单
   useEffect(() => {
     if (!subtitleMenuOpen) return
@@ -112,14 +138,16 @@ export function PlayerControls({
         !controlsHoveredRef.current &&
         !isScrubbingRef.current &&
         !subtitleMenuOpenRef.current &&
-        !danmakuOpenRef.current
+        !danmakuOpenRef.current &&
+        !playlistOpenRef.current
       ) {
         hideTimerRef.current = setTimeout(() => {
           if (
             !controlsHoveredRef.current &&
             !isScrubbingRef.current &&
             !subtitleMenuOpenRef.current &&
-            !danmakuOpenRef.current
+            !danmakuOpenRef.current &&
+            !playlistOpenRef.current
           ) {
             setUiVisible(false)
           }
@@ -137,7 +165,7 @@ export function PlayerControls({
       if (e.relatedTarget && stage.contains(e.relatedTarget as Node)) {
         return
       }
-      if (el.paused || controlsHoveredRef.current || isScrubbingRef.current) return
+      if (el.paused || controlsHoveredRef.current || isScrubbingRef.current || playlistOpenRef.current) return
       if (hideTimerRef.current) clearTimeout(hideTimerRef.current)
       setUiVisible(false)
     }
@@ -201,7 +229,7 @@ export function PlayerControls({
 
   // 当悬停或菜单状态改变时，更新控制栏计时器
   useEffect(() => {
-    if (controlsHovered || isScrubbing || subtitleMenuOpen || danmakuOpen) {
+    if (controlsHovered || isScrubbing || subtitleMenuOpen || danmakuOpen || playlistOpen) {
       setUiVisible(true)
       if (hideTimerRef.current) clearTimeout(hideTimerRef.current)
     } else {
@@ -211,7 +239,7 @@ export function PlayerControls({
         hideTimerRef.current = setTimeout(() => setUiVisible(false), 3000)
       }
     }
-  }, [controlsHovered, isScrubbing, subtitleMenuOpen, danmakuOpen])
+  }, [controlsHovered, isScrubbing, subtitleMenuOpen, danmakuOpen, playlistOpen])
 
   const togglePlay = () => {
     const el = video()
@@ -297,14 +325,43 @@ export function PlayerControls({
       onClick={(e) => e.stopPropagation()}
     >
       <div className="flex items-center gap-2.5 text-white">
+        {/* 上一集 */}
+        <button
+          onClick={onPrevEpisode}
+          disabled={!hasPrevEpisode}
+          className={`rounded-full p-1.5 transition ${
+            hasPrevEpisode
+              ? 'hover:bg-white/15 text-white cursor-pointer'
+              : 'text-white/30 cursor-not-allowed opacity-40'
+          }`}
+          title={hasPrevEpisode ? (prevEpisodeTitle ? `上一集：${prevEpisodeTitle} ([)` : '上一集 ([)') : '没有上一集'}
+        >
+          <SkipBack size={18} />
+        </button>
+
+        {/* 播放 / 暂停 */}
         <button
           onClick={togglePlay}
           className="rounded-full p-1.5 transition hover:bg-white/15"
-          title={playing ? '暂停' : '播放'}
+          title={playing ? '暂停 (Space)' : '播放 (Space)'}
         >
           {playing ? <Pause size={20} /> : <Play size={20} />}
         </button>
 
+        {/* 下一集 */}
+        <button
+          onClick={onNextEpisode}
+          disabled={!hasNextEpisode}
+          className={`rounded-full p-1.5 transition ${
+            hasNextEpisode
+              ? 'hover:bg-white/15 text-white cursor-pointer'
+              : 'text-white/30 cursor-not-allowed opacity-40'
+          }`}
+          title={hasNextEpisode ? (nextEpisodeTitle ? `下一集：${nextEpisodeTitle} (])` : '下一集 (])') : '没有下一集'}
+        >
+          <SkipForward size={18} />
+        </button>
+
         <input
           type="range"
           min={0}
@@ -383,6 +440,27 @@ export function PlayerControls({
           </div>
         )}
 
+        {/* 选集 / 播放列表按钮 */}
+        {onTogglePlaylist && (
+          <button
+            onClick={onTogglePlaylist}
+            disabled={!hasPlaylist}
+            className={
+              'flex items-center gap-1.5 rounded-full px-2.5 py-1.5 text-xs font-medium transition ' +
+              (!hasPlaylist
+                ? 'bg-white/5 text-white/30 cursor-not-allowed opacity-50'
+                : playlistOpen
+                ? 'bg-rose-500 text-white hover:bg-rose-600'
+                : 'bg-white/10 text-white/80 hover:bg-white/20')
+            }
+            title={hasPlaylist ? '选集列表' : '当前无更多剧集'}
+          >
+            <ListVideo size={15} />
+            选集
+          </button>
+        )}
+
+        {/* 弹幕按钮 */}
         <button
           onClick={onToggleDanmaku}
           className={
@@ -401,7 +479,7 @@ export function PlayerControls({
         <button
           onClick={toggleMute}
           className="rounded-full p-1.5 transition hover:bg-white/15"
-          title={muted || volume === 0 ? '取消静音' : '静音'}
+          title={muted || volume === 0 ? '取消静音 (M)' : '静音 (M)'}
         >
           {muted || volume === 0 ? <VolumeX size={18} /> : <Volume2 size={18} />}
         </button>
@@ -419,7 +497,7 @@ export function PlayerControls({
         <button
           onClick={toggleFullscreen}
           className="rounded-full p-1.5 transition hover:bg-white/15"
-          title={fullscreen ? '退出全屏' : '全屏'}
+          title={fullscreen ? '退出全屏 (F)' : '全屏 (F)'}
         >
           {fullscreen ? <Minimize size={18} /> : <Maximize size={18} />}
         </button>

web/src/components/PlayerPlaylistPanel.tsx

@@ -0,0 +1,296 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Check, Film, ListVideo, Play, Search, X } from 'lucide-react'
+
+import { imageURL } from '../api/client'
+import type { Media } from '../types'
+import { seriesTitleFromPath } from '../utils/groupSeries'
+
+export type SeasonGroup = {
+  season: number
+  episodes: Media[]
+}
+
+type PlayerPlaylistPanelProps = {
+  open: boolean
+  onClose: () => void
+  currentMediaId: string
+  episodes: Media[]
+  onSelectEpisode: (media: Media) => void
+}
+
+export function PlayerPlaylistPanel({
+  open,
+  onClose,
+  currentMediaId,
+  episodes,
+  onSelectEpisode,
+}: PlayerPlaylistPanelProps) {
+  const [filterText, setFilterText] = useState('')
+  const activeItemRef = useRef<HTMLDivElement | null>(null)
+  const listContainerRef = useRef<HTMLDivElement | null>(null)
+
+  // 按季分组
+  const seasonGroups = useMemo<SeasonGroup[]>(() => {
+    if (!episodes || episodes.length === 0) return []
+    const seasonsMap = new Map<number, Media[]>()
+    for (const ep of episodes) {
+      const s = ep.episode_num > 0 ? (ep.season_num ?? 0) : (ep.season_num || 1)
+      if (!seasonsMap.has(s)) seasonsMap.set(s, [])
+      seasonsMap.get(s)!.push(ep)
+    }
+    for (const [, list] of seasonsMap) {
+      list.sort((a, b) => (a.episode_num || 0) - (b.episode_num || 0))
+    }
+    return Array.from(seasonsMap.entries())
+      .sort(([a], [b]) => a - b)
+      .map(([season, list]) => ({ season, episodes: list }))
+  }, [episodes])
+
+  // 当前播放所在季
+  const currentSeason = useMemo(() => {
+    const found = episodes.find((e) => e.id === currentMediaId)
+    if (!found) return seasonGroups[0]?.season ?? 1
+    return found.episode_num > 0 ? (found.season_num ?? 0) : (found.season_num || 1)
+  }, [episodes, currentMediaId, seasonGroups])
+
+  const [selectedSeason, setSelectedSeason] = useState<number>(currentSeason)
+
+  // 当当前播放媒体改变或打开面板时，默认选中当前媒体所在的季
+  useEffect(() => {
+    if (open) {
+      setSelectedSeason(currentSeason)
+    }
+  }, [open, currentSeason])
+
+  // 当面板打开时，自动平滑滚动到当前播放集的位置
+  useEffect(() => {
+    if (open && activeItemRef.current) {
+      const timer = setTimeout(() => {
+        activeItemRef.current?.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+      }, 100)
+      return () => clearTimeout(timer)
+    }
+  }, [open, selectedSeason, currentMediaId])
+
+  if (!open) return null
+
+  const currentGroup = seasonGroups.find((g) => g.season === selectedSeason) ?? seasonGroups[0]
+  const listToDisplay = currentGroup ? currentGroup.episodes : episodes
+
+  const filteredEpisodes = filterText.trim()
+    ? listToDisplay.filter((ep) => {
+        const query = filterText.trim().toLowerCase()
+        const title = (ep.episode_title || ep.title || '').toLowerCase()
+        const epNum = String(ep.episode_num)
+        return title.includes(query) || epNum === query || `e${epNum}`.includes(query) || `第${epNum}集`.includes(query)
+      })
+    : listToDisplay
+
+  return (
+    <div
+      onClick={(e) => e.stopPropagation()}
+      className="absolute right-4 top-16 bottom-20 z-30 flex w-80 sm:w-96 flex-col rounded-2xl border border-white/15 bg-black/85 text-white shadow-2xl backdrop-blur-md overflow-hidden"
+    >
+      {/* 头部 */}
+      <div className="flex items-center justify-between border-b border-white/10 px-4 py-3 shrink-0">
+        <div className="flex items-center gap-2 text-sm font-semibold">
+          <ListVideo size={17} className="text-rose-400" />
+          <span>选集列表</span>
+          <span className="font-mono text-xs font-normal text-white/50">
+            ({episodes.length} 集)
+          </span>
+        </div>
+        <button
+          onClick={onClose}
+          className="rounded-full p-1 text-white/60 transition hover:bg-white/10 hover:text-white"
+          title="关闭"
+        >
+          <X size={16} />
+        </button>
+      </div>
+
+      {/* 季选择 Tabs（若有多季） */}
+      {seasonGroups.length > 1 && (
+        <div className="flex items-center gap-1.5 border-b border-white/10 px-3 py-2 shrink-0 overflow-x-auto no-scrollbar">
+          {seasonGroups.map(({ season, episodes: sesEps }) => {
+            const isSelected = selectedSeason === season
+            const isPlayingThisSeason = sesEps.some((e) => e.id === currentMediaId)
+            return (
+              <button
+                key={season}
+                onClick={() => {
+                  setSelectedSeason(season)
+                  setFilterText('')
+                }}
+                className={`relative flex shrink-0 items-center gap-1 rounded-lg px-2.5 py-1 text-xs font-medium transition ${
+                  isSelected
+                    ? 'bg-rose-500 text-white'
+                    : 'bg-white/5 text-white/70 hover:bg-white/10 hover:text-white'
+                }`}
+              >
+                <span>{season === 0 ? '特别篇' : `第 ${season} 季`}</span>
+                <span className="text-[10px] opacity-75">({sesEps.length})</span>
+                {isPlayingThisSeason && !isSelected && (
+                  <span className="h-1.5 w-1.5 rounded-full bg-rose-400" />
+                )}
+              </button>
+            )
+          })}
+        </div>
+      )}
+
+      {/* 搜索/过滤单集（当单集数量较多时） */}
+      {listToDisplay.length > 10 && (
+        <div className="px-3 pt-2.5 pb-1.5 shrink-0">
+          <div className="flex items-center gap-1.5 rounded-lg border border-white/10 bg-white/5 px-2.5 py-1 text-xs">
+            <Search size={13} className="text-white/40 shrink-0" />
+            <input
+              type="text"
+              value={filterText}
+              onChange={(e) => setFilterText(e.target.value)}
+              placeholder="搜索集数或标题…"
+              className="w-full bg-transparent outline-none placeholder:text-white/30 text-white text-xs"
+            />
+            {filterText && (
+              <button
+                onClick={() => setFilterText('')}
+                className="text-white/40 hover:text-white"
+              >
+                <X size={12} />
+              </button>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* 集数列表 */}
+      <div
+        ref={listContainerRef}
+        className="flex-1 overflow-y-auto p-2.5 space-y-1.5 pr-2 select-none"
+      >
+        {filteredEpisodes.length === 0 ? (
+          <div className="py-8 text-center text-xs text-white/40">
+            {filterText ? '未找到匹配的剧集' : '暂无剧集列表'}
+          </div>
+        ) : (
+          filteredEpisodes.map((ep) => {
+            const isPlaying = ep.id === currentMediaId
+            const displayTitle = getEpisodeTitle(ep, listToDisplay)
+            const durationText =
+              ep.duration_sec > 0 ? `${Math.floor(ep.duration_sec / 60)} 分钟` : ''
+
+            return (
+              <div
+                key={ep.id}
+                ref={isPlaying ? activeItemRef : null}
+                onClick={() => onSelectEpisode(ep)}
+                className={`group flex cursor-pointer items-center gap-2.5 rounded-xl p-2 transition border ${
+                  isPlaying
+                    ? 'border-rose-500/60 bg-rose-500/20 text-white'
+                    : 'border-white/5 bg-white/5 hover:border-white/20 hover:bg-white/10 text-white/85'
+                }`}
+              >
+                {/* 封面/集号 */}
+                <div className="relative flex h-11 w-16 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-white/10 text-xs font-semibold">
+                  {ep.backdrop_url || ep.poster_url ? (
+                    <img
+                      src={imageURL(ep.backdrop_url || ep.poster_url || '', ep.updated_at)}
+                      alt=""
+                      className="h-full w-full object-cover"
+                      referrerPolicy="no-referrer"
+                    />
+                  ) : (
+                    <Film size={16} className="text-white/40" />
+                  )}
+
+                  {/* 正在播放动效 / 集数徽标 */}
+                  {isPlaying ? (
+                    <div className="absolute inset-0 flex items-center justify-center bg-black/60 backdrop-blur-xs">
+                      <div className="flex items-end gap-0.5 h-3">
+                        <span className="w-0.5 bg-rose-400 animate-pulse h-full" />
+                        <span className="w-0.5 bg-rose-400 animate-pulse h-2" />
+                        <span className="w-0.5 bg-rose-400 animate-pulse h-3" />
+                      </div>
+                    </div>
+                  ) : (
+                    <div className="absolute inset-0 flex items-center justify-center bg-black/40 opacity-0 group-hover:opacity-100 transition-opacity">
+                      <Play size={14} className="text-white fill-white" />
+                    </div>
+                  )}
+
+                  {/* 角标显示集数 */}
+                  <span className="absolute bottom-0.5 right-1 rounded bg-black/75 px-1 py-0.2 text-[9px] font-mono text-white/90">
+                    {ep.episode_num > 0 ? `${ep.episode_num}` : '—'}
+                  </span>
+                </div>
+
+                {/* 标题 & 时长 */}
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-1.5">
+                    <p
+                      className={`truncate text-xs font-medium ${
+                        isPlaying ? 'text-rose-300 font-semibold' : 'group-hover:text-white'
+                      }`}
+                    >
+                      {displayTitle}
+                    </p>
+                  </div>
+                  <div className="flex items-center gap-2 mt-0.5 text-[10px] text-white/50">
+                    {ep.episode_num > 0 && (
+                      <span className="font-mono">第 {ep.episode_num} 集</span>
+                    )}
+                    {durationText && <span>{durationText}</span>}
+                  </div>
+                </div>
+
+                {isPlaying && (
+                  <div className="shrink-0 flex items-center gap-1 text-[11px] font-medium text-rose-400 px-1">
+                    <Check size={13} />
+                  </div>
+                )}
+              </div>
+            )
+          })
+        )}
+      </div>
+    </div>
+  )
+}
+
+function getEpisodeTitle(ep: Media, siblings: Media[]): string {
+  const title = ep.episode_title?.trim()
+  if (title && !looksLikeSeriesTitle(ep, title, siblings)) {
+    return title
+  }
+
+  const mediaTitle = ep.title?.trim()
+  if (mediaTitle && !looksLikeSeriesTitle(ep, mediaTitle, siblings)) {
+    return mediaTitle
+  }
+
+  return ep.episode_num > 0 ? `第 ${ep.episode_num} 集` : mediaTitle || title || '未命名'
+}
+
+function looksLikeSeriesTitle(ep: Media, title: string, siblings: Media[]): boolean {
+  const normalized = normalizeEpisodeTitle(title)
+  if (!normalized) return true
+  if (ep.original_name && normalizeEpisodeTitle(ep.original_name) === normalized) return true
+  const pathTitle = seriesTitleFromPath(ep.path)
+  if (pathTitle && normalizeEpisodeTitle(pathTitle) === normalized) return true
+
+  const siblingTitles = new Set(
+    siblings
+      .map((item) => normalizeEpisodeTitle(item.title))
+      .filter(Boolean),
+  )
+  return siblingTitles.size === 1 && siblingTitles.has(normalized) && siblings.length > 1
+}
+
+function normalizeEpisodeTitle(value?: string): string {
+  return (value ?? '')
+    .toLowerCase()
+    .replace(/\s*\((?:19|20)\d{2}\)\s*/g, ' ')
+    .replace(/\s*\{(?:tmdb|tmdbid|douban|bangumi|bgm|thetvdb|tvdb)[\s:=#-]*[a-z0-9_-]+\}\s*/g, ' ')
+    .replace(/[\s._-]+/g, ' ')
+    .trim()
+}

web/src/pages/AdminUsersPanel.tsx

@@ -5,6 +5,7 @@ import { adminAPI } from '../api/admin'
 import type { User } from '../types'
 import { confirmAction } from '../components/confirmAction'
 import { requestPassword } from '../components/requestPassword'
+import { AdminUserLibrariesDialog } from '../components/AdminUserLibrariesDialog'
 import { AdminUsersForm } from './AdminUsersForm'
 import { AdminUsersTable } from './AdminUsersTable'
 
@@ -15,6 +16,8 @@ export function AdminUsersPanel() {
   const [editingID, setEditingID] = useState<string | null>(null)
   const [editingUsername, setEditingUsername] = useState('')
   const [resettingPasswordID, setResettingPasswordID] = useState<string | null>(null)
+  const [configuringLibrariesUser, setConfiguringLibrariesUser] = useState<User | null>(null)
+
   const refresh = async () => {
     setUsers(await adminAPI.listUsers())
   }
@@ -148,9 +151,20 @@ export function AdminUsersPanel() {
         onCancelEdit={() => setEditingID(null)}
         onStartEdit={startEdit}
         onResetPassword={resetPassword}
+        onConfigureLibraries={(u) => setConfiguringLibrariesUser(u)}
         onToggleStatus={toggleStatus}
         onDeleteUser={deleteUser}
       />
+
+      <AdminUserLibrariesDialog
+        user={configuringLibrariesUser}
+        isOpen={Boolean(configuringLibrariesUser)}
+        onClose={() => setConfiguringLibrariesUser(null)}
+        onSaved={async (updated) => {
+          setUsers((prev) => prev.map((u) => (u.id === updated.id ? updated : u)))
+          await refresh()
+        }}
+      />
     </div>
   )
 }

web/src/pages/AdminUsersTable.tsx

@@ -1,4 +1,14 @@
-import { KeyRound, Loader2, Pencil, ShieldCheck, Trash2, UserCheck, UserX, X } from 'lucide-react'
+import {
+  FolderLock,
+  KeyRound,
+  Loader2,
+  Pencil,
+  ShieldCheck,
+  Trash2,
+  UserCheck,
+  UserX,
+  X,
+} from 'lucide-react'
 
 import type { User } from '../types'
 
@@ -12,6 +22,7 @@ type AdminUsersTableProps = {
   onCancelEdit: () => void
   onStartEdit: (user: User) => void
   onResetPassword: (user: User) => void
+  onConfigureLibraries: (user: User) => void
   onToggleStatus: (user: User) => void
   onDeleteUser: (user: User) => void
 }
@@ -26,6 +37,7 @@ export function AdminUsersTable({
   onCancelEdit,
   onStartEdit,
   onResetPassword,
+  onConfigureLibraries,
   onToggleStatus,
   onDeleteUser,
 }: AdminUsersTableProps) {
@@ -36,6 +48,7 @@ export function AdminUsersTable({
           <tr>
             <th className="py-2">用户名</th>
             <th>角色</th>
+            <th>媒体库权限</th>
             <th>状态</th>
             <th>权限说明</th>
             <th>最近登录</th>
@@ -60,6 +73,27 @@ export function AdminUsersTable({
                 )}
               </td>
               <td className="text-ink-100">{u.role === 'admin' ? '管理员' : '观看用户'}</td>
+              <td>
+                {u.role === 'admin' ? (
+                  <span className="inline-flex items-center rounded-full bg-sand-100 px-2.5 py-0.5 text-xs text-sand-600 font-medium">
+                    全库 (管理员)
+                  </span>
+                ) : !u.allowed_library_ids || u.allowed_library_ids.length === 0 ? (
+                  <span className="inline-flex items-center rounded-full bg-green-50 border border-green-200/80 px-2.5 py-0.5 text-xs font-medium text-green-700">
+                    全部媒体库 (默认)
+                  </span>
+                ) : (
+                  <button
+                    type="button"
+                    onClick={() => onConfigureLibraries(u)}
+                    className="inline-flex items-center gap-1 rounded-full bg-brand-50 border border-brand-300 px-2.5 py-0.5 text-xs font-semibold text-brand-700 hover:bg-brand-100/70 transition-colors"
+                    title="点击修改媒体库访问权限"
+                  >
+                    <FolderLock size={12} />
+                    <span>已指定 {u.allowed_library_ids.length} 个库</span>
+                  </button>
+                )}
+              </td>
               <td className={u.is_active ? 'text-green-500' : 'text-red-400'}>
                 {u.is_active ? '正常' : '已禁用'}
               </td>
@@ -92,11 +126,19 @@ export function AdminUsersTable({
                 ) : (
                   <button
                     className="rounded-lg border border-primary-400/40 px-2 py-1 text-xs text-brand-500 hover:bg-primary-400/10"
+                    title="重命名用户"
                     onClick={() => onStartEdit(u)}
                   >
                     <Pencil size={12} />
                   </button>
                 )}
+                <button
+                  className="rounded-lg border border-brand-400/40 px-2 py-1 text-xs text-brand-600 hover:bg-brand-400/10"
+                  title="配置媒体库访问权限"
+                  onClick={() => onConfigureLibraries(u)}
+                >
+                  <FolderLock size={12} />
+                </button>
                 <button
                   className="rounded-lg border border-amber-400/40 px-2 py-1 text-xs text-amber-500 hover:bg-amber-400/10"
                   title="重置密码"

web/src/pages/LibraryPage.tsx

@@ -1,10 +1,17 @@
-import { useState } from 'react'
+import { useEffect, useMemo, useState } from 'react'
 import { useLocation, useParams, useSearchParams } from 'react-router-dom'
 import { motion } from 'framer-motion'
 
+import { historyAPI } from '../api/history'
 import type { Media } from '../types'
 import { useAuthStore } from '../stores/auth'
 import type { SeriesCard } from '../utils/groupSeries'
+import {
+  sortMediaList,
+  sortSeriesList,
+  type SortField,
+  type SortOrder,
+} from '../utils/mediaSort'
 import { LibraryPageDialogs } from './LibraryPageDialogs'
 import { LibraryPageHeader } from './LibraryPageHeader'
 import { LibraryMediaSections } from './LibraryMediaSections'
@@ -25,6 +32,53 @@ export function LibraryPage() {
   const [seriesMetadataEditOpen, setSeriesMetadataEditOpen] = useState(false)
   const [manualMovie, setManualMovie] = useState<Media | null>(null)
 
+  // 排序状态（支持按库记忆）
+  const [sortField, setSortField] = useState<SortField>(() => {
+    const saved = localStorage.getItem(`mmtl_lib_sort_field_${id}`) || localStorage.getItem('mmtl_lib_sort_field')
+    return (saved as SortField) || 'title'
+  })
+  const [sortOrder, setSortOrder] = useState<SortOrder>(() => {
+    const saved = localStorage.getItem(`mmtl_lib_sort_order_${id}`) || localStorage.getItem('mmtl_lib_sort_order')
+    return (saved as SortOrder) || 'asc'
+  })
+  const [randomSeed, setRandomSeed] = useState(() => Date.now())
+  const [historyMap, setHistoryMap] = useState<Map<string, string>>(new Map())
+
+  useEffect(() => {
+    historyAPI
+      .list(1000)
+      .then((historyItems) => {
+        const map = new Map<string, string>()
+        for (const item of historyItems ?? []) {
+          if (item.media_id && item.watched_at) {
+            if (!map.has(item.media_id) || new Date(item.watched_at) > new Date(map.get(item.media_id)!)) {
+              map.set(item.media_id, item.watched_at)
+            }
+          }
+        }
+        setHistoryMap(map)
+      })
+      .catch(() => {})
+  }, [])
+
+  const handleSortChange = (field: SortField, order: SortOrder) => {
+    setSortField(field)
+    setSortOrder(order)
+    if (id) {
+      localStorage.setItem(`mmtl_lib_sort_field_${id}`, field)
+      localStorage.setItem(`mmtl_lib_sort_order_${id}`, order)
+    }
+    localStorage.setItem('mmtl_lib_sort_field', field)
+    localStorage.setItem('mmtl_lib_sort_order', order)
+    if (field === 'random') {
+      setRandomSeed(Date.now())
+    }
+  }
+
+  const handleReshuffle = () => {
+    setRandomSeed(Date.now())
+  }
+
   // 剧集模式：选中某个剧集后展开详情
   const [selectedSeries, setSelectedSeries] = useState<SeriesCard | null>(null)
   const [selectedSeason, setSelectedSeason] = useState<number | null>(null)
@@ -43,6 +97,14 @@ export function LibraryPage() {
     reloadCurrentLibrary,
   } = useLibraryData(id, selectedSeries)
 
+  const sortedItems = useMemo(() => {
+    return sortMediaList(items, sortField, sortOrder, randomSeed, historyMap)
+  }, [items, sortField, sortOrder, randomSeed, historyMap])
+
+  const sortedSeriesCards = useMemo(() => {
+    return sortSeriesList(seriesCards, sortField, sortOrder, randomSeed, historyMap)
+  }, [seriesCards, sortField, sortOrder, randomSeed, historyMap])
+
   const {
     scanning,
     scanProgress,
@@ -66,7 +128,7 @@ export function LibraryPage() {
     isSeriesLibrary,
     isSeries,
     loading,
-    seriesCards,
+    seriesCards: sortedSeriesCards,
     searchParams,
     setSearchParams,
     selectedSeries,
@@ -116,7 +178,7 @@ export function LibraryPage() {
       {!selectedSeries && (
         <LibraryPageHeader
           library={library}
-          itemCount={isSeries ? seriesCards.length : total}
+          itemCount={isSeries ? sortedSeriesCards.length : total}
           loadingAllText={loadingAllText}
           scanProgress={scanProgress}
           isAdmin={role === 'admin'}
@@ -124,6 +186,10 @@ export function LibraryPage() {
           scanning={scanning}
           scraping={scraping}
           repairing={repairing}
+          sortField={sortField}
+          sortOrder={sortOrder}
+          onSortChange={handleSortChange}
+          onReshuffle={handleReshuffle}
           onScrapeEpisodeArtworkChange={setScrapeEpisodeArtwork}
           onScan={handleScan}
           onScrape={() => setScrapeDialogOpen(true)}
@@ -133,8 +199,8 @@ export function LibraryPage() {
 
       <LibraryMediaSections
         isSeries={isSeries}
-        items={items}
-        seriesCards={seriesCards}
+        items={sortedItems}
+        seriesCards={sortedSeriesCards}
         selectedSeries={selectedSeries}
         loading={loading}
         movieActions={movieActions}

web/src/pages/LibraryPageHeader.tsx

@@ -1,5 +1,7 @@
 import type { Library } from '../types'
 import { EpisodeArtworkToggle } from '../components/EpisodeArtworkToggle'
+import { MediaSortDropdown } from '../components/MediaSortDropdown'
+import type { SortField, SortOrder } from '../utils/mediaSort'
 import { libraryDisplayPath } from './libraryDisplayModel'
 
 type LibraryPageHeaderProps = {
@@ -12,6 +14,10 @@ type LibraryPageHeaderProps = {
   scanning: boolean
   scraping: boolean
   repairing: boolean
+  sortField: SortField
+  sortOrder: SortOrder
+  onSortChange: (field: SortField, order: SortOrder) => void
+  onReshuffle: () => void
   onScrapeEpisodeArtworkChange: (checked: boolean) => void
   onScan: () => void
   onScrape: () => void
@@ -28,6 +34,10 @@ export function LibraryPageHeader({
   scanning,
   scraping,
   repairing,
+  sortField,
+  sortOrder,
+  onSortChange,
+  onReshuffle,
   onScrapeEpisodeArtworkChange,
   onScan,
   onScrape,
@@ -46,30 +56,38 @@ export function LibraryPageHeader({
         {loadingAllText && <p className="mt-1 text-xs text-sand-500">{loadingAllText}</p>}
         {scanProgress && <p className="mt-1 text-xs text-brand-500">{scanProgress}</p>}
       </div>
-      {isAdmin && (
-        <div className="flex flex-wrap items-center gap-2">
-          <EpisodeArtworkToggle
-            checked={scrapeEpisodeArtwork}
-            onChange={onScrapeEpisodeArtworkChange}
-            title="关闭后仍会获取主海报和每集文字元数据，只跳过每集图片"
-            className="h-10"
-          />
-          <button onClick={onScan} disabled={scanning} className="btn-outline">
-            {scanning ? '扫描中…' : '扫描媒体库'}
-          </button>
-          <button onClick={onScrape} disabled={scraping} className="btn-outline" title="对整个媒体库执行刮削元数据">
-            {scraping ? '刮削中…' : '整库刮削元数据'}
-          </button>
-          <button
-            onClick={onRepairRescrape}
-            disabled={repairing}
-            className="btn-outline"
-            title="回填本库占位符外部 ID 并重刮，修正空 ID / 拆集问题"
-          >
-            {repairing ? '修复中…' : '修复+重刮整库'}
-          </button>
-        </div>
-      )}
+      <div className="flex flex-wrap items-center gap-2">
+        <MediaSortDropdown
+          value={sortField}
+          order={sortOrder}
+          onChange={onSortChange}
+          onReshuffle={onReshuffle}
+        />
+        {isAdmin && (
+          <>
+            <EpisodeArtworkToggle
+              checked={scrapeEpisodeArtwork}
+              onChange={onScrapeEpisodeArtworkChange}
+              title="关闭后仍会获取主海报和每集文字元数据，只跳过每集图片"
+              className="h-9"
+            />
+            <button onClick={onScan} disabled={scanning} className="btn-outline">
+              {scanning ? '扫描中…' : '扫描媒体库'}
+            </button>
+            <button onClick={onScrape} disabled={scraping} className="btn-outline" title="对整个媒体库执行刮削元数据">
+              {scraping ? '刮削中…' : '整库刮削元数据'}
+            </button>
+            <button
+              onClick={onRepairRescrape}
+              disabled={repairing}
+              className="btn-outline"
+              title="回填本库占位符外部 ID 并重刮，修正空 ID / 拆集问题"
+            >
+              {repairing ? '修复中…' : '修复+重刮整库'}
+            </button>
+          </>
+        )}
+      </div>
     </div>
   )
 }

web/src/pages/LibrarySeriesEpisodes.tsx

@@ -62,40 +62,53 @@ export function LibrarySeriesEpisodes({
         <h3 className="mb-3 font-display text-lg font-semibold text-ink-600">
           {displaySeason === 0 ? '特别篇' : `第 ${displaySeason} 季`}
         </h3>
-        <div className="grid grid-cols-2 gap-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6">
-          {visibleEpisodes.map((ep) => (
-            <div
-              key={ep.id}
-              className="group flex items-center gap-3 rounded-xl border border-sand-200 bg-white p-3 shadow-card transition-all hover:border-brand-300 hover:shadow-card-hover"
-            >
-              <Link to={`/play/${ep.id}`} state={{ from: playbackFrom }} className="flex min-w-0 flex-1 items-center gap-3">
-                <div className="flex h-10 w-10 shrink-0 items-center justify-center overflow-hidden rounded-xl bg-brand-50 text-brand-600 font-semibold text-sm">
-                  {ep.backdrop_url || ep.poster_url ? (
-                    <img
-                      src={imageURL(ep.backdrop_url || ep.poster_url || '', ep.updated_at)}
-                      alt=""
-                      className="h-full w-full object-cover"
-                      referrerPolicy="no-referrer"
-                    />
-                  ) : (
-                    ep.episode_num || '—'
-                  )}
-                </div>
-                <div className="min-w-0 flex-1">
-                  <p className="truncate text-sm font-medium text-ink-600">
-                    {episodeDisplayTitle(ep, visibleEpisodes)}
-                  </p>
-                  <p className="text-xs text-sand-500">
-                    {ep.duration_sec > 0
-                      ? `${Math.floor(ep.duration_sec / 60)} 分钟`
-                      : formatSize(ep.size_bytes)}
-                  </p>
-                </div>
-                <Play size={14} className="shrink-0 text-gray-500 opacity-0 transition-opacity group-hover:opacity-100 group-hover:text-brand-500" />
-              </Link>
-              <ExternalPlayerButton mediaId={ep.id} label="外部" compact />
-            </div>
-          ))}
+        <div className="grid grid-cols-1 gap-2.5 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-5">
+          {visibleEpisodes.map((ep) => {
+            const displayTitle = episodeDisplayTitle(ep, visibleEpisodes)
+            return (
+              <div
+                key={ep.id}
+                className="group flex items-center justify-between gap-3 rounded-xl border border-sand-200 bg-white p-2.5 shadow-card transition-all hover:border-brand-300 hover:shadow-card-hover"
+              >
+                <Link to={`/play/${ep.id}`} state={{ from: playbackFrom }} className="flex min-w-0 flex-1 items-center gap-3">
+                  <div
+                    className="relative flex h-11 w-16 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-brand-50/70 border border-sand-200/60"
+                    title={displayTitle}
+                  >
+                    {ep.backdrop_url || ep.poster_url ? (
+                      <img
+                        src={imageURL(ep.backdrop_url || ep.poster_url || '', ep.updated_at)}
+                        alt=""
+                        className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
+                        referrerPolicy="no-referrer"
+                      />
+                    ) : (
+                      <span className="text-brand-600 font-bold text-sm">{ep.episode_num || '—'}</span>
+                    )}
+                    <div className="absolute inset-0 flex items-center justify-center bg-black/25 opacity-0 transition-opacity duration-200 group-hover:opacity-100">
+                      <Play size={15} className="fill-white text-white drop-shadow-sm" />
+                    </div>
+                    {ep.episode_num > 0 && (
+                      <span className="absolute bottom-0 right-0 rounded-tl bg-black/75 px-1 py-0.5 text-[9px] font-bold leading-none text-white backdrop-blur-[2px]">
+                        {ep.episode_num}
+                      </span>
+                    )}
+                  </div>
+                  <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-medium text-ink-600 transition-colors group-hover:text-brand-600" title={displayTitle}>
+                      {displayTitle}
+                    </p>
+                    <p className="text-xs text-sand-500 whitespace-nowrap">
+                      {ep.duration_sec > 0
+                        ? `${Math.floor(ep.duration_sec / 60)} 分钟`
+                        : formatSize(ep.size_bytes)}
+                    </p>
+                  </div>
+                </Link>
+                <ExternalPlayerButton mediaId={ep.id} label="外部" compact />
+              </div>
+            )
+          })}
         </div>
       </div>
     </>
@@ -103,17 +116,29 @@ export function LibrarySeriesEpisodes({
 }
 
 function episodeDisplayTitle(ep: Media, siblings: Media[]): string {
-  const title = ep.episode_title?.trim()
-  if (title && !looksLikeSeriesTitle(ep, title, siblings)) {
-    return title
+  let mainTitle = ''
+  const epTitle = ep.episode_title?.trim()
+  if (epTitle && !looksLikeSeriesTitle(ep, epTitle, siblings)) {
+    mainTitle = epTitle
+  } else {
+    const mediaTitle = ep.title?.trim()
+    if (mediaTitle && !looksLikeSeriesTitle(ep, mediaTitle, siblings)) {
+      mainTitle = mediaTitle
+    }
   }
 
-  const mediaTitle = ep.title?.trim()
-  if (mediaTitle && !looksLikeSeriesTitle(ep, mediaTitle, siblings)) {
-    return mediaTitle
+  if (ep.episode_num > 0) {
+    if (!mainTitle) {
+      return `第 ${ep.episode_num} 集`
+    }
+    const prefixRegex = new RegExp(`^(第\\s*0*${ep.episode_num}\\s*集|ep?\\.?\\s*0*${ep.episode_num}\\b)`, 'i')
+    if (prefixRegex.test(mainTitle)) {
+      return mainTitle
+    }
+    return `第 ${ep.episode_num} 集 · ${mainTitle}`
   }
 
-  return ep.episode_num > 0 ? `第 ${ep.episode_num} 集` : mediaTitle || title || '未命名'
+  return mainTitle || '未命名'
 }
 
 function looksLikeSeriesTitle(ep: Media, title: string, siblings: Media[]): boolean {

web/src/pages/PlayerPage.tsx

@@ -1,20 +1,21 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useLocation, useNavigate, useParams, useSearchParams } from 'react-router-dom'
 import type Hls from 'hls.js'
 import toast from 'react-hot-toast'
 
-import { mediaAPI } from '../api/library'
+import { mediaAPI, libraryAPI } from '../api/library'
 import { api, hlsURL, streamURL } from '../api/client'
 import { danmakuAPI, type DanmakuAnime, type DanmakuLoadedInfo } from '../api/danmaku'
 import { playbackAPI } from '../api/playback'
 import { subtitlesAPI, type SubtitleTrack } from '../api/subtitles'
 import { systemAPI } from '../api/system'
 import type { Media } from '../types'
-import { getSeriesKey, isEpisodeLike } from '../utils/groupSeries'
+import { getSeriesKey, isEpisodeLike, seriesTitleFromPath } from '../utils/groupSeries'
 import { pickPlayerMode, needsTranscodeForBrowser, type PlayerMode } from './playerPageModel'
 import { PlayerTopBar } from './PlayerTopBar'
 import { PlayerVideoStage } from './PlayerVideoStage'
 import { PlayerDanmakuPanel } from '../components/PlayerDanmakuPanel'
+import { PlayerPlaylistPanel } from '../components/PlayerPlaylistPanel'
 
 // Fullscreen, dark-themed video page.
 //
@@ -80,6 +81,10 @@ export function PlayerPage() {
   const [danmakuFontSize, setDanmakuFontSize] = useState(24)
   const [danmakuArea, setDanmakuArea] = useState(1)
 
+  // 选集 / 播放列表状态
+  const [playlistEpisodes, setPlaylistEpisodes] = useState<Media[]>([])
+  const [playlistOpen, setPlaylistOpen] = useState(false)
+
   const teardownHls = useCallback((mediaId?: string, stopServer = false) => {
     if (hlsRef.current) {
       hlsRef.current.destroy()
@@ -272,14 +277,160 @@ export function PlayerPage() {
     }
   }, [media])
 
-  // ESC = back.
+  // 加载剧集/播放列表
+  useEffect(() => {
+    if (!id) return
+    let canceled = false
+    mediaAPI
+      .getEpisodes(id)
+      .then((res) => {
+        if (canceled) return
+        setPlaylistEpisodes(res.items ?? [])
+      })
+      .catch(() => {
+        if (canceled) return
+        if (media && (media.display_library_id || media.library_id)) {
+          const libId = media.display_library_id || media.library_id
+          const seriesKey = getSeriesKey(media)
+          if (seriesKey) {
+            libraryAPI
+              .listSeriesEpisodes(libId, seriesKey)
+              .then((res) => {
+                if (!canceled) setPlaylistEpisodes(res.items ?? [])
+              })
+              .catch(() => {
+                if (!canceled) setPlaylistEpisodes([])
+              })
+            return
+          }
+        }
+        setPlaylistEpisodes([])
+      })
+    return () => {
+      canceled = true
+    }
+  }, [id, media])
+
+  const currentEpisodeIndex = useMemo(() => {
+    if (!media || playlistEpisodes.length === 0) return -1
+    return playlistEpisodes.findIndex((e) => e.id === media.id)
+  }, [media, playlistEpisodes])
+
+  const prevEpisode = useMemo(() => {
+    if (currentEpisodeIndex > 0) {
+      return playlistEpisodes[currentEpisodeIndex - 1]
+    }
+    return null
+  }, [currentEpisodeIndex, playlistEpisodes])
+
+  const nextEpisode = useMemo(() => {
+    if (currentEpisodeIndex >= 0 && currentEpisodeIndex < playlistEpisodes.length - 1) {
+      return playlistEpisodes[currentEpisodeIndex + 1]
+    }
+    return null
+  }, [currentEpisodeIndex, playlistEpisodes])
+
+  const prevEpisodeTitle = useMemo(() => {
+    return prevEpisode ? formatEpisodeDisplay(prevEpisode, playlistEpisodes) : ''
+  }, [prevEpisode, playlistEpisodes])
+
+  const nextEpisodeTitle = useMemo(() => {
+    return nextEpisode ? formatEpisodeDisplay(nextEpisode, playlistEpisodes) : ''
+  }, [nextEpisode, playlistEpisodes])
+
+  const playEpisode = useCallback(
+    (target: Media) => {
+      navigate(
+        {
+          pathname: `/play/${target.id}`,
+          search: location.search,
+        },
+        { state: location.state },
+      )
+    },
+    [navigate, location.search, location.state],
+  )
+
+  const handlePrevEpisode = useCallback(() => {
+    if (prevEpisode) {
+      playEpisode(prevEpisode)
+    }
+  }, [prevEpisode, playEpisode])
+
+  const handleNextEpisode = useCallback(() => {
+    if (nextEpisode) {
+      playEpisode(nextEpisode)
+    }
+  }, [nextEpisode, playEpisode])
+
+  const togglePlaylistOpen = useCallback(() => {
+    setPlaylistOpen((prev) => {
+      const next = !prev
+      if (next) setDanmakuOpen(false)
+      return next
+    })
+  }, [])
+
+  const toggleDanmakuOpen = useCallback(() => {
+    setDanmakuOpen((prev) => {
+      const next = !prev
+      if (next) setPlaylistOpen(false)
+      return next
+    })
+  }, [])
+
+  // 视频播放结束时自动播放下一集
+  useEffect(() => {
+    if (!ref.current || !nextEpisode) return
+    const video = ref.current
+    const onEnded = () => {
+      toast.success(`正在播放下一集：${nextEpisodeTitle || '下一集'}`)
+      playEpisode(nextEpisode)
+    }
+    video.addEventListener('ended', onEnded)
+    return () => {
+      video.removeEventListener('ended', onEnded)
+    }
+  }, [nextEpisode, nextEpisodeTitle, playEpisode])
+
+  // ESC = back 或关闭浮层，[ / ] 或 Shift+P / Shift+N 切换上一集/下一集
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') goBack()
+      const target = e.target as HTMLElement | null
+      if (
+        target &&
+        (target.tagName === 'INPUT' ||
+          target.tagName === 'TEXTAREA' ||
+          target.isContentEditable)
+      ) {
+        return
+      }
+
+      if (e.key === 'Escape') {
+        if (playlistOpen) {
+          setPlaylistOpen(false)
+          return
+        }
+        if (danmakuOpen) {
+          setDanmakuOpen(false)
+          return
+        }
+        goBack()
+      } else if (e.key === '[' || (e.shiftKey && e.key.toLowerCase() === 'p')) {
+        if (prevEpisode) {
+          e.preventDefault()
+          handlePrevEpisode()
+        }
+      } else if (e.key === ']' || (e.shiftKey && e.key.toLowerCase() === 'n')) {
+        if (nextEpisode) {
+          e.preventDefault()
+          handleNextEpisode()
+        }
+      }
     }
     window.addEventListener('keydown', onKey)
     return () => window.removeEventListener('keydown', onKey)
-  }, [goBack])
+  }, [goBack, prevEpisode, nextEpisode, handlePrevEpisode, handleNextEpisode, playlistOpen, danmakuOpen])
 
   const toggleMode = useCallback(() => {
     const next = mode === 'hls' ? 'direct' : 'hls'
@@ -344,9 +495,27 @@ export function PlayerPage() {
         danmakuSearch={danmakuSearch}
         danmakuEpisodeId={danmakuEpisodeId}
         danmakuOpen={danmakuOpen}
-        onToggleDanmaku={() => setDanmakuOpen((v) => !v)}
+        onToggleDanmaku={toggleDanmakuOpen}
         onDanmakuLoaded={danmakuLoaded}
         onDanmakuCandidates={danmakuGotCandidates}
+        hasPrevEpisode={Boolean(prevEpisode)}
+        hasNextEpisode={Boolean(nextEpisode)}
+        onPrevEpisode={handlePrevEpisode}
+        onNextEpisode={handleNextEpisode}
+        prevEpisodeTitle={prevEpisodeTitle}
+        nextEpisodeTitle={nextEpisodeTitle}
+        playlistOpen={playlistOpen}
+        hasPlaylist={playlistEpisodes.length > 0}
+        onTogglePlaylist={togglePlaylistOpen}
+        playlistPanel={
+          <PlayerPlaylistPanel
+            open={playlistOpen}
+            onClose={() => setPlaylistOpen(false)}
+            currentMediaId={media?.id ?? ''}
+            episodes={playlistEpisodes}
+            onSelectEpisode={playEpisode}
+          />
+        }
         danmakuPanel={
           <PlayerDanmakuPanel
             open={danmakuOpen}
@@ -373,3 +542,41 @@ export function PlayerPage() {
     </div>
   )
 }
+
+function formatEpisodeDisplay(ep: Media, siblings: Media[]): string {
+  const title = ep.episode_title?.trim()
+  if (title && !looksLikeSeriesTitle(ep, title, siblings)) {
+    return title
+  }
+
+  const mediaTitle = ep.title?.trim()
+  if (mediaTitle && !looksLikeSeriesTitle(ep, mediaTitle, siblings)) {
+    return mediaTitle
+  }
+
+  return ep.episode_num > 0 ? `第 ${ep.episode_num} 集` : mediaTitle || title || '未命名'
+}
+
+function looksLikeSeriesTitle(ep: Media, title: string, siblings: Media[]): boolean {
+  const normalized = normalizeEpisodeTitle(title)
+  if (!normalized) return true
+  if (ep.original_name && normalizeEpisodeTitle(ep.original_name) === normalized) return true
+  const pathTitle = seriesTitleFromPath(ep.path)
+  if (pathTitle && normalizeEpisodeTitle(pathTitle) === normalized) return true
+
+  const siblingTitles = new Set(
+    siblings
+      .map((item) => normalizeEpisodeTitle(item.title))
+      .filter(Boolean),
+  )
+  return siblingTitles.size === 1 && siblingTitles.has(normalized) && siblings.length > 1
+}
+
+function normalizeEpisodeTitle(value?: string): string {
+  return (value ?? '')
+    .toLowerCase()
+    .replace(/\s*\((?:19|20)\d{2}\)\s*/g, ' ')
+    .replace(/\s*\{(?:tmdb|tmdbid|douban|bangumi|bgm|thetvdb|tvdb)[\s:=#-]*[a-z0-9_-]+\}\s*/g, ' ')
+    .replace(/[\s._-]+/g, ' ')
+    .trim()
+}

web/src/pages/PlayerVideoStage.tsx

@@ -28,6 +28,17 @@ type PlayerVideoStageProps = {
   onDanmakuCandidates: (candidates: DanmakuAnime[]) => void
   /** Danmaku settings panel; rendered inside the stage so it stays visible in fullscreen. */
   danmakuPanel: ReactNode
+  /** Playlist drawer / panel; rendered inside the stage so it stays visible in fullscreen. */
+  playlistPanel?: ReactNode
+  hasPrevEpisode?: boolean
+  hasNextEpisode?: boolean
+  onPrevEpisode?: () => void
+  onNextEpisode?: () => void
+  prevEpisodeTitle?: string
+  nextEpisodeTitle?: string
+  playlistOpen?: boolean
+  hasPlaylist?: boolean
+  onTogglePlaylist?: () => void
 }
 
 export function PlayerVideoStage({
@@ -49,6 +60,16 @@ export function PlayerVideoStage({
   onDanmakuLoaded,
   onDanmakuCandidates,
   danmakuPanel,
+  playlistPanel,
+  hasPrevEpisode,
+  hasNextEpisode,
+  onPrevEpisode,
+  onNextEpisode,
+  prevEpisodeTitle,
+  nextEpisodeTitle,
+  playlistOpen,
+  hasPlaylist,
+  onTogglePlaylist,
 }: PlayerVideoStageProps) {
   const stageRef = useRef<HTMLDivElement>(null)
   const [videoRatio, setVideoRatio] = useState<number | null>(null)
@@ -114,10 +135,11 @@ export function PlayerVideoStage({
       setActiveCueText('')
       return
     }
+    const trackIdx = subtitleIndex
 
     const updateCue = () => {
       const trackEls = Array.from(video.querySelectorAll('track'))
-      const selectedEl = trackEls[subtitleIndex]
+      const selectedEl = trackEls[trackIdx]
       const tt = selectedEl?.track
       if (!tt) {
         setActiveCueText('')
@@ -151,11 +173,11 @@ export function PlayerVideoStage({
         const tt = el.track
         if (tt) {
           // 'hidden' 模式：浏览器解析 WebVTT 并触发 cuechange，但隐藏原生黑底 UI
-          tt.mode = i === subtitleIndex ? 'hidden' : 'disabled'
+          tt.mode = i === trackIdx ? 'hidden' : 'disabled'
         }
       })
 
-      const selected = trackEls[subtitleIndex]
+      const selected = trackEls[trackIdx]
       if (!selected) return
 
       const tt = selected.track
@@ -184,7 +206,7 @@ export function PlayerVideoStage({
       video.removeEventListener('seeked', updateCue)
       video.removeEventListener('playing', updateCue)
       const trackEls = Array.from(video.querySelectorAll('track'))
-      const selected = trackEls[subtitleIndex]
+      const selected = trackEls[trackIdx]
       if (selected) {
         selected.removeEventListener('load', updateCue)
         if (selected.track) {
@@ -241,7 +263,7 @@ export function PlayerVideoStage({
                   src={subtitlesAPI.url(media.id, track.path)}
                   srcLang={track.lang}
                   label={track.label || track.lang}
-                  default={index === subtitleIndex}
+                  default={subtitleIndex === index}
                 />
               ))}
             </video>
@@ -282,8 +304,18 @@ export function PlayerVideoStage({
             danmakuOpen={danmakuOpen}
             danmakuEnabled={danmakuEnabled}
             onToggleDanmaku={onToggleDanmaku}
+            hasPrevEpisode={hasPrevEpisode}
+            hasNextEpisode={hasNextEpisode}
+            onPrevEpisode={onPrevEpisode}
+            onNextEpisode={onNextEpisode}
+            prevEpisodeTitle={prevEpisodeTitle}
+            nextEpisodeTitle={nextEpisodeTitle}
+            playlistOpen={playlistOpen}
+            hasPlaylist={hasPlaylist}
+            onTogglePlaylist={onTogglePlaylist}
           />
           {danmakuPanel}
+          {playlistPanel}
         </>
       ) : (
         <p className="text-sand-500">加载中…</p>

web/src/pages/SettingsPage.tsx

@@ -7,6 +7,7 @@ import { adminAPI } from '../api/admin'
 import { libraryAPI } from '../api/library'
 import type { Library, Setting } from '../types'
 import { APIConfigsPanel } from '../components/APIConfigsPanel'
+import { FFToolsPanel } from '../components/FFToolsPanel'
 import { AdultSettingsPanel } from './AdultSettingsPanel'
 import { DatabaseSettingsPanel } from './DatabaseSettingsPanel'
 import { RecognitionWordsPanel } from './RecognitionWordsPanel'
@@ -172,6 +173,7 @@ export function SettingsPage() {
           {group.key === 'api-configs' && <APIConfigsPanel />}
           {group.key === 'recognition-words' && <RecognitionWordsPanel />}
           {group.key === 'adult' && <AdultSettingsPanel />}
+          {group.key === 'general' && <FFToolsPanel onInstalled={() => refresh().catch(() => undefined)} />}
           {group.key !== 'adult' && group.key !== 'library' && group.items.length > 0 && (
             <form onSubmit={onSave} className="glass-panel space-y-4">
               {group.description && <p className="text-xs text-sand-500">{group.description}</p>}

web/src/pages/settingsGroupGeneral.ts

@@ -83,12 +83,14 @@ export const generalSettingsGroup: SettingGroup = {
       label: 'FFmpeg 路径',
       type: 'text',
       placeholder: 'ffmpeg',
+      hint: '留空时使用系统 PATH 中的 ffmpeg；也可点击上方「下载并安装」自动下载到 data 目录并自动填入，无需手动填写',
     },
     {
       key: 'ffprobe.path',
       label: 'FFprobe 路径',
       type: 'text',
       placeholder: 'ffprobe',
+      hint: '留空时使用系统 PATH 中的 ffprobe；也可点击上方「下载并安装」自动下载到 data 目录并自动填入',
     },
     {
       key: 'ffprobe.max_concurrent',

web/src/pages/useLibraryAdminActions.tsx

@@ -73,8 +73,9 @@ export function useLibraryAdminActions({
       toast.success(`${label}完成：${selectedSeriesEpisodes.length} 个媒体`)
       reloadCurrentLibrary()
     } catch (err: unknown) {
-      const msg = (err as { response?: { data?: { error?: string } } })?.response?.data?.error || `${label}失败`
-      toast.error(msg)
+      const serverErr = (err as { response?: { data?: { error?: string } } })?.response?.data?.error
+      const msg = serverErr || (err instanceof Error ? err.message : '')
+      toast.error(msg ? `${label}失败：${msg}` : `${label}失败`)
     } finally {
       setSeriesToolBusy('')
     }
@@ -146,8 +147,9 @@ export function useLibraryAdminActions({
       toast.success(`${label}完成：${media.title}`)
       reloadCurrentLibrary()
     } catch (err: unknown) {
-      const msg = (err as { response?: { data?: { error?: string } } })?.response?.data?.error || `${label}失败`
-      toast.error(msg)
+      const serverErr = (err as { response?: { data?: { error?: string } } })?.response?.data?.error
+      const msg = serverErr || (err instanceof Error ? err.message : '')
+      toast.error(msg ? `${label}失败：${msg}` : `${label}失败`)
     } finally {
       setMovieToolBusy('')
     }

web/src/types/auth.ts

@@ -9,6 +9,7 @@ export interface User {
   hide_adult?: boolean
   force_password_reset: boolean
   is_active: boolean
+  allowed_library_ids?: string[]
   is_default_admin?: boolean
   is_protected?: boolean
   realtime_online?: boolean

web/src/utils/mediaSort.ts

@@ -0,0 +1,205 @@
+import type { Media } from '../types'
+import { seriesTitle, type SeriesCard } from './groupSeries'
+
+export type SortField =
+  | 'title'
+  | 'release_date'
+  | 'year'
+  | 'created_at'
+  | 'updated_at'
+  | 'rating'
+  | 'imdb_rating'
+  | 'last_played'
+  | 'duration'
+  | 'bitrate'
+  | 'random'
+
+export type SortOrder = 'asc' | 'desc'
+
+export type SortOption = {
+  id: SortField
+  label: string
+  defaultOrder: SortOrder
+}
+
+export const SORT_OPTIONS: SortOption[] = [
+  { id: 'title', label: '标题', defaultOrder: 'asc' },
+  { id: 'release_date', label: '发行日期', defaultOrder: 'desc' },
+  { id: 'year', label: '年份', defaultOrder: 'desc' },
+  { id: 'created_at', label: '加入日期', defaultOrder: 'desc' },
+  { id: 'updated_at', label: '最后一集添加日期', defaultOrder: 'desc' },
+  { id: 'rating', label: '影评人评分', defaultOrder: 'desc' },
+  { id: 'imdb_rating', label: 'IMDB评分', defaultOrder: 'desc' },
+  { id: 'last_played', label: '播放日期', defaultOrder: 'desc' },
+  { id: 'duration', label: '播放时长', defaultOrder: 'desc' },
+  { id: 'bitrate', label: '比特率', defaultOrder: 'desc' },
+  { id: 'random', label: '随机', defaultOrder: 'desc' },
+]
+
+export function getSortOption(field: SortField): SortOption {
+  return SORT_OPTIONS.find((opt) => opt.id === field) ?? SORT_OPTIONS[0]
+}
+
+// 简单伪随机洗牌（基于 seed 保证同一渲染周期内稳定）
+function pseudoRandomShuffle<T>(array: T[], seed = 1): T[] {
+  const result = [...array]
+  let currentSeed = seed
+  const random = () => {
+    currentSeed = (currentSeed * 9301 + 49297) % 233280
+    return currentSeed / 233280
+  }
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1))
+    const temp = result[i]
+    result[i] = result[j]
+    result[j] = temp
+  }
+  return result
+}
+
+function compareStrings(a?: string, b?: string, order: SortOrder = 'asc'): number {
+  const valA = (a ?? '').trim()
+  const valB = (b ?? '').trim()
+  if (!valA && !valB) return 0
+  if (!valA) return 1
+  if (!valB) return -1
+  const cmp = valA.localeCompare(valB, 'zh-CN', { numeric: true, sensitivity: 'base' })
+  return order === 'asc' ? cmp : -cmp
+}
+
+function compareNumbers(a: number, b: number, order: SortOrder = 'asc'): number {
+  if (isNaN(a) && isNaN(b)) return 0
+  if (isNaN(a)) return 1
+  if (isNaN(b)) return -1
+  return order === 'asc' ? a - b : b - a
+}
+
+function compareDates(a?: string, b?: string, order: SortOrder = 'asc'): number {
+  const timeA = a ? new Date(a).getTime() : 0
+  const timeB = b ? new Date(b).getTime() : 0
+  const safeTimeA = isNaN(timeA) ? 0 : timeA
+  const safeTimeB = isNaN(timeB) ? 0 : timeB
+  if (!safeTimeA && !safeTimeB) return 0
+  if (!safeTimeA) return 1
+  if (!safeTimeB) return -1
+  return order === 'asc' ? safeTimeA - safeTimeB : safeTimeB - safeTimeA
+}
+
+export function sortMediaList(
+  items: Media[],
+  field: SortField,
+  order: SortOrder,
+  randomSeed = 1,
+  historyMap?: Map<string, string>,
+): Media[] {
+  if (!items || items.length === 0) return []
+  if (field === 'random') {
+    return pseudoRandomShuffle(items, randomSeed)
+  }
+
+  const list = [...items]
+  list.sort((a, b) => {
+    switch (field) {
+      case 'title':
+        return compareStrings(a.title || a.original_name, b.title || b.original_name, order)
+      case 'release_date': {
+        const dateA = a.release_date || (a.year ? `${a.year}-01-01` : '')
+        const dateB = b.release_date || (b.year ? `${b.year}-01-01` : '')
+        return compareDates(dateA, dateB, order) || compareStrings(a.title, b.title, 'asc')
+      }
+      case 'year': {
+        const cmp = compareNumbers(a.year || 0, b.year || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(a.title, b.title, 'asc')
+      }
+      case 'created_at':
+        return compareDates(a.created_at, b.created_at, order) || compareStrings(a.title, b.title, 'asc')
+      case 'updated_at':
+        return compareDates(a.updated_at || a.created_at, b.updated_at || b.created_at, order) || compareStrings(a.title, b.title, 'asc')
+      case 'rating':
+      case 'imdb_rating': {
+        const cmp = compareNumbers(a.rating || 0, b.rating || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(a.title, b.title, 'asc')
+      }
+      case 'last_played': {
+        const playedA = historyMap?.get(a.id)
+        const playedB = historyMap?.get(b.id)
+        return compareDates(playedA, playedB, order) || compareStrings(a.title, b.title, 'asc')
+      }
+      case 'duration': {
+        const cmp = compareNumbers(a.duration_sec || 0, b.duration_sec || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(a.title, b.title, 'asc')
+      }
+      case 'bitrate': {
+        // 比特率 / 大小
+        const cmp = compareNumbers(a.size_bytes || 0, b.size_bytes || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(a.title, b.title, 'asc')
+      }
+      default:
+        return 0
+    }
+  })
+  return list
+}
+
+export function sortSeriesList(
+  cards: SeriesCard[],
+  field: SortField,
+  order: SortOrder,
+  randomSeed = 1,
+  historyMap?: Map<string, string>,
+): SeriesCard[] {
+  if (!cards || cards.length === 0) return []
+  if (field === 'random') {
+    return pseudoRandomShuffle(cards, randomSeed)
+  }
+
+  const list = [...cards]
+  list.sort((a, b) => {
+    const repA = a.rep
+    const repB = b.rep
+    const titleA = seriesTitle(repA)
+    const titleB = seriesTitle(repB)
+
+    switch (field) {
+      case 'title':
+        return compareStrings(titleA, titleB, order)
+      case 'release_date': {
+        const dateA = repA.release_date || (repA.year ? `${repA.year}-01-01` : '')
+        const dateB = repB.release_date || (repB.year ? `${repB.year}-01-01` : '')
+        return compareDates(dateA, dateB, order) || compareStrings(titleA, titleB, 'asc')
+      }
+      case 'year': {
+        const cmp = compareNumbers(repA.year || 0, repB.year || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(titleA, titleB, 'asc')
+      }
+      case 'created_at':
+        return compareDates(repA.created_at, repB.created_at, order) || compareStrings(titleA, titleB, 'asc')
+      case 'updated_at': {
+        const updateA = repA.updated_at || repA.created_at
+        const updateB = repB.updated_at || repB.created_at
+        return compareDates(updateA, updateB, order) || compareStrings(titleA, titleB, 'asc')
+      }
+      case 'rating':
+      case 'imdb_rating': {
+        const cmp = compareNumbers(repA.rating || 0, repB.rating || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(titleA, titleB, 'asc')
+      }
+      case 'last_played': {
+        const playedA = historyMap?.get(repA.id)
+        const playedB = historyMap?.get(repB.id)
+        return compareDates(playedA, playedB, order) || compareStrings(titleA, titleB, 'asc')
+      }
+      case 'duration': {
+        const cmp = compareNumbers(repA.duration_sec || 0, repB.duration_sec || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(titleA, titleB, 'asc')
+      }
+      case 'bitrate': {
+        const cmp = compareNumbers(repA.size_bytes || 0, repB.size_bytes || 0, order)
+        return cmp !== 0 ? cmp : compareStrings(titleA, titleB, 'asc')
+      }
+      default:
+        return 0
+    }
+  })
+  return list
+}