优化

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

internal/handler/reader_media_test.go

@@ -0,0 +1,525 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	"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)
+	}
+}
+
+// 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)
+	}
+}
+
+// TestReaderAudioCacheRejectsTruncatedUpstream 音轨拉不完整时重试；全部失败回 502，
+// 且不能留下半截缓存文件（否则后续会把截断的音频当完整文件下发）。
+func TestReaderAudioCacheRejectsTruncatedUpstream(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")
+
+	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)
+	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
+}
+
+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++
+			s.mu.Unlock()
+			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()
+}
+
+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
+}

internal/handler/reader_routes.go

@@ -2,13 +2,22 @@
 package handler
 
 import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
+	"path"
 	"strconv"
 	"strings"
+	"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"
@@ -403,6 +412,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 +882,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 +920,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 +933,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 +958,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 +968,476 @@ 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
+	// readerAudioCacheRetryDelay 重试退避基数，实际等待为 (attempt-1) 倍。
+	readerAudioCacheRetryDelay = 500 * time.Millisecond
+	// readerAudioCacheMaxBytes 单个音频的落盘上限。有声书一章约 3–5MB，
+	// 给到 64MB 足够容纳长章节，也能挡住误当成音频的超大对象。
+	readerAudioCacheMaxBytes = 64 << 20
+	// readerMediaReissueAttempts 换票重试次数：跨境 CDN 的「空 401」是概率性的，
+	// 一张票不行往往换一张就好；旧实现只换一次，第二次失败就把 502 交给播放器。
+	readerMediaReissueAttempts = 3
+	readerMediaReissueDelay    = 300 * time.Millisecond
+)
+
+// readerAudioFetchGroup 同一音轨并发请求（播放器 + 预取 + 预热）只下载一次。
+var readerAudioFetchGroup singleflight.Group
+
+// handleCachedReaderAudio 音频直链的统一入口：先查本地缓存，未命中则整段拉取落盘，
+// 最后交给 http.ServeContent 处理 Range（拖动进度、续播都读本地文件）。
+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
+	}
+	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)
+}
+
+// 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 整段拉取并落盘：上游断流/换票失败时重试，
+// 落盘后按 Content-Length 校验长度，防止把截断的音频缓存下来。
+func downloadReaderAudioToCache(
+	ctx context.Context,
+	svc *service.Container,
+	book *model.ReaderBook,
+	bookID, rawURL string,
+	headers map[string]string,
+) error {
+	var lastErr error
+	for attempt := 1; attempt <= readerAudioCacheAttempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(readerAudioCacheRetryDelay * time.Duration(attempt-1)):
+			}
+		}
+		out, err := fetchReaderMediaResilient(ctx, svc, book, rawURL, "", headers, true)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		if out == nil || out.resp == nil {
+			lastErr = fmt.Errorf("音源响应为空")
+			continue
+		}
+		resp := out.resp
+		status := resp.StatusCode
+		if status != http.StatusOK && status != http.StatusPartialContent {
+			_ = resp.Body.Close()
+			lastErr = fmt.Errorf("音源返回 %d", status)
+			continue
+		}
+		expected := resp.ContentLength
+		path, storeErr := svc.Reader.StoreCachedRemoteAudio(bookID, rawURL, func(w io.Writer) error {
+			if len(out.head) > 0 {
+				if _, err := w.Write(out.head); err != nil {
+					return err
+				}
+			}
+			return copyLimited(w, resp.Body, readerAudioCacheMaxBytes)
+		})
+		_ = resp.Body.Close()
+		if storeErr != nil {
+			lastErr = storeErr
+			continue
+		}
+		if expected > 0 {
+			info, statErr := os.Stat(path)
+			if statErr != nil {
+				_ = os.Remove(path)
+				lastErr = fmt.Errorf("音频缓存写入后不可读: %w", statErr)
+				continue
+			}
+			if info.Size() != expected {
+				_ = os.Remove(path)
+				lastErr = fmt.Errorf("音频写入不完整（%d/%d 字节）", info.Size(), expected)
+				continue
+			}
+		}
+		return nil
+	}
+	if lastErr == nil {
+		lastErr = fmt.Errorf("音源拉取失败")
+	}
+	return fmt.Errorf("已重试 %d 次: %w", readerAudioCacheAttempts, lastErr)
+}
+
+// copyLimited 复制响应体，超过上限时报错（避免把超大对象写进缓存）。
+func copyLimited(w io.Writer, r io.Reader, limit int64) error {
+	n, err := io.Copy(w, io.LimitReader(r, limit+1))
+	if err != nil {
+		return err
+	}
+	if n > limit {
+		return fmt.Errorf("音源超过 %d 字节上限", limit)
+	}
+	return nil
+}
+
+// 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 等）→ 原样透传上游状态，
+//     不改变原有行为；
+//   - 该换票但换不到、或换票后依然不可用 → 返回错误，由调用方给出明确文案，
+//     而不是让播放器对着必然失败的地址反复重试。
+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, fmt.Errorf("音源签名失效（上游 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", 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, fmt.Errorf("音源换票后仍返回非媒体内容，请稍后重试或换源")
+	}
+	if reader.MediaNeedsRefresh(retried.resp.StatusCode) {
+		return nil, fmt.Errorf("音源换票后仍被拒绝（上游 %d），请稍后重试或换源", retried.resp.StatusCode)
+	}
+	return retried, nil
+}
+
+// fetchReaderMediaResilient 在 fetchReaderMedia（已含一次换票）之上再包一层。
+//
+// 跨境 CDN 判掉签名票是概率性的：换一张票往往就能取到，而旧实现只换一次，
+// 第二次失败直接把 502 交给播放器。这里最多再重来 readerMediaReissueAttempts 轮，
+// 每轮都会作废章节缓存、重新回源签票。不可恢复的 4xx（如 404）原样返回，
+// 不做无意义的等待。
+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
+	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
+			}
+			lastErr = fmt.Errorf("音源换票后仍不可用（上游 %d）", out.resp.StatusCode)
+			_ = out.resp.Body.Close()
+			continue
+		}
+		lastErr = err
+		if ctx.Err() != nil {
+			return nil, err
+		}
+	}
+	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 {

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/service/reader/audio_media_cache.go

@@ -0,0 +1,222 @@
+package reader
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// 远端音轨的本地落盘缓存（媒体代理 /api/reader/media 使用）。
+//
+// 背景：听书源的音频直链签在腾讯音乐 CDN 上，跨境链路会间歇性返回 401
+// 或直接 RST 连接。旧行为是每次请求（首播、拖动进度、播放器重试）都重新
+// 回源，一次抖动就把错误交给播放器。这里按「书 + 媒体对象路径」把整段音频
+// 落盘（忽略 ?vkey=... 这类会轮换的签名参数），命中后由 http.ServeContent
+// 按 Range 下发：首播成功之后不再依赖 CDN，拖动进度也是本地读取。
+
+const (
+	audioMediaDirName      = "reader-audio"
+	audioMediaTTL          = 7 * 24 * time.Hour
+	audioMediaMaxBytes     = 2 << 30 // 2GiB：超出后按 mtime 淘汰最旧的
+	audioMediaPrunePeriod  = 10 * time.Minute
+	audioMediaPruneKeepPct = 90
+)
+
+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)
+}
+
+// audioMediaCacheKey 缓存键：书 + scheme://host/path。
+//
+// 必须忽略 query：同一段音频每次换票都会得到新的 vkey/uid/ct，只按完整 URL
+// 取哈希的话缓存永远打不中。
+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()
+	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
+}
+
+// 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
+}
+
+// StoreCachedRemoteAudio 把一段音源原子写入缓存，fill 负责把内容写进 writer。
+// 返回最终文件路径；内容为空或写入失败时不留下半成品。
+func (s *ReaderService) StoreCachedRemoteAudio(bookID, mediaURL string, fill func(io.Writer) error) (string, error) {
+	path := s.RemoteAudioCachePath(bookID, mediaURL)
+	if path == "" {
+		return "", errors.New("音频缓存目录未配置")
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o750); err != nil {
+		return "", fmt.Errorf("创建音频缓存目录失败: %w", err)
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(path), ".audio-*")
+	if err != nil {
+		return "", fmt.Errorf("创建音频缓存文件失败: %w", err)
+	}
+	tmpName := tmp.Name()
+	fillErr := fill(tmp)
+	closeErr := tmp.Close()
+	if fillErr != nil || closeErr != nil {
+		_ = os.Remove(tmpName)
+		if fillErr != nil {
+			return "", fillErr
+		}
+		return "", closeErr
+	}
+	info, statErr := os.Stat(tmpName)
+	if statErr != nil || info.Size() == 0 {
+		_ = os.Remove(tmpName)
+		return "", errors.New("音源内容为空")
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		_ = os.Remove(tmpName)
+		return "", fmt.Errorf("写入音频缓存失败: %w", err)
+	}
+	s.pruneAudioMediaCache()
+	return path, nil
+}
+
+// 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,41 @@
+package reader
+
+import "testing"
+
+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，缓存键必须只看
+// scheme + host + path，否则每次换票都会重新下载一遍。
+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("不同对象的缓存键不应相同")
+	}
+}

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_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)
+	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)
+	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)
+	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); 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)
+	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)
 
@@ -1801,7 +1902,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
 	}
@@ -1942,12 +2043,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 +2163,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 +2617,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 +2634,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 +2695,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

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)
+	}
+}

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/PlayerPage.tsx

@@ -139,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)
@@ -556,6 +560,7 @@ export function PlayerPage() {
     setDanmakuInfo(null)
     setDanmakuSearching(true)
     directRetryRef.current = false
+    directViaProxyRef.current = false
     retryingDirectRef.current = false
     directSeekGraceUntilRef.current = 0
     transientPlayErrorRef.current = ''
@@ -1485,7 +1490,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 的中断。
@@ -2455,7 +2460,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,
@@ -2493,8 +2498,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)

web/src/pages/PlayerVideoStage.tsx

@@ -350,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」记录：切换投影方式/画幅布局不会重建画布，也就不能清掉这个
   // 状态——渲染器只在挂载后上报一次就绪，清掉之后提示会一直停在「正在启动」。
@@ -567,6 +600,7 @@ export function PlayerVideoStage({
     // 锁上时立刻收起操作栏；解锁时也保持收起，这样画面在任何一侧都不会突然
     // 弹出一整条浮层。解锁那一下顺带显示「已解锁」提示。
     setControlsVisible(false)
+    setMarkBarHovered(false)
     revealLock(!next)
   }
 
@@ -576,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
@@ -907,7 +943,7 @@ export function PlayerVideoStage({
             onPlaybackRateChange={onPlayerPlaybackRateChange}
             uiVisible={controlsVisible && !locked}
             onUiVisibleChange={setControlsVisible}
-            uiHold={vrUiHovered}
+            uiHold={vrUiHovered || markBarHovered}
             uiLocked={locked}
             subs={subs}
             subtitleIndex={subtitleIndex}
@@ -982,45 +1018,77 @@ export function PlayerVideoStage({
           {danmakuPanel}
           {playlistPanel}
           {/* 手动标记片头/片尾：数据源查不到时用户自己标一次，服务端会按季传播。
-              放在左下角，与右侧的「跳过」按钮分开，避免误触。 */}
-          {!locked && (onMarkIntro || onMarkOutro) ? (
+              常态只有画面左边缘一条半透明小白条；点开才展开「片头 / 片尾」，展开的
+              动作跟下面进度条同进同出。全屏时也一样，静止画面里只有这条小白条。
+              位置避开左侧居中的锁定按钮，不与它的悬停感应区重叠。 */}
+          {onMarkIntro || onMarkOutro ? (
             <div
-              className="absolute bottom-16 left-3 z-30 flex items-center gap-1.5 rounded-xl border border-white/15 bg-black/70 px-1.5 py-1.5 text-xs text-white shadow-[0_8px_28px_rgba(0,0,0,0.5)] backdrop-blur-md sm:bottom-20 sm:left-5"
+              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)}
             >
-              <span className="px-1.5 text-white/55">标记</span>
-              <button
-                type="button"
-                onClick={(event) => {
-                  event.stopPropagation()
-                  onMarkIntro?.()
-                }}
-                onContextMenu={(event) => {
-                  if (!hasIntroMark) return
-                  event.preventDefault()
-                  onClearIntroMark?.()
-                }}
-                title={hasIntroMark ? '点击重新标记片头，右键清除' : '把当前位置标为片头结束'}
-                className="rounded-lg bg-white/10 px-2.5 py-1 font-medium transition hover:bg-white/20"
-              >
-                片头
-              </button>
-              <button
-                type="button"
-                onClick={(event) => {
-                  event.stopPropagation()
-                  onMarkOutro?.()
-                }}
-                onContextMenu={(event) => {
-                  if (!hasOutroMark) return
-                  event.preventDefault()
-                  onClearOutroMark?.()
-                }}
-                title={hasOutroMark ? '点击重新标记片尾，右键清除' : '把当前位置标为片尾开始'}
-                className="rounded-lg bg-white/10 px-2.5 py-1 font-medium transition hover:bg-white/20"
-              >
-                片尾
-              </button>
+              <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}
         </>

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,8 @@ import { readerCoverSrc } from '../../utils/readerCover'
 const PROGRESS_SAVE_INTERVAL_MS = 5_000
 /** -15s / +15s 步长（对齐面板与 legado SEEK_STEP）。 */
 const SEEK_STEP = 15
+/** 音源加载失败后自动重试（重新换取签名地址）的次数上限。 */
+const AUDIO_RETRY_LIMIT = 2
 
 export interface LoadChapterInput {
   bookId: string
@@ -78,6 +80,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 +113,8 @@ class ReaderAudioEngine {
     }
     // 换章前把上一章的最后位置补报掉（此时 store 里还是上一章的上下文）
     this.commitProgress()
+    // 换章是一次全新的加载：清掉上一章遗留的自动重试计数/定时器
+    this.resetRetry()
     // 换书：预取的音轨属于上一本，全部作废
     if (s.bookId !== input.bookId) this.clearPrefetch()
     this.applyChapter(input)
@@ -244,6 +252,7 @@ class ReaderAudioEngine {
   /** 完全停止并清空状态（迷你播放器的关闭按钮）。 */
   stop(): void {
     this.commitProgress()
+    this.resetRetry()
     this.detachSource()
     this.clearPrefetch()
     this.timerDeadline = 0
@@ -457,10 +466,70 @@ 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
+    }
+  }
+
+  /** 退避后再重新解析本章音轨；期间保持 loading 态，不给用户闪错误。 */
+  private scheduleRetry(): void {
+    if (this.retryTimer !== null) window.clearTimeout(this.retryTimer)
+    useReaderAudioStore.setState({ status: 'loading', error: '' })
+    const delay = 800 * this.retryCount
+    this.retryTimer = window.setTimeout(() => {
+      this.retryTimer = null
+      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 +615,21 @@ class ReaderAudioEngine {
 
     audio.addEventListener('error', () => {
       const code = audio.error?.code
+      // 服务端代理拉的是腾讯 CDN 的直链，跨境链路会偶发 502 / 中途断流。
+      // 浏览器对这两种情况都报 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
-            ? '音频加载失败，请检查网络或源文件是否还在'
+            ? '音频加载失败，请检查网络后重试'
             : '音频无法播放',
       )
     })