优化

2026-11-15 20:34:23 +08:00 · 2026-10-04 22:17:19 +08:00 · 2026-10-04 21:31:09 +08:00 · 2026-10-04 17:50:26 +08:00 · 2026-10-04 16:28:13 +08:00 · 2026-10-04 13:53:44 +08:00
22 changed files with 1416 additions and 45 deletions
@@ -21,6 +21,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/url"
 	"regexp"
@@ -237,6 +238,88 @@ func (r *EmbyRemoteService) ConfiguredRemoteHosts(ctx context.Context) []string
 	return hosts
 }

+// findAccountByHost 返回某条线路主机名匹配 host 的启用远程 Emby 账号（无则 nil）。
+func (r *EmbyRemoteService) findAccountByHost(ctx context.Context, host string) *model.StrmAccount {
+	host = normalizeHostKey(host)
+	if host == "" || r == nil || r.repo == nil || r.repo.StrmAccount == nil {
+		return nil
+	}
+	accounts, err := r.ListAccounts(ctx)
+	if err != nil {
+		return nil
+	}
+	for i := range accounts {
+		lines, _, err := r.LinesOf(&accounts[i])
+		if err != nil {
+			continue
+		}
+		for _, line := range lines {
+			u, err := url.Parse(line.URL)
+			if err != nil {
+				continue
+			}
+			if normalizeHostKey(u.Hostname()) == host {
+				return &accounts[i]
+			}
+		}
+	}
+	return nil
+}
+
+// normalizeHostKey 去掉端口并小写化，便于主机名字符串比较。
+func normalizeHostKey(host string) string {
+	host = strings.ToLower(strings.TrimSpace(host))
+	if host == "" {
+		return ""
+	}
+	if h, _, err := net.SplitHostPort(host); err == nil {
+		return strings.ToLower(strings.TrimSpace(h))
+	}
+	return host
+}
+
+// RemoteEmbyImageTokenForHost 返回图片代理回源某个远程 Emby 主机所需的当前
+// api_key。host 不属于任何已配置账号时返回 ok=false。
+func (r *EmbyRemoteService) RemoteEmbyImageTokenForHost(ctx context.Context, host string) (string, bool) {
+	if r == nil || r.repo == nil {
+		return "", false
+	}
+	acct := r.findAccountByHost(ctx, host)
+	if acct == nil {
+		return "", false
+	}
+	cfg, err := r.configOf(acct)
+	if err != nil || strings.TrimSpace(cfg.Token) == "" {
+		return "", false
+	}
+	return cfg.Token, true
+}
+
+// RefreshRemoteEmbyImageTokenForHost 强制用用户名/密码重新登录拥有该主机的账号
+// 并持久化新 token，供图片代理在上游 401 时自愈。仅配置了 api_key、没有登录
+// 凭据的账号无法自动刷新，返回错误由调用方按原失败处理。
+func (r *EmbyRemoteService) RefreshRemoteEmbyImageTokenForHost(ctx context.Context, host string) (string, error) {
+	if r == nil || r.repo == nil {
+		return "", errors.New("远程 Emby 服务不可用")
+	}
+	acct := r.findAccountByHost(ctx, host)
+	if acct == nil {
+		return "", fmt.Errorf("未找到主机 %s 对应的远程 Emby 账号", host)
+	}
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(cfg.Username) == "" || strings.TrimSpace(cfg.Password) == "" {
+		return "", errors.New("远程 Emby 账号未配置用户名/密码，无法自动刷新 api_key")
+	}
+	cfg.Token = "" // 强制走登录流程，忽略已失效的 api_key
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return "", err
+	}
+	return cfg.Token, nil
+}
+
 // AccountByID 按 ID 查找远程 Emby 挂载账号（不存在或类型不符返回 nil）。
 func (r *EmbyRemoteService) AccountByID(ctx context.Context, id string) *model.StrmAccount {
 	if strings.TrimSpace(id) == "" {
@@ -699,17 +782,23 @@ func (r *EmbyRemoteService) doGetOnLine(ctx context.Context, acct *model.StrmAcc
 			return err
 		}
 		if status == http.StatusUnauthorized && attempt == 0 {
-			// 401：只清当前线路的内存 token 并立即重认证；不在此时删除
-			// DB 里的 api_key——①外层还会按线路故障转移（其他线路可能
-			// 存有自己的 token）；②纯 api_key 账号删除后无法再认证，一次
-			// 线路误报就会把账号“砖化”。重认证成功后 persistToken 会用
-			// 新 token 覆盖 api_key。
+			// 401：只清当前线路的内存 token 并立即重认证；不先删 DB 里的
+			// api_key——纯 api_key 账号删除后无法再认证，一次线路误报就会
+			// 把账号“砖化”。重认证成功后把新 token 写回：既让重试用上正确
+			// 凭据，也避免每个后续请求都重新登录一次。
+			previous := cfg.Token
 			cfg.Token = ""
 			if err := r.ensureTokenOnLine(ctx, acct, cfg); err != nil {
 				return fmt.Errorf("认证重试失败: %w", err)
 			}
+			if q != nil {
+				q.Set("api_key", cfg.Token)
+			}
 			master.Token = cfg.Token
 			master.RemoteUserID = cfg.RemoteUserID
+			if cfg.Token != "" && cfg.Token != previous {
+				_ = r.persistToken(ctx, acct, cfg)
+			}
 			continue
 		}
 		if status >= 300 {
@@ -0,0 +1,100 @@
+package service
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+func TestRemoteEmbyImageTokenForHostUnknownHost(t *testing.T) {
+	svc, _, _ := newImageTagTestService(t)
+
+	if token, ok := svc.RemoteEmbyImageTokenForHost(t.Context(), "nope.example"); ok || token != "" {
+		t.Fatalf("got (%q,%v), want no token for a host not owned by any account", token, ok)
+	}
+}
+
+func TestRemoteEmbyImageTokenForHostMatchesConfiguredLine(t *testing.T) {
+	svc, _, _ := newImageTagTestService(t)
+
+	token, ok := svc.RemoteEmbyImageTokenForHost(t.Context(), "emby.test")
+	if !ok || token != "fake-token" {
+		t.Fatalf("got (%q,%v), want the account token for the configured line host", token, ok)
+	}
+}
+
+func TestRefreshRemoteEmbyImageTokenForHostRequiresCredentials(t *testing.T) {
+	svc, _, _ := newImageTagTestService(t)
+
+	// The account carries only an api_key — there is nothing to re-authenticate with.
+	if _, err := svc.RefreshRemoteEmbyImageTokenForHost(t.Context(), "emby.test"); err == nil {
+		t.Fatal("expected an error when the account has no username/password to re-authenticate with")
+	}
+}
+
+// TestRefreshRemoteEmbyImageTokenForHostRelogins 覆盖「token 被撤销后自动恢复」：
+// 用用户名/密码重新登录拿到新 token，并持久化，后续请求不再重复登录。
+func TestRefreshRemoteEmbyImageTokenForHostRelogins(t *testing.T) {
+	const fresh = "fresh-token"
+	logins := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/emby/Users/AuthenticateByName" {
+			http.NotFound(w, r)
+			return
+		}
+		logins++
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"AccessToken":"` + fresh + `","User":{"Id":"remote-user"}}`))
+	}))
+	defer upstream.Close()
+
+	db := newServiceTestDB(t, &model.StrmAccount{}, &model.EmbyMount{})
+	repos := repository.New(db)
+	svc := NewEmbyRemoteService(&config.Config{}, zap.NewNop(), repos, NewCryptoService("", zap.NewNop()))
+	acct := &model.StrmAccount{
+		Base:     model.Base{ID: "acct-refresh"},
+		Name:     "refresh-emby",
+		Provider: model.StrmProviderEmbyRemote,
+		Enabled:  true,
+		Config:   `{"url":"` + upstream.URL + `","api_key":"stale-token","username":"u","password":"p"}`,
+	}
+	if err := repos.StrmAccount.Create(t.Context(), acct); err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+
+	u, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	host := u.Hostname()
+
+	if token, ok := svc.RemoteEmbyImageTokenForHost(t.Context(), host); !ok || token != "stale-token" {
+		t.Fatalf("token before refresh = (%q,%v), want the stale stored token", token, ok)
+	}
+
+	token, err := svc.RefreshRemoteEmbyImageTokenForHost(t.Context(), host)
+	if err != nil {
+		t.Fatalf("refresh: %v", err)
+	}
+	if token != fresh {
+		t.Fatalf("refreshed token = %q, want %q", token, fresh)
+	}
+	if logins != 1 {
+		t.Fatalf("logins = %d, want 1", logins)
+	}
+
+	// 新 token 必须落库，否则每个请求都要重新登录一次。
+	if token, ok := svc.RemoteEmbyImageTokenForHost(t.Context(), host); !ok || token != fresh {
+		t.Fatalf("token after refresh = (%q,%v), want the persisted %q", token, ok, fresh)
+	}
+	if logins != 1 {
+		t.Fatalf("logins = %d, want 1 after the refresh was persisted", logins)
+	}
+}
@@ -13,6 +13,7 @@
 package service

 import (
+	"context"
 	"errors"
 	"net"
 	"net/http"
@@ -65,6 +66,16 @@ type ImageProxy struct {
 	allowedHostsMu       sync.Mutex
 	allowedHostsCache    map[string]bool
 	allowedHostsAt       time.Time
+
+	// remoteEmbyTokenFn / refreshRemoteEmbyTokenFn let the proxy carry a fresh
+	// credential for configured remote-Emby mounts. Image URLs are minted from
+	// whatever token the account had when the payload was built, so a URL can
+	// outlive its api_key; these hooks re-supply the current one and force a
+	// re-login when the mount rejects it.
+	remoteEmbyTokenFn        func(ctx context.Context, host string) (string, bool)
+	refreshRemoteEmbyTokenFn func(ctx context.Context, host string) (string, error)
+	remoteEmbyTokenMu        sync.Mutex
+	remoteEmbyTokenCache     map[string]remoteEmbyImageToken
 }

 const (
@@ -14,6 +14,10 @@ import (
 var errImageProxyRequestSetup = errors.New("image proxy request setup failed")
 var errImageProxyNonImageContent = errors.New("upstream returned non-image content")

+// errImageProxyUnauthorized 表示上游以 401/403 拒绝了回源凭据。它与普通失败
+// 分开，是为了让调用方对挂载 Emby 做一次重认证再重试，而不是直接下发占位图。
+var errImageProxyUnauthorized = errors.New("upstream rejected image credentials")
+
 // prefetchCardResizeOptions 对应前端 ARTWORK.posterCard（见 web/src/api/client.ts）：
 // 卡片是海报墙最常请求的档位，刮削阶段预生成它能让首个列表请求直接命中缓存。
 // 若前端调整该预设，这里只是白生成一份用不到的档位（约几十 KB），不影响正确性。
@@ -183,16 +187,27 @@ func (p *ImageProxy) removeUnusableImageCache(cachePath, failPath string) {
 }

 func (p *ImageProxy) fetchAndCacheRemoteImage(ctx context.Context, raw, host, cachePath, failPath string) (remoteImageFetchResult, error) {
-	var lastErr error
-	for _, candidate := range p.remoteImageFetchClients(host) {
-		result, err := p.fetchRemoteImageOnce(ctx, raw, host, candidate, cachePath, failPath)
-		if err == nil {
-			return result, nil
+	result, lastErr := p.fetchRemoteImageAcrossClients(ctx, raw, host, cachePath, failPath)
+	if lastErr == nil {
+		return result, nil
+	}
+	if errors.Is(lastErr, errImageProxyRequestSetup) {
+		return remoteImageFetchResult{}, lastErr
+	}
+	// 已挂载的远程 Emby 认 X-Emby-Token 请求头，但轮换前生成的图片 URL 里还留着
+	// 旧 api_key。上游拒绝时重新登录拥有该主机的账号一次再重试，而不是一直下发
+	// 占位图、等人工去改账号配置。
+	if errors.Is(lastErr, errImageProxyUnauthorized) {
+		token, refreshErr := p.refreshRemoteEmbyTokenForHost(ctx, host)
+		if refreshErr != nil {
+			logImageFetchError(p.log, "imageproxy: remote emby re-auth failed", host, "reauth", refreshErr)
+		} else if token != "" {
+			retried, retryErr := p.fetchRemoteImageAcrossClients(ctx, raw, host, cachePath, failPath)
+			if retryErr == nil {
+				return retried, nil
+			}
+			lastErr = retryErr
 		}
-		if errors.Is(err, errImageProxyRequestSetup) {
-			return remoteImageFetchResult{}, err
-		}
-		lastErr = err
 	}
 	if p.canUseExternalImageFallback() && isDoubanImageHost(host) {
 		data, ctype, _, err := fetchRemoteImageWithCurl(ctx, raw, host)
@@ -210,6 +225,24 @@ func (p *ImageProxy) fetchAndCacheRemoteImage(ctx context.Context, raw, host, ca
 	return remoteImageFetchResult{}, redactSensitiveError(lastErr)
 }

+// fetchRemoteImageAcrossClients 按直连/代理顺序依次尝试，返回首个成功结果。
+// 请求构造失败立即中止（重试无意义）；401/403 会继续尝试另一个客户端，并把
+// errImageProxyUnauthorized 作为最终错误交给调用方去刷新挂载 token。
+func (p *ImageProxy) fetchRemoteImageAcrossClients(ctx context.Context, raw, host, cachePath, failPath string) (remoteImageFetchResult, error) {
+	var lastErr error
+	for _, candidate := range p.remoteImageFetchClients(host) {
+		result, err := p.fetchRemoteImageOnce(ctx, raw, host, candidate, cachePath, failPath)
+		if err == nil {
+			return result, nil
+		}
+		if errors.Is(err, errImageProxyRequestSetup) {
+			return remoteImageFetchResult{}, err
+		}
+		lastErr = err
+	}
+	return remoteImageFetchResult{}, lastErr
+}
+
 // fetchAndCacheRemoteImageShared coalesces concurrent requests for the same
 // upstream image. A poster can appear in the hero, a shelf and the detail page
 // at the same time; without this guard every resize variant may fetch the same
@@ -0,0 +1,102 @@
+package service
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// remoteEmbyImageTokenTTL 是 host → api_key 的缓存时长。海报墙首屏一口气请求
+// 几十张图，逐个回读数据库不值得；token 轮换时 401 重认证会立即覆盖这份缓存。
+const remoteEmbyImageTokenTTL = 60 * time.Second
+
+type remoteEmbyImageToken struct {
+	token string
+	at    time.Time
+}
+
+// SetRemoteEmbyAuthProvider 注入「按主机名取当前远程 Emby api_key」的回调。
+// 图片代理回源已挂载的远程 Emby 时用它替换 URL 里可能已过期的凭据。
+func (p *ImageProxy) SetRemoteEmbyAuthProvider(fn func(ctx context.Context, host string) (string, bool)) {
+	if p == nil {
+		return
+	}
+	p.remoteEmbyTokenFn = fn
+}
+
+// SetRemoteEmbyAuthRefresher 注入「强制重新登录并返回新 api_key」的回调。上游以
+// 401/403 拒绝旧 token 时调用一次，再重试拉图，从而不需要人工改账号配置。
+func (p *ImageProxy) SetRemoteEmbyAuthRefresher(fn func(ctx context.Context, host string) (string, error)) {
+	if p == nil {
+		return
+	}
+	p.refreshRemoteEmbyTokenFn = fn
+}
+
+// remoteEmbyTokenForHost 返回挂载 Emby 的当前 token，短期缓存避免每张图都查库。
+// 「不是挂载主机」的结果同样缓存，否则普通图床（TMDb/Douban 等）的每张海报都会
+// 白白查一次账号表。
+func (p *ImageProxy) remoteEmbyTokenForHost(ctx context.Context, host string) string {
+	if p == nil || p.remoteEmbyTokenFn == nil || strings.TrimSpace(host) == "" {
+		return ""
+	}
+	p.remoteEmbyTokenMu.Lock()
+	if cached, ok := p.remoteEmbyTokenCache[host]; ok && time.Since(cached.at) < remoteEmbyImageTokenTTL {
+		p.remoteEmbyTokenMu.Unlock()
+		return cached.token
+	}
+	p.remoteEmbyTokenMu.Unlock()
+
+	token, ok := p.remoteEmbyTokenFn(ctx, host)
+	if !ok {
+		token = ""
+	}
+	p.cacheRemoteEmbyToken(host, token)
+	return token
+}
+
+func (p *ImageProxy) cacheRemoteEmbyToken(host, token string) {
+	if p == nil || strings.TrimSpace(host) == "" {
+		return
+	}
+	p.remoteEmbyTokenMu.Lock()
+	if p.remoteEmbyTokenCache == nil {
+		p.remoteEmbyTokenCache = make(map[string]remoteEmbyImageToken, 8)
+	}
+	p.remoteEmbyTokenCache[host] = remoteEmbyImageToken{token: token, at: time.Now()}
+	p.remoteEmbyTokenMu.Unlock()
+}
+
+// refreshRemoteEmbyTokenForHost 强制重认证一次并刷新缓存。没有配置刷新器、或
+// 账号无法自动刷新（如仅填了 api_key）时返回空串，调用方按原错误处理。
+func (p *ImageProxy) refreshRemoteEmbyTokenForHost(ctx context.Context, host string) (string, error) {
+	if p == nil || p.refreshRemoteEmbyTokenFn == nil || strings.TrimSpace(host) == "" {
+		return "", nil
+	}
+	token, err := p.refreshRemoteEmbyTokenFn(ctx, host)
+	if err != nil {
+		return "", err
+	}
+	if token != "" {
+		p.cacheRemoteEmbyToken(host, token)
+	}
+	return token, nil
+}
+
+// applyRemoteEmbyAuth 用账号当前 token 覆盖回源请求上的凭据。已配置的远程 Emby
+// 以 X-Emby-Token 请求头为准，所以图片 URL 里带的是轮换前的旧 api_key 也不会再
+// 被采纳；同时把查询参数里的 api_key 一并改写，避免旧值干扰。
+func (p *ImageProxy) applyRemoteEmbyAuth(ctx context.Context, req *http.Request, host string) {
+	if p == nil || p.remoteEmbyTokenFn == nil || req == nil || req.URL == nil {
+		return
+	}
+	token := p.remoteEmbyTokenForHost(ctx, host)
+	if token == "" {
+		return
+	}
+	req.Header.Set("X-Emby-Token", token)
+	q := req.URL.Query()
+	q.Set("api_key", token)
+	req.URL.RawQuery = q.Encode()
+}
@@ -0,0 +1,126 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync"
+	"testing"
+)
+
+// TestImageProxyInjectsRemoteEmbyToken 覆盖封面空白问题：图片 URL 里签发时的
+// api_key 已经失效，但账号当前 token 有效。代理回源必须用当前 token 覆盖旧值，
+// 否则挂载 Emby 的封面会一直 401、下发占位图。
+func TestImageProxyInjectsRemoteEmbyToken(t *testing.T) {
+	const current = "current-token"
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Emby-Token") != current {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(testJPEG)
+	}))
+	defer upstream.Close()
+
+	u, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proxy := newUpstreamImageProxy(t, u.Host)
+	proxy.SetRemoteEmbyAuthProvider(func(context.Context, string) (string, bool) {
+		return current, true
+	})
+
+	raw := upstream.URL + "/emby/Items/abc/Images/Primary?api_key=stale-token"
+	rec := httptest.NewRecorder()
+	if err := proxy.Serve(t.Context(), rec, httptest.NewRequest(http.MethodGet, "/api/img", nil), raw); err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(rec.Body.Bytes(), testJPEG) {
+		t.Fatalf("body = %x, want the upstream image served with the current token", rec.Body.Bytes())
+	}
+}
+
+// TestImageProxyRefreshesRemoteEmbyTokenOn401 覆盖 token 在运行中被撤销的场景：
+// 账号当前 token 也被上游拒绝时，代理应重新登录一次并重试，且只刷新一次。
+func TestImageProxyRefreshesRemoteEmbyTokenOn401(t *testing.T) {
+	const (
+		stale = "stale-token"
+		fresh = "fresh-token"
+	)
+	var mu sync.Mutex
+	refreshes := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Emby-Token") != fresh {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(testJPEG)
+	}))
+	defer upstream.Close()
+
+	u, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proxy := newUpstreamImageProxy(t, u.Host)
+	proxy.SetRemoteEmbyAuthProvider(func(context.Context, string) (string, bool) {
+		return stale, true
+	})
+	proxy.SetRemoteEmbyAuthRefresher(func(context.Context, string) (string, error) {
+		mu.Lock()
+		refreshes++
+		mu.Unlock()
+		return fresh, nil
+	})
+
+	raw := upstream.URL + "/emby/Items/abc/Images/Primary?api_key=" + stale
+	rec := httptest.NewRecorder()
+	if err := proxy.Serve(t.Context(), rec, httptest.NewRequest(http.MethodGet, "/api/img", nil), raw); err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(rec.Body.Bytes(), testJPEG) {
+		t.Fatalf("body = %x, want the upstream image served after re-auth", rec.Body.Bytes())
+	}
+
+	mu.Lock()
+	got := refreshes
+	mu.Unlock()
+	if got != 1 {
+		t.Fatalf("refreshes = %d, want exactly 1 re-auth", got)
+	}
+}
+
+// TestImageProxyLeavesNonEmbyHostsUntouched 确认新的凭据注入只作用于已配置的
+// 远程 Emby 主机：普通图床（这里用 provider 返回 ok=false 模拟）不受影响。
+func TestImageProxyDoesNotInjectForUnknownHost(t *testing.T) {
+	var gotHeader string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotHeader = r.Header.Get("X-Emby-Token")
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(testJPEG)
+	}))
+	defer upstream.Close()
+
+	u, err := url.Parse(upstream.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proxy := newUpstreamImageProxy(t, u.Host)
+	proxy.SetRemoteEmbyAuthProvider(func(context.Context, string) (string, bool) {
+		return "", false
+	})
+
+	raw := upstream.URL + "/img/cover.jpg"
+	rec := httptest.NewRecorder()
+	if err := proxy.Serve(t.Context(), rec, httptest.NewRequest(http.MethodGet, "/api/img", nil), raw); err != nil {
+		t.Fatal(err)
+	}
+	if gotHeader != "" {
+		t.Fatalf("X-Emby-Token = %q, want no credential header for a non-Emby host", gotHeader)
+	}
+}
@@ -71,6 +71,8 @@ func (p *ImageProxy) fetchRemoteImageOnce(ctx context.Context, raw, host string,
 		return remoteImageFetchResult{}, errImageProxyRequestSetup
 	}
 	applyRemoteImageHeaders(req, host, raw)
+	// 已挂载的远程 Emby：用账号当前 token 覆盖旧凭据，返回头形式对端优先采纳。
+	p.applyRemoteEmbyAuth(ctx, req, host)

 	resp, err := candidate.client.Do(req)
 	if err != nil {
@@ -80,6 +82,9 @@ func (p *ImageProxy) fetchRemoteImageOnce(ctx context.Context, raw, host string,
 	defer resp.Body.Close()
 	if resp.StatusCode >= 400 {
 		p.log.Warn("imageproxy: upstream returned non-OK", zap.String("host", host), zap.String("client", candidate.name), zap.String("status", resp.Status))
+		if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+			return remoteImageFetchResult{}, errImageProxyUnauthorized
+		}
 		return remoteImageFetchResult{}, errors.New("upstream returned " + resp.Status)
 	}
 	if err := p.streamImageToCache(cachePath, failPath, resp.Body); err != nil {
@@ -0,0 +1,239 @@
+package reader
+
+import (
+	"encoding/json"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+)
+
+// 本文件：段落评论接口（/para_review）的分页适配。
+//
+// 上游聚合站自带的评论页按 page=N 翻页（滑到底请求 page=2、page=3…），但它的列表
+// 接口早就改成了游标分页：响应里给 next_cursor，请求时要带 cursor=。接口不认识
+// page，于是每次「加载更多」都原样返回第一页——一条新评论都加不进去，has_more 又
+// 始终是 true，评论页就一遍遍触发加载更多、反复闪骨架屏。用户看到的就是「段评往
+// 下滑一闪一闪」，其实评论一条没多。
+//
+// 评论页是上游 HTML，改不了，于是在代理层做最小适配：
+//   - 请求带 page=N（N>1）且有上一页给的游标时，换成 cursor= 请求；
+//   - 某页返回的 comment_id 全是已经见过的，就把 has_more 改成 false 收尾，
+//     免得页面在「加载更多 → 没有新内容」之间空转。
+//
+// 只认路径以 /para_review 结尾、带 page 且不带 cursor 的请求；对不上就原样透传，
+// 不影响别的书源。
+
+// commentPageState 一个评论列表（同一段落 + 同一排序）的翻页状态。
+type commentPageState struct {
+	// cursor 上一页响应给的游标：下一页请求用它代替 page。
+	cursor string
+	// seen 已经下发给页面的 comment_id：整页重复时据此收尾。
+	seen map[string]struct{}
+}
+
+// commentPager 承载页面里评论接口的翻页适配器（每个承载页面一份）。
+type commentPager struct {
+	mu     sync.Mutex
+	states map[string]*commentPageState
+}
+
+func newCommentPager() *commentPager {
+	return &commentPager{states: map[string]*commentPageState{}}
+}
+
+// rewriteRequest 按需把 page=N 改写成 cursor=<上一页游标>。
+//
+// 返回改写后的地址与状态键（空串表示这个请求不需要适配，调用方也不必观察响应）。
+func (p *commentPager) rewriteRequest(target string) (string, string) {
+	if p == nil {
+		return target, ""
+	}
+	parsed, err := url.Parse(target)
+	if err != nil || !isCommentListPath(parsed.Path) {
+		return target, ""
+	}
+	query := parsed.Query()
+	pageRaw := strings.TrimSpace(query.Get("page"))
+	if pageRaw == "" || strings.TrimSpace(query.Get("cursor")) != "" {
+		return target, ""
+	}
+	page, err := strconv.Atoi(pageRaw)
+	if err != nil || page < 1 {
+		return target, ""
+	}
+	key := commentPageKey(parsed.Path, query)
+	if page == 1 {
+		// 重新加载 / 换了排序：游标与去重表都从头来。
+		p.mu.Lock()
+		delete(p.states, key)
+		p.mu.Unlock()
+		return target, key
+	}
+	p.mu.Lock()
+	cursor := ""
+	if st := p.states[key]; st != nil {
+		cursor = st.cursor
+	}
+	p.mu.Unlock()
+	if cursor == "" {
+		// 不是从第一页翻过来的（没有游标可用）：原样透传，仍然观察响应，
+		// 靠下面的「整页重复」判断让页面停下来。
+		return target, key
+	}
+	query.Set("cursor", cursor)
+	query.Del("page")
+	parsed.RawQuery = query.Encode()
+	return parsed.String(), key
+}
+
+// observeResponse 观察评论列表响应：记下游标，并在整页重复时把 has_more 改成 false。
+func (p *commentPager) observeResponse(key, body string) string {
+	if p == nil || key == "" {
+		return body
+	}
+	trimmed := strings.TrimSpace(body)
+	if !strings.HasPrefix(trimmed, "{") {
+		return body
+	}
+	var env commentListEnvelope
+	if err := json.Unmarshal([]byte(trimmed), &env); err != nil {
+		return body
+	}
+	if env.Data.Comments == nil && env.Data.HasMore == nil {
+		return body
+	}
+	ids := make([]string, 0, len(env.Data.Comments))
+	for _, c := range env.Data.Comments {
+		if id := strings.TrimSpace(c.CommentID); id != "" {
+			ids = append(ids, id)
+		}
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.states == nil {
+		p.states = map[string]*commentPageState{}
+	}
+	st := p.states[key]
+	if st == nil {
+		st = &commentPageState{seen: map[string]struct{}{}}
+		p.states[key] = st
+	}
+	repeated := len(ids) > 0
+	for _, id := range ids {
+		if _, ok := st.seen[id]; !ok {
+			repeated = false
+			break
+		}
+	}
+	if repeated && env.Data.HasMore != nil && *env.Data.HasMore {
+		// 整页都是老评论：接口不认 page，再翻下去也只会拿到同一页。
+		// 改掉 has_more，让页面显示「没有更多了」，别再反复拉取闪骨架屏。
+		if replaced, ok := setFirstJSONBoolFalse(trimmed, "has_more"); ok {
+			return replaced
+		}
+		return body
+	}
+	for _, id := range ids {
+		st.seen[id] = struct{}{}
+	}
+	if env.Data.HasMore != nil && !*env.Data.HasMore {
+		// 已经是最后一页：游标链到头，清掉它，页面万一再要一页也别拿旧游标
+		// 去请求（那种请求会落在下面的「整页重复」判断上收尾）。
+		st.cursor = ""
+		return body
+	}
+	// 游标只在拿到新内容时前进：请求失败/重复时页面会重试同一页，
+	// 游标也跟着重试同一个。
+	if cursor := rawJSONScalar(env.Data.Cursor); cursor != "" {
+		st.cursor = cursor
+	}
+	return body
+}
+
+// commentListEnvelope 评论列表响应里我们关心的字段。
+type commentListEnvelope struct {
+	Data struct {
+		Comments []struct {
+			CommentID string `json:"comment_id"`
+		} `json:"comments"`
+		HasMore *bool           `json:"has_more"`
+		Cursor  json.RawMessage `json:"next_cursor"`
+	} `json:"data"`
+}
+
+// isCommentListPath 判断是否是段落评论列表接口（/para_review）。
+func isCommentListPath(path string) bool {
+	p := strings.TrimSuffix(strings.ToLower(strings.TrimSpace(path)), "/")
+	return strings.HasSuffix(p, "/para_review")
+}
+
+// commentPageKey 生成翻页状态键：接口路径 + 除 page/cursor 之外的查询参数。
+// 同一段落的不同排序（sort_by）各自一套状态，互不干扰。
+func commentPageKey(path string, query url.Values) string {
+	rest := make(url.Values, len(query))
+	for k, v := range query {
+		if k == "page" || k == "cursor" {
+			continue
+		}
+		rest[k] = v
+	}
+	keys := make([]string, 0, len(rest))
+	for k := range rest {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	var b strings.Builder
+	b.WriteString(path)
+	for _, k := range keys {
+		for _, v := range rest[k] {
+			b.WriteString("|" + k + "=" + v)
+		}
+	}
+	return b.String()
+}
+
+// rawJSONScalar 取一个 JSON 标量的字面量（游标是毫秒时间戳，可能被上游写成数字）。
+func rawJSONScalar(raw json.RawMessage) string {
+	s := strings.TrimSpace(string(raw))
+	if s == "" || s == "null" {
+		return ""
+	}
+	if strings.HasPrefix(s, `"`) {
+		var out string
+		if json.Unmarshal(raw, &out) == nil {
+			return strings.TrimSpace(out)
+		}
+		return ""
+	}
+	return s
+}
+
+// setFirstJSONBoolFalse 把 JSON 里第一个 `"key":true` 改成 `"key":false`。
+//
+// 只做这一处等长替换，不重新序列化整份响应：评论里的 user_id、时间戳动辄十几位，
+// 走一遍 float64 会变成科学计数法，页面再解析就废了。
+func setFirstJSONBoolFalse(body, key string) (string, bool) {
+	token := `"` + key + `"`
+	idx := strings.Index(body, token)
+	if idx < 0 {
+		return body, false
+	}
+	i := idx + len(token)
+	for i < len(body) && (body[i] == ' ' || body[i] == '\t' || body[i] == '\n' || body[i] == '\r') {
+		i++
+	}
+	if i >= len(body) || body[i] != ':' {
+		return body, false
+	}
+	i++
+	for i < len(body) && (body[i] == ' ' || body[i] == '\t' || body[i] == '\n' || body[i] == '\r') {
+		i++
+	}
+	if !strings.HasPrefix(body[i:], "true") {
+		return body, false
+	}
+	return body[:i] + "false" + body[i+len("true"):], true
+}
@@ -0,0 +1,187 @@
+package reader
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/service/reader/rule"
+)
+
+// 本文件：段落评论翻页适配（browser_comment_page.go）的测试。
+//
+// 覆盖两件事：
+//  1. page=N（N>1）被换成上一页响应给的 cursor；
+//  2. 整页重复（接口不认 page 时的表现）时把 has_more 改成 false，页面才会收尾。
+
+const commentParaBase = "https://cmt.example.com/para_review?item_id=X&para=1&source=QQ"
+
+func TestCommentPagerRewritesPageToCursor(t *testing.T) {
+	p := newCommentPager()
+
+	// 第一页：原样请求，响应里的游标被记下
+	target, key := p.rewriteRequest(commentParaBase + "&page=1")
+	if key == "" {
+		t.Fatal("段落评论接口应被识别")
+	}
+	if target != commentParaBase+"&page=1" {
+		t.Fatalf("第一页不该改写: %q", target)
+	}
+	p.observeResponse(key, `{"code":0,"data":{"comments":[{"comment_id":"c1"}],"has_more":true,"next_cursor":"1500000000000"}}`)
+
+	// 第二页：改成带 cursor 的请求，page 不再出现
+	target, key2 := p.rewriteRequest(commentParaBase + "&page=2")
+	if key2 != key {
+		t.Fatalf("同一段落的状态键应一致: %q vs %q", key2, key)
+	}
+	if !strings.Contains(target, "cursor=1500000000000") || strings.Contains(target, "page=") {
+		t.Fatalf("第二页应换成 cursor 请求: %q", target)
+	}
+
+	// 拿到新评论：游标前进到下一页
+	p.observeResponse(key, `{"code":0,"data":{"comments":[{"comment_id":"c2"}],"has_more":true,"next_cursor":"1400000000000"}}`)
+	target, _ = p.rewriteRequest(commentParaBase + "&page=3")
+	if !strings.Contains(target, "cursor=1400000000000") {
+		t.Fatalf("第三页应使用新的游标: %q", target)
+	}
+
+	// 重新加载（page=1）会把整轮状态清掉：没有游标就原样透传
+	p.rewriteRequest(commentParaBase + "&page=1")
+	target, _ = p.rewriteRequest(commentParaBase + "&page=2")
+	if strings.Contains(target, "cursor=") {
+		t.Fatalf("重置后不该还带着旧游标: %q", target)
+	}
+}
+
+func TestCommentPagerStopsOnRepeatedPage(t *testing.T) {
+	p := newCommentPager()
+	_, key := p.rewriteRequest(commentParaBase + "&page=1")
+	first := `{"code":0,"data":{"comments":[{"comment_id":"c1","like_count":562,"user":{"user_id":601948729051219}}],"has_more":true,"next_cursor":"1500000000000"}}`
+	if got := p.observeResponse(key, first); got != first {
+		t.Fatalf("第一页不该被改写: %q", got)
+	}
+
+	// 同一页又被返回一次（接口忽略 page）：改 has_more，让页面显示「没有更多了」
+	repeat := `{"code":0,"data":{"comments":[{"comment_id":"c1","like_count":562,"user":{"user_id":601948729051219}}],"has_more":true,"next_cursor":"1500000000000"}}`
+	got := p.observeResponse(key, repeat)
+	if !strings.Contains(got, `"has_more":false`) {
+		t.Fatalf("重复页应把 has_more 改成 false: %q", got)
+	}
+	// 只动 has_more 一处，其它字段（尤其是大整数）保持原样
+	if strings.Replace(got, `"has_more":false`, `"has_more":true`, 1) != first {
+		t.Fatalf("除 has_more 外不应改动响应: %q", got)
+	}
+	// 重复页不再推进游标
+	target, _ := p.rewriteRequest(commentParaBase + "&page=2")
+	if !strings.Contains(target, "cursor=1500000000000") {
+		t.Fatalf("游标不该被重复页顶掉: %q", target)
+	}
+}
+
+func TestCommentPagerIgnoresOtherRequests(t *testing.T) {
+	p := newCommentPager()
+	cases := []string{
+		"https://cmt.example.com/book/detail?page=2",               // 不是评论接口
+		"https://cmt.example.com/para_review?item_id=X",            // 没有 page
+		"https://cmt.example.com/para_review?item_id=X&cursor=1",   // 已经在用游标
+		"https://cmt.example.com/para_review?item_id=X&page=0",     // page 非法
+		"https://cmt.example.com/para_review?item_id=X&sort_by=1&", // 没有 page
+	}
+	for _, target := range cases {
+		got, key := p.rewriteRequest(target)
+		if got != target || key != "" {
+			t.Fatalf("不该改写的请求被处理了: %q -> %q (key=%q)", target, got, key)
+		}
+	}
+	// 非 JSON 响应原样返回
+	if got := p.observeResponse("k", "<html></html>"); got != "<html></html>" {
+		t.Fatalf("非 JSON 响应被改动: %q", got)
+	}
+}
+
+// TestBrowserXHRCommentPagerFollowsCursor 端到端：页面按 page 翻页，
+// 代理层换成 cursor，接口给出新评论，最后一页重复时收尾。
+func TestBrowserXHRCommentPagerFollowsCursor(t *testing.T) {
+	svc, _ := newLoginTestService(t)
+
+	var mu sync.Mutex
+	seenCursors := []string{}
+	seenPages := []string{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/page":
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			_, _ = io.WriteString(w, `<html><body>comment page</body></html>`)
+		case "/para_review":
+			q := r.URL.Query()
+			mu.Lock()
+			seenCursors = append(seenCursors, q.Get("cursor"))
+			seenPages = append(seenPages, q.Get("page"))
+			mu.Unlock()
+			w.Header().Set("Content-Type", "application/json; charset=utf-8")
+			// 上游只认 cursor：不认识 page，靠 next_cursor 一页页往前。
+			switch q.Get("cursor") {
+			case "":
+				_, _ = io.WriteString(w, `{"code":0,"data":{"comments":[{"comment_id":"c1"}],"has_more":true,"next_cursor":"1500000000000"}}`)
+			case "1500000000000":
+				_, _ = io.WriteString(w, `{"code":0,"data":{"comments":[{"comment_id":"c2"}],"has_more":true,"next_cursor":"1400000000000"}}`)
+			case "1400000000000":
+				_, _ = io.WriteString(w, `{"code":0,"data":{"comments":[{"comment_id":"c3"}],"has_more":false,"next_cursor":""}}`)
+			default:
+				// 兜底分支：上游把同一页又给了一遍（页面的 page 循环就会走到这里）
+				_, _ = io.WriteString(w, `{"code":0,"data":{"comments":[{"comment_id":"c3"}],"has_more":true,"next_cursor":"1300000000000"}}`)
+			}
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+
+	entry, err := svc.registerBrowser(t.Context(), srv.URL, "src-1", readerTestUserID,
+		browserCookieTarget{}, rule.BrowserTask{URL: srv.URL + "/page", Title: "段评"}, browserModeOpen)
+	if err != nil {
+		t.Fatalf("登记承载页面失败: %v", err)
+	}
+	call := func(page string) string {
+		t.Helper()
+		res, err := svc.ProxyBrowserXHR(t.Context(), entry.id, http.MethodGet,
+			srv.URL+"/para_review?item_id=X&para=1&source=QQ&page="+page, nil, "")
+		if err != nil {
+			t.Fatalf("代理请求失败: %v", err)
+		}
+		return res.Body
+	}
+
+	if body := call("1"); !strings.Contains(body, `"has_more":true`) || !strings.Contains(body, "c1") {
+		t.Fatalf("第一页响应异常: %q", body)
+	}
+	if body := call("2"); !strings.Contains(body, "c2") {
+		t.Fatalf("第二页应拿到下一页评论: %q", body)
+	}
+	if body := call("3"); !strings.Contains(body, "c3") || !strings.Contains(body, `"has_more":false`) {
+		t.Fatalf("第三页应是真正的最后一页: %q", body)
+	}
+	// 页面不知道已经到底，还可能再要一页：上游又把最后一页给了一遍，
+	// 适配层要把 has_more 改成 false，页面才会显示「没有更多了」并停下。
+	last := call("4")
+	if !strings.Contains(last, `"has_more":false`) {
+		t.Fatalf("整页重复时应收尾（has_more=false）: %q", last)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if strings.Join(seenPages, ",") != "1,,,4" {
+		t.Fatalf("page 参数只应出现在没有游标可用的请求上: %v", seenPages)
+	}
+	if strings.Join(seenCursors, ",") != ",1500000000000,1400000000000," {
+		t.Fatalf("游标传递不符预期: %v", seenCursors)
+	}
+	var env map[string]any
+	if err := json.Unmarshal([]byte(last), &env); err != nil {
+		t.Fatalf("收尾后的响应不是合法 JSON: %v", err)
+	}
+}
@@ -103,6 +103,9 @@ type pendingBrowser struct {
 	finalURL string
 	mode     string
 	expires  time.Time
+	// comments 段落评论接口的翻页适配（上游页面按 page 翻页，接口只认 cursor，
+	// 见 browser_comment_page.go）。
+	comments *commentPager

 	done     chan struct{}
 	mu       sync.Mutex
@@ -218,6 +221,7 @@ func (s *ReaderService) registerBrowser(ctx context.Context, sourceURL, sourceID
 		mode:      mode,
 		expires:   time.Now().Add(browserPageTTL),
 		done:      make(chan struct{}),
+		comments:  newCommentPager(),
 	}

 	s.browserMu.Lock()
@@ -375,6 +379,12 @@ func (s *ReaderService) prepareBrowserPage(ctx context.Context, sourceURL, id st
 	if err != nil {
 		return "", "", fmt.Errorf("打开页面失败: %w", err)
 	}
+	// 空响应没有可展示的内容：以前照样包一层空 <pre> 交给 iframe，面板就是一片白，
+	// 用户看不出是地址有问题还是自己没登录。这里直接报错（如段评地址参数被改写、
+	// 上游按缺参数返回空 body 的情形）。
+	if strings.TrimSpace(body) == "" {
+		return "", "", fmt.Errorf("目标地址没有返回任何内容: %s", truncateForLog(req.URL, 120))
+	}
 	cookie := s.browserCookieHeader(ctx, sourceURL, finalURL)
 	if !strings.Contains(strings.ToLower(contentType), "html") {
 		// 非 HTML（如 JSON 接口）：包一层 <pre>，至少让用户看到内容
@@ -505,6 +515,13 @@ func (s *ReaderService) ProxyBrowserXHR(ctx context.Context, id, method, target
 	if method == "" {
 		method = http.MethodGet
 	}
+	// 段落评论接口：评论页按 page=N 翻页，而接口只认 cursor（见
+	// browser_comment_page.go）。改写发生在补书源凭据之前，Cookie/Referer
+	// 仍然按目标站点选取。
+	pagerKey := ""
+	if entry.comments != nil {
+		target, pagerKey = entry.comments.rewriteRequest(target)
+	}
 	reqCtx, cancel := context.WithTimeout(ctx, browserFetchTimeout)
 	defer cancel()
 	// 挂上 sink：页面自己发起的请求（如扫码登录的轮询/取票跳转）下发的
@@ -571,6 +588,9 @@ func (s *ReaderService) ProxyBrowserXHR(ctx context.Context, id, method, target
 	out := &BrowserXHRResult{Status: resp.StatusCode, ContentType: contentType}
 	if isTextualContent(contentType) {
 		out.Body = string(data)
+		if entry.comments != nil && pagerKey != "" {
+			out.Body = entry.comments.observeResponse(pagerKey, out.Body)
+		}
 	} else {
 		out.Body = base64.StdEncoding.EncodeToString(data)
 		out.Base64 = true
@@ -723,8 +743,34 @@ func (s *ReaderService) browserAssetSig(id, target string) string {
 	return s.browserSign("asset|" + id + "|" + target)
 }

-func (s *ReaderService) browserPageURL(id string) string {
-	return "/api/reader/browser/page?id=" + url.QueryEscape(id) + "&s=" + s.browserPageSig(id)
+// browserPageURL 生成 iframe 承载地址。
+//
+// 承载页面常常靠 location.search 取值：光遇聚合的段评页就是从 ?item_id&para&source
+// 读出「哪本书的哪一段、哪个来源」，再据此请求 /para_review。承载地址是我们自己的
+// 代理路径，页面看到的 query 只有 id/s，原地址的参数全丢了——页面于是按缺参数去
+// 请求评论接口，气泡数照样显示，点开却一条段评都没有。
+//
+// 所以把原地址的 query 原样拼在签名参数之后：页面看到的 search 与原站一致。
+// 我们自己的 id/s 放最前，Gin 取同名的第一个值，不会被原地址里的同名参数顶掉。
+func (s *ReaderService) browserPageURL(id, target string) string {
+	u := "/api/reader/browser/page?id=" + url.QueryEscape(id) + "&s=" + s.browserPageSig(id)
+	if q := browserTargetQuery(target); q != "" {
+		u += "&" + q
+	}
+	return u
+}
+
+// browserTargetQuery 取原地址的 query（不含 `?`）；data: 地址或解析失败时返回空串。
+func browserTargetQuery(target string) string {
+	target = strings.TrimSpace(target)
+	if target == "" || strings.HasPrefix(strings.ToLower(target), "data:") {
+		return ""
+	}
+	parsed, err := url.Parse(target)
+	if err != nil {
+		return ""
+	}
+	return parsed.RawQuery
 }

 // browserAssetProxyURL 生成资源代理地址（iframe 页面内引用用）。
@@ -882,7 +928,7 @@ func (s *ReaderService) pageOfLocked(e *pendingBrowser) BrowserPage {
 		Title:     e.request.Title,
 		Mode:      e.mode,
 		Seq:       e.seq,
-		PageURL:   s.browserPageURL(e.id),
+		PageURL:   s.browserPageURL(e.id, e.request.URL),
 		Refetch:   e.request.Refetch,
 		SourceID:  e.sourceID,
 		TargetURL: target,
@@ -167,6 +167,51 @@ func TestBrowserPanelCancelReleasesBlock(t *testing.T) {
 	}
 }

+// TestBrowserPageURLKeepsTargetQuery 承载地址必须原样带上目标地址的 query。
+//
+// 光遇聚合的段评页从 location.search 读 item_id/para/source，再据此请求评论接口。
+// 承载地址若只剩我们自己的 id/s，页面就按缺参数去请求：段评气泡上的数字照常有，
+// 点开却一条评论都没有。
+func TestBrowserPageURLKeepsTargetQuery(t *testing.T) {
+	svc, _ := newLoginTestService(t)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write([]byte(`<html><body>comment page</body></html>`))
+	}))
+	defer srv.Close()
+
+	// 目标地址里故意带上与我们同名的 s/id：它们不能顶掉签名参数。
+	target := srv.URL + "/get_para_review?item_id=abc&para=1&source=QQ%E9%98%85%E8%AF%BB&s=decoy&id=decoy"
+	entry, err := svc.registerBrowser(t.Context(), srv.URL, "src-1", readerTestUserID,
+		browserCookieTarget{}, rule.BrowserTask{URL: target, Title: "段评"}, browserModeOpen)
+	if err != nil {
+		t.Fatalf("登记承载页面失败: %v", err)
+	}
+
+	page := svc.browserPageOf(entry)
+	u, err := url.Parse(page.PageURL)
+	if err != nil {
+		t.Fatalf("承载地址不合法: %q", page.PageURL)
+	}
+	q := u.Query()
+	if q.Get("item_id") != "abc" || q.Get("para") != "1" || q.Get("source") != "QQ阅读" {
+		t.Fatalf("承载地址丢了目标参数（段评页会因此取不到评论）: %q", page.PageURL)
+	}
+	// 路由按 id/s 取承载的页面快照，同名参数必须仍指向我们自己的待办
+	if q.Get("id") != entry.id || q.Get("s") != svc.browserPageSig(entry.id) {
+		t.Fatalf("同名参数顶掉了签名参数: %q", page.PageURL)
+	}
+	if _, err := svc.VerifyBrowserPage(q.Get("id"), q.Get("s")); err != nil {
+		t.Fatalf("带业务参数后签名校验失败: %v", err)
+	}
+	// 没有 query 的地址（含 data: 页面）不该多出参数
+	for _, plain := range []string{"https://panel.example.com/plain", "data:text/html;base64,AAA"} {
+		if got := svc.browserPageURL("id1", plain); strings.Count(got, "&") != 1 {
+			t.Fatalf("无 query 的地址被拼进了多余参数: %q", got)
+		}
+	}
+}
+
 // TestBrowserPanelInjectsSourceCookies http(s) 页面必须由服务端带书源 Cookie
 // 抓取，否则「用户后台」在浏览器里永远是未登录状态。
 func TestBrowserPanelInjectsSourceCookies(t *testing.T) {
@@ -2,6 +2,7 @@ package rule

 import (
 	"net/url"
+	"regexp"
 	"strings"

 	"github.com/PaesslerAG/jsonpath"
@@ -450,10 +451,7 @@ func (a *AnalyzeRule) getStringRules(ruleList []*SourceRule, mContent any, isUrl
 	if result == nil {
 		result = ""
 	}
-	str := resultString(result)
-	if strings.Contains(str, "&") {
-		str = html.UnescapeString(str)
-	}
+	str := unescapeRuleEntities(resultString(result))
 	if isUrl {
 		if strings.TrimSpace(str) == "" {
 			// 对应 legado：取值为空时回退 baseUrl，让相对地址还能解析。
@@ -597,6 +595,49 @@ func applyReplaceRegex(result string, r ResolvedSourceRule) string {
 	return regexReplaceAll(r.ReplaceRegex, result, r.Replacement)
 }

+// entityRefRe 匹配一个 HTML 字符引用：命名实体（&amp;、&nbsp;）、十进制（&#39;）、
+// 十六进制（&#x27;）。分号可选——旧式简写（&nbsp、&amp）在 HTML 文本里同样成立。
+var entityRefRe = regexp.MustCompile(`&(?:[a-zA-Z][a-zA-Z0-9]{1,31}|#[0-9]{1,7}|#[xX][0-9a-fA-F]{1,6});?`)
+
+// unescapeRuleEntities 还原规则结果里的 HTML 实体（`&amp;` → `&`、`&#39;` → `'`）。
+//
+// 唯一的例外是「不带分号的旧式简写后面紧跟 = 或字母数字」这一种：HTML5 里这类写法
+// 属于历史匹配，而规则结果并不是纯 HTML 文本——正文、地址、查询串都在同一份字符串里。
+// 按浏览器语义无差别还原会把查询串吃掉：光遇聚合的段评地址
+// `…?item_id=X&para=1&source=QQ阅读` 会变成 `…?item_id=X¶=1&source=QQ阅读`，
+// 上游按缺参数处理返回空页面，段评面板就只剩一片空白（见 reader/comment.go）。
+func unescapeRuleEntities(s string) string {
+	if !strings.Contains(s, "&") {
+		return s
+	}
+	var b strings.Builder
+	last := 0
+	for _, loc := range entityRefRe.FindAllStringIndex(s, -1) {
+		match := s[loc[0]:loc[1]]
+		if !strings.HasSuffix(match, ";") && loc[1] < len(s) && isEntityStopByte(s[loc[1]]) {
+			continue
+		}
+		decoded := html.UnescapeString(match)
+		if decoded == match {
+			continue // 不是已知实体，原样保留
+		}
+		b.WriteString(s[last:loc[0]])
+		b.WriteString(decoded)
+		last = loc[1]
+	}
+	if last == 0 {
+		return s
+	}
+	b.WriteString(s[last:])
+	return b.String()
+}
+
+// isEntityStopByte 判断旧式简写实体后面这个字符是否让它失去实体语义
+// （HTML5 规定不带分号的引用后跟 = 或字母数字时按普通文本处理）。
+func isEntityStopByte(c byte) bool {
+	return c == '=' || c >= '0' && c <= '9' || c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z'
+}
+
 // resultString 对应 Kotlin 的 result.toString()。
 func resultString(result any) string {
 	switch t := result.(type) {
@@ -0,0 +1,80 @@
+package rule
+
+import (
+	"strings"
+	"testing"
+)
+
+// 规则结果里的地址带查询串。html.UnescapeString 会按 HTML5 旧式简写把 &para 吃成
+// 「¶」，参数名变成 ¶ 之后上游按缺参数返回空页面——光遇聚合的段评面板一片空白
+// 就是这个原因（见 reader/comment.go、reader/browser_panel.go）。
+func TestUnescapeRuleEntitiesKeepsQueryString(t *testing.T) {
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "段评地址里的 &para 不能被当成实体",
+			in:   "https://v1.qingtian618.com/get_para_review?item_id=X&para=1&source=QQ%E9%98%85%E8%AF%BB",
+			want: "https://v1.qingtian618.com/get_para_review?item_id=X&para=1&source=QQ%E9%98%85%E8%AF%BB",
+		},
+		{
+			name: "&not 开头的参数名同样不能被吃掉",
+			in:   "https://example.com/api?book=1&notify=1",
+			want: "https://example.com/api?book=1&notify=1",
+		},
+		{
+			name: "带分号的实体照旧还原",
+			in:   "url?a=1&amp;b=2&amp;c=3",
+			want: "url?a=1&b=2&c=3",
+		},
+		{
+			name: "数字实体照旧还原",
+			in:   "&#39;引号&#39; &#x27;x&#x27; &#169;",
+			want: "'引号' 'x' ©",
+		},
+		{
+			name: "文字里的旧式简写（后面不是 = 或字母数字）照旧还原",
+			in:   "第一段&nbsp第二段&copy 2026&times",
+			want: "第一段\u00a0第二段© 2026×",
+		},
+		{
+			name: "不是实体的 & 原样保留",
+			in:   "a & b &foo; c",
+			want: "a & b &foo; c",
+		},
+		{
+			name: "不含 & 的字符串直接放行",
+			in:   "魔法大陆。",
+			want: "魔法大陆。",
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := unescapeRuleEntities(c.in); got != c.want {
+				t.Fatalf("unescapeRuleEntities(%q) = %q，期望 %q", c.in, got, c.want)
+			}
+		})
+	}
+}
+
+// 端到端：走 GetString 的规则结果同样不能把段评地址里的 &para 吃掉
+// （光遇聚合的正文规则是 <js>…</js>$.content 形态，最终取 $.content）。
+func TestGetStringCommentURLKeepsParaParam(t *testing.T) {
+	const url = "https://v1.qingtian618.com/get_para_review?item_id=YmlkPTYxNDc4MiZjaWQ9MQ&para=11&source=QQ%E9%98%85%E8%AF%BB"
+	payload := `{"content":"<p>正文<comment ident=\"` + url + `\" count=\"39\" /></p>"}`
+
+	a := NewAnalyzeRule()
+	a.SetContent(payload, "https://v1.qingtian618.com")
+	got, err := a.GetString("$.content", nil, false)
+	if err != nil {
+		t.Fatalf("GetString: %v", err)
+	}
+	if !strings.Contains(got, "&para=11") {
+		t.Fatalf("段评地址里的 &para=11 被改写了: %q", got)
+	}
+	if strings.Contains(got, "\u00b6") {
+		t.Fatalf("段评地址里出现了 ¶（HTML 旧式实体还原的产物）: %q", got)
+	}
+}
@@ -237,6 +237,15 @@ func (b *serviceContainerBuilder) initImageProxy() {
 		b.c.ImageProxy.SetAllowedRemoteHostsProvider(func() []string {
 			return b.c.EmbyRemote.ConfiguredRemoteHosts(context.Background())
 		})
+		// 远程 Emby 的图片 URL 会带着签发时的 api_key 长期缓存/下发；轮换后
+		// URL 里的旧值必然过期。回源时改用账号当前 token，并在上游 401/403 时
+		// 重新登录一次再重试，封面图不再依赖人工改账号。
+		b.c.ImageProxy.SetRemoteEmbyAuthProvider(func(ctx context.Context, host string) (string, bool) {
+			return b.c.EmbyRemote.RemoteEmbyImageTokenForHost(ctx, host)
+		})
+		b.c.ImageProxy.SetRemoteEmbyAuthRefresher(func(ctx context.Context, host string) (string, error) {
+			return b.c.EmbyRemote.RefreshRemoteEmbyImageTokenForHost(ctx, host)
+		})
 	}
 	b.c.Scan.SetImageProxy(b.c.ImageProxy)
 	b.c.Scraper.SetImageProxy(b.c.ImageProxy)
@@ -41,10 +41,10 @@ export const MediaCard = memo(function MediaCard({
  const card = (
      <div
        ref={ref}
-        className="relative overflow-hidden rounded-2xl border border-[var(--app-border)] bg-[var(--app-panel)] shadow-[0_1px_3px_rgba(0,0,0,0.01),0_1px_2px_rgba(0,0,0,0.015)] transition-all duration-300 hover:scale-[1.04] hover:-translate-y-1.5 hover:border-brand-500/40 hover:shadow-[0_12px_32px_var(--app-shadow)]"
+        className="relative flex h-full flex-col overflow-hidden rounded-2xl border border-[var(--app-border)] bg-[var(--app-panel)] shadow-[0_1px_3px_rgba(0,0,0,0.01),0_1px_2px_rgba(0,0,0,0.015)] transition-all duration-300 hover:scale-[1.04] hover:-translate-y-1.5 hover:border-brand-500/40 hover:shadow-[0_12px_32px_var(--app-shadow)]"
      >
        {/* Poster Wrapper */}
-        <div className="relative aspect-[2/3] w-full overflow-hidden bg-[var(--app-panel-soft)]">
+        <div className="relative aspect-[2/3] w-full shrink-0 overflow-hidden bg-[var(--app-panel-soft)]">
          {media.poster_url ? (
            <>
              {posterFit === 'contain' && (
@@ -120,26 +120,34 @@ export const MediaCard = memo(function MediaCard({

        {/* Media Metadata Info */}
        <div className={`space-y-1 border-t border-[var(--app-border)] bg-[var(--app-panel)] ${
-          compact ? 'p-2' : 'p-4'
+          compact ? 'p-2' : 'p-2.5 sm:p-4'
        }`}>
-          <p className={`truncate font-bold text-[var(--app-text)] transition-colors duration-200 group-hover:text-brand-500 ${
-            compact ? 'text-xs' : 'text-sm'
+          {/* 手机端一张卡只有 ~100px 宽：标题放开到两行，并预留两行高度，
+              这样同一行的卡片不会因为标题行数不同而参差不齐。 */}
+          <p className={`font-bold text-[var(--app-text)] transition-colors duration-200 group-hover:text-brand-500 ${
+            compact
+              ? 'truncate text-xs'
+              : 'line-clamp-2 min-h-[2.75em] text-[13px] leading-snug sm:line-clamp-none sm:min-h-0 sm:truncate sm:text-sm sm:leading-normal'
          }`}>
            {media.title}
          </p>
-          <div className="flex items-center justify-between gap-2 text-[11px] font-bold uppercase tracking-wider text-[var(--app-muted)]">
-            <span>{media.year > 0 ? media.year : "未知年份"}</span>
-            <span className="flex items-center gap-1.5">
+          {/* 单行、不折行：年份可截断，徽标永不压缩。折行会让同一行里各卡片的
+              徽标落位高低不一，看起来就是「错位」，所以宁可极窄屏上截断年份。
+              min-h 统一行高，避免有/无徽标的卡片年份基线差几像素。 */}
+          <div className="flex min-h-[21px] items-center text-[10px] font-bold uppercase text-[var(--app-muted)] sm:min-h-0 sm:gap-x-2 sm:text-[11px] sm:tracking-wider">
+            <span className="truncate">{media.year > 0 ? media.year : "未知年份"}</span>
+            <span className="ml-auto flex shrink-0 items-center gap-0.5 sm:gap-1.5">
              {/* 集数/版本数徽标：放在海报下方的信息行而不是压在画面上。海报底部通常
                  自带片名，角标会盖住它（Game of Thrones / Breaking Bad 都很明显）。 */}
              {(count !== undefined && count > 1) || (count === undefined && versionCount > 1) ? (
-                <span className="inline-flex items-center gap-1 rounded-xl border border-[var(--app-border)] bg-[var(--app-panel-soft)] px-1.5 py-0.5 text-[var(--app-subtle)]">
+                <span className="inline-flex items-center gap-0.5 whitespace-nowrap rounded-xl border border-[var(--app-border)] bg-[var(--app-panel-soft)] px-1 py-0.5 text-[var(--app-subtle)] sm:gap-1 sm:px-1.5">
                  <Layers size={10} className="shrink-0 text-[#c9954a]" />
                  <span>{count !== undefined && count > 1 ? `${count} 集` : `${versionCount} 版本`}</span>
                </span>
              ) : null}
+              {/* 编码格式在小卡片上没有信息价值，手机上直接隐藏，避免挤掉集数徽标。 */}
              {media.video_codec && (
-                <span className="rounded-xl border border-[var(--app-border)] bg-[var(--app-panel-soft)] px-1.5 py-0.5 text-[var(--app-subtle)]">
+                <span className="hidden whitespace-nowrap rounded-xl border border-[var(--app-border)] bg-[var(--app-panel-soft)] px-1.5 py-0.5 text-[var(--app-subtle)] sm:inline-block">
                  {media.video_codec}
                </span>
              )}
@@ -151,8 +159,8 @@ export const MediaCard = memo(function MediaCard({

  if (onClick) {
    return (
-      <div className="group relative block w-full">
-        <button type="button" onClick={onClick} className="block w-full text-left">
+      <div className="group relative block h-full w-full">
+        <button type="button" onClick={onClick} className="block h-full w-full text-left">
          {card}
        </button>
        {actionContent && (
@@ -166,8 +174,8 @@ export const MediaCard = memo(function MediaCard({

  if (actionContent) {
    return (
-      <div className="group relative block">
-        <Link to={href} state={linkState} className="block">
+      <div className="group relative block h-full">
+        <Link to={href} state={linkState} className="block h-full">
          {card}
        </Link>
        <div className={ACTION_OVERLAY_CLASS}>
@@ -178,7 +186,7 @@ export const MediaCard = memo(function MediaCard({
  }

  return (
-    <Link to={href} state={linkState} className="group block">
+    <Link to={href} state={linkState} className="group block h-full">
        {card}
    </Link>
  )
@@ -3,8 +3,9 @@ import { Virtuoso } from 'react-virtuoso'
 import clsx from 'clsx'

 // 与 LibraryMediaSections 等处的海报网格保持同一套响应式列配置。
+// 手机上单卡只有约 100px 宽，间距收到 gap-3 给标题和徽标多留一点宽度。
 export const MEDIA_GRID_CLASS =
-  'grid grid-cols-3 gap-4 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-7 2xl:grid-cols-8'
+  'grid grid-cols-3 gap-3 sm:gap-4 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-7 2xl:grid-cols-8'

 function getFallbackColumns(width: number): number {
  if (width >= 1536) return 8
@@ -105,7 +106,7 @@ export function VirtualMediaGrid({
          itemContent={(rowIndex) => {
            const start = rowIndex * columns
            return (
-              <div className={clsx(MEDIA_GRID_CLASS, rowIndex < rowCount - 1 && 'pb-4')}>
+              <div className={clsx(MEDIA_GRID_CLASS, rowIndex < rowCount - 1 && 'pb-3 sm:pb-4')}>
                {Array.from({ length: columns }, (_, colIndex) => {
                  const itemIndex = start + colIndex
                  if (itemIndex >= totalCount) {
@@ -5,6 +5,7 @@ import { ArrowLeft, ArrowLeftRight, BookOpen, ChevronDown, ChevronUp, Loader2, R

 import { readerAPI, type ReaderBook, type ReaderBookInfo, type ReaderSearchOrigin, type ReaderTocChapter } from '../../api/reader'
 import ReaderBookCover from '../../components/ReaderBookCover'
+import { pickChapterIndex } from './bookDetailModel'
 import { SourcePickerDialog } from './SourcePickerDialog'

 // 书籍详情页（仿 legado BookInfoActivity：封面 + 信息 + 简介 + 目录入口 + 加书架/开始阅读）。
@@ -86,7 +87,16 @@ export default function ReaderBookPage() {

  const firstReadableChapter = useMemo(() => chapters?.find((c) => !c.is_volume && c.url) ?? null, [chapters])

-  const startReading = async () => {
+  /**
+   * 目录点章：把点中的章节换算成阅读器要的序号（换算规则与理由见 bookDetailModel）。
+   */
+  const resolveChapterIndex = async (bookID: string, chapter: ReaderTocChapter): Promise<number> => {
+    const cached = await readerAPI.listChapters(bookID).catch(() => [])
+    return pickChapterIndex(cached, chapter)
+  }
+
+  // chapter 为空＝开始/继续阅读（沿用服务端进度）；给了章节＝目录点章跳读。
+  const startReading = async (chapter?: ReaderTocChapter) => {
    setBusy(true)
    try {
      let book = shelfBook
@@ -105,7 +115,9 @@ export default function ReaderBookPage() {
          cover_url: cover,
        })
      }
-      navigate(`/reader/view/${book.id}`)
+      // 目录点章：带上阅读器认识的 chapter 序号跳进去（没有它阅读器就用服务端进度）。
+      const index = chapter ? await resolveChapterIndex(book.id, chapter) : null
+      navigate(index === null ? `/reader/view/${book.id}` : `/reader/view/${book.id}?chapter=${index}`)
    } catch (e) {
      toast.error((e as { response?: { data?: { error?: string } } })?.response?.data?.error ?? '操作失败')
    } finally {
@@ -273,11 +285,11 @@ export default function ReaderBookPage() {
            <Trash2 size={13} className="mr-1 inline" /> 移出书架
          </button>
        ) : (
-          <button type="button" onClick={startReading} disabled={busy} className="btn-outline flex-1 text-xs disabled:opacity-50">
+          <button type="button" onClick={() => startReading()} disabled={busy} className="btn-outline flex-1 text-xs disabled:opacity-50">
            <BookOpen size={13} className="mr-1 inline" /> 加入书架
          </button>
        )}
-        <button type="button" onClick={startReading} disabled={busy || !firstReadableChapter} className="btn-primary flex-1 text-xs disabled:opacity-50">
+        <button type="button" onClick={() => startReading()} disabled={busy || !firstReadableChapter} className="btn-primary flex-1 text-xs disabled:opacity-50">
          {busy ? <Loader2 size={13} className="mr-1 inline animate-spin" /> : null}
          {shelfBook?.dur_chapter_title ? '继续阅读' : '开始阅读'}
        </button>
@@ -318,6 +330,16 @@ export default function ReaderBookPage() {
              <div key={c.index} className="px-1 py-1.5 text-xs text-[var(--app-muted)]">
                {c.is_volume ? (
                  <p className="font-bold text-[var(--app-text)]">{c.title}</p>
+                ) : c.url ? (
+                  // 点章节＝跳到阅读器并从这一章开始（听书源会自动起播这一章）。
+                  <button
+                    type="button"
+                    disabled={busy}
+                    onClick={() => startReading(c)}
+                    className="block w-full truncate text-left transition-colors hover:text-brand-600 disabled:opacity-50"
+                  >
+                    {c.title}
+                  </button>
                ) : (
                  c.title
                )}
@@ -220,7 +220,10 @@ export default function ReaderViewPage() {
        else if (b.dur_chapter_index > 0 && chs[b.dur_chapter_index] && !chs[b.dur_chapter_index].is_volume) {
          idx = b.dur_chapter_index
        }
-        pendingPosRef.current = b.dur_chapter_pos ?? 0
+        // 位置只在「接着上次那一章读」时恢复：URL 显式跳到别的章时，b.dur_chapter_pos
+        // 属于另一章，套到新章上会从中间开始（音频表现为一进去就从错的时间点续播）。
+        const resumingSavedChapter = !explicitChapter || idx === b.dur_chapter_index
+        pendingPosRef.current = resumingSavedChapter ? (b.dur_chapter_pos ?? 0) : 0
        // 听书：引擎是常驻的，可能已经自动播到更靠后的章，而服务端的进度还停在
        // 上一次落库的位置。这种「续听」场景要以引擎的实时章节为准，否则回到本书
        // 会把正在播的章节往回拽。URL 显式指定 chapter 时尊重 URL（那是明确的跳转）。
@@ -268,6 +271,10 @@ export default function ReaderViewPage() {
    // 响应，换源后还可能把旧源的正文塞进新书的缓存。
    const ac = new AbortController()
    ;(async () => {
+      // 每次重新取正文都先清掉上一次的报错。换源时的典型情形：服务端章节缓存刚被清空、
+      // 而本地 chapters 还是旧源的，这一次请求必然失败（「章节缓存为空」）；等新源目录
+      // 落地后正文 effect 会再来一次并且成功，但不清这里的话，旧错误会一直压在正文上。
+      setError('')
      setContent(null)
      setLoadingStage('content')
      try {
@@ -553,6 +560,12 @@ export default function ReaderViewPage() {
        await readerAPI.switchOrigin(book.id, origin)
        toast.success(`已切换到「${origin.origin_name || origin.origin}」`)
        contentCache.current.clear()
+        // 换源后服务端已清空章节缓存，而本地的 chapters 还是旧源的目录：不清理的话，
+        // 重新加载书籍期间（listBooks 已返回、新目录还没抓回来）正文 effect 会拿旧目录
+        // 去打新源，撞上「章节缓存为空」。这里先把正文/目录清空，等新源目录到位再取。
+        setError('')
+        setContent(null)
+        setChapters([])
        setReloadKey((v) => v + 1)
      } catch (e) {
        toast.error((e as { response?: { data?: { error?: string } } })?.response?.data?.error ?? '换源失败')
@@ -0,0 +1,46 @@
+import type { ReaderChapter, ReaderTocChapter } from '../../api/reader.ts'
+import { pickChapterIndex } from './bookDetailModel.ts'
+
+function check(name: string, condition: boolean) {
+  if (!condition) throw new Error(`bookDetailModel: ${name}`)
+}
+
+function cached(index: number, url: string): ReaderChapter {
+  return { index, title: `第${index}章`, url, is_volume: false }
+}
+
+function toc(index: number, url: string, over: Partial<ReaderTocChapter> = {}): ReaderTocChapter {
+  return { index, title: `第${index}章`, url, is_volume: false, update_time: '', ...over }
+}
+
+// 目录一致（正常情况）：按 url 定位到的序号与现抓序号相同
+{
+  const list = [cached(0, 'https://s/1'), cached(1, 'https://s/2'), cached(2, 'https://s/3')]
+  check('same url keeps the same index', pickChapterIndex(list, toc(2, 'https://s/3')) === 2)
+}
+
+// 站点在开头插了新章：同一章在现抓目录里是 2，在缓存目录里是 1——必须用缓存里的 1，
+// 照搬现抓的 2 会跳到下一章。
+{
+  const list = [cached(0, 'https://s/1'), cached(1, 'https://s/2'), cached(2, 'https://s/3')]
+  check('inserted chapter maps back to the cached index', pickChapterIndex(list, toc(2, 'https://s/2')) === 1)
+}
+
+// 缓存目录里没有这一章（站点改版、或两边取的不是同一份目录）：退回现抓的序号
+{
+  const list = [cached(0, 'https://s/1')]
+  check('unknown url falls back to the fetched index', pickChapterIndex(list, toc(7, 'https://s/7')) === 7)
+}
+
+// 缓存为空（第一次打开这本书）：退回现抓序号，阅读器随后会把这份目录存下来
+{
+  check('empty cache falls back to the fetched index', pickChapterIndex([], toc(5, 'https://s/5')) === 5)
+}
+
+// 章节没有 url（拿不到地址）：退回现抓序号，不做 url 匹配
+{
+  const list = [cached(0, ''), cached(1, '')]
+  check('chapter without url falls back to the fetched index', pickChapterIndex(list, toc(1, '')) === 1)
+}
+
+console.log('bookDetailModel.test.ts ok')
@@ -0,0 +1,20 @@
+// 书籍详情页点目录跳读的纯逻辑（不依赖 React，便于单测）。
+
+import type { ReaderChapter, ReaderTocChapter } from '../../api/reader'
+
+/**
+ * 把详情页点中的章节换算成阅读器要的序号。
+ *
+ * 阅读器打开一本书时优先用库里缓存的目录（`/books/:id/chapters`），而详情页显示的
+ * 目录是现抓的：站点更新过目录（插入或调整过章节）时两者会错位，直接照搬现抓目录
+ * 里的序号会跳到别的章。url 是章节的稳定标识，所以先按 url 在缓存目录里定位；
+ * 找不到（缓存为空，或两边取的根本不是同一份目录）才退回现抓的序号——缓存为空时
+ * 阅读器本来就会把这次现抓的目录存下来，序号自然对得上。
+ */
+export function pickChapterIndex(cached: ReaderChapter[], chapter: ReaderTocChapter): number {
+  if (chapter.url) {
+    const hit = cached.findIndex((c) => c.url === chapter.url)
+    if (hit >= 0) return hit
+  }
+  return chapter.index
+}
@@ -64,6 +64,14 @@ class ReaderAudioEngine {
  private detaching = false
  /** 加载批次号：动态 import hls.js 期间被新的加载打断时用来丢弃旧结果。 */
  private loadToken = 0
+  /** 预取缓存：章序号 → 已解析的音轨。命中的切章可以同步开播，不用等网络。 */
+  private prefetched = new Map<number, { track: string; transcoding: boolean }>()
+  /** 预取在途的章序号，避免同一章重复请求。 */
+  private prefetching = new Set<number>()
+  /** 预热下一章字节的隐藏播放器（只下载，从不 play()）。 */
+  private warmer: HTMLAudioElement | null = null
+  /** warmer 当前装载的音轨，避免重复赋值。 */
+  private warmedTrack = ''

  constructor() {
    const audio = new Audio()
@@ -93,7 +101,13 @@ class ReaderAudioEngine {
    }
    // 换章前把上一章的最后位置补报掉（此时 store 里还是上一章的上下文）
    this.commitProgress()
+    // 换书：预取的音轨属于上一本，全部作废
+    if (s.bookId !== input.bookId) this.clearPrefetch()
+    this.applyChapter(input)
+  }

+  /** 真正把一章装上播放器（同步部分）：预取命中的续播也走这里。 */
+  private applyChapter(input: LoadChapterInput): void {
    const chapterTitle = input.chapters[input.chapterIndex]?.title ?? ''
    useReaderAudioStore.setState({
      bookId: input.bookId,
@@ -128,6 +142,9 @@ class ReaderAudioEngine {
    }

    void this.attachSource(input.track)
+    // 提前解析下一章的音轨并在后台预热字节：息屏自动续播时才能立刻接上
+    const nextIndex = this.neighborChapterIndex(1)
+    if (nextIndex !== null) this.prefetchChapter(nextIndex)
  }

  play(): void {
@@ -222,6 +239,7 @@ class ReaderAudioEngine {
  stop(): void {
    this.commitProgress()
    this.detachSource()
+    this.clearPrefetch()
    this.timerDeadline = 0
    this.pausedAt = 0
    // 下一次开播重新套用「上次的定时设置」，否则关掉再听一本书时定时不会自动开
@@ -242,12 +260,22 @@ class ReaderAudioEngine {

  private async attachSource(src: string): Promise<void> {
    const token = ++this.loadToken
-    this.detachSource()
-    this.setSessionMetadata(src)
+    // 只销毁上一章的 hls，不再 removeAttribute('src') + load()。load() 会把媒体
+    // 元素彻底卸载、释放系统音频会话，息屏时紧接着的 play() 就会被浏览器当成
+    // 「无用户手势」拦下——表现正是切章卡住、解锁后必须手动点播放。直接覆盖 src，
+    // 元素始终持有媒体，会话才接得上。
+    this.hls?.destroy()
+    this.hls = null
    if (!src) {
+      this.audio.removeAttribute('src')
+      this.audio.load()
+      this.setSessionMetadata(null)
      this.fail('本章没有可播放的音频')
      return
    }
+    // 先停住上一章：HLS 分支要 await 动态 import，不先停会有一小段两章叠播
+    if (!this.audio.paused) this.audio.pause()
+    this.setSessionMetadata(src)
    if (src.includes('.m3u8')) {
      const mod = await import('hls.js')
      // 动态 import 期间可能已经切到别的章：丢弃这次结果
@@ -270,6 +298,7 @@ class ReaderAudioEngine {
    this.audio.src = src
  }

+  /** 彻底卸载音源（停止播放时用）。换章不走这里，见 attachSource 的说明。 */
  private detachSource(): void {
    this.detaching = true
    this.hls?.destroy()
@@ -279,9 +308,117 @@ class ReaderAudioEngine {
    this.detaching = false
  }

+  // ─── 预取与续播 ───────────────────────────────────────────────────────
+
+  /**
+   * 提前解析某章的音轨并预热字节。息屏时 ended 与 play() 之间不能有网络空档，
+   * 否则系统收走音频会话、标签页被冻结，浏览器就拒绝自动播放了。
+   */
+  private prefetchChapter(index: number): void {
+    const { bookId, chapters } = useReaderAudioStore.getState()
+    if (!bookId || index < 0 || index >= chapters.length || chapters[index].is_volume) return
+    if (this.prefetched.has(index) || this.prefetching.has(index)) return
+    // 反复跳章时旧的预取会变成垃圾，做个上限兜底
+    if (this.prefetched.size > 32) this.prefetched.clear()
+    this.prefetching.add(index)
+    const forBook = bookId
+    readerAPI
+      .bookContent(bookId, index)
+      .then((ct) => {
+        // 期间换了书：结果作废
+        if (useReaderAudioStore.getState().bookId !== forBook) return
+        const track = ct.tracks?.[0]
+        if (ct.type !== 'audio' || !track) return
+        this.prefetched.set(index, { track, transcoding: ct.transcoding ?? false })
+        // 要服务端转码的音轨立刻预热（把转码提前跑掉）；直链等到本章快播完再拉字节，
+        // 避免用户中途停下时白下整章的流量。
+        if (ct.transcoding) this.warmNextBytes(track)
+      })
+      .catch(() => undefined)
+      .finally(() => this.prefetching.delete(index))
+  }
+
+  /** 用隐藏播放器把下一章的字节（以及服务端转码）提前拉起来，减少切章等待。 */
+  private warmNextBytes(track: string): void {
+    // HLS 交给 hls.js 按需拉流，二次下载没有意义
+    if (!track || track.includes('.m3u8') || this.warmedTrack === track) return
+    this.warmedTrack = track
+    if (!this.warmer) {
+      const a = new Audio()
+      a.preload = 'auto'
+      this.warmer = a
+    }
+    this.warmer.src = track
+  }
+
+  /** 本章快播完时把下一章的字节预热起来（30 秒足够开头缓冲）。 */
+  private maybeWarmNext(): void {
+    const audio = this.audio
+    if (!Number.isFinite(audio.duration) || audio.duration <= 0) return
+    if (audio.duration - audio.currentTime > 30) return
+    const nextIndex = this.neighborChapterIndex(1)
+    if (nextIndex === null) return
+    const hit = this.prefetched.get(nextIndex)
+    if (hit) this.warmNextBytes(hit.track)
+  }
+
+  /** 用预取结果接续下一章；命中返回 true（未命中由调用方走异步加载兜底）。 */
+  private playPrefetched(index: number): boolean {
+    const hit = this.prefetched.get(index)
+    if (!hit) return false
+    this.prefetched.delete(index)
+    const s = useReaderAudioStore.getState()
+    this.applyChapter({
+      bookId: s.bookId,
+      bookName: s.bookName,
+      cover: s.cover,
+      chapters: s.chapters,
+      chapterIndex: index,
+      track: hit.track,
+      transcoding: hit.transcoding,
+      openCredits: s.openCredits,
+      closeCredits: s.closeCredits,
+      initialPos: 0,
+    })
+    // 立刻在 ended 的同一次事件里发起 play()，保证没有空档。片头跳转由
+    // loadedmetadata 处理器完成：音频在 loadedmetadata 之前不会出声，所以
+    // 先 play() 也不会漏出片头。HLS 交给 hls.js 承载，无法同帧开播。
+    if (!hit.track.includes('.m3u8')) this.play()
+    return true
+  }
+
+  private clearPrefetch(): void {
+    this.prefetched.clear()
+    this.prefetching.clear()
+    this.warmedTrack = ''
+    if (this.warmer) {
+      this.warmer.removeAttribute('src')
+      this.warmer.load()
+    }
+  }
+
  private async goToChapter(index: number, initialPos: number): Promise<void> {
    const { bookId, chapters } = useReaderAudioStore.getState()
    if (!bookId || index < 0 || index >= chapters.length || chapters[index].is_volume) return
+    // 命中预取：直接装，不等网络（片尾自动续播大多走这里）
+    const hit = this.prefetched.get(index)
+    if (hit) {
+      useReaderAudioStore.setState({ status: 'loading', error: '' })
+      const s = useReaderAudioStore.getState()
+      this.loadChapter({
+        bookId,
+        bookName: s.bookName,
+        cover: s.cover,
+        chapters,
+        chapterIndex: index,
+        track: hit.track,
+        transcoding: hit.transcoding,
+        openCredits: s.openCredits,
+        closeCredits: s.closeCredits,
+        initialPos,
+      })
+      return
+    }
    useReaderAudioStore.setState({ status: 'loading', error: '' })
    try {
      const ct = await readerAPI.bookContent(bookId, index)
@@ -344,6 +481,10 @@ class ReaderAudioEngine {
      this.lastTime = Number.isFinite(audio.duration) ? audio.duration : this.lastTime
      this.commitProgress()
      if (useReaderAudioStore.getState().hasNext) {
+        // 预取命中：在 ended 的同一次事件里同步接上下一章。息屏时这段「零空档」
+        // 很关键——空太久系统会收走音频会话、冻结标签页，浏览器随后拒绝自动播放。
+        const nextIndex = this.neighborChapterIndex(1)
+        if (nextIndex !== null && this.playPrefetched(nextIndex)) return
        this.next()
        return
      }
@@ -389,6 +530,7 @@ class ReaderAudioEngine {
      this.checkCreditsEnd()
      // 后台播放时 timeupdate 仍会触发，这是「到点暂停」最可靠的位置
      this.checkTimer()
+      this.maybeWarmNext()
    })

    audio.addEventListener('error', () => {
@@ -1,6 +1,12 @@
 /** @type {import('tailwindcss').Config} */
 export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
+  future: {
+    // hover 样式只对真正能悬停的设备（鼠标/触控板）生效。触屏点击会让浏览器
+    // 保留 :hover 状态，导致海报墙上的卡片被放大、上移、盖上「立即观影」遮罩，
+    // 看起来像是整行错位、海报显示不全。
+    hoverOnlyWhenSupported: true,
+  },
  theme: {
    extend: {
      fontFamily: {
Author	SHA1	Message	Date
truewhile	8bfdd75d47	优化	2026-10-04 22:17:19 +08:00
truewhile	1a3248f4bb	优化	2026-10-04 21:31:09 +08:00
truewhile	0be7f8b97e	优化	2026-10-04 17:50:26 +08:00
truewhile	6984158f24	修复段评往下滑一直闪：评论接口分页改游标，页面还在按 page 翻页上游评论页按 page=N 翻页，但列表接口 /para_review 早已改成游标分页（响应给 next_cursor，请求要带 cursor=）。接口不认识 page，于是每次「加载更多」都原样返回第一页：一条新评论都加不进去，has_more 又始终是 true，评论页便一遍遍触发加载更多、反复闪骨架屏——用户看到的就是段评往下滑一闪一闪，评论一条没多。评论页是上游 HTML 改不了，于是在承载页面的接口代理里做最小适配： - 请求带 page=N（N>1）且有上一页给的游标时，换成 cursor= 请求； - 某页返回的 comment_id 全是已经见过的，就把 has_more 改成 false 收尾，避免页面在「加载更多 → 没有新内容」之间空转。只认路径以 /para_review 结尾、带 page 且不带 cursor 的请求，其余原样透传。	2026-10-04 16:28:13 +08:00
truewhile	d545ff1a7b	修复段评打开后没有评论：承载页面丢失原地址参数段评气泡上的数字来自正文里的 <comment count>，但点开后的评论页跑在「/api/reader/browser/page?id=..&s=..」这个承载地址上，页面看到的 location.search 只剩我们自己的 id/s，原地址的 item_id/para/source 全丢了。评论页正是靠这几个参数去请求 /para_review，于是按缺参数请求，列表永远为空：外面气泡显示 99，点开一条段评都没有。承载地址改为把原地址的 query 原样拼在签名参数之后（页面看到的 search 与原站一致）；id/s 放最前，同名的原参数顶不掉我们的签名参数。	2026-10-04 13:53:44 +08:00
truewhile	227e0a9197	优化	2026-10-04 13:29:39 +08:00
truewhile	e85df5fb6b	优化	2026-10-04 12:35:33 +08:00