优化

internal/service/reader/audio_media_cache.go

@@ -22,14 +22,18 @@ import (
 //
 // 背景：听书源的音频直链签在腾讯音乐 CDN 上，跨境链路会间歇性返回 401
 // 或直接 RST 连接。旧行为是每次请求（首播、拖动进度、播放器重试）都重新
-// 回源，一次抖动就把错误交给播放器。这里按「书 + 媒体对象路径」把整段音频
-// 落盘（忽略 ?vkey=... 这类会轮换的签名参数），命中后由 http.ServeContent
+// 回源，一次抖动就把错误交给播放器。这里按「书 + 媒体对象」把整段音频
+// 落盘（丢掉 ?vkey=... 这类会轮换的签名参数），命中后由 http.ServeContent
 // 按 Range 下发：首播成功之后不再依赖 CDN，拖动进度也是本地读取。
 
 const (
-	audioMediaDirName      = "reader-audio"
-	audioMediaTTL          = 7 * 24 * time.Hour
-	audioMediaMaxBytes     = 2 << 30 // 2GiB：超出后按 mtime 淘汰最旧的
+	audioMediaDirName = "reader-audio"
+	audioMediaTTL     = 7 * 24 * time.Hour
+	// audioMediaMaxBytes 音频缓存的总容量上限。超限时按 mtime 淘汰最旧的。
+	//
+	// 这个池不参与 cache_cleanup 的全局总量统计（hls/images/library-covers
+	// 三池），而是在每次下载成功后自行淘汰，见 pruneAudioMediaCache。
+	audioMediaMaxBytes     = 1 << 30 // 1GiB
 	audioMediaPrunePeriod  = 10 * time.Minute
 	audioMediaPruneKeepPct = 90
 
@@ -68,16 +72,48 @@ func (s *ReaderService) audioMediaDir() string {
 	return filepath.Join(base, audioMediaDirName)
 }
 
-// audioMediaCacheKey 缓存键：书 + scheme://host/path。
+// audioMediaVolatileParams 是换票时会变、但与「这是哪段音频」无关的 query 参数。
+// 缓存键必须忽略它们，否则每次换票都打不中缓存。
 //
-// 必须忽略 query：同一段音频每次换票都会得到新的 vkey/uid/ct，只按完整 URL
-// 取哈希的话缓存永远打不中。
+// 不在这张表里的参数一律保留：有些书源的直链形如
+// https://host/audio?id=12345，路径固定、靠 query 区分章节，把 query 整个丢掉
+// 会让第二集命中第一集的缓存，直接播错集。
+var audioMediaVolatileParams = map[string]bool{
+	"vkey": true, "uid": true, "ct": true, "t": true, "ts": true,
+	"token": true, "sign": true, "signature": true, "sig": true,
+	"expires": true, "expire": true, "expiry": true, "auth": true,
+	"nonce": true, "rand": true, "rnd": true, "r": true, "guid": true,
+	"ftime": true,
+}
+
+// audioMediaCacheKey 缓存键：书 + 媒体对象身份。
+//
+// 身份 = scheme://host/path + 非签名类 query。签名/时效参数（vkey、token、
+// 时间戳等）被剔除，保证换票后仍命中同一条缓存；其余参数保留，避免
+// 「路径相同、只靠 query 区分」的书源串集。
 func audioMediaCacheKey(bookID, mediaURL string) string {
 	u, err := url.Parse(strings.TrimSpace(mediaURL))
 	if err != nil || u.Host == "" {
 		return ""
 	}
 	ident := strings.ToLower(u.Scheme) + "://" + strings.ToLower(u.Host) + u.EscapedPath()
+	if u.RawQuery != "" {
+		if q, parseErr := url.ParseQuery(u.RawQuery); parseErr == nil {
+			var kept []string
+			for k, vs := range q {
+				if audioMediaVolatileParams[strings.ToLower(k)] {
+					continue
+				}
+				for _, v := range vs {
+					kept = append(kept, k+"="+v)
+				}
+			}
+			if len(kept) > 0 {
+				sort.Strings(kept)
+				ident += "?" + strings.Join(kept, "&")
+			}
+		}
+	}
 	sum := sha256.Sum256([]byte(bookID + "|" + ident))
 	return hex.EncodeToString(sum[:16])
 }
@@ -121,6 +157,23 @@ func (s *ReaderService) HasCachedRemoteAudio(bookID, mediaURL string) bool {
 	return ok
 }
 
+// HasPartialRemoteAudio 是否有可续传的未完成分片（.part）。
+//
+// 调用方据此决定首播策略：有分片说明上一次已经下到一半（用户点过重试、
+// 或播放器自己重连过），此时「下载完再下发」能透明续上剩余字节；
+// 没有分片才是真正的冷启动，边下边发换更低的 TTFB。
+func (s *ReaderService) HasPartialRemoteAudio(bookID, mediaURL string) bool {
+	path := s.RemoteAudioCachePath(bookID, mediaURL)
+	if path == "" {
+		return false
+	}
+	info, err := os.Stat(path + audioPartialSuffix)
+	if err != nil || !info.Mode().IsRegular() || info.Size() == 0 {
+		return false
+	}
+	return info.Size() <= audioMediaObjectMaxBytes
+}
+
 // OpenCachedRemoteAudio 打开已缓存的音轨（命中返回打开的文件，调用方负责关闭）。
 // 过期的缓存顺手删掉，未过期则刷新 mtime 供 LRU 淘汰。
 func (s *ReaderService) OpenCachedRemoteAudio(bookID, mediaURL string) (*os.File, os.FileInfo, bool) {
@@ -166,6 +219,23 @@ func (e *NoRetryError) Unwrap() error { return e.Err }
 // 调用方负责在内部完成换票；这里只看状态码和字节。
 type AudioRangeFetcher func(rangeHeader string) (resp *http.Response, head []byte, err error)
 
+// AudioStreamStart 首播直通开始的回调：调用方在这里写响应头与状态码。
+// total 是上游声明的总长度（分块传输时为 -1），contentType 是上游给的类型。
+type AudioStreamStart func(total int64, contentType string)
+
+// errAudioStreamCannotRestart 直通模式下遇到必须「从第 0 字节重来」的情况。
+//
+// 直通时客户端已经收到了前缀字节，不可能让它把已收到的丢掉重听，所以这类
+// 分支只能中止这次响应（让客户端判成不完整），并把已下载的分片留给下次续传。
+var errAudioStreamCannotRestart = errors.New("直通中无法从零重新下载")
+
+// audioSinkError 标记「写客户端失败」（通常是播放器关掉了连接）。
+// 与写盘失败区分开：写盘失败说明本地有问题，写客户端失败只需停止下载。
+type audioSinkError struct{ err error }
+
+func (e *audioSinkError) Error() string { return "写入客户端失败: " + e.err.Error() }
+func (e *audioSinkError) Unwrap() error { return e.err }
+
 // DownloadRemoteAudio 带断点续传地把整段音轨写进缓存，返回最终文件路径。
 //
 // 为什么需要续传：腾讯 CDN 的跨境边缘常在传输中途 RST，旧实现每次重试都从
@@ -181,6 +251,40 @@ func (s *ReaderService) DownloadRemoteAudio(
 	bookID, mediaURL string,
 	attempts int,
 	fetch AudioRangeFetcher,
+) (string, error) {
+	return s.downloadRemoteAudio(ctx, bookID, mediaURL, attempts, fetch, nil, nil)
+}
+
+// DownloadRemoteAudioStreaming 首播直通：一边落盘一边把字节写给 sink。
+//
+// 与 DownloadRemoteAudio 的区别只有一处——不再等整段下完才返回，第一个字节
+// 到达就通过 onStart 写好响应头并开始外发，慢链路上的首播不必先等 3–5MB。
+//
+// 代价是失败语义变严：客户端已经收到前缀字节，任何「必须从 0 重来」的情况
+// （上游忽略 Range 回 200、分片区间对不上、416）都只能中止这次响应，
+// 不能像普通模式那样静默重下。已写入的分片仍然保留，下次可续传。
+func (s *ReaderService) DownloadRemoteAudioStreaming(
+	ctx context.Context,
+	bookID, mediaURL string,
+	attempts int,
+	fetch AudioRangeFetcher,
+	onStart AudioStreamStart,
+	sink io.Writer,
+) (string, error) {
+	if sink == nil {
+		return "", errors.New("直通下载未提供输出目标")
+	}
+	return s.downloadRemoteAudio(ctx, bookID, mediaURL, attempts, fetch, onStart, sink)
+}
+
+// downloadRemoteAudio 是两种下载模式的共同实现。sink 非空即首播直通模式。
+func (s *ReaderService) downloadRemoteAudio(
+	ctx context.Context,
+	bookID, mediaURL string,
+	attempts int,
+	fetch AudioRangeFetcher,
+	onStart AudioStreamStart,
+	sink io.Writer,
 ) (string, error) {
 	path := s.RemoteAudioCachePath(bookID, mediaURL)
 	if path == "" {
@@ -209,6 +313,8 @@ func (s *ReaderService) DownloadRemoteAudio(
 	if err != nil {
 		return "", fmt.Errorf("创建音频缓存文件失败: %w", err)
 	}
+	// onStart 只应触发一次：直通模式下响应头只能写一次。
+	started := false
 
 	var lastErr error
 	for attempt := 1; attempt <= attempts; attempt++ {
@@ -250,6 +356,12 @@ func (s *ReaderService) DownloadRemoteAudio(
 			start, total, ok := parseContentRange(resp.Header.Get("Content-Range"))
 			if !ok || offset == 0 || start != offset {
 				drainAndClose(resp.Body)
+				if sink != nil && offset > 0 {
+					// 已经发给客户端 offset 字节：重来会让客户端收到重复内容。
+					// 分片保持原样，下次请求从这里续。
+					_ = file.Close()
+					return "", errAudioStreamCannotRestart
+				}
 				offset = 0
 				_ = file.Truncate(0)
 				lastErr = fmt.Errorf("音源返回的分片区间不可用（%q）", resp.Header.Get("Content-Range"))
@@ -259,9 +371,14 @@ func (s *ReaderService) DownloadRemoteAudio(
 		case http.StatusOK:
 			// 上游忽略了 Range（或者本来就是整段请求）：只能从第 0 字节写。
 			if offset > 0 {
+				drainAndClose(resp.Body)
+				if sink != nil {
+					// 同上：已发出去的字节不能撤回，分片留着供下次续传。
+					_ = file.Close()
+					return "", errAudioStreamCannotRestart
+				}
 				offset = 0
 				if truncErr := file.Truncate(0); truncErr != nil {
-					drainAndClose(resp.Body)
 					lastErr = fmt.Errorf("重置音频缓存失败: %w", truncErr)
 					continue
 				}
@@ -270,6 +387,10 @@ func (s *ReaderService) DownloadRemoteAudio(
 		case http.StatusRequestedRangeNotSatisfiable:
 			// 分片比上游对象还长（对象换过）：丢掉分片重来。
 			drainAndClose(resp.Body)
+			if sink != nil && offset > 0 {
+				_ = file.Close()
+				return "", errAudioStreamCannotRestart
+			}
 			offset = 0
 			_ = file.Truncate(0)
 			lastErr = fmt.Errorf("音源分片已失效（%d）", resp.StatusCode)
@@ -280,12 +401,27 @@ func (s *ReaderService) DownloadRemoteAudio(
 			continue
 		}
 
+		if sink != nil && !started {
+			// 直通模式下要在这里就把状态码与 Content-Length 写出去，客户端才能
+			// 边收边播。写头的失败（客户端已断开）当作停止下载处理。
+			if onStart != nil {
+				onStart(expected, resp.Header.Get("Content-Type"))
+			}
+			started = true
+		}
+
 		if _, seekErr := file.Seek(offset, io.SeekStart); seekErr != nil {
 			drainAndClose(resp.Body)
 			lastErr = fmt.Errorf("音频缓存定位失败: %w", seekErr)
 			continue
 		}
-		written, writeErr := writeAudioChunk(file, head, resp.Body, audioMediaObjectMaxBytes-offset)
+		var written int64
+		var writeErr error
+		if sink != nil {
+			written, writeErr = writeAudioChunkStream(file, sink, head, resp.Body, audioMediaObjectMaxBytes-offset)
+		} else {
+			written, writeErr = writeAudioChunk(file, head, resp.Body, audioMediaObjectMaxBytes-offset)
+		}
 		_ = resp.Body.Close()
 		offset += written
 		if errors.Is(writeErr, errAudioObjectTooLarge) {
@@ -293,6 +429,12 @@ func (s *ReaderService) DownloadRemoteAudio(
 			_ = os.Remove(partPath)
 			return "", fmt.Errorf("已重试 %d 次: %w", attempts, writeErr)
 		}
+		var sinkErr *audioSinkError
+		if errors.As(writeErr, &sinkErr) {
+			// 客户端不要了：停止下载，已写入的分片留着供下次续传。
+			_ = file.Close()
+			return "", sinkErr
+		}
 		if writeErr != nil {
 			// 已写入的字节保留在分片里，下一轮从新的断点续传。
 			lastErr = writeErr
@@ -355,6 +497,64 @@ func writeAudioChunk(w io.Writer, head []byte, body io.Reader, limit int64) (int
 	return total, nil
 }
 
+// writeAudioChunkStream 同 writeAudioChunk，但同时把字节写给客户端（首播直通）。
+//
+// 写盘失败要让整个下载停下来（本地状态不可信，继续发字节等于给客户端一份
+// 服务端存不下的内容）；写客户端失败只说明接收方不要了，用 audioSinkError
+// 标出来让上层保留分片、安静收尾。两者必须区分，否则播放器一关就把分片删了。
+func writeAudioChunkStream(w io.Writer, sink io.Writer, head []byte, body io.Reader, limit int64) (int64, error) {
+	var total int64
+	writeBoth := func(p []byte) error {
+		n, err := w.Write(p)
+		total += int64(n)
+		if err != nil {
+			return err
+		}
+		if n > 0 {
+			if _, sinkErr := sink.Write(p[:n]); sinkErr != nil {
+				return &audioSinkError{err: sinkErr}
+			}
+		}
+		return nil
+	}
+	if len(head) > 0 {
+		if err := writeBoth(head); err != nil {
+			return total, err
+		}
+	}
+	if limit <= 0 {
+		return total, errAudioObjectTooLarge
+	}
+	buf := make([]byte, 32<<10)
+	remaining := limit - total + 1
+	for {
+		if remaining <= 0 {
+			return total, errAudioObjectTooLarge
+		}
+		chunk := buf
+		if int64(len(chunk)) > remaining {
+			chunk = chunk[:remaining]
+		}
+		n, readErr := body.Read(chunk)
+		if n > 0 {
+			if err := writeBoth(chunk[:n]); err != nil {
+				return total, err
+			}
+			remaining -= int64(n)
+		}
+		if readErr == io.EOF {
+			break
+		}
+		if readErr != nil {
+			return total, readErr
+		}
+	}
+	if total > limit {
+		return total, errAudioObjectTooLarge
+	}
+	return total, nil
+}
+
 // parseContentRange 解析 "bytes 100-199/1234" 的起点与总长度。
 // 总长度未知（"*"）时 total 为 -1。
 func parseContentRange(v string) (start, total int64, ok bool) {

internal/service/reader/audio_media_cache_test.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -35,8 +36,8 @@ func TestIsAudioMediaURL(t *testing.T) {
 	}
 }
 
-// TestAudioMediaCacheKeyIgnoresQuery 换票会改写 uid/vkey/ct，缓存键必须只看
-// scheme + host + path，否则每次换票都会重新下载一遍。
+// TestAudioMediaCacheKeyIgnoresQuery 换票会改写 uid/vkey/ct，缓存键必须忽略
+// 这些签名/时效参数，否则每次换票都会重新下载一遍。
 func TestAudioMediaCacheKeyIgnoresQuery(t *testing.T) {
 	a := audioMediaCacheKey("book-1", "https://cdn.example.com/long/a.m4a?uid=1&vkey=aaa")
 	b := audioMediaCacheKey("book-1", "https://cdn.example.com/long/a.m4a?uid=2&vkey=bbb&ct=3")
@@ -51,6 +52,30 @@ func TestAudioMediaCacheKeyIgnoresQuery(t *testing.T) {
 	}
 }
 
+// TestAudioMediaCacheKeyKeepsIdentifyingQuery 只靠 query 区分章节的书源
+// （路径固定、如 /audio?id=12345）不能被合并成同一个缓存对象，否则第二集
+// 会命中第一集的缓存直接播错内容。
+func TestAudioMediaCacheKeyKeepsIdentifyingQuery(t *testing.T) {
+	ep1 := audioMediaCacheKey("book-1", "https://host/audio?id=12345&vkey=aaa")
+	ep2 := audioMediaCacheKey("book-1", "https://host/audio?id=67890&vkey=bbb")
+	if ep1 == "" || ep2 == "" {
+		t.Fatal("缓存键不应为空")
+	}
+	if ep1 == ep2 {
+		t.Fatalf("不同章节（query 不同）的缓存键不应相同，否则会串集")
+	}
+}
+
+// TestAudioMediaCacheKeyIgnoresQueryOrder 非签名参数的顺序不应影响缓存键。
+func TestAudioMediaCacheKeyIgnoresQueryOrder(t *testing.T) {
+	a := audioMediaCacheKey("book-1", "https://host/a.m4a?id=7&chapter=3&vkey=x")
+	b := audioMediaCacheKey("book-1", "https://host/a.m4a?chapter=3&id=7&vkey=y")
+	if a == "" || a != b {
+		t.Fatalf("参数顺序不应影响缓存键: %q vs %q", a, b)
+	}
+}
+
+
 // ─── 断点续传下载器 ──────────────────────────────────────────────────────
 
 func TestParseContentRange(t *testing.T) {
@@ -267,3 +292,143 @@ func TestDownloadRemoteAudioStopsOnNoRetry(t *testing.T) {
 		t.Fatalf("不可重试的失败只应请求 1 次，实际 %d 次", calls)
 	}
 }
+
+// ─── 首播直通（边下边发） ────────────────────────────────────────────────
+
+// TestDownloadRemoteAudioStreamingForwardsWhileDownloading 直通模式：字节必须
+// 在下载过程中就到达 sink，而不是等整段下完才一次性写出去（首播 TTFB）。
+func TestDownloadRemoteAudioStreamingForwardsWhileDownloading(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/stream.m4a? vkey=1"
+	payload := bytes.Repeat([]byte("stream!"), 1000)
+
+	var sink bytes.Buffer
+	var startedTotal int64
+	// 用「读到一半时 sink 里已经有数据」来证明确实在边下边发。
+	var midLength int
+	path, err := svc.DownloadRemoteAudioStreaming(t.Context(), "book-s", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			if rangeHeader != "" {
+				t.Fatalf("首播直通不应带 Range，实际 %q", rangeHeader)
+			}
+			return okResponse(payload), nil, nil
+		},
+		func(total int64, contentType string) {
+			startedTotal = total
+			// 头部回调必须早于任何字节下发。
+			if sink.Len() != 0 {
+				t.Errorf("写响应头时不应已有字节写出")
+			}
+		},
+		writerFunc(func(p []byte) (int, error) {
+			if midLength == 0 && sink.Len() == 0 && len(p) > 0 {
+				midLength = sink.Len()
+			}
+			return sink.Write(p)
+		}),
+	)
+	if err != nil {
+		t.Fatalf("直通下载失败: %v", err)
+	}
+	if startedTotal != int64(len(payload)) {
+		t.Fatalf("头部回调应拿到上游总长 %d，实际 %d", len(payload), startedTotal)
+	}
+	if !bytes.Equal(sink.Bytes(), payload) {
+		t.Fatalf("下发的字节不完整: %d 字节，期望 %d", sink.Len(), len(payload))
+	}
+	// 下载完成后缓存文件必须完整可命中。
+	got, readErr := os.ReadFile(path)
+	if readErr != nil {
+		t.Fatalf("读缓存文件失败: %v", readErr)
+	}
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("落盘内容不完整: %d 字节", len(got))
+	}
+	if !svc.HasCachedRemoteAudio("book-s", mediaURL) {
+		t.Fatal("直通下完后应当命中缓存")
+	}
+}
+
+// TestDownloadRemoteAudioStreamingStopsWhenClientGoesAway 客户端中途断开时
+// 停止下载，但保留分片供下次续传（不能把已下的字节白扔掉）。
+func TestDownloadRemoteAudioStreamingStopsWhenClientGoesAway(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/gone.m4a"
+	payload := bytes.Repeat([]byte("abcdefgh"), 2000)
+	clientGone := errors.New("client closed connection")
+
+	var sink bytes.Buffer
+	_, err := svc.DownloadRemoteAudioStreaming(t.Context(), "book-g", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			return okResponse(payload), nil, nil
+		},
+		nil,
+		writerFunc(func(p []byte) (int, error) {
+			// 收下前 1000 字节后模拟播放器断开。
+			if sink.Len() >= 1000 {
+				return 0, clientGone
+			}
+			room := 1000 - sink.Len()
+			if len(p) <= room {
+				return sink.Write(p)
+			}
+			n, _ := sink.Write(p[:room])
+			return n, clientGone
+		}),
+	)
+	if err == nil {
+		t.Fatal("客户端断开时应当停止下载")
+	}
+	var sinkErr *audioSinkError
+	if !errors.As(err, &sinkErr) {
+		t.Fatalf("应标记为写客户端失败（便于上层区分），实际 %v", err)
+	}
+	// 分片要留着：这是续传的原料。
+	path := svc.RemoteAudioCachePath("book-g", mediaURL)
+	if path == "" {
+		t.Fatal("缓存路径不应为空")
+	}
+	if info, statErr := os.Stat(path + audioPartialSuffix); statErr != nil || info.Size() == 0 {
+		t.Fatalf("断流后应保留 .part 分片，实际 %v", statErr)
+	}
+	if svc.HasCachedRemoteAudio("book-g", mediaURL) {
+		t.Fatal("中断的下载不能留下完整缓存（否则会下发截断音频）")
+	}
+}
+
+// TestDownloadRemoteAudioStreamingAbortsOnRestart 直通模式下上游忽略 Range 回
+// 200（需要从 0 重来）时必须中止，而不是把重复字节拼进客户端已收到的流里。
+func TestDownloadRemoteAudioStreamingAbortsOnRestart(t *testing.T) {
+	svc := newAudioDownloadTestService(t)
+	const mediaURL = "https://cdn.example.com/long/restart.m4a"
+	payload := bytes.Repeat([]byte("zz"), 100)
+	// 先留一个分片，让第二轮带 Range。
+	partPath := svc.RemoteAudioCachePath("book-r", mediaURL) + audioPartialSuffix
+	if err := os.MkdirAll(filepath.Dir(partPath), 0o750); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(partPath, payload[:50], 0o640); err != nil {
+		t.Fatal(err)
+	}
+
+	var sink bytes.Buffer
+	_, err := svc.DownloadRemoteAudioStreaming(t.Context(), "book-r", mediaURL, 1,
+		func(rangeHeader string) (*http.Response, []byte, error) {
+			// 无视 Range，整段回 200 → 直通无法重来。
+			return okResponse(payload), nil, nil
+		},
+		nil,
+		&sink,
+	)
+	if !errors.Is(err, errAudioStreamCannotRestart) {
+		t.Fatalf("应返回不可重来错误，实际 %v", err)
+	}
+	if sink.Len() != 0 {
+		t.Fatalf("中止前不应向客户端写出字节，实际 %d", sink.Len())
+	}
+}
+
+// writerFunc 把函数适配成 io.Writer。
+type writerFunc func(p []byte) (int, error)
+
+func (f writerFunc) Write(p []byte) (int, error) { return f(p) }

internal/service/reader/book_type_fallback_test.go

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

internal/service/reader/comic_image_test.go

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

internal/service/reader/comment_test.go

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

internal/service/reader/media_direct_test.go

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

internal/service/reader/media_refresh_test.go

@@ -129,7 +129,7 @@ func TestRefreshMediaURLIssuesNewTicket(t *testing.T) {
 	ctx := t.Context()
 
 	// 首读：拿到第一张票并落缓存
-	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("首次读取失败: %v", err)
 	}
@@ -166,7 +166,7 @@ func TestRefreshMediaURLIssuesNewTicket(t *testing.T) {
 	}
 
 	// 缓存要被刷新成新票：再次读章节不应再回源
-	out2, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0)
+	out2, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("换票后读章节失败: %v", err)
 	}
@@ -188,7 +188,7 @@ func TestRefreshMediaURLMemoryReusesTicket(t *testing.T) {
 	svc, srv, book := prepareTicketBook(t)
 	ctx := t.Context()
 
-	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("首次读取失败: %v", err)
 	}
@@ -218,7 +218,7 @@ func TestRefreshMediaURLSkipsNonTrackURL(t *testing.T) {
 	svc, _, book := prepareTicketBook(t)
 	ctx := t.Context()
 
-	if _, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0); err != nil {
+	if _, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{}); err != nil {
 		t.Fatalf("首次读取失败: %v", err)
 	}
 	_, refreshable, err := svc.RefreshMediaURL(ctx, book, "https://img.example.com/cover.jpg")
@@ -236,7 +236,7 @@ func TestRefreshMediaURLErrorsWhenSourceRepeatsTicket(t *testing.T) {
 	svc, srv, book := prepareTicketBook(t)
 	ctx := t.Context()
 
-	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0)
+	out, err := svc.GetContentForBook(ctx, readerTestUserID, book.ID, 0, ContentOptions{})
 	if err != nil {
 		t.Fatalf("首次读取失败: %v", err)
 	}

internal/service/reader/reader.go

@@ -1850,6 +1850,13 @@ type ChapterContent struct {
 	// 前端据此决定走 hls.js 而不是原生 <audio>：代理地址是 base64 编码的
 	// /api/reader/media?...&u=...，前端无法再从 URL 后缀判断格式。
 	IsHLS bool `json:"hls,omitempty"`
+	// MediaDirect 为真表示 Tracks/Images 是上游原始地址，由客户端直接去取，
+	// 服务端不再代理字节。此时 MediaHeaders 给出取这些地址所需的请求头。
+	// 只有客户端显式请求直连（ContentOptions.MediaDirect）且书源开启该开关时才会出现。
+	MediaDirect bool `json:"media_direct,omitempty"`
+	// MediaHeaders 直连模式下取媒体所需的请求头（防盗链 Referer/UA、登录 Cookie 等）。
+	// 代理模式下为空：请求头只在服务端内部使用，不下发给客户端。
+	MediaHeaders map[string]string `json:"media_headers,omitempty"`
 	// declaredType 书源在规则 JS 里声明的书籍类型（-1 表示未声明），
 	// 由 GetContentForBook 写回书架记录（对应 legado Book.type）。
 	declaredType int
@@ -1857,6 +1864,106 @@ type ChapterContent struct {
 
 // ─── 媒体代理（音频流 / 漫画图片，带防盗链头与 HMAC 签名） ──────────────────
 
+// ContentOptions 正文下发的可选行为，只由请求参数决定，不改变默认链路。
+//
+// 默认零值 = 今天的网页行为：媒体地址全部改写为服务端签名代理，由服务端
+// 拉取字节再转发。MediaDirect 让客户端（Android App）自己去取上游字节，
+// 服务端只负责解析地址与下发请求头。
+type ContentOptions struct {
+	// MediaDirect 请求直连媒体字节。仅对开启了 MediaDirect 的书源生效，
+	// 否则仍返回代理地址，避免把未验证的源推到客户端直连。
+	MediaDirect bool
+	// ForceProxy 本次强制走服务端代理，即使书源开着直连。
+	//
+	// 给客户端留的退路：直连取不到（防盗链、票失效、上游限流等）时可以要求
+	// 服务端先代理一次，而不是让用户去改书源设置。
+	ForceProxy bool
+}
+
+// mediaDirectFor 结合书源开关与本次请求选项，决定这一章是否直连。
+func (s *ReaderService) mediaDirectFor(ctx context.Context, origin string, opts ContentOptions) bool {
+	if !opts.MediaDirect || opts.ForceProxy {
+		return false
+	}
+	return s.sourceAllowsMediaDirect(ctx, origin)
+}
+
+// applyMediaURLs 决定音频/图片地址是代理还是直连，并填好直连所需请求头。
+//
+// 直连时保留上游原始地址，同时把这一章的请求头一次性下发：同一章内的音轨与
+// 图片通常共用书源级 header / 登录态，逐条下发会让响应体成倍变大。
+// 逐图选项段（",{headers:...}"）的差异不在这里展开 —— 客户端会自行拆分。
+func (s *ReaderService) applyMediaURLs(ctx context.Context, book *model.ReaderBook, out *ChapterContent, direct bool) {
+	if out == nil {
+		return
+	}
+	if !direct {
+		for i, t := range out.Tracks {
+			out.Tracks[i] = s.ProxyURL(book.ID, t)
+		}
+		for i, img := range out.Images {
+			out.Images[i] = s.ProxyURL(book.ID, img)
+		}
+		return
+	}
+	out.MediaDirect = true
+	if out.MediaHeaders == nil {
+		out.MediaHeaders = map[string]string{}
+	}
+	// 请求头按章节内第一条媒体地址计算：同一章的音轨（或图片）通常同域名、
+	// 共用书源级 header 与登录态。逐图选项段（",{headers:...}"）的差异留给
+	// 客户端自行拆分，不下发也不参与这里的计算。
+	sample := ""
+	if len(out.Tracks) > 0 {
+		sample = out.Tracks[0]
+	} else if len(out.Images) > 0 {
+		sample = out.Images[0]
+	}
+	if sample != "" {
+		base, options, _ := rule.ParseMediaOptions(sample)
+		for k, v := range s.MediaRequestHeaders(ctx, book, base, options.Headers) {
+			// 传输层头由客户端 HTTP 栈自己算，下发了反而可能冲突。
+			if transportHeader(k) {
+				continue
+			}
+			out.MediaHeaders[k] = v
+		}
+	}
+}
+
+// sourceAllowsMediaDirect 书源是否允许客户端直连取媒体（按书源 URL 查当前用户的副本）。
+//
+// 查不到书源时返回 false：宁可退回代理，也不把未确认归属的源推到客户端直连。
+func (s *ReaderService) sourceAllowsMediaDirect(ctx context.Context, origin string) bool {
+	if s == nil || s.repo == nil || strings.TrimSpace(origin) == "" {
+		return false
+	}
+	src, err := s.repo.GetSourceAnyByURL(ctx, origin)
+	if err != nil || src == nil {
+		return false
+	}
+	return src.MediaDirect
+}
+
+// SetSourceMediaDirect 切换书源的媒体直连开关（限当前用户自己的书源）。
+func (s *ReaderService) SetSourceMediaDirect(ctx context.Context, userID, id string, direct bool) error {
+	src, err := s.repo.GetSourceForUser(ctx, userID, id)
+	if err != nil {
+		return err
+	}
+	src.MediaDirect = direct
+	return s.repo.UpdateSource(ctx, src)
+}
+
+// transportHeader 判断是否是传输层头（由客户端 HTTP 栈负责，不应下发）。
+func transportHeader(name string) bool {
+	switch strings.ToLower(name) {
+	case "accept-encoding", "connection", "host", "content-length", "cookie2":
+		return true
+	}
+	return false
+}
+
 // ProxyURL 将书源返回的媒体地址改写为签名代理地址。
 // 签名 = HMAC-SHA256(jwtSecret, bookID|url)，防止代理被滥用为开放中转。
 //
@@ -1945,6 +2052,80 @@ func BodyIsPlaylist(head []byte, contentType string) bool {
 	return strings.Contains(contentType, "mpegurl") && strings.Contains(string(head), "#EXTM3U")
 }
 
+// MediaRequestHeaders 构造取上游媒体所需的完整请求头。
+//
+// 服务端拉流（FetchMediaWithOptions）与客户端直连（ContentOptions.MediaDirect）
+// 共用这一份逻辑，保证两条链路的防盗链头、登录态与书源头完全一致 —— 直连只是
+// 把「谁发起 HTTP 请求」从服务端换成 App，不应退化成一套更弱的请求。
+//
+// 优先级由低到高：通用预设 < 书源 header < 登录态 < URL 尾部选项。
+func (s *ReaderService) MediaRequestHeaders(ctx context.Context, book *model.ReaderBook, rawURL string, options map[string]string) map[string]string {
+	out := map[string]string{}
+	for k, v := range helper.HTTPHeaderPresets() {
+		out[k] = v
+	}
+	if book == nil || s == nil {
+		return out
+	}
+	// 书源级请求头
+	if s.repo != nil {
+		if found, findErr := s.repo.GetSourceAnyByURL(ctx, book.Origin); findErr == nil && found != nil && found.Header != "" {
+			var headers map[string]any
+			if json.Unmarshal([]byte(found.Header), &headers) == nil {
+				for k, v := range headers {
+					out[k] = fmt.Sprintf("%v", v)
+				}
+			}
+		}
+	}
+	// 登录态：登录类书源的漫画/音频资源同样需要 Cookie 与 loginHeader 才能取到。
+	if s.repo != nil {
+		state := s.newSourceState(ctx, book.Origin)
+		for k, v := range state.LoginHeaderMap() {
+			if strings.EqualFold(k, "cookie") {
+				continue
+			}
+			if out[k] == "" {
+				out[k] = v
+			}
+		}
+		if out["Cookie"] == "" {
+			if ck := state.CookieForRequest(rawURL); ck != "" {
+				out["Cookie"] = ck
+			}
+		}
+	}
+	// URL 尾部选项里的请求头：优先级最高（逐图声明，取图必需）。
+	optionCookie := ""
+	for k, v := range options {
+		if strings.EqualFold(k, "Cookie") {
+			optionCookie = v
+			continue
+		}
+		out[k] = v
+	}
+	if optionCookie != "" {
+		// 与源 Cookie 合并时 options 优先（对应 legado AnalyzeUrl.setCookie 的临时 Cookie）。
+		if base := out["Cookie"]; base != "" {
+			out["Cookie"] = rule.MergeCookie(base, optionCookie)
+		} else {
+			out["Cookie"] = optionCookie
+		}
+	}
+	// 默认 Referer 只能用「真正的 http(s) 书源地址」。
+	// legado 的 origin 对普通书源是 bookSourceUrl，但聚合类书源（如「光遇聚合」）
+	// 的 origin 是个显示名，拼出来的 Referer 非法，会被图床判定为盗链并
+	// 301 到一张「请到本网站阅读」的占位图 —— 表现为漫画每一页都是同一张提示图。
+	// 这种情况下宁可不发 Referer（实测不带 Referer 能拿到原图）；书源 header
+	// 里自己声明的 Referer 优先级更高，不受这里影响。
+	if out["Referer"] == "" {
+		if referer := sourceReferer(book.Origin); referer != "" {
+			out["Referer"] = referer
+		}
+	}
+	return out
+}
+
 // FetchMedia 用书源会话拉取媒体（不应用 URL 尾部选项）。
 func (s *ReaderService) FetchMedia(ctx context.Context, book *model.ReaderBook, rawURL, rangeHeader string) (*http.Response, error) {
 	return s.FetchMediaWithOptions(ctx, book, rawURL, rangeHeader, nil)
@@ -1962,66 +2143,13 @@ func (s *ReaderService) FetchMediaWithOptions(ctx context.Context, book *model.R
 		if err != nil {
 			return nil, err
 		}
-		for k, v := range helper.HTTPHeaderPresets() {
+		for k, v := range s.MediaRequestHeaders(ctx, book, rawURL, options) {
 			httpReq.Header.Set(k, v)
 		}
 		// 媒体流同样交给 net/http 管压缩：否则压缩过的资源会以原始字节透传给
 		// 播放器/图片标签，表现为「打不开」。Range 请求服务端通常不压缩，
 		// 解压后 resp 会去掉 Content-Length/Content-Encoding，透传逻辑不受影响。
 		helper.StripAcceptEncoding(httpReq.Header)
-		// 书源级请求头
-		if s.repo != nil {
-			if found, findErr := s.repo.GetSourceAnyByURL(ctx, book.Origin); findErr == nil && found != nil && found.Header != "" {
-				var headers map[string]any
-				if json.Unmarshal([]byte(found.Header), &headers) == nil {
-					for k, v := range headers {
-						httpReq.Header.Set(k, fmt.Sprintf("%v", v))
-					}
-				}
-			}
-		}
-		// 登录态：登录类书源的漫画/音频资源同样需要 Cookie 与 loginHeader 才能取到。
-		if s.repo != nil {
-			state := s.newSourceState(ctx, book.Origin)
-			for k, v := range state.LoginHeaderMap() {
-				if !strings.EqualFold(k, "cookie") && httpReq.Header.Get(k) == "" {
-					httpReq.Header.Set(k, v)
-				}
-			}
-			if httpReq.Header.Get("Cookie") == "" {
-				if ck := state.CookieForRequest(rawURL); ck != "" {
-					httpReq.Header.Set("Cookie", ck)
-				}
-			}
-		}
-		// URL 尾部选项里的请求头：优先级最高（逐图声明，取图必需）。
-		optionCookie := ""
-		for k, v := range options {
-			if strings.EqualFold(k, "Cookie") {
-				optionCookie = v
-				continue
-			}
-			httpReq.Header.Set(k, v)
-		}
-		if optionCookie != "" {
-			// 与源 Cookie 合并时 options 优先（对应 legado AnalyzeUrl.setCookie 的临时 Cookie）。
-			if base := httpReq.Header.Get("Cookie"); base != "" {
-				httpReq.Header.Set("Cookie", rule.MergeCookie(base, optionCookie))
-			} else {
-				httpReq.Header.Set("Cookie", optionCookie)
-			}
-		}
-		// 默认 Referer 只能用「真正的 http(s) 书源地址」。
-		// legado 的 origin 对普通书源是 bookSourceUrl，但聚合类书源（如「光遇聚合」）
-		// 的 origin 是个显示名，拼出来的 Referer 非法，会被图床判定为盗链并
-		// 301 到一张「请到本网站阅读」的占位图 —— 表现为漫画每一页都是同一张提示图。
-		// 这种情况下宁可不发 Referer（实测不带 Referer 能拿到原图）；书源 header
-		// 里自己声明的 Referer 优先级更高，不受这里影响。
-		if httpReq.Header.Get("Referer") == "" {
-			if referer := sourceReferer(book.Origin); referer != "" {
-				httpReq.Header.Set("Referer", referer)
-			}
-		}
 		if rangeHeader != "" {
 			httpReq.Header.Set("Range", rangeHeader)
 		}
@@ -3108,7 +3236,9 @@ func (s *ReaderService) DeleteReplaceRule(ctx context.Context, userID, id string
 // GetContentForBook 按书架书籍 + 章节序号取正文：
 // 解析书源 → 持久缓存（命中直接返回）→ 抓正文（单飞）→ 写缓存 →
 // 书源 replaceRegex → 用户替换净化规则 → 签名代理改写。
-func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID string, chapterIndex int) (*ChapterContent, error) {
+//
+// opts 为零值时行为与历史版本完全一致（媒体全部走服务端代理）。
+func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID string, chapterIndex int, opts ContentOptions) (*ChapterContent, error) {
 	book, err := s.repo.GetBook(ctx, bookID)
 	if err != nil {
 		return nil, err
@@ -3152,22 +3282,21 @@ func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID st
 	if out.Type == "text" {
 		out.Content = s.applyUserReplaceRules(ctx, userID, book.Name, out.Content)
 	}
-	// 音频/图片地址改写为签名代理（浏览器播放/展示无法带防盗链头）
-	for i, t := range out.Tracks {
-		out.Tracks[i] = s.ProxyURL(book.ID, t)
-	}
-	for i, img := range out.Images {
-		out.Images[i] = s.ProxyURL(book.ID, img)
-	}
-	// 文本型漫画源：正文里的 <img> 标签换成前端认识的 [img] 标记（同样走签名代理，
-	// 这样需要防盗链头的图片也能显示）。见 rewriteContentImageMarkers 的说明。
+	direct := s.mediaDirectFor(ctx, book.Origin, opts)
+	// 文本型漫画源：正文里的 <img> 标签换成前端认识的 [img] 标记。
+	// 默认仍走签名代理，这样需要防盗链头的图片也能显示（见
+	// rewriteContentImageMarkers 的说明）；直连时保留上游原始地址。
 	if out.Type == "text" && strings.Contains(out.Content, "<img") {
 		out.Content = rewriteContentImageMarkers(out.Content, ch.URL, func(u string) string {
+			if direct {
+				return u
+			}
 			return s.ProxyURL(book.ID, u)
 		})
 	}
 	// 整章都是 [img] 标记 → 这就是一章漫画，改成图片类型交给漫画阅读器。
 	// 若还按文本下发，前端会把它当文字按列分页，一屏只有一张图（双页铺开也无从谈起）。
+	// 必须早于 applyMediaURLs：转换出来的图片地址同样要参与代理/直连决策与请求头计算。
 	if out.Type == "text" {
 		if imgs, ok := imageMarkersOnly(out.Content); ok {
 			out.Type = "image"
@@ -3175,6 +3304,9 @@ func (s *ReaderService) GetContentForBook(ctx context.Context, userID, bookID st
 			out.Content = ""
 		}
 	}
+	// 音频/图片地址改写：默认走签名代理（浏览器播放/展示无法带防盗链头）；
+	// 客户端显式请求直连且书源允许时，保留上游地址并下发所需请求头。
+	s.applyMediaURLs(ctx, book, out, direct)
 	return out, nil
 }
 
@@ -3260,6 +3392,9 @@ type ContentBatchItem struct {
 	// Cached 为 true 表示这次由持久缓存直接命中（未访问书源）。
 	Cached bool   `json:"cached"`
 	Error  string `json:"error,omitempty"`
+	// MediaDirect / MediaHeaders 同 ChapterContent：客户端直连时的地址与请求头。
+	MediaDirect  bool              `json:"media_direct,omitempty"`
+	MediaHeaders map[string]string `json:"media_headers,omitempty"`
 }
 
 // ContentBatchResult 批量取正文的汇总结果。
@@ -3278,7 +3413,7 @@ const contentBatchConcurrency = 4
 // GetContentBatch 批量取正文（对应 legado 的 CacheBook 离线缓存协议）。
 //
 // 单章失败不中断整批：失败项带 error，其余照常返回。已缓存的章节不访问书源。
-func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID string, indexes []int, applyReplace bool) (*ContentBatchResult, error) {
+func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID string, indexes []int, applyReplace bool, opts ContentOptions) (*ContentBatchResult, error) {
 	book, err := s.repo.GetBook(ctx, bookID)
 	if err != nil {
 		return nil, err
@@ -3314,7 +3449,7 @@ func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID stri
 				result.Items[pos] = ContentBatchItem{ChapterIndex: idx, Error: ctx.Err().Error()}
 				return
 			}
-			item, cached := s.loadBatchItem(ctx, userID, book, chapters[idx], applyReplace)
+			item, cached := s.loadBatchItem(ctx, userID, book, chapters[idx], applyReplace, opts)
 			result.Items[pos] = item
 			if item.Error != "" {
 				result.Stats.Failed++
@@ -3330,18 +3465,22 @@ func (s *ReaderService) GetContentBatch(ctx context.Context, userID, bookID stri
 }
 
 // loadBatchItem 取单章（批量接口用）：先查缓存（不访问书源），再走完整链路。
-func (s *ReaderService) loadBatchItem(ctx context.Context, userID string, book *model.ReaderBook, ch model.ReaderChapter, applyReplace bool) (ContentBatchItem, bool) {
+func (s *ReaderService) loadBatchItem(ctx context.Context, userID string, book *model.ReaderBook, ch model.ReaderChapter, applyReplace bool, opts ContentOptions) (ContentBatchItem, bool) {
 	item := ContentBatchItem{ChapterIndex: ch.Index}
 	src, bs, loadErr := s.loadSourceFlexible(ctx, "", book.Origin)
 	cached := false
 	if loadErr == nil {
 		if out, ok := s.loadCachedContent(ctx, src, bs, book, ch, ""); ok {
+			// 缓存里存的是书源侧原始地址（改写前），命中后同样要按本次请求
+			// 决定代理/直连，否则缓存命中的章节会绕过媒体通道选择。
+			direct := s.mediaDirectFor(ctx, book.Origin, opts)
+			s.applyMediaURLs(ctx, book, out, direct)
 			item = batchItemFromContent(ch.Index, out, applyReplace, userID, book, s)
 			cached = true
 		}
 	}
 	if !cached {
-		out, err := s.GetContentForBook(ctx, userID, book.ID, ch.Index)
+		out, err := s.GetContentForBook(ctx, userID, book.ID, ch.Index, opts)
 		if err != nil {
 			item.Error = err.Error()
 			return item, false
@@ -3362,6 +3501,8 @@ func batchItemFromContent(index int, out *ChapterContent, applyReplace bool, use
 		ImageStyle:   out.ImageStyle,
 		IsHLS:        out.IsHLS,
 		Comments:     out.Comments,
+		MediaDirect:  out.MediaDirect,
+		MediaHeaders: out.MediaHeaders,
 	}
 	if applyReplace && out.Type == "text" && s != nil && book != nil {
 		item.Content = s.applyUserReplaceRules(context.Background(), userID, book.Name, item.Content)

internal/service/reader/reader_content_cache_test.go

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

internal/service/reader/reader_test.go

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