优化

方向键调整进度/音量时，若控制栏隐藏则保持隐藏，若可见则只刷新自动隐藏计时器，避免连续按键中途消失。

cmd/server/application.go

@@ -113,6 +113,14 @@ func (a *application) start() error {
 		a.logger.Info("polluted episode metadata cleanup completed", zap.Int("media_count", cleaned))
 	}
 
+	// 一次性删除旧版解析误写的「整集片头/回顾」区间（end_ms <= start_ms），
+	// 否则升级后播放器仍会一开播就弹跳过按钮。
+	if cleaned, err := a.services.NormalizeImpossibleSegments(context.Background()); err != nil {
+		a.logger.Warn("impossible skip segment cleanup failed", zap.Error(err))
+	} else if cleaned > 0 {
+		a.logger.Info("impossible skip segments removed", zap.Int("rows", cleaned))
+	}
+
 	if err := a.services.Auth.SeedAdmin(context.Background()); err != nil {
 		a.logger.Warn("seed admin failed", zap.Error(err))
 	}

internal/config/defaults.go

@@ -45,14 +45,13 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("logging.max_backups", 10)
 
 	v.SetDefault("cache.cache_dir", "./cache")
-	v.SetDefault("cache.images_max_size_mb", 2000)
+	v.SetDefault("cache.images_max_size_mb", 2048)
 	v.SetDefault("cache.images_originals_max_size_mb", 256)
-	v.SetDefault("cache.images_originals_ttl_hours", 168)
 	v.SetDefault("cache.memory_max_size_mb", DefaultCacheMemoryMaxSizeMB)
 	v.SetDefault("cache.redis_url", "")
 	v.SetDefault("cache.redis_prefix", "mebox")
 	v.SetDefault("cache.media_ttl_seconds", 90)
-	v.SetDefault("cache.emby_latest_ttl_seconds", 300)
+	v.SetDefault("cache.emby_latest_ttl_seconds", 900)
 	v.SetDefault("cache.reader_content_max_size_mb", 1024)
 	v.SetDefault("cache.reader_content_ttl_hours", 168)
 	v.SetDefault("cache.reader_files_ttl_hours", 720)

internal/config/normalize.go

@@ -50,9 +50,6 @@ func (c *Config) normalize() error {
 	if c.Cache.ImagesOriginalsMaxSizeMB < 0 {
 		c.Cache.ImagesOriginalsMaxSizeMB = 0
 	}
-	if c.Cache.ImagesOriginalsTTLHours < 0 {
-		c.Cache.ImagesOriginalsTTLHours = 0
-	}
 	if c.Cache.MemoryMaxSizeMB <= 0 {
 		c.Cache.MemoryMaxSizeMB = DefaultCacheMemoryMaxSizeMB
 	}

internal/config/types.go

@@ -120,14 +120,16 @@ type LoggingConfig struct {
 
 // CacheConfig 控制磁盘转写缓存和进程内热缓存。
 type CacheConfig struct {
-	CacheDir        string `mapstructure:"cache_dir"`
-	ImagesMaxSizeMB int    `mapstructure:"images_max_size_mb"`
+	CacheDir string `mapstructure:"cache_dir"`
+	// ImagesMaxSizeMB 是整个磁盘缓存的总容量上限（MB），不是 images 子目录
+	// 的配额。参与统计的池为 hls、images、library-covers；超限时按该顺序淘汰
+	// 最旧文件。reader-audio 不在其中：它按 reader.audioMediaMaxBytes 的固定
+	// 配额（当前 1GiB）在写入时独立淘汰，不参与这里的总量。
+	// 0 表示不限制。
+	ImagesMaxSizeMB int `mapstructure:"images_max_size_mb"`
 	// ImagesOriginalsMaxSizeMB 限制 cache/images 下原图子配额（MB）。原图只是
 	// 生成缩略图的原料，丢了可以重新回源；0 表示不单独限制（只受总量约束）。
 	ImagesOriginalsMaxSizeMB int `mapstructure:"images_originals_max_size_mb"`
-	// ImagesOriginalsTTLHours 是原图的保留时长（小时），超过即删除；0 表示
-	// 不按时间淘汰。缩短它能让原图缓存保持在一个滚动窗口内。
-	ImagesOriginalsTTLHours int `mapstructure:"images_originals_ttl_hours"`
 	// MemoryMaxSizeMB 限制进程内 L1 缓存总字节数，JSON/对象缓存共用该预算。
 	MemoryMaxSizeMB int    `mapstructure:"memory_max_size_mb"`
 	RedisURL        string `mapstructure:"redis_url"`
@@ -136,7 +138,8 @@ type CacheConfig struct {
 	// EmbyLatestTTLSeconds 是 Emby「最新添加」(Items/Latest) 的缓存时长。
 	// 客户端刷新首页时会并发请求全部媒体库的 Latest（生产环境观察到 73 个
 	// 并发），缓存过短会让这批请求同时穿透并各自重建 payload，在低配主机
-	// 上造成秒级延迟。默认 300 秒，新入库内容最迟 5 分钟后出现在最新列表。
+	// 上造成秒级延迟。默认 900 秒；过期后仍会先返回陈旧副本并在后台重建，
+	// 新入库内容最迟 15 分钟后出现在最新列表（扫描完成会主动失效缓存）。
 	EmbyLatestTTLSeconds int `mapstructure:"emby_latest_ttl_seconds"`
 	// ReaderContentMaxSizeMB 阅读正文持久缓存的总容量（MB），0 表示不限制。
 	ReaderContentMaxSizeMB int `mapstructure:"reader_content_max_size_mb"`

internal/database/schema_migration.go

@@ -376,6 +376,11 @@ func ensurePerformanceIndexes(db *gorm.DB) error {
 		`DROP INDEX IF EXISTS idx_media_library_release_active`,
 		`CREATE INDEX IF NOT EXISTS idx_media_library_created_active ON media(library_id, created_at DESC) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_media_library_episode_active ON media(library_id, season_num, episode_num, created_at DESC) WHERE deleted_at IS NULL`,
+		// 虚拟剧集分组索引：series_id 为空的剧集行要按
+		// (season_num, episode_num, episode_fraction, created_at) 排序后做内存
+		// 分组。没有它 SQLite 只能全表扫描再建临时 B-tree，而 Emby 的
+		// 卡片/海报查询每次只关心其中一部剧（生产环境实测单次 1.3s）。
+		`CREATE INDEX IF NOT EXISTS idx_media_virtual_series_group ON media(season_num, episode_num, episode_fraction, created_at) WHERE deleted_at IS NULL AND (series_id IS NULL OR series_id = '')`,
 		`CREATE INDEX IF NOT EXISTS idx_media_library_root_active ON media(library_id, library_root_id) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_media_series_active ON media(series_id, season_num, episode_num) WHERE deleted_at IS NULL`,
 		`CREATE INDEX IF NOT EXISTS idx_media_library_series_active ON media(library_id, series_id, season_num, episode_num) WHERE deleted_at IS NULL`,

internal/handler/admin_settings.go

@@ -87,9 +87,9 @@ func updateSettingHandler(svc *service.Container) gin.HandlerFunc {
 		if req.Key == "transcode.hw_enabled" || req.Key == "transcode.hw_accel" || req.Key == "transcoder.hardware_accel" || req.Key == "transcoder.encoder" {
 			svc.Transcoder.StopAll()
 		}
-		if req.Key == "cache.images_max_size_mb" || req.Key == "cache.images_originals_max_size_mb" || req.Key == "cache.images_originals_ttl_hours" {
+		if req.Key == "cache.images_max_size_mb" || req.Key == "cache.images_originals_max_size_mb" {
 			if svc.Scheduler != nil {
-				_ = svc.Scheduler.RunNowAsync(c.Request.Context(), "image_cache_cleanup")
+				_ = svc.Scheduler.RunNowAsync(c.Request.Context(), "cache_cleanup")
 			}
 		}
 		if req.Key == "cache.memory_max_size_mb" && svc.Cache != nil {

internal/handler/emby_home_compat_test.go

@@ -0,0 +1,113 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 客户端刷新首页时会用 IncludeItemTypes=Movie,Series,Video 一次取「最新」行。
+// 电影库必须返回电影，而不是因为请求里带了 Series 就整行判空。
+func TestEmbyItemsMixedTypesKeepsMoviesInMovieLibrary(t *testing.T) {
+	router, svc, _ := newEmbyDiscoveryEnv(t)
+	if err := svc.Repo.DB.AutoMigrate(&model.Series{}, &model.PlayProfile{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	libID := seedEmbyLibrary(t, svc, "movie")
+	if err := svc.Repo.DB.WithContext(context.Background()).Create(&model.Media{
+		Base:        model.Base{ID: "movie-1"},
+		LibraryID:   libID,
+		Title:       "Movie One",
+		Path:        "/media/movie/one.mp4",
+		Year:        2024,
+		ReleaseDate: "2024-01-01",
+	}).Error; err != nil {
+		t.Fatalf("create movie: %v", err)
+	}
+
+	path := "/emby/Items?ParentId=" + libID +
+		"&IncludeItemTypes=Movie,Series,Video&Recursive=true" +
+		"&SortBy=DateCreated,SortName&SortOrder=Descending&Limit=12&StartIndex=0"
+	w := embyGet(t, router, path, signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", w.Code, w.Body.String())
+	}
+
+	items := decodeItemsEnvelope(t, w.Body.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("expected the movie to be returned, got %d items: %s", len(items), w.Body.String())
+	}
+	if items[0]["Id"] != "movie-1" || items[0]["Type"] != "Movie" {
+		t.Fatalf("unexpected item payload: %#v", items[0])
+	}
+}
+
+// 同一组混合类型在剧集库上仍要折叠成剧集卡片，修复不能把这条路径弄回单集。
+func TestEmbyItemsMixedTypesKeepsSeriesCardsInTvLibrary(t *testing.T) {
+	router, svc, _ := newEmbyDiscoveryEnv(t)
+	if err := svc.Repo.DB.AutoMigrate(&model.Series{}, &model.PlayProfile{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	libID := seedEmbyLibrary(t, svc, "tv")
+	for _, ep := range []struct {
+		id   string
+		num  int
+		path string
+	}{
+		{id: "ep-1", num: 1, path: "/media/tv/show/S01E01.mkv"},
+		{id: "ep-2", num: 2, path: "/media/tv/show/S01E02.mkv"},
+	} {
+		if err := svc.Repo.DB.WithContext(context.Background()).Create(&model.Media{
+			Base:       model.Base{ID: ep.id},
+			LibraryID:  libID,
+			SeriesID:   "series-1",
+			Title:      "Show",
+			Path:       ep.path,
+			SeasonNum:  1,
+			EpisodeNum: ep.num,
+			Year:       2024,
+		}).Error; err != nil {
+			t.Fatalf("create episode: %v", err)
+		}
+	}
+
+	path := "/emby/Items?ParentId=" + libID +
+		"&IncludeItemTypes=Movie,Series,Video&Recursive=true" +
+		"&SortBy=DateCreated,SortName&SortOrder=Descending&Limit=12&StartIndex=0"
+	w := embyGet(t, router, path, signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", w.Code, w.Body.String())
+	}
+
+	items := decodeItemsEnvelope(t, w.Body.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("expected one series card, got %d items: %s", len(items), w.Body.String())
+	}
+	if items[0]["Type"] != "Series" {
+		t.Fatalf("expected Series card, got %#v", items[0])
+	}
+}
+
+// Emby 的 SpecialFeatures 响应是 BaseItemDto[]，客户端按 List 强转；
+// 返回 {"Items":[]} 会直接抛 type cast 异常。
+func TestEmbySpecialFeaturesReturnsBareArray(t *testing.T) {
+	router, _, _ := newEmbyDiscoveryEnv(t)
+	w := embyGet(t, router, "/emby/Items/movie-1/SpecialFeatures", signedTestToken(t, "test-secret"))
+	if w.Code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", w.Code, w.Body.String())
+	}
+	if trimmed := bytes.TrimSpace(w.Body.Bytes()); len(trimmed) == 0 || trimmed[0] != '[' {
+		t.Fatalf("SpecialFeatures must be a JSON array, got %s", w.Body.String())
+	}
+	var items []any
+	if err := json.Unmarshal(w.Body.Bytes(), &items); err != nil {
+		t.Fatalf("decode array: %v body=%s", err, w.Body.String())
+	}
+	if len(items) != 0 {
+		t.Fatalf("expected empty array, got %d entries", len(items))
+	}
+}

internal/handler/emby_images.go

@@ -50,6 +50,25 @@ func embyServeImage(c *gin.Context, svc *service.Container, id, imageType, tag s
 		embyServePlaceholderImage(c)
 		return
 	}
+	// 媒体库主图：按 Emby 的做法，用库内几张成员海报拼一张封面（folder
+	// image）。没有自定义封面时才生成；自定义封面继续走下面的代理路径。
+	if svc.ImageProxy != nil && strings.EqualFold(strings.TrimSpace(imageType), "Primary") {
+		if sources, lib := service.LibraryCoverSourcesForLibrary(ctx, svc.Repo, id); lib != nil &&
+			strings.TrimSpace(lib.CoverURL) == "" && len(sources) > 0 {
+			width, height := libraryCoverRequestSize(c)
+			if data, err := svc.ImageProxy.LibraryCoverImage(ctx, id, sources, width, height); err == nil && len(data) > 0 {
+				c.Header("Cache-Control", "public, max-age=300, stale-while-revalidate=86400")
+				c.Header("Content-Type", "image/jpeg")
+				c.Header("Content-Length", strconv.Itoa(len(data)))
+				if c.Request.Method == http.MethodHead {
+					c.Status(http.StatusOK)
+					return
+				}
+				c.Data(http.StatusOK, "image/jpeg", data)
+				return
+			}
+		}
+	}
 	// PersonImageURL handles TMDb/remote people first and falls back to regular
 	// media/library artwork, so the official /Items/{personId}/Images route
 	// works for synthetic person IDs as well as normal item IDs.

internal/handler/emby_media_segments.go

@@ -86,6 +86,12 @@ func embySegmentItems(m *model.Media, rows []model.MediaSegment, want map[string
 		}
 		endMs := row.EndMs
 		if endMs <= 0 {
+			// 只有片尾类允许「延续到片尾」。片头/回顾的结束点缺失意味着这段区间
+			// 本身不可信（数据源用 0 表示「这段不存在」），补成片长会让客户端把
+			// 整集标成片头，所以直接丢弃。
+			if row.Kind != model.SegmentKindCredits && row.Kind != model.SegmentKindPreview {
+				continue
+			}
 			if durationMs <= 0 {
 				continue
 			}

internal/handler/emby_routes.go

@@ -212,9 +212,11 @@ func registerEmbyAuthenticatedItemRoutes(auth *gin.RouterGroup, svc *service.Con
 	auth.GET("/Items/:id/Similar", embySimilarHandler(svc))
 	auth.GET("/Items/:id/ThumbnailSet", embyEmptyItemsHandler(svc))
 	auth.GET("/Items/:id/ThemeMedia", embyThemeMediaHandler(svc))
-	auth.GET("/Users/:userId/Items/:id/SpecialFeatures", embyEmptyItemsHandler(svc))
+	// SpecialFeatures 在 Emby 官方 schema 里是 BaseItemDto[]（裸数组），
+	// 返回 {"Items":[]} 会让按 List 强转的客户端抛 type cast 异常。
+	auth.GET("/Users/:userId/Items/:id/SpecialFeatures", embyEmptyArrayHandler(svc))
 	auth.GET("/Users/:userId/Items/:id/Intros", embyEmptyItemsHandler(svc))
-	auth.GET("/Items/:id/SpecialFeatures", embyEmptyItemsHandler(svc))
+	auth.GET("/Items/:id/SpecialFeatures", embyEmptyArrayHandler(svc))
 	auth.GET("/Items/:id/Intros", embyEmptyItemsHandler(svc))
 	auth.GET("/api/danmu/:id/raw", embyDanmuRawHandler(svc))
 }

internal/handler/emby_routes_lowercase.go

@@ -55,9 +55,9 @@ func registerLowercaseEmbyItemRoutes(auth *gin.RouterGroup, svc *service.Contain
 	auth.GET("/items/:id/similar", embySimilarHandler(svc))
 	auth.GET("/items/:id/thumbnailset", embyEmptyItemsHandler(svc))
 	auth.GET("/items/:id/thememedia", embyThemeMediaHandler(svc))
-	auth.GET("/users/:userId/items/:id/specialfeatures", embyEmptyItemsHandler(svc))
+	auth.GET("/users/:userId/items/:id/specialfeatures", embyEmptyArrayHandler(svc))
 	auth.GET("/users/:userId/items/:id/intros", embyEmptyItemsHandler(svc))
-	auth.GET("/items/:id/specialfeatures", embyEmptyItemsHandler(svc))
+	auth.GET("/items/:id/specialfeatures", embyEmptyArrayHandler(svc))
 	auth.GET("/items/:id/intros", embyEmptyItemsHandler(svc))
 }
 

internal/handler/library_cover.go

@@ -0,0 +1,100 @@
+package handler
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// libraryCoverHandler 输出媒体库封面图（Emby 风格的成员海报拼图）。
+//
+// 之前 Web 端是拿两张成员海报在前端用 CSS 拼格子，Emby 客户端则直接拿一张
+// 评分最高的海报，结果同一个库在不同客户端长得完全不一样。现在服务端生成
+// 一张 16:9 的拼图（Emby 的 folder image 做法），Emby 客户端、Web 和 App
+// 都指向这一份，外观统一。
+func libraryCoverHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		id := strings.TrimSpace(c.Param("id"))
+		if id == "" || svc == nil || svc.ImageProxy == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "cover unavailable"})
+			return
+		}
+		ctx, cancel := context.WithTimeout(c.Request.Context(), 25*time.Second)
+		defer cancel()
+
+		sources, lib := service.LibraryCoverSourcesForLibrary(ctx, svc.Repo, id)
+		if lib == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "library not found"})
+			return
+		}
+		if strings.TrimSpace(lib.CoverURL) != "" {
+			// 管理员自定义封面优先，保持既有行为（代理该地址）。
+			if err := svc.ImageProxy.Serve(ctx, c.Writer, c.Request, lib.CoverURL); err != nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "custom cover unavailable"})
+			}
+			return
+		}
+		if len(sources) == 0 {
+			c.JSON(http.StatusNotFound, gin.H{"error": "no library items with artwork"})
+			return
+		}
+		width, height := libraryCoverRequestSize(c)
+		data, err := svc.ImageProxy.LibraryCoverImage(ctx, id, sources, width, height)
+		if err != nil || len(data) == 0 {
+			c.JSON(http.StatusNotFound, gin.H{"error": "cover generation failed"})
+			return
+		}
+		writeLibraryCoverImage(c, data, http.StatusOK)
+	}
+}
+
+// libraryCoverRequestSize 解析请求的封面尺寸：Web 用 w/h，Emby 用
+// maxWidth/maxHeight，两种都兼容。服务端统一输出 16:9 画布（与该库在 Emby
+// 里上报的 PrimaryImageAspectRatio 一致），客户端传的尺寸只当作「不超过」的
+// 边界使用。
+func libraryCoverRequestSize(c *gin.Context) (int, int) {
+	return firstPositiveQueryIntParam(c, "maxWidth", "maxwidth", "width", "w"),
+		firstPositiveQueryIntParam(c, "maxHeight", "maxheight", "height", "h")
+}
+
+func firstPositiveQueryIntParam(c *gin.Context, names ...string) int {
+	for _, name := range names {
+		raw := strings.TrimSpace(c.Query(name))
+		if raw == "" {
+			continue
+		}
+		if n, err := strconv.Atoi(raw); err == nil && n > 0 {
+			return n
+		}
+		if f, err := strconv.ParseFloat(raw, 64); err == nil && f > 0 {
+			return int(f)
+		}
+	}
+	return 0
+}
+
+func writeLibraryCoverImage(c *gin.Context, data []byte, status int) {
+	sum := sha256.Sum256(data)
+	etag := `"` + hex.EncodeToString(sum[:8]) + `"`
+	c.Header("ETag", etag)
+	c.Header("Cache-Control", "public, max-age=300, stale-while-revalidate=86400")
+	if match := strings.TrimSpace(c.GetHeader("If-None-Match")); match != "" && match == etag {
+		c.Status(http.StatusNotModified)
+		return
+	}
+	c.Header("Content-Type", "image/jpeg")
+	c.Header("Content-Length", strconv.Itoa(len(data)))
+	if c.Request.Method == http.MethodHead {
+		c.Status(status)
+		return
+	}
+	c.Data(status, "image/jpeg", data)
+}

internal/handler/library_cover_route_test.go

@@ -0,0 +1,118 @@
+package handler
+
+import (
+	"bytes"
+	"image/color"
+	"image/jpeg"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/middleware"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func coverTestToken(t *testing.T, secret, userID string) string {
+	t.Helper()
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, middleware.Claims{
+		UserID: userID,
+		Role:   "admin",
+		RegisteredClaims: jwt.RegisteredClaims{
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour)),
+			IssuedAt:  jwt.NewNumericDate(time.Now()),
+			Subject:   userID,
+		},
+	})
+	signed, err := token.SignedString([]byte(secret))
+	if err != nil {
+		t.Fatalf("sign token: %v", err)
+	}
+	return signed
+}
+
+// TestLibraryCoverRouteServesImageThroughFullRouter 走完整的 handler.Register
+// 路由表请求封面：既验证路由挂载正确，也验证鉴权链（AuthRequired +
+// activeUserRequired）不会把它挡成 404。
+func TestLibraryCoverRouteServesImageThroughFullRouter(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	const secret = "test-secret"
+
+	poster := coverTestJPEG(t, color.RGBA{R: 200, G: 120, B: 60, A: 255})
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(poster)
+	}))
+	defer upstream.Close()
+	parsed, _ := url.Parse(upstream.URL)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.Library{}, &model.Media{}, &model.User{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+	user := model.User{Base: model.Base{ID: "user-1"}, Username: "viewer", IsActive: true}
+	if err := db.Create(&user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	lib := model.Library{Name: "电影", Path: "/media/movies", Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	for i := 0; i < 4; i++ {
+		row := model.Media{
+			Base:      model.Base{ID: "m" + string(rune('a'+i))},
+			LibraryID: lib.ID,
+			Title:     "Movie " + string(rune('A'+i)),
+			Path:      "/media/movies/m" + string(rune('a'+i)) + ".mkv",
+			PosterURL: upstream.URL + "/p" + string(rune('1'+i)) + ".jpg",
+		}
+		if err := db.Create(&row).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+
+	cfg := &config.Config{
+		Cache:   config.CacheConfig{CacheDir: filepath.Join(t.TempDir(), "cache")},
+		Secrets: config.SecretsConfig{JWTSecret: secret},
+	}
+	proxy := service.NewImageProxy(cfg, zap.NewNop())
+	proxy.SetAllowedRemoteHostsProvider(func() []string { return []string{parsed.Host} })
+	svc := &service.Container{Repo: repos, ImageProxy: proxy}
+
+	engine := gin.New()
+	Register(engine, cfg, zap.NewNop(), svc)
+
+	token := coverTestToken(t, secret, user.ID)
+	req := httptest.NewRequest(http.MethodGet, "/api/libraries/"+lib.ID+"/cover?w=480&h=270&api_key="+token, nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	if ct := w.Header().Get("Content-Type"); ct != "image/jpeg" {
+		t.Fatalf("content type = %q, want image/jpeg", ct)
+	}
+	img, err := jpeg.Decode(bytes.NewReader(w.Body.Bytes()))
+	if err != nil {
+		t.Fatalf("decode cover: %v", err)
+	}
+	if img.Bounds().Dx() != 480 || img.Bounds().Dy() != 270 {
+		t.Fatalf("cover size = %v, want 480x270", img.Bounds())
+	}
+}

internal/handler/library_cover_test.go

@@ -0,0 +1,228 @@
+package handler
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+func coverTestJPEG(t *testing.T, c color.RGBA) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, 160, 240))
+	for y := 0; y < 240; y++ {
+		for x := 0; x < 160; x++ {
+			img.Set(x, y, c)
+		}
+	}
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: 90}); err != nil {
+		t.Fatalf("encode jpeg: %v", err)
+	}
+	return buf.Bytes()
+}
+
+// newLibraryCoverTestRouter 构造一个带真实图片代理的路由：成员海报来自
+// 本地 httptest 服务，走的是与生产一致的 ImageProxy 抓取路径。
+func newLibraryCoverTestRouter(t *testing.T) (*gin.Engine, *repository.Container, *httptest.Server) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	poster := coverTestJPEG(t, color.RGBA{R: 200, G: 120, B: 60, A: 255})
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(poster)
+	}))
+	t.Cleanup(upstream.Close)
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.Library{}, &model.Media{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := repository.New(db)
+
+	parsed, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatalf("parse upstream: %v", err)
+	}
+	cfg := &config.Config{Cache: config.CacheConfig{CacheDir: filepath.Join(t.TempDir(), "cache")}}
+	proxy := service.NewImageProxy(cfg, zap.NewNop())
+	proxy.SetAllowedRemoteHostsProvider(func() []string { return []string{parsed.Host} })
+
+	svc := &service.Container{Repo: repos, ImageProxy: proxy}
+	router := gin.New()
+	router.GET("/libraries/:id/cover", libraryCoverHandler(svc))
+	router.HEAD("/libraries/:id/cover", libraryCoverHandler(svc))
+	return router, repos, upstream
+}
+
+func seedCoverLibrary(t *testing.T, repos *repository.Container, posterBase string, coverURL string) model.Library {
+	t.Helper()
+	lib := model.Library{Name: "电影", Path: "/media/movies", Type: "movie", Enabled: true, CoverURL: coverURL}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	for i := 0; i < 4; i++ {
+		row := model.Media{
+			Base:      model.Base{ID: "m" + string(rune('a'+i))},
+			LibraryID: lib.ID,
+			Title:     "Movie " + string(rune('A'+i)),
+			Path:      "/media/movies/m" + string(rune('a'+i)) + ".mkv",
+			PosterURL: posterBase + "/p" + string(rune('1'+i)) + ".jpg",
+		}
+		if err := repos.DB.Create(&row).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+	return lib
+}
+
+// TestLibraryCoverHandlerServesGeneratedCollage 覆盖 Web/App 的封面接口：
+// 返回的是服务端拼好的 16:9 图片，而不是单张成员海报。
+func TestLibraryCoverHandlerServesGeneratedCollage(t *testing.T) {
+	router, repos, upstream := newLibraryCoverTestRouter(t)
+	lib := seedCoverLibrary(t, repos, upstream.URL, "")
+
+	req := httptest.NewRequest(http.MethodGet, "/libraries/"+lib.ID+"/cover?w=480&h=270", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	if ct := w.Header().Get("Content-Type"); ct != "image/jpeg" {
+		t.Fatalf("content type = %q, want image/jpeg", ct)
+	}
+	img, err := jpeg.Decode(bytes.NewReader(w.Body.Bytes()))
+	if err != nil {
+		t.Fatalf("decode cover: %v", err)
+	}
+	if img.Bounds().Dx() != 480 || img.Bounds().Dy() != 270 {
+		t.Fatalf("cover size = %v, want 480x270", img.Bounds())
+	}
+	if etag := w.Header().Get("ETag"); etag == "" {
+		t.Fatal("expected an ETag so clients can revalidate")
+	}
+
+	// 条件请求应拿到 304。
+	req = httptest.NewRequest(http.MethodGet, "/libraries/"+lib.ID+"/cover?w=480&h=270", nil)
+	req.Header.Set("If-None-Match", w.Header().Get("ETag"))
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	if rec.Code != http.StatusNotModified {
+		t.Fatalf("conditional request status = %d, want 304", rec.Code)
+	}
+}
+
+func TestLibraryCoverHandlerUnknownLibraryReturns404(t *testing.T) {
+	router, _, _ := newLibraryCoverTestRouter(t)
+	req := httptest.NewRequest(http.MethodGet, "/libraries/missing/cover", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404", w.Code)
+	}
+}
+
+// TestLibraryCoverHandlerServesCustomCover 管理员填了 cover_url 时必须继续
+// 用自定义封面，不能在不知不觉中换成拼图。
+func TestLibraryCoverHandlerServesCustomCover(t *testing.T) {
+	router, repos, upstream := newLibraryCoverTestRouter(t)
+	lib := seedCoverLibrary(t, repos, upstream.URL, upstream.URL+"/custom.jpg")
+
+	req := httptest.NewRequest(http.MethodGet, "/libraries/"+lib.ID+"/cover", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	if _, err := jpeg.Decode(bytes.NewReader(w.Body.Bytes())); err != nil {
+		t.Fatalf("custom cover should be an image: %v", err)
+	}
+}
+
+// TestEmbyLibraryPrimaryUsesGeneratedCollage 保证 Emby 客户端请求库主图时
+// 拿到的也是拼图（与 Web/App 同一份生成逻辑）。
+func TestEmbyLibraryPrimaryUsesGeneratedCollage(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.Library{}, &model.Media{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+
+	poster := coverTestJPEG(t, color.RGBA{G: 180, R: 90, B: 60, A: 255})
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(poster)
+	}))
+	defer upstream.Close()
+	parsed, _ := url.Parse(upstream.URL)
+
+	repos := repository.New(db)
+	lib := model.Library{Name: "剧集", Path: "/media/tv", Type: "tv", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	for i := 0; i < 4; i++ {
+		row := model.Media{
+			Base:      model.Base{ID: "e" + string(rune('a'+i))},
+			LibraryID: lib.ID,
+			Title:     "Show " + string(rune('A'+i)),
+			Path:      "/media/tv/show" + string(rune('a'+i)) + "/S01E01.mkv",
+			SeasonNum: 1, EpisodeNum: 1,
+			PosterURL: upstream.URL + "/p" + string(rune('1'+i)) + ".jpg",
+		}
+		if err := repos.DB.Create(&row).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+
+	cfg := &config.Config{Cache: config.CacheConfig{CacheDir: filepath.Join(t.TempDir(), "cache")}}
+	proxy := service.NewImageProxy(cfg, zap.NewNop())
+	proxy.SetAllowedRemoteHostsProvider(func() []string { return []string{parsed.Host} })
+	svc := &service.Container{
+		Repo:       repos,
+		Emby:       service.NewEmbyService(cfg, zap.NewNop(), repos),
+		ImageProxy: proxy,
+	}
+	router := gin.New()
+	registerEmbyRoutes(router, "test-secret", svc)
+
+	req := httptest.NewRequest(http.MethodGet, "/Items/"+lib.ID+"/Images/Primary?maxWidth=400&maxHeight=300", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	img, err := jpeg.Decode(bytes.NewReader(w.Body.Bytes()))
+	if err != nil {
+		t.Fatalf("decode emby library cover: %v", err)
+	}
+	// 请求的是 400×300 的盒子，拼图按 16:9 装进去 → 400×225。
+	if img.Bounds().Dx() != 400 || img.Bounds().Dy() != 225 {
+		t.Fatalf("cover size = %v, want 400x225 (16:9 inside the requested box)", img.Bounds())
+	}
+}

internal/handler/media.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"math"
 	"net/http"
+	"net/url"
 	"sort"
 	"strconv"
 	"strings"
@@ -40,6 +41,25 @@ type webLibraryPayload struct {
 	RemoteSource string                   `json:"remote_source,omitempty"`
 	Total        int64                    `json:"total,omitempty"`
 	Cards        []service.SeriesCardView `json:"cards,omitempty"`
+	// CoverImageURL 是客户端可直接使用的「有效封面」：管理员自定义的
+	// cover_url 优先，否则指向服务端生成的成员海报拼图接口。Web / App 都
+	// 读这一个字段，避免各自用卡片在前端拼格子、长得还不一样。
+	CoverImageURL string `json:"cover_image_url,omitempty"`
+}
+
+// effectiveLibraryCoverURL 计算库封面的有效地址。远程挂载库的封面由上游
+// Emby 决定，这里返回空串，调用方继续用卡片拼图兜底。
+func effectiveLibraryCoverURL(lib model.Library, isRemote bool) string {
+	if isRemote {
+		return ""
+	}
+	if raw := strings.TrimSpace(lib.CoverURL); raw != "" {
+		return raw
+	}
+	if strings.TrimSpace(lib.ID) == "" {
+		return ""
+	}
+	return "/api/libraries/" + url.PathEscape(lib.ID) + "/cover"
 }
 
 // remoteLibraryPreviewBudget 限制 /api/libraries?with_preview=1 里远程 Emby
@@ -124,9 +144,10 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 			}
 			for _, p := range previews {
 				out = append(out, webLibraryPayload{
-					Library: p.Library,
-					Total:   p.Total,
-					Cards:   service.NewSeriesCardViews(p.Cards),
+					Library:       p.Library,
+					Total:         p.Total,
+					Cards:         service.NewSeriesCardViews(p.Cards),
+					CoverImageURL: effectiveLibraryCoverURL(p.Library, false),
 				})
 			}
 		} else {
@@ -145,7 +166,7 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 				if counts != nil {
 					total = counts[l.ID]
 				}
-				out = append(out, webLibraryPayload{Library: l, Total: total})
+				out = append(out, webLibraryPayload{Library: l, Total: total, CoverImageURL: effectiveLibraryCoverURL(l, false)})
 			}
 		}
 		// 精确指定目标库时，如果目标全是本地库，就不必枚举远程挂载。
@@ -272,9 +293,9 @@ func getLibraryHandler(svc *service.Container) gin.HandlerFunc {
 				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 				return
 			}
-			c.JSON(http.StatusOK, webLibraryPayload{Library: libs[0]})
+			c.JSON(http.StatusOK, webLibraryPayload{Library: libs[0], CoverImageURL: effectiveLibraryCoverURL(libs[0], false)})
 		} else {
-			c.JSON(http.StatusOK, webLibraryPayload{Library: *lib})
+			c.JSON(http.StatusOK, webLibraryPayload{Library: *lib, CoverImageURL: effectiveLibraryCoverURL(*lib, false)})
 		}
 	}
 }

internal/handler/playback_segments.go

@@ -1,13 +1,18 @@
 // Package handler — 片头/片尾片段接口。
 //
-//	GET /playback/:id/segments
+//	GET    /playback/:id/segments
+//	PUT    /playback/:id/segments   {kind, position_ms, clear}
 //
 // 单独开一个接口而不是塞进 /media/:id/playback，有两个原因：一是抓取外部数据
 // 可能要几秒，不能拖慢决定能否起播的那个请求；二是片段与播放来源（本地 / 云盘 /
 // 远程 Emby）无关，独立出来对所有媒体一致。
+//
+// 写入接口只处理「手动标记」：用户播放时把当前位置标成片头结束 / 片尾开始。
+// 外部数据永远由提供方刷新，不接受客户端写入。
 package handler
 
 import (
+	"errors"
 	"net/http"
 
 	"github.com/gin-gonic/gin"
@@ -42,6 +47,72 @@ func playbackSegmentsHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+// playbackSegmentsMarkRequest 是手动标记的入参。
+type playbackSegmentsMarkRequest struct {
+	// Kind 只接受 intro / credits。
+	Kind string `json:"kind" binding:"required"`
+	// PositionMs 是当前播放位置：标片头时表示片头结束点，标片尾时表示片尾开始点。
+	PositionMs int64 `json:"position_ms"`
+	// Clear 为 true 时删除该类型的标记。
+	Clear bool `json:"clear"`
+}
+
+// playbackSegmentsMarkHandler 写入或清除一条手动标记，返回更新后的完整片段列表。
+//
+// 返回整份列表而不是只回 204：播放器需要立刻反映合并后的结果（手动标记优先级
+// 最高），避免自己再发一次 GET 造成竞态。
+func playbackSegmentsMarkHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc.Segments == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "segments unavailable"})
+			return
+		}
+		m, err := findMediaForPlaybackEndpoint(c, svc, c.Param("id"))
+		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
+			return
+		}
+		// 远程 Emby 挂载是上游库的投影，本地标记没有可落地的地方。
+		if service.IsEmbyRemoteID(m.ID) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "remote media cannot be marked"})
+			return
+		}
+		var req playbackSegmentsMarkRequest
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid body"})
+			return
+		}
+		err = svc.Segments.SetManualMark(c.Request.Context(), m, service.ManualMarkRequest{
+			Kind:       req.Kind,
+			PositionMs: req.PositionMs,
+			Clear:      req.Clear,
+		})
+		if errors.Is(err, service.ErrInvalidManualMark) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid skip mark"})
+			return
+		}
+		if err != nil {
+			if svc.Log != nil {
+				svc.Log.Warn("save manual skip mark failed",
+					zap.String("media_id", m.ID), zap.Error(err))
+			}
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "save failed"})
+			return
+		}
+		rows, listErr := svc.Segments.ListForPlayback(c.Request.Context(), m)
+		if listErr != nil {
+			if svc.Log != nil {
+				svc.Log.Debug("list media segments after mark failed",
+					zap.String("media_id", m.ID), zap.Error(listErr))
+			}
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"segments":  service.ToSegmentViews(rows),
+			"auto_skip": resolveAutoSkipFlag(c, svc),
+		})
+	}
+}
+
 // resolveAutoSkipFlag reads the「自动跳过片头」switch off whichever profile is
 // currently in effect. It reuses selectedPlayProfile so the server agrees with
 // the UI about which profile is active (explicit header first, then the user's

internal/handler/reader_media_test.go

@@ -0,0 +1,764 @@
+package handler
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/service"
+	"github.com/truewhile/MeBox/internal/service/reader"
+)
+
+// 媒体代理在「上游签名票被拒」时的行为契约。
+//
+// 背景（真实故障）：聆阅·懒人听书源的音频直链是第三方中转现签的腾讯 CDN 票，
+// 票被 CDN 判掉时上游回的是**空的 401**（无 Content-Type、无 body）。旧行为把它
+// 原样透传给播放器，播放器重试的还是同一个 URL，于是 App 日志里连续 4~8 个
+// ERROR_CODE_IO_BAD_HTTP_STATUS (2004)，表现为「这本书怎么都播不了」。
+//
+// 现在的契约：
+//   - 能换票 → 用新票重拉，直接返回媒体本体（第一个请求就被治好）；
+//   - 换不到 → 502 + 明确文案，而不是把 401 丢给播放器；
+//   - 非音轨地址（漫画图片防盗链等）→ 维持原样透传，不改变既有行为。
+
+func TestReaderMediaPayloadRejected(t *testing.T) {
+	cases := []struct {
+		name        string
+		head        string
+		contentType string
+		want        bool
+	}{
+		{"HTML 错误页", "<!DOCTYPE html><html><body>403</body></html>", "text/html; charset=utf-8", true},
+		{"JSON 报错", `{"code":403,"message":"expired"}`, "application/json", true},
+		{"数组形态报错", `[{"error":"bad ticket"}]`, "application/json; charset=utf-8", true},
+		{"纯文本报错", "ticket expired", "text/plain", false},
+		{"正常 m4a", "\x00\x00\x00\x20ftypmp42", "audio/mp4", false},
+		{"正常 mp3", "ID3\x04\x00", "audio/mpeg", false},
+		{"正常图片", "\xff\xd8\xff\xe0", "image/jpeg", false},
+		{"播放列表", "#EXTM3U\n#EXTINF:10,", "application/vnd.apple.mpegurl", false},
+		{"空体", "", "text/html", false},
+		{"HTML 类型但二进制体", "\x00\x00\x00\x20ftypmp42", "text/html", false},
+	}
+	for _, c := range cases {
+		got := readerMediaPayloadRejected([]byte(c.head), c.contentType)
+		if got != c.want {
+			t.Errorf("%s: readerMediaPayloadRejected(%q, %q) = %v，期望 %v",
+				c.name, c.head, c.contentType, got, c.want)
+		}
+	}
+}
+
+// TestReaderMediaProxyHealsStaleTicket 票被上游拒绝时代理自己换票重拉，
+// 第一个请求就返回媒体本体（不必等播放器重试）。
+func TestReaderMediaProxyHealsStaleTicket(t *testing.T) {
+	svc, srv, book := prepareMediaTicketBook(t)
+	router := mediaRouterForTest(svc)
+
+	signed := primeTicketBook(t, svc, book.ID)
+	// 让中转再签一张新票：章节缓存里那张就此变成「旧票」。
+	srv.rotate()
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusOK {
+		t.Fatalf("换票重试后 status=%d body=%s", code, body)
+	}
+	if !strings.Contains(body, "fake-audio-bytes") {
+		t.Fatalf("响应体不是媒体: %q", body)
+	}
+	if got := srv.contentHits(); got < 2 {
+		t.Fatalf("应当回源重取章节，实际请求 %d 次", got)
+	}
+}
+
+// TestReaderMediaProxyFailsClearlyWhenRefreshImpossible 换不到票时给 502 + 明确文案，
+// 而不是把 401 透传给播放器（那样播放器只会对着必然失败的地址反复重试）。
+func TestReaderMediaProxyFailsClearlyWhenRefreshImpossible(t *testing.T) {
+	svc, srv, book := prepareMediaTicketBook(t)
+	router := mediaRouterForTest(svc)
+
+	signed := primeTicketBook(t, svc, book.ID)
+	srv.rotate()
+	srv.stopIssuing()
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusBadGateway {
+		t.Fatalf("换票失败应当返回 502，实际 %d body=%s", code, body)
+	}
+	if !strings.Contains(body, "签名失效") {
+		t.Fatalf("错误文案应说明是音源签名失效: %s", body)
+	}
+}
+
+// TestReaderMediaProxyStopsResendingRejectedTicket 上游成批拒绝时（连新签的票
+// 也是空 401），不能在播放器那一次请求里把同一张被拒的票打上十几遍：连续两轮
+// 换票都是同一个状态码就立刻失败，把明确文案交出去。
+func TestReaderMediaProxyStopsResendingRejectedTicket(t *testing.T) {
+	svc, srv, book := prepareMediaTicketBook(t)
+	router := mediaRouterForTest(svc)
+
+	signed := primeTicketBook(t, svc, book.ID)
+	srv.denyAlways()
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusBadGateway {
+		t.Fatalf("上游持续拒绝应返回 502，实际 %d body=%s", code, body)
+	}
+	if !strings.Contains(body, "401") {
+		t.Fatalf("错误文案应带上上游状态码: %s", body)
+	}
+	// 每轮 fetchReaderMedia = 首拉(401) + 换票后重拉(401)，两轮即收手。
+	if got := srv.mediaRequests(); got > 4 {
+		t.Fatalf("无进展的拒绝应当两轮就收手，实际上游请求 %d 次", got)
+	}
+}
+
+// TestReaderAudioCacheResumesTruncatedUpstream 上游中途 RST 后用 Range 续传：
+// 播放器最终拿到的仍是完整的一章，而不是从头重下。
+func TestReaderAudioCacheResumesTruncatedUpstream(t *testing.T) {
+	const bodyBytes = 300 << 10
+	payload := bytes.Repeat([]byte("m4a!"), bodyBytes/4)
+	var ranges []string
+	var mu sync.Mutex
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		ranges = append(ranges, r.Header.Get("Range"))
+		count := len(ranges)
+		mu.Unlock()
+
+		w.Header().Set("Content-Type", "audio/mp4")
+		w.Header().Set("Accept-Ranges", "bytes")
+		start := 0
+		if count > 1 {
+			// 第二次起按 Range 续传。
+			start = bodyBytes / 2
+			w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, bodyBytes-1, bodyBytes))
+			w.WriteHeader(http.StatusPartialContent)
+		} else {
+			w.Header().Set("Content-Length", strconv.Itoa(bodyBytes))
+		}
+		chunk := payload[start:]
+		if count == 1 {
+			// 第一次只写一半就断开。
+			chunk = payload[:bodyBytes/2]
+		}
+		for written := 0; written < len(chunk); written += 8 << 10 {
+			end := written + 8<<10
+			if end > len(chunk) {
+				end = len(chunk)
+			}
+			if _, err := w.Write(chunk[written:end]); err != nil {
+				return
+			}
+		}
+		w.(http.Flusher).Flush()
+		if count == 1 {
+			if hj, ok := w.(http.Hijacker); ok {
+				if conn, _, err := hj.Hijack(); err == nil {
+					_ = conn.Close()
+				}
+			}
+		}
+	}))
+	defer srv.Close()
+
+	svc, _, book := prepareMediaTicketBookWithUpstream(t, srv.URL)
+	router := mediaRouterForTest(svc)
+	signed := svc.Reader.ProxyURL(book.ID, srv.URL+"/media")
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusOK {
+		t.Fatalf("续传后应当成功，实际 status=%d body=%.120s", code, body)
+	}
+	if len(body) != bodyBytes {
+		t.Fatalf("交付字节 = %d，期望 %d", len(body), bodyBytes)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(ranges) < 2 || ranges[0] != "" {
+		t.Fatalf("请求序列 = %q，期望先整段再续传", ranges)
+	}
+	if !strings.HasPrefix(ranges[1], "bytes=") {
+		t.Fatalf("第二轮应当带 Range，实际 %q", ranges[1])
+	}
+}
+
+// TestReaderMediaProxyPassesThroughNonTrackError 漫画图片这类不可换票的地址，
+// 上游 4xx 仍按原状态透传（既有行为不变）。
+func TestReaderMediaProxyPassesThroughNonTrackError(t *testing.T) {
+	svc, srv, book := prepareMediaTicketBook(t)
+	router := mediaRouterForTest(svc)
+
+	// 书源域名下的图片地址：不在任何音轨缓存里。
+	imgURL := srv.URL + "/img/forbidden.jpg"
+	signed := svc.Reader.ProxyURL(book.ID, imgURL)
+
+	code, body := getReaderMedia(t, router, signed)
+	if code == http.StatusBadGateway || code == http.StatusUnauthorized {
+		t.Fatalf("非音轨地址不该走换票分支，实际 %d body=%s", code, body)
+	}
+	if code != http.StatusForbidden {
+		t.Fatalf("图片 403 应原样透传，实际 %d body=%s", code, body)
+	}
+	if got := srv.contentHits(); got != 0 {
+		t.Fatalf("图片失败不该触发回源取章节，实际 %d 次", got)
+	}
+}
+
+// TestReaderMediaProxyRejectsNonMediaPayload 上游用 200 回一段 HTML/JSON 错误页时，
+// 代理直接判失败，不把网页喂给播放器（否则报「格式不支持」）。
+func TestReaderMediaProxyRejectsNonMediaPayload(t *testing.T) {
+	svc, srv, book := prepareMediaTicketBook(t)
+	router := mediaRouterForTest(svc)
+
+	signed := primeTicketBook(t, svc, book.ID)
+	srv.serveErrorPage()
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusBadGateway {
+		t.Fatalf("非媒体内容应当返回 502，实际 %d body=%.160s", code, body)
+	}
+	if !strings.Contains(body, "非媒体内容") {
+		t.Fatalf("错误文案应说明上游返回了非媒体内容: %s", body)
+	}
+}
+
+// ─── 上游抖动：连接被 reset 时的重试与截断可见化 ─────────────────────────
+
+// TestReaderMediaProbeRetriesConnectionReset 上游在响应体中途 RST 连接时，
+// 代理要退避重试，而不是第一次读失败就回 502。
+//
+// 真实故障：腾讯 CDN 的跨境边缘在并发/长传输时会直接 RST，同一章重试一次
+// 往往就好。以前这里读 body 失败即判死，把一次可恢复的抖动变成「这本书播不了」。
+func TestReaderMediaProbeRetriesConnectionReset(t *testing.T) {
+	var attempts int32
+	const bodyBytes = 200 << 10
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		n := atomic.AddInt32(&attempts, 1)
+		if n == 1 {
+			// 第一次：声明长度，写一小段后直接断开连接（模拟 RST/提前 EOF）。
+			w.Header().Set("Content-Type", "audio/mp4")
+			w.Header().Set("Content-Length", strconv.Itoa(bodyBytes))
+			_, _ = w.Write([]byte("\x00\x00\x00\x20ftypmp42"))
+			w.(http.Flusher).Flush()
+			if hj, ok := w.(http.Hijacker); ok {
+				if conn, _, err := hj.Hijack(); err == nil {
+					_ = conn.Close()
+				}
+			}
+			return
+		}
+		w.Header().Set("Content-Type", "audio/mp4")
+		w.Header().Set("Content-Length", strconv.Itoa(bodyBytes))
+		payload := make([]byte, 8<<10)
+		for written := 0; written < bodyBytes; written += len(payload) {
+			if _, err := w.Write(payload); err != nil {
+				return
+			}
+		}
+	}))
+	defer srv.Close()
+
+	svc, _, book := prepareMediaTicketBookWithUpstream(t, srv.URL)
+	router := mediaRouterForTest(svc)
+	signed := svc.Reader.ProxyURL(book.ID, srv.URL+"/media")
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusOK {
+		t.Fatalf("连接被 reset 后应当重试成功，实际 status=%d body=%.200s", code, body)
+	}
+	if int32(len(body)) != bodyBytes {
+		t.Fatalf("交付字节 = %d，期望 %d", len(body), bodyBytes)
+	}
+	if got := atomic.LoadInt32(&attempts); got < 2 {
+		t.Fatalf("应当重试过，实际上游请求 %d 次", got)
+	}
+}
+
+// TestReaderMediaAbortsWhenUpstreamTruncates 非音轨的流式透传路径：上游中途
+// 断开且重试都失败时，必须让客户端看到「传输不完整」，不能返回一个长度正确
+// 却内容缺失的响应。
+//
+// 以前这里是 `_, _ = io.Copy(...)`，错误被丢掉，客户端拿到一个正常结束的
+// 半截文件 —— 播放器只能报「格式不支持」（3003），根因被彻底掩盖。
+//
+// 音轨走的是整段落盘缓存（见 TestReaderAudioCacheRejectsTruncatedUpstream）：
+// 拉不完整就重试，全部失败回 502，绝不会把半截音频交给播放器。
+func TestReaderMediaAbortsWhenUpstreamTruncates(t *testing.T) {
+	const declared = 400 << 10
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "audio/mp4")
+		w.Header().Set("Content-Length", strconv.Itoa(declared))
+		// 先写够探测用的前缀，再断开：探测能过，透传阶段才断。
+		payload := make([]byte, 8<<10)
+		for written := 0; written < 128<<10; written += len(payload) {
+			if _, err := w.Write(payload); err != nil {
+				return
+			}
+		}
+		w.(http.Flusher).Flush()
+		if hj, ok := w.(http.Hijacker); ok {
+			if conn, _, err := hj.Hijack(); err == nil {
+				_ = conn.Close()
+			}
+		}
+	}))
+	defer srv.Close()
+
+	svc, _, book := prepareMediaTicketBookWithUpstream(t, srv.URL)
+	router := mediaRouterForTest(svc)
+	// .mp4 不是音频后缀：走流式透传分支（音轨会被整段落盘缓存）。
+	signed := svc.Reader.ProxyURL(book.ID, srv.URL+"/media.mp4")
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, signed, nil)
+	// panic(http.ErrAbortHandler) 由 net/http 捕获；httptest 下会向上冒泡，
+	// 这里断言它确实发生了（即「没有静默地把半截文件当成功」）。
+	defer func() {
+		recovered := recover()
+		if recovered == nil {
+			t.Fatalf("上游截断时必须中止响应（panic(http.ErrAbortHandler)），实际正常返回了 %d 字节",
+				w.Body.Len())
+		}
+		if recovered != http.ErrAbortHandler {
+			t.Fatalf("中止响应时应使用 http.ErrAbortHandler，实际 %v", recovered)
+		}
+	}()
+	router.ServeHTTP(w, req)
+	if w.Body.Len() >= declared {
+		t.Fatalf("不应交付完整长度的响应体（上游只写了 128KB）")
+	}
+}
+
+// TestReaderAudioCacheServesFromDisk 音轨首次拉取后落盘；后续请求即使带着一张
+// 新签的票（query 全变了）也不再回源——这是让播放不受跨境链路抖动影响的关键。
+func TestReaderAudioCacheServesFromDisk(t *testing.T) {
+	svc, srv, book := prepareMediaTicketBook(t)
+	router := mediaRouterForTest(svc)
+	signed := primeTicketBook(t, svc, book.ID)
+
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusOK || !strings.Contains(body, "fake-audio-bytes") {
+		t.Fatalf("首次拉取失败 status=%d body=%q", code, body)
+	}
+	if got := srv.mediaRequests(); got != 1 {
+		t.Fatalf("首次拉取应对上游请求 1 次，实际 %d", got)
+	}
+
+	// 同一段音频的另一张票：URL 的 query 不同，缓存键必须一致。
+	rotated := svc.Reader.ProxyURL(book.ID, srv.URL+"/media?t=ticket-rotated")
+	code, body = getReaderMedia(t, router, rotated)
+	if code != http.StatusOK || !strings.Contains(body, "fake-audio-bytes") {
+		t.Fatalf("命中缓存失败 status=%d body=%q", code, body)
+	}
+	if got := srv.mediaRequests(); got != 1 {
+		t.Fatalf("命中缓存后不该再回源，实际上游请求 %d 次", got)
+	}
+}
+
+// TestReaderAudioCacheAbortsOnTruncatedUpstream 首播直通模式下上游持续截断的契约：
+//
+// 冷启动走边下边发（见 handleStreamingReaderAudio），响应头和前缀字节在探测
+// 通过后就已发出，因此中途截断不可能再改写成 502 —— 必须中止连接让客户端
+// 判定「传输不完整」，同时保留 .part 分片。
+//
+// 关键不变量：**绝不能留下可命中的完整缓存**（否则后续会把截断音频当真完整
+// 文件下发，播放器表现为「时长正确但没有声音」）。下一次请求带着分片走续传
+// 路径，那时才可能给出 502 + 明确文案。
+func TestReaderAudioCacheAbortsOnTruncatedUpstream(t *testing.T) {
+	const declared = 400 << 10
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "audio/mp4")
+		w.Header().Set("Content-Length", strconv.Itoa(declared))
+		payload := make([]byte, 8<<10)
+		for written := 0; written < 128<<10; written += len(payload) {
+			if _, err := w.Write(payload); err != nil {
+				return
+			}
+		}
+		w.(http.Flusher).Flush()
+		if hj, ok := w.(http.Hijacker); ok {
+			if conn, _, err := hj.Hijack(); err == nil {
+				_ = conn.Close()
+			}
+		}
+	}))
+	defer srv.Close()
+
+	svc, _, book := prepareMediaTicketBookWithUpstream(t, srv.URL)
+	router := mediaRouterForTest(svc)
+	// 无后缀地址 + 音频书籍 → 走音轨落盘缓存。
+	signed := svc.Reader.ProxyURL(book.ID, srv.URL+"/media")
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, signed, nil)
+	// panic(http.ErrAbortHandler) 由 net/http 捕获；httptest 下会向上冒泡，
+	// 这里断言它确实发生了（即「没有静默地把半截音频当成功」）。
+	func() {
+		defer func() {
+			recovered := recover()
+			if recovered == nil {
+				t.Fatalf("上游截断时必须中止响应，实际正常返回了 %d 字节", w.Body.Len())
+			}
+			if recovered != http.ErrAbortHandler {
+				t.Fatalf("中止响应时应使用 http.ErrAbortHandler，实际 %v", recovered)
+			}
+		}()
+		router.ServeHTTP(w, req)
+	}()
+
+	if w.Body.Len() >= declared {
+		t.Fatalf("不应交付完整长度的响应体（上游只写了 128KB）")
+	}
+	if _, _, ok := svc.Reader.OpenCachedRemoteAudio(book.ID, srv.URL+"/media"); ok {
+		t.Fatalf("中断的下载不能留下可命中的完整缓存")
+	}
+	if !svc.Reader.HasPartialRemoteAudio(book.ID, srv.URL+"/media") {
+		t.Fatalf("中断后应保留 .part 分片供续传")
+	}
+
+	// 二次请求带分片走续传路径；上游依旧忽略 Range 并截断 → 这时才给 502。
+	code, body := getReaderMedia(t, router, signed)
+	if code != http.StatusBadGateway {
+		t.Fatalf("续传路径持续失败应返回 502，实际 %d body=%.120s", code, body)
+	}
+	if strings.Contains(body, "ftyp") {
+		t.Fatalf("不能把半截音频交给客户端: %q", body)
+	}
+	if _, _, ok := svc.Reader.OpenCachedRemoteAudio(book.ID, srv.URL+"/media"); ok {
+		t.Fatalf("失败的续传仍不应留下完整缓存")
+	}
+}
+
+func mediaRouterForTest(svc *service.Container) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	// /api/reader/media 挂在公共 api 组（签名鉴权，不需要 JWT），单独注册即可。
+	r.GET("/api/reader/media", readerMediaProxyHandler(svc))
+	return r
+}
+
+func getReaderMedia(t *testing.T, router *gin.Engine, signedPath string) (int, string) {
+	t.Helper()
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, signedPath, nil)
+	router.ServeHTTP(w, req)
+	return w.Code, w.Body.String()
+}
+
+// primeTicketBook 先读一次章节（签出第一张票并落缓存），返回该音轨的签名代理路径。
+func primeTicketBook(t *testing.T, svc *service.Container, bookID string) string {
+	t.Helper()
+	out, err := svc.Reader.GetContentForBook(t.Context(), "u1", bookID, 0, reader.ContentOptions{})
+	if err != nil {
+		t.Fatalf("首次取章节失败: %v", err)
+	}
+	if len(out.Tracks) != 1 {
+		t.Fatalf("音轨数 = %d，期望 1", len(out.Tracks))
+	}
+	return out.Tracks[0]
+}
+
+// ─── 模拟「中转现签 CDN 直链」的上游 ───────────────────────────────────────
+
+// mediaTicketServer：
+//   - /book/1  详情页
+//   - /content 章节正文，每次请求签一张新票
+//   - /media   媒体本体，只认最新签出的票；旧票回**空的 401**（与腾讯 CDN 一致）
+//   - /img/*   图片资源，固定 403（模拟防盗链）
+type mediaTicketServer struct {
+	*httptest.Server
+	mu         sync.Mutex
+	issued     []string
+	hits       int
+	mediaHits  int
+	noToken    bool
+	errorPage  bool
+	alwaysDeny bool
+}
+
+func newMediaTicketServer(t *testing.T) *mediaTicketServer {
+	t.Helper()
+	s := &mediaTicketServer{}
+	s.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasPrefix(r.URL.Path, "/book/1"):
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			_, _ = w.Write([]byte(`<html><body><h1>票源之书</h1></body></html>`))
+		case r.URL.Path == "/content":
+			s.mu.Lock()
+			s.hits++
+			n := s.hits
+			noToken := s.noToken
+			s.mu.Unlock()
+			w.Header().Set("Content-Type", "application/json; charset=utf-8")
+			if noToken {
+				_, _ = w.Write([]byte(`{"data":{"url":""}}`))
+				return
+			}
+			token := s.newTokenLocked(fmt.Sprintf("ticket-%d", n))
+			_, _ = w.Write([]byte(fmt.Sprintf(`{"data":{"url":"%s/media?t=%s"}}`, s.URL, token)))
+		case r.URL.Path == "/media":
+			s.mu.Lock()
+			s.mediaHits++
+			deny := s.alwaysDeny
+			s.mu.Unlock()
+			if deny {
+				// 与腾讯 CDN 一致：连新签的票也直接空 401（成批拒绝的那几分钟）。
+				w.WriteHeader(http.StatusUnauthorized)
+				return
+			}
+			if s.errorPageNow() {
+				w.Header().Set("Content-Type", "text/html; charset=utf-8")
+				_, _ = w.Write([]byte(`<html><body>ticket expired</body></html>`))
+				return
+			}
+			token := r.URL.Query().Get("t")
+			s.mu.Lock()
+			valid := len(s.issued) > 0 && s.issued[len(s.issued)-1] == token
+			s.mu.Unlock()
+			if !valid {
+				// 与上游一致：空 body、无 Content-Type。
+				w.WriteHeader(http.StatusUnauthorized)
+				return
+			}
+			w.Header().Set("Content-Type", "audio/mp4")
+			_, _ = w.Write([]byte("\x00\x00\x00\x20ftypmp42fake-audio-bytes"))
+		case strings.HasPrefix(r.URL.Path, "/img/"):
+			w.WriteHeader(http.StatusForbidden)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(s.Close)
+	return s
+}
+
+// newTokenLocked 签一张新票（调用方需持有或随后获取锁；这里内部加锁）。
+func (s *mediaTicketServer) newTokenLocked(token string) string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.issued = append(s.issued, token)
+	return token
+}
+
+// rotate 模拟「中转又签了一张新票」：章节缓存里那张就此失效。
+func (s *mediaTicketServer) rotate() {
+	s.mu.Lock()
+	s.issued = append(s.issued, fmt.Sprintf("rotated-%d", len(s.issued)))
+	s.mu.Unlock()
+}
+
+// stopIssuing 让书源此后给不出播放地址（模拟中转本身挂了）。
+func (s *mediaTicketServer) stopIssuing() {
+	s.mu.Lock()
+	s.noToken = true
+	s.mu.Unlock()
+}
+
+// serveErrorPage 让媒体端点改用 200 + HTML 错误页（直链失效的另一种形态）。
+func (s *mediaTicketServer) serveErrorPage() {
+	s.mu.Lock()
+	s.errorPage = true
+	s.mu.Unlock()
+}
+
+// denyAlways 让媒体端点连新签的票也一律空 401（模拟上游成批拒绝的那几分钟）。
+func (s *mediaTicketServer) denyAlways() {
+	s.mu.Lock()
+	s.alwaysDeny = true
+	s.mu.Unlock()
+}
+
+func (s *mediaTicketServer) errorPageNow() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.errorPage
+}
+
+func (s *mediaTicketServer) contentHits() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.hits
+}
+
+func (s *mediaTicketServer) mediaRequests() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.mediaHits
+}
+
+// prepareMediaTicketBookWithUpstream 用指定的上游地址建一本书（上游由调用方提供）。
+func prepareMediaTicketBookWithUpstream(t *testing.T, upstream string) (*service.Container, *mediaTicketServer, *model.ReaderBook) {
+	t.Helper()
+	svc := newReaderHandlerContainer(t)
+	svc.Cfg.Cache.CacheDir = t.TempDir()
+	// 占位 ticket server：只用来满足清理钩子，不参与请求。
+	srv := newMediaTicketServer(t)
+	srcJSON := fmt.Sprintf(`{
+  "bookSourceName": "上游直连测试",
+  "bookSourceType": 1,
+  "bookSourceUrl": %q,
+  "ruleContent": {"content": "$.data.url"}
+}`, upstream)
+	if _, err := svc.Reader.ImportSources(t.Context(), "u1", srcJSON); err != nil {
+		t.Fatalf("导入书源失败: %v", err)
+	}
+	srcs, err := svc.Reader.ListSources(t.Context(), "u1")
+	if err != nil || len(srcs) == 0 {
+		t.Fatalf("读不到书源: %v", err)
+	}
+	book, err := svc.Reader.AddBook(t.Context(), "u1", reader.SearchOrigin{
+		SourceID:   srcs[0].ID,
+		Origin:     upstream,
+		OriginName: "上游直连测试",
+		OriginType: 1,
+		BookURL:    upstream + "/book/1",
+	}, "上游直连之书", "某作者", "")
+	if err != nil {
+		t.Fatalf("加入书架失败: %v", err)
+	}
+	return svc, srv, book
+}
+
+func prepareMediaTicketBook(t *testing.T) (*service.Container, *mediaTicketServer, *model.ReaderBook) {
+	t.Helper()
+	svc := newReaderHandlerContainer(t)
+	// 章节缓存必须落在磁盘上：换票要凭落盘载荷找回「这个地址属于哪一章」。
+	// newReaderHandlerContainer 只给空 cfg，这里补一个临时缓存目录。
+	svc.Cfg.Cache.CacheDir = t.TempDir()
+	srv := newMediaTicketServer(t)
+	srcJSON := fmt.Sprintf(`{
+  "bookSourceName": "票源测试",
+  "bookSourceType": 1,
+  "bookSourceUrl": %q,
+  "ruleContent": {"content": "$.data.url"}
+}`, srv.URL)
+	if _, err := svc.Reader.ImportSources(t.Context(), "u1", srcJSON); err != nil {
+		t.Fatalf("导入书源失败: %v", err)
+	}
+	srcs, err := svc.Reader.ListSources(t.Context(), "u1")
+	if err != nil || len(srcs) == 0 {
+		t.Fatalf("读不到书源: %v", err)
+	}
+	book, err := svc.Reader.AddBook(t.Context(), "u1", reader.SearchOrigin{
+		SourceID:   srcs[0].ID,
+		Origin:     srv.URL,
+		OriginName: "票源测试",
+		OriginType: 1,
+		BookURL:    srv.URL + "/book/1",
+	}, "票源之书", "某作者", "")
+	if err != nil {
+		t.Fatalf("加入书架失败: %v", err)
+	}
+	if err := svc.Reader.SaveChapters(t.Context(), book.ID, []reader.ChapterInput{
+		{Index: 0, Title: "第一章", URL: srv.URL + "/content"},
+	}); err != nil {
+		t.Fatalf("保存目录失败: %v", err)
+	}
+	return svc, srv, book
+}
+
+// TestReaderAudioStreamsFirstByteBeforeDownloadCompletes 首播 TTFB 回归：
+// 冷启动必须边下边发，而不是等整章下完再一次性下发。
+//
+// 上游在第一块之后卡住不放：直通实现此时应已把那块转给客户端，所以读端能
+// 拿到字节；旧实现（整段下载后才 ServeContent）在 release 关闭前一个字节都
+// 不会发出，读端会一直阻塞。
+func TestReaderAudioStreamsFirstByteBeforeDownloadCompletes(t *testing.T) {
+	// 总长必须大于探测窗口（readerMediaProbeBytes=64KB）：首播要先读完这一小段
+	// 才能判断上游给的是错误页还是媒体，这之后才可能外发。卡点在探测结束之后，
+	// 才能证明「整段下完才发」和「边下边发」的区别。
+	const chunks = 16
+	const chunkBytes = 16 << 10
+	const stallAfter = 4 // 写满探测窗口（4×16KB=64KB）后卡住
+	release := make(chan struct{})
+	var releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	defer unblock()
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "audio/mp4")
+		w.Header().Set("Content-Length", strconv.Itoa(chunks*chunkBytes))
+		w.WriteHeader(http.StatusOK)
+		for i := 0; i < chunks; i++ {
+			if _, err := w.Write(bytes.Repeat([]byte("m4a!"), chunkBytes/4)); err != nil {
+				return
+			}
+			w.(http.Flusher).Flush()
+			if i+1 == stallAfter {
+				// 探测窗口刚写满就卡住，直到测试确认客户端已经收到字节。
+				<-release
+			}
+		}
+	}))
+	defer upstream.Close()
+
+	svc, _, book := prepareMediaTicketBookWithUpstream(t, upstream.URL)
+	signed := svc.Reader.ProxyURL(book.ID, upstream.URL+"/media")
+
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/api/reader/media", readerMediaProxyHandler(svc))
+	proxy := httptest.NewServer(router)
+	defer proxy.Close()
+
+	resp, err := http.Get(proxy.URL + signed)
+	if err != nil {
+		t.Fatalf("请求媒体代理失败: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("直通应返回 200，实际 %d", resp.StatusCode)
+	}
+
+	// 上游仍卡在 release 上：此时能读到第一批字节，才说明是边下边发。
+	first := make([]byte, 4)
+	readDone := make(chan error, 1)
+	go func() {
+		_, readErr := io.ReadFull(resp.Body, first)
+		readDone <- readErr
+	}()
+	select {
+	case readErr := <-readDone:
+		if readErr != nil {
+			t.Fatalf("读取首批字节失败: %v", readErr)
+		}
+	case <-time.After(5 * time.Second):
+		unblock()
+		t.Fatalf("首播没有边下边发：上游卡在中途（仍有 %d 字节未发）时客户端读不到任何字节",
+			(chunks-stallAfter)*chunkBytes)
+	}
+	if string(first) != "m4a!" {
+		t.Fatalf("首批字节内容不对: %q", first)
+	}
+
+	// 放行上游，把剩余字节读完并确认缓存落盘完整。
+	unblock()
+	rest, readErr := io.ReadAll(resp.Body)
+	if readErr != nil {
+		t.Fatalf("读取剩余字节失败: %v", readErr)
+	}
+	if total := 4 + len(rest); total != chunks*chunkBytes {
+		t.Fatalf("交付字节 = %d，期望 %d", total, chunks*chunkBytes)
+	}
+	// 客户端读完最后一个字节时，服务端可能还在做 truncate + rename：
+	// 落盘完成是 handler 的收尾动作，给一个有限窗口等它。
+	deadline := time.Now().Add(2 * time.Second)
+	for !svc.Reader.HasCachedRemoteAudio(book.ID, upstream.URL+"/media") {
+		if time.Now().After(deadline) {
+			t.Fatalf("直通完成后应命中缓存")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}

internal/handler/reader_routes.go

@@ -2,13 +2,23 @@
 package handler
 
 import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
+	"path"
 	"strconv"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+	"golang.org/x/sync/singleflight"
 
 	"github.com/truewhile/MeBox/internal/middleware"
 	"github.com/truewhile/MeBox/internal/model"
@@ -122,16 +132,27 @@ func readerImportSourcesHandler(svc *service.Container) gin.HandlerFunc {
 func readerUpdateSourceHandler(svc *service.Container) gin.HandlerFunc {
 	var body struct {
 		Enabled *bool `json:"enabled"`
+		// MediaDirect 媒体直连开关：允许客户端自行下载音频/漫画图片字节。
+		// 可单独提交，也可与其他字段一起提交（只更新出现的字段）。
+		MediaDirect *bool `json:"media_direct"`
 	}
 	return func(c *gin.Context) {
-		if err := c.ShouldBindJSON(&body); err != nil || body.Enabled == nil {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "enabled 字段必填"})
+		if err := c.ShouldBindJSON(&body); err != nil || (body.Enabled == nil && body.MediaDirect == nil) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "enabled 或 media_direct 字段必填"})
 			return
 		}
 		userID := c.GetString(middleware.CtxUserID)
-		if err := svc.Reader.UpdateSourceEnabled(c.Request.Context(), userID, c.Param("id"), *body.Enabled); err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-			return
+		if body.Enabled != nil {
+			if err := svc.Reader.UpdateSourceEnabled(c.Request.Context(), userID, c.Param("id"), *body.Enabled); err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+		}
+		if body.MediaDirect != nil {
+			if err := svc.Reader.SetSourceMediaDirect(c.Request.Context(), userID, c.Param("id"), *body.MediaDirect); err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
 		}
 		c.JSON(http.StatusOK, gin.H{"ok": true})
 	}
@@ -403,6 +424,10 @@ func readerBookInfoHandler(svc *service.Container) gin.HandlerFunc {
 		}
 		// 声明了封面解密的书源：详情封面也要走解密代理（尚未入库，按书源 URL 签）。
 		if info != nil {
+			// 顺手修复书架里被上游限流写坏的封面（存成接口地址的那种），先按原始
+			// 地址写回，再做下发时的解密代理改写。
+			userID := c.GetString(middleware.CtxUserID)
+			svc.Reader.RepairShelfCover(c.Request.Context(), userID, c.Query("source_url"), c.Query("book_url"), info.CoverURL)
 			info.CoverURL = svc.Reader.RewriteBookCover(c.Request.Context(), "", c.Query("source_url"), info.CoverURL)
 		}
 		c.JSON(http.StatusOK, info)
@@ -869,12 +894,34 @@ func readerMediaProxyHandler(svc *service.Container) gin.HandlerFunc {
 		// 图片地址可自带 ",{headers:{...}}" 选项段：拆分后 headers 逐图应用，
 		// 代理地址里只保留不带选项的地址（见 ProxyURL）。
 		rawURL, mediaOptions, _ := readerrule.ParseMediaOptions(rawURL)
-		resp, err := svc.Reader.FetchMediaWithOptions(c.Request.Context(), book, rawURL, c.GetHeader("Range"), mediaOptions.Headers)
+
+		// 远端音轨：整段落盘缓存，命中后不再回源。
+		//
+		// 听书源的音频直链签在腾讯音乐 CDN 上，跨境链路会间歇性返回空 401
+		// 或直接 RST 连接。旧实现每次都把抖动原样交给播放器：要么是 502 的
+		// JSON，要么是截断的 206，浏览器一律判成 MEDIA_ERR_SRC_NOT_SUPPORTED
+		// （前端据此提示「格式不支持，请检查 ffmpeg」——其实完全无关）。
+		// 缓存后只要首播成功一次，后续拖动进度、续播、重试都走本地文件。
+		// 缓存目录不可用时退回旧的流式透传，不让配置问题直接变成「播不了」。
+		if c.Request.Method == http.MethodGet &&
+			reader.IsAudioMediaURL(rawURL, book.Type) &&
+			svc.Reader.RemoteAudioCachePath(bookID, rawURL) != "" {
+			handleCachedReaderAudio(c, svc, book, bookID, rawURL, mediaOptions.Headers)
+			return
+		}
+
+		// 只有 200 的 GET 需要嗅探响应体（判播放列表 / 判错误页）；
+		// 206 的体是二进制分片、HEAD 没有体，读了反而要额外拼回去。
+		probeBody := c.Request.Method == http.MethodGet
+		media, err := fetchReaderMedia(c.Request.Context(), svc, book, rawURL, c.GetHeader("Range"), mediaOptions.Headers, probeBody)
 		if err != nil {
 			c.JSON(http.StatusBadGateway, gin.H{"error": "媒体拉取失败: " + err.Error()})
 			return
 		}
+		resp := media.resp
 		defer resp.Body.Close()
+		// 换过票时用新地址：m3u8 里的相对分片要按新地址解析。
+		rawURL = media.url
 
 		ct := resp.Header.Get("Content-Type")
 		// 书源声明了 imageDecode 时，图片字节需要服务端二次解密。
@@ -885,6 +932,7 @@ func readerMediaProxyHandler(svc *service.Container) gin.HandlerFunc {
 				c.JSON(http.StatusBadGateway, gin.H{"error": "图片过大或读取失败"})
 				return
 			}
+			sniffed = append(append([]byte(nil), media.head...), sniffed...)
 			decoded, decErr := svc.Reader.DecodeImageBytes(c.Request.Context(), book, rawURL, false, sniffed)
 			if decErr != nil {
 				c.JSON(http.StatusBadGateway, gin.H{"error": "图片解密失败: " + decErr.Error()})
@@ -897,20 +945,21 @@ func readerMediaProxyHandler(svc *service.Container) gin.HandlerFunc {
 			c.Data(resp.StatusCode, contentType, decoded)
 			return
 		}
-		// m3u8 判定不能只看 Content-Type 或 URL 后缀：上游经常把播放列表标成
-		// application/octet-stream，或者地址是 /index.m3u8?token=...（后缀判断不命中）。
-		// 先读一小段用 #EXTM3U 标记确认；不是播放列表就把这段拼回响应体继续流式透传。
+		// 200 的 GET：media.head 已经读过一小段，先用它判播放列表与错误页。
 		//
-		// 只嗅探 200 的 GET：206 的体是二进制分片、HEAD 没有体，都不需要判断。
-		if c.Request.Method == http.MethodGet && resp.StatusCode == http.StatusOK {
-			head, readErr := io.ReadAll(io.LimitReader(resp.Body, 64<<10))
-			if readErr == nil && reader.BodyIsPlaylist(head, ct) {
+		// m3u8 判定不能只看 Content-Type 或 URL 后缀：上游经常把播放列表标成
+		// application/octet-stream，或者地址是 /index.m3u8?token=...（后缀判断不命中），
+		// 所以以 #EXTM3U 标记为准。
+		if probeBody && resp.StatusCode == http.StatusOK {
+			head := media.head
+			if reader.BodyIsPlaylist(head, ct) {
 				rest, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
 				rewritten := svc.Reader.RewritePlaylist(bookID, rawURL, string(head)+string(rest))
 				c.Data(http.StatusOK, "application/vnd.apple.mpegurl", []byte(rewritten))
 				return
 			}
-			// 不是播放列表：透传时 Content-Length 可能因为已经读过一部分而失配，
+			// 走到这里说明 head 不是错误页（fetchReaderMedia 已经把错误页换票重试过了），
+			// 原样拼回去继续流式透传。Content-Length 因为已读过一部分会失配，
 			// 直接省略交给 net/http 按 chunked 处理，避免少写/多写导致截断。
 			for _, h := range []string{"Content-Type", "Content-Range", "Accept-Ranges"} {
 				if v := resp.Header.Get(h); v != "" {
@@ -921,7 +970,7 @@ func readerMediaProxyHandler(svc *service.Container) gin.HandlerFunc {
 			if len(head) > 0 {
 				_, _ = c.Writer.Write(head)
 			}
-			_, _ = io.Copy(c.Writer, resp.Body)
+			streamReaderMediaBody(c.Writer, resp.Body)
 			return
 		}
 		// 流式透传（含 206 Partial Content，支持音频拖动进度）
@@ -931,13 +980,628 @@ func readerMediaProxyHandler(svc *service.Container) gin.HandlerFunc {
 			}
 		}
 		c.Status(resp.StatusCode)
-		_, _ = io.Copy(c.Writer, resp.Body)
+		streamReaderMediaBody(c.Writer, resp.Body)
+	}
+}
+
+// streamReaderMediaBody 把上游响应体写到客户端，并在上游中途断开时**主动掐断**连接。
+//
+// 这是修复「播放器拿到半首歌」的关键：以前这里 `_, _ = io.Copy(...)` 把错误直接
+// 丢掉，上游（腾讯 CDN 边缘）在跨境链路上 RST 连接时，客户端收到的是一个正常
+// 结束、但字节数不足的响应 —— 播放器无从判断，只能报
+// ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED（看起来像「格式不支持」，实际是被截断）。
+//
+// 现在改成：上游没读完就中止这个响应，客户端因此拿到「传输不完整」而不是「正常结束」，
+// 播放器可以按常规的重试/重连逻辑处理，而不是误判成格式问题。
+func streamReaderMediaBody(w io.Writer, body io.Reader) {
+	if _, err := io.Copy(w, body); err != nil {
+		// panic(http.ErrAbortHandler) 是 net/http 约定的「异常中止」：不再补写
+		// chunked 结尾，直接关闭连接，客户端据此判定响应不完整。
+		panic(http.ErrAbortHandler)
+	}
+}
+
+// ─── 远端音轨落盘缓存 ──────────────────────────────────────────────────────
+
+const (
+	// readerAudioCacheAttempts 首次落盘的最多尝试次数（每次内部都会走「失败换票」）。
+	// 续传只补没下完的部分，所以这里的次数比过去更可用：每次失败都能推进进度。
+	readerAudioCacheAttempts = 4
+	// readerMediaReissueAttempts 换票重试次数：跨境 CDN 的「空 401」是概率性的，
+	// 一张票不行往往换一张就好；旧实现只换一次，第二次失败就把 502 交给播放器。
+	readerMediaReissueAttempts = 3
+	readerMediaReissueDelay    = 300 * time.Millisecond
+)
+
+// readerAudioFetchGroup 同一音轨并发请求（播放器 + 预取 + 预热）只下载一次。
+var readerAudioFetchGroup singleflight.Group
+
+// readerAudioStreamLocks 首播直通按缓存键串行化。
+//
+// 直通模式下两个并发请求会同时写同一个 .part 文件（播放器 + 预热器各自开一条
+// 连接很常见），交错写入必然把文件写坏。这里让后到者排队等前一个下完，
+// 拿到锁后再查一次缓存直接下发——语义与原来 singleflight 等价，只是领导者
+// 是在流式外发的，追随者不需要重复下载。
+var readerAudioStreamLocks = newKeyedMutex()
+
+// keyedMutex 按字符串键串行化，锁释放后回收条目，避免 map 无限增长。
+type keyedMutex struct {
+	mu    sync.Mutex
+	locks map[string]*keyedMutexEntry
+}
+
+type keyedMutexEntry struct {
+	mu   sync.Mutex
+	refs int
+}
+
+func newKeyedMutex() *keyedMutex {
+	return &keyedMutex{locks: map[string]*keyedMutexEntry{}}
+}
+
+// Lock 取得该键的独占锁，返回解锁函数（必须调用）。
+func (k *keyedMutex) Lock(key string) func() {
+	k.mu.Lock()
+	entry := k.locks[key]
+	if entry == nil {
+		entry = &keyedMutexEntry{}
+		k.locks[key] = entry
+	}
+	entry.refs++
+	k.mu.Unlock()
+
+	entry.mu.Lock()
+	return func() {
+		entry.mu.Unlock()
+		k.mu.Lock()
+		entry.refs--
+		if entry.refs == 0 {
+			delete(k.locks, key)
+		}
+		k.mu.Unlock()
+	}
+}
+
+// handleCachedReaderAudio 音频直链的统一入口。
+//
+// 三条路径，按代价从低到高：
+//  1. 命中完整缓存 → http.ServeContent 按 Range 下发（拖动、续播都读本地）；
+//  2. 冷启动首播 → 边下边发给客户端，同时落盘（DownloadRemoteAudioStreaming）。
+//     旧实现是「整段下完再下发」，慢链路上用户要对着转圈等整章 3–5MB，
+//     把「偶发失败」换成了「必然慢」；直通后几百毫秒就能出声，落盘照旧；
+//  3. 已有 .part 分片 → 走整段下载：分片意味着上次已经下到一半，同步续传
+//     剩余字节比重新直通更省流量，下完再一次性下发。
+func handleCachedReaderAudio(
+	c *gin.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	bookID, rawURL string,
+	headers map[string]string,
+) {
+	if f, info, ok := svc.Reader.OpenCachedRemoteAudio(bookID, rawURL); ok {
+		defer f.Close()
+		serveCachedReaderAudio(c, f, info, rawURL)
+		return
+	}
+	// 播放器拖进度时会带 Range。已缓存的文件才谈得上 Range；未缓存时直通
+	// 只能从 0 发，否则客户端拿到的区间与它请求的对不上。
+	rangeHeader := strings.TrimSpace(c.GetHeader("Range"))
+	canStream := c.Request.Method == http.MethodGet &&
+		rangeHeader == "" &&
+		!svc.Reader.HasPartialRemoteAudio(bookID, rawURL)
+
+	if canStream {
+		handleStreamingReaderAudio(c, svc, book, bookID, rawURL, headers)
+		return
+	}
+
+	cachePath, err := ensureCachedRemoteAudio(c.Request.Context(), svc, book, bookID, rawURL, headers)
+	if err != nil {
+		if svc.Log != nil {
+			svc.Log.Warn("reader 音频拉取失败", zap.String("book", bookID), zap.Error(err))
+		}
+		c.String(http.StatusBadGateway, "音频拉取失败: %s", err.Error())
+		return
+	}
+	f, err := os.Open(cachePath) // #nosec G304 -- 路径由服务端哈希生成
+	if err != nil {
+		c.String(http.StatusBadGateway, "音频缓存不可用: %s", err.Error())
+		return
+	}
+	defer f.Close()
+	info, err := f.Stat()
+	if err != nil {
+		c.String(http.StatusBadGateway, "音频缓存不可用: %s", err.Error())
+		return
+	}
+	serveCachedReaderAudio(c, f, info, rawURL)
+}
+
+// handleStreamingReaderAudio 首播直通：一边落盘一边把字节写给客户端。
+//
+// 直接写 c.Writer 而不是先落盘再 ServeContent，是为了让第一个字节尽早到达。
+// 下载失败时客户端已经收到部分字节，只能中止响应（见下面的 panic），
+// 不能改成 502 —— 状态码早就发出去了。
+func handleStreamingReaderAudio(
+	c *gin.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	bookID, rawURL string,
+	headers map[string]string,
+) {
+	key := svc.Reader.RemoteAudioCachePath(bookID, rawURL)
+	if key == "" {
+		c.String(http.StatusBadGateway, "音频缓存不可用")
+		return
+	}
+	unlock := readerAudioStreamLocks.Lock(key)
+	defer unlock()
+
+	// 排队期间前一个请求可能已经把整章下完：直接下发本地文件，不重复回源。
+	if f, info, ok := svc.Reader.OpenCachedRemoteAudio(bookID, rawURL); ok {
+		defer f.Close()
+		serveCachedReaderAudio(c, f, info, rawURL)
+		return
+	}
+
+	writer := c.Writer
+	// started 表示响应头是否已发出。没发出时失败还能改成 502；已经发出就只能
+	// 中止连接——状态码收不回来了。
+	started := false
+	_, err := svc.Reader.DownloadRemoteAudioStreaming(
+		c.Request.Context(), bookID, rawURL, readerAudioCacheAttempts,
+		readerAudioFetchFunc(c.Request.Context(), svc, book, bookID, rawURL, headers),
+		func(total int64, upstreamType string) {
+			contentType := readerAudioContentType(rawURL)
+			// 上游给了明确类型时优先用它（个别源把 m4a 标成 audio/x-m4a）。
+			if strings.HasPrefix(strings.ToLower(upstreamType), "audio/") {
+				contentType = upstreamType
+			}
+			writer.Header().Set("Content-Type", contentType)
+			writer.Header().Set("Cache-Control", "private, max-age=604800")
+			if total > 0 {
+				writer.Header().Set("Content-Length", strconv.FormatInt(total, 10))
+			}
+			writer.WriteHeader(http.StatusOK)
+			started = true
+			// 立刻把已写好的头刷给客户端：gin 的 ResponseWriter 有缓冲，
+			// 不 Flush 的话播放器要等到第一批音频字节才看到响应，白等一轮 RTT。
+			writer.Flush()
+		},
+		writer,
+	)
+	if err == nil {
+		return
+	}
+	if svc.Log != nil {
+		svc.Log.Warn("reader 音频直通失败", zap.String("book", bookID), zap.Error(err))
+	}
+	if !started {
+		// 一个字节都还没发出去（首拉就失败）：保持与旧实现一致的错误语义。
+		c.String(http.StatusBadGateway, "音频拉取失败: %s", err.Error())
+		return
+	}
+	// 响应头已经发出：只能中止连接，让客户端判定「传输不完整」并自己重试。
+	// 保留 .part 分片，下一次请求会走续传路径。
+	panic(http.ErrAbortHandler)
+}
+
+// readerAudioFetchFunc 把「带换票重试的媒体拉取」适配成下载器需要的 fetcher。
+func readerAudioFetchFunc(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	bookID, rawURL string,
+	headers map[string]string,
+) reader.AudioRangeFetcher {
+	return func(rangeHeader string) (*http.Response, []byte, error) {
+		// 只有整段请求才需要嗅探响应体（判 HLS/错误页）；续传拿到的是 206
+		// 二进制分片，读了还得再补写一次，没必要。
+		out, fetchErr := fetchReaderMediaResilient(ctx, svc, book, rawURL, rangeHeader, headers, rangeHeader == "")
+		if fetchErr != nil {
+			if isReaderMediaNoRetry(fetchErr) {
+				return nil, nil, &reader.NoRetryError{Err: fetchErr}
+			}
+			return nil, nil, fetchErr
+		}
+		return out.resp, out.head, nil
+	}
+}
+
+// serveCachedReaderAudio 用 http.ServeContent 下发本地音轨（自带 Range / 206 语义）。
+func serveCachedReaderAudio(c *gin.Context, f *os.File, info os.FileInfo, rawURL string) {
+	c.Header("Content-Type", readerAudioContentType(rawURL))
+	c.Header("Cache-Control", "private, max-age=604800")
+	http.ServeContent(c.Writer, c.Request, "audio"+readerAudioExt(rawURL), info.ModTime(), f)
+}
+
+// ensureCachedRemoteAudio 单飞下载：并发命中同一章时只回源一次。
+func ensureCachedRemoteAudio(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	bookID, rawURL string,
+	headers map[string]string,
+) (string, error) {
+	key := svc.Reader.RemoteAudioCachePath(bookID, rawURL)
+	if key == "" {
+		return "", fmt.Errorf("音频缓存目录不可用")
+	}
+	v, err, _ := readerAudioFetchGroup.Do(key, func() (any, error) {
+		if svc.Reader.HasCachedRemoteAudio(bookID, rawURL) {
+			return key, nil
+		}
+		if err := downloadReaderAudioToCache(ctx, svc, book, bookID, rawURL, headers); err != nil {
+			return nil, err
+		}
+		return key, nil
+	})
+	if err != nil {
+		return "", err
+	}
+	path, _ := v.(string)
+	if path == "" {
+		return "", fmt.Errorf("音频缓存不可用")
+	}
+	return path, nil
+}
+
+// downloadReaderAudioToCache 整段拉取并落盘，支持断点续传：
+// 上游 RST/超时后用 Range 从已写入的位置接着下，不再整段重下；
+// 只有字节数与上游声明的总长一致时才会生成正式缓存文件。
+func downloadReaderAudioToCache(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	bookID, rawURL string,
+	headers map[string]string,
+) error {
+	_, err := svc.Reader.DownloadRemoteAudio(ctx, bookID, rawURL, readerAudioCacheAttempts,
+		readerAudioFetchFunc(ctx, svc, book, bookID, rawURL, headers))
+	return err
+}
+
+// isReaderMediaNoRetry 判断这次失败是否「换个花样重试也没用」。
+// 用于让外层下载循环立刻收手，而不是把同一张被拒的票再打四遍。
+func isReaderMediaNoRetry(err error) bool {
+	if errors.Is(err, errReaderMediaStaleTicket) {
+		return true
+	}
+	var rejected *readerMediaRejectedError
+	return errors.As(err, &rejected)
+}
+
+// readerAudioExt 取音频地址的后缀（用于推断 Content-Type）。
+func readerAudioExt(rawURL string) string {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return ""
+	}
+	return strings.ToLower(path.Ext(u.Path))
+}
+
+// readerAudioContentType 按后缀给出 Content-Type：缓存文件统一存成 .audio，
+// 不能依赖 http.ServeContent 的嗅探，直接在响应头里写死。
+func readerAudioContentType(rawURL string) string {
+	switch readerAudioExt(rawURL) {
+	case ".mp3":
+		return "audio/mpeg"
+	case ".aac":
+		return "audio/aac"
+	case ".flac":
+		return "audio/flac"
+	case ".wav":
+		return "audio/wav"
+	case ".ogg", ".oga", ".opus":
+		return "audio/ogg"
+	default:
+		// .m4a / .m4b / .wma / .ape 以及无后缀地址：腾讯的听书直链都是 m4a。
+		return "audio/mp4"
 	}
 }
 
 // readerImageDecodeMaxBytes 需要服务端解密的单张图片上限。
 const readerImageDecodeMaxBytes = 32 << 20
 
+// readerMediaProbeBytes 媒体代理嗅探上游响应体用的前缀长度。
+//
+// 这个前缀同时用于三件事：判定 HLS 播放列表（#EXTM3U）、判定「其实是错误页」、
+// 以及把已读出的字节原样拼回响应体继续流式透传。
+const readerMediaProbeBytes = 64 << 10
+
+// readerMediaResult 一次媒体拉取的结果。
+type readerMediaResult struct {
+	resp *http.Response
+	// url 是本次真正请求的媒体地址（换过票时是新票），m3u8 重写要用它做 base。
+	url string
+	// head 是已从响应体读出的前缀（仅 200 的 GET 才有），调用方写响应时要先写它。
+	head []byte
+	// rejected 表示 200 的响应体其实是错误页（HTML/JSON 报错），不能喂给播放器。
+	rejected bool
+}
+
+// fetchReaderMedia 拉取媒体，并在「签名票失效」时换票重试一次。
+//
+// 听书源的播放地址是第三方中转现签的 CDN 直链（vkey/uid 带时效），票被上游判掉时
+// 有两种表现，这里都要兜住：
+//
+//	① 空的 401：没有 Content-Type、没有 body（腾讯 CDN 对无效 vkey/uid 的固定回答）；
+//	② 200 + HTML/JSON 错误页：中转自己出错时把它的报错页当成媒体回给我们。
+//
+// 旧行为是两种都原样透传给播放器：① 变成连续多个 401（播放器重试的是同一个
+// 必然失败的地址），② 变成 ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED（19 个
+// extractor 一个都不认）。两者的根因都是「这张票已经不能用了」，所以统一处理成
+// 回源换一张新票再拉：
+//
+//   - 换票成功 → 用新地址重拉，新票同时写回章节缓存，后续请求自然有效；
+//   - 地址不属于可换票的音轨（漫画图片防盗链的 403 等）→ 原样透传上游状态，
+//     不改变原有行为；
+//   - 该换票但换不到、或换票后依然不可用 → 返回错误，由调用方给出明确文案，
+//     而不是让播放器对着必然失败的地址反复重试。
+//
+// readerMediaRejectedError 上游拒绝了这张票，继续走同一条重试路径不会有进展。
+//
+//	status    —— 上游状态码（401/403/410）
+//	refreshed —— 这次拒绝发生在「已经换过一张新票」之后
+//	message   —— 对外文案（留空时按状态码生成）
+//
+// 上游的拒绝常常成批出现（几分钟一波，随后自己恢复）：换票拿到的是新票，但
+// 同一时刻仍被同一个状态码挡回。连续两轮都这样时立刻停止重试——继续重试只会
+// 让播放器多等十几秒，结果并不会更好。
+type readerMediaRejectedError struct {
+	status    int
+	refreshed bool
+	message   string
+}
+
+func (e *readerMediaRejectedError) Error() string {
+	if e.message != "" {
+		return e.message
+	}
+	return fmt.Sprintf("音源暂时被上游拒绝（HTTP %d），请稍后重试或换源", e.status)
+}
+
+// errReaderMediaStaleTicket 换票没有拿到新票（书源还是给回同一张、或干脆给不出），
+// 再重试同一个书源不会有不同结果。具体原因由外层用 %w 串上。
+var errReaderMediaStaleTicket = errors.New("音源签名失效且重新取票失败")
+
+func fetchReaderMedia(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	rawURL, rangeHeader string,
+	options map[string]string,
+	probeBody bool,
+) (*readerMediaResult, error) {
+	// 上游 CDN 在并发/跨境链路上偶发 reset 连接（实测同一章重试即可成功），
+	// 探测阶段读到一半断开不能直接判死，先按退避重试几次。
+	out, refreshable, err := fetchReaderMediaWithRetry(ctx, svc, book, rawURL, rangeHeader, options, probeBody)
+	if err != nil || !refreshable {
+		return out, err
+	}
+	fresh, canRefresh, refreshErr := svc.Reader.RefreshMediaURL(ctx, book, rawURL)
+	if !canRefresh {
+		// 换不动（漫画图片防盗链的 403 等）：原样透传上游状态，保持既有行为。
+		// 但有两类失败例外——它们透传给播放器毫无意义（播放器只会一直重试
+		// 同一个必然失败的地址，或者把网页当成音频），改成明确错误让前端提示。
+		switch {
+		case out.rejected:
+			_ = out.resp.Body.Close()
+			return nil, fmt.Errorf("音源返回了非媒体内容（%s），请稍后重试或换源",
+				strings.TrimSpace(out.resp.Header.Get("Content-Type")))
+		case out.resp.StatusCode == http.StatusUnauthorized:
+			_, _ = io.Copy(io.Discard, io.LimitReader(out.resp.Body, 1<<16))
+			_ = out.resp.Body.Close()
+			return nil, &readerMediaRejectedError{
+				status:  http.StatusUnauthorized,
+				message: "音源签名失效（上游 401 拒绝），请稍后重试或换源",
+			}
+		}
+		return out, nil
+	}
+	// 换得动就必须先释放这张失败响应的连接，再发新请求。
+	_, _ = io.Copy(io.Discard, io.LimitReader(out.resp.Body, 1<<16))
+	_ = out.resp.Body.Close()
+	if refreshErr != nil {
+		return nil, fmt.Errorf("%w: %v", errReaderMediaStaleTicket, refreshErr)
+	}
+	retried, _, retryErr := fetchReaderMediaOnce(ctx, svc, book, fresh, rangeHeader, options, probeBody)
+	if retryErr != nil {
+		return nil, retryErr
+	}
+	if retried.rejected {
+		_ = retried.resp.Body.Close()
+		return nil, &readerMediaRejectedError{
+			status:    retried.resp.StatusCode,
+			refreshed: true,
+			message:   "音源换票后仍返回非媒体内容，请稍后重试或换源",
+		}
+	}
+	if reader.MediaNeedsRefresh(retried.resp.StatusCode) {
+		status := retried.resp.StatusCode
+		_ = retried.resp.Body.Close()
+		return nil, &readerMediaRejectedError{status: status, refreshed: true}
+	}
+	return retried, nil
+}
+
+// fetchReaderMediaResilient 在 fetchReaderMedia（已含一次换票）之上再包一层。
+//
+// 跨境 CDN 判掉签名票是概率性的：换一张票往往就能取到，而旧实现只换一次，
+// 第二次失败直接把 502 交给播放器。这里最多再重来 readerMediaReissueAttempts 轮，
+// 每轮都会作废章节缓存、重新回源签票。
+//
+// 但"没有进展"的失败会提前收手，否则用户要对着转圈干等三十多秒：
+//   - 换票拿不到新票（errReaderMediaStaleTicket）→ 立即结束；
+//   - 换过票仍是同一个拒绝状态码 → 两轮即结束（见 readerMediaRejectedError）。
+func fetchReaderMediaResilient(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	rawURL, rangeHeader string,
+	options map[string]string,
+	probeBody bool,
+) (*readerMediaResult, error) {
+	var lastErr error
+	lastRejected := 0
+	for attempt := 1; attempt <= readerMediaReissueAttempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			case <-time.After(readerMediaReissueDelay * time.Duration(attempt-1)):
+			}
+		}
+		out, err := fetchReaderMedia(ctx, svc, book, rawURL, rangeHeader, options, probeBody)
+		if err == nil {
+			if out == nil || out.resp == nil {
+				lastErr = fmt.Errorf("音源响应为空")
+				continue
+			}
+			if !out.rejected && !reader.MediaNeedsRefresh(out.resp.StatusCode) {
+				return out, nil
+			}
+			status := out.resp.StatusCode
+			_ = out.resp.Body.Close()
+			lastErr = &readerMediaRejectedError{status: status, refreshed: true}
+		} else {
+			lastErr = err
+			if ctx.Err() != nil {
+				return nil, err
+			}
+			if errors.Is(err, errReaderMediaStaleTicket) {
+				return nil, err
+			}
+		}
+		var rejected *readerMediaRejectedError
+		if errors.As(lastErr, &rejected) {
+			// 没有换票空间的拒绝：原样重试同一张票没有意义。
+			if !rejected.refreshed {
+				return nil, lastErr
+			}
+			// 换过票还是同一个状态码：上游这几分钟就是不放行。
+			if lastRejected == rejected.status {
+				return nil, lastErr
+			}
+			lastRejected = rejected.status
+		}
+	}
+	return nil, lastErr
+}
+
+// readerMediaProbeAttempts 探测阶段遇到连接中断（reset/EOF）的最大尝试次数。
+//
+// 上游 CDN（腾讯 CDN 的跨境边缘）在并发或长传输时会直接 RST 连接，同一章
+// 重试一次往往就好。以前这里读 body 失败就直接回 502，把一次可恢复的抖动
+// 变成了「这本书播不了」。
+const readerMediaProbeAttempts = 3
+
+// readerMediaProbeRetryDelay 探测重试的退避基数。
+const readerMediaProbeRetryDelay = 300 * time.Millisecond
+
+// readerMediaProbeError 探测阶段的可重试错误（连接被 reset / 提前 EOF）。
+type readerMediaProbeError struct{ err error }
+
+func (e *readerMediaProbeError) Error() string { return e.err.Error() }
+func (e *readerMediaProbeError) Unwrap() error { return e.err }
+
+// fetchReaderMediaWithRetry 探测阶段按退避重试，只对「连接中断」类错误重试：
+// 上游明确回了 4xx 时重试同一张票没有意义（那是换票流程的事）。
+func fetchReaderMediaWithRetry(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	rawURL, rangeHeader string,
+	options map[string]string,
+	probeBody bool,
+) (*readerMediaResult, bool, error) {
+	var lastErr error
+	for attempt := 1; attempt <= readerMediaProbeAttempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				return nil, false, ctx.Err()
+			case <-time.After(readerMediaProbeRetryDelay * time.Duration(attempt-1)):
+			}
+		}
+		out, refreshable, err := fetchReaderMediaOnce(ctx, svc, book, rawURL, rangeHeader, options, probeBody)
+		if err == nil {
+			return out, refreshable, nil
+		}
+		var probeErr *readerMediaProbeError
+		if !errors.As(err, &probeErr) {
+			return nil, false, err
+		}
+		lastErr = err
+	}
+	return nil, false, lastErr
+}
+
+// fetchReaderMediaOnce 发一次媒体请求并做可用性判定。
+//
+// 返回的 refreshable 表示「这次失败值得换一张签名票再试」：
+// 上游 401/403/410，或 200 但响应体其实是错误页（详见 fetchReaderMedia 的说明）。
+// rejected 表示「200 但内容不是媒体」——调用方据此在无法换票时报明确错误，
+// 而不是把网页喂给播放器。
+func fetchReaderMediaOnce(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	rawURL, rangeHeader string,
+	options map[string]string,
+	probeBody bool,
+) (*readerMediaResult, bool, error) {
+	resp, err := svc.Reader.FetchMediaWithOptions(ctx, book, rawURL, rangeHeader, options)
+	if err != nil {
+		return nil, false, err
+	}
+	if reader.MediaNeedsRefresh(resp.StatusCode) {
+		return &readerMediaResult{resp: resp, url: rawURL}, true, nil
+	}
+	if !probeBody || resp.StatusCode != http.StatusOK {
+		return &readerMediaResult{resp: resp, url: rawURL}, false, nil
+	}
+	// 先读一小段判断是不是错误页/播放列表；不是就原样拼回去继续流式透传。
+	head, readErr := io.ReadAll(io.LimitReader(resp.Body, readerMediaProbeBytes))
+	if readErr != nil {
+		_ = resp.Body.Close()
+		// 连接被 reset / 提前 EOF 属于上游抖动，交给上层退避重试。
+		return nil, false, &readerMediaProbeError{err: fmt.Errorf("读取媒体响应失败: %w", readErr)}
+	}
+	rejected := readerMediaPayloadRejected(head, resp.Header.Get("Content-Type"))
+	return &readerMediaResult{resp: resp, url: rawURL, head: head, rejected: rejected}, rejected, nil
+}
+
+// readerMediaPayloadRejected 判断上游 200 响应体其实是错误页而不是媒体。
+//
+// 直链失效的另一个变种：CDN/中转不返回 4xx，而是回一段 HTML 错误页或 JSON
+// 报错（Content-Type 是 text/html、application/json）。这类字节喂给播放器，
+// ExoPlayer 的 19 个 extractor 全都不认，报出来的是
+// ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED —— 看起来像「格式不支持」，
+// 实际是「拿到了一张网页」。这里按 Content-Type + 首字符识别出来，直接判失败。
+func readerMediaPayloadRejected(head []byte, contentType string) bool {
+	if len(head) == 0 {
+		return false
+	}
+	lower := strings.ToLower(contentType)
+	errish := strings.Contains(lower, "html") ||
+		strings.Contains(lower, "json") ||
+		strings.HasPrefix(lower, "text/")
+	if !errish {
+		return false
+	}
+	trimmed := bytes.TrimSpace(head)
+	if len(trimmed) == 0 {
+		return false
+	}
+	switch trimmed[0] {
+	case '<', '{', '[':
+		return true
+	default:
+		return false
+	}
+}
+
 // isMediaPlaylistRequest 判断响应是否可能已是 HLS 播放列表。
 // 播放列表太小、不该走图片解密分支（书源的 imageDecode 只会用于图片）。
 func isMediaPlaylistRequest(resp *http.Response) bool {
@@ -1022,7 +1686,28 @@ func readerLocalAudioHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+// readerContentOptions 从查询参数解析正文下发的可选项。
+//
+// 目前只有 `media` 一个维度：
+//   - 不传（网页端）：媒体全部走服务端签名代理，与历史行为一致；
+//   - `media=direct`：书源开启直连时保留上游地址，由客户端自取；
+//   - `media=proxy`：本次强制代理，给客户端直连失败时的退路。
+func readerContentOptions(c *gin.Context) reader.ContentOptions {
+	switch strings.ToLower(strings.TrimSpace(c.Query("media"))) {
+	case "direct":
+		return reader.ContentOptions{MediaDirect: true}
+	case "proxy":
+		return reader.ContentOptions{ForceProxy: true}
+	default:
+		return reader.ContentOptions{}
+	}
+}
+
 // readerBookContentHandler 书架维度正文（服务端应用替换净化规则）。
+//
+// media=direct 是客户端（Android App）专用的可选能力：媒体地址保留上游原始
+// 地址并由客户端自行下载，服务端只下发所需请求头。不传该参数（网页端）时
+// 行为与历史版本完全一致。
 func readerBookContentHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		chapter, err := strconv.Atoi(c.DefaultQuery("chapter", "0"))
@@ -1031,7 +1716,8 @@ func readerBookContentHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		userID := c.GetString(middleware.CtxUserID)
-		content, err := svc.Reader.GetContentForBook(c.Request.Context(), userID, c.Param("id"), chapter)
+		opts := readerContentOptions(c)
+		content, err := svc.Reader.GetContentForBook(c.Request.Context(), userID, c.Param("id"), chapter, opts)
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
@@ -1044,13 +1730,14 @@ func readerBookContentHandler(svc *service.Container) gin.HandlerFunc {
 //
 // 请求 {chapter_indexes:[...], apply_replace:bool}：单章失败不中断整批，
 // 返回每章内容与 hit/miss/failed 统计，供前端窗口预取与后续离线缓存。
+// 媒体通道同样按 media=direct 查询参数选择，默认（网页端）走服务端代理。
 func readerBookContentBatchHandler(svc *service.Container) gin.HandlerFunc {
-	var body struct {
-		ChapterIndexes []int `json:"chapter_indexes" binding:"required"`
-		// ApplyReplace 是否在服务端应用用户替换净化规则（默认 false，与单章接口一致）。
-		ApplyReplace bool `json:"apply_replace"`
-	}
 	return func(c *gin.Context) {
+		var body struct {
+			ChapterIndexes []int `json:"chapter_indexes" binding:"required"`
+			// ApplyReplace 是否在服务端应用用户替换净化规则（默认 false，与单章接口一致）。
+			ApplyReplace bool `json:"apply_replace"`
+		}
 		if err := c.ShouldBindJSON(&body); err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "chapter_indexes 不能为空"})
 			return
@@ -1060,7 +1747,7 @@ func readerBookContentBatchHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		userID := c.GetString(middleware.CtxUserID)
-		result, err := svc.Reader.GetContentBatch(c.Request.Context(), userID, c.Param("id"), body.ChapterIndexes, body.ApplyReplace)
+		result, err := svc.Reader.GetContentBatch(c.Request.Context(), userID, c.Param("id"), body.ChapterIndexes, body.ApplyReplace, readerContentOptions(c))
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return

internal/handler/routes_authenticated_core.go

@@ -36,6 +36,9 @@ func registerAuthedLibraryRoutes(authed *gin.RouterGroup, svc *service.Container
 	authed.GET("/libraries", listLibrariesHandler(svc))
 	authed.POST("/libraries", middleware.AdminRequired(), createLibraryHandler(svc))
 	authed.GET("/libraries/:id", getLibraryHandler(svc))
+	// 服务端生成的媒体库封面（成员海报拼图），Web / App / Emby 共用同一份。
+	authed.GET("/libraries/:id/cover", libraryCoverHandler(svc))
+	authed.HEAD("/libraries/:id/cover", libraryCoverHandler(svc))
 	authed.PATCH("/libraries/:id", middleware.AdminRequired(), updateLibraryHandler(svc))
 	authed.PUT("/libraries/reorder", middleware.AdminRequired(), reorderLibrariesHandler(svc))
 	authed.DELETE("/libraries/:id", middleware.AdminRequired(), deleteLibraryHandler(svc))

internal/handler/routes_authenticated_extras.go

@@ -74,6 +74,7 @@ func registerAuthedPlaybackExtraRoutes(authed *gin.RouterGroup, svc *service.Con
 	authed.GET("/playback/:id/info", playbackInfoHandler(svc))
 	authed.GET("/playback/:id/resume", playbackResumeHandler(svc))
 	authed.GET("/playback/:id/segments", playbackSegmentsHandler(svc))
+	authed.PUT("/playback/:id/segments", playbackSegmentsMarkHandler(svc))
 	authed.POST("/playback/:id/progress", playbackProgressHandler(svc))
 	authed.GET("/playback/:id/external-players", externalPlayersHandler(svc))
 	authed.GET("/playback/:id/external-url", externalURLHandler(svc))

internal/handler/watch_history.go

@@ -27,6 +27,10 @@ import (
 
 // historyListHandler returns the caller's history rows joined with the
 // matching media in a single response.
+//
+// include_media=0 只返回历史行本身。客户端判断「继续播放」指向哪一集时只
+// 需要 media_id/position_ms；带上整条 media 会让 300 条的响应从 ~40KB 涨到
+// ~420KB，手机链路上光传输就要十几秒，详情页的续播解析会被它拖住。
 func historyListHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		uid, _ := c.Get(middleware.CtxUserID)
@@ -34,6 +38,12 @@ func historyListHandler(svc *service.Container) gin.HandlerFunc {
 		if limit <= 0 || limit > 500 {
 			limit = 50
 		}
+		includeMedia := true
+		if raw := strings.TrimSpace(c.Query("include_media")); raw != "" {
+			if parsed, err := strconv.ParseBool(raw); err == nil {
+				includeMedia = parsed
+			}
+		}
 		items, err := svc.Playback.RecentHistory(c.Request.Context(), toString(uid), limit)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
@@ -42,7 +52,11 @@ func historyListHandler(svc *service.Container) gin.HandlerFunc {
 		visibility := mediaVisibilityForRequest(c, svc)
 		filtered := make([]service.HistoryItem, 0, len(items))
 		for _, item := range items {
+			// 可见性仍然按 media 判断，只是决定要不要把它写进响应。
 			if item.Media == nil || visibility.Allows(item.Media) {
+				if !includeMedia {
+					item.Media = nil
+				}
 				filtered = append(filtered, item)
 			}
 		}

internal/handler/watch_history_test.go

@@ -103,3 +103,75 @@ func TestHistoryContinueRemovesMissingMedia(t *testing.T) {
 		t.Fatalf("stale history rows remaining = %d, want 0", staleCount)
 	}
 }
+
+// include_media=0 只是不把 media 写进响应，行数和可见性判断都不变。
+func TestHistoryListCanOmitEmbeddedMedia(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.PlaybackHistory{}, &model.Media{}); err != nil {
+		t.Fatal(err)
+	}
+
+	media := model.Media{
+		Base:  model.Base{ID: "media-1"},
+		Title: "影片",
+		Path:  "/media/one.mkv",
+	}
+	if err := db.Create(&media).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.PlaybackHistory{
+		Base:       model.Base{ID: "history-1"},
+		UserID:     "user-1",
+		MediaID:    media.ID,
+		PositionMs: 30_000,
+		DurationMs: 120_000,
+		WatchedAt:  time.Now(),
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	repos := repository.New(db)
+	svc := &service.Container{
+		Log:      zap.NewNop(),
+		Repo:     repos,
+		Playback: service.NewPlaybackService(zap.NewNop(), repos),
+	}
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		c.Set(middleware.CtxUserID, "user-1")
+		c.Next()
+	})
+	router.GET("/watch-history", historyListHandler(svc))
+
+	type listRow struct {
+		MediaID string       `json:"media_id"`
+		Media   *model.Media `json:"media"`
+	}
+
+	full := httptest.NewRecorder()
+	router.ServeHTTP(full, httptest.NewRequest(http.MethodGet, "/watch-history?limit=10", nil))
+	var fullRows []listRow
+	if err := json.Unmarshal(full.Body.Bytes(), &fullRows); err != nil {
+		t.Fatal(err)
+	}
+	if len(fullRows) != 1 || fullRows[0].Media == nil || fullRows[0].Media.ID != media.ID {
+		t.Fatalf("default response should embed media: %s", full.Body.String())
+	}
+
+	lean := httptest.NewRecorder()
+	router.ServeHTTP(lean, httptest.NewRequest(http.MethodGet, "/watch-history?limit=10&include_media=0", nil))
+	var leanRows []listRow
+	if err := json.Unmarshal(lean.Body.Bytes(), &leanRows); err != nil {
+		t.Fatal(err)
+	}
+	if len(leanRows) != 1 || leanRows[0].MediaID != media.ID {
+		t.Fatalf("lean response should keep the row: %s", lean.Body.String())
+	}
+	if leanRows[0].Media != nil {
+		t.Fatalf("include_media=0 must not embed media: %s", lean.Body.String())
+	}
+}

internal/helper/http.go

@@ -7,6 +7,7 @@ import (
 	"compress/flate"
 	"compress/gzip"
 	"compress/zlib"
+	"crypto/tls"
 	"io"
 	"net/http"
 	"net/url"
@@ -88,10 +89,51 @@ func StripAcceptEncoding(h http.Header) {
 //
 // When useProxy is false, the client is created without proxy plumbing so
 // the request goes out direct, matching the user's checkbox intent.
+//
+// 注意 http.Client.Timeout 是「整个请求」的上限，包含读完响应体。书源的
+// 搜索/目录/正文都是小响应，30 秒足够；但同一个 client 也被用来流转发
+// 音频/视频（见 NewMediaHTTPClient），那里必须换一个没有整体超时的 client。
 func NewSiteHTTPClient(timeoutSeconds int, useProxy bool) *http.Client {
 	if timeoutSeconds <= 0 {
 		timeoutSeconds = 15
 	}
+	return &http.Client{
+		Timeout:   time.Duration(timeoutSeconds) * time.Second,
+		Transport: newSiteTransport(useProxy),
+	}
+}
+
+// NewMediaHTTPClient 拉取并转发媒体流（音频/视频/大图）的客户端。
+//
+// 为什么不能用 NewSiteHTTPClient：http.Client.Timeout 会覆盖「读完 body」这个
+// 阶段。一个 4MB 的 m4a 在跨境链路上很容易超过 30 秒，一旦超时，net/http 会
+// 直接掐断响应体，而调用方的 io.Copy 只是正常返回 —— 表现为**静默截断**
+// （播放器拿到半首歌，或判「格式不支持」），或者上游慢到 Do 本身报错 → 502。
+//
+// 为什么强制 HTTP/1.1：实测腾讯 CDN（vb.stream.tencentmusic.com）的 h2 边缘在
+// 长连接大文件上不按预期回 WINDOW_UPDATE，Go 的 http2 Transport 初始连接窗口
+// 是 1MiB，于是下载**稳定卡在 1MiB/2MiB/3MiB 整数倍**处断开；同一 URL 用
+// HTTP/1.1（wget、curl --http1.1）从头到尾都完整。因此媒体通路固定走 h1.1：
+// 音视频本来就没有「多路复用省请求」的收益，反而是流控 bug 的受害者。
+func NewMediaHTTPClient(useProxy bool) *http.Client {
+	tr := newSiteTransport(useProxy)
+	// 等响应头最多 90 秒：跨境 CDN 首包偶发要几十秒，但绝不能无上限挂着。
+	tr.ResponseHeaderTimeout = 90 * time.Second
+	// 媒体是长连接大流量，连接池开大一些，避免并发取图/拖动进度时互相排队。
+	tr.MaxIdleConns = 32
+	tr.MaxIdleConnsPerHost = 16
+	// 关闭 HTTP/2：见上面的流控说明。
+	tr.ForceAttemptHTTP2 = false
+	tr.TLSNextProto = map[string]func(string, *tls.Conn) http.RoundTripper{}
+	// 不复用连接：实测腾讯 CDN 的边缘在「同一条 keep-alive 连接上连续取多个
+	// 大对象」时会直接 RST 第二个请求的响应体（容器内 wget/curl 每次新建连接
+	// 就完全正常）。音视频请求本来就稀疏，为省一次 TLS 握手去冒截断风险不划算。
+	tr.DisableKeepAlives = true
+	return &http.Client{Transport: tr}
+}
+
+// newSiteTransport 书源请求共用的 Transport（媒体与规则请求配置一致的部分）。
+func newSiteTransport(useProxy bool) *http.Transport {
 	tr := &http.Transport{
 		MaxIdleConns:          16,
 		MaxIdleConnsPerHost:   4,
@@ -104,10 +146,7 @@ func NewSiteHTTPClient(timeoutSeconds int, useProxy bool) *http.Client {
 			return ProxyFromEnvironmentOrSystem(r)
 		}
 	}
-	return &http.Client{
-		Timeout:   time.Duration(timeoutSeconds) * time.Second,
-		Transport: tr,
-	}
+	return tr
 }
 
 // HTTPHeaderPresets returns a map of realistic browser HTTP headers.

internal/middleware/gzip.go

@@ -17,12 +17,24 @@ var gzipExcludedExtensions = []string{
 
 // apiGzipExcludedPrefixes 大文件流式传输（Range 语义）与 WS/SSE 长连接
 // 不参与 gzip：压缩会破坏 Range / 逐块推送语义。
+//
+// 阅读媒体代理（/api/reader/media、/api/reader/local/audio、
+// /api/reader/audio/transcode）同样必须排除，原因有两条：
+//   - 它们透传上游的 206 Partial Content。gin-contrib/gzip 在压缩时会删掉
+//     Content-Length，却把 Content-Range 原样留下，客户端看到的是「声明
+//     N 字节、实际收到 M 字节的 gzip 流」，自己发 Accept-Encoding 的播放器
+//     （ExoPlayer 不透明处理）直接判 ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED。
+//   - 音视频本来就是压缩格式，再 gzip 一遍只烧 CPU（3.5MB 的 m4a 压完还是
+//     3.5MB 量级），对带宽没有收益。
 var apiGzipExcludedPrefixes = []string{
 	"/api/stream/",
 	"/api/hls/",
 	"/api/img",
 	"/api/subtitles/",
 	"/api/strm/play/",
+	"/api/reader/media",
+	"/api/reader/local/audio",
+	"/api/reader/audio/transcode",
 	"/api/ws",
 	"/api/events",
 }

internal/middleware/gzip_test.go

@@ -70,6 +70,52 @@ func TestGzipAPIExcludesStreamPath(t *testing.T) {
 	}
 }
 
+// TestGzipAPIExcludesReaderMedia 阅读媒体代理必须排除在 gzip 之外。
+//
+// 它会透传 CDN 的 206 Partial Content。gin-contrib/gzip 压缩时会删掉
+// Content-Length 却保留 Content-Range，客户端看到「声明 N 字节、实收 M 字节」，
+// 自己发 Accept-Encoding 的播放器（ExoPlayer）直接判
+// ERROR_CODE_PARSING_CONTAINER_UNSUPPORTED，表现为「音频格式不支持」。
+func TestGzipAPIExcludesReaderMedia(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	api := router.Group("/api")
+	api.Use(GzipAPI())
+	// 用 206 + Content-Range 模拟真实的音频分段响应。
+	segment := func(c *gin.Context) {
+		c.Header("Content-Range", "bytes 0-99/100")
+		c.Data(http.StatusPartialContent, "audio/mp4", []byte(strings.Repeat("x", 4096)))
+	}
+	for _, path := range []string{
+		"/reader/media",
+		"/reader/local/audio",
+		"/reader/audio/transcode",
+	} {
+		api.GET(path, segment)
+	}
+
+	for _, path := range []string{
+		"/reader/media",
+		"/reader/local/audio",
+		"/reader/audio/transcode",
+	} {
+		req := httptest.NewRequest(http.MethodGet, "/api"+path+"?b=book&u=x&s=y", nil)
+		req.Header.Set("Accept-Encoding", "gzip")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if got := w.Header().Get("Content-Encoding"); got == "gzip" {
+			t.Errorf("%s 不该被 gzip（Range 语义会被破坏）", path)
+		}
+		if got := w.Header().Get("Content-Range"); got != "bytes 0-99/100" {
+			t.Errorf("%s 的 Content-Range 被破坏: %q", path, got)
+		}
+		if w.Body.Len() != 4096 {
+			t.Errorf("%s 响应体长度 = %d，期望 4096", path, w.Body.Len())
+		}
+	}
+}
+
 func TestGzipStaticCompressesAssets(t *testing.T) {
 	router := newGzipTestRouter()
 

internal/model/reader.go

@@ -38,6 +38,12 @@ type ReaderBookSource struct {
 	// NeedsBrowser 是否依赖 WebView/无头浏览器（webView 选项或 webjs 规则）。
 	// 服务端没有浏览器，这类源注定不可用，列表接口按需计算让前端能提前提示。
 	NeedsBrowser bool `gorm:"-" json:"needs_browser"`
+	// MediaDirect 允许客户端直连上游取实体媒体（音频/漫画图片），服务端只负责
+	// 解析地址与下发所需请求头。
+	//
+	// 只在客户端显式请求直连时生效（见 ContentOptions）：网页端不声明该能力，
+	// 行为与开启此字段前完全一致。
+	MediaDirect bool `gorm:"default:false" json:"media_direct"`
 }
 
 // ReaderSourceState 书源会话状态：对应 legado 中按书源 key 存储的

internal/repository/media_repository.go

@@ -237,10 +237,16 @@ func (r *MediaRepository) ListSeasonSiblings(ctx context.Context, m *model.Media
 	} else {
 		libraryID := strings.TrimSpace(m.LibraryID)
 		title := strings.TrimSpace(m.Title)
-		if libraryID == "" || title == "" || m.TMDbID <= 0 {
+		if libraryID == "" || title == "" {
 			return nil, nil
 		}
-		query = query.Where("library_id = ? AND title = ? AND tm_db_id = ?", libraryID, title, m.TMDbID)
+		// 没有 series_id 也没有 TMDb id 时，退到「同库 + 同标题」：手动标记的按季
+		// 传播是用户显式操作，同库同名已经足够可靠；而在缺 id 时直接放弃会让这个
+		// 功能在未刮削的库上完全不生效。
+		query = query.Where("library_id = ? AND title = ?", libraryID, title)
+		if m.TMDbID > 0 {
+			query = query.Where("tm_db_id = ?", m.TMDbID)
+		}
 	}
 	var rows []model.Media
 	if err := query.Find(&rows).Error; err != nil {

internal/repository/media_segment_repository.go

@@ -56,6 +56,23 @@ func (r *MediaSegmentRepository) ReplaceForMedia(ctx context.Context, mediaID, s
 	})
 }
 
+// ReplaceForMediaSourceKind swaps the segments of one (media, source, kind)
+// triple in a single transaction. Used by manual marking, where the user sets
+// one boundary at a time and must not disturb the other kinds.
+func (r *MediaSegmentRepository) ReplaceForMediaSourceKind(ctx context.Context, mediaID, source, kind string, rows []model.MediaSegment) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Unscoped().
+			Where("media_id = ? AND source = ? AND kind = ?", mediaID, source, kind).
+			Delete(&model.MediaSegment{}).Error; err != nil {
+			return err
+		}
+		if len(rows) == 0 {
+			return nil
+		}
+		return tx.Create(&rows).Error
+	})
+}
+
 // GetFetch returns the fetch ledger row for (media, source), or (nil, nil).
 func (r *MediaSegmentRepository) GetFetch(ctx context.Context, mediaID, source string) (*model.MediaSegmentFetch, error) {
 	var row model.MediaSegmentFetch

internal/service/cache_cleanup.go

@@ -74,22 +74,20 @@ type ImageCacheScope struct {
 	DropUnknownResizeVariants bool
 }
 
-// ImageCachePool 描述一个图片缓存池：范围 + 自身配额 + 保留时长。
+// ImageCachePool 描述一个图片缓存池：范围 + 自身配额。
 //
 // 分池的意义在于两类缓存的“可再生成本”完全不同：原图只是生成缩略图的原料，
 // 丢了可以重新回源；派生缩略图是客户端热路径真正读取的成品，重新生成代价高。
-// 因此原图配小配额、短保留，总量超限时也优先淘汰原图。
+// 因此原图配小配额，总量超限时也优先淘汰原图。
+//
+// 淘汰只看占用（配额头寸），不按文件年龄删除：缩略图生成成本高，只要磁盘还
+// 放得下就该留着，让再次浏览直接命中缓存。
 type ImageCachePool struct {
 	Name     string
 	Scopes   []ImageCacheScope
-	MaxBytes int64         // 0 = 不单独限制
-	MaxAge   time.Duration // 0 = 不按时间淘汰
+	MaxBytes int64 // 0 = 不单独限制
 }
 
-// imageFailMarkerMaxAge 是失败标记文件的保留时长：标记只用于观测/重试，
-// 过期即视为噪音清掉（不会因为标记残留而阻止重新抓取）。
-const imageFailMarkerMaxAge = 24 * time.Hour
-
 // tempImageCacheFile 报告文件名是否是下载/缩放过程中的临时文件。它们正在被
 // 并发写入，清理时必须跳过。
 func tempImageCacheFile(name string) bool {
@@ -182,12 +180,14 @@ func removeImageCacheEntry(entry imageCacheFileEntry, result *PruneImageCacheRes
 	_ = os.Remove(entry.path + ".fail")
 }
 
-// PruneImageCachePools 按池清理图片缓存：
-//  1. 删除超过池 MaxAge 的文件（原图按保留时长淘汰）；
-//  2. 池自身超过 MaxBytes 时按 mtime 淘汰到 80%（留水位，避免连续写入即触发）；
-//  3. 全部池合计超过 totalBytes 时，仍按“先原图、后派生”的顺序淘汰最旧文件，
+// PruneImageCachePools 按池清理图片缓存，只做占用淘汰：
+//  1. 池自身超过 MaxBytes 时按 mtime 淘汰到 80%（留水位，避免连续写入即触发）；
+//  2. 全部池合计超过 totalBytes 时，仍按“先原图、后派生”的顺序淘汰最旧文件，
 //     使总量上限始终是硬保证，同时让客户端热路径的缩略图活得更久。
 //
+// 不按文件年龄删除：过期即删会让一张几天前看过的海报重新解码（2 核机器上
+// 每张约 0.2 秒），代价远高于占着那几十 KB 磁盘。
+//
 // 传入的池顺序即总量超限时的淘汰优先级（排在前面的先被淘汰）。
 func PruneImageCachePools(pools []ImageCachePool, totalBytes int64) (PruneImageCacheResult, error) {
 	var result PruneImageCacheResult
@@ -207,16 +207,18 @@ func PruneImageCachePools(pools []ImageCachePool, totalBytes int64) (PruneImageC
 	}
 	result.RemainingBytes = result.TotalBytesBefore
 
-	// 过期的失败标记直接清掉：它们不计容量，只用于观测与重试。
-	cutoffMarkers := time.Now().Add(-imageFailMarkerMaxAge)
+	// 失败标记不计入容量：只清掉对应缓存文件已经不存在的孤儿标记（它们只是
+	// 观测/重试用的噪音，留着没有任何作用）。
 	for _, marker := range failMarkers {
-		if marker.modTime.Before(cutoffMarkers) {
-			_ = os.Remove(marker.path)
+		base := strings.TrimSuffix(marker.path, ".fail")
+		if _, err := os.Stat(base); err == nil {
+			continue
 		}
+		_ = os.Remove(marker.path)
 	}
 
-	now := time.Now()
 	deleted := make(map[string]bool, len(entries))
+
 	deleteEntry := func(entry imageCacheFileEntry) {
 		if deleted[entry.path] {
 			return
@@ -225,20 +227,7 @@ func PruneImageCachePools(pools []ImageCachePool, totalBytes int64) (PruneImageC
 		removeImageCacheEntry(entry, &result)
 	}
 
-	// 1. 按池保留时长淘汰（原图池）。
-	for i := range pools {
-		if pools[i].MaxAge <= 0 {
-			continue
-		}
-		cutoff := now.Add(-pools[i].MaxAge)
-		for _, entry := range entries {
-			if entry.pool == i && entry.modTime.Before(cutoff) {
-				deleteEntry(entry)
-			}
-		}
-	}
-
-	// 2. 池自身配额。
+	// 1. 池自身配额。
 	for i := range pools {
 		maxBytes := pools[i].MaxBytes
 		if maxBytes <= 0 {
@@ -263,7 +252,7 @@ func PruneImageCachePools(pools []ImageCachePool, totalBytes int64) (PruneImageC
 		}
 	}
 
-	// 3. 总量硬上限：跨池按淘汰优先级（池顺序）再按 mtime 淘汰。
+	// 2. 总量硬上限：跨池按淘汰优先级（池顺序）再按 mtime 淘汰。
 	if totalBytes > 0 && result.RemainingBytes > totalBytes {
 		target := totalBytes * 80 / 100
 		for _, entry := range evictionOrder(entries, deleted) {
@@ -357,11 +346,10 @@ func PruneImageCache(imagesDir string, maxSizeBytes int64) (PruneImageCacheResul
 // 第一个池是原图：历史版本平铺在 images/ 下的旧缓存也归入此池，升级后会被
 // 逐步淘汰；第二个池是派生成品（本地缩放结果 + 挂载 Emby 按尺寸返回的成品）。
 // 池顺序即总量超限时的淘汰优先级。
-func ImageCachePools(imagesDir string, originalsMaxBytes int64, originalsMaxAge time.Duration) []ImageCachePool {
+func ImageCachePools(imagesDir string, originalsMaxBytes int64) []ImageCachePool {
 	originals := ImageCachePool{
 		Name:     "originals",
 		MaxBytes: originalsMaxBytes,
-		MaxAge:   originalsMaxAge,
 		Scopes: []ImageCacheScope{
 			{Root: imagesDir, Recursive: false}, // 旧版平铺布局
 			{Root: filepath.Join(imagesDir, imageOriginalCacheSubdir), Recursive: true},
@@ -376,3 +364,199 @@ func ImageCachePools(imagesDir string, originalsMaxBytes int64, originalsMaxAge
 	}
 	return []ImageCachePool{originals, derived}
 }
+
+// CacheCleanupResult 是全缓存容量淘汰的统计。
+type CacheCleanupResult struct {
+	TotalFilesBefore int
+	TotalBytesBefore int64
+	DeletedFiles     int
+	FreedBytes       int64
+	RemainingBytes   int64
+	// FreedByPool 记录每个池释放的字节数，方便日志定位到底是哪类缓存占满了。
+	FreedByPool map[string]int64
+}
+
+// cacheEvictionEntry 是全局容量淘汰里的一个候选文件。
+type cacheEvictionEntry struct {
+	path    string
+	pool    string
+	size    int64
+	modTime time.Time
+}
+
+// cacheEvictionPoolOrder 是全局容量清理的固定优先级。
+// 顺序即“先清谁”：超限时前面的池会被整池清空，才会轮到后面的池。
+// reader-audio 不在其中：它由自身固定配额（当前 1GiB，见 reader 包的
+// audioMediaMaxBytes）在写入时独立淘汰。
+var cacheEvictionPoolOrder = []string{
+	"hls",
+	"images",
+	"library-covers",
+}
+
+// cacheCleanupKeepPercent 是触发清理后回落到的水位（占上限的百分比）。
+// 留出余量，避免刚清完又被下一次写入立刻顶到上限。
+const cacheCleanupKeepPercent = 80
+
+// tempCacheFile 判断文件名是否是缓存写入中的临时产物。这些文件正在被并发
+// 写入，容量统计和清理都应跳过。
+func tempCacheFile(name string) bool {
+	if tempImageCacheFile(name) {
+		return true
+	}
+	if strings.HasSuffix(name, ".part") {
+		return true
+	}
+	// 各缓存目录的原子写入临时文件前缀：.content- / .cover- / .audio- / .js-cache-。
+	return strings.HasPrefix(name, ".content-") ||
+		strings.HasPrefix(name, ".cover-") ||
+		strings.HasPrefix(name, ".audio-") ||
+		strings.HasPrefix(name, ".js-cache-")
+}
+
+// collectCachePoolFiles 递归收集一个普通缓存池里的候选文件，按 mtime 从旧到新。
+func collectCachePoolFiles(root, pool string) []cacheEvictionEntry {
+	if strings.TrimSpace(root) == "" {
+		return nil
+	}
+	var out []cacheEvictionEntry
+	_ = filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info == nil || info.IsDir() {
+			return nil
+		}
+		if !info.Mode().IsRegular() {
+			return nil
+		}
+		name := info.Name()
+		if tempCacheFile(name) || strings.HasSuffix(name, ".fail") {
+			return nil
+		}
+		out = append(out, cacheEvictionEntry{
+			path:    path,
+			pool:    pool,
+			size:    info.Size(),
+			modTime: info.ModTime(),
+		})
+		return nil
+	})
+	sort.Slice(out, func(i, j int) bool { return out[i].modTime.Before(out[j].modTime) })
+	return out
+}
+
+// collectImageCacheEntries 收集图片缓存候选文件。返回顺序沿用图片池的优先级：
+// 先原图、后派生成品，池内按 mtime 从旧到新。
+func collectImageCacheEntries(imagesDir string) []cacheEvictionEntry {
+	if strings.TrimSpace(imagesDir) == "" {
+		return nil
+	}
+	if _, err := os.Stat(imagesDir); err != nil {
+		return nil
+	}
+	pools := ImageCachePools(imagesDir, 0)
+	var entries []imageCacheFileEntry
+	var failMarkers []imageCacheFileEntry
+	for i, pool := range pools {
+		collectImageCachePoolFiles(pool, i, &entries, &failMarkers)
+	}
+	ordered := evictionOrder(entries, map[string]bool{})
+	out := make([]cacheEvictionEntry, 0, len(ordered))
+	for _, e := range ordered {
+		out = append(out, cacheEvictionEntry{
+			path:    e.path,
+			pool:    "images",
+			size:    e.size,
+			modTime: e.modTime,
+		})
+	}
+	return out
+}
+
+// removeEmptyDirsUnder 删除 root 下淘汰后留下的空子目录（不含 root 本身）。
+func removeEmptyDirsUnder(root string) {
+	if strings.TrimSpace(root) == "" {
+		return
+	}
+	if _, err := os.Stat(root); err != nil {
+		return
+	}
+	dirs := []string{}
+	_ = filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info == nil {
+			return nil
+		}
+		if info.IsDir() && path != root {
+			dirs = append(dirs, path)
+		}
+		return nil
+	})
+	for i := len(dirs) - 1; i >= 0; i-- {
+		_ = os.Remove(dirs[i])
+	}
+}
+
+// PruneCache 按全局容量池清理磁盘缓存。
+//
+// 总量口径是 hls、images、library-covers 三个池之和；reader-audio 及正文缓存、
+// 书源文件缓存都不参与这里的总量计算——reader-audio 由自身固定配额（当前
+// 1GiB）在写入时淘汰，正文缓存和书源文件缓存另有自己的 TTL / 配额。
+// 超过 totalBytes 时严格按 hls → images → library-covers 的顺序淘汰最旧文件，
+// 直到回落到上限的 80%。
+// originalsMaxBytes 是 images 原图池的独立子配额，在总量淘汰之后单独执行
+// （即使总量没超也会把原图压回配额）。
+func PruneCache(cacheDir string, totalBytes, originalsMaxBytes int64) (CacheCleanupResult, error) {
+	result := CacheCleanupResult{FreedByPool: map[string]int64{}}
+	if strings.TrimSpace(cacheDir) == "" {
+		return result, nil
+	}
+
+	imagesDir := filepath.Join(cacheDir, "images")
+	ordered := make([]cacheEvictionEntry, 0, 1024)
+	for _, name := range cacheEvictionPoolOrder {
+		if name == "images" {
+			ordered = append(ordered, collectImageCacheEntries(imagesDir)...)
+			continue
+		}
+		ordered = append(ordered, collectCachePoolFiles(filepath.Join(cacheDir, name), name)...)
+	}
+
+	result.TotalFilesBefore = len(ordered)
+	for _, entry := range ordered {
+		result.TotalBytesBefore += entry.size
+	}
+	result.RemainingBytes = result.TotalBytesBefore
+
+	// 1. 全局总量：严格按池优先级淘汰，直到回落到水位。
+	if totalBytes > 0 && result.RemainingBytes > totalBytes {
+		target := totalBytes * cacheCleanupKeepPercent / 100
+		for _, entry := range ordered {
+			if result.RemainingBytes <= target {
+				break
+			}
+			if err := os.Remove(entry.path); err != nil {
+				continue
+			}
+			result.DeletedFiles++
+			result.FreedBytes += entry.size
+			result.RemainingBytes -= entry.size
+			result.FreedByPool[entry.pool] += entry.size
+			_ = os.Remove(entry.path + ".fail")
+		}
+	}
+
+	// 2. 图片原图子配额独立于总量：即使总量没超，也要把原图压回自己的配额，
+	//    同时清掉旧命名变体和孤儿失败标记。
+	if _, err := os.Stat(imagesDir); err == nil {
+		pools := ImageCachePools(imagesDir, originalsMaxBytes)
+		if sub, err := PruneImageCachePools(pools, 0); err == nil {
+			result.DeletedFiles += sub.DeletedFiles
+			result.FreedBytes += sub.FreedBytes
+			result.RemainingBytes -= sub.FreedBytes
+			result.FreedByPool["images"] += sub.FreedBytes
+		}
+	}
+
+	for _, name := range cacheEvictionPoolOrder {
+		removeEmptyDirsUnder(filepath.Join(cacheDir, name))
+	}
+	return result, nil
+}

internal/service/cache_cleanup_pools_test.go

@@ -9,7 +9,7 @@ import (
 	"time"
 )
 
-// writePoolFile ?????????????????????????
+// writePoolFile ??????????????? mtime ???????
 func writePoolFile(t *testing.T, path string, size int, modTime time.Time) {
 	t.Helper()
 	if err := os.MkdirAll(filepath.Dir(path), 0o750); err != nil {
@@ -39,42 +39,38 @@ func mustExist(t *testing.T, path string) {
 	}
 }
 
-// currentVariantPath ????????????????.<??x<??q<??>.img??
-// ??????????????????????????
+// currentVariantPath ???????????????????
+// <64 ????>.<?>x<?>q<??>.img
 func currentVariantPath(dir, keyChar string, width, height, quality int) string {
 	key := strings.Repeat(keyChar, sha256HexLength)
 	return filepath.Join(dir, fmt.Sprintf("%s.%dx%dq%d.img", key, width, height, quality))
 }
 
-// TestPruneImageCachePoolsOriginalTTL ????????????????????
-// ?? TTL ??????????????????????
-func TestPruneImageCachePoolsOriginalTTL(t *testing.T) {
+// TestPruneImageCachePoolsKeepsOldFilesUnderQuota ????????????
+// ???????????????????????? / TTL ????
+func TestPruneImageCachePoolsKeepsOldFilesUnderQuota(t *testing.T) {
 	imagesDir := t.TempDir()
 	now := time.Now()
 
-	stale := filepath.Join(imagesDir, imageOriginalCacheSubdir, "stale-original")
-	fresh := filepath.Join(imagesDir, imageOriginalCacheSubdir, "fresh-original")
-	thumb := currentVariantPath(filepath.Join(imagesDir, imageResizeCacheSubdir), "b", 480, 600, 80)
-	writePoolFile(t, stale, 400, now.Add(-8*24*time.Hour))
-	writePoolFile(t, fresh, 400, now.Add(-1*time.Hour))
-	// ??????????TTL ????
-	writePoolFile(t, thumb, 400, now.Add(-8*24*time.Hour))
+	oldOriginal := filepath.Join(imagesDir, imageOriginalCacheSubdir, "old-original")
+	oldThumb := currentVariantPath(filepath.Join(imagesDir, imageResizeCacheSubdir), "b", 480, 600, 80)
+	writePoolFile(t, oldOriginal, 400, now.Add(-90*24*time.Hour))
+	writePoolFile(t, oldThumb, 400, now.Add(-90*24*time.Hour))
 
-	pools := ImageCachePools(imagesDir, 0, 7*24*time.Hour)
+	pools := ImageCachePools(imagesDir, 0)
 	res, err := PruneImageCachePools(pools, 100*1024*1024)
 	if err != nil {
 		t.Fatalf("prune failed: %v", err)
 	}
-	if res.DeletedFiles != 1 {
-		t.Fatalf("deleted files = %d, want 1", res.DeletedFiles)
+	if res.DeletedFiles != 0 {
+		t.Fatalf("deleted files = %d, want 0 (age must not trigger deletion)", res.DeletedFiles)
 	}
-	mustNotExist(t, stale)
-	mustExist(t, fresh)
-	mustExist(t, thumb)
+	mustExist(t, oldOriginal)
+	mustExist(t, oldThumb)
 }
 
 // TestPruneImageCachePoolsEvictsOriginalsBeforeDerived ????????????
-// ????????????????????
+// ????????????????
 func TestPruneImageCachePoolsEvictsOriginalsBeforeDerived(t *testing.T) {
 	imagesDir := t.TempDir()
 	now := time.Now()
@@ -82,13 +78,13 @@ func TestPruneImageCachePoolsEvictsOriginalsBeforeDerived(t *testing.T) {
 	original := filepath.Join(imagesDir, imageOriginalCacheSubdir, "original")
 	rendition := filepath.Join(imagesDir, imageRenditionCacheSubdir, "rendition")
 	thumb := currentVariantPath(filepath.Join(imagesDir, imageResizeCacheSubdir), "c", 480, 600, 80)
-	// ?????????????????
+	// ?????????????????????????
 	writePoolFile(t, original, 1024*1024, now.Add(-72*time.Hour))
 	writePoolFile(t, rendition, 1024*1024, now.Add(-2*time.Hour))
 	writePoolFile(t, thumb, 1024*1024, now.Add(-1*time.Hour))
 
-	pools := ImageCachePools(imagesDir, 0, 0)
-	// ?? 3MB????2.4MB -> ????? 1.92MB??
+	pools := ImageCachePools(imagesDir, 0)
+	// ?? 3MB??? 2.4MB -> ??? 1.92MB ???
 	res, err := PruneImageCachePools(pools, 2*1024*1024+400*1024)
 	if err != nil {
 		t.Fatalf("prune failed: %v", err)
@@ -104,8 +100,8 @@ func TestPruneImageCachePoolsEvictsOriginalsBeforeDerived(t *testing.T) {
 	}
 }
 
-// TestPruneImageCachePoolsOriginalQuotaKeepsDerived ????????????
-// ??????????????
+// TestPruneImageCachePoolsOriginalQuotaKeepsDerived ???????????
+// ????????????
 func TestPruneImageCachePoolsOriginalQuotaKeepsDerived(t *testing.T) {
 	imagesDir := t.TempDir()
 	now := time.Now()
@@ -117,8 +113,8 @@ func TestPruneImageCachePoolsOriginalQuotaKeepsDerived(t *testing.T) {
 	writePoolFile(t, newOriginal, 800, now.Add(-1*time.Hour))
 	writePoolFile(t, thumb, 800, now.Add(-2*time.Hour))
 
-	// ???? 1000 ??????????1600 -> ????800????? 1 ????
-	pools := ImageCachePools(imagesDir, 1000, 0)
+	// ???? 1000??? 1600 ?? -> ??? 800??? 1 ???????
+	pools := ImageCachePools(imagesDir, 1000)
 	res, err := PruneImageCachePools(pools, 0)
 	if err != nil {
 		t.Fatalf("prune failed: %v", err)
@@ -131,24 +127,26 @@ func TestPruneImageCachePoolsOriginalQuotaKeepsDerived(t *testing.T) {
 	mustExist(t, thumb)
 }
 
-// TestPruneImageCachePoolsCleansFailMarkers ????????????????
-// ????????????????
+// TestPruneImageCachePoolsCleansFailMarkers ???????????????
+// ???????????????????????????????????
 func TestPruneImageCachePoolsCleansFailMarkers(t *testing.T) {
 	imagesDir := t.TempDir()
 	now := time.Now()
 
 	entry := filepath.Join(imagesDir, imageOriginalCacheSubdir, "entry")
 	entryMarker := entry + ".fail"
+	kept := filepath.Join(imagesDir, imageOriginalCacheSubdir, "kept")
+	keptMarker := kept + ".fail"
 	orphanMarker := filepath.Join(imagesDir, imageOriginalCacheSubdir, "orphan.fail")
-	freshMarker := filepath.Join(imagesDir, imageOriginalCacheSubdir, "fresh.fail")
 
-	writePoolFile(t, entry, 900, now.Add(-10*time.Hour))
-	writePoolFile(t, entryMarker, 35, now.Add(-10*time.Hour))
+	writePoolFile(t, entry, 900, now.Add(-2*time.Hour))
+	writePoolFile(t, entryMarker, 35, now.Add(-2*time.Hour))
+	writePoolFile(t, kept, 300, now.Add(-1*time.Hour))
+	writePoolFile(t, keptMarker, 35, now.Add(-1*time.Hour))
 	writePoolFile(t, orphanMarker, 35, now.Add(-48*time.Hour))
-	writePoolFile(t, freshMarker, 35, now.Add(-1*time.Minute))
 
-	// ???? 500????900 ?????????????????
-	pools := ImageCachePools(imagesDir, 500, 0)
+	// ???? 500??? 900+300=1200 ???? mtime ????? entry ? 400?
+	pools := ImageCachePools(imagesDir, 500)
 	res, err := PruneImageCachePools(pools, 0)
 	if err != nil {
 		t.Fatalf("prune failed: %v", err)
@@ -158,26 +156,27 @@ func TestPruneImageCachePoolsCleansFailMarkers(t *testing.T) {
 	}
 	mustNotExist(t, entry)
 	mustNotExist(t, entryMarker)
+	mustExist(t, kept)
+	mustExist(t, keptMarker)
 	mustNotExist(t, orphanMarker)
-	mustExist(t, freshMarker)
 }
 
-// TestPruneImageCachePoolsSkipsTemporaryFiles ????????????????
+// TestPruneImageCachePoolsSkipsTemporaryFiles ??????????????
 // ?????????????????
 func TestPruneImageCachePoolsSkipsTemporaryFiles(t *testing.T) {
 	imagesDir := t.TempDir()
 	tmp := filepath.Join(imagesDir, imageOriginalCacheSubdir, "img-1234.tmp")
 	writePoolFile(t, tmp, 4096, time.Now().Add(-48*time.Hour))
 
-	pools := ImageCachePools(imagesDir, 1, 0)
+	pools := ImageCachePools(imagesDir, 1)
 	if _, err := PruneImageCachePools(pools, 1); err != nil {
 		t.Fatalf("prune failed: %v", err)
 	}
 	mustExist(t, tmp)
 }
 
-// TestPruneImageCachePoolsDropsLegacyResizeVariants ????????.img????
-// ?????????????????????????????????????
+// TestPruneImageCachePoolsDropsLegacyResizeVariants ?????? .img ??
+// ???????????????????????????
 func TestPruneImageCachePoolsDropsLegacyResizeVariants(t *testing.T) {
 	imagesDir := t.TempDir()
 	resized := filepath.Join(imagesDir, imageResizeCacheSubdir)
@@ -188,7 +187,7 @@ func TestPruneImageCachePoolsDropsLegacyResizeVariants(t *testing.T) {
 	writePoolFile(t, current, 400, time.Now())
 	writePoolFile(t, other, 400, time.Now())
 
-	pools := ImageCachePools(imagesDir, 0, 0)
+	pools := ImageCachePools(imagesDir, 0)
 	res, err := PruneImageCachePools(pools, 0)
 	if err != nil {
 		t.Fatalf("prune failed: %v", err)
@@ -201,8 +200,8 @@ func TestPruneImageCachePoolsDropsLegacyResizeVariants(t *testing.T) {
 	}
 }
 
-// TestPruneImageCachePoolsCountsLegacyFlatLayout ??????images/ ????
-// ?????????????????
+// TestPruneImageCachePoolsCountsLegacyFlatLayout ???????images/ ???
+// ???????????????????????
 func TestPruneImageCachePoolsCountsLegacyFlatLayout(t *testing.T) {
 	imagesDir := t.TempDir()
 	legacy := filepath.Join(imagesDir, "legacy-flat-cache")
@@ -210,7 +209,8 @@ func TestPruneImageCachePoolsCountsLegacyFlatLayout(t *testing.T) {
 	writePoolFile(t, legacy, 900, time.Now().Add(-30*24*time.Hour))
 	writePoolFile(t, thumb, 900, time.Now().Add(-30*24*time.Hour))
 
-	pools := ImageCachePools(imagesDir, 0, 24*time.Hour)
+	// ???? 500??????????????????????????
+	pools := ImageCachePools(imagesDir, 500)
 	res, err := PruneImageCachePools(pools, 0)
 	if err != nil {
 		t.Fatalf("prune failed: %v", err)

internal/service/cache_cleanup_test.go

@@ -134,7 +134,7 @@ func TestPruneImageCache_ZeroOrNegativeLimit(t *testing.T) {
 	}
 }
 
-func TestSchedulerJobCleanImageCache(t *testing.T) {
+func TestSchedulerJobCleanCache(t *testing.T) {
 	cacheRoot := t.TempDir()
 	imagesDir := filepath.Join(cacheRoot, "images")
 	if err := os.MkdirAll(imagesDir, 0o750); err != nil {
@@ -148,15 +148,117 @@ func TestSchedulerJobCleanImageCache(t *testing.T) {
 
 	scheduler := NewSchedulerService(zap.NewNop(), nil, nil, nil, nil, nil, cacheRoot)
 	// Set limit to 1MB; our file is 2MB -> should be pruned
-	scheduler.SetImageCachePolicyProvider(func() ImageCachePolicy {
-		return ImageCachePolicy{TotalBytes: 1 * 1024 * 1024}
+	scheduler.SetCacheCleanupPolicyProvider(func() CacheCleanupPolicy {
+		return CacheCleanupPolicy{TotalBytes: 1 * 1024 * 1024}
 	})
 
-	if err := scheduler.jobCleanImageCache(context.Background()); err != nil {
-		t.Fatalf("jobCleanImageCache failed: %v", err)
+	if err := scheduler.jobCleanCache(context.Background()); err != nil {
+		t.Fatalf("jobCleanCache failed: %v", err)
 	}
 
 	if _, err := os.Stat(f); !os.IsNotExist(err) {
 		t.Fatalf("expected file to be pruned, got err=%v", err)
 	}
 }
+
+// TestPruneCacheEvictionOrder 验证总量超限时严格按
+// hls → images → library-covers 的顺序淘汰，且 reader-audio 不参与。
+func TestPruneCacheEvictionOrder(t *testing.T) {
+	cacheRoot := t.TempDir()
+	now := time.Now()
+
+	audio := filepath.Join(cacheRoot, "reader-audio", "old.mp3")
+	hls := filepath.Join(cacheRoot, "hls", "job", "seg.ts")
+	image := filepath.Join(cacheRoot, "images", "originals", "poster.jpg")
+	cover := filepath.Join(cacheRoot, "library-covers", "cover.jpg")
+	for _, p := range []string{audio, hls, image, cover} {
+		writePoolFile(t, p, 1024*1024, now.Add(-time.Hour))
+	}
+
+	// 计入总量的只有 hls+images+cover = 3MB，上限 2MB -> 回落到 1.6MB：
+	// 按顺序删 hls、images 两个文件即可；reader-audio 与封面都应保留。
+	res, err := PruneCache(cacheRoot, 2*1024*1024, 0)
+	if err != nil {
+		t.Fatalf("prune failed: %v", err)
+	}
+	if res.DeletedFiles != 2 {
+		t.Fatalf("deleted files = %d, want 2", res.DeletedFiles)
+	}
+	mustExist(t, audio)
+	mustNotExist(t, hls)
+	mustNotExist(t, image)
+	mustExist(t, cover)
+	if _, ok := res.FreedByPool["reader-audio"]; ok {
+		t.Fatalf("reader-audio must not be part of the global pool, got %+v", res.FreedByPool)
+	}
+	if res.FreedByPool["hls"] != 1024*1024 || res.FreedByPool["images"] != 1024*1024 {
+		t.Fatalf("unexpected per-pool stats: %+v", res.FreedByPool)
+	}
+}
+
+// TestPruneCacheLeavesReaderAudioAlone reader-audio 有独立的 1GB 写入时淘汰，
+// 不参与总容量统计：即使它单独就超过全局上限，全局任务也不应删它。
+func TestPruneCacheLeavesReaderAudioAlone(t *testing.T) {
+	cacheRoot := t.TempDir()
+	audio := filepath.Join(cacheRoot, "reader-audio", "book", "chapter.mp3")
+	writePoolFile(t, audio, 4*1024*1024, time.Now().Add(-time.Hour))
+
+	res, err := PruneCache(cacheRoot, 1*1024*1024, 0)
+	if err != nil {
+		t.Fatalf("prune failed: %v", err)
+	}
+	if res.DeletedFiles != 0 {
+		t.Fatalf("deleted files = %d, want 0", res.DeletedFiles)
+	}
+	if res.TotalBytesBefore != 0 {
+		t.Fatalf("reader-audio should not count toward total, got %d bytes", res.TotalBytesBefore)
+	}
+	mustExist(t, audio)
+}
+
+// TestPruneCacheAppliesOriginalsSubQuota 验证总量没超时，图片原图子配额仍然生效。
+func TestPruneCacheAppliesOriginalsSubQuota(t *testing.T) {
+	cacheRoot := t.TempDir()
+	now := time.Now()
+
+	oldOriginal := filepath.Join(cacheRoot, "images", "originals", "old.jpg")
+	newOriginal := filepath.Join(cacheRoot, "images", "originals", "new.jpg")
+	derived := currentVariantPath(filepath.Join(cacheRoot, "images", "resize"), "d", 480, 600, 80)
+	writePoolFile(t, oldOriginal, 800, now.Add(-2*time.Hour))
+	writePoolFile(t, newOriginal, 800, now.Add(-time.Hour))
+	writePoolFile(t, derived, 800, now.Add(-time.Hour))
+
+	// 总量上限很大（不触发全局淘汰），原图子配额 1000B -> 删到 800B。
+	res, err := PruneCache(cacheRoot, 100*1024*1024, 1000)
+	if err != nil {
+		t.Fatalf("prune failed: %v", err)
+	}
+	if res.DeletedFiles != 1 {
+		t.Fatalf("deleted files = %d, want 1", res.DeletedFiles)
+	}
+	mustNotExist(t, oldOriginal)
+	mustExist(t, newOriginal)
+	mustExist(t, derived)
+}
+
+// TestPruneCacheOldestFirstWithinPool 验证同一池内先删最旧的文件。
+func TestPruneCacheOldestFirstWithinPool(t *testing.T) {
+	cacheRoot := t.TempDir()
+	now := time.Now()
+
+	oldHLS := filepath.Join(cacheRoot, "hls", "job-a", "seg1.ts")
+	newHLS := filepath.Join(cacheRoot, "hls", "job-b", "seg1.ts")
+	writePoolFile(t, oldHLS, 1024*1024, now.Add(-2*time.Hour))
+	writePoolFile(t, newHLS, 1024*1024, now.Add(-time.Minute))
+
+	// 上限 1.25MB -> 回落水位 1MB：删掉最旧的 1MB 后正好达标。
+	res, err := PruneCache(cacheRoot, 1280*1024, 0)
+	if err != nil {
+		t.Fatalf("prune failed: %v", err)
+	}
+	if res.DeletedFiles != 1 {
+		t.Fatalf("deleted files = %d, want 1", res.DeletedFiles)
+	}
+	mustNotExist(t, oldHLS)
+	mustExist(t, newHLS)
+}

internal/service/emby_cache_invalidate_test.go

@@ -0,0 +1,254 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// resetEmbyInvalThrottle 清掉全局失效节流，让测试能断言「这一次调用到底有
+// 没有真的清缓存」。测试结束后恢复原值，避免影响同包其他用例。
+func resetEmbyInvalThrottle(t *testing.T) {
+	t.Helper()
+	embyInvalMu.Lock()
+	previous := embyInvalLast
+	embyInvalLast = time.Time{}
+	embyInvalMu.Unlock()
+	t.Cleanup(func() {
+		embyInvalMu.Lock()
+		embyInvalLast = previous
+		embyInvalMu.Unlock()
+	})
+}
+
+func newCachedTestEmbyService(t *testing.T) *EmbyService {
+	t.Helper()
+	svc := newTestEmbyService(t)
+	cache := NewRuntimeCacheService(&config.Config{}, zap.NewNop())
+	t.Cleanup(func() { _ = cache.Close() })
+	return svc.SetRuntimeCache(cache)
+}
+
+// TestRecordProgressKeepsEmbyPayloadCache 覆盖首页加载慢的核心回归点：
+// 播放期间客户端每 5-10 秒上报一次进度，如果每次都清空 media:emby:*，
+// 客户端刷新首页时 73 个媒体库的 Latest 会全部回源重建（生产环境实测
+// 首批 8-25s）。普通进度上报必须保留载荷缓存；只有「已看完」翻转才失效。
+func TestRecordProgressKeepsEmbyPayloadCache(t *testing.T) {
+	svc := newCachedTestEmbyService(t)
+	const mediaID = "ep-1"
+	media := model.Media{
+		Base:        model.Base{ID: mediaID},
+		Title:       "第 1 集",
+		Path:        `/media/tv/Show/Season 01/S01E01.mkv`,
+		DurationSec: 100,
+	}
+	if err := svc.repo.DB.Create(&media).Error; err != nil {
+		t.Fatalf("create media: %v", err)
+	}
+
+	key := svc.embyLatestCacheKey("user-1", "", 16)
+	svc.cache.SetJSONWithStale(t.Context(), key, embyLatestCacheValue{
+		Items: []map[string]any{{"Id": "cached-item"}},
+	}, time.Minute, time.Hour)
+
+	resetEmbyInvalThrottle(t)
+	// 60s / 100s：播放中途
+	if err := svc.RecordProgressWithSession(t.Context(), "user-1", mediaID, 600_000_000, 1_000_000_000, "session-1"); err != nil {
+		t.Fatalf("record progress: %v", err)
+	}
+	if _, stale, ok := svc.cachedLatestItemsWithStale(t.Context(), key); !ok || stale {
+		t.Fatal("普通进度上报不应让 Emby 列表载荷缓存失效")
+	}
+
+	resetEmbyInvalThrottle(t)
+	// 98s / 100s：进入片尾 30s 内的「已看完」区间
+	if err := svc.RecordProgressWithSession(t.Context(), "user-1", mediaID, 980_000_000, 1_000_000_000, "session-2"); err != nil {
+		t.Fatalf("record completed progress: %v", err)
+	}
+	if _, _, ok := svc.cachedLatestItemsWithStale(t.Context(), key); ok {
+		t.Fatal("看完状态翻转后应让 Emby 列表载荷缓存失效")
+	}
+}
+
+// TestFindSeriesGroupCachesSiblingVirtualSeries 覆盖 N+1 回归点：一次全表
+// 扫描算出了整库的剧集分组，若只缓存命中的那一部，同一页的 16 张卡片和
+// 16 张海报会各自重扫一遍 media 表。批量记忆后同批分组都应可命中。
+func TestFindSeriesGroupCachesSiblingVirtualSeries(t *testing.T) {
+	svc := newTestEmbyService(t)
+	lib := model.Library{Name: "剧集", Path: `/media/tv`, Type: "tv", Enabled: true}
+	if err := svc.repo.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+
+	shows := []string{"Alpha", "Bravo", "Charlie"}
+	rows := make([]model.Media, 0, len(shows)*2)
+	for _, show := range shows {
+		for ep := 1; ep <= 2; ep++ {
+			rows = append(rows, model.Media{
+				Base:       model.Base{ID: show + "-" + strconv.Itoa(ep)},
+				LibraryID:  lib.ID,
+				Title:      show,
+				Path:       fmt.Sprintf("/media/tv/%s/Season 01/S01E%02d.mkv", show, ep),
+				SeasonNum:  1,
+				EpisodeNum: ep,
+			})
+		}
+	}
+	for i := range rows {
+		if err := svc.repo.DB.Create(&rows[i]).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+
+	seriesIDs := map[string]string{}
+	for i := range rows {
+		if rows[i].EpisodeNum == 1 {
+			seriesIDs[rows[i].Title] = svc.seriesIDForMedia(t.Context(), &rows[i])
+		}
+	}
+	target, ok := seriesIDs["Alpha"]
+	if !ok {
+		t.Fatal("missing fixture series")
+	}
+	if _, found, err := svc.findSeriesGroup(t.Context(), target, ""); err != nil || !found {
+		t.Fatalf("findSeriesGroup(%s) = (%v, %v), want found", target, found, err)
+	}
+
+	for show, id := range seriesIDs {
+		if show == "Alpha" {
+			continue
+		}
+		if _, cached := svc.cachedSeriesGroup(id); !cached {
+			t.Fatalf("同一次扫描算出的 %s 应一并进入缓存，否则每张卡片/海报都会重扫整库", show)
+		}
+	}
+}
+
+// TestLatestPayloadKeepsStaleCopyForIdleClients 保证「最新添加」载荷在新鲜期
+// 之后仍有可用的陈旧副本：客户端空闲很久后再打开首页时，先拿陈旧结果并由
+// 后台重建，而不是让全部媒体库同时回源。
+func TestLatestPayloadKeepsStaleCopyForIdleClients(t *testing.T) {
+	svc := newCachedTestEmbyService(t)
+	key := svc.embyLatestCacheKey("user-1", "", 16)
+	svc.cache.SetJSONWithStale(t.Context(), key, embyLatestCacheValue{
+		Items: []map[string]any{{"Id": "stale-item"}},
+	}, time.Nanosecond, embyLatestStaleWindow)
+	time.Sleep(2 * time.Millisecond)
+
+	items, stale, ok := svc.cachedLatestItemsWithStale(t.Context(), key)
+	if !ok || !stale {
+		t.Fatalf("expected a stale hit, got ok=%v stale=%v", ok, stale)
+	}
+	if len(items) != 1 || items[0]["Id"] != "stale-item" {
+		t.Fatalf("unexpected stale payload: %#v", items)
+	}
+}
+
+// mediaScanCounter 统计真正落到 media 表上的查询次数，用来断言「整库数据
+// 只扫一次」：GORM 的 Trace 回调里能拿到最终 SQL。
+type mediaScanCounter struct {
+	logger.Interface
+	mu    sync.Mutex
+	scans int
+}
+
+func (c *mediaScanCounter) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error) {
+	sql, _ := fc()
+	if strings.Contains(sql, "FROM `media`") {
+		c.mu.Lock()
+		c.scans++
+		c.mu.Unlock()
+	}
+}
+
+func (c *mediaScanCounter) Scans() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.scans
+}
+
+// TestVirtualSeriesLookupsShareOneScan 覆盖冷启动风暴的回归点：客户端刷新
+// 首页时 73 个库的卡片和海报各自要一个虚拟 series 分组。修好之后，第一次
+// 扫描把整库分组都写进缓存，同一页剩下的查询都不该再落 SQL；随后一个不存在
+// 的虚拟 ID 也不该反复触发整库重扫。
+func TestVirtualSeriesLookupsShareOneScan(t *testing.T) {
+	counter := &mediaScanCounter{Interface: logger.Discard}
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: counter})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if sqlDB, err := db.DB(); err == nil {
+		sqlDB.SetMaxOpenConns(1)
+		t.Cleanup(func() { _ = sqlDB.Close() })
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	svc := NewEmbyService(&config.Config{}, zap.NewNop(), repository.New(db))
+
+	lib := model.Library{Name: "剧集", Path: `/media/tv`, Type: "tv", Enabled: true}
+	if err := svc.repo.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	shows := []string{"Alpha", "Bravo", "Charlie"}
+	rows := make([]model.Media, 0, len(shows)*2)
+	for _, show := range shows {
+		for ep := 1; ep <= 2; ep++ {
+			rows = append(rows, model.Media{
+				Base:       model.Base{ID: show + "-" + strconv.Itoa(ep)},
+				LibraryID:  lib.ID,
+				Title:      show,
+				Path:       fmt.Sprintf("/media/tv/%s/Season 01/S01E%02d.mkv", show, ep),
+				SeasonNum:  1,
+				EpisodeNum: ep,
+			})
+		}
+	}
+	for i := range rows {
+		if err := svc.repo.DB.Create(&rows[i]).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+	seriesIDs := map[string]string{}
+	for i := range rows {
+		if rows[i].EpisodeNum == 1 {
+			seriesIDs[rows[i].Title] = svc.seriesIDForMedia(t.Context(), &rows[i])
+		}
+	}
+
+	if _, found, err := svc.findSeriesGroup(t.Context(), seriesIDs["Alpha"], ""); err != nil || !found {
+		t.Fatalf("findSeriesGroup(Alpha) = (%v, %v), want found", found, err)
+	}
+	if got := counter.Scans(); got != 1 {
+		t.Fatalf("首次查询应恰好扫描 media 一次，实际 %d 次", got)
+	}
+
+	for _, show := range []string{"Bravo", "Charlie"} {
+		if _, found, err := svc.findSeriesGroup(t.Context(), seriesIDs[show], ""); err != nil || !found {
+			t.Fatalf("findSeriesGroup(%s) = (%v, %v), want found", show, found, err)
+		}
+	}
+	if got := counter.Scans(); got != 1 {
+		t.Fatalf("同批分组应命中缓存，不应再扫 media，实际累计 %d 次", got)
+	}
+
+	if _, found, err := svc.findSeriesGroup(t.Context(), embyVirtualSeriesPrefix+"missing", ""); err != nil || found {
+		t.Fatalf("未知虚拟 ID 应为 not found，实际 found=%v err=%v", found, err)
+	}
+	if got := counter.Scans(); got != 1 {
+		t.Fatalf("刚扫过整库后，未知 ID 不应重扫 media，实际累计 %d 次", got)
+	}
+}

internal/service/emby_compat.go

@@ -56,6 +56,17 @@ type EmbyService struct {
 	virtualSeries  map[string]embySeriesCacheEntry
 	virtualSeasons map[string]embySeasonCacheEntry
 	virtualArtwork map[string]embyArtworkCacheEntry
+	// virtualGroups 把「整库虚拟剧集分组」的扫描折叠成一次。
+	//
+	// 客户端刷新首页时会同时请求 73 个库的 Latest，每个库的卡片和海报都要
+	// 各自的虚拟 series 分组。不同剧的分组缓存键不同，singleflight 键也不同，
+	// 于是第一波请求会并发重扫整张 media 表（生产环境实测冷启动 14-17s）。
+	// 按用户折叠成一次扫描后，同一波请求共享结果并整批进缓存。
+	virtualGroups singleflight.Group
+	// virtualScanAt 记录每个用户最近一次整库扫描的时间，用于避免为同一个
+	// 不存在的 id 反复重扫（必须按用户区分：可见性不同，别人的快照不能当
+	// 自己的答案）。由 virtualMu 保护。
+	virtualScanAt map[string]time.Time
 
 	visibilityMu    sync.RWMutex
 	visibilityCache map[string]embyVisibilityCacheEntry
@@ -186,6 +197,15 @@ const (
 	embyVirtualSeriesCap  = 8000
 	embyVirtualSeasonCap  = 16000
 	embyVirtualArtworkCap = 24000
+	// embySeriesGroupBulkCacheEpisodes 限制一次批量记忆的剧集行数。
+	//
+	// 批量记忆把「一次扫描服务整页卡片 + 整页海报」的收益拿满，但同时让整库
+	// 剧集常驻内存。超过该量级时退回只缓存命中的那一部，避免大库吃光内存。
+	embySeriesGroupBulkCacheEpisodes = 8000
+	// embyVirtualScanGrace 是「刚做过整库虚拟剧集扫描」的保护窗口。窗口内再
+	// 请求一个不在缓存里的虚拟 series ID，直接按不存在处理，避免为同一个
+	// 未知 id 反复重扫整库。
+	embyVirtualScanGrace = 10 * time.Second
 	// Clients that already cached the 1x1 placeholder treat a stable tag as
 	// immutable. Virtual ids are the ones that served that placeholder, so
 	// only those tags get a suffix that forces a refetch.
@@ -325,8 +345,24 @@ func (e *EmbyService) Items(ctx context.Context, p ItemsParams) (map[string]any,
 		}
 	}
 
+	// 客户端刷新首页时常用 Movie,Series,Video 这种混合类型一次取「最新」行。
+	// 只有剧集库才该折叠成剧集卡片：seriesItemsForLibrary 只查
+	// (season_num>0 OR episode_num>0)，电影库走到这里会让整行返回 0 条。
 	if containsItemType(p.IncludeItemTypes, "Series") && !containsItemType(p.IncludeItemTypes, "Episode") {
-		return e.seriesItemsForLibrary(ctx, p.ParentID, p)
+		episodic := true
+		if p.ParentID != "" {
+			if value, err := e.libraryIsEpisodic(ctx, p.ParentID); err == nil {
+				episodic = value
+			}
+		}
+		if episodic {
+			return e.seriesItemsForLibrary(ctx, p.ParentID, p)
+		}
+		// 非剧集库：只请求 Series 时确实没有可返回的条目；混合类型则落回
+		// mediaItems，由它按 Movie 过滤，而不是整行判空。
+		if !containsItemType(p.IncludeItemTypes, "Movie") && !containsItemType(p.IncludeItemTypes, "Video") {
+			return emptyItemsEnvelope(p.StartIndex), nil
+		}
 	}
 
 	// 电影库的「常规浏览」(未指定 IncludeItemTypes): 电影库里偶尔混入按

internal/service/emby_items_cache.go

@@ -6,6 +6,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"time"
 )
 
 type embyItemsCacheValue struct {
@@ -77,7 +78,15 @@ func (e *EmbyService) embySimilarCacheKey(mediaID, userID string, limit int) str
 }
 
 // defaultEmbyLatestCacheTTLSeconds 是 Emby「最新添加」缓存的兜底时长。
-const defaultEmbyLatestCacheTTLSeconds = 300
+const defaultEmbyLatestCacheTTLSeconds = 900
+
+// embyLatestStaleWindow 是「最新添加」载荷在进程内保留的陈旧副本时长。
+//
+// 客户端空闲很久之后再打开首页时，新鲜期早已过去：生产环境观察到这时
+// 73 个媒体库的 Latest 同时回源，首批请求要 8-25s 才回来，客户端等不及
+// 还会重试，进一步放大压力。保留陈旧副本后，这类请求立刻拿到上次的结果，
+// 由后台异步重建（见 refreshLatestItemsAsync），用户不再等 SQL。
+const embyLatestStaleWindow = 24 * time.Hour
 
 // embyLatestCacheTTLSeconds 返回「最新添加」列表的缓存时长。它刻意比通用
 // 媒体缓存更长：客户端刷新首页时会同时请求全部媒体库的 Latest（生产环境

internal/service/emby_items_detail.go

@@ -153,7 +153,7 @@ func (e *EmbyService) loadLatestItemsCached(ctx context.Context, userID, parentI
 		}
 		if e.cache != nil {
 			freshTTL := time.Duration(e.embyLatestCacheTTLSeconds()) * time.Second
-			e.cache.SetJSONWithStale(loadCtx, cacheKey, value, freshTTL, freshTTL+30*time.Minute)
+			e.cache.SetJSONWithStale(loadCtx, cacheKey, value, freshTTL, freshTTL+embyLatestStaleWindow)
 		}
 		e.rememberArtworkRefs(value.Artwork)
 		return value, nil

internal/service/emby_series.go

@@ -41,47 +41,65 @@ func (e *EmbyService) findSeriesGroup(ctx context.Context, id, userID string) (e
 		return embySeriesGroup{}, false, nil
 	}
 	if strings.HasPrefix(id, embyVirtualSeriesPrefix) {
-		if group, ok := e.cachedSeriesGroup(id); ok {
-			return group, true, nil
-		}
+		return e.findVirtualSeriesGroup(ctx, id, userID)
 	}
 	var rows []model.Media
 	q := e.repo.DB.WithContext(ctx).Model(&model.Media{}).Where("season_num > 0 OR episode_num > 0")
 	q = e.applyUserMediaVisibility(ctx, q, userID)
-	if !strings.HasPrefix(id, embyVirtualSeriesPrefix) {
-		q = q.Where("series_id = ?", id)
-	} else {
-		// 虚拟 series ID 只可能来自 series_id 为空的媒体：
-		// 有 series_id 时分组 key 就是 series_id 本身（UUID，不带虚拟前缀）。
-		q = q.Where("series_id IS NULL OR series_id = ''")
-	}
+	q = q.Where("series_id = ?", id)
 	if err := q.Order("media.season_num asc, media.episode_num asc, media.episode_fraction asc, media.created_at asc").Limit(embySeriesGroupingLimit).Find(&rows).Error; err != nil {
 		return embySeriesGroup{}, false, err
 	}
-	for _, group := range e.seriesGroupsFromMedia(ctx, rows) {
+	groups := e.seriesGroupsFromMedia(ctx, rows)
+	bulkCached := e.rememberScannedSeriesGroups(groups)
+	for _, group := range groups {
 		if group.ID == id {
-			e.rememberSeriesGroup(group)
+			if !bulkCached {
+				e.rememberSeriesGroup(group)
+			}
 			return group, true, nil
 		}
 	}
-	if !strings.HasPrefix(id, embyVirtualSeriesPrefix) {
-		if series, err := e.repo.Series.FindByID(ctx, id); err != nil {
-			return embySeriesGroup{}, false, err
-		} else if series != nil {
-			return embySeriesGroup{
-				ID:                 series.ID,
-				LibraryID:          series.LibraryID,
-				Name:               series.Title,
-				PosterURL:          series.PosterURL,
-				BackdropURL:        series.BackdropURL,
-				Overview:           series.Overview,
-				Rating:             series.Rating,
-				Year:               series.Year,
-				TMDbID:             series.TMDbID,
-				BangumiID:          series.BangumiID,
-				CreatedAt:          series.CreatedAt,
-				DateLastMediaAdded: series.CreatedAt,
-			}, true, nil
+	if series, err := e.repo.Series.FindByID(ctx, id); err != nil {
+		return embySeriesGroup{}, false, err
+	} else if series != nil {
+		return embySeriesGroup{
+			ID:                 series.ID,
+			LibraryID:          series.LibraryID,
+			Name:               series.Title,
+			PosterURL:          series.PosterURL,
+			BackdropURL:        series.BackdropURL,
+			Overview:           series.Overview,
+			Rating:             series.Rating,
+			Year:               series.Year,
+			TMDbID:             series.TMDbID,
+			BangumiID:          series.BangumiID,
+			CreatedAt:          series.CreatedAt,
+			DateLastMediaAdded: series.CreatedAt,
+		}, true, nil
+	}
+	return embySeriesGroup{}, false, nil
+}
+
+// findVirtualSeriesGroup 处理 series_id 为空的剧集分组（虚拟 series ID）。
+//
+// 虚拟 ID 是 hash(库名 + 剧名)，无法反解，只能整库算出分组后按 ID 取用。
+// 这里走 loadVirtualSeriesGroups，把同一用户的并发请求折叠成一次扫描：
+// 首页一次刷新会同时要 73 个库的卡片和海报，各扫一遍在 2 核主机上要 14-17s。
+func (e *EmbyService) findVirtualSeriesGroup(ctx context.Context, id, userID string) (embySeriesGroup, bool, error) {
+	if group, ok := e.cachedSeriesGroup(id); ok {
+		return group, true, nil
+	}
+	if e.virtualScanRecently(userID) {
+		return embySeriesGroup{}, false, nil
+	}
+	groups, err := e.loadVirtualSeriesGroups(ctx, userID)
+	if err != nil {
+		return embySeriesGroup{}, false, err
+	}
+	for _, group := range groups {
+		if group.ID == id {
+			return group, true, nil
 		}
 	}
 	return embySeriesGroup{}, false, nil
@@ -103,20 +121,14 @@ func (e *EmbyService) findSeasonGroup(ctx context.Context, id, userID string) (e
 		return season, true, nil
 	}
 	// 回退：未刮削（series_id 为空，虚拟 key 由库名+名称派生）的媒体只能全量分组。
-	var rows []model.Media
-	q := e.repo.DB.WithContext(ctx).Model(&model.Media{}).
-		Where("(series_id IS NULL OR series_id = '') AND (season_num > 0 OR episode_num > 0)")
-	q = e.applyUserMediaVisibility(ctx, q, userID)
-	if err := q.
-		Order("media.season_num asc, media.episode_num asc, media.episode_fraction asc, media.created_at asc").
-		Limit(embySeriesGroupingLimit).
-		Find(&rows).Error; err != nil {
+	// 复用共享扫描：首页并发刷新时整库只扫一次。
+	groups, err := e.loadVirtualSeriesGroups(ctx, userID)
+	if err != nil {
 		return embySeasonGroup{}, false, err
 	}
-	for _, series := range e.seriesGroupsFromMedia(ctx, rows) {
+	for _, series := range groups {
 		for _, season := range e.seasonsForSeries(series) {
 			if season.ID == id {
-				e.rememberSeriesGroup(series)
 				return season, true, nil
 			}
 		}
@@ -186,6 +198,84 @@ func (e *EmbyService) seasonGroupForSeries(ctx context.Context, id, seriesID, us
 	return embySeasonGroup{}, false, nil
 }
 
+// rememberScannedSeriesGroups 批量记住一次扫描得到的全部分组，返回是否真的
+// 批量写入（超过剧集预算时不做，调用方需自行缓存命中的那一部）。
+//
+// 只缓存命中的一部时，同一部剧的多张卡片/海报仍要各扫一次；整批写入后，
+// 同一次扫描算出来的其他剧也直接命中，于是整页 16 张卡片 + 16 张海报共用
+// 一次全表扫描。
+func (e *EmbyService) rememberScannedSeriesGroups(groups []embySeriesGroup) bool {
+	if e == nil || len(groups) == 0 {
+		return false
+	}
+	episodes := 0
+	for i := range groups {
+		episodes += len(groups[i].Episodes)
+		if episodes > embySeriesGroupBulkCacheEpisodes {
+			return false
+		}
+	}
+	e.rememberSeriesGroups(groups)
+	return true
+}
+
+// loadVirtualSeriesGroups 返回 series_id 为空的整库剧集分组。
+//
+// 同一用户的并发调用共享同一次扫描：客户端刷新首页时 73 个库的 Latest 同时
+// 进来，每个库的卡片和海报又各自要自己的虚拟 series 分组。分组缓存键各不
+// 相同，singleflight 也就不会合并，于是第一波请求把整张 media 表并发重算
+// 了 73 次（生产环境实测 14-17s）。这里按用户折叠成一次，结果整批进缓存，
+// 调用方拿到切片后按 ID 取用即可。
+func (e *EmbyService) loadVirtualSeriesGroups(ctx context.Context, userID string) ([]embySeriesGroup, error) {
+	if e == nil || e.repo == nil {
+		return nil, nil
+	}
+	v, err, _ := e.virtualGroups.Do("virtual:"+userID, func() (any, error) {
+		// 与 loadLatestItemsCached 一致：一个客户端断开不应取消正在为其他
+		// 客户端填充的共享扫描。
+		loadCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
+		defer cancel()
+		var rows []model.Media
+		q := e.repo.DB.WithContext(loadCtx).Model(&model.Media{}).
+			Where("(series_id IS NULL OR series_id = '') AND (season_num > 0 OR episode_num > 0)")
+		q = e.applyUserMediaVisibility(loadCtx, q, userID)
+		if err := q.
+			Order("media.season_num asc, media.episode_num asc, media.episode_fraction asc, media.created_at asc").
+			Limit(embySeriesGroupingLimit).
+			Find(&rows).Error; err != nil {
+			return nil, err
+		}
+		groups := e.seriesGroupsFromMedia(loadCtx, rows)
+		e.rememberSeriesGroups(groups)
+		e.markVirtualScan(userID)
+		return groups, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	groups, _ := v.([]embySeriesGroup)
+	return groups, nil
+}
+
+// markVirtualScan 记录该用户最近一次整库扫描的时间。
+func (e *EmbyService) markVirtualScan(userID string) {
+	e.virtualMu.Lock()
+	if e.virtualScanAt == nil {
+		e.virtualScanAt = make(map[string]time.Time, 4)
+	}
+	e.virtualScanAt[userID] = time.Now()
+	e.virtualMu.Unlock()
+}
+
+// virtualScanRecently 报告该用户是否刚做过一次整库扫描。窗口内仍不在缓存里
+// 的目标 ID 按不存在处理，避免为同一个未知 ID 反复重扫整库。
+func (e *EmbyService) virtualScanRecently(userID string) bool {
+	e.virtualMu.RLock()
+	scannedAt := e.virtualScanAt[userID]
+	e.virtualMu.RUnlock()
+	return !scannedAt.IsZero() && time.Since(scannedAt) < embyVirtualScanGrace
+}
+
 func (e *EmbyService) seriesGroupsFromMedia(ctx context.Context, rows []model.Media) []embySeriesGroup {
 	byID := map[string]*embySeriesGroup{}
 	order := []string{}

internal/service/emby_series_cache.go

@@ -26,19 +26,45 @@ func (e *EmbyService) rememberSeriesGroup(group embySeriesGroup) {
 	if e == nil || strings.TrimSpace(group.ID) == "" {
 		return
 	}
+	e.rememberSeriesGroups([]embySeriesGroup{group})
+}
+
+// rememberSeriesGroups 批量记住一组剧集分组（含派生季与封面）。
+//
+// 一次全表扫描会同时算出整库的剧集分组，而调用方往往只关心其中一部。若只
+// 逐个 rememberSeriesGroup，同一次首页刷新里 16 张卡片 + 16 张海报都要各自
+// 命中自己的虚拟 series ID，未命中就重扫整张 media 表（生产环境实测单次
+// 1.3s，73 个库并发时把连接池排满，首页要 8-25s）。批量写入后冷缓存只付
+// 一次扫描，其余全部是 O(1) 命中。
+func (e *EmbyService) rememberSeriesGroups(groups []embySeriesGroup) {
+	if e == nil || len(groups) == 0 {
+		return
+	}
 	expiresAt := time.Now().Add(embyVirtualCacheTTL)
 	e.virtualMu.Lock()
 	defer e.virtualMu.Unlock()
 	if e.virtualSeries == nil {
-		e.virtualSeries = make(map[string]embySeriesCacheEntry)
+		e.virtualSeries = make(map[string]embySeriesCacheEntry, len(groups))
 	}
 	if e.virtualSeasons == nil {
-		e.virtualSeasons = make(map[string]embySeasonCacheEntry)
+		e.virtualSeasons = make(map[string]embySeasonCacheEntry, len(groups))
 	}
 	if e.virtualArtwork == nil {
-		e.virtualArtwork = make(map[string]embyArtworkCacheEntry)
+		e.virtualArtwork = make(map[string]embyArtworkCacheEntry, len(groups)*2)
 	}
+	for _, group := range groups {
+		e.rememberSeriesGroupLocked(group, expiresAt)
+	}
+	// 写入后再裁剪：逐条裁剪会让整批写入退化成 O(n²)，且中途裁剪可能把
+	// 同一批里刚写进去的分组又淘汰掉。
 	e.trimVirtualCachesLocked(time.Now())
+}
+
+// rememberSeriesGroupLocked 写入单个分组，调用方必须已持有 virtualMu。
+func (e *EmbyService) rememberSeriesGroupLocked(group embySeriesGroup, expiresAt time.Time) {
+	if strings.TrimSpace(group.ID) == "" {
+		return
+	}
 	e.virtualSeries[group.ID] = embySeriesCacheEntry{group: group, expiresAt: expiresAt}
 	e.virtualArtwork[group.ID] = embyArtworkCacheEntry{primary: group.PosterURL, backdrop: group.BackdropURL, expiresAt: expiresAt}
 	e.virtualArtwork[group.ID+"-bd"] = embyArtworkCacheEntry{primary: group.PosterURL, backdrop: group.BackdropURL, expiresAt: expiresAt}

internal/service/emby_system.go

@@ -2,6 +2,9 @@ package service
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
 	"sort"
 	"strings"
 	"time"
@@ -278,6 +281,20 @@ func isSupportedEmbyCollectionType(t string) bool {
 	return false
 }
 
+// libraryCoverTag 生成媒体库拼图封面的图片版本号。
+//
+// 第三方客户端把库主图按 (URL, ImageTag) 缓存，tag 不变就不会重新请求。
+// 用成员海报列表的指纹做 tag，库内容变化或生成规则调整时客户端自然会刷新。
+func libraryCoverTag(libraryID string, sources []string) string {
+	h := sha256.New()
+	_, _ = io.WriteString(h, libraryID)
+	for _, src := range sources {
+		_, _ = io.WriteString(h, src)
+		_, _ = h.Write([]byte{0})
+	}
+	return libraryID + "-" + hex.EncodeToString(h.Sum(nil))[:8]
+}
+
 func (e *EmbyService) libraryAsView(ctx context.Context, l *model.Library) map[string]any {
 	collectionType := "movies"
 	switch l.Type {
@@ -292,9 +309,17 @@ func (e *EmbyService) libraryAsView(ctx context.Context, l *model.Library) map[s
 	}
 	// 库封面:与剧集/电影一样,只有在能解析出封面时才广告 ImageTags.Primary,
 	// 否则客户端会认为该库无主图而不去请求 /Images/Primary。
+	//
+	// 拼图封面的 tag 带上「成员海报」的指纹：库内容变化或生成规则调整（例如
+	// 从 2×2 改成竖切）时 tag 会变，客户端才会丢缓存重新拉图；固定用库 ID
+	// 会让第三方客户端永远显示第一次缓存下来的封面。
 	imageTags := map[string]string{}
-	if e.LibraryHasCover(ctx, l.ID) {
-		imageTags["Primary"] = l.ID
+	if sources, lib := LibraryCoverSourcesForLibrary(ctx, e.repo, l.ID); lib != nil {
+		if len(sources) > 0 {
+			imageTags["Primary"] = libraryCoverTag(l.ID, sources)
+		} else if strings.TrimSpace(lib.CoverURL) != "" {
+			imageTags["Primary"] = l.ID
+		}
 	}
 	return map[string]any{
 		"Id":                       l.ID,

internal/service/emby_user_data.go

@@ -136,7 +136,12 @@ func (e *EmbyService) RecordProgressWithSession(ctx context.Context, userID, med
 		SessionID:          playSessionID,
 		SessionStartedAtMs: embyPlaySessionStartedAtMs(playSessionID),
 	})
-	if err == nil {
+	// 普通进度上报不清列表载荷缓存。播放期间客户端每 5-10 秒上报一次，
+	// 每次清空 media:emby:* 会让「最新添加」整批 payload（客户端刷新首页时
+	// 一次并发 73 个库）反复回源 SQL，生产环境实测因此出现 8-25s 的加载。
+	// 续播位置由 /Items/Resume 与条目详情实时查库，列表里的进度条允许滞后；
+	// 只有「已看完」这类状态翻转才让缓存失效（position 到达片尾 30s 内）。
+	if err == nil && playbackProgressCompleted(pos, dur) {
 		e.invalidateEmbyItemsCache(ctx)
 	}
 	return err
@@ -287,10 +292,11 @@ func applyMeBoxUserData(raw any, history *model.PlaybackHistory, favorite bool)
 	return userData
 }
 
-// embyInvalMu 节流全量缓存失效：播放期间客户端每 5-10s 上报一次进度，
-// 每次都 SCAN+DEL 全部 media:emby:* 缓存会把缓存命中率持续打穿（其他
-// 客户端每次翻页都回源 SQL）。条目载荷的 UserData 在请求时动态合并，
-// 进度类变更做 30s 节流即可，不影响正确性观感。
+// embyInvalMu 节流全量缓存失效：收藏/标记已看这类显式操作会改变列表里的
+// UserData，必须让 payload 失效。客户端连续点选时会短时间触发多次，节流到
+// 30s 一次即可，避免每次都 SCAN+DEL 全部 media:emby:* 缓存。
+// 播放进度上报不走这里（见 RecordProgressWithSession）：续播位置实时查库，
+// 列表里的进度条允许滞后，不值得为它把整批首页载荷打回源 SQL。
 var (
 	embyInvalMu   sync.Mutex
 	embyInvalLast time.Time

internal/service/episode_metadata_cleanup.go

@@ -144,3 +144,43 @@ func (c *Container) NormalizePollutedEpisodeMetadata(ctx context.Context) (int,
 	}
 	return cleaned, nil
 }
+
+// segmentRangeCleanupSettingKey marks the one-time removal of impossible
+// skip ranges written by the older end_ms: 0 interpretation.
+const segmentRangeCleanupSettingKey = "segment.range_cleanup_v1_done"
+
+// NormalizeImpossibleSegments 删除历史误写进来的「不可能区间」。
+//
+// 旧解析把 TheIntroDB 的 end_ms: 0 当成「延续到片尾」，于是
+// intro:[{start_ms:null,end_ms:0}] 被落成 intro (0, 0)，客户端补齐后覆盖整集；
+// 同理 recap (0,0) 也会让整集变成回顾。这类行只会让播放器一开播就弹跳过按钮，
+// 没有任何保留价值，直接硬删。
+//
+// 幂等：完成后写 setting 标记。只处理片头/回顾——片尾类允许开放结束点。
+func (c *Container) NormalizeImpossibleSegments(ctx context.Context) (int, error) {
+	if c == nil || c.Repo == nil || c.Repo.DB == nil {
+		return 0, nil
+	}
+	if c.Repo.Setting != nil {
+		if v, err := c.Repo.Setting.Get(ctx, segmentRangeCleanupSettingKey); err == nil && strings.TrimSpace(v) == "true" {
+			return 0, nil
+		}
+	}
+	res := c.Repo.DB.WithContext(ctx).Unscoped().
+		Where("kind IN ?", []string{model.SegmentKindIntro, model.SegmentKindRecap}).
+		Where("end_ms <= start_ms").
+		Delete(&model.MediaSegment{})
+	if res.Error != nil {
+		return 0, res.Error
+	}
+	cleaned := int(res.RowsAffected)
+	if c.Repo.Setting != nil {
+		if err := c.Repo.Setting.Set(ctx, segmentRangeCleanupSettingKey, "true"); err != nil && c.Log != nil {
+			c.Log.Warn("mark segment range cleanup done failed", zap.Error(err))
+		}
+	}
+	if cleaned > 0 && c.Log != nil {
+		c.Log.Info("impossible skip segments removed", zap.Int("rows", cleaned))
+	}
+	return cleaned, nil
+}

internal/service/image_proxy.go

@@ -199,21 +199,19 @@ func imageResizeConcurrency() int {
 	return n
 }
 
-// Prune removes oldest cached images until disk usage is within the configured limit.
-// 原图池按独立配额与保留时长优先淘汰，客户端热路径读取的成品图最后淘汰。
+// Prune 只执行图片原图子配额与旧缓存清理；整个磁盘缓存的总量淘汰由调度器的
+// cache_cleanup 任务（PruneCache）负责。
 func (p *ImageProxy) Prune() (PruneImageCacheResult, error) {
-	if p.cfg == nil || p.cfg.Cache.ImagesMaxSizeMB <= 0 {
+	if p.cfg == nil {
 		return PruneImageCacheResult{}, nil
 	}
 	var originalsMaxBytes int64
 	if p.cfg.Cache.ImagesOriginalsMaxSizeMB > 0 {
 		originalsMaxBytes = int64(p.cfg.Cache.ImagesOriginalsMaxSizeMB) * 1024 * 1024
 	}
-	var originalsMaxAge time.Duration
-	if p.cfg.Cache.ImagesOriginalsTTLHours > 0 {
-		originalsMaxAge = time.Duration(p.cfg.Cache.ImagesOriginalsTTLHours) * time.Hour
+	if originalsMaxBytes <= 0 {
+		return PruneImageCacheResult{}, nil
 	}
-	totalBytes := int64(p.cfg.Cache.ImagesMaxSizeMB) * 1024 * 1024
-	pools := ImageCachePools(p.cacheDir, originalsMaxBytes, originalsMaxAge)
-	return PruneImageCachePools(pools, totalBytes)
+	pools := ImageCachePools(p.cacheDir, originalsMaxBytes)
+	return PruneImageCachePools(pools, 0)
 }

internal/service/introdb.go

@@ -41,15 +41,6 @@ const (
 	introDBMaxRetryDelay = 3 * time.Second
 )
 
-// IntroDBSpan is one resolved skip range, still in provider terms.
-// EndMs == 0 means "runs to the end of the media" (TheIntroDB returns
-// end_ms: null for end credits); the caller resolves it against the duration.
-type IntroDBSpan struct {
-	Kind    string
-	StartMs int64
-	EndMs   int64
-}
-
 // IntroDBService queries TheIntroDB for one media item.
 type IntroDBService struct {
 	log        *zap.Logger
@@ -113,7 +104,7 @@ type introDBResponse struct {
 // 429/503 会重试一次（社区库在短时间连发下确实会限流）。重试前会先确认调用方
 // 的 deadline 还够用；预算不够就直接返回错误，让调用方保留自己的缓存，
 // 把「拿不到片段」维持在「少一个跳过按钮」的量级。
-func (s *IntroDBService) Fetch(ctx context.Context, tmdbID, season, episode int) ([]IntroDBSpan, error) {
+func (s *IntroDBService) Fetch(ctx context.Context, tmdbID, season, episode int) ([]SegmentSpan, error) {
 	if s == nil || s.client == nil {
 		return nil, errors.New("introdb service nil")
 	}
@@ -135,9 +126,20 @@ func (s *IntroDBService) Fetch(ctx context.Context, tmdbID, season, episode int)
 	}
 }
 
+// Source implements SegmentProvider.
+func (s *IntroDBService) Source() string { return IntroDBSource }
+
+// FetchSegments implements SegmentProvider. TheIntroDB 以 TMDb id 寻址。
+func (s *IntroDBService) FetchSegments(ctx context.Context, q SegmentQuery) ([]SegmentSpan, error) {
+	if q.IsMovie {
+		return s.Fetch(ctx, q.TMDbID, 0, 0)
+	}
+	return s.Fetch(ctx, q.TMDbID, q.Season, q.Episode)
+}
+
 // introDBFetchAttempt 是一次请求的结果：数据或错误，外加「值不值得重试」。
 type introDBFetchAttempt struct {
-	spans      []IntroDBSpan
+	spans      []SegmentSpan
 	err        error
 	retryable  bool
 	retryAfter time.Duration
@@ -246,7 +248,7 @@ func (s *IntroDBService) mediaURL(tmdbID, season, episode int) string {
 // parseIntroDBResponse flattens the per-type arrays into spans, preserving the
 // intro -> recap -> credits -> preview order so the player sees the earliest
 // range first.
-func parseIntroDBResponse(body []byte) ([]IntroDBSpan, error) {
+func parseIntroDBResponse(body []byte) ([]SegmentSpan, error) {
 	var raw introDBResponse
 	if err := json.Unmarshal(body, &raw); err != nil {
 		return nil, fmt.Errorf("parse introdb json: %w", err)
@@ -260,7 +262,7 @@ func parseIntroDBResponse(body []byte) ([]IntroDBSpan, error) {
 		{"credits", raw.Credits},
 		{"preview", raw.Preview},
 	}
-	spans := make([]IntroDBSpan, 0, len(raw.Intro)+len(raw.Credits))
+	spans := make([]SegmentSpan, 0, len(raw.Intro)+len(raw.Credits))
 	for _, group := range groups {
 		for _, r := range group.ranges {
 			var start int64
@@ -274,12 +276,24 @@ func parseIntroDBResponse(body []byte) ([]IntroDBSpan, error) {
 			if start < 0 {
 				start = 0
 			}
-			// end == 0 表示「延续到片尾」，是合法值；其余情况 end 必须大于 start，
-			// 否则这段区间没有任何可跳过的内容，直接丢弃避免在播放器里出现空按钮。
-			if end != 0 && end <= start {
+			// 官方规范（theintrodb.org/openapi.yaml，SegmentTimestamp）区分了两种
+			// 「没有数值」的写法，含义完全不同，必须按指针区分而不能都归零：
+			//   end_ms: null —— Credits/Preview 专用，「一直到片尾」，合法，
+			//                   落成 0 作为哨兵值由客户端结合片长补齐；
+			//   end_ms: 0    —— 「no segment」，即这一段不存在。
+			// 早期实现把两者都当成「到片尾」，于是 intro:[{start_ms:null,end_ms:0}]
+			// 被解释成 [0, 片长]，整集都落在「片头」区间里：一开播就弹跳过按钮，
+			// 开了自动跳过更是直接跳到片尾。实测约三分之一的剧集会返回这种占位。
+			if r.EndMs != nil && end <= start {
 				continue
 			}
-			spans = append(spans, IntroDBSpan{Kind: group.kind, StartMs: start, EndMs: end})
+			// 只有片尾类区间才允许「开放结束点」（end_ms: null 落成 0）。片头/回顾
+			// 如果出现 null 结束点，补齐后的区间会覆盖到片尾，等于把整集判成片头，
+			// 所以宁可不显示也不猜。
+			if r.EndMs == nil && group.kind != "credits" && group.kind != "preview" {
+				continue
+			}
+			spans = append(spans, SegmentSpan{Kind: group.kind, StartMs: start, EndMs: end})
 		}
 	}
 	return spans, nil

internal/service/introdb_app.go

@@ -0,0 +1,160 @@
+// Package service — IntroDB (https://introdb.app) segment client.
+//
+// 与 TheIntroDB 是两家不同的社区库：IntroDB 只接受 IMDb id 定位媒体，
+// 用 is_movie 区分电影与剧集，响应把每种区间直接给成 {start_ms,end_ms} 对象
+// （而不是按类型分数组），片尾字段名是 outro 而不是 credits，
+// 另外还有 post_credits（片尾彩蛋，映射为预告/额外片尾）。
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+// IntroDBAppBaseURL 是公开只读端点。POST /submit 需要 API key，这里不做写入。
+const IntroDBAppBaseURL = "https://api.introdb.app"
+
+// IntroDBAppSource 写入 media_segments.source，与 TheIntroDB 的 "theintrodb" 区分。
+const IntroDBAppSource = "introdb"
+
+const (
+	introDBAppTimeout     = 8 * time.Second
+	introDBAppMaxBodySize = 1 << 20
+)
+
+// introDBAppSegment 是 IntroDB 的单个区间对象。null 表示该类型没有数据。
+type introDBAppSegment struct {
+	StartMs *int64 `json:"start_ms"`
+	EndMs   *int64 `json:"end_ms"`
+}
+
+// introDBAppResponse 对应 GET /segments。
+type introDBAppResponse struct {
+	IMDbID      string             `json:"imdb_id"`
+	MediaType   string             `json:"media_type"`
+	IsMovie     bool               `json:"is_movie"`
+	Season      int                `json:"season"`
+	Episode     int                `json:"episode"`
+	Intro       *introDBAppSegment `json:"intro"`
+	Recap       *introDBAppSegment `json:"recap"`
+	Outro       *introDBAppSegment `json:"outro"`
+	PostCredits *introDBAppSegment `json:"post_credits"`
+}
+
+// IntroDBAppService 查询 IntroDB 的片段数据。
+type IntroDBAppService struct {
+	log     *zap.Logger
+	client  *http.Client
+	baseURL string
+}
+
+// NewIntroDBAppService is the constructor. The client honours environment and
+// OS proxy settings so it behaves like the other third-party API clients.
+func NewIntroDBAppService(log *zap.Logger) *IntroDBAppService {
+	return &IntroDBAppService{
+		log:     log,
+		client:  NewExternalHTTPClient(introDBAppTimeout),
+		baseURL: IntroDBAppBaseURL,
+	}
+}
+
+// SetBaseURL overrides the API root (tests, mirrors).
+func (s *IntroDBAppService) SetBaseURL(base string) *IntroDBAppService {
+	if s != nil && strings.TrimSpace(base) != "" {
+		s.baseURL = strings.TrimRight(strings.TrimSpace(base), "/")
+	}
+	return s
+}
+
+// Source implements SegmentProvider.
+func (s *IntroDBAppService) Source() string { return IntroDBAppSource }
+
+// FetchSegments implements SegmentProvider.
+//
+// 没有 IMDb id 时直接返回空：IntroDB 不接受 TMDb id，用别的 id 拼请求只会拿到
+// 400，那会被误记成「查询失败」从而保留旧缓存、永远不再刷新。
+func (s *IntroDBAppService) FetchSegments(ctx context.Context, q SegmentQuery) ([]SegmentSpan, error) {
+	if s == nil || s.client == nil || strings.TrimSpace(q.IMDbID) == "" {
+		return nil, nil
+	}
+	endpoint := s.segmentsURL(q)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", "application/json")
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	// 404 = 库里没有这部片，是正常的「无数据」，不是错误。
+	if resp.StatusCode == http.StatusNotFound {
+		return nil, nil
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("introdb: unexpected status %d", resp.StatusCode)
+	}
+	body, err := io.ReadAll(io.LimitReader(resp.Body, introDBAppMaxBodySize))
+	if err != nil {
+		return nil, err
+	}
+	return parseIntroDBAppResponse(body)
+}
+
+func (s *IntroDBAppService) segmentsURL(q SegmentQuery) string {
+	values := url.Values{}
+	values.Set("imdb_id", strings.TrimSpace(q.IMDbID))
+	if q.IsMovie {
+		values.Set("is_movie", "true")
+	} else if q.Season > 0 && q.Episode > 0 {
+		values.Set("season", strconv.Itoa(q.Season))
+		values.Set("episode", strconv.Itoa(q.Episode))
+	}
+	return s.baseURL + "/segments?" + values.Encode()
+}
+
+// parseIntroDBAppResponse 把 IntroDB 的四个区间对象摊平成 spans。
+//
+// 顺序固定为 intro -> recap -> outro -> post_credits，与 TheIntroDB 的
+// intro/recap/credits/preview 对齐，后处理逻辑因此可以对来源无感。
+func parseIntroDBAppResponse(body []byte) ([]SegmentSpan, error) {
+	var raw introDBAppResponse
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("parse introdb json: %w", err)
+	}
+	groups := []struct {
+		kind string
+		seg  *introDBAppSegment
+	}{
+		{"intro", raw.Intro},
+		{"recap", raw.Recap},
+		{"credits", raw.Outro},
+		{"preview", raw.PostCredits},
+	}
+	spans := make([]SegmentSpan, 0, len(groups))
+	for _, group := range groups {
+		if group.seg == nil || group.seg.StartMs == nil || group.seg.EndMs == nil {
+			continue
+		}
+		start, end := *group.seg.StartMs, *group.seg.EndMs
+		if start < 0 {
+			start = 0
+		}
+		if end <= start {
+			continue
+		}
+		spans = append(spans, SegmentSpan{Kind: group.kind, StartMs: start, EndMs: end})
+	}
+	return spans, nil
+}

internal/service/library_cover.go

@@ -0,0 +1,564 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"image"
+	"image/jpeg"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"golang.org/x/image/draw"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// 媒体库封面拼图（Emby 风格的「封面集」）。
+//
+// Emby / Jellyfin 在没有管理员自定义封面时，会用库内几张海报拼成一张
+// 2×2 的合成图作为库主图（folder image）。MeBox 早先只是挑评分最高的
+// 那一张单图，于是每个库的封面看起来都像「随便选了一张」。这里按同样的
+// 思路生成拼图，供 Emby 客户端、Web 和 App 共用同一份图片。
+
+const (
+	// libraryCoverDefaultWidth / Height 是拼图输出的默认画布。
+	//
+	// 库条目的 PrimaryImageAspectRatio 报的是 16:9（见 emby_system.go），
+	// 客户端按这个比例摆卡片；生成同样比例的图可以避免客户端再裁一刀。
+	libraryCoverDefaultWidth  = 480
+	libraryCoverDefaultHeight = 270
+	libraryCoverMinWidth      = 96
+	libraryCoverMaxWidth      = 1920
+	libraryCoverAspect        = 16.0 / 9.0
+
+	// libraryCoverSourceLimit 是拼图实际取用的成员海报数上限。
+	//
+	// 封面是竖切分栏：三栏在 16:9 画布上每栏接近 3:5，既保留海报主体，又能
+	// 让一个库有多部作品可辨识；再多就会把海报裁成很窄的竖条。
+	libraryCoverSourceLimit = 3
+	// libraryCoverMaxPanels 是合成函数能接受的最多分栏数（更长的来源列表
+	// 只取前几张）。留 4 是给「按库类型调栏数」留的余量。
+	libraryCoverMaxPanels = 4
+	// libraryCoverCandidatePool 是挑选海报时的候选池大小。只看最近的一批
+	// 成员，避免为一个库封面扫全库；对「最新入库」的库来说这批就是它最好
+	// 的那几张。
+	libraryCoverCandidatePool = 200
+
+	libraryCoverQuality = 85
+	libraryCoverSubdir  = "library-covers"
+)
+
+// libraryCoverSourceCache 缓存「库 → 成员海报来源」。Emby 客户端进入首页
+// 时会对每个库各请求一次主图，把这个查询压到每库 10 分钟一次，避免几十个
+// 200 行的列表查询同时打进来。
+var libraryCoverSourceCache = struct {
+	mu    sync.Mutex
+	items map[string]libraryCoverSourceEntry
+}{items: make(map[string]libraryCoverSourceEntry)}
+
+type libraryCoverSourceEntry struct {
+	sources   []string
+	expiresAt time.Time
+}
+
+const libraryCoverSourceTTL = 10 * time.Minute
+
+func cachedLibraryCoverSources(libraryID string) ([]string, bool) {
+	libraryCoverSourceCache.mu.Lock()
+	defer libraryCoverSourceCache.mu.Unlock()
+	entry, ok := libraryCoverSourceCache.items[libraryID]
+	if !ok || time.Now().After(entry.expiresAt) {
+		if ok {
+			delete(libraryCoverSourceCache.items, libraryID)
+		}
+		return nil, false
+	}
+	return entry.sources, true
+}
+
+func rememberLibraryCoverSources(libraryID string, sources []string) {
+	libraryCoverSourceCache.mu.Lock()
+	defer libraryCoverSourceCache.mu.Unlock()
+	if len(libraryCoverSourceCache.items) > 4000 {
+		libraryCoverSourceCache.items = make(map[string]libraryCoverSourceEntry)
+	}
+	libraryCoverSourceCache.items[libraryID] = libraryCoverSourceEntry{
+		sources:   sources,
+		expiresAt: time.Now().Add(libraryCoverSourceTTL),
+	}
+}
+
+// LibraryCoverSources 返回媒体库封面拼图要用的海报来源，最多 limit 张。
+//
+// 选法与网页旧逻辑一致（库内最近一批成员，按 seriesArtworkScore 取质量
+// 最高者），额外按剧集去重，避免四张海报全是同一部剧的不同集。
+func LibraryCoverSources(ctx context.Context, repos *repository.Container, libraryID string, limit int) []string {
+	if repos == nil || repos.Media == nil || strings.TrimSpace(libraryID) == "" {
+		return nil
+	}
+	if limit <= 0 || limit > libraryCoverSourceLimit {
+		limit = libraryCoverSourceLimit
+	}
+	if cached, ok := cachedLibraryCoverSources(libraryID); ok {
+		if len(cached) > limit {
+			return cached[:limit]
+		}
+		return cached
+	}
+	rows, err := repos.Media.ListByLibrariesFilteredNoCount(ctx, []string{libraryID}, 0, libraryCoverCandidatePool,
+		repository.MediaQueryFilter{IncludeNSFW: true})
+	if err != nil || len(rows) == 0 {
+		return nil
+	}
+	type candidate struct {
+		url   string
+		key   string
+		score int
+	}
+	candidates := make([]candidate, 0, len(rows))
+	for i := range rows {
+		row := rows[i]
+		raw := strings.TrimSpace(row.PosterURL)
+		if raw == "" {
+			raw = strings.TrimSpace(row.BackdropURL)
+		}
+		if raw == "" {
+			continue
+		}
+		key := mediaSeriesKey(row)
+		if key == "" {
+			key = "id:" + row.ID
+		}
+		candidates = append(candidates, candidate{url: raw, key: key, score: seriesArtworkScore(row)})
+	}
+	// 评分高的优先；同分保持数据库顺序（最近的在前），封面更贴近「最新入库」。
+	sort.SliceStable(candidates, func(i, j int) bool { return candidates[i].score > candidates[j].score })
+
+	out := make([]string, 0, limit)
+	seenKey := make(map[string]struct{}, limit)
+	seenURL := make(map[string]struct{}, limit)
+	for _, item := range candidates {
+		if len(out) >= limit {
+			break
+		}
+		if _, ok := seenKey[item.key]; ok {
+			continue
+		}
+		if _, ok := seenURL[item.url]; ok {
+			continue
+		}
+		seenKey[item.key] = struct{}{}
+		seenURL[item.url] = struct{}{}
+		out = append(out, item.url)
+	}
+	if len(out) == 0 {
+		rememberLibraryCoverSources(libraryID, nil)
+		return nil
+	}
+	rememberLibraryCoverSources(libraryID, out)
+	return out
+}
+
+// LibraryCoverCacheDir 返回拼图缓存目录（与图片代理的 images/ 分开存放，
+// 不会被图片缓存的配额清理误删）。
+func LibraryCoverCacheDir(cfgCacheDir string) string {
+	base := strings.TrimSpace(cfgCacheDir)
+	if base == "" {
+		base = "./cache"
+	}
+	return filepath.Join(base, libraryCoverSubdir)
+}
+
+// LibraryCoverImage 生成（或命中缓存）媒体库封面拼图。
+//
+// width/height 是期望的输出画布；服务端会按 16:9 收敛，返回的图片不会
+// 超过该边界。sources 由调用方提供（见 LibraryCoverSources），这样 Emby
+// 路由和 Web API 可以共用同一套生成与缓存逻辑。
+func (p *ImageProxy) LibraryCoverImage(ctx context.Context, libraryID string, sources []string, width, height int) ([]byte, error) {
+	if p == nil {
+		return nil, errors.New("image proxy unavailable")
+	}
+	libraryID = strings.TrimSpace(libraryID)
+	sources = normalizeCoverSources(sources)
+	if libraryID == "" || len(sources) == 0 {
+		return nil, errors.New("no library cover sources")
+	}
+	outW, outH := libraryCoverCanvas(width, height)
+	cachePath, sourceKey := p.libraryCoverCachePath(libraryID, sources, outW, outH)
+	if data, err := os.ReadFile(cachePath); err == nil && len(data) > 0 { // #nosec G304 -- cachePath is derived from a content hash.
+		return data, nil
+	}
+
+	key := fmt.Sprintf("library-cover:%s-%dx%d-%s", libraryID, outW, outH, sourceKey)
+	v, err, _ := p.fetchGroup.Do(key, func() (any, error) {
+		if data, err := os.ReadFile(cachePath); err == nil && len(data) > 0 { // #nosec G304 -- cachePath is derived from a content hash.
+			return data, nil
+		}
+		data, buildErr := p.buildLibraryCover(ctx, libraryID, sources, outW, outH, cachePath, sourceKey)
+		if buildErr != nil {
+			return nil, buildErr
+		}
+		return data, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	data, _ := v.([]byte)
+	if len(data) == 0 {
+		return nil, errors.New("empty library cover")
+	}
+	return data, nil
+}
+
+func (p *ImageProxy) buildLibraryCover(ctx context.Context, libraryID string, sources []string, width, height int, cachePath, sourceKey string) ([]byte, error) {
+	images := p.fetchCoverSources(ctx, sources)
+	if len(images) == 0 {
+		return nil, errors.New("no library cover image fetched")
+	}
+	// 解码与合成是 CPU 密集操作：和缩略图共用同一组解码槽，避免一次首页
+	// 刷新把 2 核主机打满。
+	release, ok := p.acquireResizeSlotWithin(ctx, p.resizeQueueTimeout())
+	if ok {
+		defer release()
+	}
+	data, err := composeLibraryCover(images, width, height)
+	if err != nil {
+		return nil, err
+	}
+	if err := os.MkdirAll(filepath.Dir(cachePath), 0o750); err != nil {
+		return data, nil
+	}
+	if err := writeFileAtomic(cachePath, data); err != nil {
+		p.warn("write library cover cache failed", err)
+		return data, nil
+	}
+	p.pruneLibraryCoverVariants(filepath.Dir(cachePath), libraryID, sourceKey)
+	return data, nil
+}
+
+// fetchCoverSources 并发拉取成员海报（受图片代理自身的缓存/鉴权/SSRF 规则
+// 保护）。单张失败只丢弃该张，其余仍然可以拼图。
+func (p *ImageProxy) fetchCoverSources(ctx context.Context, sources []string) [][]byte {
+	out := make([][]byte, len(sources))
+	var wg sync.WaitGroup
+	sem := make(chan struct{}, libraryCoverMaxPanels)
+	fetchCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+	for i, raw := range sources {
+		i, raw := i, raw
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+			data, err := p.coverSourceBytes(fetchCtx, raw)
+			if err != nil || len(data) == 0 {
+				return
+			}
+			out[i] = data
+		}()
+	}
+	wg.Wait()
+	compacted := make([][]byte, 0, len(out))
+	for _, data := range out {
+		if len(data) > 0 {
+			compacted = append(compacted, data)
+		}
+	}
+	return compacted
+}
+
+// coverSourceBytes 读取一张海报来源。
+//
+// 刮削会把 sidecar 海报存成 /media/... 这类绝对路径，而 fetch 路径只接受
+// http(s)（validateURL 要求有 host），直接丢给 Fetch 会全部失败。本地路径
+// 按图片代理同一套 isAllowedLocalPath 白名单读盘，远程地址才走 Fetch，
+// 这样鉴权、SSRF 校验与磁盘缓存的行为与 /api/img 完全一致。
+func (p *ImageProxy) coverSourceBytes(ctx context.Context, raw string) ([]byte, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil, errors.New("empty cover source")
+	}
+	if isLocalImagePath(raw) {
+		abs, err := filepath.Abs(filepath.Clean(raw))
+		if err != nil {
+			return nil, err
+		}
+		if !p.isAllowedLocalPath(abs) {
+			return nil, errors.New("local cover path not allowed")
+		}
+		return os.ReadFile(abs) // #nosec G304 -- path validated against the library roots above.
+	}
+	data, _, err := p.Fetch(ctx, raw)
+	if err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+// libraryCoverCachePath 生成缓存路径。
+//
+// 文件名里的 sourceKey 只由成员海报列表决定（不含尺寸）：成员变化时换一批
+// 文件，同一批成员的多个尺寸变体可以共存，不会被互相删掉。size 单独进文件名，
+// 让 Emby（按客户端 maxWidth/maxHeight）与 Web/App（固定档位）各用自己的成品。
+func (p *ImageProxy) libraryCoverCachePath(libraryID string, sources []string, width, height int) (string, string) {
+	h := sha256.New()
+	for _, src := range sources {
+		_, _ = io.WriteString(h, src)
+		_, _ = h.Write([]byte{0})
+	}
+	sourceKey := hex.EncodeToString(h.Sum(nil))[:16]
+	name := fmt.Sprintf("%s-%dx%d-%s.jpg", safeCoverFileID(libraryID), width, height, sourceKey)
+	return filepath.Join(LibraryCoverCacheDir(p.cacheDirBase()), name), sourceKey
+}
+
+func (p *ImageProxy) cacheDirBase() string {
+	if p != nil && p.cfg != nil {
+		return p.cfg.Cache.CacheDir
+	}
+	return ""
+}
+
+// pruneLibraryCoverVariants 清掉同一个库、旧成员列表留下的封面文件（含各
+// 尺寸变体），当前成员列表对应的成品全部保留。
+func (p *ImageProxy) pruneLibraryCoverVariants(dir, libraryID, keepSourceKey string) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	prefix := safeCoverFileID(libraryID) + "-"
+	for _, entry := range entries {
+		name := entry.Name()
+		if entry.IsDir() || !strings.HasPrefix(name, prefix) || !strings.HasSuffix(name, ".jpg") {
+			continue
+		}
+		if strings.Contains(name, "-"+keepSourceKey+".jpg") {
+			continue
+		}
+		_ = os.Remove(filepath.Join(dir, name)) // #nosec G304 -- name comes from ReadDir of our own cache dir.
+	}
+}
+
+// safeCoverFileID 让文件名只包含安全字符（库 ID 来自数据库，但仍做一次
+// 白名单过滤，避免任何路径分隔符进入文件名）。
+func safeCoverFileID(libraryID string) string {
+	var b strings.Builder
+	for _, r := range libraryID {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '-', r == '_':
+			b.WriteRune(r)
+		}
+	}
+	if b.Len() == 0 {
+		return "library"
+	}
+	return b.String()
+}
+
+func normalizeCoverSources(sources []string) []string {
+	seen := make(map[string]struct{}, len(sources))
+	out := make([]string, 0, len(sources))
+	for _, raw := range sources {
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			continue
+		}
+		if _, ok := seen[raw]; ok {
+			continue
+		}
+		seen[raw] = struct{}{}
+		out = append(out, raw)
+		if len(out) >= libraryCoverMaxPanels {
+			break
+		}
+	}
+	return out
+}
+
+// libraryCoverCanvas 把请求的尺寸收敛到 16:9 画布，并夹在合理区间内。
+func libraryCoverCanvas(width, height int) (int, int) {
+	if width <= 0 && height <= 0 {
+		return libraryCoverDefaultWidth, libraryCoverDefaultHeight
+	}
+	if width <= 0 {
+		width = int(float64(height)*libraryCoverAspect + 0.5)
+	}
+	if height <= 0 {
+		height = int(float64(width)/libraryCoverAspect + 0.5)
+	}
+	// 客户端给的是一个「不超过」的盒子：按 16:9 装进去。
+	if float64(width)/float64(height) > libraryCoverAspect {
+		width = int(float64(height)*libraryCoverAspect + 0.5)
+	} else {
+		height = int(float64(width)/libraryCoverAspect + 0.5)
+	}
+	if width < libraryCoverMinWidth {
+		width = libraryCoverMinWidth
+		height = int(float64(width)/libraryCoverAspect + 0.5)
+	}
+	if width > libraryCoverMaxWidth {
+		width = libraryCoverMaxWidth
+		height = int(float64(width)/libraryCoverAspect + 0.5)
+	}
+	return width, height
+}
+
+// composeLibraryCover 把若干张海报拼成库封面：竖切成若干等宽竖条。
+//
+//   - 1 张：铺满整块画布；
+//   - 2 张：左右各一半（默认形态，对应网页/客户端卡片的分屏观感）；
+//   - 3/4 张：三等分 / 四等分竖条。
+//
+// 每格按中心裁切铺满（crop-to-fill），这样不同比例的海报都能对齐分栏。
+func composeLibraryCover(images [][]byte, width, height int) ([]byte, error) {
+	if len(images) == 0 {
+		return nil, errors.New("no images to compose")
+	}
+	if width <= 0 || height <= 0 {
+		return nil, errors.New("invalid cover size")
+	}
+	decoded := make([]image.Image, 0, len(images))
+	for _, data := range images {
+		img, ok := decodeCoverImage(data)
+		if ok {
+			decoded = append(decoded, img)
+		}
+		if len(decoded) >= libraryCoverMaxPanels {
+			break
+		}
+	}
+	if len(decoded) == 0 {
+		return nil, errors.New("no decodable cover images")
+	}
+	canvas := image.NewRGBA(image.Rect(0, 0, width, height))
+	cells := make([]image.Rectangle, 0, len(decoded))
+	if len(decoded) == 1 {
+		cells = append(cells, canvas.Bounds())
+	} else {
+		for i := range decoded {
+			x0 := width * i / len(decoded)
+			x1 := width * (i + 1) / len(decoded)
+			cells = append(cells, image.Rect(x0, 0, x1, height))
+		}
+	}
+	for i, cell := range cells {
+		drawCoverCell(canvas, cell, decoded[i])
+	}
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, canvas, &jpeg.Options{Quality: libraryCoverQuality}); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+// decodeCoverImage 解码一张海报，并对异常大的图做像素上限保护：一次拼图
+// 会同时解码 4 张，2 核 2G 的机器上不能任由超大原图把内存吃光。
+func decodeCoverImage(data []byte) (image.Image, bool) {
+	if len(data) == 0 {
+		return nil, false
+	}
+	cfg, _, err := image.DecodeConfig(bytes.NewReader(data))
+	if err != nil || cfg.Width <= 0 || cfg.Height <= 0 {
+		return nil, false
+	}
+	if cfg.Width*cfg.Height > imageResizeMaxSourcePixels {
+		return nil, false
+	}
+	img, _, err := image.Decode(bytes.NewReader(data))
+	if err != nil {
+		return nil, false
+	}
+	return img, true
+}
+
+// drawCoverCell 把一张图按中心裁切铺满目标格子。
+func drawCoverCell(dst *image.RGBA, cell image.Rectangle, src image.Image) {
+	if src == nil || cell.Dx() <= 0 || cell.Dy() <= 0 {
+		return
+	}
+	bounds := src.Bounds()
+	srcW, srcH := bounds.Dx(), bounds.Dy()
+	if srcW <= 0 || srcH <= 0 {
+		return
+	}
+	targetAspect := float64(cell.Dx()) / float64(cell.Dy())
+	srcAspect := float64(srcW) / float64(srcH)
+	crop := bounds
+	if srcAspect > targetAspect {
+		cropW := int(float64(srcH)*targetAspect + 0.5)
+		if cropW < 1 {
+			cropW = 1
+		}
+		x0 := bounds.Min.X + (srcW-cropW)/2
+		crop = image.Rect(x0, bounds.Min.Y, x0+cropW, bounds.Max.Y)
+	} else if srcAspect < targetAspect {
+		cropH := int(float64(srcW)/targetAspect + 0.5)
+		if cropH < 1 {
+			cropH = 1
+		}
+		y0 := bounds.Min.Y + (srcH-cropH)/2
+		crop = image.Rect(bounds.Min.X, y0, bounds.Max.X, y0+cropH)
+	}
+	scale := float64(cell.Dx()) / float64(crop.Dx())
+	var scaler draw.Scaler = draw.CatmullRom
+	if scale < imageResizeCheapScaleRatio {
+		scaler = draw.ApproxBiLinear
+	}
+	scaler.Scale(dst, cell, src, crop, draw.Src, nil)
+}
+
+// writeFileAtomic 先写临时文件再 rename，避免并发的读取方读到半个文件。
+func writeFileAtomic(path string, data []byte) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o750); err != nil {
+		return err
+	}
+	tmp, err := os.CreateTemp(dir, ".cover-*")
+	if err != nil {
+		return err
+	}
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		_ = os.Remove(tmp.Name())
+		return err
+	}
+	if err := tmp.Close(); err != nil {
+		_ = os.Remove(tmp.Name())
+		return err
+	}
+	if err := os.Rename(tmp.Name(), path); err != nil {
+		_ = os.Remove(tmp.Name())
+		return err
+	}
+	return nil
+}
+
+// LibraryCoverSourcesForLibrary 是给 handler 的便捷封装：库存在且没有自定
+// 义封面时返回成员海报来源；远程挂载库由各自的上游负责封面，不在此生成。
+func LibraryCoverSourcesForLibrary(ctx context.Context, repos *repository.Container, libraryID string) ([]string, *model.Library) {
+	if repos == nil || repos.Library == nil {
+		return nil, nil
+	}
+	libraryID = strings.TrimSpace(libraryID)
+	if libraryID == "" {
+		return nil, nil
+	}
+	lib, err := repos.Library.FindByID(ctx, libraryID)
+	if err != nil || lib == nil {
+		return nil, nil
+	}
+	if strings.TrimSpace(lib.CoverURL) != "" {
+		return nil, lib
+	}
+	return LibraryCoverSources(ctx, repos, libraryID, libraryCoverSourceLimit), lib
+}

internal/service/library_cover_test.go

@@ -0,0 +1,335 @@
+package service
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func solidJPEG(t *testing.T, c color.Color, w, h int) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, w, h))
+	for y := 0; y < h; y++ {
+		for x := 0; x < w; x++ {
+			img.Set(x, y, c)
+		}
+	}
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: 95}); err != nil {
+		t.Fatalf("encode jpeg: %v", err)
+	}
+	return buf.Bytes()
+}
+
+func decodeJPEG(t *testing.T, data []byte) image.Image {
+	t.Helper()
+	img, err := jpeg.Decode(bytes.NewReader(data))
+	if err != nil {
+		t.Fatalf("decode composed cover: %v", err)
+	}
+	return img
+}
+
+// TestComposeLibraryCoverSplitsIntoSideBySideColumns 保证多张海报是竖切成
+// 左右分栏（左→右顺序），而不是 2×2 田字格。
+func TestComposeLibraryCoverSplitsIntoSideBySideColumns(t *testing.T) {
+	images := [][]byte{
+		solidJPEG(t, color.RGBA{R: 220, A: 255}, 200, 300),
+		solidJPEG(t, color.RGBA{G: 220, A: 255}, 200, 300),
+		solidJPEG(t, color.RGBA{B: 220, A: 255}, 200, 300),
+		solidJPEG(t, color.RGBA{R: 220, G: 220, A: 255}, 200, 300),
+	}
+	out, err := composeLibraryCover(images, 480, 270)
+	if err != nil {
+		t.Fatalf("compose: %v", err)
+	}
+	img := decodeJPEG(t, out)
+	if img.Bounds().Dx() != 480 || img.Bounds().Dy() != 270 {
+		t.Fatalf("size = %v, want 480x270", img.Bounds())
+	}
+	// 四张图 → 四条竖栏；同一栏从顶部到底部颜色一致（竖切，不是上下分割）。
+	y := img.Bounds().Dy() / 2
+	checks := []struct {
+		name     string
+		x        int
+		dominant func(color.RGBA) bool
+	}{
+		{"column 1 red", 60, func(c color.RGBA) bool { return c.R > c.G+40 && c.R > c.B+40 }},
+		{"column 2 green", 180, func(c color.RGBA) bool { return c.G > c.R+40 && c.G > c.B+40 }},
+		{"column 3 blue", 300, func(c color.RGBA) bool { return c.B > c.R+40 && c.B > c.G+40 }},
+		{"column 4 yellow", 420, func(c color.RGBA) bool { return c.R > c.B+40 && c.G > c.B+40 }},
+	}
+	for _, check := range checks {
+		for _, yy := range []int{2, y, img.Bounds().Dy() - 3} {
+			r, g, b, _ := img.At(check.x, yy).RGBA()
+			got := color.RGBA{R: uint8(r >> 8), G: uint8(g >> 8), B: uint8(b >> 8), A: 255}
+			if !check.dominant(got) {
+				t.Fatalf("%s at y=%d: pixel = %v", check.name, yy, got)
+			}
+		}
+	}
+}
+
+// TestComposeLibraryCoverHandlesFewerPosters 覆盖 1/2/3 张成员的布局。
+func TestComposeLibraryCoverHandlesFewerPosters(t *testing.T) {
+	cases := []struct {
+		name  string
+		count int
+	}{
+		{"single", 1},
+		{"pair", 2},
+		{"triple", 3},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			images := make([][]byte, 0, tc.count)
+			for i := 0; i < tc.count; i++ {
+				images = append(images, solidJPEG(t, color.RGBA{R: 200, G: 120, A: 255}, 300, 450))
+			}
+			out, err := composeLibraryCover(images, 320, 180)
+			if err != nil {
+				t.Fatalf("compose: %v", err)
+			}
+			img := decodeJPEG(t, out)
+			if img.Bounds().Dx() != 320 || img.Bounds().Dy() != 180 {
+				t.Fatalf("size = %v, want 320x180", img.Bounds())
+			}
+		})
+	}
+}
+
+// TestComposeLibraryCoverSkipsUndecodableSources 保证一张坏图不会让整张
+// 封面失败：其余可解码的成员仍然会拼出来。
+func TestComposeLibraryCoverSkipsUndecodableSources(t *testing.T) {
+	images := [][]byte{
+		[]byte("not an image"),
+		solidJPEG(t, color.RGBA{G: 200, A: 255}, 200, 300),
+	}
+	out, err := composeLibraryCover(images, 240, 135)
+	if err != nil {
+		t.Fatalf("compose: %v", err)
+	}
+	if len(out) == 0 {
+		t.Fatal("expected composed cover bytes")
+	}
+	if _, err := composeLibraryCover([][]byte{[]byte("nope")}, 240, 135); err == nil {
+		t.Fatal("expected error when no source is decodable")
+	}
+}
+
+func TestLibraryCoverCanvasKeepsSixteenByNine(t *testing.T) {
+	cases := []struct {
+		inW, inH   int
+		wantW      int
+		wantH      int
+		checkRatio bool
+	}{
+		{0, 0, 480, 270, true},
+		{640, 480, 640, 360, true},   // 4:3 盒子 → 装进 16:9
+		{2000, 0, 1920, 1080, true},  // 超上限 → 夹紧
+		{40, 0, 96, 54, true},        // 低于下限 → 抬到最小宽度
+		{0, 540, 960, 540, false},    // 只给高度 → 按 16:9 推宽度
+	}
+	for _, tc := range cases {
+		w, h := libraryCoverCanvas(tc.inW, tc.inH)
+		if w != tc.wantW || h != tc.wantH {
+			t.Fatalf("libraryCoverCanvas(%d,%d) = %dx%d, want %dx%d", tc.inW, tc.inH, w, h, tc.wantW, tc.wantH)
+		}
+		if tc.checkRatio && w != 0 && h != 0 {
+			ratio := float64(w) / float64(h)
+			if ratio < 1.7 || ratio > 1.85 {
+				t.Fatalf("ratio for %dx%d = %.3f, want ~1.78", tc.inW, tc.inH, ratio)
+			}
+		}
+	}
+}
+
+// TestLibraryCoverSourcesDedupesSeries 保证封面不会两张都是同一部剧的不同集，
+// 并且优先取海报、没有海报时退回剧照、完全没有图的成员被跳过。
+func TestLibraryCoverSourcesDedupesSeries(t *testing.T) {
+	svc := newTestEmbyService(t)
+	lib := model.Library{Name: "剧集", Path: "/media/tv", Type: "tv", Enabled: true}
+	if err := svc.repo.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	rows := []model.Media{
+		{Base: model.Base{ID: "a1"}, LibraryID: lib.ID, Title: "A", Path: "/media/tv/A/S01E01.mkv", SeriesID: "series-a", PosterURL: "https://img/a1.jpg"},
+		{Base: model.Base{ID: "a2"}, LibraryID: lib.ID, Title: "A", Path: "/media/tv/A/S01E02.mkv", SeriesID: "series-a", PosterURL: "https://img/a2.jpg"},
+		{Base: model.Base{ID: "b1"}, LibraryID: lib.ID, Title: "B", Path: "/media/tv/B/S01E01.mkv", SeriesID: "series-b", PosterURL: "https://img/b1.jpg"},
+		{Base: model.Base{ID: "c1"}, LibraryID: lib.ID, Title: "C", Path: "/media/tv/C/S01E01.mkv", SeriesID: "series-c", BackdropURL: "https://img/c1-backdrop.jpg"},
+		{Base: model.Base{ID: "d1"}, LibraryID: lib.ID, Title: "D", Path: "/media/tv/D/S01E01.mkv", SeriesID: "series-d"},
+	}
+	for i := range rows {
+		if err := svc.repo.DB.Create(&rows[i]).Error; err != nil {
+			t.Fatalf("create media: %v", err)
+		}
+	}
+	// 竖切三栏：一部剧只出一张，无图成员被跳过 → 正好 3 张。
+	sources := LibraryCoverSources(t.Context(), svc.repo, lib.ID, libraryCoverSourceLimit)
+	if len(sources) != 3 {
+		t.Fatalf("sources = %v, want 3 (一部剧一张、跳过无图成员)", sources)
+	}
+	seen := map[string]bool{}
+	for _, src := range sources {
+		if seen[src] {
+			t.Fatalf("duplicate source in %v", sources)
+		}
+		seen[src] = true
+	}
+	// 同一部剧只会出现一次：具体保留哪一集由查询顺序决定，但绝不能两张。
+	if seen["https://img/a1.jpg"] && seen["https://img/a2.jpg"] {
+		t.Fatalf("same series contributed two posters: %v", sources)
+	}
+	if !seen["https://img/a1.jpg"] && !seen["https://img/a2.jpg"] {
+		t.Fatalf("series A is missing from sources: %v", sources)
+	}
+	if !seen["https://img/c1-backdrop.jpg"] {
+		t.Fatalf("member without poster should fall back to backdrop: %v", sources)
+	}
+}
+
+// TestLibraryCoverImageCachesComposedBytes 验证生成结果会落盘复用：同一份
+// 内容第二次请求不再回源。
+func TestLibraryCoverImageCachesComposedBytes(t *testing.T) {
+	var hits int32
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&hits, 1)
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(solidJPEG(t, color.RGBA{R: 180, G: 140, B: 90, A: 255}, 240, 360))
+	}))
+	defer upstream.Close()
+
+	parsed, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatalf("parse upstream: %v", err)
+	}
+	cacheCfg := &config.Config{Cache: config.CacheConfig{CacheDir: filepath.Join(t.TempDir(), "cache")}}
+	proxy := NewImageProxy(cacheCfg, zap.NewNop())
+	proxy.SetAllowedRemoteHostsProvider(func() []string { return []string{parsed.Host} })
+
+	sources := []string{upstream.URL + "/1.jpg", upstream.URL + "/2.jpg", upstream.URL + "/3.jpg", upstream.URL + "/4.jpg"}
+	first, err := proxy.LibraryCoverImage(t.Context(), "lib-1", sources, 480, 270)
+	if err != nil {
+		t.Fatalf("first cover: %v", err)
+	}
+	if img := decodeJPEG(t, first); img.Bounds().Dx() != 480 || img.Bounds().Dy() != 270 {
+		t.Fatalf("size = %v, want 480x270", img.Bounds())
+	}
+	hitsAfterFirst := atomic.LoadInt32(&hits)
+	if hitsAfterFirst != 4 {
+		t.Fatalf("upstream hits = %d, want one per source", hitsAfterFirst)
+	}
+
+	second, err := proxy.LibraryCoverImage(t.Context(), "lib-1", sources, 480, 270)
+	if err != nil {
+		t.Fatalf("second cover: %v", err)
+	}
+	if !bytes.Equal(first, second) {
+		t.Fatal("cached cover bytes differ from the first build")
+	}
+	if got := atomic.LoadInt32(&hits); got != hitsAfterFirst {
+		t.Fatalf("cache miss: upstream hits %d -> %d", hitsAfterFirst, got)
+	}
+
+	// 内容变了要重新生成（成员海报换了新文件）。已缓存的三张海报不会重下，
+	// 只有新增的那张会回源。
+	changed := append([]string{}, sources[:3]...)
+	changed = append(changed, upstream.URL+"/5.jpg")
+	if _, err := proxy.LibraryCoverImage(t.Context(), "lib-1", changed, 480, 270); err != nil {
+		t.Fatalf("cover after content change: %v", err)
+	}
+	if got := atomic.LoadInt32(&hits); got != hitsAfterFirst+1 {
+		t.Fatalf("content change should rebuild with one new fetch, hits = %d", got)
+	}
+
+	// 同一批成员的另一个尺寸档位要能共存：Web/App 与 Emby 请求的尺寸不同，
+	// 不能互相把对方的成品当「旧内容」删掉。
+	if _, err := proxy.LibraryCoverImage(t.Context(), "lib-1", changed, 400, 225); err != nil {
+		t.Fatalf("other size cover: %v", err)
+	}
+	entries, err := os.ReadDir(LibraryCoverCacheDir(cacheCfg.Cache.CacheDir))
+	if err != nil {
+		t.Fatalf("read cover cache dir: %v", err)
+	}
+	files := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			files = append(files, entry.Name())
+		}
+	}
+	if len(files) != 2 {
+		t.Fatalf("expected 480x270 and 400x225 variants to coexist, got %v", files)
+	}
+}
+
+// TestLibraryCoverSourceBytesReadsLocalSidecarPoster 覆盖刮削把海报存成
+// /media/... 本地绝对路径的情况：这类来源没有 http(s) host，不能走 Fetch，
+// 必须按库根目录白名单直接读盘，否则整张拼图会因为「没有可解码的海报」而
+// 生成失败（生产环境所有本地库都是这种来源）。
+func TestLibraryCoverSourceBytesReadsLocalSidecarPoster(t *testing.T) {
+	libDir := t.TempDir()
+	posterPath := filepath.Join(libDir, "poster.jpg")
+	if err := os.WriteFile(posterPath, solidJPEG(t, color.RGBA{R: 180, G: 90, A: 255}, 200, 300), 0o644); err != nil {
+		t.Fatalf("write poster: %v", err)
+	}
+	proxy := NewImageProxy(&config.Config{Cache: config.CacheConfig{CacheDir: filepath.Join(t.TempDir(), "cache")}}, zap.NewNop())
+
+	// 未登记为库根目录时必须拒绝读取。
+	if _, err := proxy.coverSourceBytes(t.Context(), posterPath); err == nil {
+		t.Fatal("expected local path outside the library roots to be rejected")
+	}
+
+	proxy.SetLibraryRootsProvider(func() []string { return []string{libDir} })
+	data, err := proxy.coverSourceBytes(t.Context(), posterPath)
+	if err != nil {
+		t.Fatalf("read local poster: %v", err)
+	}
+	if len(data) == 0 {
+		t.Fatal("expected poster bytes")
+	}
+	if _, ok := decodeCoverImage(data); !ok {
+		t.Fatal("local poster should decode")
+	}
+}
+
+// TestLibraryCoverSourcesForLibrarySkipsCustomCover 保证管理员填了自定义
+// 封面时不会再生成拼图（沿用自定义图）。
+func TestLibraryCoverSourcesForLibrarySkipsCustomCover(t *testing.T) {
+	svc := newTestEmbyService(t)
+	lib := model.Library{Name: "电影", Path: "/media/movies", Type: "movie", CoverURL: "https://example.com/custom.jpg"}
+	if err := svc.repo.Library.Create(t.Context(), &lib); err != nil {
+		t.Fatalf("create library: %v", err)
+	}
+	if err := svc.repo.DB.Create(&model.Media{
+		Base:      model.Base{ID: "m1"},
+		LibraryID: lib.ID,
+		Title:     "M",
+		Path:      "/media/movies/m1.mkv",
+		PosterURL: "https://img/m1.jpg",
+	}).Error; err != nil {
+		t.Fatalf("create media: %v", err)
+	}
+	sources, found := LibraryCoverSourcesForLibrary(t.Context(), svc.repo, lib.ID)
+	if found == nil || found.CoverURL != lib.CoverURL {
+		t.Fatalf("library = %#v, want the existing library", found)
+	}
+	if len(sources) != 0 {
+		t.Fatalf("expected no generated sources with a custom cover, got %v", sources)
+	}
+	if _, blank := LibraryCoverSourcesForLibrary(t.Context(), svc.repo, "missing"); blank != nil {
+		t.Fatalf("unknown library should return nil, got %#v", blank)
+	}
+}

internal/service/manual_mark_test.go

@@ -0,0 +1,165 @@
+package service
+
+import (
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+func newManualMarkFixture(t *testing.T) (*MediaSegmentService, *repository.Container, *model.Media) {
+	t.Helper()
+	repos := repository.New(newServiceTestDB(t))
+	svc := NewMediaSegmentService(zap.NewNop(), repos)
+	m := &model.Media{
+		Base:       model.Base{ID: "ep-1"},
+		Title:      "Show",
+		Path:       "/tv/show/s01e01.mkv",
+		LibraryID:  "lib-1",
+		SeasonNum:  1,
+		EpisodeNum: 1,
+	}
+	if err := repos.DB.Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+	return svc, repos, m
+}
+
+func TestSetManualMarkWritesIntroBoundary(t *testing.T) {
+	svc, repos, m := newManualMarkFixture(t)
+	if err := svc.SetManualMark(t.Context(), m, ManualMarkRequest{
+		Kind: model.SegmentKindIntro, PositionMs: 90_000,
+	}); err != nil {
+		t.Fatalf("set mark: %v", err)
+	}
+	rows, err := repos.MediaSegment.ListByMedia(t.Context(), m.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 {
+		t.Fatalf("rows = %#v, want 1", rows)
+	}
+	if rows[0].Kind != model.SegmentKindIntro || rows[0].Source != SegmentSourceManual {
+		t.Fatalf("row = %#v, want manual intro", rows[0])
+	}
+	if rows[0].StartMs != 0 || rows[0].EndMs != 90_000 {
+		t.Fatalf("row = %#v, want 0-90000ms", rows[0])
+	}
+}
+
+func TestSetManualMarkClearRemovesOnlyThatKind(t *testing.T) {
+	svc, repos, m := newManualMarkFixture(t)
+	ctx := t.Context()
+	if err := svc.SetManualMark(ctx, m, ManualMarkRequest{Kind: model.SegmentKindIntro, PositionMs: 90_000}); err != nil {
+		t.Fatal(err)
+	}
+	if err := svc.SetManualMark(ctx, m, ManualMarkRequest{Kind: model.SegmentKindCredits, PositionMs: 1_200_000}); err != nil {
+		t.Fatal(err)
+	}
+	if err := svc.SetManualMark(ctx, m, ManualMarkRequest{Kind: model.SegmentKindIntro, Clear: true}); err != nil {
+		t.Fatal(err)
+	}
+	rows, err := repos.MediaSegment.ListByMedia(ctx, m.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 || rows[0].Kind != model.SegmentKindCredits {
+		t.Fatalf("rows = %#v, want only the credits mark to survive", rows)
+	}
+}
+
+func TestSetManualMarkRejectsInvalidRequests(t *testing.T) {
+	svc, _, m := newManualMarkFixture(t)
+	cases := []ManualMarkRequest{
+		{Kind: "recap", PositionMs: 1000},   // 只支持 intro/credits
+		{Kind: "preview", PositionMs: 1000}, // 同上
+		{Kind: model.SegmentKindIntro, PositionMs: 0},
+		{Kind: model.SegmentKindIntro, PositionMs: -5},
+	}
+	for _, req := range cases {
+		if err := svc.SetManualMark(t.Context(), m, req); err == nil {
+			t.Fatalf("req %#v: want an error", req)
+		}
+	}
+}
+
+// 同一季的其它集应自动继承手动标记，但用户已显式标过的集不能被覆盖。
+func TestSetManualMarkPropagatesToSeasonSiblings(t *testing.T) {
+	svc, repos, m := newManualMarkFixture(t)
+	ctx := t.Context()
+	sibling := &model.Media{
+		Base:       model.Base{ID: "ep-2"},
+		Title:      "Show",
+		Path:       "/tv/show/s01e02.mkv",
+		LibraryID:  "lib-1",
+		SeasonNum:  1,
+		EpisodeNum: 2,
+	}
+	other := &model.Media{
+		Base:       model.Base{ID: "ep-3"},
+		Title:      "Show",
+		Path:       "/tv/show/s01e03.mkv",
+		LibraryID:  "lib-1",
+		SeasonNum:  1,
+		EpisodeNum: 3,
+	}
+	if err := repos.DB.Create(sibling).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.DB.Create(other).Error; err != nil {
+		t.Fatal(err)
+	}
+	// other 已经有自己的手动片头标记，不该被覆盖。
+	if err := svc.SetManualMark(ctx, other, ManualMarkRequest{
+		Kind: model.SegmentKindIntro, PositionMs: 45_000,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := svc.SetManualMark(ctx, m, ManualMarkRequest{
+		Kind: model.SegmentKindIntro, PositionMs: 90_000,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	sibRows, err := repos.MediaSegment.ListByMedia(ctx, sibling.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(sibRows) != 1 || sibRows[0].EndMs != 90_000 {
+		t.Fatalf("sibling rows = %#v, want the propagated 90000ms mark", sibRows)
+	}
+
+	otherRows, err := repos.MediaSegment.ListByMedia(ctx, other.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(otherRows) != 1 || otherRows[0].EndMs != 45_000 {
+		t.Fatalf("other rows = %#v, want its own 45000ms mark preserved", otherRows)
+	}
+}
+
+// 手动标记优先级最高：即使外部源给了不同位置，播放时也只输出手动那条。
+func TestManualMarkOutranksExternalSource(t *testing.T) {
+	svc, repos, m := newManualMarkFixture(t)
+	ctx := t.Context()
+	if err := repos.MediaSegment.ReplaceForMedia(ctx, m.ID, IntroDBSource, []model.MediaSegment{{
+		MediaID: m.ID, Kind: model.SegmentKindIntro, StartMs: 0, EndMs: 30_000, Source: IntroDBSource,
+	}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := svc.SetManualMark(ctx, m, ManualMarkRequest{
+		Kind: model.SegmentKindIntro, PositionMs: 90_000,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	rows, err := svc.mergeForPlayback(ctx, m.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 || rows[0].Source != SegmentSourceManual || rows[0].EndMs != 90_000 {
+		t.Fatalf("rows = %#v, want the manual mark to win", rows)
+	}
+}

internal/service/media_segment.go

@@ -6,6 +6,7 @@ package service
 
 import (
 	"context"
+	"errors"
 	"strings"
 	"time"
 
@@ -43,9 +44,20 @@ type SegmentView struct {
 }
 
 // ToSegmentViews 转换库内行为对外视图。
+//
+// 顺手丢掉明显不可能的区间：库里的历史数据可能是在 end_ms: 0 被误当成「到片尾」
+// 的时期写下的（那会把整集变成片头），这些行如果原样下发，播放器仍然会整集弹
+// 跳过按钮。只有片尾类允许开放结束点（EndMs == 0），其余要求 EndMs > StartMs。
 func ToSegmentViews(rows []model.MediaSegment) []SegmentView {
 	out := make([]SegmentView, 0, len(rows))
 	for _, row := range rows {
+		openEnded := row.Kind == model.SegmentKindCredits || row.Kind == model.SegmentKindPreview
+		if row.StartMs < 0 {
+			continue
+		}
+		if row.EndMs <= row.StartMs && !(openEnded && row.EndMs <= 0) {
+			continue
+		}
 		out = append(out, SegmentView{Kind: row.Kind, StartMs: row.StartMs, EndMs: row.EndMs})
 	}
 	return out
@@ -53,16 +65,36 @@ func ToSegmentViews(rows []model.MediaSegment) []SegmentView {
 
 // MediaSegmentService 负责把外部片头片尾数据补齐到本地并供播放器读取。
 type MediaSegmentService struct {
-	log     *zap.Logger
-	repo    *repository.Container
-	introdb *IntroDBService
-	// probe 负责异步补齐媒体信息（主要是 STRM 时长）。未注入时只用 TheIntroDB。
+	log  *zap.Logger
+	repo *repository.Container
+	// probe 负责异步补齐媒体信息（主要是 STRM 时长）。未注入时只用外部源。
 	probe *MediaProbeService
-	// prewarmGap 是预热两次 IntroDB 请求之间的间隔；测试可设为 0。
+	// prewarmGap 是预热两次请求之间的间隔；测试可设为 0。
 	prewarmGap time.Duration
 	now        func() time.Time
+	// providers 是已启用的外部片段源，顺序即注册顺序。
+	// 由设置项 segment.source 决定实际使用哪一个，见 activeProvider。
+	providers []SegmentProvider
+	// imdb 用于给只认 IMDb id 的源（IntroDB）解析外部 id。未注入时该源被跳过。
+	imdb IMDbIDResolver
 }
 
+// IMDbIDResolver 把 TMDb 条目解析成 IMDb id（ttXXXXXXX）。
+// 由 TMDbProvider 实现；抽出接口是为了让 service 层不直接依赖配置与 API key。
+type IMDbIDResolver interface {
+	ResolveIMDbID(ctx context.Context, tmdbID int, isMovie bool) (string, error)
+}
+
+// 片段数据源设置项。取值形如 off / theintrodb / introdb / todb，
+// 与播放器档案里的「自动跳过」是两件独立的事。
+const SegmentSourceSettingKey = "segment.source"
+
+// SegmentSourceOff 表示不查询任何外部源，只消费已落库的数据（手动标记等）。
+const SegmentSourceOff = "off"
+
+// SegmentSourceOptions 是设置页可选的源标识。
+var SegmentSourceOptions = []string{SegmentSourceOff, IntroDBSource, IntroDBAppSource, TODbSource}
+
 // NewMediaSegmentService is the constructor.
 func NewMediaSegmentService(log *zap.Logger, repo *repository.Container) *MediaSegmentService {
 	return &MediaSegmentService{
@@ -81,14 +113,98 @@ func (s *MediaSegmentService) SetPrewarmGap(gap time.Duration) *MediaSegmentServ
 	return s
 }
 
-// SetIntroDB wires the provider. Without it the service only reads cached rows.
+// SetIntroDB wires the TheIntroDB provider and registers it as a source.
 func (s *MediaSegmentService) SetIntroDB(p *IntroDBService) *MediaSegmentService {
 	if s != nil {
-		s.introdb = p
+		s.registerProvider(p)
 	}
 	return s
 }
 
+// SetIntroDBApp wires the IntroDB (introdb.app) provider.
+func (s *MediaSegmentService) SetIntroDBApp(p *IntroDBAppService) *MediaSegmentService {
+	if s != nil {
+		s.registerProvider(p)
+	}
+	return s
+}
+
+// SetTODb wires the TODb provider.
+func (s *MediaSegmentService) SetTODb(p *TODbService) *MediaSegmentService {
+	if s != nil {
+		s.registerProvider(p)
+	}
+	return s
+}
+
+// SetIMDbResolver wires the TMDb-backed IMDb id resolver used by sources that
+// only address media by IMDb id.
+func (s *MediaSegmentService) SetIMDbResolver(r IMDbIDResolver) *MediaSegmentService {
+	if s != nil {
+		s.imdb = r
+	}
+	return s
+}
+
+// registerProvider adds a provider once, keeping registration order as the
+// fallback order.
+func (s *MediaSegmentService) registerProvider(p SegmentProvider) {
+	if s == nil || p == nil {
+		return
+	}
+	for _, existing := range s.providers {
+		if existing.Source() == p.Source() {
+			return
+		}
+	}
+	s.providers = append(s.providers, p)
+}
+
+// providerBySource returns the registered provider with that source tag.
+func (s *MediaSegmentService) providerBySource(source string) SegmentProvider {
+	for _, p := range s.providers {
+		if p.Source() == source {
+			return p
+		}
+	}
+	return nil
+}
+
+// activeProvider 选出本次查询要用的源。
+//
+// 设置项没配置时沿用历史行为（TheIntroDB），避免升级后功能凭空消失；
+// 显式配置成 off 才真正停用外部查询。
+func (s *MediaSegmentService) activeProvider(ctx context.Context) SegmentProvider {
+	if s == nil || len(s.providers) == 0 {
+		return nil
+	}
+	source := s.configuredSource(ctx)
+	if source == "" {
+		return s.providerBySource(IntroDBSource)
+	}
+	if source == SegmentSourceOff {
+		return nil
+	}
+	if p := s.providerBySource(source); p != nil {
+		return p
+	}
+	// 配了一个不认识的源（多半是降级回滚后的残留设置）：退回默认源，
+	// 让功能继续可用，而不是静默失效。
+	return s.providerBySource(IntroDBSource)
+}
+
+// configuredSource reads the operator's source selection.
+func (s *MediaSegmentService) configuredSource(ctx context.Context) string {
+	if s == nil || s.repo == nil || s.repo.Setting == nil {
+		return ""
+	}
+	v, err := s.repo.Setting.Get(ctx, SegmentSourceSettingKey)
+	if err != nil {
+		return ""
+	}
+	return strings.ToLower(strings.TrimSpace(v))
+}
+
 // SetProbe wires the async media probe (duration backfill for STRM). Without it
 // open-ended credits still work once duration is known from elsewhere.
 func (s *MediaSegmentService) SetProbe(p *MediaProbeService) *MediaSegmentService {
@@ -114,7 +230,7 @@ func (s *MediaSegmentService) ListForPlayback(ctx context.Context, m *model.Medi
 	// 写库，若在本次写事务还没结束时启动，两个写事务会抢同一把锁（SQLite 下就是
 	// SQLITE_BUSY，实测能直接把社区库的落库打失败）。
 	defer s.ensureMediaProbe(ctx, m)
-	return s.introDBSegments(ctx, m)
+	return s.communitySegments(ctx, m)
 }
 
 // ensureMediaProbe 在还没探过（或上次失败已过冷却期）时起一次异步探测。
@@ -147,10 +263,15 @@ func mediaProbeSettled(row *model.MediaProbe) bool {
 	return time.Since(row.ProbedAt) < mediaProbeFailureRetry
 }
 
-// introDBSegments 读社区库的片段，缓存过期时按调用方的预算抓一次并落库。
-// 返回值是按来源优先级合并后的结果（manual > theintrodb > propagated）。
-func (s *MediaSegmentService) introDBSegments(ctx context.Context, m *model.Media) ([]model.MediaSegment, error) {
-	ledger, err := s.repo.MediaSegment.GetFetch(ctx, m.ID, IntroDBSource)
+// communitySegments 读社区库的片段，缓存过期时按调用方的预算抓一次并落库。
+// 返回值是按来源优先级合并后的结果（manual > 外部源 > propagated）。
+func (s *MediaSegmentService) communitySegments(ctx context.Context, m *model.Media) ([]model.MediaSegment, error) {
+	provider := s.activeProvider(ctx)
+	// 没选任何外部源（off）：只读本地已有数据，绝不发起外网请求。
+	if provider == nil {
+		return s.mergeForPlayback(context.WithoutCancel(ctx), m.ID)
+	}
+	ledger, err := s.repo.MediaSegment.GetFetch(ctx, m.ID, provider.Source())
 	if err != nil {
 		// 调用方预算耗尽时仍读本地缓存，绝不能让播放接口报错。
 		if ctx.Err() != nil {
@@ -159,7 +280,7 @@ func (s *MediaSegmentService) introDBSegments(ctx context.Context, m *model.Medi
 		return nil, err
 	}
 	if ledger == nil || !ledgerFresh(ledger) {
-		if _, _, err := s.refresh(ctx, m); err != nil {
+		if _, _, err := s.refreshWithProvider(ctx, m, provider); err != nil {
 			// 社区库不可达或返回异常：沿用已有缓存，不影响播放；也不写负缓存。
 			logIntroDBFailure(s.log, 0, err)
 		}
@@ -178,13 +299,22 @@ func (s *MediaSegmentService) mergeForPlayback(ctx context.Context, mediaID stri
 }
 
 // segmentSourcePriority 数值越大越优先。未知来源视为最低，避免挡住已知源。
+//
+// 顺序体现用户意图的强度：
+//
+//	manual     用户在当前集显式标记
+//	propagated 用户在同季其它集标记后继承来的值（仍然是人给的，优先于社区库）
+//	外部社区库  自动抓取，最容易被覆盖
+//
+// 外部社区库之间刻意同级：用户一次只会启用其中一个，历史数据可能来自另一个，
+// 同级时按区间起点排序展示即可，不必让旧源压住新源。
 func segmentSourcePriority(source string) int {
 	switch source {
 	case SegmentSourceManual:
 		return 3
-	case IntroDBSource:
-		return 2
 	case SegmentSourcePropagated:
+		return 2
+	case IntroDBSource, IntroDBAppSource, TODbSource:
 		return 1
 	default:
 		return 0
@@ -224,16 +354,17 @@ func (s *MediaSegmentService) debug(message, mediaID string, err error) {
 	s.log.Debug(message, zap.String("media_id", mediaID), zap.Error(err))
 }
 
-// refresh 向提供方查询并落库，返回 (rows, 是否真的发起过查询, error)。
+// refreshWithProvider 向指定来源查询并落库，返回 (rows, 是否真的发起过查询, error)。
 //
 // attempted=false 表示这部媒体缺少可查询的外部 ID（最常见的原因是还没刮削，
-// 剧集也还没关联到 Series），此时刻意不写负缓存：等元数据补齐后下次播放就能查到。
-func (s *MediaSegmentService) refresh(ctx context.Context, m *model.Media) ([]model.MediaSegment, bool, error) {
-	if s.introdb == nil {
+// 剧集也还没关联到 Series），或者该源需要的 id 类型拿不到（IntroDB 要 IMDb），
+// 此时刻意不写负缓存：等元数据补齐后下次播放就能查到。
+func (s *MediaSegmentService) refreshWithProvider(ctx context.Context, m *model.Media, provider SegmentProvider) ([]model.MediaSegment, bool, error) {
+	if s == nil || provider == nil || m == nil {
 		return nil, false, nil
 	}
-	tmdbID, season, episode := s.queryIDs(ctx, m)
-	if tmdbID <= 0 {
+	query, ok := s.segmentQuery(ctx, m, provider)
+	if !ok {
 		return nil, false, nil
 	}
 	// 用脱离请求的 context：客户端可能在抓取完成前就离开了播放页，但结果仍然
@@ -256,10 +387,11 @@ func (s *MediaSegmentService) refresh(ctx context.Context, m *model.Media) ([]mo
 	fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), budget)
 	defer cancel()
 
-	spans, err := s.introdb.Fetch(fetchCtx, tmdbID, season, episode)
+	spans, err := provider.FetchSegments(fetchCtx, query)
 	if err != nil {
 		return nil, true, err
 	}
+	source := provider.Source()
 	rows := make([]model.MediaSegment, 0, len(spans))
 	for _, span := range spans {
 		rows = append(rows, model.MediaSegment{
@@ -268,15 +400,15 @@ func (s *MediaSegmentService) refresh(ctx context.Context, m *model.Media) ([]mo
 			Kind:     span.Kind,
 			StartMs:  span.StartMs,
 			EndMs:    span.EndMs,
-			Source:   IntroDBSource,
+			Source:   source,
 		})
 	}
-	if err := s.repo.MediaSegment.ReplaceForMedia(fetchCtx, m.ID, IntroDBSource, rows); err != nil {
+	if err := s.repo.MediaSegment.ReplaceForMedia(fetchCtx, m.ID, source, rows); err != nil {
 		return nil, true, err
 	}
 	if err := s.repo.MediaSegment.UpsertFetch(fetchCtx, &model.MediaSegmentFetch{
 		MediaID:   m.ID,
-		Source:    IntroDBSource,
+		Source:    source,
 		FetchedAt: time.Now(),
 		Found:     len(rows) > 0,
 	}); err != nil {
@@ -286,6 +418,38 @@ func (s *MediaSegmentService) refresh(ctx context.Context, m *model.Media) ([]mo
 	return rows, true, nil
 }
 
+// refresh 保留旧签名（预热任务与测试使用），走当前选中的源。
+func (s *MediaSegmentService) refresh(ctx context.Context, m *model.Media) ([]model.MediaSegment, bool, error) {
+	return s.refreshWithProvider(ctx, m, s.activeProvider(ctx))
+}
+
+// segmentQuery 组装该源需要的身份参数。返回 false 表示这个源缺少必要 ID，
+// 本次不必发请求。
+func (s *MediaSegmentService) segmentQuery(ctx context.Context, m *model.Media, provider SegmentProvider) (SegmentQuery, bool) {
+	tmdbID, season, episode := s.queryIDs(ctx, m)
+	isMovie := season <= 0 && episode <= 0
+	q := SegmentQuery{TMDbID: tmdbID, Season: season, Episode: episode, IsMovie: isMovie}
+
+	switch provider.Source() {
+	case IntroDBAppSource:
+		// IntroDB 只认 IMDb id，必须经 TMDb external_ids 解析。
+		if s.imdb == nil || tmdbID <= 0 {
+			return q, false
+		}
+		imdbID, err := s.imdb.ResolveIMDbID(ctx, tmdbID, isMovie)
+		if err != nil || imdbID == "" {
+			// 解析不出 IMDb id 不是错误：这部片可能本来就没有，或 TMDb 不可达。
+			// 返回 false 让本次跳过，但不写负缓存，下次还有机会。
+			s.debug("resolve imdb id failed", m.ID, err)
+			return q, false
+		}
+		q.IMDbID = imdbID
+		return q, true
+	default:
+		return q, tmdbID > 0
+	}
+}
+
 // propagateIntroToSeason 把本集 IntroDB 命中的 intro 复制到同季还没有
 // theintrodb intro 的兄弟集。片尾/预告不传播：各集时长与片尾位置经常不同。
 func (s *MediaSegmentService) propagateIntroToSeason(ctx context.Context, m *model.Media, rows []model.MediaSegment) {
@@ -347,9 +511,131 @@ func hasSegmentKind(rows []model.MediaSegment, kind string) bool {
 	return false
 }
 
-// Prewarm 批量向 TheIntroDB 补齐过期/缺失账本的可查询媒体。返回实际发起过查询的数量。
+// ManualMarkRequest 是「标记片头/片尾」的入参。
+//
+// PositionMs 是用户点击时所在的播放位置：标记片头时它是片头结束点，
+// 标记片尾时它是片尾开始点。
+type ManualMarkRequest struct {
+	Kind       string
+	PositionMs int64
+	// Clear 为 true 表示清除该类型的标记，PositionMs 被忽略。
+	Clear bool
+}
+
+// ErrInvalidManualMark 表示请求本身不合法（类型的取值或位置越界）。
+var ErrInvalidManualMark = errors.New("invalid manual skip mark")
+
+// SetManualMark 写入或清除一条手动标记，并按季传播片头/片尾。
+//
+// 手动标记的优先级最高（见 segmentSourcePriority），所以用户标过一次之后，
+// 外部源即使给出不同位置也不会覆盖它。清除时只删 manual 来源的行，外部数据
+// 会自然回落到优先队列里。
+func (s *MediaSegmentService) SetManualMark(ctx context.Context, m *model.Media, req ManualMarkRequest) error {
+	if s == nil || s.repo == nil || m == nil || m.ID == "" {
+		return ErrInvalidManualMark
+	}
+	kind := normalizeManualMarkKind(req.Kind)
+	if kind == "" {
+		return ErrInvalidManualMark
+	}
+	if !req.Clear && req.PositionMs < 0 {
+		return ErrInvalidManualMark
+	}
+	rows := []model.MediaSegment{}
+	if !req.Clear {
+		if req.PositionMs <= 0 {
+			// 位置 0 的标记没有意义：片头在 0 秒结束等于没有片头。
+			return ErrInvalidManualMark
+		}
+		rows = append(rows, model.MediaSegment{
+			MediaID:  m.ID,
+			SeriesID: m.SeriesID,
+			Kind:     kind,
+			StartMs:  manualMarkStart(kind),
+			EndMs:    req.PositionMs,
+			Source:   SegmentSourceManual,
+		})
+	}
+	if err := s.repo.MediaSegment.ReplaceForMediaSourceKind(ctx, m.ID, SegmentSourceManual, kind, rows); err != nil {
+		return err
+	}
+	if len(rows) > 0 {
+		s.propagateManualMarkToSeason(ctx, m, rows)
+	}
+	return nil
+}
+
+// normalizeManualMarkKind 把外部传入的类型收敛到库内 kind。
+// 只接受片头与片尾：回顾/预告没有对应的用户操作入口。
+func normalizeManualMarkKind(kind string) string {
+	switch strings.ToLower(strings.TrimSpace(kind)) {
+	case model.SegmentKindIntro:
+		return model.SegmentKindIntro
+	case model.SegmentKindCredits:
+		return model.SegmentKindCredits
+	default:
+		return ""
+	}
+}
+
+// manualMarkStart 给出该类型区间的起点：片头从 0 开始，片尾的开始点就是用户
+// 标记的位置（所以这里填 0，真正的起点在 EndMs 里由调用方传入）。
+func manualMarkStart(kind string) int64 { return 0 }
+
+// propagateManualMarkToSeason 把手动标记复制到同季还没有「显式手动标记」的兄弟集。
+//
+// 同一季的 OP/ED 通常一致，标一集即可覆盖整季——这是报告里最实用的行为。
+// 关键约束：传播值必须写成 SegmentSourcePropagated 而不是 manual，这样才能区分
+// 「用户显式标过的集」与「继承来的值」。否则先标 A 集会让 B 集看起来也是手动标
+// 过的，之后用户再标 B 集时反而无法覆盖它（或反过来，B 集的传播值挡住 A 集的
+// 新标记），两种顺序都会得出错误结果。
+func (s *MediaSegmentService) propagateManualMarkToSeason(ctx context.Context, m *model.Media, rows []model.MediaSegment) {
+	if s == nil || s.repo == nil || m == nil || m.SeasonNum <= 0 || len(rows) == 0 {
+		return
+	}
+	siblings, err := s.repo.Media.ListSeasonSiblings(ctx, m)
+	if err != nil {
+		s.debug("list season siblings for manual mark failed", m.ID, err)
+		return
+	}
+	for i := range siblings {
+		sib := &siblings[i]
+		// 用户显式标过的集保持原样；继承值可以被新的显式标记覆盖。
+		explicit, err := s.repo.MediaSegment.ListByMediaSource(ctx, sib.ID, SegmentSourceManual)
+		if err != nil {
+			s.debug("list sibling manual segments failed", sib.ID, err)
+			continue
+		}
+		if hasSegmentKind(explicit, rows[0].Kind) {
+			continue
+		}
+		copied := make([]model.MediaSegment, 0, len(rows))
+		for _, row := range rows {
+			copied = append(copied, model.MediaSegment{
+				MediaID:  sib.ID,
+				SeriesID: sib.SeriesID,
+				Kind:     row.Kind,
+				StartMs:  row.StartMs,
+				EndMs:    row.EndMs,
+				Source:   SegmentSourcePropagated,
+			})
+		}
+		if err := s.repo.MediaSegment.ReplaceForMediaSourceKind(ctx, sib.ID, SegmentSourcePropagated, rows[0].Kind, copied); err != nil {
+			s.debug("propagate manual mark failed", sib.ID, err)
+		}
+	}
+}
+
+// Prewarm 批量补齐过期/缺失账本的可查询媒体。返回实际发起过查询的数量。
+//
+// 只预热当前启用的源：用户把源切成 off 时不该继续打外网，切换源之后旧源的
+// 账本也不再需要刷新。
 func (s *MediaSegmentService) Prewarm(ctx context.Context, limit int) (int, error) {
-	if s == nil || s.repo == nil || s.introdb == nil {
+	if s == nil || s.repo == nil || len(s.providers) == 0 {
+		return 0, nil
+	}
+	provider := s.activeProvider(ctx)
+	if provider == nil {
 		return 0, nil
 	}
 	if limit <= 0 {
@@ -360,7 +646,7 @@ func (s *MediaSegmentService) Prewarm(ctx context.Context, limit int) (int, erro
 		now = s.now()
 	}
 	candidates, err := s.repo.MediaSegment.ListPrewarmCandidates(
-		ctx, IntroDBSource, now.Add(-segmentMissingTTL), now.Add(-segmentFoundTTL), limit,
+		ctx, provider.Source(), now.Add(-segmentMissingTTL), now.Add(-segmentFoundTTL), limit,
 	)
 	if err != nil {
 		return 0, err
@@ -371,7 +657,7 @@ func (s *MediaSegmentService) Prewarm(ctx context.Context, limit int) (int, erro
 			return attempted, err
 		}
 		m := &candidates[i]
-		_, did, err := s.refresh(ctx, m)
+		_, did, err := s.refreshWithProvider(ctx, m, provider)
 		if err != nil {
 			logIntroDBFailure(s.log, m.TMDbID, err)
 		}

internal/service/media_segment_test.go

@@ -385,7 +385,9 @@ func TestListForPlaybackRespectsCallerDeadline(t *testing.T) {
 	}
 }
 
-func TestPreferSegmentsBySourcePrefersManualThenIntroDBThenPropagated(t *testing.T) {
+// 优先级体现「用户意图强度」：manual > propagated > 社区库。
+// 传播值来自用户在同季其它集的手动标记，是人给的，必须压过自动抓取的数据。
+func TestPreferSegmentsBySourcePrefersManualThenPropagatedThenIntroDB(t *testing.T) {
 	rows := []model.MediaSegment{
 		{Kind: model.SegmentKindIntro, StartMs: 1, EndMs: 2, Source: SegmentSourcePropagated},
 		{Kind: model.SegmentKindIntro, StartMs: 10, EndMs: 20, Source: IntroDBSource},
@@ -395,13 +397,14 @@ func TestPreferSegmentsBySourcePrefersManualThenIntroDBThenPropagated(t *testing
 	}
 	got := preferSegmentsBySource(rows)
 	if len(got) != 2 {
-		t.Fatalf("got %#v, want manual intro + introdb credits", got)
+		t.Fatalf("got %#v, want manual intro + propagated credits", got)
 	}
 	if got[0].Source != SegmentSourceManual || got[0].StartMs != 100 {
 		t.Fatalf("intro = %#v, want manual", got[0])
 	}
-	if got[1].Source != IntroDBSource || got[1].StartMs != 2000 {
-		t.Fatalf("credits = %#v, want theintrodb", got[1])
+	// 片尾没有 manual，propagated 应当压过社区库。
+	if got[1].Source != SegmentSourcePropagated || got[1].StartMs != 1000 {
+		t.Fatalf("credits = %#v, want propagated", got[1])
 	}
 }
 

internal/service/reader/audio_media_cache.go

@@ -0,0 +1,649 @@
+package reader
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// 远端音轨的本地落盘缓存（媒体代理 /api/reader/media 使用）。
+//
+// 背景：听书源的音频直链签在腾讯音乐 CDN 上，跨境链路会间歇性返回 401
+// 或直接 RST 连接。旧行为是每次请求（首播、拖动进度、播放器重试）都重新
+// 回源，一次抖动就把错误交给播放器。这里按「书 + 媒体对象」把整段音频
+// 落盘（丢掉 ?vkey=... 这类会轮换的签名参数），命中后由 http.ServeContent
+// 按 Range 下发：首播成功之后不再依赖 CDN，拖动进度也是本地读取。
+
+const (
+	audioMediaDirName = "reader-audio"
+	audioMediaTTL     = 7 * 24 * time.Hour
+	// audioMediaMaxBytes 音频缓存的总容量上限。超限时按 mtime 淘汰最旧的。
+	//
+	// 这个池不参与 cache_cleanup 的全局总量统计（hls/images/library-covers
+	// 三池），而是在每次下载成功后自行淘汰，见 pruneAudioMediaCache。
+	audioMediaMaxBytes     = 1 << 30 // 1GiB
+	audioMediaPrunePeriod  = 10 * time.Minute
+	audioMediaPruneKeepPct = 90
+
+	// audioPartialSuffix 未下完的音轨分片后缀。
+	//
+	// 分片跨请求保留：首播失败后用户再点一次、或播放器重连，都能用 Range 接着下，
+	// 不必从第 0 字节重来。分片名带 .part 后缀，不会被 OpenCachedRemoteAudio 当成
+	// 完整音轨下发。
+	audioPartialSuffix = ".part"
+	// audioMediaObjectMaxBytes 单个音频对象的落盘上限。有声书一章约 3–5MB，
+	// 给到 64MB 足够容纳长章节，也能挡住误当成音频的超大对象。
+	audioMediaObjectMaxBytes = 64 << 20
+	// audioDownloadRetryDelay 断点续传重试的退避基数，实际等待为 (attempt-1) 倍。
+	audioDownloadRetryDelay = 500 * time.Millisecond
+)
+
+var (
+	audioMediaPruneMu  sync.Mutex
+	audioMediaPrunedAt time.Time
+)
+
+// audioMediaDir 音频缓存根目录（与转码缓存同一套目录约定）。
+func (s *ReaderService) audioMediaDir() string {
+	if s == nil || s.cfg == nil {
+		return ""
+	}
+	base := strings.TrimSpace(s.cfg.Cache.CacheDir)
+	if base == "" {
+		if dataDir := strings.TrimSpace(s.cfg.App.DataDir); dataDir != "" {
+			base = filepath.Join(dataDir, "cache")
+		}
+	}
+	if base == "" {
+		return ""
+	}
+	return filepath.Join(base, audioMediaDirName)
+}
+
+// audioMediaVolatileParams 是换票时会变、但与「这是哪段音频」无关的 query 参数。
+// 缓存键必须忽略它们，否则每次换票都打不中缓存。
+//
+// 不在这张表里的参数一律保留：有些书源的直链形如
+// https://host/audio?id=12345，路径固定、靠 query 区分章节，把 query 整个丢掉
+// 会让第二集命中第一集的缓存，直接播错集。
+var audioMediaVolatileParams = map[string]bool{
+	"vkey": true, "uid": true, "ct": true, "t": true, "ts": true,
+	"token": true, "sign": true, "signature": true, "sig": true,
+	"expires": true, "expire": true, "expiry": true, "auth": true,
+	"nonce": true, "rand": true, "rnd": true, "r": true, "guid": true,
+	"ftime": true,
+}
+
+// audioMediaCacheKey 缓存键：书 + 媒体对象身份。
+//
+// 身份 = scheme://host/path + 非签名类 query。签名/时效参数（vkey、token、
+// 时间戳等）被剔除，保证换票后仍命中同一条缓存；其余参数保留，避免
+// 「路径相同、只靠 query 区分」的书源串集。
+func audioMediaCacheKey(bookID, mediaURL string) string {
+	u, err := url.Parse(strings.TrimSpace(mediaURL))
+	if err != nil || u.Host == "" {
+		return ""
+	}
+	ident := strings.ToLower(u.Scheme) + "://" + strings.ToLower(u.Host) + u.EscapedPath()
+	if u.RawQuery != "" {
+		if q, parseErr := url.ParseQuery(u.RawQuery); parseErr == nil {
+			var kept []string
+			for k, vs := range q {
+				if audioMediaVolatileParams[strings.ToLower(k)] {
+					continue
+				}
+				for _, v := range vs {
+					kept = append(kept, k+"="+v)
+				}
+			}
+			if len(kept) > 0 {
+				sort.Strings(kept)
+				ident += "?" + strings.Join(kept, "&")
+			}
+		}
+	}
+	sum := sha256.Sum256([]byte(bookID + "|" + ident))
+	return hex.EncodeToString(sum[:16])
+}
+
+// RemoteAudioCachePath 返回该音轨的缓存文件路径；无法缓存时返回空串。
+func (s *ReaderService) RemoteAudioCachePath(bookID, mediaURL string) string {
+	key := audioMediaCacheKey(bookID, mediaURL)
+	if key == "" {
+		return ""
+	}
+	dir := s.audioMediaDir()
+	if dir == "" {
+		return ""
+	}
+	return filepath.Join(dir, key[:2], key+".audio")
+}
+
+// IsAudioMediaURL 判断媒体代理这次要拉的是不是音轨。
+//
+// 后缀优先：音频书籍里也会出现封面/插图（.jpg）或 HLS 播放列表（.m3u8），
+// 这些不能当成音轨整段落盘。只有后缀为空（签名直链常见形态）时才退回按
+// 书籍类型判断。
+func IsAudioMediaURL(rawURL string, bookType int) bool {
+	u, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil {
+		return bookType == 1
+	}
+	ext := strings.ToLower(filepath.Ext(u.Path))
+	if ext == "" {
+		return bookType == 1
+	}
+	return audioExtensions[ext]
+}
+
+// HasCachedRemoteAudio 判断该音轨是否已有可用缓存（会顺带刷新 mtime）。
+func (s *ReaderService) HasCachedRemoteAudio(bookID, mediaURL string) bool {
+	f, _, ok := s.OpenCachedRemoteAudio(bookID, mediaURL)
+	if ok {
+		_ = f.Close()
+	}
+	return ok
+}
+
+// HasPartialRemoteAudio 是否有可续传的未完成分片（.part）。
+//
+// 调用方据此决定首播策略：有分片说明上一次已经下到一半（用户点过重试、
+// 或播放器自己重连过），此时「下载完再下发」能透明续上剩余字节；
+// 没有分片才是真正的冷启动，边下边发换更低的 TTFB。
+func (s *ReaderService) HasPartialRemoteAudio(bookID, mediaURL string) bool {
+	path := s.RemoteAudioCachePath(bookID, mediaURL)
+	if path == "" {
+		return false
+	}
+	info, err := os.Stat(path + audioPartialSuffix)
+	if err != nil || !info.Mode().IsRegular() || info.Size() == 0 {
+		return false
+	}
+	return info.Size() <= audioMediaObjectMaxBytes
+}
+
+// OpenCachedRemoteAudio 打开已缓存的音轨（命中返回打开的文件，调用方负责关闭）。
+// 过期的缓存顺手删掉，未过期则刷新 mtime 供 LRU 淘汰。
+func (s *ReaderService) OpenCachedRemoteAudio(bookID, mediaURL string) (*os.File, os.FileInfo, bool) {
+	path := s.RemoteAudioCachePath(bookID, mediaURL)
+	if path == "" {
+		return nil, nil, false
+	}
+	f, err := os.Open(path) // #nosec G304 -- 路径由服务端哈希生成
+	if err != nil {
+		return nil, nil, false
+	}
+	info, err := f.Stat()
+	if err != nil || info.IsDir() || info.Size() == 0 {
+		_ = f.Close()
+		return nil, nil, false
+	}
+	if info.ModTime().Add(audioMediaTTL).Before(time.Now()) {
+		_ = f.Close()
+		_ = os.Remove(path)
+		return nil, nil, false
+	}
+	now := time.Now()
+	_ = os.Chtimes(path, now, now)
+	return f, info, true
+}
+
+// errAudioObjectTooLarge 上游对象超过单章缓存上限（不是可重试的错误）。
+var errAudioObjectTooLarge = errors.New("音源超过缓存上限")
+
+// NoRetryError 标记「换着花样再试也不会有进展」的失败（例如上游正成批拒绝
+// 签名票、书源根本给不出新票）。带断点续传的下载器收到它会立刻停止，并把
+// Err 原样交给调用方——继续重试只会让播放器多等十几秒，还会让对方更坚定地
+// 拒绝我们。
+type NoRetryError struct{ Err error }
+
+func (e *NoRetryError) Error() string { return e.Err.Error() }
+func (e *NoRetryError) Unwrap() error { return e.Err }
+
+// AudioRangeFetcher 取一次上游音轨响应。
+//
+// rangeHeader 为空表示整段请求；否则形如 "bytes=N-"，用于从断点续传。
+// head 是调用方已经嗅探读过、必须补写回文件的前缀（只有整段请求才有）。
+// 调用方负责在内部完成换票；这里只看状态码和字节。
+type AudioRangeFetcher func(rangeHeader string) (resp *http.Response, head []byte, err error)
+
+// AudioStreamStart 首播直通开始的回调：调用方在这里写响应头与状态码。
+// total 是上游声明的总长度（分块传输时为 -1），contentType 是上游给的类型。
+type AudioStreamStart func(total int64, contentType string)
+
+// errAudioStreamCannotRestart 直通模式下遇到必须「从第 0 字节重来」的情况。
+//
+// 直通时客户端已经收到了前缀字节，不可能让它把已收到的丢掉重听，所以这类
+// 分支只能中止这次响应（让客户端判成不完整），并把已下载的分片留给下次续传。
+var errAudioStreamCannotRestart = errors.New("直通中无法从零重新下载")
+
+// audioSinkError 标记「写客户端失败」（通常是播放器关掉了连接）。
+// 与写盘失败区分开：写盘失败说明本地有问题，写客户端失败只需停止下载。
+type audioSinkError struct{ err error }
+
+func (e *audioSinkError) Error() string { return "写入客户端失败: " + e.err.Error() }
+func (e *audioSinkError) Unwrap() error { return e.err }
+
+// DownloadRemoteAudio 带断点续传地把整段音轨写进缓存，返回最终文件路径。
+//
+// 为什么需要续传：腾讯 CDN 的跨境边缘常在传输中途 RST，旧实现每次重试都从
+// 第 0 字节重下，一章 3MB 白下几次就把首播拖到几十秒。这里把已写入的字节留在
+// <cache>.part 里，下一次用 Range: bytes=N- 续上；分片跨请求保留，用户点重试
+// 或播放器重连都能接着下。
+//
+// 上游忽略 Range 直接回 200、或分片区间对不上时，丢弃分片从头重来。
+// 下载过程中的失败不会留下「看起来完整」的缓存文件：只有字节数与上游声明的
+// 总长一致才会原子改名到正式路径。
+func (s *ReaderService) DownloadRemoteAudio(
+	ctx context.Context,
+	bookID, mediaURL string,
+	attempts int,
+	fetch AudioRangeFetcher,
+) (string, error) {
+	return s.downloadRemoteAudio(ctx, bookID, mediaURL, attempts, fetch, nil, nil)
+}
+
+// DownloadRemoteAudioStreaming 首播直通：一边落盘一边把字节写给 sink。
+//
+// 与 DownloadRemoteAudio 的区别只有一处——不再等整段下完才返回，第一个字节
+// 到达就通过 onStart 写好响应头并开始外发，慢链路上的首播不必先等 3–5MB。
+//
+// 代价是失败语义变严：客户端已经收到前缀字节，任何「必须从 0 重来」的情况
+// （上游忽略 Range 回 200、分片区间对不上、416）都只能中止这次响应，
+// 不能像普通模式那样静默重下。已写入的分片仍然保留，下次可续传。
+func (s *ReaderService) DownloadRemoteAudioStreaming(
+	ctx context.Context,
+	bookID, mediaURL string,
+	attempts int,
+	fetch AudioRangeFetcher,
+	onStart AudioStreamStart,
+	sink io.Writer,
+) (string, error) {
+	if sink == nil {
+		return "", errors.New("直通下载未提供输出目标")
+	}
+	return s.downloadRemoteAudio(ctx, bookID, mediaURL, attempts, fetch, onStart, sink)
+}
+
+// downloadRemoteAudio 是两种下载模式的共同实现。sink 非空即首播直通模式。
+func (s *ReaderService) downloadRemoteAudio(
+	ctx context.Context,
+	bookID, mediaURL string,
+	attempts int,
+	fetch AudioRangeFetcher,
+	onStart AudioStreamStart,
+	sink io.Writer,
+) (string, error) {
+	path := s.RemoteAudioCachePath(bookID, mediaURL)
+	if path == "" {
+		return "", errors.New("音频缓存目录未配置")
+	}
+	if fetch == nil {
+		return "", errors.New("音频下载器未配置")
+	}
+	if attempts <= 0 {
+		attempts = 1
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o750); err != nil {
+		return "", fmt.Errorf("创建音频缓存目录失败: %w", err)
+	}
+	partPath := path + audioPartialSuffix
+	var offset int64
+	if info, statErr := os.Stat(partPath); statErr == nil && info.Mode().IsRegular() {
+		offset = info.Size()
+		// 分片太旧或超过上限：续传没有意义，直接丢掉重下。
+		if offset > audioMediaObjectMaxBytes || info.ModTime().Add(audioMediaTTL).Before(time.Now()) {
+			_ = os.Remove(partPath)
+			offset = 0
+		}
+	}
+	file, err := os.OpenFile(partPath, os.O_CREATE|os.O_WRONLY, 0o640)
+	if err != nil {
+		return "", fmt.Errorf("创建音频缓存文件失败: %w", err)
+	}
+	// onStart 只应触发一次：直通模式下响应头只能写一次。
+	started := false
+
+	var lastErr error
+	for attempt := 1; attempt <= attempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				_ = file.Close()
+				return "", ctx.Err()
+			case <-time.After(audioDownloadRetryDelay * time.Duration(attempt-1)):
+			}
+		}
+
+		rangeHeader := ""
+		if offset > 0 {
+			rangeHeader = fmt.Sprintf("bytes=%d-", offset)
+		}
+		resp, head, fetchErr := fetch(rangeHeader)
+		if fetchErr != nil {
+			var noRetry *NoRetryError
+			if errors.As(fetchErr, &noRetry) {
+				_ = file.Close()
+				// 已经写下的分片留着：上游恢复后用户再点一次能接着续。
+				if offset == 0 {
+					_ = os.Remove(partPath)
+				}
+				return "", noRetry.Err
+			}
+			lastErr = fetchErr
+			continue
+		}
+		if resp == nil {
+			lastErr = errors.New("音源响应为空")
+			continue
+		}
+
+		expected := int64(-1)
+		switch resp.StatusCode {
+		case http.StatusPartialContent:
+			start, total, ok := parseContentRange(resp.Header.Get("Content-Range"))
+			if !ok || offset == 0 || start != offset {
+				drainAndClose(resp.Body)
+				if sink != nil && offset > 0 {
+					// 已经发给客户端 offset 字节：重来会让客户端收到重复内容。
+					// 分片保持原样，下次请求从这里续。
+					_ = file.Close()
+					return "", errAudioStreamCannotRestart
+				}
+				offset = 0
+				_ = file.Truncate(0)
+				lastErr = fmt.Errorf("音源返回的分片区间不可用（%q）", resp.Header.Get("Content-Range"))
+				continue
+			}
+			expected = total
+		case http.StatusOK:
+			// 上游忽略了 Range（或者本来就是整段请求）：只能从第 0 字节写。
+			if offset > 0 {
+				drainAndClose(resp.Body)
+				if sink != nil {
+					// 同上：已发出去的字节不能撤回，分片留着供下次续传。
+					_ = file.Close()
+					return "", errAudioStreamCannotRestart
+				}
+				offset = 0
+				if truncErr := file.Truncate(0); truncErr != nil {
+					lastErr = fmt.Errorf("重置音频缓存失败: %w", truncErr)
+					continue
+				}
+			}
+			expected = resp.ContentLength
+		case http.StatusRequestedRangeNotSatisfiable:
+			// 分片比上游对象还长（对象换过）：丢掉分片重来。
+			drainAndClose(resp.Body)
+			if sink != nil && offset > 0 {
+				_ = file.Close()
+				return "", errAudioStreamCannotRestart
+			}
+			offset = 0
+			_ = file.Truncate(0)
+			lastErr = fmt.Errorf("音源分片已失效（%d）", resp.StatusCode)
+			continue
+		default:
+			drainAndClose(resp.Body)
+			lastErr = fmt.Errorf("音源返回 %d", resp.StatusCode)
+			continue
+		}
+
+		if sink != nil && !started {
+			// 直通模式下要在这里就把状态码与 Content-Length 写出去，客户端才能
+			// 边收边播。写头的失败（客户端已断开）当作停止下载处理。
+			if onStart != nil {
+				onStart(expected, resp.Header.Get("Content-Type"))
+			}
+			started = true
+		}
+
+		if _, seekErr := file.Seek(offset, io.SeekStart); seekErr != nil {
+			drainAndClose(resp.Body)
+			lastErr = fmt.Errorf("音频缓存定位失败: %w", seekErr)
+			continue
+		}
+		var written int64
+		var writeErr error
+		if sink != nil {
+			written, writeErr = writeAudioChunkStream(file, sink, head, resp.Body, audioMediaObjectMaxBytes-offset)
+		} else {
+			written, writeErr = writeAudioChunk(file, head, resp.Body, audioMediaObjectMaxBytes-offset)
+		}
+		_ = resp.Body.Close()
+		offset += written
+		if errors.Is(writeErr, errAudioObjectTooLarge) {
+			_ = file.Close()
+			_ = os.Remove(partPath)
+			return "", fmt.Errorf("已重试 %d 次: %w", attempts, writeErr)
+		}
+		var sinkErr *audioSinkError
+		if errors.As(writeErr, &sinkErr) {
+			// 客户端不要了：停止下载，已写入的分片留着供下次续传。
+			_ = file.Close()
+			return "", sinkErr
+		}
+		if writeErr != nil {
+			// 已写入的字节保留在分片里，下一轮从新的断点续传。
+			lastErr = writeErr
+			continue
+		}
+		if expected >= 0 && offset != expected {
+			lastErr = fmt.Errorf("音频写入不完整（%d/%d 字节）", offset, expected)
+			continue
+		}
+		if offset == 0 {
+			lastErr = errors.New("音源内容为空")
+			continue
+		}
+		if truncErr := file.Truncate(offset); truncErr != nil {
+			_ = file.Close()
+			return "", fmt.Errorf("写入音频缓存失败: %w", truncErr)
+		}
+		if closeErr := file.Close(); closeErr != nil {
+			return "", fmt.Errorf("写入音频缓存失败: %w", closeErr)
+		}
+		if renameErr := os.Rename(partPath, path); renameErr != nil {
+			return "", fmt.Errorf("写入音频缓存失败: %w", renameErr)
+		}
+		s.pruneAudioMediaCache()
+		return path, nil
+	}
+
+	_ = file.Close()
+	if lastErr == nil {
+		lastErr = errors.New("音源拉取失败")
+	}
+	if offset > 0 {
+		return "", fmt.Errorf("已重试 %d 次: %w（已缓存 %d 字节，重试可续传）", attempts, lastErr, offset)
+	}
+	return "", fmt.Errorf("已重试 %d 次: %w", attempts, lastErr)
+}
+
+// writeAudioChunk 先把已读前缀补写回文件，再把响应体写到 limit 字节为止。
+// 返回本次实际写入的字节数（出错时也包含已写成功的部分）。
+func writeAudioChunk(w io.Writer, head []byte, body io.Reader, limit int64) (int64, error) {
+	var total int64
+	if len(head) > 0 {
+		n, err := w.Write(head)
+		total += int64(n)
+		if err != nil {
+			return total, err
+		}
+	}
+	if limit <= 0 {
+		return total, errAudioObjectTooLarge
+	}
+	n, err := io.Copy(w, io.LimitReader(body, limit-total+1))
+	total += n
+	if err != nil {
+		return total, err
+	}
+	if total > limit {
+		return total, errAudioObjectTooLarge
+	}
+	return total, nil
+}
+
+// writeAudioChunkStream 同 writeAudioChunk，但同时把字节写给客户端（首播直通）。
+//
+// 写盘失败要让整个下载停下来（本地状态不可信，继续发字节等于给客户端一份
+// 服务端存不下的内容）；写客户端失败只说明接收方不要了，用 audioSinkError
+// 标出来让上层保留分片、安静收尾。两者必须区分，否则播放器一关就把分片删了。
+func writeAudioChunkStream(w io.Writer, sink io.Writer, head []byte, body io.Reader, limit int64) (int64, error) {
+	var total int64
+	writeBoth := func(p []byte) error {
+		n, err := w.Write(p)
+		total += int64(n)
+		if err != nil {
+			return err
+		}
+		if n > 0 {
+			if _, sinkErr := sink.Write(p[:n]); sinkErr != nil {
+				return &audioSinkError{err: sinkErr}
+			}
+		}
+		return nil
+	}
+	if len(head) > 0 {
+		if err := writeBoth(head); err != nil {
+			return total, err
+		}
+	}
+	if limit <= 0 {
+		return total, errAudioObjectTooLarge
+	}
+	buf := make([]byte, 32<<10)
+	remaining := limit - total + 1
+	for {
+		if remaining <= 0 {
+			return total, errAudioObjectTooLarge
+		}
+		chunk := buf
+		if int64(len(chunk)) > remaining {
+			chunk = chunk[:remaining]
+		}
+		n, readErr := body.Read(chunk)
+		if n > 0 {
+			if err := writeBoth(chunk[:n]); err != nil {
+				return total, err
+			}
+			remaining -= int64(n)
+		}
+		if readErr == io.EOF {
+			break
+		}
+		if readErr != nil {
+			return total, readErr
+		}
+	}
+	if total > limit {
+		return total, errAudioObjectTooLarge
+	}
+	return total, nil
+}
+
+// parseContentRange 解析 "bytes 100-199/1234" 的起点与总长度。
+// 总长度未知（"*"）时 total 为 -1。
+func parseContentRange(v string) (start, total int64, ok bool) {
+	v = strings.TrimSpace(v)
+	const prefix = "bytes "
+	if len(v) <= len(prefix) || !strings.EqualFold(v[:len(prefix)], prefix) {
+		return 0, -1, false
+	}
+	v = strings.TrimSpace(v[len(prefix):])
+	slash := strings.IndexByte(v, '/')
+	if slash < 0 {
+		return 0, -1, false
+	}
+	span, size := v[:slash], strings.TrimSpace(v[slash+1:])
+	dash := strings.IndexByte(span, '-')
+	if dash <= 0 {
+		return 0, -1, false
+	}
+	start, err := strconv.ParseInt(strings.TrimSpace(span[:dash]), 10, 64)
+	if err != nil || start < 0 {
+		return 0, -1, false
+	}
+	if size == "" || size == "*" {
+		return start, -1, true
+	}
+	total, err = strconv.ParseInt(size, 10, 64)
+	if err != nil || total <= 0 {
+		return start, -1, true
+	}
+	return start, total, true
+}
+
+// drainAndClose 丢弃剩余响应体并关闭连接（尽量让上游把连接收回去）。
+func drainAndClose(body io.ReadCloser) {
+	if body == nil {
+		return
+	}
+	_, _ = io.Copy(io.Discard, io.LimitReader(body, 64<<10))
+	_ = body.Close()
+}
+
+// pruneAudioMediaCache 低频清理：删过期文件，超容量时按 mtime 淘汰最旧的。
+func (s *ReaderService) pruneAudioMediaCache() {
+	dir := s.audioMediaDir()
+	if dir == "" {
+		return
+	}
+	audioMediaPruneMu.Lock()
+	if time.Since(audioMediaPrunedAt) < audioMediaPrunePeriod {
+		audioMediaPruneMu.Unlock()
+		return
+	}
+	audioMediaPrunedAt = time.Now()
+	audioMediaPruneMu.Unlock()
+
+	type entry struct {
+		path string
+		size int64
+		mod  time.Time
+	}
+	var entries []entry
+	var total int64
+	_ = filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil
+		}
+		info, infoErr := d.Info()
+		if infoErr != nil {
+			return nil
+		}
+		if info.ModTime().Add(audioMediaTTL).Before(time.Now()) {
+			_ = os.Remove(path)
+			return nil
+		}
+		entries = append(entries, entry{path: path, size: info.Size(), mod: info.ModTime()})
+		total += info.Size()
+		return nil
+	})
+	if total <= audioMediaMaxBytes {
+		return
+	}
+	sort.Slice(entries, func(i, j int) bool { return entries[i].mod.Before(entries[j].mod) })
+	target := int64(audioMediaMaxBytes) * audioMediaPruneKeepPct / 100
+	for _, e := range entries {
+		if total <= target {
+			break
+		}
+		if err := os.Remove(e.path); err == nil {
+			total -= e.size
+		}
+	}
+}

internal/service/reader/audio_media_cache_test.go

@@ -0,0 +1,434 @@
+package reader
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/config"
+)
+
+func TestIsAudioMediaURL(t *testing.T) {
+	cases := []struct {
+		name     string
+		url      string
+		bookType int
+		want     bool
+	}{
+		{"m4a 直链", "https://cdn.example.com/a.m4a?uid=1&vkey=x", 0, true},
+		{"mp3 直链", "https://cdn.example.com/a.MP3", 0, true},
+		{"音频书里的插图", "https://cdn.example.com/img/cover.jpg", 1, false},
+		{"HLS 播放列表", "https://cdn.example.com/index.m3u8?token=1", 1, false},
+		{"无后缀签名直链（音频书）", "https://cdn.example.com/stream?token=1", 1, true},
+		{"无后缀签名直链（文本/图片书）", "https://cdn.example.com/stream?token=1", 0, false},
+		{"坏地址但书籍是音频", "://bad", 1, true},
+	}
+	for _, c := range cases {
+		if got := IsAudioMediaURL(c.url, c.bookType); got != c.want {
+			t.Errorf("%s: IsAudioMediaURL(%q, %d) = %v，期望 %v", c.name, c.url, c.bookType, got, c.want)
+		}
+	}
+}
+
+// TestAudioMediaCacheKeyIgnoresQuery 换票会改写 uid/vkey/ct，缓存键必须忽略
+// 这些签名/时效参数，否则每次换票都会重新下载一遍。
+func TestAudioMediaCacheKeyIgnoresQuery(t *testing.T) {
+	a := audioMediaCacheKey("book-1", "https://cdn.example.com/long/a.m4a?uid=1&vkey=aaa")
+	b := audioMediaCacheKey("book-1", "https://cdn.example.com/long/a.m4a?uid=2&vkey=bbb&ct=3")
+	if a == "" || a != b {
+		t.Fatalf("同一对象换票后缓存键应一致: %q vs %q", a, b)
+	}
+	if c := audioMediaCacheKey("book-2", "https://cdn.example.com/long/a.m4a"); c == a {
+		t.Fatalf("不同书籍的缓存键不应相同")
+	}
+	if d := audioMediaCacheKey("book-1", "https://cdn.example.com/long/b.m4a"); d == a {
+		t.Fatalf("不同对象的缓存键不应相同")
+	}
+}
+
+// TestAudioMediaCacheKeyKeepsIdentifyingQuery 只靠 query 区分章节的书源
+// （路径固定、如 /audio?id=12345）不能被合并成同一个缓存对象，否则第二集
+// 会命中第一集的缓存直接播错内容。
+func TestAudioMediaCacheKeyKeepsIdentifyingQuery(t *testing.T) {
+	ep1 := audioMediaCacheKey("book-1", "https://host/audio?id=12345&vkey=aaa")
+	ep2 := audioMediaCacheKey("book-1", "https://host/audio?id=67890&vkey=bbb")
+	if ep1 == "" || ep2 == "" {
+		t.Fatal("缓存键不应为空")
+	}
+	if ep1 == ep2 {
+		t.Fatalf("不同章节（query 不同）的缓存键不应相同，否则会串集")
+	}
+}
+
+// TestAudioMediaCacheKeyIgnoresQueryOrder 非签名参数的顺序不应影响缓存键。
+func TestAudioMediaCacheKeyIgnoresQueryOrder(t *testing.T) {
+	a := audioMediaCacheKey("book-1", "https://host/a.m4a?id=7&chapter=3&vkey=x")
+	b := audioMediaCacheKey("book-1", "https://host/a.m4a?chapter=3&id=7&vkey=y")
+	if a == "" || a != b {
+		t.Fatalf("参数顺序不应影响缓存键: %q vs %q", a, b)
+	}
+}
+
+
+// ─── 断点续传下载器 ──────────────────────────────────────────────────────
+
+func TestParseContentRange(t *testing.T) {
+	cases := []struct {
+		in     string
+		start  int64
+		total  int64
+		wantOK bool
+	}{
+		{"bytes 100-199/1234", 100, 1234, true},
+		{"bytes 0-99/*", 0, -1, true},
+		{"BYTES 500-599/600", 500, 600, true},
+		{"", 0, -1, false},
+		{"bytes */1234", 0, -1, false},
+		{"bytes x-1/2", 0, -1, false},
+	}
+	for _, c := range cases {
+		start, total, ok := parseContentRange(c.in)
+		if ok != c.wantOK || start != c.start || total != c.total {
+			t.Errorf("parseContentRange(%q) = (%d,%d,%v)，期望 (%d,%d,%v)",
+				c.in, start, total, ok, c.start, c.total, c.wantOK)
+		}
+	}
+}
+
+// errAfterReader 读到 data 末尾后返回 err，模拟上游中途 RST/提前 EOF。
+type errAfterReader struct {
+	data []byte
+	pos  int
+	err  error
+}
+
+func (r *errAfterReader) Read(p []byte) (int, error) {
+	if r.pos >= len(r.data) {
+		return 0, r.err
+	}
+	n := copy(p, r.data[r.pos:])
+	r.pos += n
+	return n, nil
+}
+
+func (r *errAfterReader) Close() error { return nil }
+
+func newAudioDownloadTestService(t *testing.T) *ReaderService {
+	t.Helper()
+	return &ReaderService{cfg: &config.Config{Cache: config.CacheConfig{CacheDir: t.TempDir()}}}
+}
+
+func okResponse(body []byte) *http.Response {
+	return &http.Response{
+		StatusCode:    http.StatusOK,
+		ContentLength: int64(len(body)),
+		Header:        http.Header{"Content-Type": {"audio/mp4"}},
+		Body:          io.NopCloser(bytes.NewReader(body)),
+	}
+}
+
+func rangeResponse(header string, body []byte) *http.Response {
+	return &http.Response{
+		StatusCode: http.StatusPartialContent,
+		Header:     http.Header{"Content-Range": {header}},
+		Body:       io.NopCloser(bytes.NewReader(body)),
+	}
+}
+
+// TestDownloadRemoteAudioResumesAfterReset 上游写到一半断开后，第二轮必须用
+// Range 从断点续传，最终文件与上游内容逐字节一致。
+func TestDownloadRemoteAudioResumesAfterReset(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/a.m4a?vkey=1"
+	payload := bytes.Repeat([]byte("0123456789"), 500) // 5000 字节
+	const firstChunk = 2000
+
+	var ranges []string
+	attempt := 0
+	path, err := svc.DownloadRemoteAudio(t.Context(), "book-1", mediaURL, 3,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			ranges = append(ranges, rangeHeader)
+			attempt++
+			if attempt == 1 {
+				// 声明全量长度，只写 2000 字节就断开。
+				return &http.Response{
+					StatusCode:    http.StatusOK,
+					ContentLength: int64(len(payload)),
+					Header:        http.Header{"Content-Type": {"audio/mp4"}},
+					Body: &errAfterReader{
+						data: payload[:firstChunk],
+						err:  io.ErrUnexpectedEOF,
+					},
+				}, nil, nil
+			}
+			if rangeHeader != fmt.Sprintf("bytes=%d-", firstChunk) {
+				t.Fatalf("第二轮应请求断点续传，实际 Range=%q", rangeHeader)
+			}
+			return rangeResponse(
+				fmt.Sprintf("bytes %d-%d/%d", firstChunk, len(payload)-1, len(payload)),
+				payload[firstChunk:],
+			), nil, nil
+		})
+	if err != nil {
+		t.Fatalf("续传后应当成功: %v", err)
+	}
+	got, readErr := os.ReadFile(path)
+	if readErr != nil {
+		t.Fatalf("读缓存文件失败: %v", readErr)
+	}
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("续传后的内容不完整: %d 字节，期望 %d", len(got), len(payload))
+	}
+	if len(ranges) != 2 || ranges[0] != "" {
+		t.Fatalf("请求序列 = %q，期望首次整段、第二次续传", ranges)
+	}
+}
+
+// TestDownloadRemoteAudioResumesAcrossCalls 上一次请求失败留下的分片，下一次
+// （用户点重试）要能直接接着下，而不是从第 0 字节重来。
+func TestDownloadRemoteAudioResumesAcrossCalls(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/b.m4a"
+	payload := bytes.Repeat([]byte("abcdefgh"), 1000)
+	const firstChunk = 3000
+
+	// 第一次调用：上游只给 3000 字节就断，重试也没用（每次都 200 + 截断）。
+	_, err := svc.DownloadRemoteAudio(t.Context(), "book-2", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			return &http.Response{
+				StatusCode:    http.StatusOK,
+				ContentLength: int64(len(payload)),
+				Header:        http.Header{"Content-Type": {"audio/mp4"}},
+				Body: &errAfterReader{
+					data: payload[:firstChunk],
+					err:  io.ErrUnexpectedEOF,
+				},
+			}, nil, nil
+		})
+	if err == nil {
+		t.Fatalf("上游截断时应当失败")
+	}
+
+	// 第二次调用：直接请求 bytes=3000-，续完。
+	var seenRange string
+	path, err := svc.DownloadRemoteAudio(t.Context(), "book-2", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			seenRange = rangeHeader
+			return rangeResponse(
+				fmt.Sprintf("bytes %d-%d/%d", firstChunk, len(payload)-1, len(payload)),
+				payload[firstChunk:],
+			), nil, nil
+		})
+	if err != nil {
+		t.Fatalf("跨请求续传应当成功: %v", err)
+	}
+	if seenRange != fmt.Sprintf("bytes=%d-", firstChunk) {
+		t.Fatalf("应当从上次的断点续传，实际 Range=%q", seenRange)
+	}
+	got, _ := os.ReadFile(path)
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("跨请求续传后的内容不完整: %d 字节", len(got))
+	}
+}
+
+// TestDownloadRemoteAudioRestartsWhenRangeIgnored 上游忽略 Range 仍回 200 时，
+// 必须丢掉分片从头写，不能把两段字节拼在一起。
+func TestDownloadRemoteAudioRestartsWhenRangeIgnored(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/c.m4a"
+	payload := bytes.Repeat([]byte("xyz9"), 500)
+
+	var ranges []string
+	attempt := 0
+	path, err := svc.DownloadRemoteAudio(t.Context(), "book-3", mediaURL, 3,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			ranges = append(ranges, rangeHeader)
+			attempt++
+			if attempt == 1 {
+				return &http.Response{
+					StatusCode:    http.StatusOK,
+					ContentLength: int64(len(payload)),
+					Header:        http.Header{"Content-Type": {"audio/mp4"}},
+					Body:          &errAfterReader{data: payload[:700], err: io.ErrUnexpectedEOF},
+				}, nil, nil
+			}
+			// 无视 Range，整段回 200。
+			return okResponse(payload), nil, nil
+		})
+	if err != nil {
+		t.Fatalf("应当成功: %v", err)
+	}
+	if ranges[1] == "" {
+		t.Fatalf("第二轮应当带 Range")
+	}
+	got, _ := os.ReadFile(path)
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("忽略 Range 后必须从头重写，实际 %d 字节（期望 %d）", len(got), len(payload))
+	}
+}
+
+// TestDownloadRemoteAudioStopsOnNoRetry 上游成批拒绝时（NoRetryError），
+// 下载器要立刻收手，不能把同一张被拒的票再打几遍。
+func TestDownloadRemoteAudioStopsOnNoRetry(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	denied := errors.New("音源暂时被上游拒绝（HTTP 401）")
+
+	calls := 0
+	_, err := svc.DownloadRemoteAudio(t.Context(), "book-4", "https://cdn.example.com/long/d.m4a", 4,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			calls++
+			return nil, nil, &NoRetryError{Err: denied}
+		})
+	if err == nil || !strings.Contains(err.Error(), "401") {
+		t.Fatalf("应原样返回上游拒绝原因，实际 %v", err)
+	}
+	if calls != 1 {
+		t.Fatalf("不可重试的失败只应请求 1 次，实际 %d 次", calls)
+	}
+}
+
+// ─── 首播直通（边下边发） ────────────────────────────────────────────────
+
+// TestDownloadRemoteAudioStreamingForwardsWhileDownloading 直通模式：字节必须
+// 在下载过程中就到达 sink，而不是等整段下完才一次性写出去（首播 TTFB）。
+func TestDownloadRemoteAudioStreamingForwardsWhileDownloading(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/stream.m4a? vkey=1"
+	payload := bytes.Repeat([]byte("stream!"), 1000)
+
+	var sink bytes.Buffer
+	var startedTotal int64
+	// 用「读到一半时 sink 里已经有数据」来证明确实在边下边发。
+	var midLength int
+	path, err := svc.DownloadRemoteAudioStreaming(t.Context(), "book-s", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			if rangeHeader != "" {
+				t.Fatalf("首播直通不应带 Range，实际 %q", rangeHeader)
+			}
+			return okResponse(payload), nil, nil
+		},
+		func(total int64, contentType string) {
+			startedTotal = total
+			// 头部回调必须早于任何字节下发。
+			if sink.Len() != 0 {
+				t.Errorf("写响应头时不应已有字节写出")
+			}
+		},
+		writerFunc(func(p []byte) (int, error) {
+			if midLength == 0 && sink.Len() == 0 && len(p) > 0 {
+				midLength = sink.Len()
+			}
+			return sink.Write(p)
+		}),
+	)
+	if err != nil {
+		t.Fatalf("直通下载失败: %v", err)
+	}
+	if startedTotal != int64(len(payload)) {
+		t.Fatalf("头部回调应拿到上游总长 %d，实际 %d", len(payload), startedTotal)
+	}
+	if !bytes.Equal(sink.Bytes(), payload) {
+		t.Fatalf("下发的字节不完整: %d 字节，期望 %d", sink.Len(), len(payload))
+	}
+	// 下载完成后缓存文件必须完整可命中。
+	got, readErr := os.ReadFile(path)
+	if readErr != nil {
+		t.Fatalf("读缓存文件失败: %v", readErr)
+	}
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("落盘内容不完整: %d 字节", len(got))
+	}
+	if !svc.HasCachedRemoteAudio("book-s", mediaURL) {
+		t.Fatal("直通下完后应当命中缓存")
+	}
+}
+
+// TestDownloadRemoteAudioStreamingStopsWhenClientGoesAway 客户端中途断开时
+// 停止下载，但保留分片供下次续传（不能把已下的字节白扔掉）。
+func TestDownloadRemoteAudioStreamingStopsWhenClientGoesAway(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/gone.m4a"
+	payload := bytes.Repeat([]byte("abcdefgh"), 2000)
+	clientGone := errors.New("client closed connection")
+
+	var sink bytes.Buffer
+	_, err := svc.DownloadRemoteAudioStreaming(t.Context(), "book-g", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			return okResponse(payload), nil, nil
+		},
+		nil,
+		writerFunc(func(p []byte) (int, error) {
+			// 收下前 1000 字节后模拟播放器断开。
+			if sink.Len() >= 1000 {
+				return 0, clientGone
+			}
+			room := 1000 - sink.Len()
+			if len(p) <= room {
+				return sink.Write(p)
+			}
+			n, _ := sink.Write(p[:room])
+			return n, clientGone
+		}),
+	)
+	if err == nil {
+		t.Fatal("客户端断开时应当停止下载")
+	}
+	var sinkErr *audioSinkError
+	if !errors.As(err, &sinkErr) {
+		t.Fatalf("应标记为写客户端失败（便于上层区分），实际 %v", err)
+	}
+	// 分片要留着：这是续传的原料。
+	path := svc.RemoteAudioCachePath("book-g", mediaURL)
+	if path == "" {
+		t.Fatal("缓存路径不应为空")
+	}
+	if info, statErr := os.Stat(path + audioPartialSuffix); statErr != nil || info.Size() == 0 {
+		t.Fatalf("断流后应保留 .part 分片，实际 %v", statErr)
+	}
+	if svc.HasCachedRemoteAudio("book-g", mediaURL) {
+		t.Fatal("中断的下载不能留下完整缓存（否则会下发截断音频）")
+	}
+}
+
+// TestDownloadRemoteAudioStreamingAbortsOnRestart 直通模式下上游忽略 Range 回
+// 200（需要从 0 重来）时必须中止，而不是把重复字节拼进客户端已收到的流里。
+func TestDownloadRemoteAudioStreamingAbortsOnRestart(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/restart.m4a"
+	payload := bytes.Repeat([]byte("zz"), 100)
+	// 先留一个分片，让第二轮带 Range。
+	partPath := svc.RemoteAudioCachePath("book-r", mediaURL) + audioPartialSuffix
+	if err := os.MkdirAll(filepath.Dir(partPath), 0o750); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(partPath, payload[:50], 0o640); err != nil {
+		t.Fatal(err)
+	}
+
+	var sink bytes.Buffer
+	_, err := svc.DownloadRemoteAudioStreaming(t.Context(), "book-r", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			// 无视 Range，整段回 200 → 直通无法重来。
+			return okResponse(payload), nil, nil
+		},
+		nil,
+		&sink,
+	)
+	if !errors.Is(err, errAudioStreamCannotRestart) {
+		t.Fatalf("应返回不可重来错误，实际 %v", err)
+	}
+	if sink.Len() != 0 {
+		t.Fatalf("中止前不应向客户端写出字节，实际 %d", sink.Len())
+	}
+}
+
+// writerFunc 把函数适配成 io.Writer。
+type writerFunc func(p []byte) (int, error)
+
+func (f writerFunc) Write(p []byte) (int, error) { return f(p) }

internal/service/reader/book_type_fallback_test.go

@@ -58,7 +58,7 @@ func TestAudioBookTypeFallbackBySource(t *testing.T) {
 		t.Fatalf("保存目录失败: %v", err)
 	}
 
-	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("取正文失败: %v", err)
 	}
@@ -125,7 +125,7 @@ func TestDeclaredTextTypeWinsOverAudioSource(t *testing.T) {
 		t.Fatalf("保存目录失败: %v", err)
 	}
 
-	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("取正文失败: %v", err)
 	}

internal/service/reader/comic_image_test.go

@@ -75,7 +75,7 @@ func TestGetContentForBookExtractsImageSrc(t *testing.T) {
 	}
 	_ = sourceID
 
-	out, err := svc.GetContentForBook(ctx, "u1", book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("取正文失败: %v", err)
 	}

internal/service/reader/comment_test.go

@@ -207,7 +207,7 @@ func TestGetContentForBookExtractsComments(t *testing.T) {
 		t.Fatalf("写入章节失败: %v", err)
 	}
 
-	out, err := svc.GetContentForBook(ctx, "u1", book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("取正文失败: %v", err)
 	}
@@ -282,7 +282,7 @@ func TestGetContentForBookKeepsTextWithStandaloneImage(t *testing.T) {
 		`<img src="https://cdn.example.com/pic.jpg">`
 	svc, bookID := setupTextChapterBook(t, content)
 
-	out, err := svc.GetContentForBook(t.Context(), "u1", bookID, 0)
+	out, err := svc.GetContentForBook(t.Context(), "u1", bookID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("取正文失败: %v", err)
 	}
@@ -310,7 +310,7 @@ func TestGetContentForBookStripsBlockTagsKeepsText(t *testing.T) {
 		`<img src="https://cdn.example.com/pic.jpg">`
 	svc, bookID := setupTextChapterBook(t, content)
 
-	out, err := svc.GetContentForBook(t.Context(), "u1", bookID, 0)
+	out, err := svc.GetContentForBook(t.Context(), "u1", bookID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("取正文失败: %v", err)
 	}

internal/service/reader/cover_repair_test.go

@@ -0,0 +1,69 @@
+package reader
+
+import (
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 上游限流时详情解析不到封面，规则会把页面地址当封面回退。这类记录被存进书架后
+// 会一直显示破图；打开一次详情页应当用真实封面把它修好。
+func TestRepairShelfCoverReplacesFallbackURL(t *testing.T) {
+	svc, _ := newLoginTestService(t)
+	ctx := t.Context()
+
+	const origin = "https://api.example.com/book"
+	const bookURL = "https://api.example.com/book?bookId=1"
+	const cover = "https://img.example.com/c.jpg"
+
+	book := &model.ReaderBook{
+		UserID:   "u1",
+		Origin:   origin,
+		BookURL:  bookURL,
+		Name:     "测试书",
+		CoverURL: bookURL, // 规则取空后回退的产物
+	}
+	if err := svc.repo.CreateBook(ctx, book); err != nil {
+		t.Fatal(err)
+	}
+
+	svc.RepairShelfCover(ctx, "u1", origin, bookURL, cover)
+
+	stored, err := svc.repo.GetBook(ctx, book.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stored.CoverURL != cover {
+		t.Fatalf("封面应修为 %q，实际 %q", cover, stored.CoverURL)
+	}
+}
+
+// 已经有有效封面的书不能被动覆盖（可能是换源得到的、或用户自己挑的）。
+func TestRepairShelfCoverKeepsValidCover(t *testing.T) {
+	svc, _ := newLoginTestService(t)
+	ctx := t.Context()
+
+	const origin = "https://api.example.com/book"
+	const bookURL = "https://api.example.com/book?bookId=1"
+
+	book := &model.ReaderBook{
+		UserID:   "u1",
+		Origin:   origin,
+		BookURL:  bookURL,
+		Name:     "测试书",
+		CoverURL: "https://img.example.com/old.jpg",
+	}
+	if err := svc.repo.CreateBook(ctx, book); err != nil {
+		t.Fatal(err)
+	}
+
+	svc.RepairShelfCover(ctx, "u1", origin, bookURL, "https://img.example.com/new.jpg")
+
+	stored, err := svc.repo.GetBook(ctx, book.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stored.CoverURL != "https://img.example.com/old.jpg" {
+		t.Fatalf("有效封面不应被覆盖，实际 %q", stored.CoverURL)
+	}
+}

internal/service/reader/cover_url_test.go

@@ -6,32 +6,48 @@ import "testing"
 // normalizeCoverURL 必须拦住这类非图片地址，避免前端 <img> 显示破图。
 func TestNormalizeCoverURL(t *testing.T) {
 	cases := []struct {
-		name string
-		in   string
-		want string
+		name    string
+		in      string
+		baseURL string
+		want    string
 	}{
-		{"empty", "", ""},
-		{"blank", "   ", ""},
-		{"https", "https://img.example.com/a.jpg", "https://img.example.com/a.jpg"},
-		{"http", "http://img.example.com/a.jpg", "http://img.example.com/a.jpg"},
-		{"uppercase scheme", "HTTPS://img.example.com/a.jpg", "HTTPS://img.example.com/a.jpg"},
-		{"trimmed", "  https://img.example.com/a.jpg  ", "https://img.example.com/a.jpg"},
-		{"inline image data uri", "data:image/png;base64,iVBORw0KGgo=", "data:image/png;base64,iVBORw0KGgo="},
-		{"local asset url", "/api/reader/local/asset?b=1&p=2&s=3", "/api/reader/local/asset?b=1&p=2&s=3"},
+		{"empty", "", "", ""},
+		{"blank", "   ", "", ""},
+		{"https", "https://img.example.com/a.jpg", "", "https://img.example.com/a.jpg"},
+		{"http", "http://img.example.com/a.jpg", "", "http://img.example.com/a.jpg"},
+		{"uppercase scheme", "HTTPS://img.example.com/a.jpg", "", "HTTPS://img.example.com/a.jpg"},
+		{"trimmed", "  https://img.example.com/a.jpg  ", "", "https://img.example.com/a.jpg"},
+		{"inline image data uri", "data:image/png;base64,iVBORw0KGgo=", "", "data:image/png;base64,iVBORw0KGgo="},
+		{"local asset url", "/api/reader/local/asset?b=1&p=2&s=3", "", "/api/reader/local/asset?b=1&p=2&s=3"},
 		{
 			"search params envelope",
 			"data:;base64,eyJrZXkiOiLlhajnkIPpq5jmraYiLCJ0YWIiOiLlsI/or7QiLCJzb3VyY2VzS2V5Ijoi5YWo6YOoIiwicGFnZSI6MSwiZGlzYWJsZWRfc291cmNlcyI6IjAifQ==",
 			"",
+			"",
+		},
+		{"text data uri", "data:text/plain;base64,aGk=", "", ""},
+		{"source name", "光遇聚合", "", ""},
+		{"javascript url", "javascript:alert(1)", "", ""},
+		{
+			// 详情规则取不到 $.meta.cover 时按 legado 语义回退成页面地址，
+			// 这个接口地址不是图片，必须丢掉。
+			"fallback to page url",
+			"https://api.example.com/book?bookId=1",
+			"https://api.example.com/book?bookId=1",
+			"",
+		},
+		{
+			"real cover with page url base",
+			"https://img.example.com/a.jpg",
+			"https://api.example.com/book?bookId=1",
+			"https://img.example.com/a.jpg",
 		},
-		{"text data uri", "data:text/plain;base64,aGk=", ""},
-		{"source name", "光遇聚合", ""},
-		{"javascript url", "javascript:alert(1)", ""},
 	}
 
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			if got := normalizeCoverURL(tc.in); got != tc.want {
-				t.Fatalf("normalizeCoverURL(%q) = %q, want %q", tc.in, got, tc.want)
+			if got := normalizeCoverURL(tc.in, tc.baseURL); got != tc.want {
+				t.Fatalf("normalizeCoverURL(%q, %q) = %q, want %q", tc.in, tc.baseURL, got, tc.want)
 			}
 		})
 	}

internal/service/reader/media_direct_test.go

@@ -0,0 +1,168 @@
+package reader
+
+import (
+	"strings"
+	"testing"
+)
+
+// 本文件：媒体直连（客户端自己取音频/漫画图片字节）的回归测试。
+//
+// 契约：
+//   - 默认（ContentOptions 零值）必须与历史行为完全一致：媒体地址一律改写成
+//     服务端签名代理，响应里不出现直连标记与请求头 —— 网页端依赖这一点。
+//   - 客户端显式请求直连 + 书源开启开关时：保留上游原始地址，并下发取媒体
+//     所需的请求头。
+//   - 客户端请求直连但书源没开开关时：退回代理，不能把未开启的源推到客户端直连。
+
+// TestMediaDirectDefaultsToProxy 不传直连选项时行为不变（网页端契约）。
+func TestMediaDirectDefaultsToProxy(t *testing.T) {
+	svc, _, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
+	if err != nil {
+		t.Fatalf("读取失败: %v", err)
+	}
+	if len(out.Tracks) == 0 {
+		t.Fatal("应至少有一条音轨")
+	}
+	if !strings.HasPrefix(out.Tracks[0], "/api/reader/media?") {
+		t.Fatalf("默认应改写为服务端代理，实际 %q", out.Tracks[0])
+	}
+	if out.MediaDirect {
+		t.Fatal("默认不应标记为直连")
+	}
+	if len(out.MediaHeaders) != 0 {
+		t.Fatalf("代理模式不应下发取媒体请求头，实际 %v", out.MediaHeaders)
+	}
+}
+
+// TestMediaDirectRequiresSourceSwitch 书源没开开关时，即使客户端请求直连也只给代理。
+func TestMediaDirectRequiresSourceSwitch(t *testing.T) {
+	svc, srv, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{MediaDirect: true})
+	if err != nil {
+		t.Fatalf("读取失败: %v", err)
+	}
+	if out.MediaDirect {
+		t.Fatal("书源未开启直连，不应标记为直连")
+	}
+	if !strings.HasPrefix(out.Tracks[0], "/api/reader/media?") {
+		t.Fatalf("书源未开启直连时仍应走代理，实际 %q", out.Tracks[0])
+	}
+	_ = srv
+}
+
+// TestMediaDirectKeepsUpstreamURL 开启开关后：地址是上游原始地址，并下发请求头。
+func TestMediaDirectKeepsUpstreamURL(t *testing.T) {
+	svc, srv, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	if err := svc.SetSourceMediaDirect(ctx, readerTestUserID, sourceIDOf(t, svc, book.Origin), true); err != nil {
+		t.Fatalf("开启直连失败: %v", err)
+	}
+
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{MediaDirect: true})
+	if err != nil {
+		t.Fatalf("读取失败: %v", err)
+	}
+	if !out.MediaDirect {
+		t.Fatal("书源已开启直连，响应应标记 media_direct")
+	}
+	if len(out.Tracks) == 0 {
+		t.Fatal("应至少有一条音轨")
+	}
+	track := out.Tracks[0]
+	if strings.HasPrefix(track, "/api/") {
+		t.Fatalf("直连模式不该返回服务端代理地址，实际 %q", track)
+	}
+	if !strings.HasPrefix(track, srv.URL+"/media") {
+		t.Fatalf("直连模式应保留上游原始地址，实际 %q", track)
+	}
+	// 取媒体需要的防盗链头必须下发，否则客户端拿不到字节。
+	if out.MediaHeaders["Referer"] == "" {
+		t.Fatalf("直连模式应下发 Referer，实际 %v", out.MediaHeaders)
+	}
+	if out.MediaHeaders["User-Agent"] == "" {
+		t.Fatalf("直连模式应下发 User-Agent，实际 %v", out.MediaHeaders)
+	}
+	// 传输层头交给客户端 HTTP 栈，不能下发。
+	if _, ok := out.MediaHeaders["Accept-Encoding"]; ok {
+		t.Fatalf("不应下发 Accept-Encoding: %v", out.MediaHeaders)
+	}
+}
+
+// TestMediaDirectAppliesToCachedChapter 缓存命中的章节同样要按本次请求决定通道。
+//
+// 缓存里存的是书源侧原始地址（改写前），若命中后不改写就会把上游地址直接
+// 漏给代理模式的客户端，表现为「图片/音频打不开」。
+func TestMediaDirectAppliesToCachedChapter(t *testing.T) {
+	svc, _, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	// 首次读取写入缓存（直连模式）。
+	if err := svc.SetSourceMediaDirect(ctx, readerTestUserID, sourceIDOf(t, svc, book.Origin), true); err != nil {
+		t.Fatalf("开启直连失败: %v", err)
+	}
+	first, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{MediaDirect: true})
+	if err != nil || !first.MediaDirect {
+		t.Fatalf("首次直连读取失败: %v", err)
+	}
+
+	// 同章再按代理模式读：必须拿到签名代理地址，而不是缓存里的上游地址。
+	second, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
+	if err != nil {
+		t.Fatalf("二次读取失败: %v", err)
+	}
+	if second.MediaDirect {
+		t.Fatal("代理模式不应标记直连")
+	}
+	if !strings.HasPrefix(second.Tracks[0], "/api/reader/media?") {
+		t.Fatalf("缓存命中后仍应按代理改写，实际 %q", second.Tracks[0])
+	}
+}
+
+// TestMediaDirectForceProxyWins 客户端显式要求代理时，即使书源开着直连也走代理。
+//
+// 这是直连取不到字节时的退路：不让用户为了继续读一章去改书源设置。
+func TestMediaDirectForceProxyWins(t *testing.T) {
+	svc, _, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	if err := svc.SetSourceMediaDirect(ctx, readerTestUserID, sourceIDOf(t, svc, book.Origin), true); err != nil {
+		t.Fatalf("开启直连失败: %v", err)
+	}
+
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0,
+		ContentOptions{MediaDirect: true, ForceProxy: true})
+	if err != nil {
+		t.Fatalf("读取失败: %v", err)
+	}
+	if out.MediaDirect {
+		t.Fatal("强制代理时不应标记直连")
+	}
+	if !strings.HasPrefix(out.Tracks[0], "/api/reader/media?") {
+		t.Fatalf("强制代理时应返回签名代理地址，实际 %q", out.Tracks[0])
+	}
+	if len(out.MediaHeaders) != 0 {
+		t.Fatalf("代理模式不应下发请求头，实际 %v", out.MediaHeaders)
+	}
+}
+
+// sourceIDOf 按书源 URL 取当前用户的书源 ID。
+func sourceIDOf(t *testing.T, svc *ReaderService, origin string) string {
+	t.Helper()
+	srcs, err := svc.ListSources(t.Context(), readerTestUserID)
+	if err != nil {
+		t.Fatalf("列书源失败: %v", err)
+	}
+	for _, src := range srcs {
+		if src.SourceURL == origin {
+			return src.ID
+		}
+	}
+	t.Fatalf("找不到书源 %s", origin)
+	return ""
+}

internal/service/reader/media_refresh.go

@@ -0,0 +1,190 @@
+package reader
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 本文件处理「音频直链的签名票过期」这一类上游故障。
+//
+// 背景：听书源（聆阅·懒人听书这类）的播放地址是第三方中转现签的 CDN 直链，
+// 形如 https://vb.stream.tencentmusic.com/long/xxx.m4a?...&vkey=...&ttl=86400000。
+// 票的有效性不只取决于时间：中转背后是多个账号 token 轮换，某个 uid/vkey 组合
+// 会被 CDN 判掉，此时上游返回**空的 401**（无 Content-Type、无 body），而同一章
+// 隔几百毫秒重新签一张票就又能取到。
+//
+// 旧行为：媒体代理把这个 401 原样透传给播放器，播放器重试的又是同一个 URL，
+// 于是 App 日志里出现连续 4~8 个 401；同时音频清单还有 30 分钟缓存，这 30 分钟
+// 内 /content 一直下发同一张死票，表现为「这本书怎么都播不了，换本书才行」。
+//
+// 现在的行为：代理遇到 401/403/410 时先把该章的缓存作废、重新走一次书源取正文，
+// 拿到新票再拉一次；新票同时写回缓存，后续请求自然就是有效的。
+
+// mediaRefreshTTL 新票的短缓存：播放器一次失败会立刻用同一 URL 重试多次，
+// 这里让并发的重试共用一次回源，避免把书源打成限流。
+const mediaRefreshTTL = 2 * time.Minute
+
+// mediaRefreshEntry 一次成功换票的结果。
+type mediaRefreshEntry struct {
+	url string
+	exp time.Time
+}
+
+// mediaRefreshState 保护「旧直链 → 新直链」的短缓存。
+type mediaRefreshState struct {
+	mu      sync.Mutex
+	entries map[string]mediaRefreshEntry
+}
+
+// lookupMediaRefresh 查换票短缓存（过期条目顺手清掉）。
+func (s *ReaderService) lookupMediaRefresh(staleURL string) (string, bool) {
+	s.mediaRefresh.mu.Lock()
+	defer s.mediaRefresh.mu.Unlock()
+	entry, ok := s.mediaRefresh.entries[staleURL]
+	if !ok {
+		return "", false
+	}
+	if time.Now().After(entry.exp) {
+		delete(s.mediaRefresh.entries, staleURL)
+		return "", false
+	}
+	return entry.url, true
+}
+
+// rememberMediaRefresh 记住换票结果，并顺手清理过期条目（表很小，遍历即可）。
+func (s *ReaderService) rememberMediaRefresh(staleURL, freshURL string) {
+	s.mediaRefresh.mu.Lock()
+	defer s.mediaRefresh.mu.Unlock()
+	if s.mediaRefresh.entries == nil {
+		s.mediaRefresh.entries = map[string]mediaRefreshEntry{}
+	}
+	now := time.Now()
+	for k, v := range s.mediaRefresh.entries {
+		if now.After(v.exp) {
+			delete(s.mediaRefresh.entries, k)
+		}
+	}
+	s.mediaRefresh.entries[staleURL] = mediaRefreshEntry{url: freshURL, exp: now.Add(mediaRefreshTTL)}
+}
+
+// RefreshMediaURL 在直链签名失效后重新换一张票。
+//
+// staleURL 是书源侧产出的原始媒体地址（媒体代理已还原、未加签名）。返回三个值：
+//
+//	refreshable=false  这个地址不是「可换票的音轨」（漫画图片、封面、或并非来自
+//	                   章节缓存的地址），调用方应原样透传上游状态，保持旧行为；
+//	refreshable=true 且 err!=nil  确实是音轨但换票失败，调用方应给出明确错误，
+//	                   别让播放器对着必然失败的地址反复重试；
+//	refreshable=true 且 err==nil  拿到了新票。
+//
+// 换票流程：在书架书籍的章节缓存里找到它所属的那一章 → 作废该章缓存（否则
+// /content 会继续下发同一张死票）→ 重新走书源取正文 → 按同一个音轨序号取新地址。
+func (s *ReaderService) RefreshMediaURL(ctx context.Context, book *model.ReaderBook, staleURL string) (string, bool, error) {
+	if s == nil || s.repo == nil || book == nil {
+		return "", false, nil
+	}
+	staleURL = strings.TrimSpace(staleURL)
+	if staleURL == "" {
+		return "", false, nil
+	}
+	if fresh, ok := s.lookupMediaRefresh(staleURL); ok {
+		return fresh, true, nil
+	}
+	sourceID := s.contentSourceID(ctx, nil, book)
+	if sourceID == "" {
+		return "", false, nil
+	}
+	bookKey := contentBookKey(sourceID, book.BookURL)
+	rows, err := s.repo.ListContentCacheByBook(ctx, bookKey)
+	if err != nil || len(rows) == 0 {
+		return "", false, nil
+	}
+	for i := range rows {
+		row := rows[i]
+		payload, ok := s.readContentPayload(&row)
+		if !ok || payload.ContentType != "audio" {
+			continue
+		}
+		trackIndex := indexOfString(payload.Tracks, staleURL)
+		if trackIndex < 0 {
+			continue
+		}
+		ch, ok := s.chapterForCacheRow(ctx, book, row)
+		if !ok {
+			return "", true, fmt.Errorf("章节已不在目录中")
+		}
+		// 先作废：即使后面重抓失败，也不会继续把死票发给播放器。
+		s.dropContentCacheRow(ctx, &row)
+		out, fetchErr := s.fetchChapterContentShared(ctx, book, ch)
+		if fetchErr != nil {
+			return "", true, fmt.Errorf("重新取章节失败: %w", fetchErr)
+		}
+		if out == nil || trackIndex >= len(out.Tracks) {
+			return "", true, fmt.Errorf("新内容没有对应的音轨")
+		}
+		fresh := strings.TrimSpace(out.Tracks[trackIndex])
+		if strings.HasPrefix(fresh, "/api/") {
+			// fetchChapterContentShared 返回缓存原样地址；兜底解析一次代理形态。
+			return "", true, fmt.Errorf("书源返回了代理地址")
+		}
+		if fresh == "" || fresh == staleURL {
+			return "", true, fmt.Errorf("书源返回了相同地址")
+		}
+		s.rememberMediaRefresh(staleURL, fresh)
+		return fresh, true, nil
+	}
+	return "", false, nil
+}
+
+// readContentPayload 读取一条章节缓存的落盘载荷。
+func (s *ReaderService) readContentPayload(row *model.ReaderContentCache) (cachedChapterContent, bool) {
+	var payload cachedChapterContent
+	path := s.contentPathFromRow(row)
+	if path == "" {
+		return payload, false
+	}
+	raw, err := os.ReadFile(path) // #nosec G304 -- 路径由服务端生成
+	if err != nil {
+		return payload, false
+	}
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return payload, false
+	}
+	return payload, true
+}
+
+// chapterForCacheRow 按缓存行的章节键找回目录里的章节（remap 后键仍一致）。
+func (s *ReaderService) chapterForCacheRow(ctx context.Context, book *model.ReaderBook, row model.ReaderContentCache) (model.ReaderChapter, bool) {
+	chapters, err := s.repo.ListChapters(ctx, book.ID)
+	if err != nil {
+		return model.ReaderChapter{}, false
+	}
+	for _, ch := range chapters {
+		if contentChapterKey(book, ch) == row.ChapterKey {
+			return ch, true
+		}
+	}
+	// 退一步按序号取：目录里同一章可能因为标题变化换了身份键。
+	if row.ChapterIndex >= 0 && row.ChapterIndex < len(chapters) && !chapters[row.ChapterIndex].IsVolume {
+		return chapters[row.ChapterIndex], true
+	}
+	return model.ReaderChapter{}, false
+}
+
+// indexOfString 返回目标字符串在列表中的下标，找不到返回 -1。
+func indexOfString(list []string, target string) int {
+	target = strings.TrimSpace(target)
+	for i, item := range list {
+		if strings.TrimSpace(item) == target {
+			return i
+		}
+	}
+	return -1
+}

internal/service/reader/media_refresh_test.go

@@ -0,0 +1,263 @@
+package reader
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 本文件：「音频直链签名票被 CDN 拒掉」后的换票回归测试。
+//
+// 背景：听书源（聆阅·懒人听书）的播放地址是第三方中转现签的 CDN 直链，票会被
+// 上游判掉，此时 CDN 回的是**空的 401**（无 Content-Type、无 body）。旧行为把它
+// 原样透传给播放器，播放器重试的又是同一个 URL，于是连续 4~8 个 401，
+// App 日志表现为 ERROR_CODE_IO_BAD_HTTP_STATUS (2004)「怎么都播不了」。
+//
+// 现在的约定（RefreshMediaURL）：
+//   - 能定位到归属章节 → 换票（先作废缓存，再重新走书源取正文）；
+//   - 地址不是音轨（漫画图片、封面等）→ refreshable=false，调用方原样透传；
+//   - 是音轨但换不到 → refreshable=true + err，调用方给出明确错误不再让播放器重试。
+
+// ticketServer 模拟「中转现签 CDN 直链」的上游：
+//   - /book/1   详情页（含目录链接）
+//   - /toc      目录
+//   - /content  章节正文，每次请求签一张新票
+//   - /media    媒体本体，只认最新签出的那张票，其余回空的 401
+type ticketServer struct {
+	*httptest.Server
+	mu      sync.Mutex
+	issued  []string
+	hits    int
+	noToken bool // true 时正文里不带票（模拟书源不再给新地址）
+}
+
+func newTicketServer() *ticketServer {
+	s := &ticketServer{}
+	s.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasPrefix(r.URL.Path, "/book/1"):
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			_, _ = w.Write([]byte(`<html><body><h1>票源之书</h1></body></html>`))
+		case r.URL.Path == "/content":
+			s.mu.Lock()
+			s.hits++
+			n := s.hits
+			noToken := s.noToken
+			s.mu.Unlock()
+			w.Header().Set("Content-Type", "application/json; charset=utf-8")
+			if noToken {
+				_, _ = w.Write([]byte(`{"data":{"url":""}}`))
+				return
+			}
+			token := fmt.Sprintf("ticket-%d", n)
+			s.mu.Lock()
+			s.issued = append(s.issued, token)
+			s.mu.Unlock()
+			_, _ = w.Write([]byte(fmt.Sprintf(`{"data":{"url":"%s/media?t=%s"}}`, s.URL, token)))
+		case r.URL.Path == "/media":
+			// 只认最近签出的那张票；旧票回空的 401（与腾讯 CDN 行为一致）。
+			token := r.URL.Query().Get("t")
+			s.mu.Lock()
+			valid := len(s.issued) > 0 && s.issued[len(s.issued)-1] == token
+			s.mu.Unlock()
+			if !valid {
+				w.WriteHeader(http.StatusUnauthorized)
+				return
+			}
+			w.Header().Set("Content-Type", "audio/mp4")
+			_, _ = w.Write([]byte("\x00\x00\x00\x20ftypmp42fake-audio-bytes"))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	return s
+}
+
+func (s *ticketServer) contentHits() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.hits
+}
+
+// ticketSourceJSON 一个最小听书源：正文规则取 JSON 里的播放直链。
+func ticketSourceJSON(t *testing.T, base string) string {
+	t.Helper()
+	return `{
+  "bookSourceName": "票源测试",
+  "bookSourceType": 1,
+  "bookSourceUrl": "` + base + `",
+  "ruleContent": {"content": "$.data.url"}
+}`
+}
+
+// prepareTicketBook 建好「听书源 + 书架书籍 + 一章目录」，并开独立缓存目录。
+func prepareTicketBook(t *testing.T) (*ReaderService, *ticketServer, *model.ReaderBook) {
+	t.Helper()
+	srv := newTicketServer()
+	t.Cleanup(srv.Close)
+
+	svc, _ := newLoginTestService(t)
+	svc.cfg.Cache.CacheDir = t.TempDir()
+	ctx := t.Context()
+	sourceID := prepareLoginSource(t, svc, ticketSourceJSON(t, srv.URL))
+	book, err := svc.AddBook(ctx, readerTestUserID, SearchOrigin{
+		SourceID:   sourceID,
+		Origin:     srv.URL,
+		OriginName: "票源测试",
+		OriginType: 1,
+		BookURL:    srv.URL + "/book/1",
+	}, "票源之书", "某作者", "")
+	if err != nil {
+		t.Fatalf("加入书架失败: %v", err)
+	}
+	if err := svc.SaveChapters(ctx, book.ID, []ChapterInput{
+		{Index: 0, Title: "第一章", URL: srv.URL + "/content"},
+	}); err != nil {
+		t.Fatalf("保存目录失败: %v", err)
+	}
+	return svc, srv, book
+}
+
+// TestRefreshMediaURLIssuesNewTicket 票被拒后换票：拿到新地址、缓存被刷新。
+func TestRefreshMediaURLIssuesNewTicket(t *testing.T) {
+	svc, srv, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	// 首读：拿到第一张票并落缓存
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
+	if err != nil {
+		t.Fatalf("首次读取失败: %v", err)
+	}
+	if len(out.Tracks) != 1 {
+		t.Fatalf("音轨数 = %d", len(out.Tracks))
+	}
+	stale, err := svc.VerifyProxyURL(book.ID, trackQueryValue(t, out.Tracks[0], "u"), trackQueryValue(t, out.Tracks[0], "s"))
+	if err != nil {
+		t.Fatalf("还原直链失败: %v", err)
+	}
+
+	fresh, refreshable, err := svc.RefreshMediaURL(ctx, book, stale)
+	if err != nil {
+		t.Fatalf("换票失败: %v", err)
+	}
+	if !refreshable {
+		t.Fatal("音轨地址应当可换票")
+	}
+	if fresh == stale {
+		t.Fatalf("换票后地址没变: %q", fresh)
+	}
+	if got := srv.contentHits(); got != 2 {
+		t.Fatalf("换票应回源重取一次章节，实际请求 %d 次", got)
+	}
+
+	// 新票必须能取到媒体本体（旧票是空的 401）
+	resp, err := http.Get(fresh)
+	if err != nil {
+		t.Fatalf("新票请求失败: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("新票状态码 = %d，期望 200", resp.StatusCode)
+	}
+
+	// 缓存要被刷新成新票：再次读章节不应再回源
+	out2, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
+	if err != nil {
+		t.Fatalf("换票后读章节失败: %v", err)
+	}
+	refreshed, err := svc.VerifyProxyURL(book.ID, trackQueryValue(t, out2.Tracks[0], "u"), trackQueryValue(t, out2.Tracks[0], "s"))
+	if err != nil {
+		t.Fatalf("还原刷新后的直链失败: %v", err)
+	}
+	if refreshed != fresh {
+		t.Fatalf("章节缓存应刷新为新票 %q，实际 %q", fresh, refreshed)
+	}
+	if got := srv.contentHits(); got != 2 {
+		t.Fatalf("缓存已刷新，不应再回源，实际请求 %d 次", got)
+	}
+}
+
+// TestRefreshMediaURLMemoryReusesTicket 同一张旧票的多次换票只回源一次：
+// 播放器一次失败会立刻用同一 URL 重试多次，重复回源会把书源打成限流。
+func TestRefreshMediaURLMemoryReusesTicket(t *testing.T) {
+	svc, srv, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
+	if err != nil {
+		t.Fatalf("首次读取失败: %v", err)
+	}
+	stale, _ := svc.VerifyProxyURL(book.ID, trackQueryValue(t, out.Tracks[0], "u"), trackQueryValue(t, out.Tracks[0], "s"))
+
+	first, _, err := svc.RefreshMediaURL(ctx, book, stale)
+	if err != nil {
+		t.Fatalf("首次换票失败: %v", err)
+	}
+	for i := 0; i < 3; i++ {
+		again, refreshable, err := svc.RefreshMediaURL(ctx, book, stale)
+		if err != nil || !refreshable {
+			t.Fatalf("第 %d 次换票失败: refreshable=%v err=%v", i+2, refreshable, err)
+		}
+		if again != first {
+			t.Fatalf("同一旧票应复用同一个新票：%q vs %q", again, first)
+		}
+	}
+	if got := srv.contentHits(); got != 2 {
+		t.Fatalf("重复换票只该回源一次，实际 %d 次", got)
+	}
+}
+
+// TestRefreshMediaURLSkipsNonTrackURL 漫画图片/防盗链图片这类地址不属于音轨，
+// 调用方应原样透传上游状态（不能被换票逻辑吃掉响应体）。
+func TestRefreshMediaURLSkipsNonTrackURL(t *testing.T) {
+	svc, _, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	if _, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{}); err != nil {
+		t.Fatalf("首次读取失败: %v", err)
+	}
+	_, refreshable, err := svc.RefreshMediaURL(ctx, book, "https://img.example.com/cover.jpg")
+	if err != nil {
+		t.Fatalf("非音轨地址不该报错: %v", err)
+	}
+	if refreshable {
+		t.Fatal("非音轨地址不该被判为可换票")
+	}
+}
+
+// TestRefreshMediaURLErrorsWhenSourceRepeatsTicket 书源重新签出同一张票时，
+// 说明中转本身没换票，应当明确失败而不是让播放器继续对着死票重试。
+func TestRefreshMediaURLErrorsWhenSourceRepeatsTicket(t *testing.T) {
+	svc, srv, book := prepareTicketBook(t)
+	ctx := t.Context()
+
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
+	if err != nil {
+		t.Fatalf("首次读取失败: %v", err)
+	}
+	stale, _ := svc.VerifyProxyURL(book.ID, trackQueryValue(t, out.Tracks[0], "u"), trackQueryValue(t, out.Tracks[0], "s"))
+
+	// 让书源此后只回空地址：换票必然失败。
+	srv.mu.Lock()
+	srv.noToken = true
+	srv.mu.Unlock()
+
+	_, refreshable, err := svc.RefreshMediaURL(ctx, book, stale)
+	if !refreshable {
+		t.Fatal("音轨地址应当被判为可换票")
+	}
+	if err == nil {
+		t.Fatal("书源给不出新票时应当报错")
+	}
+	// 作废过的缓存不该把死票留在库里
+	if _, ok := svc.loadCachedContent(ctx, nil, nil, book, model.ReaderChapter{
+		Index: 0, Title: "第一章", URL: srv.URL + "/content",
+	}, "audio"); ok {
+		t.Fatal("换票失败后旧缓存应已被作废，不应继续下发死票")
+	}
+}

internal/service/reader/proxy_test.go

@@ -5,11 +5,13 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"strconv"
 	"sync/atomic"
 	"testing"
 	"time"
 
 	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/helper"
 	"github.com/truewhile/MeBox/internal/model"
 )
 
@@ -132,3 +134,71 @@ func TestFetchMediaDoesNotRetryNotFound(t *testing.T) {
 		t.Fatalf("上游请求次数 = %d，期望 1（404 不该重试）", got)
 	}
 }
+
+// TestMediaHTTPClientHasNoOverallTimeout 媒体客户端不能用「整体超时」。
+//
+// 这是本次故障的第二个根因：http.Client.Timeout 覆盖「读完 body」这一阶段。
+// 一个 4MB 的 m4a 在跨境链路上很容易超过 30 秒，超时后 net/http 直接掐断
+// 响应体，而调用方的 io.Copy 只是正常返回——表现为**静默截断**（播放器拿到
+// 半首歌，判「格式不支持」）或 502。所以媒体客户端必须没有整体超时。
+func TestMediaHTTPClientHasNoOverallTimeout(t *testing.T) {
+	client := helper.NewMediaHTTPClient(false)
+	if client.Timeout != 0 {
+		t.Fatalf("媒体 client 的整体 Timeout = %v，必须为 0（大文件下载会被静默截断）", client.Timeout)
+	}
+	tr, ok := client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("Transport 类型 = %T", client.Transport)
+	}
+	if tr.ResponseHeaderTimeout <= 0 {
+		t.Fatal("媒体 client 应设置 ResponseHeaderTimeout，避免上游不给首字节时无限挂起")
+	}
+	// 必须走 HTTP/1.1：腾讯 CDN 的 h2 边缘在长连接大文件上不回 WINDOW_UPDATE，
+	// Go 的 h2 初始连接窗口是 1MiB，下载会稳定断在 1MiB/2MiB/3MiB 整数倍处。
+	if tr.ForceAttemptHTTP2 {
+		t.Error("媒体 client 必须关闭 HTTP/2（1MiB 窗口截断）")
+	}
+	if tr.TLSNextProto == nil || len(tr.TLSNextProto) != 0 {
+		t.Error("媒体 client 需要清空 TLSNextProto，才能确保不用 h2")
+	}
+}
+
+// TestFetchMediaStreamsLargeBodyWithoutTruncation 大响应体必须完整送达。
+//
+// 用「慢速分块发送」模拟跨境链路上的大音频：总耗时超过规则请求的 30 秒超时，
+// 但媒体通路必须把每一个字节都交出来，绝不静默截断。
+func TestFetchMediaStreamsLargeBodyWithoutTruncation(t *testing.T) {
+	const totalBytes = 24 << 20 // 24MB
+	const chunk = 512 << 10
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "audio/mp4")
+		w.Header().Set("Content-Length", strconv.Itoa(totalBytes))
+		payload := make([]byte, chunk)
+		for off := 0; off < totalBytes; off += chunk {
+			if _, err := w.Write(payload); err != nil {
+				return
+			}
+			w.(http.Flusher).Flush()
+			time.Sleep(5 * time.Millisecond)
+		}
+	}))
+	defer srv.Close()
+
+	svc, _ := newLoginTestService(t)
+	book := &model.ReaderBook{Origin: srv.URL}
+
+	resp, err := svc.FetchMedia(t.Context(), book, srv.URL+"/big.m4a", "")
+	if err != nil {
+		t.Fatalf("FetchMedia 失败: %v", err)
+	}
+	defer resp.Body.Close()
+	got, readErr := io.Copy(io.Discard, resp.Body)
+	if readErr != nil {
+		t.Fatalf("读取响应体失败: %v", readErr)
+	}
+	if got != totalBytes {
+		t.Fatalf("交付字节 = %d，期望 %d（少了 %d 字节 → 播放器会判格式不支持）",
+			got, totalBytes, int64(totalBytes)-got)
+	}
+}

internal/service/reader/rate_limit.go

@@ -80,12 +80,19 @@ func parseConcurrentRate(rate string) time.Duration {
 const (
 	// maxRequestAttempts 单次请求最大尝试次数（含首次），兜住书源里写很大的 retry。
 	maxRequestAttempts = 5
+	// implicitRetryAttempts 书源没声明 retry 时，GET 请求在可重试状态码上的默认尝试次数。
+	// 实测这类聚合源的单次 429 概率接近一半，两次尝试仍有约两成失败，三次降到一成左右；
+	// 再往上加只会让被限流的接口更难恢复。退避总共不到 1 秒，详情/目录请求扛得住。
+	implicitRetryAttempts = 3
 	// requestRetryDelay 请求重试退避基数，实际等待为 attempt 倍。
 	requestRetryDelay = 300 * time.Millisecond
 )
 
 // retryableStatus 该状态码是否值得重试：限流（403/429）与上游抖动（5xx）可重试，
 // 404/400 这类确定性错误不重试。规则请求与媒体代理共用。
+//
+// 注意 401 不在这里：书源的规则请求返回 401 通常是「登录态失效」，反复重试
+// 只会白等退避时间。媒体直链另有语义，见 mediaRetryableStatus。
 func retryableStatus(code int) bool {
 	switch code {
 	case 403, 408, 425, 429, 500, 502, 503, 504:
@@ -95,6 +102,46 @@ func retryableStatus(code int) bool {
 	}
 }
 
+// implicitRetryableStatus 书源没声明 retry 时，值得自动补一次的失败。
+//
+// 只覆盖「上游临时顶不住」的情形：429 是限流/并发上限，502/503/504 是网关或
+// 实例暂时不可用，歇一轮基本会恢复。403（风控）重试同一份请求多半还是 403，
+// 500 可能是源站自身 bug（确定性失败），都不在这里浪费一次往返。
+func implicitRetryableStatus(code int) bool {
+	switch code {
+	case 429, 502, 503, 504:
+		return true
+	default:
+		return false
+	}
+}
+
+// mediaRetryableStatus 媒体拉取专用的可重试判定。
+//
+// 与规则请求不同，CDN 直链的 410 表示「对象已下线」，与 403/429 一样属于
+// 上游抖动，同一张票稍后重试可能就恢复；而 401 是「签名票被拒」，重试同一张票
+// 一定还是 401，必须由调用方回源换票（见 MediaNeedsRefresh）。
+// 所以这里只补 410，不把 401 加进来。
+func mediaRetryableStatus(code int) bool {
+	if retryableStatus(code) {
+		return true
+	}
+	return code == 410
+}
+
+// MediaNeedsRefresh 判断媒体上游状态是否值得「换一张签名票再试」。
+//
+// 401 是 CDN 对无效 vkey/uid 的固定回答（空 body、无 Content-Type），410 是
+// 对象已下线，403 常见于票与资源不匹配。这三类都值得回到书源重新签票。
+func MediaNeedsRefresh(code int) bool {
+	switch code {
+	case 401, 403, 410:
+		return true
+	default:
+		return false
+	}
+}
+
 // sleepWithContext 可被 ctx 取消的等待；返回 false 表示上下文已结束。
 func sleepWithContext(ctx context.Context, d time.Duration) bool {
 	if d <= 0 {

internal/service/reader/rate_limit_test.go

@@ -71,3 +71,36 @@ func TestRetryableStatus(t *testing.T) {
 		}
 	}
 }
+
+// TestMediaRetryableStatus 媒体直链的 410（对象已下线）与 403/429 一样值得原地重试，
+// 但 401「签名票被拒」原地重试一定是同样的结果，只能靠回源换票。
+func TestMediaRetryableStatus(t *testing.T) {
+	for _, code := range []int{403, 410, 429, 500, 503} {
+		if !mediaRetryableStatus(code) {
+			t.Errorf("媒体状态码 %d 应当可重试", code)
+		}
+	}
+	for _, code := range []int{200, 206, 301, 400, 401, 404} {
+		if mediaRetryableStatus(code) {
+			t.Errorf("媒体状态码 %d 不该原地重试", code)
+		}
+	}
+	// 规则请求的判定不能被放宽：登录态失效的 401 反复重试只会白等。
+	if retryableStatus(401) || retryableStatus(410) {
+		t.Error("retryableStatus 不应包含 401/410")
+	}
+}
+
+// TestMediaNeedsRefresh 只有「票被拒」这一类状态才值得回源换票。
+func TestMediaNeedsRefresh(t *testing.T) {
+	for _, code := range []int{401, 403, 410} {
+		if !MediaNeedsRefresh(code) {
+			t.Errorf("状态码 %d 应当换票重试", code)
+		}
+	}
+	for _, code := range []int{200, 206, 304, 400, 404, 429, 500} {
+		if MediaNeedsRefresh(code) {
+			t.Errorf("状态码 %d 不该换票", code)
+		}
+	}
+}

internal/service/reader/reader.go

@@ -43,7 +43,14 @@ type ReaderService struct {
 	log    *zap.Logger
 	repo   *repository.ReaderRepository
 	http   *http.Client
-	crypto *helper.SecretCipher
+	// mediaHTTP 用于转发媒体流（音频/视频/漫画大图）。
+	//
+	// 必须与 http 分开：http 设了 30 秒的「整体」超时（含读完 body），而一个
+	// 4MB 的音频在跨境链路上很容易超过它，超时后 net/http 直接掐断 body，
+	// 调用方的 io.Copy 却只是正常返回 —— 表现为静默截断（播放器拿到半首歌）
+	// 或 502。见 helper.NewMediaHTTPClient 的说明。
+	mediaHTTP *http.Client
+	crypto    *helper.SecretCipher
 
 	// browserMu / browserPending 保护「待用户完成的页面」表
 	// （java.startBrowser / startBrowserAwait，见 browser_panel.go）。
@@ -71,6 +78,10 @@ type ReaderService struct {
 	// 阅读页与批量预取会并发请求同一章（见 fetchChapterContentShared）。
 	contentFlightsMu sync.Mutex
 	contentFlights   map[string]*contentFlight
+
+	// mediaRefresh 记录「已失效直链 → 重新签到的新直链」的短缓存：
+	// CDN 判掉某张签名票后，播放器的多次重试共用一次回源（见 media_refresh.go）。
+	mediaRefresh mediaRefreshState
 }
 
 // NewReaderService 创建服务。
@@ -83,12 +94,21 @@ func NewReaderService(cfg *config.Config, log *zap.Logger, repos *repository.Con
 		log:                log,
 		repo:               repos.Reader,
 		http:               client,
+		mediaHTTP:          helper.NewMediaHTTPClient(true),
 		crypto:             helper.NewSecretCipher(firstNonEmpty(cfg.Secrets.EncryptionKey, cfg.Secrets.JWTSecret)),
 		limiter:            newSourceRateLimiter(),
 		coverDecodeOrigins: map[string]bool{},
 	}
 }
 
+// mediaClient 返回转发媒体流用的客户端（未注入时退回规则请求的 client）。
+func (s *ReaderService) mediaClient() *http.Client {
+	if s != nil && s.mediaHTTP != nil {
+		return s.mediaHTTP
+	}
+	return s.http
+}
+
 // markSourceCoverDecode 记录某书源是否声明了 coverDecodeJs（导入/更新书源时调用）。
 func (s *ReaderService) markSourceCoverDecode(sourceURL string, enabled bool) {
 	if s == nil || strings.TrimSpace(sourceURL) == "" {
@@ -405,12 +425,25 @@ func (s *ReaderService) executeWithState(ctx context.Context, req *rule.Request,
 	// retry：URL 选项声明的重试次数（对应 legado AnalyzeUrl 的同名字段）。
 	// 只重试可恢复的失败：网络错误、5xx、403/429（防盗链/限流）。确定性 4xx 不重试。
 	attempts := 1
-	if req.Retry != nil && *req.Retry > 0 {
+	declaredRetry := req.Retry != nil && *req.Retry > 0
+	if declaredRetry {
 		attempts += *req.Retry
 		if attempts > maxRequestAttempts {
 			attempts = maxRequestAttempts
 		}
 	}
+	// 书源没声明 retry 时，GET 也对上游瞬时失败（429/5xx）自动补一次。
+	// 很多聚合源跑在免费/低配后端上，限流是常态（懒人听书源实测约四成请求返回
+	// HTTP 429），而 429 的响应体根本不是书源数据，交给规则只会解析出空目录、
+	// 空详情。POST 可能有副作用，仍然只按书源声明重试。
+	if !declaredRetry && (req.Method == "" || req.Method == http.MethodGet) {
+		attempts = implicitRetryAttempts
+	}
+	// 自动补的一次只认「上游临时顶不住」的状态码，见 implicitRetryableStatus。
+	retryAllowed := retryableStatus
+	if !declaredRetry {
+		retryAllowed = implicitRetryableStatus
+	}
 	var (
 		resp *http.Response
 		data []byte
@@ -444,7 +477,7 @@ func (s *ReaderService) executeWithState(ctx context.Context, req *rule.Request,
 			}
 			return "", "", resp.StatusCode, err
 		}
-		if attempt < attempts && retryableStatus(resp.StatusCode) {
+		if attempt < attempts && retryAllowed(resp.StatusCode) {
 			if !sleepWithContext(ctx, requestRetryDelay*time.Duration(attempt)) {
 				return "", "", resp.StatusCode, nil
 			}
@@ -516,6 +549,25 @@ func charsetFromContentType(ct string) string {
 	return strings.Trim(cs, "\"")
 }
 
+// upstreamStatusError 把书源接口的失败状态码翻译成可读错误。
+//
+// 上游限流/过载时返回的响应体不是书源数据：交给规则解析只会得到空目录、空详情，
+// 页面就表现成「目录 0 章」而没有任何报错。这里让调用方拿到明确错误，
+// 前端才能提示重试，而不是把「抓不到」当成「这本书没有章节」。
+func upstreamStatusError(code int) error {
+	if code < 400 {
+		return nil
+	}
+	switch code {
+	case http.StatusTooManyRequests:
+		return fmt.Errorf("书源接口限流（HTTP 429），请稍后重试")
+	case http.StatusForbidden:
+		return fmt.Errorf("书源接口拒绝访问（HTTP 403），可能触发了风控")
+	default:
+		return fmt.Errorf("书源接口返回 HTTP %d", code)
+	}
+}
+
 // ─── 规则执行辅助 ───────────────────────────────────────────────────────────
 
 // sourceSession 是一次书源操作的执行上下文：把书源记录、解析结构与
@@ -1111,10 +1163,13 @@ func (s *ReaderService) searchInSource(ctx context.Context, src *model.ReaderBoo
 		return nil, req.Unsupported
 	}
 	sess.applyHeaders(req, runner)
-	body, finalURL, _, err := sess.fetch(req)
+	body, finalURL, code, err := sess.fetch(req)
 	if err != nil {
 		return nil, err
 	}
+	if err := upstreamStatusError(code); err != nil {
+		return nil, err
+	}
 	ar := sess.newAnalyzer(key, page, body, finalURL)
 
 	elements, err := ar.GetElements(SPtr(sr.BookList))
@@ -1144,7 +1199,7 @@ func (s *ReaderService) searchInSource(ctx context.Context, src *model.ReaderBoo
 			WordCount:     wordCount,
 			LatestChapter: lastChapter,
 			Intro:         intro,
-			CoverURL:      normalizeCoverURL(cover),
+			CoverURL:      normalizeCoverURL(cover, finalURL),
 			BookURL:       bookURL,
 			Origins: []SearchOrigin{{
 				SourceID:      src.ID,
@@ -1201,11 +1256,20 @@ func firstNonEmpty(vals ...string) string {
 // 于是封面上会落一串 data: 文本，<img> 按 text/plain 处理必然破图。
 // 允许的相对地址以 "/" 开头，用于应用自身生成的本地书封面
 // （/api/reader/local/asset?...）。
-func normalizeCoverURL(raw string) string {
+//
+// baseURL 是规则解析时的页面地址（详情页就是书本地址）。取值为空时规则会原样
+// 回退成它，回退结果同样不是图片：比如懒人听书源被上游限流（HTTP 429）时，
+// 详情 JSON 里没有 meta.cover，封面就会变成 .../lrts-book?bookId=xxx 这个接口地址。
+// 这类值必须一并丢掉，否则会被存进书架，之后一直显示破图。
+func normalizeCoverURL(raw, baseURL string) string {
 	u := strings.TrimSpace(raw)
 	if u == "" {
 		return ""
 	}
+	// 规则取空后回退成页面地址的产物：不是图片，也不是用户要的封面。
+	if base := strings.TrimSpace(baseURL); base != "" && u == base {
+		return ""
+	}
 	lower := strings.ToLower(u)
 	switch {
 	case strings.HasPrefix(lower, "http://"), strings.HasPrefix(lower, "https://"):
@@ -1262,10 +1326,13 @@ func (s *ReaderService) getBookInfoFrom(ctx context.Context, src *model.ReaderBo
 		return nil, req.Unsupported
 	}
 	sess.applyHeaders(req, runner)
-	body, finalURL, _, err := sess.fetch(req)
+	body, finalURL, code, err := sess.fetch(req)
 	if err != nil {
 		return nil, err
 	}
+	if err := upstreamStatusError(code); err != nil {
+		return nil, err
+	}
 	ar := sess.newAnalyzer("", 0, body, finalURL)
 	sess.applyBookContext(ar, bookURL, book, "", 0)
 
@@ -1299,7 +1366,7 @@ func (s *ReaderService) getBookInfoFrom(ctx context.Context, src *model.ReaderBo
 		info.Intro = v
 	}
 	if v, err := ar.GetString(SPtr(bir.CoverURL), nil, true); err == nil && v != "" {
-		info.CoverURL = normalizeCoverURL(v)
+		info.CoverURL = normalizeCoverURL(v, finalURL)
 	}
 	if v, err := ar.GetString(SPtr(bir.TocURL), nil, true); err == nil && v != "" {
 		info.TocURL = v
@@ -1549,6 +1616,37 @@ func (s *ReaderService) persistBookTocURL(ctx context.Context, userID, origin, b
 	}
 }
 
+// RepairShelfCover 用详情页刚解析出的封面修复书架记录。
+//
+// 只修「明显坏掉」的旧记录：封面为空，或等于书本地址/书源地址（规则取空后回退
+// baseUrl 的产物）。上游限流（HTTP 429）时详情里没有封面，旧版本会把接口地址
+// 存进书架，之后一直显示破图；打开一次详情页就能自愈。已有有效封面的记录不动，
+// 避免覆盖换源或用户数据。
+func (s *ReaderService) RepairShelfCover(ctx context.Context, userID, origin, bookURL, cover string) {
+	if s.repo == nil || userID == "" || origin == "" || bookURL == "" {
+		return
+	}
+	// 书架记录里的 BookURL 与调用方传入的一致（可能带 ",{...}" 选项段），
+	// 查找用原值；只在校验封面是否为「回退地址」时用去掉选项段的形态。
+	pageURL := tocBookTarget(bookURL)
+	cover = normalizeCoverURL(cover, pageURL)
+	if cover == "" {
+		return
+	}
+	book, err := s.repo.FindBookByURL(ctx, userID, origin, bookURL)
+	if err != nil || book == nil {
+		return
+	}
+	current := strings.TrimSpace(book.CoverURL)
+	if current != "" && current != pageURL && current != strings.TrimSpace(origin) {
+		return
+	}
+	book.CoverURL = cover
+	if err := s.repo.UpdateBook(ctx, book); err != nil && s.log != nil {
+		s.log.Warn("reader: 修复书架封面失败", zap.String("book", book.ID), zap.Error(err))
+	}
+}
+
 // applyTocMeta 把目录阶段得到的信息写回书架记录：
 //   - 书源在规则 JS 里声明的书籍类型（declared >= 0 时）；
 //   - 末章标题，以及末章变化时刷新的「最近更新」时间（对应 legado Book.latestChapterTime）。
@@ -1675,10 +1773,13 @@ func (s *ReaderService) fetchTocPage(ctx context.Context, sess *sourceSession, b
 		return nil, nil, -1, req.Unsupported
 	}
 	sess.applyHeaders(req, runner)
-	body, finalURL, _, err := sess.fetch(req)
+	body, finalURL, code, err := sess.fetch(req)
 	if err != nil {
 		return nil, nil, -1, err
 	}
+	if err := upstreamStatusError(code); err != nil {
+		return nil, nil, -1, err
+	}
 	ar := sess.newAnalyzer("", 0, body, finalURL)
 	sess.applyBookContext(ar, bookURL, nil, "", 0)
 
@@ -1749,6 +1850,13 @@ type ChapterContent struct {
 	// 前端据此决定走 hls.js 而不是原生 <audio>：代理地址是 base64 编码的
 	// /api/reader/media?...&u=...，前端无法再从 URL 后缀判断格式。
 	IsHLS bool `json:"hls,omitempty"`
+	// MediaDirect 为真表示 Tracks/Images 是上游原始地址，由客户端直接去取，
+	// 服务端不再代理字节。此时 MediaHeaders 给出取这些地址所需的请求头。
+	// 只有客户端显式请求直连（ContentOptions.MediaDirect）且书源开启该开关时才会出现。
+	MediaDirect bool `json:"media_direct,omitempty"`
+	// MediaHeaders 直连模式下取媒体所需的请求头（防盗链 Referer/UA、登录 Cookie 等）。
+	// 代理模式下为空：请求头只在服务端内部使用，不下发给客户端。
+	MediaHeaders map[string]string `json:"media_headers,omitempty"`
 	// declaredType 书源在规则 JS 里声明的书籍类型（-1 表示未声明），
 	// 由 GetContentForBook 写回书架记录（对应 legado Book.type）。
 	declaredType int
@@ -1756,6 +1864,106 @@ type ChapterContent struct {
 
 // ─── 媒体代理（音频流 / 漫画图片，带防盗链头与 HMAC 签名） ──────────────────
 
+// ContentOptions 正文下发的可选行为，只由请求参数决定，不改变默认链路。
+//
+// 默认零值 = 今天的网页行为：媒体地址全部改写为服务端签名代理，由服务端
+// 拉取字节再转发。MediaDirect 让客户端（Android App）自己去取上游字节，
+// 服务端只负责解析地址与下发请求头。
+type ContentOptions struct {
+	// MediaDirect 请求直连媒体字节。仅对开启了 MediaDirect 的书源生效，
+	// 否则仍返回代理地址，避免把未验证的源推到客户端直连。
+	MediaDirect bool
+	// ForceProxy 本次强制走服务端代理，即使书源开着直连。
+	//
+	// 给客户端留的退路：直连取不到（防盗链、票失效、上游限流等）时可以要求
+	// 服务端先代理一次，而不是让用户去改书源设置。
+	ForceProxy bool
+}
+
+// mediaDirectFor 结合书源开关与本次请求选项，决定这一章是否直连。
+func (s *ReaderService) mediaDirectFor(ctx context.Context, origin string, opts ContentOptions) bool {
+	if !opts.MediaDirect || opts.ForceProxy {
+		return false
+	}
+	return s.sourceAllowsMediaDirect(ctx, origin)
+}
+
+// applyMediaURLs 决定音频/图片地址是代理还是直连，并填好直连所需请求头。
+//
+// 直连时保留上游原始地址，同时把这一章的请求头一次性下发：同一章内的音轨与
+// 图片通常共用书源级 header / 登录态，逐条下发会让响应体成倍变大。
+// 逐图选项段（",{headers:...}"）的差异不在这里展开 —— 客户端会自行拆分。
+func (s *ReaderService) applyMediaURLs(ctx context.Context, book *model.ReaderBook, out *ChapterContent, direct bool) {
+	if out == nil {
+		return
+	}
+	if !direct {
+		for i, t := range out.Tracks {
+			out.Tracks[i] = s.ProxyURL(book.ID, t)
+		}
+		for i, img := range out.Images {
+			out.Images[i] = s.ProxyURL(book.ID, img)
+		}
+		return
+	}
+	out.MediaDirect = true
+	if out.MediaHeaders == nil {
+		out.MediaHeaders = map[string]string{}
+	}
+	// 请求头按章节内第一条媒体地址计算：同一章的音轨（或图片）通常同域名、
+	// 共用书源级 header 与登录态。逐图选项段（",{headers:...}"）的差异留给
+	// 客户端自行拆分，不下发也不参与这里的计算。
+	sample := ""
+	if len(out.Tracks) > 0 {
+		sample = out.Tracks[0]
+	} else if len(out.Images) > 0 {
+		sample = out.Images[0]
+	}
+	if sample != "" {
+		base, options, _ := rule.ParseMediaOptions(sample)
+		for k, v := range s.MediaRequestHeaders(ctx, book, base, options.Headers) {
+			// 传输层头由客户端 HTTP 栈自己算，下发了反而可能冲突。
+			if transportHeader(k) {
+				continue
+			}
+			out.MediaHeaders[k] = v
+		}
+	}
+}
+
+// sourceAllowsMediaDirect 书源是否允许客户端直连取媒体（按书源 URL 查当前用户的副本）。
+//
+// 查不到书源时返回 false：宁可退回代理，也不把未确认归属的源推到客户端直连。
+func (s *ReaderService) sourceAllowsMediaDirect(ctx context.Context, origin string) bool {
+	if s == nil || s.repo == nil || strings.TrimSpace(origin) == "" {
+		return false
+	}
+	src, err := s.repo.GetSourceAnyByURL(ctx, origin)
+	if err != nil || src == nil {
+		return false
+	}
+	return src.MediaDirect
+}
+
+// SetSourceMediaDirect 切换书源的媒体直连开关（限当前用户自己的书源）。
+func (s *ReaderService) SetSourceMediaDirect(ctx context.Context, userID, id string, direct bool) error {
+	src, err := s.repo.GetSourceForUser(ctx, userID, id)
+	if err != nil {
+		return err
+	}
+	src.MediaDirect = direct
+	return s.repo.UpdateSource(ctx, src)
+}
+
+// transportHeader 判断是否是传输层头（由客户端 HTTP 栈负责，不应下发）。
+func transportHeader(name string) bool {
+	switch strings.ToLower(name) {
+	case "accept-encoding", "connection", "host", "content-length", "cookie2":
+		return true
+	}
+	return false
+}
+
 // ProxyURL 将书源返回的媒体地址改写为签名代理地址。
 // 签名 = HMAC-SHA256(jwtSecret, bookID|url)，防止代理被滥用为开放中转。
 //
@@ -1801,7 +2009,7 @@ func (s *ReaderService) ProxyCoverURL(id, rawURL string) string {
 //
 // id 为空时按书源 URL 签（搜索结果）；传入书籍 ID 时按书签。
 func (s *ReaderService) RewriteBookCover(ctx context.Context, id, origin, coverURL string) string {
-	cover := normalizeCoverURL(coverURL)
+	cover := normalizeCoverURL(coverURL, "")
 	if cover == "" || !strings.HasPrefix(cover, "http") {
 		return cover
 	}
@@ -1844,6 +2052,80 @@ func BodyIsPlaylist(head []byte, contentType string) bool {
 	return strings.Contains(contentType, "mpegurl") && strings.Contains(string(head), "#EXTM3U")
 }
 
+// MediaRequestHeaders 构造取上游媒体所需的完整请求头。
+//
+// 服务端拉流（FetchMediaWithOptions）与客户端直连（ContentOptions.MediaDirect）
+// 共用这一份逻辑，保证两条链路的防盗链头、登录态与书源头完全一致 —— 直连只是
+// 把「谁发起 HTTP 请求」从服务端换成 App，不应退化成一套更弱的请求。
+//
+// 优先级由低到高：通用预设 < 书源 header < 登录态 < URL 尾部选项。
+func (s *ReaderService) MediaRequestHeaders(ctx context.Context, book *model.ReaderBook, rawURL string, options map[string]string) map[string]string {
+	out := map[string]string{}
+	for k, v := range helper.HTTPHeaderPresets() {
+		out[k] = v
+	}
+	if book == nil || s == nil {
+		return out
+	}
+	// 书源级请求头
+	if s.repo != nil {
+		if found, findErr := s.repo.GetSourceAnyByURL(ctx, book.Origin); findErr == nil && found != nil && found.Header != "" {
+			var headers map[string]any
+			if json.Unmarshal([]byte(found.Header), &headers) == nil {
+				for k, v := range headers {
+					out[k] = fmt.Sprintf("%v", v)
+				}
+			}
+		}
+	}
+	// 登录态：登录类书源的漫画/音频资源同样需要 Cookie 与 loginHeader 才能取到。
+	if s.repo != nil {
+		state := s.newSourceState(ctx, book.Origin)
+		for k, v := range state.LoginHeaderMap() {
+			if strings.EqualFold(k, "cookie") {
+				continue
+			}
+			if out[k] == "" {
+				out[k] = v
+			}
+		}
+		if out["Cookie"] == "" {
+			if ck := state.CookieForRequest(rawURL); ck != "" {
+				out["Cookie"] = ck
+			}
+		}
+	}
+	// URL 尾部选项里的请求头：优先级最高（逐图声明，取图必需）。
+	optionCookie := ""
+	for k, v := range options {
+		if strings.EqualFold(k, "Cookie") {
+			optionCookie = v
+			continue
+		}
+		out[k] = v
+	}
+	if optionCookie != "" {
+		// 与源 Cookie 合并时 options 优先（对应 legado AnalyzeUrl.setCookie 的临时 Cookie）。
+		if base := out["Cookie"]; base != "" {
+			out["Cookie"] = rule.MergeCookie(base, optionCookie)
+		} else {
+			out["Cookie"] = optionCookie
+		}
+	}
+	// 默认 Referer 只能用「真正的 http(s) 书源地址」。
+	// legado 的 origin 对普通书源是 bookSourceUrl，但聚合类书源（如「光遇聚合」）
+	// 的 origin 是个显示名，拼出来的 Referer 非法，会被图床判定为盗链并
+	// 301 到一张「请到本网站阅读」的占位图 —— 表现为漫画每一页都是同一张提示图。
+	// 这种情况下宁可不发 Referer（实测不带 Referer 能拿到原图）；书源 header
+	// 里自己声明的 Referer 优先级更高，不受这里影响。
+	if out["Referer"] == "" {
+		if referer := sourceReferer(book.Origin); referer != "" {
+			out["Referer"] = referer
+		}
+	}
+	return out
+}
+
 // FetchMedia 用书源会话拉取媒体（不应用 URL 尾部选项）。
 func (s *ReaderService) FetchMedia(ctx context.Context, book *model.ReaderBook, rawURL, rangeHeader string) (*http.Response, error) {
 	return s.FetchMediaWithOptions(ctx, book, rawURL, rangeHeader, nil)
@@ -1861,66 +2143,13 @@ func (s *ReaderService) FetchMediaWithOptions(ctx context.Context, book *model.R
 		if err != nil {
 			return nil, err
 		}
-		for k, v := range helper.HTTPHeaderPresets() {
+		for k, v := range s.MediaRequestHeaders(ctx, book, rawURL, options) {
 			httpReq.Header.Set(k, v)
 		}
 		// 媒体流同样交给 net/http 管压缩：否则压缩过的资源会以原始字节透传给
 		// 播放器/图片标签，表现为「打不开」。Range 请求服务端通常不压缩，
 		// 解压后 resp 会去掉 Content-Length/Content-Encoding，透传逻辑不受影响。
 		helper.StripAcceptEncoding(httpReq.Header)
-		// 书源级请求头
-		if s.repo != nil {
-			if found, findErr := s.repo.GetSourceAnyByURL(ctx, book.Origin); findErr == nil && found != nil && found.Header != "" {
-				var headers map[string]any
-				if json.Unmarshal([]byte(found.Header), &headers) == nil {
-					for k, v := range headers {
-						httpReq.Header.Set(k, fmt.Sprintf("%v", v))
-					}
-				}
-			}
-		}
-		// 登录态：登录类书源的漫画/音频资源同样需要 Cookie 与 loginHeader 才能取到。
-		if s.repo != nil {
-			state := s.newSourceState(ctx, book.Origin)
-			for k, v := range state.LoginHeaderMap() {
-				if !strings.EqualFold(k, "cookie") && httpReq.Header.Get(k) == "" {
-					httpReq.Header.Set(k, v)
-				}
-			}
-			if httpReq.Header.Get("Cookie") == "" {
-				if ck := state.CookieForRequest(rawURL); ck != "" {
-					httpReq.Header.Set("Cookie", ck)
-				}
-			}
-		}
-		// URL 尾部选项里的请求头：优先级最高（逐图声明，取图必需）。
-		optionCookie := ""
-		for k, v := range options {
-			if strings.EqualFold(k, "Cookie") {
-				optionCookie = v
-				continue
-			}
-			httpReq.Header.Set(k, v)
-		}
-		if optionCookie != "" {
-			// 与源 Cookie 合并时 options 优先（对应 legado AnalyzeUrl.setCookie 的临时 Cookie）。
-			if base := httpReq.Header.Get("Cookie"); base != "" {
-				httpReq.Header.Set("Cookie", rule.MergeCookie(base, optionCookie))
-			} else {
-				httpReq.Header.Set("Cookie", optionCookie)
-			}
-		}
-		// 默认 Referer 只能用「真正的 http(s) 书源地址」。
-		// legado 的 origin 对普通书源是 bookSourceUrl，但聚合类书源（如「光遇聚合」）
-		// 的 origin 是个显示名，拼出来的 Referer 非法，会被图床判定为盗链并
-		// 301 到一张「请到本网站阅读」的占位图 —— 表现为漫画每一页都是同一张提示图。
-		// 这种情况下宁可不发 Referer（实测不带 Referer 能拿到原图）；书源 header
-		// 里自己声明的 Referer 优先级更高，不受这里影响。
-		if httpReq.Header.Get("Referer") == "" {
-			if referer := sourceReferer(book.Origin); referer != "" {
-				httpReq.Header.Set("Referer", referer)
-			}
-		}
 		if rangeHeader != "" {
 			httpReq.Header.Set("Range", rangeHeader)
 		}
@@ -1942,12 +2171,14 @@ func (s *ReaderService) FetchMediaWithOptions(ctx context.Context, book *model.R
 		if err != nil {
 			return nil, err
 		}
-		resp, err := s.http.Do(httpReq)
+		// 媒体用无整体超时的 client：4MB 音频在跨境链路上常超过 30 秒，
+		// 用带整体超时的 client 会在读完 body 前被掐断（静默截断）。
+		resp, err := s.mediaClient().Do(httpReq)
 		if err != nil {
 			lastErr = err
 			continue
 		}
-		if attempt == mediaFetchAttempts || !retryableStatus(resp.StatusCode) {
+		if attempt == mediaFetchAttempts || !mediaRetryableStatus(resp.StatusCode) {
 			return resp, nil
 		}
 		// 可重试的状态码：读完并关闭响应体再试，避免连接泄漏。
@@ -2060,10 +2291,13 @@ func (s *ReaderService) getContentFrom(ctx context.Context, src *model.ReaderBoo
 			return nil, req.Unsupported
 		}
 		sess.applyHeaders(req, runner)
-		body, finalURL, _, err := sess.fetch(req)
+		body, finalURL, code, err := sess.fetch(req)
 		if err != nil {
 			return nil, err
 		}
+		if err := upstreamStatusError(code); err != nil {
+			return nil, err
+		}
 		lastFinalURL = finalURL
 		ar := sess.newAnalyzer("", 0, body, finalURL)
 		sess.applyBookContext(ar, bookURL, sess.book, "", 0)
@@ -2511,7 +2745,7 @@ func (s *ReaderService) fetchSourceResource(ctx context.Context, sourceURL, rawU
 			httpReq.Header.Set("Referer", referer)
 		}
 	}
-	return s.http.Do(httpReq)
+	return s.mediaClient().Do(httpReq)
 }
 
 // ─── 书架 ──────────────────────────────────────────────────────────────────
@@ -2528,7 +2762,7 @@ func (s *ReaderService) AddBook(ctx context.Context, userID string, origin Searc
 		BookURL:    origin.BookURL,
 		Name:       name,
 		Author:     author,
-		CoverURL:   normalizeCoverURL(coverURL),
+		CoverURL:   normalizeCoverURL(coverURL, origin.BookURL),
 		Type:       origin.OriginType,
 	}
 	if err := s.repo.CreateBook(ctx, book); err != nil {
@@ -2589,7 +2823,7 @@ func (s *ReaderService) SwitchOrigin(ctx context.Context, userID, bookID string,
 	if info != nil {
 		book.TocURL = strings.TrimSpace(info.TocURL)
 		if book.CoverURL == "" {
-			book.CoverURL = normalizeCoverURL(info.CoverURL)
+			book.CoverURL = normalizeCoverURL(info.CoverURL, target)
 		}
 		if info.LatestChapter != "" {
 			book.LatestChapterTitle = info.LatestChapter
@@ -3002,7 +3236,9 @@ func (s *ReaderService) DeleteReplaceRule(ctx context.Context, userID, id string
 // GetContentForBook 按书架书籍 + 章节序号取正文：
 // 解析书源 → 持久缓存（命中直接返回）→ 抓正文（单飞）→ 写缓存 →
 // 书源 replaceRegex → 用户替换净化规则 → 签名代理改写。
-func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID string, chapterIndex int) (*ChapterContent, error) {
+//
+// opts 为零值时行为与历史版本完全一致（媒体全部走服务端代理）。
+func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID string, chapterIndex int, opts ContentOptions) (*ChapterContent, error) {
 	book, err := s.repo.GetBook(ctx, bookID)
 	if err != nil {
 		return nil, err
@@ -3046,22 +3282,21 @@ func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID st
 	if out.Type == "text" {
 		out.Content = s.applyUserReplaceRules(ctx, userID, book.Name, out.Content)
 	}
-	// 音频/图片地址改写为签名代理（浏览器播放/展示无法带防盗链头）
-	for i, t := range out.Tracks {
-		out.Tracks[i] = s.ProxyURL(book.ID, t)
-	}
-	for i, img := range out.Images {
-		out.Images[i] = s.ProxyURL(book.ID, img)
-	}
-	// 文本型漫画源：正文里的 <img> 标签换成前端认识的 [img] 标记（同样走签名代理，
-	// 这样需要防盗链头的图片也能显示）。见 rewriteContentImageMarkers 的说明。
+	direct := s.mediaDirectFor(ctx, book.Origin, opts)
+	// 文本型漫画源：正文里的 <img> 标签换成前端认识的 [img] 标记。
+	// 默认仍走签名代理，这样需要防盗链头的图片也能显示（见
+	// rewriteContentImageMarkers 的说明）；直连时保留上游原始地址。
 	if out.Type == "text" && strings.Contains(out.Content, "<img") {
 		out.Content = rewriteContentImageMarkers(out.Content, ch.URL, func(u string) string {
+			if direct {
+				return u
+			}
 			return s.ProxyURL(book.ID, u)
 		})
 	}
 	// 整章都是 [img] 标记 → 这就是一章漫画，改成图片类型交给漫画阅读器。
 	// 若还按文本下发，前端会把它当文字按列分页，一屏只有一张图（双页铺开也无从谈起）。
+	// 必须早于 applyMediaURLs：转换出来的图片地址同样要参与代理/直连决策与请求头计算。
 	if out.Type == "text" {
 		if imgs, ok := imageMarkersOnly(out.Content); ok {
 			out.Type = "image"
@@ -3069,6 +3304,9 @@ func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID st
 			out.Content = ""
 		}
 	}
+	// 音频/图片地址改写：默认走签名代理（浏览器播放/展示无法带防盗链头）；
+	// 客户端显式请求直连且书源允许时，保留上游地址并下发所需请求头。
+	s.applyMediaURLs(ctx, book, out, direct)
 	return out, nil
 }
 
@@ -3154,6 +3392,9 @@ type ContentBatchItem struct {
 	// Cached 为 true 表示这次由持久缓存直接命中（未访问书源）。
 	Cached bool   `json:"cached"`
 	Error  string `json:"error,omitempty"`
+	// MediaDirect / MediaHeaders 同 ChapterContent：客户端直连时的地址与请求头。
+	MediaDirect  bool              `json:"media_direct,omitempty"`
+	MediaHeaders map[string]string `json:"media_headers,omitempty"`
 }
 
 // ContentBatchResult 批量取正文的汇总结果。
@@ -3172,7 +3413,7 @@ const contentBatchConcurrency = 4
 // GetContentBatch 批量取正文（对应 legado 的 CacheBook 离线缓存协议）。
 //
 // 单章失败不中断整批：失败项带 error，其余照常返回。已缓存的章节不访问书源。
-func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID string, indexes []int, applyReplace bool) (*ContentBatchResult, error) {
+func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID string, indexes []int, applyReplace bool, opts ContentOptions) (*ContentBatchResult, error) {
 	book, err := s.repo.GetBook(ctx, bookID)
 	if err != nil {
 		return nil, err
@@ -3208,7 +3449,7 @@ func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID stri
 				result.Items[pos] = ContentBatchItem{ChapterIndex: idx, Error: ctx.Err().Error()}
 				return
 			}
-			item, cached := s.loadBatchItem(ctx, userID, book, chapters[idx], applyReplace)
+			item, cached := s.loadBatchItem(ctx, userID, book, chapters[idx], applyReplace, opts)
 			result.Items[pos] = item
 			if item.Error != "" {
 				result.Stats.Failed++
@@ -3224,18 +3465,22 @@ func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID stri
 }
 
 // loadBatchItem 取单章（批量接口用）：先查缓存（不访问书源），再走完整链路。
-func (s *ReaderService) loadBatchItem(ctx context.Context, userID string, book *model.ReaderBook, ch model.ReaderChapter, applyReplace bool) (ContentBatchItem, bool) {
+func (s *ReaderService) loadBatchItem(ctx context.Context, userID string, book *model.ReaderBook, ch model.ReaderChapter, applyReplace bool, opts ContentOptions) (ContentBatchItem, bool) {
 	item := ContentBatchItem{ChapterIndex: ch.Index}
 	src, bs, loadErr := s.loadSourceFlexible(ctx, "", book.Origin)
 	cached := false
 	if loadErr == nil {
 		if out, ok := s.loadCachedContent(ctx, src, bs, book, ch, ""); ok {
+			// 缓存里存的是书源侧原始地址（改写前），命中后同样要按本次请求
+			// 决定代理/直连，否则缓存命中的章节会绕过媒体通道选择。
+			direct := s.mediaDirectFor(ctx, book.Origin, opts)
+			s.applyMediaURLs(ctx, book, out, direct)
 			item = batchItemFromContent(ch.Index, out, applyReplace, userID, book, s)
 			cached = true
 		}
 	}
 	if !cached {
-		out, err := s.GetContentForBook(ctx, userID, book.ID, ch.Index)
+		out, err := s.GetContentForBook(ctx, userID, book.ID, ch.Index, opts)
 		if err != nil {
 			item.Error = err.Error()
 			return item, false
@@ -3256,6 +3501,8 @@ func batchItemFromContent(index int, out *ChapterContent, applyReplace bool, use
 		ImageStyle:   out.ImageStyle,
 		IsHLS:        out.IsHLS,
 		Comments:     out.Comments,
+		MediaDirect:  out.MediaDirect,
+		MediaHeaders: out.MediaHeaders,
 	}
 	if applyReplace && out.Type == "text" && s != nil && book != nil {
 		item.Content = s.applyUserReplaceRules(context.Background(), userID, book.Name, item.Content)

internal/service/reader/reader_content_cache_test.go

@@ -123,7 +123,7 @@ func TestContentCacheHitAndPersist(t *testing.T) {
 	svc, srv, book := prepareCacheTestBook(t)
 	ctx := t.Context()
 
-	first, err := svc.GetContentForBook(ctx, "u1", book.ID, 0)
+	first, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("首次读取失败: %v", err)
 	}
@@ -134,7 +134,7 @@ func TestContentCacheHitAndPersist(t *testing.T) {
 		t.Fatalf("首次读取应访问书源 1 次，实际 %d", got)
 	}
 
-	second, err := svc.GetContentForBook(ctx, "u1", book.ID, 0)
+	second, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("二次读取失败: %v", err)
 	}
@@ -166,7 +166,7 @@ func TestContentCacheSurvivesTocRefresh(t *testing.T) {
 	svc, srv, book := prepareCacheTestBook(t)
 	ctx := t.Context()
 
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 1); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 1, ContentOptions{}); err != nil {
 		t.Fatalf("读取第 2 章失败: %v", err)
 	}
 
@@ -190,7 +190,7 @@ func TestContentCacheSurvivesTocRefresh(t *testing.T) {
 	newChapters, _ := svc.repo.ListChapters(ctx, book.ID)
 	svc.RemapContentCacheOnTocChange(ctx, book, oldChapters, newChapters)
 
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 1); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 1, ContentOptions{}); err != nil {
 		t.Fatalf("刷新后读取失败: %v", err)
 	}
 	if got := srv.count(2); got != 1 {
@@ -209,7 +209,7 @@ func TestContentCacheSingleFlight(t *testing.T) {
 		wg.Add(1)
 		go func(i int) {
 			defer wg.Done()
-			_, errs[i] = svc.GetContentForBook(ctx, "u1", book.ID, 0)
+			_, errs[i] = svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{})
 		}(i)
 	}
 	wg.Wait()
@@ -229,14 +229,14 @@ func TestContentBatchStatsAndFailureIsolation(t *testing.T) {
 	ctx := t.Context()
 
 	// 预热第 1 章（进缓存），第 2 章按失败处理。
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{}); err != nil {
 		t.Fatalf("预热失败: %v", err)
 	}
 	srv.mu.Lock()
 	srv.failOn[2] = true
 	srv.mu.Unlock()
 
-	result, err := svc.GetContentBatch(ctx, "u1", book.ID, []int{0, 1, 2}, false)
+	result, err := svc.GetContentBatch(ctx, "u1", book.ID, []int{0, 1, 2}, false, ContentOptions{})
 	if err != nil {
 		t.Fatalf("批量读取失败: %v", err)
 	}
@@ -262,14 +262,14 @@ func TestContentBatchStatsAndFailureIsolation(t *testing.T) {
 	srv.mu.Lock()
 	srv.failOn[2] = false
 	srv.mu.Unlock()
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 1); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 1, ContentOptions{}); err != nil {
 		t.Fatalf("恢复后读取第 2 章失败: %v", err)
 	}
 	if got := srv.count(2); got != 2 {
 		t.Fatalf("失败章不应进缓存，恢复后应重抓（2 次），实际 %d", got)
 	}
 	// 越界/卷章节被忽略。
-	if got, err := svc.GetContentBatch(ctx, "u1", book.ID, []int{-1, 99}, false); err != nil || len(got.Items) != 0 {
+	if got, err := svc.GetContentBatch(ctx, "u1", book.ID, []int{-1, 99}, false, ContentOptions{}); err != nil || len(got.Items) != 0 {
 		t.Fatalf("越界索引应被忽略: items=%d err=%v", len(got.Items), err)
 	}
 }
@@ -279,7 +279,7 @@ func TestContentCacheInvalidatedOnSourceUpdate(t *testing.T) {
 	svc, srv, book := prepareCacheTestBook(t)
 	ctx := t.Context()
 
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{}); err != nil {
 		t.Fatalf("首次读取失败: %v", err)
 	}
 	// 重新导入同一书源（RawJSON 变化）→ 指纹变化。
@@ -287,7 +287,7 @@ func TestContentCacheInvalidatedOnSourceUpdate(t *testing.T) {
 	if _, err := svc.ImportSources(ctx, "u1", updated); err != nil {
 		t.Fatalf("更新书源失败: %v", err)
 	}
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{}); err != nil {
 		t.Fatalf("更新后读取失败: %v", err)
 	}
 	if got := srv.count(1); got != 2 {
@@ -299,7 +299,7 @@ func TestContentCacheInvalidatedOnSourceUpdate(t *testing.T) {
 func TestContentCacheClearedOnRemoveBook(t *testing.T) {
 	svc, _, book := prepareCacheTestBook(t)
 	ctx := t.Context()
-	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0); err != nil {
+	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{}); err != nil {
 		t.Fatalf("读取失败: %v", err)
 	}
 	sourceID := svc.contentSourceID(ctx, nil, book)
@@ -395,7 +395,7 @@ func TestContentCacheWithoutCacheDir(t *testing.T) {
 	if err := svc.SaveChapters(ctx, book.ID, []ChapterInput{{Index: 0, Title: "第 1 章", URL: srv.URL + "/book/1/c1.html"}}); err != nil {
 		t.Fatal(err)
 	}
-	out, err := svc.GetContentForBook(ctx, "u1", book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, "u1", book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("无缓存目录时读取失败: %v", err)
 	}

internal/service/reader/reader_test.go

@@ -220,7 +220,7 @@ func TestEndToEndSourceChain(t *testing.T) {
 func TestGetContentForBookEmptyContentFails(t *testing.T) {
 	svc, bookID := setupTextChapterBook(t, "")
 
-	_, err := svc.GetContentForBook(t.Context(), "u1", bookID, 0)
+	_, err := svc.GetContentForBook(t.Context(), "u1", bookID, 0, ContentOptions{})
 	if err == nil {
 		t.Fatal("空正文应当报错，实际当成功下发了")
 	}

internal/service/reader/upstream_retry_test.go

@@ -0,0 +1,82 @@
+package reader
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// 上游限流（HTTP 429）在免费/低配后端上是常态。书源没声明 retry 时，
+// GET 也会自动补一次：第一次 429、第二次正常时，详情必须能拿到数据。
+func TestGetBookInfoRetriesUpstream429(t *testing.T) {
+	upstream := e2eServer()
+	defer upstream.Close()
+
+	var mu sync.Mutex
+	hits := map[string]int{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		hits[r.URL.Path]++
+		n := hits[r.URL.Path]
+		mu.Unlock()
+		if n == 1 {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusTooManyRequests)
+			_, _ = w.Write([]byte(`{"code":"projectConcurrencyLimitExceeded","message":"当前访问人数较多"}`))
+			return
+		}
+		resp, err := http.Get(upstream.URL + r.URL.RequestURI())
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadGateway)
+			return
+		}
+		defer resp.Body.Close()
+		w.Header().Set("Content-Type", resp.Header.Get("Content-Type"))
+		w.WriteHeader(resp.StatusCode)
+		buf := make([]byte, 32*1024)
+		for {
+			n, err := resp.Body.Read(buf)
+			if n > 0 {
+				_, _ = w.Write(buf[:n])
+			}
+			if err != nil {
+				return
+			}
+		}
+	}))
+	defer srv.Close()
+
+	svc, _ := newLoginTestService(t)
+	sourceID := importTestSource(t, svc, e2eSourceJSON(srv.URL), srv.URL)
+
+	info, err := svc.GetBookInfo(t.Context(), sourceID, "", srv.URL+"/book/1")
+	if err != nil {
+		t.Fatalf("第一次 429、重试后应成功: %v", err)
+	}
+	if info.Name == "" {
+		t.Fatalf("重试后详情应有书名，实际为空")
+	}
+}
+
+// 持续限流时必须报错，而不是把 429 的响应体解析成「空目录 / 0 章」。
+func TestGetTocReportsUpstream429(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusTooManyRequests)
+		_, _ = w.Write([]byte(`{"code":"projectConcurrencyLimitExceeded","message":"当前访问人数较多"}`))
+	}))
+	defer srv.Close()
+
+	svc, _ := newLoginTestService(t)
+	sourceID := importTestSource(t, svc, e2eSourceJSON(srv.URL), srv.URL)
+
+	_, err := svc.GetToc(t.Context(), "u1", sourceID, srv.URL, srv.URL+"/book/1", srv.URL+"/book/1")
+	if err == nil {
+		t.Fatalf("持续 429 时应返回错误，而不是空目录")
+	}
+	if !strings.Contains(err.Error(), "429") {
+		t.Fatalf("错误信息应包含 429，实际: %v", err)
+	}
+}

internal/service/runtime_settings.go

@@ -126,13 +126,6 @@ func ApplyRuntimeSetting(cfg *config.Config, key, value string) {
 			}
 			cfg.Cache.ImagesOriginalsMaxSizeMB = n
 		}
-	case "cache.images_originals_ttl_hours":
-		if n, err := strconv.Atoi(value); err == nil {
-			if n < 0 {
-				n = 0
-			}
-			cfg.Cache.ImagesOriginalsTTLHours = n
-		}
 	case "cache.memory_max_size_mb":
 		n := config.DefaultCacheMemoryMaxSizeMB
 		if value != "" {

internal/service/scheduler.go

@@ -8,6 +8,9 @@
 //	organize_source   opt-in        — organize the configured staging folder.
 //	transcode_cleanup every 24 h   — purge HLS transcode artefacts
 //	                                  older than 24 h.
+//	cache_cleanup     every 1 h    — enforce the global disk-cache capacity
+//	                                  (hls → images → library-covers; reader-audio
+//	                                  has its own 1 GB eviction on write).
 //	segment_prewarm   every 6 h    — fill IntroDB skip segments for queryable media.
 //
 // Each job runs at most once at a time (an in-flight run blocks the
@@ -41,7 +44,7 @@ type SchedulerService struct {
 	cacheDir         string
 	now              func() time.Time
 
-	imagesPolicyProvider func() ImageCachePolicy
+	cachePolicyProvider func() CacheCleanupPolicy
 
 	// readerContentCleaner 阅读正文缓存的清理钩子（由阅读模块注入）。
 	readerContentCleaner func(context.Context)
@@ -79,22 +82,24 @@ func (s *SchedulerService) SetExpiryWatcher(watcher *TelegramExpiryWatcher) {
 	s.expiryWatcher = watcher
 }
 
-// ImageCachePolicy 是一次图片缓存清理要用的策略（全部为 0 表示不做任何清理）。
-type ImageCachePolicy struct {
+// CacheCleanupPolicy 是一次全缓存容量清理要用的策略（全部为 0 表示不做任何清理）。
+// TotalBytes 是 hls / images / library-covers 三个池的总容量上限；OriginalsBytes
+// 是 images 原图池的独立子配额。reader-audio 由自身 1GB 配额管理，不在此列。
+// 只有容量配额，没有保留时长：淘汰只看占用，不按文件年龄删除。
+type CacheCleanupPolicy struct {
 	TotalBytes     int64
 	OriginalsBytes int64
-	OriginalsAge   time.Duration
 }
 
-func (s *SchedulerService) SetImageCachePolicyProvider(fn func() ImageCachePolicy) {
-	s.imagesPolicyProvider = fn
+func (s *SchedulerService) SetCacheCleanupPolicyProvider(fn func() CacheCleanupPolicy) {
+	s.cachePolicyProvider = fn
 }
 
-func (s *SchedulerService) imageCachePolicy() ImageCachePolicy {
-	if s.imagesPolicyProvider != nil {
-		return s.imagesPolicyProvider()
+func (s *SchedulerService) cacheCleanupPolicy() CacheCleanupPolicy {
+	if s.cachePolicyProvider != nil {
+		return s.cachePolicyProvider()
 	}
-	return ImageCachePolicy{}
+	return CacheCleanupPolicy{}
 }
 
 // SetReaderContentCleaner 注入阅读正文缓存的清理钩子（TTL 过期 + 容量 LRU）。
@@ -166,9 +171,9 @@ func (s *SchedulerService) Start(ctx context.Context) {
 			run:      s.jobCleanTranscodeCache,
 		},
 		{
-			name:     "image_cache_cleanup",
+			name:     "cache_cleanup",
 			interval: 1 * time.Hour,
-			run:      s.jobCleanImageCache,
+			run:      s.jobCleanCache,
 		},
 	}
 	// 阅读正文缓存清理只在注入钩子后注册（见 SetReaderContentCleaner）。

internal/service/scheduler_local_jobs.go

@@ -299,30 +299,33 @@ func (s *SchedulerService) jobCleanTranscodeCache(ctx context.Context) error {
 	return walkAndPrune(s.cacheDir+"/hls", cutoff)
 }
 
-// jobCleanImageCache prunes the image proxy cache: 原图按保留时长与独立配额
-// 优先淘汰，总量超限时再淘汰派生成品。
-func (s *SchedulerService) jobCleanImageCache(ctx context.Context) error {
+// jobCleanCache enforces the global disk-cache capacity: when the total size of
+// hls + images + library-covers exceeds the configured limit, the pools are
+// evicted strictly in that order (oldest file first within each pool) until
+// usage falls back to 80% of the limit. reader-audio is not part of the total;
+// it has its own 1 GB eviction on write. The images original sub-quota is
+// enforced afterwards as an independent constraint.
+func (s *SchedulerService) jobCleanCache(ctx context.Context) error {
 	if s.cacheDir == "" {
 		return nil
 	}
-	policy := s.imageCachePolicy()
-	if policy.TotalBytes <= 0 && policy.OriginalsBytes <= 0 && policy.OriginalsAge <= 0 {
+	policy := s.cacheCleanupPolicy()
+	if policy.TotalBytes <= 0 && policy.OriginalsBytes <= 0 {
 		return nil
 	}
-	imagesDir := filepath.Join(s.cacheDir, "images")
-	pools := ImageCachePools(imagesDir, policy.OriginalsBytes, policy.OriginalsAge)
-	res, err := PruneImageCachePools(pools, policy.TotalBytes)
+	res, err := PruneCache(s.cacheDir, policy.TotalBytes, policy.OriginalsBytes)
 	if err != nil {
 		if s.log != nil {
-			s.log.Warn("scheduled image cache cleanup failed", zap.Error(err))
+			s.log.Warn("scheduled cache cleanup failed", zap.Error(err))
 		}
 		return err
 	}
 	if res.DeletedFiles > 0 && s.log != nil {
-		s.log.Info("scheduled image cache cleanup completed",
+		s.log.Info("scheduled cache cleanup completed",
 			zap.Int("deleted_files", res.DeletedFiles),
 			zap.Int64("freed_bytes", res.FreedBytes),
 			zap.Int64("remaining_bytes", res.RemainingBytes),
+			zap.Any("freed_by_pool", res.FreedByPool),
 		)
 	}
 	return nil

internal/service/segment_provider.go

@@ -0,0 +1,46 @@
+// Package service — 片头/片尾片段的外部提供方抽象。
+//
+// 目前有三个社区库可用，它们对「媒体身份」的要求各不相同：
+//
+//	TheIntroDB  TMDb id（服务端自己映射到 TVDB）
+//	IntroDB     只有 IMDb id（用 is_movie 区分电影/剧集）
+//	TODb        TMDb id + 平台类型（tmdb_id_tv / tmdb_id_movie），秒级时间轴
+//
+// 播放链路只关心「一段可跳过的区间」，所以这里把三者收敛成同一个
+// SegmentProvider 接口和 SegmentQuery 入参，上层按设置项挑选其一。
+package service
+
+import "context"
+
+// SegmentSpan 是一个已解析的可跳过区间，单位为毫秒。
+//
+// EndMs == 0 是哨兵值，表示「一直到片尾」：只有片尾（credits/preview）可能
+// 出现这种区间，由客户端结合媒体总时长补齐。片头/回顾不允许开放区间，
+// 拿不到结束点就整段丢弃——否则会得到一个覆盖全片的区间。
+type SegmentSpan struct {
+	Kind    string
+	StartMs int64
+	EndMs   int64
+}
+
+// IntroDBSpan 保留旧名字，避免既有调用方和测试大范围改名。
+type IntroDBSpan = SegmentSpan
+
+// SegmentQuery 是一次片段查询的身份参数。不同提供方按需取用其中一部分。
+type SegmentQuery struct {
+	TMDbID  int
+	IMDbID  string
+	Season  int
+	Episode int
+	// IsMovie 为 true 时 Season/Episode 无意义。
+	IsMovie bool
+}
+
+// SegmentProvider 是一个外部片段数据源。
+type SegmentProvider interface {
+	// Source 返回写入 media_segments.source 的标识，也是缓存账本的键。
+	Source() string
+	// FetchSegments 返回该媒体已知的可跳过区间。查不到不是错误（返回空切片），
+	// 只有请求本身失败才返回 error——调用方据此决定是否保留旧缓存。
+	FetchSegments(ctx context.Context, q SegmentQuery) ([]SegmentSpan, error)
+}

internal/service/segment_providers_test.go

@@ -0,0 +1,150 @@
+package service
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+// 官方规范（theintrodb.org/openapi.yaml，SegmentTimestamp）对「没有数值」有两种
+// 写法，含义完全不同：end_ms: null = 一直到片尾；end_ms: 0 = 这一段不存在。
+// 实测约三分之一的剧集会返回 {"start_ms":null,"end_ms":0} 的 intro 占位。
+const (
+	// 真实返回：intro 是占位、credits 到片尾。
+	introDBNoSegmentPayload = `{"tvdb_id":73762,"type":"tv","season":1,"episode":1,"intro":[{"start_ms":null,"end_ms":0}],"credits":[{"start_ms":2574000,"end_ms":null}]}`
+	// 整集都是占位：recap/credits 都是 (0,0)。
+	introDBAllPlaceholderPayload = `{"tvdb_id":375921,"type":"tv","season":1,"episode":1,"recap":[{"start_ms":0,"end_ms":0}],"credits":[{"start_ms":0,"end_ms":0}]}`
+)
+
+// 把 end_ms: 0 当成「到片尾」会让 intro 变成 [0, 片长]，整集都是片头：
+// 一开播就弹跳过按钮，开了自动跳过直接跳到片尾。
+func TestParseIntroDBResponseDropsZeroEndPlaceholders(t *testing.T) {
+	spans, err := parseIntroDBResponse([]byte(introDBNoSegmentPayload))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(spans) != 1 {
+		t.Fatalf("spans = %#v, want only the credits range", spans)
+	}
+	if spans[0].Kind != "credits" || spans[0].StartMs != 2_574_000 || spans[0].EndMs != 0 {
+		t.Fatalf("credits span = %#v, want start 2574000 and open end", spans[0])
+	}
+}
+
+func TestParseIntroDBResponseDropsAllPlaceholderSegments(t *testing.T) {
+	spans, err := parseIntroDBResponse([]byte(introDBAllPlaceholderPayload))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(spans) != 0 {
+		t.Fatalf("spans = %#v, want none for all-placeholder payload", spans)
+	}
+}
+
+// 片头/回顾不允许开放结束点：即使数据源给了 null，也不能补齐成「一直到片尾」。
+func TestParseIntroDBResponseRejectsOpenEndedIntro(t *testing.T) {
+	body := `{"tvdb_id":1,"type":"tv","season":1,"episode":1,"intro":[{"start_ms":1000,"end_ms":null}]}`
+	spans, err := parseIntroDBResponse([]byte(body))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(spans) != 0 {
+		t.Fatalf("spans = %#v, want an open-ended intro to be dropped", spans)
+	}
+}
+
+// IntroDB 的响应把区间给成对象而不是数组，且片尾字段叫 outro。
+func TestParseIntroDBAppResponseMapsKinds(t *testing.T) {
+	body := `{"imdb_id":"tt0903747","media_type":"tv","is_movie":false,"season":1,"episode":1,
+		"intro":{"start_ms":437000,"end_ms":531000},
+		"recap":null,
+		"outro":{"start_ms":3431000,"end_ms":3500000},
+		"post_credits":{"start_ms":3600000,"end_ms":3610000}}`
+	spans, err := parseIntroDBAppResponse([]byte(body))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	want := []struct {
+		kind     string
+		start    int64
+		end      int64
+	}{
+		{"intro", 437_000, 531_000},
+		{"credits", 3_431_000, 3_500_000},
+		{"preview", 3_600_000, 3_610_000},
+	}
+	if len(spans) != len(want) {
+		t.Fatalf("spans = %#v, want %d", spans, len(want))
+	}
+	for i, w := range want {
+		if spans[i].Kind != w.kind || spans[i].StartMs != w.start || spans[i].EndMs != w.end {
+			t.Fatalf("span[%d] = %#v, want %s %d-%d", i, spans[i], w.kind, w.start, w.end)
+		}
+	}
+}
+
+// IntroDB 只认 IMDb id：没有 IMDb id 时不能退化成用 TMDb id 拼请求，
+// 那只会在服务端拿到 400，被误记成「查询失败」而保留旧缓存。
+func TestIntroDBAppFetchSkipsWithoutIMDbID(t *testing.T) {
+	var calls int
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		calls++
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	svc := NewIntroDBAppService(zap.NewNop()).SetBaseURL(server.URL)
+	spans, err := svc.FetchSegments(t.Context(), SegmentQuery{TMDbID: 1396, Season: 1, Episode: 1})
+	if err != nil {
+		t.Fatalf("fetch: %v", err)
+	}
+	if len(spans) != 0 || calls != 0 {
+		t.Fatalf("spans = %#v calls = %d, want no request without an imdb id", spans, calls)
+	}
+}
+
+func TestIntroDBAppFetchSendsIMDbAndSeasonEpisode(t *testing.T) {
+	var gotQuery string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotQuery = r.URL.RawQuery
+		_, _ = w.Write([]byte(`{"imdb_id":"tt0903747","media_type":"tv","is_movie":false,
+			"intro":{"start_ms":1000,"end_ms":2000}}`))
+	}))
+	defer server.Close()
+
+	svc := NewIntroDBAppService(zap.NewNop()).SetBaseURL(server.URL)
+	if _, err := svc.FetchSegments(t.Context(), SegmentQuery{
+		IMDbID: "tt0903747", Season: 2, Episode: 3,
+	}); err != nil {
+		t.Fatalf("fetch: %v", err)
+	}
+	for _, want := range []string{"imdb_id=tt0903747", "season=2", "episode=3"} {
+		if !strings.Contains(gotQuery, want) {
+			t.Fatalf("query = %q, want it to contain %q", gotQuery, want)
+		}
+	}
+}
+
+// 电影要用 is_movie，且不能带季集参数。
+func TestIntroDBAppFetchUsesIsMovieForMovies(t *testing.T) {
+	var gotQuery string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotQuery = r.URL.RawQuery
+		_, _ = w.Write([]byte(`{"imdb_id":"tt1375666","is_movie":true}`))
+	}))
+	defer server.Close()
+
+	svc := NewIntroDBAppService(zap.NewNop()).SetBaseURL(server.URL)
+	if _, err := svc.FetchSegments(t.Context(), SegmentQuery{IMDbID: "tt1375666", IsMovie: true}); err != nil {
+		t.Fatalf("fetch: %v", err)
+	}
+	if !strings.Contains(gotQuery, "is_movie=true") {
+		t.Fatalf("query = %q, want is_movie=true", gotQuery)
+	}
+	if strings.Contains(gotQuery, "season=") || strings.Contains(gotQuery, "episode=") {
+		t.Fatalf("query = %q, want no season/episode for a movie", gotQuery)
+	}
+}

internal/service/segment_source_test.go

@@ -0,0 +1,188 @@
+package service
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// stubIMDbResolver 返回固定 IMDb id，用于验证 IntroDB 的 id 解析链路。
+type stubIMDbResolver struct {
+	id    string
+	calls int32
+}
+
+func (s *stubIMDbResolver) ResolveIMDbID(_ context.Context, _ int, _ bool) (string, error) {
+	atomic.AddInt32(&s.calls, 1)
+	return s.id, nil
+}
+
+func TestSegmentSourceOffSkipsExternalLookup(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	var calls int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		_, _ = w.Write([]byte(introDBMoviePayload))
+	}))
+	defer server.Close()
+
+	svc := NewMediaSegmentService(zap.NewNop(), repos).
+		SetIntroDB(NewIntroDBService(zap.NewNop()).SetBaseURL(server.URL))
+	if err := repos.Setting.Set(t.Context(), SegmentSourceSettingKey, SegmentSourceOff); err != nil {
+		t.Fatal(err)
+	}
+	m := &model.Media{Base: model.Base{ID: "mv-off"}, Path: "/movies/off.mkv", TMDbID: 27205}
+	if err := repos.DB.Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := svc.ListForPlayback(t.Context(), m)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(rows) != 0 || atomic.LoadInt32(&calls) != 0 {
+		t.Fatalf("rows = %#v calls = %d, want no lookup when the source is off", rows, calls)
+	}
+}
+
+// 默认（未配置设置项）必须保持历史行为：用 TheIntroDB。
+func TestSegmentSourceDefaultsToTheIntroDB(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	var calls int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		_, _ = w.Write([]byte(introDBMoviePayload))
+	}))
+	defer server.Close()
+
+	svc := NewMediaSegmentService(zap.NewNop(), repos).
+		SetIntroDB(NewIntroDBService(zap.NewNop()).SetBaseURL(server.URL))
+	m := &model.Media{Base: model.Base{ID: "mv-default"}, Path: "/movies/default.mkv", TMDbID: 27205}
+	if err := repos.DB.Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := svc.ListForPlayback(t.Context(), m)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(rows) != 1 || atomic.LoadInt32(&calls) != 1 {
+		t.Fatalf("rows = %#v calls = %d, want the default provider to run", rows, calls)
+	}
+}
+
+// 切到 TODb 后，TheIntroDB 不应再被调用，写入的 source 也要跟着变。
+func TestSegmentSourceSwitchesToTODb(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	var introCalls, todbCalls int32
+	introServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&introCalls, 1)
+		_, _ = w.Write([]byte(introDBMoviePayload))
+	}))
+	defer introServer.Close()
+	todbServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&todbCalls, 1)
+		_, _ = w.Write([]byte(`{"items":[{"marker":[{"marker_type":"intro","time_start":5,"time_end":30}]}]}`))
+	}))
+	defer todbServer.Close()
+
+	svc := NewMediaSegmentService(zap.NewNop(), repos).
+		SetIntroDB(NewIntroDBService(zap.NewNop()).SetBaseURL(introServer.URL)).
+		SetTODb(NewTODbService(zap.NewNop()).SetBaseURL(todbServer.URL))
+	if err := repos.Setting.Set(t.Context(), SegmentSourceSettingKey, TODbSource); err != nil {
+		t.Fatal(err)
+	}
+	m := &model.Media{Base: model.Base{ID: "mv-todb"}, Path: "/movies/todb.mkv", TMDbID: 27205}
+	if err := repos.DB.Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := svc.ListForPlayback(t.Context(), m)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if atomic.LoadInt32(&introCalls) != 0 {
+		t.Fatalf("theintrodb was called %d times, want 0 after switching source", introCalls)
+	}
+	if atomic.LoadInt32(&todbCalls) != 1 {
+		t.Fatalf("todb calls = %d, want 1", todbCalls)
+	}
+	if len(rows) != 1 || rows[0].Source != TODbSource {
+		t.Fatalf("rows = %#v, want one row tagged %s", rows, TODbSource)
+	}
+	if rows[0].StartMs != 5000 || rows[0].EndMs != 30000 {
+		t.Fatalf("row = %#v, want 5000-30000ms", rows[0])
+	}
+}
+
+// 未知的源标识（降级回滚残留）要退回默认源，而不是静默失效。
+func TestSegmentSourceFallsBackForUnknownValue(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	var calls int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		_, _ = w.Write([]byte(introDBMoviePayload))
+	}))
+	defer server.Close()
+
+	svc := NewMediaSegmentService(zap.NewNop(), repos).
+		SetIntroDB(NewIntroDBService(zap.NewNop()).SetBaseURL(server.URL))
+	if err := repos.Setting.Set(t.Context(), SegmentSourceSettingKey, "no-such-source"); err != nil {
+		t.Fatal(err)
+	}
+	m := &model.Media{Base: model.Base{ID: "mv-unknown"}, Path: "/movies/u.mkv", TMDbID: 27205}
+	if err := repos.DB.Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.ListForPlayback(t.Context(), m); err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if atomic.LoadInt32(&calls) != 1 {
+		t.Fatalf("calls = %d, want the default provider to still run", calls)
+	}
+}
+
+// IntroDB 需要 IMDb id；解析不出来时必须跳过请求，且不能写负缓存
+// （否则元数据补齐之后也永远不会再查）。
+func TestSegmentIntroDBSkipsWhenIMDbUnavailable(t *testing.T) {
+	repos := repository.New(newServiceTestDB(t))
+	var calls int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		_, _ = w.Write([]byte(`{}`))
+	}))
+	defer server.Close()
+
+	svc := NewMediaSegmentService(zap.NewNop(), repos).
+		SetIntroDBApp(NewIntroDBAppService(zap.NewNop()).SetBaseURL(server.URL)).
+		SetIMDbResolver(&stubIMDbResolver{id: ""})
+	if err := repos.Setting.Set(t.Context(), SegmentSourceSettingKey, IntroDBAppSource); err != nil {
+		t.Fatal(err)
+	}
+	m := &model.Media{Base: model.Base{ID: "mv-noimdb"}, Path: "/movies/noimdb.mkv", TMDbID: 27205}
+	if err := repos.DB.Create(m).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := svc.ListForPlayback(t.Context(), m)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(rows) != 0 || atomic.LoadInt32(&calls) != 0 {
+		t.Fatalf("rows = %#v calls = %d, want no request without an imdb id", rows, calls)
+	}
+	ledger, err := repos.MediaSegment.GetFetch(t.Context(), "mv-noimdb", IntroDBAppSource)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ledger != nil {
+		t.Fatalf("ledger = %#v, want no negative cache entry", ledger)
+	}
+}

internal/service/service_builder.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"strings"
-	"time"
 
 	"go.uber.org/zap"
 
@@ -135,8 +134,14 @@ func (b *serviceContainerBuilder) initContentServices() {
 	b.c.Media = NewMediaService(b.cfg, b.log, b.repos).SetRuntimeCache(b.c.Cache)
 	b.c.Stream = NewStreamService(b.cfg, b.log, b.repos, b.c.Transcoder)
 	b.c.Playback = NewPlaybackService(b.log, b.repos).SetEmbyRemote(b.c.EmbyRemote)
-	// 片头/片尾片段：播放时按需向 TheIntroDB 补齐并落库，供下次直接命中。
-	b.c.Segments = NewMediaSegmentService(b.log, b.repos).SetIntroDB(NewIntroDBService(b.log))
+	// 片头/片尾片段：播放时按需向社区库补齐并落库，供下次直接命中。
+	// 三个源都注册，具体用哪个由设置项 segment.source 决定（默认 theintrodb）。
+	b.c.Segments = NewMediaSegmentService(b.log, b.repos).
+		SetIntroDB(NewIntroDBService(b.log)).
+		SetIntroDBApp(NewIntroDBAppService(b.log)).
+		SetTODb(NewTODbService(b.log)).
+		// IntroDB 只认 IMDb id，需要经 TMDb 的 external_ids 解析。
+		SetIMDbResolver(b.c.TMDb)
 	b.c.Subtitle = NewSubtitleService(b.cfg, b.log, b.repos)
 	b.c.Profile = NewProfileService(b.log, b.repos)
 	b.c.Audit = NewAuditService(b.log, b.repos)
@@ -212,19 +217,16 @@ func (b *serviceContainerBuilder) initAccessAndStorageServices() {
 	b.c.Scheduler.SetBackupService(b.c.Backup)
 	b.c.Scheduler.SetOrganizePipeline(b.c.OrganizePipeline)
 	b.c.Scheduler.SetSegments(b.c.Segments)
-	b.c.Scheduler.SetImageCachePolicyProvider(func() ImageCachePolicy {
+	b.c.Scheduler.SetCacheCleanupPolicyProvider(func() CacheCleanupPolicy {
 		if b.cfg == nil {
-			return ImageCachePolicy{}
+			return CacheCleanupPolicy{}
 		}
-		policy := ImageCachePolicy{
+		policy := CacheCleanupPolicy{
 			TotalBytes: int64(b.cfg.Cache.ImagesMaxSizeMB) * 1024 * 1024,
 		}
 		if b.cfg.Cache.ImagesOriginalsMaxSizeMB > 0 {
 			policy.OriginalsBytes = int64(b.cfg.Cache.ImagesOriginalsMaxSizeMB) * 1024 * 1024
 		}
-		if b.cfg.Cache.ImagesOriginalsTTLHours > 0 {
-			policy.OriginalsAge = time.Duration(b.cfg.Cache.ImagesOriginalsTTLHours) * time.Hour
-		}
 		return policy
 	})
 	// 阅读正文缓存清理：由阅读模块自己按 TTL + 容量 LRU 淘汰（见 reader_content_cache.go）。

internal/service/tmdb.go

@@ -20,6 +20,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"net/url"
+	"strings"
 	"time"
 
 	"go.uber.org/zap"
@@ -133,3 +135,34 @@ func (t *TMDbProvider) getJSON(ctx context.Context, url string, out any) error {
 	}
 	return json.NewDecoder(resp.Body).Decode(out)
 }
+
+// ResolveIMDbID 用 TMDb 的 external_ids 端点把 TMDb 条目解析成 IMDb id。
+//
+// 这是为只认 IMDb id 的片段源（IntroDB）准备的。结果不做本地缓存：TMDb 的
+// external_ids 响应很小，而片段查询本身已经有 30 天/24 小时的正负缓存兜底，
+// 再叠一层只会引入失效问题。
+//
+// TMDb 未配置或上游不可达时返回空字符串与 error，调用方据此跳过该源，
+// 而不是把所有媒体都记成「查不到」。
+func (t *TMDbProvider) ResolveIMDbID(ctx context.Context, tmdbID int, isMovie bool) (string, error) {
+	if t == nil || t.cfg == nil || tmdbID <= 0 {
+		return "", nil
+	}
+	apiKey := t.resolveAPIKey(ctx)
+	if apiKey == "" {
+		return "", nil
+	}
+	mediaType := "tv"
+	if isMovie {
+		mediaType = "movie"
+	}
+	u := t.resolveBaseURL(ctx) + "/" + mediaType + "/" + fmt.Sprint(tmdbID) +
+		"/external_ids?api_key=" + url.QueryEscape(apiKey)
+	var r struct {
+		IMDbID string `json:"imdb_id"`
+	}
+	if err := t.getJSON(ctx, u, &r); err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(r.IMDbID), nil
+}

internal/service/todb.go

@@ -0,0 +1,213 @@
+// Package service — TODb (TheOtherDB) segment client.
+//
+// TODb 的播放资料库按「片源」组织：同一个 TMDB 条目可能有爱奇艺、腾讯等多个
+// 版本的 marker，每个版本自带 version_runtime（该片源的时长）。因此它的响应是
+// 一个 items 数组，而不是单一区间集合。
+//
+// 接口是 POST + JSON body（GET 会返回 405），平台用 platform_type 表达：
+//
+//	tmdb_id_tv     + season_number / episode_number
+//	tmdb_id_movie  无季集
+//
+// marker 的时间轴是**秒**（time_start / time_end），不是毫秒。
+package service
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+// TODbBaseURL 是公开只读端点。
+const TODbBaseURL = "https://playback.theotherdb.org/api/metadata"
+
+// TODbSource 写入 media_segments.source。
+const TODbSource = "todb"
+
+const (
+	todbTimeout     = 10 * time.Second
+	todbMaxBodySize = 1 << 20
+	// todbPageSize 一次取多少条版本记录。社区库大多数条目只有一个片源，
+	// 但同一部剧的各平台版本可能都有人标，取多一点可以避免漏掉匹配时长的那个。
+	todbPageSize = 10
+)
+
+// todbRequest 是 POST /api/metadata 的请求体。
+type todbRequest struct {
+	PlatformType    string   `json:"platform_type"`
+	PlatformValue   string   `json:"platform_value"`
+	SeasonNumber    int      `json:"season_number,omitempty"`
+	EpisodeNumber   int      `json:"episode_number,omitempty"`
+	Includes        []string `json:"includes"`
+	Page            int      `json:"page"`
+	PageSize        int      `json:"page_size"`
+}
+
+// todbMarker 是单个标记点。time_start/time_end 单位是秒。
+type todbMarker struct {
+	MarkerType string   `json:"marker_type"`
+	TimeStart  *float64 `json:"time_start"`
+	TimeEnd    *float64 `json:"time_end"`
+}
+
+// todbItem 是一个片源版本及其 marker。
+type todbItem struct {
+	VersionID      int          `json:"version_id"`
+	VersionName    string       `json:"version_name"`
+	VersionRuntime *int         `json:"version_runtime"`
+	VideoType      string       `json:"video_type"`
+	Marker         []todbMarker `json:"marker"`
+}
+
+type todbResponse struct {
+	Page     int        `json:"page"`
+	PageSize int        `json:"page_size"`
+	HasMore  bool       `json:"has_more"`
+	Items    []todbItem `json:"items"`
+}
+
+// TODbService 查询 TODb 的片段数据。
+type TODbService struct {
+	log        *zap.Logger
+	client     *http.Client
+	baseURL    string
+	pageSize   int
+}
+
+// NewTODbService is the constructor.
+func NewTODbService(log *zap.Logger) *TODbService {
+	return &TODbService{
+		log:      log,
+		client:   NewExternalHTTPClient(todbTimeout),
+		baseURL:  TODbBaseURL,
+		pageSize: todbPageSize,
+	}
+}
+
+// SetBaseURL overrides the API endpoint (tests, mirrors).
+func (s *TODbService) SetBaseURL(base string) *TODbService {
+	if s != nil && strings.TrimSpace(base) != "" {
+		s.baseURL = strings.TrimSpace(base)
+	}
+	return s
+}
+
+// Source implements SegmentProvider.
+func (s *TODbService) Source() string { return TODbSource }
+
+// FetchSegments implements SegmentProvider.
+//
+// 返回时会把多个版本的 marker 合并：同 kind 取第一个出现的区间。TODb 的片源
+// 时长各不相同，严格按 version_runtime 匹配当前媒体需要可靠的总时长，而片段
+// 查询经常跑在时长还不知道的时候（STRM 媒体），所以这里不做版本筛选——宁可
+// 给一个近似位置，也好过整段缺失。真正需要精度的场景由 manual 标记覆盖。
+func (s *TODbService) FetchSegments(ctx context.Context, q SegmentQuery) ([]SegmentSpan, error) {
+	if s == nil || s.client == nil || q.TMDbID <= 0 {
+		return nil, nil
+	}
+	payload := todbRequest{
+		PlatformValue: fmt.Sprint(q.TMDbID),
+		Includes:      []string{"marker"},
+		Page:          1,
+		PageSize:      s.pageSize,
+	}
+	if q.IsMovie {
+		payload.PlatformType = "tmdb_id_movie"
+	} else {
+		payload.PlatformType = "tmdb_id_tv"
+		payload.SeasonNumber = q.Season
+		payload.EpisodeNumber = q.Episode
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, s.baseURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusNotFound {
+		return nil, nil
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("todb: unexpected status %d", resp.StatusCode)
+	}
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, todbMaxBodySize))
+	if err != nil {
+		return nil, err
+	}
+	return parseTODbResponse(raw)
+}
+
+// parseTODbResponse 把各片源的 marker 合并成 spans。
+//
+// marker_type 的映射沿用报告里的规则：intro -> intro，credits/post_credits ->
+// credits（片尾），其余（chapter 等章节标记）忽略——章节标题没有可靠的语义，
+// 当成片头会让跳过点漂到任意位置。
+func parseTODbResponse(body []byte) ([]SegmentSpan, error) {
+	var raw todbResponse
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("parse todb json: %w", err)
+	}
+	seen := make(map[string]bool, 4)
+	spans := make([]SegmentSpan, 0, 4)
+	for _, item := range raw.Items {
+		for _, marker := range item.Marker {
+			kind := todbMarkerKind(marker.MarkerType)
+			if kind == "" || seen[kind] {
+				continue
+			}
+			if marker.TimeStart == nil || marker.TimeEnd == nil {
+				continue
+			}
+			startMs := int64(*marker.TimeStart * 1000)
+			endMs := int64(*marker.TimeEnd * 1000)
+			if startMs < 0 {
+				startMs = 0
+			}
+			// 结束点缺失或非正表示「到片尾」，只有这样才是合法的开放区间；
+			// 与 TheIntroDB 不同，TODb 用 0 而不是 null 表示没标结束点，
+			// 所以这里把 <= start 的片尾当作开放区间。
+			if endMs <= startMs {
+				if kind != "credits" && kind != "preview" {
+					continue
+				}
+				endMs = 0
+			}
+			spans = append(spans, SegmentSpan{Kind: kind, StartMs: startMs, EndMs: endMs})
+			seen[kind] = true
+		}
+	}
+	return spans, nil
+}
+
+// todbMarkerKind 把 TODb 的 marker_type 映射成库内 kind。
+func todbMarkerKind(markerType string) string {
+	switch strings.ToLower(strings.TrimSpace(markerType)) {
+	case "intro":
+		return "intro"
+	case "recap":
+		return "recap"
+	case "credits", "post_credits", "outro":
+		return "credits"
+	case "preview":
+		return "preview"
+	default:
+		return ""
+	}
+}

internal/service/todb_test.go

@@ -0,0 +1,112 @@
+package service
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+// TODb 的接口是 POST + JSON body（GET 返回 405），平台类型用 tmdb_id_tv /
+// tmdb_id_movie 表达，marker 的时间轴是秒。
+func TestTODbFetchSendsPostWithTMDBPlatform(t *testing.T) {
+	var body map[string]any
+	var method string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		method = r.Method
+		raw, _ := io.ReadAll(r.Body)
+		_ = json.Unmarshal(raw, &body)
+		_, _ = w.Write([]byte(`{"page":1,"page_size":10,"has_more":false,"items":[]}`))
+	}))
+	defer server.Close()
+
+	svc := NewTODbService(zap.NewNop()).SetBaseURL(server.URL)
+	if _, err := svc.FetchSegments(t.Context(), SegmentQuery{TMDbID: 226045, Season: 1, Episode: 1}); err != nil {
+		t.Fatalf("fetch: %v", err)
+	}
+	if method != http.MethodPost {
+		t.Fatalf("method = %s, want POST", method)
+	}
+	if body["platform_type"] != "tmdb_id_tv" || body["platform_value"] != "226045" {
+		t.Fatalf("body = %#v, want tmdb_id_tv/226045", body)
+	}
+	if body["season_number"] != float64(1) || body["episode_number"] != float64(1) {
+		t.Fatalf("body = %#v, want season/episode 1", body)
+	}
+}
+
+func TestTODbFetchUsesMoviePlatform(t *testing.T) {
+	var body map[string]any
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, _ := io.ReadAll(r.Body)
+		_ = json.Unmarshal(raw, &body)
+		_, _ = w.Write([]byte(`{"items":[]}`))
+	}))
+	defer server.Close()
+
+	svc := NewTODbService(zap.NewNop()).SetBaseURL(server.URL)
+	if _, err := svc.FetchSegments(t.Context(), SegmentQuery{TMDbID: 83533, IsMovie: true}); err != nil {
+		t.Fatalf("fetch: %v", err)
+	}
+	if body["platform_type"] != "tmdb_id_movie" {
+		t.Fatalf("platform_type = %v, want tmdb_id_movie", body["platform_type"])
+	}
+	if _, ok := body["season_number"]; ok {
+		t.Fatalf("body = %#v, want no season_number for a movie", body)
+	}
+}
+
+// 实测返回：marker 的时间是秒，marker_type 为 intro。
+func TestParseTODbResponseConvertsSecondsToMilliseconds(t *testing.T) {
+	body := `{"page":1,"page_size":3,"has_more":false,"items":[
+		{"version_id":1192,"version_name":"爱奇艺","version_runtime":1300,"video_type":"tv",
+		 "marker":[{"marker_id":1588,"marker_type":"intro","time_start":0,"time_end":27}]}]}`
+	spans, err := parseTODbResponse([]byte(body))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(spans) != 1 {
+		t.Fatalf("spans = %#v, want 1", spans)
+	}
+	if spans[0].Kind != "intro" || spans[0].StartMs != 0 || spans[0].EndMs != 27_000 {
+		t.Fatalf("span = %#v, want intro 0-27000ms", spans[0])
+	}
+}
+
+func TestParseTODbResponseMapsMarkerTypes(t *testing.T) {
+	body := `{"items":[{"marker":[
+		{"marker_type":"intro","time_start":10,"time_end":30},
+		{"marker_type":"credits","time_start":100,"time_end":120},
+		{"marker_type":"post_credits","time_start":130,"time_end":140},
+		{"marker_type":"chapter","time_start":5,"time_end":6}
+	]}]}`
+	spans, err := parseTODbResponse([]byte(body))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	// chapter 被忽略；post_credits 与 credits 同为片尾，同 kind 只保留第一个。
+	if len(spans) != 2 {
+		t.Fatalf("spans = %#v, want intro + credits", spans)
+	}
+	if spans[0].Kind != "intro" || spans[1].Kind != "credits" {
+		t.Fatalf("kinds = %s/%s, want intro/credits", spans[0].Kind, spans[1].Kind)
+	}
+}
+
+// 片尾的结束点缺失或非正表示「到片尾」，是合法的开放区间；片头不行。
+func TestParseTODbResponseAllowsOpenEndedCreditsOnly(t *testing.T) {
+	body := `{"items":[{"marker":[
+		{"marker_type":"intro","time_start":10,"time_end":10},
+		{"marker_type":"credits","time_start":100,"time_end":100}
+	]}]}`
+	spans, err := parseTODbResponse([]byte(body))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(spans) != 1 || spans[0].Kind != "credits" || spans[0].EndMs != 0 {
+		t.Fatalf("spans = %#v, want only an open-ended credits", spans)
+	}
+}

internal/service/transcoder.go

@@ -272,6 +272,9 @@ func (t *TranscoderService) EnsureJobFromSubtitleQuality(ctx context.Context, me
 	input.Quality = quality
 	t.maybeFillDuration(ctx, m, input)
 	settings := ffmpegArgSettingsFromConfig(cfg, quality)
+	// 「原画」档位遇到浏览器可解的 H.264 源时只换封装，避免慢机器上重编码
+	// 追不上播放（两核软件编码实测 0.1～0.2 倍速）。其它档位要改分辨率，仍重编码。
+	input.CopyVideo = t.remuxEligible(ctx, m, quality, subtitleStream)
 	jobEncoder := settings.encoder
 	if settings.noScale || subtitleStream >= 0 {
 		jobEncoder = ""
@@ -312,6 +315,9 @@ func (t *TranscoderService) EnsureJobFromSubtitleQuality(ctx context.Context, me
 	if subtitleStream >= 0 {
 		jobEncoder = "software (subtitle burn-in)"
 	}
+	if input.CopyVideo {
+		jobEncoder = remuxEncoderLabel
+	}
 	job := &hlsJob{
 		jobKey:         jobKey,
 		mediaID:        mediaID,

internal/service/transcoder_ffmpeg_args.go

@@ -16,6 +16,9 @@ type transcodeInput struct {
 	StartSec       float64
 	SubtitleStream *int
 	Quality        *LocalHLSQuality
+	// CopyVideo 为 true 时视频流只换封装（-c:v copy），不重编码。
+	// 仅当源视频是浏览器可解的老三样（H.264/8bit/4:2:0）且不需要缩放时启用。
+	CopyVideo bool
 }
 
 type ffmpegArgSettings struct {
@@ -52,6 +55,7 @@ func buildFFmpegArgsForInput(cfg *config.Config, input transcodeInput, playlist,
 		// 原画档位不做硬件缩放的兼容处理，直接走软件编码，保持源分辨率。
 		settings.encoder = ""
 	}
+	copyVideo := input.CopyVideo && input.SubtitleStream == nil
 	video := ffmpegVideoPlanForSettings(settings)
 	if input.SubtitleStream != nil {
 		// Bitmap subtitles must be composited in software. Keeping CUDA/QSV/
@@ -60,13 +64,17 @@ func buildFFmpegArgsForInput(cfg *config.Config, input transcodeInput, playlist,
 		settings.encoder = ""
 		video = ffmpegVideoPlanForSettings(settings)
 	}
+	if copyVideo {
+		// 直通：不做缩放、不挂滤镜、不选编码器，整条视频流原样塞进 TS。
+		video = ffmpegVideoPlan{codec: "copy"}
+	}
 
 	// Mid-file restarts must not use -re: output -ss would otherwise crawl to the
 	// seek point at 1x wall-clock before emitting the first HLS segment.
 	realtime := settings.realtime && input.StartSec <= 0.05
 	args := baseFFmpegArgs(video.preInput, realtime)
-	args = appendInputAndVideoArgs(args, input, settings, video)
-	args = appendOutputHLSArgs(args, settings, segments, playlist)
+	args = appendInputAndVideoArgs(args, input, settings, video, copyVideo)
+	args = appendOutputHLSArgs(args, settings, segments, playlist, copyVideo)
 	return args
 }
 
@@ -161,7 +169,7 @@ func baseFFmpegArgs(preInput string, realtime bool) []string {
 	return args
 }
 
-func appendInputAndVideoArgs(args []string, input transcodeInput, settings ffmpegArgSettings, video ffmpegVideoPlan) []string {
+func appendInputAndVideoArgs(args []string, input transcodeInput, settings ffmpegArgSettings, video ffmpegVideoPlan, copyVideo bool) []string {
 	args = append(args, ffmpegHTTPInputArgs(input)...)
 	ss := ""
 	if input.StartSec > 0.05 {
@@ -172,6 +180,11 @@ func appendInputAndVideoArgs(args []string, input transcodeInput, settings ffmpe
 	// scrubbing; CDNs with Range support jump via demuxer seek instead.
 	if ss != "" {
 		args = append(args, "-ss", ss)
+		if copyVideo {
+			// 复制视频流时 ffmpeg 不能解码，精确 seek 会把关键帧之前的分组丢掉，
+			// 输出从 P 帧开始（花屏）。退到前一个关键帧，最多提前一两秒。
+			args = append(args, "-noaccurate_seek")
+		}
 	}
 	args = append(args, "-i", input.Source)
 	if input.SubtitleStream != nil {
@@ -197,7 +210,23 @@ func appendInputAndVideoArgs(args []string, input transcodeInput, settings ffmpe
 	return args
 }
 
-func appendOutputHLSArgs(args []string, settings ffmpegArgSettings, segments, playlist string) []string {
+func appendOutputHLSArgs(args []string, settings ffmpegArgSettings, segments, playlist string, copyVideo bool) []string {
+	if copyVideo {
+		// 视频是复制进来的，编码参数一律不适用；只保留音频转 AAC 与切片参数。
+		// -avoid_negative_ts 让带 B 帧的源在 -ss 之后不会出现负时间戳。
+		return append(args,
+			"-avoid_negative_ts", "make_zero",
+			"-c:a", "aac",
+			"-ar", "48000",
+			"-b:a", "128k",
+			"-ac", "2",
+			"-f", "hls",
+			"-hls_time", fmt.Sprintf("%d", settings.segmentSeconds),
+			"-hls_list_size", "0",
+			"-hls_segment_filename", segments,
+			playlist,
+		)
+	}
 	return append(args,
 		"-pix_fmt", "yuv420p",
 		"-b:v", settings.bitrate,

internal/service/transcoder_remux.go

@@ -0,0 +1,102 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 蓝光原盘（m2ts，40 Mbps 级别）在两核小机器上重编码只有 0.1～0.2 倍速，HLS
+// 永远追不上播放，播放器等不到切片就报「转码失败」。当源视频本身就是浏览器
+// 能解的 H.264 / 8bit / 4:2:0，且用户选的是「原画」档位（不改分辨率）时，
+// 这里改走只换封装（-c:v copy）的直通路径：视频不重编码，音频转 AAC，
+// CPU 占用接近于零，起播时间从几十秒降到几秒。
+//
+// 直通只对「原画」生效。1080P/720P/480P 档位意味着要改分辨率，必须重新编码；
+// 那类请求仍然按原来的 libx264 路径处理（慢，但码率可控）。
+
+// remuxEncoderLabel 是直通任务在日志与任务面板里的标签。
+const remuxEncoderLabel = "remux"
+
+// remuxEligible 判断这次请求能否复制视频流而不是重编码。
+func (t *TranscoderService) remuxEligible(ctx context.Context, m *model.Media, quality *LocalHLSQuality, subtitleStream int) bool {
+	if t == nil || t.repo == nil || m == nil {
+		return false
+	}
+	// 烧录图形字幕要把字幕叠加进画面，必须解码+重编码。
+	if subtitleStream >= 0 {
+		return false
+	}
+	if !remuxAppliesToQuality(quality) {
+		return false
+	}
+	probe, err := t.repo.MediaProbe.Get(ctx, m.ID)
+	if err != nil || probe == nil {
+		// 没有探测缓存就无法确认档次/像素格式，保守走重编码。
+		return false
+	}
+	return remuxCopyableHeight(probe) > 0
+}
+
+// remuxAppliesToQuality 只放行「原画」档位（Height 为 0，即不缩放）。
+// quality 为 nil 表示调用方没有指定档位（走全局 max_height），同样不直通，
+// 否则会绕过配置的分辨率上限给出一个远超预期的码流。
+func remuxAppliesToQuality(quality *LocalHLSQuality) bool {
+	return quality != nil && quality.Height <= 0
+}
+
+// remuxCopyableHeight 在源视频可直接复制进 HLS 时返回它的高度，否则返回 0。
+func remuxCopyableHeight(probe *model.MediaProbe) int {
+	if probe == nil || probe.Height <= 0 {
+		return 0
+	}
+	if !strings.EqualFold(strings.TrimSpace(probe.VideoCodec), "h264") {
+		return 0
+	}
+	if !browserSafeH264Payload(probe.Payload) {
+		return 0
+	}
+	return probe.Height
+}
+
+// probePayloadStreams 只解析落库 payload 里与直通判断有关的字段。
+type probePayloadStreams struct {
+	Streams []struct {
+		Type    string `json:"type"`
+		Profile string `json:"profile"`
+		PixFmt  string `json:"pix_fmt"`
+	} `json:"streams"`
+}
+
+// browserSafeH264Payload 只放行 8bit 4:2:0 的 Baseline/Main/High。
+// Hi10P（High 10）和 4:2:2 母带浏览器解不出来，复制过去只会黑屏或无声。
+func browserSafeH264Payload(payload string) bool {
+	payload = strings.TrimSpace(payload)
+	if payload == "" {
+		// 老数据没有 payload：已经有 codec + 分辨率，按 8bit 常规情况处理。
+		return true
+	}
+	var parsed probePayloadStreams
+	if err := json.Unmarshal([]byte(payload), &parsed); err != nil {
+		return false
+	}
+	for _, stream := range parsed.Streams {
+		if !strings.EqualFold(strings.TrimSpace(stream.Type), "video") {
+			continue
+		}
+		switch strings.ToLower(strings.TrimSpace(stream.Profile)) {
+		case "", "constrained baseline", "baseline", "main", "high":
+		default:
+			return false
+		}
+		switch strings.ToLower(strings.TrimSpace(stream.PixFmt)) {
+		case "", "yuv420p", "yuvj420p":
+		default:
+			return false
+		}
+		return true
+	}
+	return true
+}

internal/service/transcoder_remux_test.go

@@ -0,0 +1,170 @@
+package service
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// 直通档位必须真的把视频流复制过去：一旦又带上 libx264 / -vf / 码率参数，
+// 慢机器上的「原画」就还是几十秒起播。
+func TestBuildFFmpegArgsRemuxCopiesVideoStream(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Transcoder.SegmentSeconds = 4
+	cfg.Transcoder.Realtime = true
+	cfg.Transcoder.Threads = 2
+	cfg.Transcoder.MaxHeight = 720
+
+	quality, ok := LocalHLSQualityByID("source")
+	if !ok {
+		t.Fatal("source quality missing")
+	}
+	args := buildFFmpegArgsForInput(cfg, transcodeInput{
+		Source:    "https://cdn.example/x.m2ts",
+		Headers:   map[string]string{"User-Agent": "MeBox-115-GoClient/1.0"},
+		StartSec:  52.4,
+		Quality:   &quality,
+		CopyVideo: true,
+	}, "/cache/hls/k/run-1/index.m3u8", "/cache/hls/k/run-1/seg_%05d.ts")
+	joined := strings.Join(args, " ")
+
+	for _, want := range []string{
+		"-c:v copy",
+		"-c:a aac",
+		"-ar 48000",
+		"-b:a 128k",
+		"-ac 2",
+		"-avoid_negative_ts make_zero",
+		"-ss 52.400",
+		"-noaccurate_seek",
+		"-hls_time 4",
+		"-hls_segment_filename /cache/hls/k/run-1/seg_%05d.ts",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("remux args missing %q: %s", want, joined)
+		}
+	}
+	for _, unwanted := range []string{
+		"libx264",
+		"-vf ",
+		"-b:v",
+		"-maxrate",
+		"-bufsize",
+		"-force_key_frames",
+		"-preset",
+		"-threads",
+		"-pix_fmt",
+	} {
+		if strings.Contains(joined, unwanted) {
+			t.Errorf("remux args must not contain %q: %s", unwanted, joined)
+		}
+	}
+	// 中途起播不能加 -re，否则会先按 1 倍速爬到目标位置才出第一个切片。
+	if strings.Contains(joined, " -re ") {
+		t.Errorf("mid-file remux must not use -re: %s", joined)
+	}
+}
+
+// 烧录图形字幕要把字幕叠进画面，必须解码重编码，不能被直通标志绕过。
+func TestBuildFFmpegArgsRemuxIgnoredForSubtitleBurnIn(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Transcoder.MaxHeight = 720
+	cfg.Transcoder.SegmentSeconds = 4
+
+	quality, _ := LocalHLSQualityByID("source")
+	subtitle := 4
+	args := buildFFmpegArgsForInput(cfg, transcodeInput{
+		Source:         "/media/ep.mkv",
+		Quality:        &quality,
+		CopyVideo:      true,
+		SubtitleStream: &subtitle,
+	}, "/o/x.m3u8", "/o/seg_%05d.ts")
+	joined := strings.Join(args, " ")
+
+	if strings.Contains(joined, "-c:v copy") {
+		t.Fatalf("subtitle burn-in must not copy the video stream: %s", joined)
+	}
+	if !strings.Contains(joined, "libx264") || !strings.Contains(joined, "-filter_complex") {
+		t.Fatalf("subtitle burn-in should re-encode: %s", joined)
+	}
+	if strings.Contains(joined, "-noaccurate_seek") {
+		t.Fatalf("encoded path should keep accurate seek: %s", joined)
+	}
+}
+
+// 只有「原画」档位（不缩放）可以直通；其它档位要改分辨率。
+func TestRemuxAppliesToQuality(t *testing.T) {
+	if remuxAppliesToQuality(nil) {
+		t.Fatal("nil quality must not remux: it falls back to the configured max height")
+	}
+	source, _ := LocalHLSQualityByID("source")
+	if !remuxAppliesToQuality(&source) {
+		t.Fatal("source quality should remux")
+	}
+	for _, id := range []string{"1080", "720", "480"} {
+		quality, ok := LocalHLSQualityByID(id)
+		if !ok {
+			t.Fatalf("quality %s missing", id)
+		}
+		if remuxAppliesToQuality(&quality) {
+			t.Fatalf("quality %s must re-encode", id)
+		}
+	}
+}
+
+// 只有 8bit 4:2:0 的 H.264 能安全复制；Hi10P / 4:2:2 / HEVC 复制过去浏览器黑屏。
+func TestRemuxCopyableHeight(t *testing.T) {
+	const blurayPayload = `{"container":"mpegts","duration_sec":1451,"bit_rate":42609934,"streams":[{"index":0,"type":"video","codec":"h264","profile":"High","width":1920,"height":1080,"pix_fmt":"yuv420p","frame_rate":"23.976"},{"index":1,"type":"audio","codec":"pcm_bluray","channels":2}]}`
+
+	cases := []struct {
+		name  string
+		probe *model.MediaProbe
+		want  int
+	}{
+		{
+			name:  "bluray h264 8bit 420",
+			probe: &model.MediaProbe{VideoCodec: "h264", Height: 1080, Payload: blurayPayload},
+			want:  1080,
+		},
+		{
+			name:  "no payload falls back to codec and height",
+			probe: &model.MediaProbe{VideoCodec: "h264", Height: 720},
+			want:  720,
+		},
+		{
+			name:  "hevc cannot be copied into browser hls",
+			probe: &model.MediaProbe{VideoCodec: "hevc", Height: 1080, Payload: `{"streams":[{"type":"video","profile":"Main 10","pix_fmt":"yuv420p10le"}]}`},
+			want:  0,
+		},
+		{
+			name:  "hi10p h264 is unplayable in browsers",
+			probe: &model.MediaProbe{VideoCodec: "h264", Height: 1080, Payload: `{"streams":[{"type":"video","profile":"High 10","pix_fmt":"yuv420p10le"}]}`},
+			want:  0,
+		},
+		{
+			name:  "4:2:2 h264 is unplayable in browsers",
+			probe: &model.MediaProbe{VideoCodec: "h264", Height: 1080, Payload: `{"streams":[{"type":"video","profile":"High 4:2:2","pix_fmt":"yuv422p"}]}`},
+			want:  0,
+		},
+		{
+			name:  "missing probe",
+			probe: nil,
+			want:  0,
+		},
+		{
+			name:  "unknown height",
+			probe: &model.MediaProbe{VideoCodec: "h264", Height: 0, Payload: blurayPayload},
+			want:  0,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := remuxCopyableHeight(tc.probe); got != tc.want {
+				t.Fatalf("remuxCopyableHeight() = %d, want %d", got, tc.want)
+			}
+		})
+	}
+}

web/src/api/playback.ts

@@ -54,6 +54,16 @@ export const playbackAPI = {
       .get<PlaybackSegmentsResponse>(`/playback/${encodeURIComponent(mediaId)}/segments`)
       .then((r) => r.data),
 
+  // 手动标记：把当前位置记为片头结束 / 片尾开始（clear 则清除）。服务端会按季
+  // 传播到同季其它尚未标记的集，并返回合并后的完整片段列表。
+  markSegment: (
+    mediaId: string,
+    payload: { kind: 'intro' | 'credits'; position_ms?: number; clear?: boolean },
+  ) =>
+    api
+      .put<PlaybackSegmentsResponse>(`/playback/${encodeURIComponent(mediaId)}/segments`, payload)
+      .then((r) => r.data),
+
   recordProgress: (payload: PlaybackProgressRequest) =>
     api.post('/history', payload).then((r) => r.data),
 

web/src/components/PlayerControls.tsx

@@ -79,6 +79,15 @@ const SEEK_STEP_SEC = 10
 const SEEK_REPEAT_MS = 160
 const SEEK_APPLY_MS = 220
 const SEEK_HINT_MS = 700
+/**
+ * 一次 seek 之后，播放事件在这段时间内不得把控制栏唤出来。
+ *
+ * 方向键/进度条跳转会让 <video> 走一遍 seeking → waiting → playing：
+ * 直连要重新拉 Range，本地 HLS 甚至要重起一段转码，缓冲恢复时的 playing
+ * 事件会把「播放器自己恢复」误当成用户操作，控制栏（连同整条进度条）就又
+ * 冒出来了。键盘处理本身早就不再唤出控制栏，漏的就是这条事件链。
+ */
+const SEEK_CONTROLS_SUPPRESS_MS = 1500
 const PLAYBACK_RATE_REPEAT_MS = 140
 const PLAYBACK_RATE_HINT_MS = 900
 /** 播放中控制栏无操作自动隐藏的延时。 */
@@ -290,6 +299,10 @@ export function PlayerControls({
   const vr360ActiveRef = useRef(Boolean(vr360))
   /** 画面是否已锁住（VR 锁）。事件回调里读它，避免闭包读到过期值。 */
   const uiLockedRef = useRef(uiLocked)
+  /** 控制栏当前是否可见：方向键只续期计时器，不改变可见性。 */
+  const uiVisibleRef = useRef(uiVisible)
+  /** 最近一次真正下发 seek 的时间（含键盘与进度条），用于压掉 seek 引发的播放事件。 */
+  const lastSeekActivityRef = useRef(0)
   /** VR 画布上的按下状态：按住拖动 = 转动视角，不唤出控制栏。 */
   const vrDragRef = useRef<{ x: number; y: number; moved: boolean } | null>(null)
   const pendingSeekRef = useRef<number | null>(null)
@@ -318,6 +331,10 @@ export function PlayerControls({
     uiLockedRef.current = uiLocked
   }, [uiLocked])
 
+  useEffect(() => {
+    uiVisibleRef.current = uiVisible
+  }, [uiVisible])
+
   // 「保持显示」条件集中在这里：悬停控制栏、拖动进度条、打开任何菜单或面板。
   // 事件回调里读 ref，渲染里读派生值，两边始终一致。
   const keepControlsVisible =
@@ -487,10 +504,27 @@ export function PlayerControls({
       onUiVisibleChange(false)
     }
 
+    /**
+     * 播放状态变化：图标永远同步，但只有「暂停」这种明确需要操作栏的动作才
+     * 主动唤出控制栏。
+     *
+     * `playing` 在 seek 之后缓冲恢复时同样会派发（直连要重拉 Range、本地 HLS
+     * 甚至重起一段转码），把它当成用户操作，方向键快进时整条控制栏（进度条）
+     * 就会自己冒出来。所以 play / playing 只同步图标并续期自动隐藏计时器，
+     * 不改变可见性；pause 才唤出控制栏，并且要避开刚下发 seek 的那一小段时间。
+     */
+    const seekSuppressed = () =>
+      Date.now() - lastSeekActivityRef.current < SEEK_CONTROLS_SUPPRESS_MS
     const syncPlay = () => {
       setPlaying(!el.paused)
+      if (seekSuppressed()) return
       onMove()
     }
+    /** 播放/缓冲恢复：只同步状态并续期隐藏计时器，绝不主动唤出控制栏。 */
+    const syncPlaying = () => {
+      setPlaying(!el.paused)
+      resetTimer()
+    }
     const syncTime = () => {
       const ranges = el.buffered
       if (ranges && ranges.length > 0) {
@@ -539,8 +573,11 @@ export function PlayerControls({
     stage.addEventListener('pointerup', endVrDrag)
     stage.addEventListener('pointercancel', endVrDrag)
 
-    el.addEventListener('play', syncPlay)
-    el.addEventListener('playing', syncPlay)
+    // 播放开始/缓冲恢复都不唤出控制栏：播放本身几乎总是由点击画面、播放按钮
+    // 或 seek 触发，这些入口要么已经在控制栏里，要么会被显式显示；事件再顶一次
+    // 就会让方向键快进时整条进度条冒出来。只有暂停需要主动亮出控制栏。
+    el.addEventListener('play', syncPlaying)
+    el.addEventListener('playing', syncPlaying)
     el.addEventListener('pause', syncPlay)
     el.addEventListener('timeupdate', syncTime)
     el.addEventListener('progress', syncTime)
@@ -561,8 +598,8 @@ export function PlayerControls({
       stage.removeEventListener('pointermove', onVrPointerMove)
       stage.removeEventListener('pointerup', endVrDrag)
       stage.removeEventListener('pointercancel', endVrDrag)
-      el.removeEventListener('play', syncPlay)
-      el.removeEventListener('playing', syncPlay)
+      el.removeEventListener('play', syncPlaying)
+      el.removeEventListener('playing', syncPlaying)
       el.removeEventListener('pause', syncPlay)
       el.removeEventListener('timeupdate', syncTime)
       el.removeEventListener('progress', syncTime)
@@ -632,6 +669,8 @@ export function PlayerControls({
     (absolute: number) => {
       const el = video()
       if (!el) return
+      // 记下这次 seek：随后由它触发的 waiting/playing 不算用户操作。
+      lastSeekActivityRef.current = Date.now()
       if (onSeekAbsolute?.(absolute)) {
         pendingSeekRef.current = absolute
         setCurrentTime(absolute)
@@ -682,10 +721,12 @@ export function PlayerControls({
     setSeekHover(clampRatio((event.clientX - rect.left) / rect.width))
   }
 
-  const revealControls = useCallback(() => {
-    // 锁住时键盘操作（方向键调进度/音量）不应该把控制栏唤回来。
-    if (uiLockedRef.current) return
-    onUiVisibleChange(true)
+  /**
+   * 方向键调进度时只续期自动隐藏计时器，不主动唤出操作栏：控制栏原本隐藏时
+   * 保持画面干净（只留轻量的快进/回退提示），原本可见时也不会在连续按键中途消失。
+   */
+  const refreshControlsTimer = useCallback(() => {
+    if (uiLockedRef.current || !uiVisibleRef.current) return
     if (hideTimerRef.current) clearTimeout(hideTimerRef.current)
     const el = video()
     if (!el || el.paused || holdControlsRef.current) {
@@ -723,12 +764,14 @@ export function PlayerControls({
     }
 
     pendingSeekRef.current = target
+    // 方向键也是一次真实 seek：播放事件在抑制窗口内不得唤出控制栏。
+    lastSeekActivityRef.current = Date.now()
     setCurrentTime(target)
     setSeekHint({
       dir: applied < 0 ? 'back' : 'forward',
       seconds: Math.abs(Math.round(applied)),
     })
-    revealControls()
+    refreshControlsTimer()
 
     if (seekHintTimerRef.current) clearTimeout(seekHintTimerRef.current)
     seekHintTimerRef.current = setTimeout(() => setSeekHint(null), SEEK_HINT_MS)
@@ -750,7 +793,7 @@ export function PlayerControls({
       if (!burst) return
       applySeekRef.current(burst.base + burst.delta)
     }, SEEK_APPLY_MS)
-  }, [revealControls, streamOffset, video])
+  }, [refreshControlsTimer, streamOffset, video])
 
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {

web/src/pages/HomePageSections.tsx

@@ -464,7 +464,9 @@ export function HomeLibrariesSection({
             pinned={pinnedIds.includes(lib.id)}
             onTogglePin={onTogglePin ? () => onTogglePin(lib.id) : undefined}
             onVisible={() => {
-              if (!lib.cover_url) {
+              // 服务端会生成库封面时不必再为首屏卡片拉成员预览；
+              // 远程挂载库的封面仍由卡片拼图兜底。
+              if (!lib.cover_url && !lib.cover_image_url) {
                 queuePreview(lib.id)
               }
             }}

web/src/pages/PlayerPage.tsx

@@ -88,6 +88,16 @@ type PlayerDiagnosticEvent = { at: string; phase: string; mode: string; message:
 // 自动跳过片头后，「已跳过 · 撤销」提示停留的时长。
 const SKIP_NOTICE_MS = 6000
 
+// 手动标记的提示里展示的时间点（mm:ss 或 h:mm:ss）。
+function formatMarkTime(totalSec: number): string {
+  const safe = Math.max(0, Math.floor(totalSec))
+  const hours = Math.floor(safe / 3600)
+  const minutes = Math.floor((safe % 3600) / 60)
+  const seconds = safe % 60
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return hours > 0 ? `${hours}:${pad(minutes)}:${pad(seconds)}` : `${minutes}:${pad(seconds)}`
+}
+
 // 115 云 HLS 中途断流后，允许在窗口内重建几次会话再退回本地转码。
 const CLOUD_HLS_RELOAD_MAX = 3
 const CLOUD_HLS_RELOAD_WINDOW_MS = 10 * 60 * 1000
@@ -129,6 +139,10 @@ export function PlayerPage() {
     return () => guard.invalidate()
   }, [id])
   const directRetryRef = useRef(false)
+  // 直连 302 被网盘 CDN 按 UA 防盗链拒绝后（115 直链绑定换链时的 UA，电视
+  // WebView、按站点改 UA 的扩展、改写 UA 的代理都会让「页面请求」与「取流
+  // 请求」的 UA 不一致而 403），改用服务端同源转发（?proxy=1）再试的标记。
+  const directViaProxyRef = useRef(false)
   const retryingDirectRef = useRef(false)
   // 程序化续播 seek 后的宽限截止时间；期内直连误报不升到 HLS。
   const directSeekGraceUntilRef = useRef(0)
@@ -163,6 +177,11 @@ export function PlayerPage() {
   const [mode, setMode] = useState<PlayerMode>('direct')
   const diagnosticModeRef = useRef(mode)
   useEffect(() => { diagnosticModeRef.current = mode }, [mode])
+  // modeRef / mediaRef 会被声明点之上的回调读到（handleDirectSeekStalled、
+  // fallbackDirectPlay、toggleVr360 等），所以先在这里声明，赋值仍由下方各自的
+  // 同步 effect 负责；否则以后有人在渲染期调用这些回调就会踩 TDZ。
+  const modeRef = useRef(mode)
+  const mediaRef = useRef(media)
   const [diagnosticsOpen, setDiagnosticsOpen] = useState(false)
   const [diagnosticEvents, setDiagnosticEvents] = useState<PlayerDiagnosticEvent[]>([])
   const [subs, setSubs] = useState<SubtitleTrack[]>([])
@@ -188,6 +207,12 @@ export function PlayerPage() {
   const subtitlePreferenceTouchedRef = useRef(false)
   const subtitlePreferenceSaveQueueRef = useRef<Promise<void>>(Promise.resolve())
   const [hlsUnavailable, setHlsUnavailable] = useState(false)
+  // 播放接线 effect 里只有一条提示需要读它，用 ref 读即可保持最新；如果放进依赖，
+  // 这个 effect 会因为自己写出来的状态而整体重建（teardownHls + DELETE 转码任务）。
+  const hlsUnavailableRef = useRef(false)
+  useEffect(() => {
+    hlsUnavailableRef.current = hlsUnavailable
+  }, [hlsUnavailable])
   const [playerError, setPlayerError] = useState('')
   // 媒体元数据加载失败（404 / 无权限等）：舞台区直接展示错误而不是永远「加载中」
   const [loadError, setLoadError] = useState('')
@@ -528,6 +553,12 @@ export function PlayerPage() {
     setPlaybackInfo(null)
     setHlsSource('local')
     setSelectedQuality('')
+    // HLS 可用性与字幕列表都是「上一条媒体」得出的结论，必须跟着媒体一起清掉：
+    // 否则某一集 HLS 失败一次，之后每集直连失败就再也不会回退转码（只弹「HLS 不可用」）；
+    // 字幕列表留着旧条目还会用新 media.id 拼旧 path 去请求一次。
+    setHlsUnavailable(false)
+    setSubs([])
+    setSubtitleIndex(-1)
     setCloudWaiting(false)
     setCloudWaitMessage('')
     setCloudWaitStartedAt(0)
@@ -546,6 +577,7 @@ export function PlayerPage() {
     setDanmakuInfo(null)
     setDanmakuSearching(true)
     directRetryRef.current = false
+    directViaProxyRef.current = false
     retryingDirectRef.current = false
     directSeekGraceUntilRef.current = 0
     transientPlayErrorRef.current = ''
@@ -1243,7 +1275,6 @@ export function PlayerPage() {
   // 作为播放 effect 的依赖，会在 STRM 的 302 直链仍在建立时重复设置 src，
   // Chromium 会把被中断的首次加载报告成播放错误并误触发 HLS 回退。
   const activeBurnedSubtitleStream = mode === 'hls' ? burnedSubtitleStream : undefined
-  const mediaRef = useRef(media)
   useEffect(() => {
     mediaRef.current = media
     directOnlyRef.current = directOnly
@@ -1475,7 +1506,7 @@ export function PlayerPage() {
     } else {
       // VR 全景需要浏览器能读帧：STRM/网盘直链会被 302 到跨域 CDN，此时改为
       // 服务端同源转发（原画，不转码）；普通播放仍走 302 直连，省服务器流量。
-      const url = streamURL(mediaId, { proxy: vr360DirectProxyRef.current })
+      const url = streamURL(mediaId, { proxy: vr360DirectProxyRef.current || directViaProxyRef.current })
       const absoluteURL = new URL(url, window.location.href).href
       // 其它异步播放器状态更新不应重启同一个直连请求；STRM 的重定向/换链
       // 比本地文件慢，重启请求可能产生一个短暂但会触发 onError 的中断。
@@ -1511,7 +1542,7 @@ export function PlayerPage() {
         // 起播兜底：上游不回 error 时会一直停在 readyState=0，见 armDirectStallWatchdog。
         armDirectStallWatchdog()
       }
-      if (hlsUnavailable && needsTranscodeForBrowser(currentMedia)) {
+      if (hlsUnavailableRef.current && needsTranscodeForBrowser(currentMedia)) {
         setPlayerError('当前正在直连播放原始文件；此封装或音轨浏览器兼容性有限，可能只有画面没有声音。请配置本机 ffmpeg 后切回 HLS 转码播放。')
       }
     }
@@ -1540,7 +1571,6 @@ export function PlayerPage() {
     cloudReloadNonce,
     cloudWaiting,
     hlsSource,
-    hlsUnavailable,
     hlsStartSec,
     mediaId,
     mode,
@@ -1575,22 +1605,39 @@ export function PlayerPage() {
 
   useEffect(() => {
     if (!resumePosition || initialSeekDone) return
+    let cancelled = false
     if (mode === 'hls' && hlsSource === 'local') {
       // Restart transcode near the resume point instead of seeking a short partial playlist.
       if (Math.abs(hlsStartSec - resumePosition) > 2) {
         setHlsStartSec(resumePosition)
       }
-      setInitialSeekDone(true)
-      const m = Math.floor(resumePosition / 60)
-      const s = Math.floor(resumePosition % 60)
-      const timeStr = `${m.toString().padStart(2, '0')}:${s.toString().padStart(2, '0')}`
-      toast.success(`已恢复上次播放进度至 ${timeStr}`, { duration: 2500 })
-      return
+      // 本地 HLS 的播放列表 t=0 就是 resumePosition，位置由转码起点决定；但清单还没
+      // 回来、转码也可能直接失败，此刻同步弹「已恢复」就是一句空承诺。等画面真的出
+      // 数据（loadeddata）再报，和下面直连分支的行为保持一致。
+      const hlsVideo = ref.current
+      if (!hlsVideo) return
+      const confirmResume = () => {
+        if (cancelled) return
+        const el = ref.current
+        if (!el || el.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) return
+        setInitialSeekDone(true)
+        const m = Math.floor(resumePosition / 60)
+        const s = Math.floor(resumePosition % 60)
+        toast.success(`已恢复上次播放进度至 ${m.toString().padStart(2, '0')}:${s.toString().padStart(2, '0')}`, { duration: 2500 })
+      }
+      if (hlsVideo.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
+        confirmResume()
+        return
+      }
+      hlsVideo.addEventListener('loadeddata', confirmResume, { once: true })
+      return () => {
+        cancelled = true
+        hlsVideo.removeEventListener('loadeddata', confirmResume)
+      }
     }
     const video = ref.current
     if (!video) return
 
-    let cancelled = false
     let seekStarted = false
     let onPlaying: (() => void) | undefined
     let onCanPlay: (() => void) | undefined
@@ -1681,7 +1728,6 @@ export function PlayerPage() {
 
   // 使用 ref 实时同步进度计算所需的状态，避免每次 hlsStartSec 改变都触发 cleanup 并误上报旧进度
   const hlsStartSecRef = useRef(hlsStartSec)
-  const modeRef = useRef(mode)
   useEffect(() => {
     hlsStartSecRef.current = hlsStartSec
     hlsSourceRef.current = hlsSource
@@ -2245,6 +2291,73 @@ export function PlayerPage() {
     if (activeSkip) performSkip(activeSkip)
   }, [activeSkip, performSkip])
 
+  // ── 手动标记片头/片尾 ──────────────────────────────────────────────────────
+  // 服务端把手动标记的优先级排在最前，并按季传播到还没标记的集，所以这里只需
+  // 把「当前播放位置」发过去，再用返回的合并结果替换本地片段。
+  const manualMarkBusyRef = useRef(false)
+  const submitManualMark = useCallback(
+    (kind: 'intro' | 'credits', clear: boolean) => {
+      const current = mediaRef.current
+      if (!current?.id || manualMarkBusyRef.current) return
+      // 位置必须是源时间轴上的绝对秒数：本地 HLS 的 t=0 对应 hlsStartSec。
+      const video = ref.current
+      const positionSec = playbackPositionSec(
+        modeRef.current,
+        hlsSourceRef.current,
+        hlsStartSecRef.current,
+        video?.currentTime || 0,
+      )
+      const positionMs = Math.max(0, Math.round(positionSec * 1000))
+      if (!clear && positionMs <= 0) {
+        toast.error('当前位置为 0，请播放到片头结束后再标记')
+        return
+      }
+      manualMarkBusyRef.current = true
+      const markLabel = kind === 'intro' ? '片头' : '片尾'
+      const markTime = formatMarkTime(positionSec)
+      playbackAPI
+        .markSegment(current.id, {
+          kind,
+          position_ms: clear ? undefined : positionMs,
+          clear,
+        })
+        .then((res) => {
+          setRawSkipSegments(res.segments ?? [])
+          setAutoSkipIntro(Boolean(res.auto_skip))
+          setActiveSkip(null)
+          activeSkipKeyRef.current = ''
+          setDismissedSkipKinds([])
+          setAutoSuppressedKinds([])
+          if (clear) {
+            toast.success(`已清除${markLabel}标记`)
+          } else {
+            toast.success(`已标记${markLabel}：${markTime}（同季其它集已同步）`)
+          }
+        })
+        .catch(() => toast.error('标记保存失败，请稍后重试'))
+        .finally(() => {
+          manualMarkBusyRef.current = false
+        })
+    },
+    [],
+  )
+
+  const handleMarkIntro = useCallback(() => submitManualMark('intro', false), [submitManualMark])
+  const handleMarkOutro = useCallback(() => submitManualMark('credits', false), [submitManualMark])
+  const handleClearIntroMark = useCallback(() => submitManualMark('intro', true), [submitManualMark])
+  const handleClearOutroMark = useCallback(() => submitManualMark('credits', true), [submitManualMark])
+
+  // 已有手动标记的类型：用于按钮提示文案。只有手动标记可以清除，外部源的不算。
+  const markPresence = useMemo(() => {
+    let intro = false
+    let outro = false
+    for (const segment of rawSkipSegments) {
+      if (segment.kind === 'intro') intro = true
+      if (segment.kind === 'credits') outro = true
+    }
+    return { intro, outro }
+  }, [rawSkipSegments])
+
   const handleUndoSkip = useCallback(() => {
     const notice = skipNotice
     setSkipNotice(null)
@@ -2378,7 +2491,7 @@ export function PlayerPage() {
     if (retryingDirectRef.current) return
 
     const expectedSrc = mediaId
-      ? new URL(streamURL(mediaId, { proxy: vr360DirectProxyRef.current }), window.location.href).href
+      ? new URL(streamURL(mediaId, { proxy: vr360DirectProxyRef.current || directViaProxyRef.current }), window.location.href).href
       : ''
     const action = classifyDirectPlayError({
       errorCode: video?.error?.code,
@@ -2416,8 +2529,32 @@ export function PlayerPage() {
       return
     }
 
+    // STRM/115 直连重试仍失败：最常见的原因是 115 防盗链按 UA 拒绝——直链
+    // 绑定换链（302）时浏览器的 UA，但取流请求的 UA 可能不同（电视/WebView
+    // 的内核播放器、按站点改 UA 的扩展、改写 UA 的代理）。这在本机无法修复，
+    // 而服务端同源转发（?proxy=1）由 MeBox 用绑定 UA 取流、必然通过校验。
+    // 先用转发续播原画；仍失败再走 scheduleDirectFallback 退转码线路。
+    if (
+      video &&
+      mediaId &&
+      !directViaProxyRef.current &&
+      !vr360DirectProxyRef.current &&
+      isStrmMedia(mediaRef.current)
+    ) {
+      directViaProxyRef.current = true
+      clearFallbackTimer()
+      recordDiagnostic('error', '直连被 CDN 拒绝（多为 UA 防盗链），改用服务端转发重试')
+      const resumeAt = pendingDirectSeekRef.current ?? (video.currentTime > 2 ? video.currentTime : 0)
+      pendingDirectSeekRef.current = null
+      video.src = streamURL(mediaId, { proxy: true })
+      void video.play().catch(() => undefined)
+      if (resumeAt > 1) seekStrmDirectTo(resumeAt)
+      armDirectStallWatchdog()
+      return
+    }
+
     scheduleDirectFallback()
-  }, [mediaId, mode, scheduleDirectFallback, seekStrmDirectTo, showPlayFailure])
+  }, [armDirectStallWatchdog, clearFallbackTimer, mediaId, mode, recordDiagnostic, scheduleDirectFallback, seekStrmDirectTo, showPlayFailure])
 
   const changeSubtitlePosition = useCallback((nextPosition: SubtitlePosition) => {
     setSubtitlePosition(nextPosition)
@@ -2547,6 +2684,12 @@ export function PlayerPage() {
         onSkipPrompt={handleSkipClick}
         skipNotice={skipNotice ? { text: skipNotice.text } : null}
         onUndoSkip={handleUndoSkip}
+        onMarkIntro={handleMarkIntro}
+        onMarkOutro={handleMarkOutro}
+        onClearIntroMark={handleClearIntroMark}
+        onClearOutroMark={handleClearOutroMark}
+        hasIntroMark={markPresence.intro}
+        hasOutroMark={markPresence.outro}
         playlistPanel={
           isMobileTheater
             ? undefined

web/src/pages/PlayerVideoStage.tsx

@@ -242,6 +242,15 @@ type PlayerVideoStageProps = {
   /** 自动跳过后的撤销提示；null 表示不显示。 */
   skipNotice?: { text: string } | null
   onUndoSkip?: () => void
+  /** 手动标记：把当前位置记为片头结束 / 片尾开始。 */
+  onMarkIntro?: () => void
+  onMarkOutro?: () => void
+  /** 长按清除已有的片头 / 片尾标记。 */
+  onClearIntroMark?: () => void
+  onClearOutroMark?: () => void
+  /** 当前是否已有对应类型的标记（决定按钮文案与长按是否可用）。 */
+  hasIntroMark?: boolean
+  hasOutroMark?: boolean
   waiting?: boolean
   waitingMessage?: string
 }
@@ -312,6 +321,12 @@ export function PlayerVideoStage({
   onSkipPrompt,
   skipNotice = null,
   onUndoSkip,
+  onMarkIntro,
+  onMarkOutro,
+  onClearIntroMark,
+  onClearOutroMark,
+  hasIntroMark = false,
+  hasOutroMark = false,
   waiting = false,
   waitingMessage = '',
 }: PlayerVideoStageProps) {
@@ -335,6 +350,39 @@ export function PlayerVideoStage({
   const lockRevealTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const lockVisible = lockHovered || lockShown
   const vrActive = Boolean(vr360)
+  // 手动标记入口：画面左边缘一条半透明小白条，常态常驻（锁画面时才收），
+  // 点开才展开「片头 / 片尾」——展开的动作面板跟下面进度条同进同出。
+  // 悬停白条时按住操作栏：它不在操作栏自身的悬停判定范围内，鼠标停在上面时
+  // 操作栏会照常在三秒后收起，否则展开的面板会被一起带走。
+  const [markBarHovered, setMarkBarHovered] = useState(false)
+  const [markDockOpen, setMarkDockOpen] = useState(false)
+  const markDockRef = useRef<HTMLDivElement>(null)
+  const markDockVisible = !locked
+  const markPanelVisible = markDockVisible && controlsVisible
+
+  // 进度条收起（或画面锁定）就关掉标记面板：展开的动作跟操作栏同一套显隐规则。
+  useEffect(() => {
+    if (!markPanelVisible) setMarkDockOpen(false)
+  }, [markPanelVisible])
+
+  // 点画面别处、换片或按 Esc 都收起面板，避免它挂在那里挡住画面。
+  useEffect(() => {
+    if (!markDockOpen) return
+    const onDocPointerDown = (event: Event) => {
+      const dock = markDockRef.current
+      if (dock && event.target instanceof Node && dock.contains(event.target)) return
+      setMarkDockOpen(false)
+    }
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setMarkDockOpen(false)
+    }
+    document.addEventListener('pointerdown', onDocPointerDown, true)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('pointerdown', onDocPointerDown, true)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [markDockOpen])
   // VR 渲染器是否已经画出第一帧（在此之前给出「正在启动」提示，避免只看到黑屏）。
   // 只按「媒体 ID」记录：切换投影方式/画幅布局不会重建画布，也就不能清掉这个
   // 状态——渲染器只在挂载后上报一次就绪，清掉之后提示会一直停在「正在启动」。
@@ -552,6 +600,7 @@ export function PlayerVideoStage({
     // 锁上时立刻收起操作栏；解锁时也保持收起，这样画面在任何一侧都不会突然
     // 弹出一整条浮层。解锁那一下顺带显示「已解锁」提示。
     setControlsVisible(false)
+    setMarkBarHovered(false)
     revealLock(!next)
   }
 
@@ -561,6 +610,8 @@ export function PlayerVideoStage({
     setLockShown(false)
     setLockHint(false)
     setLockHovered(false)
+    setMarkBarHovered(false)
+    setMarkDockOpen(false)
     if (lockRevealTimerRef.current) {
       clearTimeout(lockRevealTimerRef.current)
       lockRevealTimerRef.current = null
@@ -892,7 +943,7 @@ export function PlayerVideoStage({
             onPlaybackRateChange={onPlayerPlaybackRateChange}
             uiVisible={controlsVisible && !locked}
             onUiVisibleChange={setControlsVisible}
-            uiHold={vrUiHovered}
+            uiHold={vrUiHovered || markBarHovered}
             uiLocked={locked}
             subs={subs}
             subtitleIndex={subtitleIndex}
@@ -966,6 +1017,80 @@ export function PlayerVideoStage({
           ) : null}
           {danmakuPanel}
           {playlistPanel}
+          {/* 手动标记片头/片尾：数据源查不到时用户自己标一次，服务端会按季传播。
+              常态只有画面左边缘一条半透明小白条；点开才展开「片头 / 片尾」，展开的
+              动作跟下面进度条同进同出。全屏时也一样，静止画面里只有这条小白条。
+              位置避开左侧居中的锁定按钮，不与它的悬停感应区重叠。 */}
+          {onMarkIntro || onMarkOutro ? (
+            <div
+              ref={markDockRef}
+              aria-hidden={!markDockVisible}
+              className={`absolute left-0 top-[78%] z-30 -translate-y-1/2 select-none transition duration-200 ${
+                markDockVisible ? 'opacity-100' : 'pointer-events-none -translate-x-1 opacity-0'
+              }`}
+              onPointerDown={(event) => event.stopPropagation()}
+              onClick={(event) => event.stopPropagation()}
+              onDoubleClick={(event) => event.stopPropagation()}
+              onPointerEnter={(event) => {
+                // 只有真鼠标才按住操作栏：触摸端抬起后拿不到可靠的离开信号。
+                if (event.pointerType === 'mouse') setMarkBarHovered(true)
+              }}
+              onPointerLeave={() => setMarkBarHovered(false)}
+            >
+              <div className="flex items-center">
+                <button
+                  type="button"
+                  tabIndex={markDockVisible ? 0 : -1}
+                  aria-expanded={markDockOpen}
+                  aria-label={markDockOpen ? '收起片头片尾标记' : '标记片头 / 片尾'}
+                  title={markDockOpen ? '收起' : '标记片头 / 片尾'}
+                  onClick={() => {
+                    // 展开的动作面板跟进度条走：操作栏收着时先把它亮出来。
+                    if (!markDockOpen) setControlsVisible(true)
+                    setMarkDockOpen((open) => !open)
+                  }}
+                  className="group flex h-12 items-center bg-transparent pl-0 pr-3 focus-visible:outline-none"
+                >
+                  <span
+                    className={`block h-10 rounded-r-full bg-white/40 shadow-[0_0_8px_rgba(0,0,0,0.55)] transition-all duration-200 group-hover:w-1.5 group-hover:bg-white/70 group-focus-visible:w-1.5 group-focus-visible:bg-white/90 ${
+                      markDockOpen ? 'w-1.5 bg-white/70' : 'w-1'
+                    }`}
+                  />
+                </button>
+                {markDockOpen && markPanelVisible ? (
+                  <div className="flex items-center gap-0.5 rounded-full border border-white/10 bg-black/70 py-0.5 pl-2 pr-0.5 text-[11px] text-white shadow-[0_6px_24px_rgba(0,0,0,0.45)] backdrop-blur-md">
+                    <span className="pr-0.5 text-[10px] tracking-wide text-white/40">标记</span>
+                    <button
+                      type="button"
+                      onClick={() => onMarkIntro?.()}
+                      onContextMenu={(event) => {
+                        if (!hasIntroMark) return
+                        event.preventDefault()
+                        onClearIntroMark?.()
+                      }}
+                      title={hasIntroMark ? '点击重新标记片头，右键清除' : '把当前位置标为片头结束'}
+                      className="rounded-full px-2.5 py-1 font-medium leading-4 text-white/75 transition hover:bg-white/15 hover:text-white"
+                    >
+                      片头
+                    </button>
+                    <button
+                      type="button"
+                      onClick={() => onMarkOutro?.()}
+                      onContextMenu={(event) => {
+                        if (!hasOutroMark) return
+                        event.preventDefault()
+                        onClearOutroMark?.()
+                      }}
+                      title={hasOutroMark ? '点击重新标记片尾，右键清除' : '把当前位置标为片尾开始'}
+                      className="rounded-full px-2.5 py-1 font-medium leading-4 text-white/75 transition hover:bg-white/15 hover:text-white"
+                    >
+                      片尾
+                    </button>
+                  </div>
+                ) : null}
+              </div>
+            </div>
+          ) : null}
         </>
       ) : loadError ? (
         <p className="max-w-[92%] text-center text-sm text-rose-400">{loadError}</p>

web/src/pages/librariesPageModel.ts

@@ -43,5 +43,12 @@ export function getLibraryArtworks(
   if (library.cover_url) {
     return [{ src: library.cover_url, version: library.updated_at }]
   }
+  // 服务端生成的库封面（成员海报竖切拼图）：所有客户端共用一张图，
+  // 不再由前端拿两张卡片自己拼格子。
+  // version 里带一个版次后缀：接口地址是固定的，靠它让浏览器在拼图规则
+  // 调整（如田字格改成竖切）后丢掉旧缓存重新拉图。
+  if (library.cover_image_url) {
+    return [{ src: library.cover_image_url, version: `${library.updated_at}-c3` }]
+  }
   return libraryArtworkItems(cards)
 }

web/src/pages/reader/ReaderAudioPanel.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { ChevronLeft, ChevronRight, Gauge, ListMusic, Loader2, Pause, Play, Scissors, Timer, X } from 'lucide-react'
+import { ChevronLeft, ChevronRight, Gauge, ListMusic, Loader2, Pause, Play, RefreshCw, Scissors, Timer, X } from 'lucide-react'
 import { Virtuoso, type VirtuosoHandle } from 'react-virtuoso'
 
 import { useReaderAudioStore } from '../../stores/readerAudio'
@@ -196,9 +196,21 @@ export function ReaderAudioPanel({ theme, onToggleMenu }: ReaderAudioPanelProps)
           </p>
           <p className="mt-1 text-2xs opacity-60" style={{ color: theme.text }}>
             {audioError ? (
-              <span className="font-bold" style={{ color: theme.accent }}>
-                {audioError}
-              </span>
+              // 失败态下这行就是重试入口：服务端这一轮要十几秒才判定失败，
+              // 与其让用户对着转圈，不如把「为什么」和「再试一次」一起给他。
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  engine.retry()
+                }}
+                className="inline-flex items-center gap-1 rounded-full px-2.5 py-1 text-2xs font-bold opacity-100"
+                style={{ backgroundColor: theme.accent + '1a', color: theme.accent }}
+                title="重新请求音源"
+              >
+                <RefreshCw size={12} />
+                {audioError} · 立即重试
+              </button>
             ) : (
               <>
                 {loading ? (transcoding ? '服务端转码中，请稍候…' : '加载中…') : playing ? '播放中' : '已暂停'} ·

web/src/pages/reader/ReaderBookPage.tsx

@@ -23,6 +23,9 @@ export default function ReaderBookPage() {
   const [info, setInfo] = useState<ReaderBookInfo | null>(null)
   const [infoError, setInfoError] = useState('')
   const [chapters, setChapters] = useState<ReaderTocChapter[] | null>(null)
+  // 目录拉取失败的原因（书源限流/失联）。有它时不再把空列表显示成「0 章」，
+  // 否则用户以为这本书真的没有目录。
+  const [tocError, setTocError] = useState('')
   const [shelfBook, setShelfBook] = useState<ReaderBook | null>(null)
   const [busy, setBusy] = useState(false)
   // 当前书源声明的类型（1 音频 / 2 图片），加入书架时写进来源记录
@@ -46,19 +49,48 @@ export default function ReaderBookPage() {
   useEffect(loadInfo, [bookURL])
 
   // 书架状态 + 目录
+  //
+  // 两个请求都依赖书源上游，而聚合源的免费后端经常限流（HTTP 429）。目录失败时
+  // 不再静默显示「0 章」：先退回书架里的目录缓存（至少能看章节、点开阅读），
+  // 没有缓存才把失败原因交给目录区展示，用户点「重试」即可。
   useEffect(() => {
     if (!bookURL) return
-    readerAPI
-      .listBooks()
-      .then((books) => {
-        const hit = books.find((b) => b.book_url === bookURL && b.origin === sourceURL) ?? null
-        setShelfBook(hit)
-      })
-      .catch(() => undefined)
-    readerAPI
-      .toc({ source_url: sourceURL, book_url: bookURL, toc_url: bookURL })
-      .then(setChapters)
-      .catch(() => setChapters([]))
+    let alive = true
+    setChapters(null)
+    setTocError('')
+    ;(async () => {
+      let shelf: ReaderBook | null = null
+      try {
+        const books = await readerAPI.listBooks()
+        shelf = books.find((b) => b.book_url === bookURL && b.origin === sourceURL) ?? null
+      } catch {
+        // 书架读取失败不影响详情页展示
+      }
+      if (!alive) return
+      setShelfBook(shelf)
+      try {
+        const list = await readerAPI.toc({ source_url: sourceURL, book_url: bookURL, toc_url: bookURL })
+        if (!alive) return
+        setChapters(list)
+      } catch (e) {
+        if (!alive) return
+        const msg = (e as { response?: { data?: { error?: string } } })?.response?.data?.error ?? '目录加载失败'
+        if (shelf) {
+          const cached = await readerAPI.listChapters(shelf.id).catch(() => [])
+          if (!alive) return
+          if (cached.length > 0) {
+            setChapters(cached.map((c) => ({ ...c, update_time: '' })))
+            setTocError(`${msg}（已显示书架缓存）`)
+            return
+          }
+        }
+        setChapters([])
+        setTocError(msg)
+      }
+    })()
+    return () => {
+      alive = false
+    }
   }, [bookURL, sourceURL])
 
   // 书源声明的类型（1 音频 / 2 图片）。加入书架时要带上它：写死成 0（文本）会让
@@ -77,7 +109,10 @@ export default function ReaderBookPage() {
     if (!tocURL || tocURL === bookURL) return
     readerAPI
       .toc({ source_url: sourceURL, book_url: bookURL, toc_url: tocURL })
-      .then(setChapters)
+      .then((list) => {
+        setChapters(list)
+        setTocError('')
+      })
       .catch(() => undefined)
   }, [info?.toc_url, sourceURL, bookURL])
 
@@ -142,9 +177,12 @@ export default function ReaderBookPage() {
     try {
       const list = await readerAPI.toc({ source_url: sourceURL, book_url: bookURL, toc_url: info?.toc_url || bookURL })
       setChapters(list)
+      setTocError('')
       toast.success(`目录已刷新，共 ${list.length} 章`)
-    } catch {
-      toast.error('目录刷新失败')
+    } catch (e) {
+      const msg = (e as { response?: { data?: { error?: string } } })?.response?.data?.error ?? '目录刷新失败'
+      setTocError(msg)
+      toast.error(msg)
     } finally {
       setBusy(false)
     }
@@ -256,7 +294,7 @@ export default function ReaderBookPage() {
             </p>
           )}
           <p className="mt-1 truncate text-xs text-[var(--app-muted)]">
-            最新：<span className="text-[var(--app-text)]">{info?.latest_chapter || '加载中…'}</span>
+            最新：<span className="text-[var(--app-text)]">{info?.latest_chapter || (info ? '—' : '加载中…')}</span>
           </p>
           <p className="mt-0.5 text-2xs text-[var(--app-muted)]">书源：{originName || sourceURL}</p>
           {(info?.intro || infoError) && (
@@ -264,7 +302,15 @@ export default function ReaderBookPage() {
               <p className={`text-xs leading-5 text-[var(--app-subtle)] ${introExpanded ? '' : 'line-clamp-3'}`}>
                 {infoError || info?.intro}
               </p>
-              {!infoError && (
+              {infoError ? (
+                <button
+                  type="button"
+                  onClick={loadInfo}
+                  className="mt-1 inline-flex items-center text-2xs font-bold text-brand-600"
+                >
+                  重试
+                </button>
+              ) : (
                 <button
                   type="button"
                   onClick={() => setIntroExpanded((v) => !v)}
@@ -308,7 +354,10 @@ export default function ReaderBookPage() {
       <div className="mt-8">
         <div className="flex items-center justify-between border-b border-[var(--app-border)] pb-2">
           <p className="text-sm font-bold text-[var(--app-text)]">
-            目录 {chapters !== null && <span className="text-xs font-normal text-[var(--app-muted)]">（{chapters.length} 章）</span>}
+            目录{' '}
+            {chapters !== null && (chapters.length > 0 || !tocError) && (
+              <span className="text-xs font-normal text-[var(--app-muted)]">（{chapters.length} 章）</span>
+            )}
           </p>
           {chapters !== null && chapters.length > 20 && (
             <button
@@ -320,6 +369,19 @@ export default function ReaderBookPage() {
             </button>
           )}
         </div>
+        {tocError && (
+          <div className="mt-2 flex items-center gap-2 rounded-lg bg-[var(--app-panel-soft)] px-3 py-2 text-2xs text-[var(--app-muted)]">
+            <span className="min-w-0 flex-1">{tocError}</span>
+            <button
+              type="button"
+              onClick={refreshToc}
+              disabled={busy}
+              className="shrink-0 font-bold text-brand-600 disabled:opacity-50"
+            >
+              重试
+            </button>
+          </div>
+        )}
         {chapters === null ? (
           <div className="flex justify-center py-10 text-[var(--app-muted)]">
             <Loader2 className="animate-spin" size={20} />

web/src/pages/reader/readerAudioEngine.ts

@@ -22,6 +22,15 @@ import { readerCoverSrc } from '../../utils/readerCover'
 const PROGRESS_SAVE_INTERVAL_MS = 5_000
 /** -15s / +15s 步长（对齐面板与 legado SEEK_STEP）。 */
 const SEEK_STEP = 15
+/**
+ * 音源加载失败后自动重试的退避间隔（毫秒），数组长度即自动重试次数。
+ *
+ * 别调得太短：服务端媒体代理要回源换票、拉整章音频，失败一次本身就要十几秒，
+ * 立刻重试只会让用户对着转圈更久。第一次 3 秒、第二次 9 秒，总等待可控。
+ */
+const AUDIO_RETRY_DELAYS_MS = [3_000, 9_000]
+/** 自动重试次数上限（与退避表的长度一致）。 */
+const AUDIO_RETRY_LIMIT = AUDIO_RETRY_DELAYS_MS.length
 
 export interface LoadChapterInput {
   bookId: string
@@ -78,6 +87,10 @@ class ReaderAudioEngine {
   private warmer: HTMLAudioElement | null = null
   /** warmer 当前装载的音轨，避免重复赋值。 */
   private warmedTrack = ''
+  /** 当前章已自动重试的次数（换章/加载成功时清零）。 */
+  private retryCount = 0
+  /** 自动重试的定时器句柄。 */
+  private retryTimer: number | null = null
 
   constructor() {
     const audio = new Audio()
@@ -107,6 +120,8 @@ class ReaderAudioEngine {
     }
     // 换章前把上一章的最后位置补报掉（此时 store 里还是上一章的上下文）
     this.commitProgress()
+    // 换章是一次全新的加载：清掉上一章遗留的自动重试计数/定时器
+    this.resetRetry()
     // 换书：预取的音轨属于上一本，全部作废
     if (s.bookId !== input.bookId) this.clearPrefetch()
     this.applyChapter(input)
@@ -175,10 +190,23 @@ class ReaderAudioEngine {
   }
 
   toggle(): void {
+    // 失败态下播放键就是「重试」：重新解析本章音轨（换一张签名票）再装源，
+    // 而不是对着一份已经出错的 src 再调 play()。
+    if (useReaderAudioStore.getState().status === 'error') {
+      this.retry()
+      return
+    }
     if (this.audio.paused) this.play()
     else this.pause()
   }
 
+  /** 用户手动重试：清掉自动重试计数与待执行定时器，立刻重新解析本章音轨。 */
+  retry(): void {
+    this.resetRetry()
+    useReaderAudioStore.setState({ status: 'loading', error: '' })
+    void this.reloadCurrentChapter()
+  }
+
   seekBy(delta: number): void {
     const total = Number.isFinite(this.audio.duration)
       ? this.audio.duration
@@ -244,6 +272,7 @@ class ReaderAudioEngine {
   /** 完全停止并清空状态（迷你播放器的关闭按钮）。 */
   stop(): void {
     this.commitProgress()
+    this.resetRetry()
     this.detachSource()
     this.clearPrefetch()
     this.timerDeadline = 0
@@ -457,10 +486,80 @@ class ReaderAudioEngine {
   }
 
   private fail(message: string): void {
+    this.resetRetry()
     useReaderAudioStore.setState({ status: 'error', error: message })
     this.setSessionPlaybackState('paused')
   }
 
+  // ─── 失败自动重试 ─────────────────────────────────────────────────────
+
+  /** 清掉自动重试计数与待执行的定时器（换章、停止、最终失败时调用）。 */
+  private resetRetry(): void {
+    this.retryCount = 0
+    if (this.retryTimer !== null) {
+      window.clearTimeout(this.retryTimer)
+      this.retryTimer = null
+    }
+  }
+
+  /**
+   * 退避后再重新解析本章音轨。
+   *
+   * 期间刻意停留在 error 态而不是 loading：服务端这次请求本来就要十几秒才判定
+   * 失败，再挂一个转圈只会让人以为卡死。明确告诉他「几秒后自动重试」，并且这
+   * 行提示本身可以点，等于把等待权交回用户。
+   */
+  private scheduleRetry(): void {
+    if (this.retryTimer !== null) window.clearTimeout(this.retryTimer)
+    const delay = AUDIO_RETRY_DELAYS_MS[Math.min(this.retryCount - 1, AUDIO_RETRY_LIMIT - 1)]
+    useReaderAudioStore.setState({
+      status: 'error',
+      error: `音源暂时取不到，${Math.round(delay / 1000)} 秒后自动重试`,
+    })
+    this.retryTimer = window.setTimeout(() => {
+      this.retryTimer = null
+      useReaderAudioStore.setState({ status: 'loading', error: '' })
+      void this.reloadCurrentChapter()
+    }, delay)
+  }
+
+  /**
+   * 重新取一次章节内容再装源。服务端媒体代理会在签名票失效/上游抖动时
+   * 重新回源签票；重新取内容能拿到新的签名地址，比原样重试同一个 URL 有效。
+   */
+  private async reloadCurrentChapter(): Promise<void> {
+    const s = useReaderAudioStore.getState()
+    if (!s.bookId) {
+      this.fail('音频加载失败，请稍后重试')
+      return
+    }
+    const token = this.loadToken
+    const resumeAt = this.lastTime > 0 ? this.lastTime : s.cur
+    try {
+      const ct = await readerAPI.bookContent(s.bookId, s.chapterIndex)
+      if (token !== this.loadToken) return
+      const track = ct.tracks?.[0]
+      if (ct.type !== 'audio' || !track) {
+        this.fail('本章没有可播放的音频')
+        return
+      }
+      this.applyChapter({
+        bookId: s.bookId,
+        bookName: s.bookName,
+        cover: s.cover,
+        chapters: s.chapters,
+        chapterIndex: s.chapterIndex,
+        track,
+        transcoding: ct.transcoding ?? false,
+        openCredits: s.openCredits,
+        closeCredits: s.closeCredits,
+        initialPos: resumeAt,
+      })
+    } catch {
+      this.fail('音频加载失败，请稍后重试')
+    }
+  }
+
   // ─── <audio> 事件 ─────────────────────────────────────────────────────
 
   private bindAudio(): void {
@@ -546,11 +645,22 @@ class ReaderAudioEngine {
 
     audio.addEventListener('error', () => {
       const code = audio.error?.code
+      // 服务端代理拉的是第三方 CDN 的直链，跨境链路会偶发被上游拒绝 / 中途断流。
+      // 浏览器对这两种情况都报 SRC_NOT_SUPPORTED（看起来像「格式不支持」），
+      // 实际上重新取一次章节（换一张签名票）通常就能播，所以先自动重试。
+      const retryable =
+        code === MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED || code === MediaError.MEDIA_ERR_NETWORK
+      if (retryable && this.retryCount < AUDIO_RETRY_LIMIT) {
+        this.retryCount++
+        this.scheduleRetry()
+        return
+      }
+      // 重试用完：文案要能解释「为什么播不了」，并且面板上这行本身就是重试按钮。
       this.fail(
         code === MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED
-          ? '浏览器无法播放该音频格式，且服务端转码不可用（请检查 ffmpeg 是否已安装）'
+          ? '音源暂时被上游拒绝'
           : code === MediaError.MEDIA_ERR_NETWORK
-            ? '音频加载失败，请检查网络或源文件是否还在'
+            ? '网络异常，音源没取到'
             : '音频无法播放',
       )
     })

web/src/pages/settingsGroupGeneral.ts

@@ -23,11 +23,24 @@ export const generalSettingsGroup: SettingGroup = {
       hint: '默认关闭。开启后宿主机不再进行任何 FFmpeg 转码，所有播放交给第三方客户端（Infuse / VLC / Emby 客户端等）或浏览器本地解码直连（direct play / 302 直链），大幅降低宿主机 CPU 占用。若客户端不支持源编码可能无法播放。',
       defaultValue: 'false',
     },
+    {
+      key: 'segment.source',
+      label: '片头/片尾数据源',
+      type: 'select',
+      hint: '选择查询哪个社区库来补全片头/片尾时间点。TheIntroDB 数据最全（按 TMDb id）；IntroDB 只认 IMDb id，需要 TMDb 已配置 API key 才能解析；TODb 偏华语片源、按平台版本记录。选「关闭」后只使用本地已有数据（含手动标记），不再请求外网。',
+      defaultValue: 'theintrodb',
+      options: [
+        { value: 'theintrodb', label: 'TheIntroDB' },
+        { value: 'introdb', label: 'IntroDB' },
+        { value: 'todb', label: 'TODb（TheOtherDB）' },
+        { value: 'off', label: '关闭' },
+      ],
+    },
     {
       key: 'segment.prewarm_enabled',
-      label: '后台预热 IntroDB 片头片段',
+      label: '后台预热片头片段',
       type: 'toggle',
-      hint: '默认关闭。开启后每 6 小时在后台向 TheIntroDB 拉取可识别媒体的片头/片尾区间并写入本地；关闭时仅在播放时按需请求。',
+      hint: '默认关闭。开启后每 6 小时在后台向上面选择的数据源拉取可识别媒体的片头/片尾区间并写入本地；关闭时仅在播放时按需请求。',
       defaultValue: 'false',
     },
     {
@@ -116,28 +129,20 @@ export const generalSettingsGroup: SettingGroup = {
     },
     {
       key: 'cache.images_max_size_mb',
-      label: '图片缓存上限 (MB)',
+      label: '磁盘缓存总容量上限 (MB)',
       type: 'number',
-      hint: '海报、剧照等图片代理缓存目录 (cache/images) 的总占用上限。超过上限时先淘汰原图、再按修改时间清理最旧的缩略图；上限过小会导致旧图被淘汰后又要重新从上游/挂载的 Emby 下载。设为 0 表示不限制，默认 2000MB',
-      defaultValue: '2000',
-      placeholder: '2000',
+      hint: '磁盘缓存（hls、images、library-covers）的总占用上限。超过上限时严格按「转码 HLS → 图片 → 媒体库封面」的顺序淘汰最旧的文件，直到回落到上限的 80%。有声书转码缓存（reader-audio）另有 1GB 写入时淘汰，不计入这里。设为 0 表示不限制，默认 2048MB（2GB）',
+      defaultValue: '2048',
+      placeholder: '2048',
     },
     {
       key: 'cache.images_originals_max_size_mb',
-      label: '原图缓存上限 (MB)',
+      label: '图片原图缓存上限 (MB)',
       type: 'number',
-      hint: '原图只是生成缩略图的原料，丢了可以重新回源，因此单独给一个小配额（默认 256MB）。总量超限时原图也优先被淘汰，保证客户端实际读取的缩略图能留住。设为 0 表示不单独限制',
+      hint: 'originals 子目录的独立配额（默认 256MB）。原图只是生成缩略图的原料，丢了可以重新回源，因此单独给小配额；图片池被淘汰时优先删原图，保证客户端实际读取的缩略图能留住。设为 0 表示不单独限制',
       defaultValue: '256',
       placeholder: '256',
     },
-    {
-      key: 'cache.images_originals_ttl_hours',
-      label: '原图保留时长 (小时)',
-      type: 'number',
-      hint: '原图缓存的最长保留时间，超过即删除（默认 168 小时 = 7 天）。缩略图都已生成时原图就不再需要，缩短它可以让原图缓存保持在一个滚动窗口内。设为 0 表示不按时间淘汰',
-      defaultValue: '168',
-      placeholder: '168',
-    },
     {
       key: 'https.enabled',
       label: '启用 HTTPS',

web/src/types/library.ts

@@ -15,6 +15,12 @@ export interface Library {
   path: string
   type: string
   cover_url?: string
+  /**
+   * 服务端生成的封面地址（成员海报拼图）。管理员自定义 cover_url 时等于
+   * 该地址，否则指向 `/api/libraries/:id/cover`。Web/App 统一读这个字段，
+   * 不用再自己用卡片拼格子。
+   */
+  cover_image_url?: string
   enabled: boolean
   sort_order?: number
   carousel_enabled?: boolean

web/src/utils/skipSegments.test.ts

@@ -15,7 +15,7 @@ function equal<T>(name: string, actual: T, expected: T) {
 check('空片段返回空数组', toSkipSegments(null, 600).length === 0)
 check('空数组返回空数组', toSkipSegments([], 600).length === 0)
 
-// end_ms: 0 表示延续到片尾，用媒体时长补齐。
+// end_ms: 0 只在片尾类（credits/preview）表示「延续到片尾」，用媒体时长补齐。
 const resolved = toSkipSegments(
   [
     { kind: 'intro', start_ms: 228_664, end_ms: 246_143 },
@@ -28,6 +28,17 @@ equal('片头起点(秒)', resolved[0].startSec, 228.664)
 equal('片头终点(秒)', resolved[0].endSec, 246.143)
 equal('片尾终点补齐为总时长', resolved[1].endSec, 3600)
 
+// 片头 / 回顾的 end_ms: 0 是数据源的「这段不存在」占位（TheIntroDB 官方语义），
+// 绝不能补齐成总时长——那会让整集都落在片头区间里，一开播就弹跳过按钮。
+check(
+  '片头 end_ms=0 不得补齐为整集',
+  toSkipSegments([{ kind: 'intro', start_ms: 0, end_ms: 0 }], 3600).length === 0,
+)
+check(
+  '回顾 end_ms=0 不得补齐为整集',
+  toSkipSegments([{ kind: 'recap', start_ms: 0, end_ms: 0 }], 3600).length === 0,
+)
+
 // 时长未知时，开放区间必须丢弃：否则会算出一个永远命中的区间。
 check(
   '时长未知时丢弃开放区间',

web/src/utils/skipSegments.ts

@@ -33,8 +33,11 @@ export function skippedNoticeText(kind: PlaybackSegmentKind): string {
 /**
  * 把服务端返回的片段换算成源时间轴上的秒区间。
  *
- * end_ms === 0 表示区间延续到片尾，用媒体总时长补齐；时长未知（0 / 非有限值）
- * 时丢弃该区间——否则会算出一个永远命中的区间，浮层上的按钮就再也点不掉了。
+ * end_ms === 0 是「一直到片尾」的哨兵值，只有片尾类（credits / preview）会这么
+ * 返回，用媒体总时长补齐。片头 / 回顾出现 0 一律丢弃：那通常意味着数据源根本没
+ * 给出结束点（TheIntroDB 用 end_ms: 0 表示「这段不存在」），补成总时长会让整集
+ * 都落在「片头」区间里，一开播就弹跳过按钮。时长未知（0 / 非有限值）同样丢弃，
+ * 否则会算出一个永远命中的区间，浮层上的按钮就再也点不掉了。
  */
 export function toSkipSegments(
   segments: PlaybackSegment[] | null | undefined,
@@ -44,9 +47,16 @@ export function toSkipSegments(
   const out: SkipSegment[] = []
   for (const segment of segments) {
     const startSec = Math.max(0, segment.start_ms / 1000)
-    const endSec = segment.end_ms > 0 ? segment.end_ms / 1000 : durationSec
-    if (!Number.isFinite(endSec) || endSec <= startSec) continue
-    out.push({ kind: segment.kind, startSec, endSec })
+    const openEnded = segment.kind === 'credits' || segment.kind === 'preview'
+    if (segment.end_ms > 0) {
+      const endSec = segment.end_ms / 1000
+      if (!Number.isFinite(endSec) || endSec <= startSec) continue
+      out.push({ kind: segment.kind, startSec, endSec })
+      continue
+    }
+    if (!openEnded) continue
+    if (!Number.isFinite(durationSec) || durationSec <= startSec) continue
+    out.push({ kind: segment.kind, startSec, endSec: durationSec })
   }
   return out.sort((a, b) => a.startSec - b.startSec)
 }