优化，bug处理

Dockerfile

@@ -84,12 +84,15 @@ ENV MEBOX_APP_PORT=8080 \
 
 EXPOSE 8080
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
-    CMD busybox wget -q --spider http://127.0.0.1:8080/api/health || exit 1
+# 探测协议不能写死：开启 HTTPS 后 8080 只接受 TLS。脚本按数据目录里的
+# .http_scheme 选择协议并在失败时回退，无需用户改配置。
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD ["/usr/local/bin/mebox-healthcheck"]
 
 # Tiny entrypoint that lets us run as a NAS host UID/GID via PUID/PGID without
 # rewriting /etc/passwd or /etc/group on every container start.
 COPY docker-entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh
+COPY docker-healthcheck.sh /usr/local/bin/mebox-healthcheck
+RUN chmod +x /entrypoint.sh /usr/local/bin/mebox-healthcheck
 
 CMD ["/entrypoint.sh"]

cmd/server/application.go

@@ -88,7 +88,7 @@ func (a *application) start() error {
 		a.logger.Error("database not ready", zap.Error(err))
 		return fmt.Errorf("database not ready: %w", err)
 	}
-	if err := database.AutoMigrate(db); err != nil {
+	if err := database.AutoMigrateWithConfig(db, a.cfg, a.logger); err != nil {
 		a.logger.Error("auto-migrate failed", zap.Error(err))
 		return fmt.Errorf("auto-migrate failed: %w", err)
 	}

cmd/server/protocol_mux.go

@@ -0,0 +1,129 @@
+package main
+
+import (
+	"bufio"
+	"net"
+	"sync"
+	"time"
+)
+
+// 开启 HTTPS 后，同一个端口会同时面对两类连接：
+//
+//   - TLS 客户端（浏览器、播放器）——正常提供 HTTPS 服务；
+//   - 明确访问 http:// 的客户端——以前只会撞出一句
+//     "Client sent an HTTP request to an HTTPS server."，用户看不懂。
+//
+// 一个端口上只有 TLS 监听时无法区分两者，所以在 Accept 之后先偷看第一个字节：
+// TLS 握手的记录类型固定是 0x16（handshake），而 HTTP 请求行必然是可见字符。
+// 据此把连接分流成两路，明文那一路交给只做跳转的 http.Server，于是 http:// 会被
+// 自动重定向到 https://（见 server_manager.go 的 httpsRedirectHandler）。
+const tlsRecordHandshake = 0x16
+
+// defaultPeekTimeout 限制"偷看首字节"阶段的等待，避免只连不发的半开连接长期占住
+// goroutine。分流器按实例持有该值，便于测试用更短的超时。
+const defaultPeekTimeout = 10 * time.Second
+
+// splitListener 是监听分流器：Accept 到底层连接后按首字节投递给对应的一路。
+type splitListener struct {
+	ln      net.Listener
+	tlsCh   chan net.Conn
+	plainCh chan net.Conn
+	quit    chan struct{}
+	once    sync.Once
+	peek    time.Duration
+}
+
+func newSplitListener(ln net.Listener) *splitListener {
+	return newSplitListenerWithTimeout(ln, defaultPeekTimeout)
+}
+
+func newSplitListenerWithTimeout(ln net.Listener, peek time.Duration) *splitListener {
+	s := &splitListener{
+		ln:      ln,
+		tlsCh:   make(chan net.Conn),
+		plainCh: make(chan net.Conn),
+		quit:    make(chan struct{}),
+		peek:    peek,
+	}
+	go s.acceptLoop()
+	return s
+}
+
+// tlsListener 返回只收到 TLS 连接的 listener。
+func (s *splitListener) tlsListener() net.Listener {
+	return &channelListener{addr: s.ln.Addr(), conns: s.tlsCh, quit: s.quit}
+}
+
+// plainListener 返回只收到明文 HTTP 连接的 listener。
+func (s *splitListener) plainListener() net.Listener {
+	return &channelListener{addr: s.ln.Addr(), conns: s.plainCh, quit: s.quit}
+}
+
+func (s *splitListener) acceptLoop() {
+	for {
+		conn, err := s.ln.Accept()
+		if err != nil {
+			// 底层监听关闭（换证、关停）后两路 Accept 一起返回 net.ErrClosed，
+			// 由持有它们的 http.Server 自行收尾。
+			s.stop()
+			return
+		}
+		go s.dispatch(conn)
+	}
+}
+
+func (s *splitListener) dispatch(conn net.Conn) {
+	br := bufio.NewReader(conn)
+	_ = conn.SetReadDeadline(time.Now().Add(s.peek))
+	first, err := br.Peek(1)
+	_ = conn.SetReadDeadline(time.Time{})
+	if err != nil {
+		_ = conn.Close()
+		return
+	}
+
+	peeked := &peekedConn{Conn: conn, r: br}
+	ch := s.plainCh
+	if first[0] == tlsRecordHandshake {
+		ch = s.tlsCh
+	}
+	select {
+	case ch <- peeked: // 交给对应的 http.Server，由它负责读写与关闭
+	case <-s.quit:
+		_ = conn.Close()
+	}
+}
+
+func (s *splitListener) stop() {
+	s.once.Do(func() { close(s.quit) })
+}
+
+// channelListener 把一路 channel 包装成 net.Listener，供 http.Server.Serve 使用。
+type channelListener struct {
+	addr  net.Addr
+	conns <-chan net.Conn
+	quit  <-chan struct{}
+}
+
+func (l *channelListener) Accept() (net.Conn, error) {
+	select {
+	case conn := <-l.conns:
+		return conn, nil
+	case <-l.quit:
+		return nil, net.ErrClosed
+	}
+}
+
+// Close 是空实现：真正要释放的端口在 splitListener 的底层监听上，它一旦关闭，
+// 这里的 Accept 就会返回 net.ErrClosed，http.Server 随之退出。
+func (l *channelListener) Close() error { return nil }
+
+func (l *channelListener) Addr() net.Addr { return l.addr }
+
+// peekedConn 把已经读进 bufio 缓冲的首字节还给上层读取者。
+type peekedConn struct {
+	net.Conn
+	r *bufio.Reader
+}
+
+func (c *peekedConn) Read(p []byte) (int, error) { return c.r.Read(p) }

cmd/server/protocol_mux_test.go

@@ -0,0 +1,140 @@
+package main
+
+import (
+	"io"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+)
+
+func TestSplitListenerRoutesByFirstByte(t *testing.T) {
+	raw, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	split := newSplitListener(raw)
+	addr := raw.Addr().String()
+
+	// TLS：首字节 0x16。分流器偷看过的字节必须还能被上层读到，否则握手会失败。
+	handshake := []byte{0x16, 0x03, 0x01, 0x00, 0x2c}
+	tlsClient, err := net.Dial("tcp", addr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = tlsClient.Close() }()
+	if _, err := tlsClient.Write(handshake); err != nil {
+		t.Fatal(err)
+	}
+	tlsConn := <-split.tlsCh
+	defer func() { _ = tlsConn.Close() }()
+	got := make([]byte, len(handshake))
+	if _, err := io.ReadFull(tlsConn, got); err != nil {
+		t.Fatalf("read peeked tls bytes: %v", err)
+	}
+	if string(got) != string(handshake) {
+		t.Fatalf("tls bytes = %v, want %v", got, handshake)
+	}
+
+	// 明文 HTTP：请求行走另一路，同样要读到偷看过的首字节。
+	request := "GET /api/health HTTP/1.1\r\nHost: example.com\r\n\r\n"
+	plainClient, err := net.Dial("tcp", addr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = plainClient.Close() }()
+	if _, err := plainClient.Write([]byte(request)); err != nil {
+		t.Fatal(err)
+	}
+	plainConn := <-split.plainCh
+	defer func() { _ = plainConn.Close() }()
+	head := make([]byte, len("GET /"))
+	if _, err := io.ReadFull(plainConn, head); err != nil {
+		t.Fatalf("read peeked plain bytes: %v", err)
+	}
+	if string(head) != request[:len(head)] {
+		t.Fatalf("plain bytes = %q, want prefix of %q", head, request)
+	}
+
+	// 底层监听关闭后两路 Accept 都要返回 net.ErrClosed，http.Server 才能收尾。
+	_ = raw.Close()
+	for _, ln := range []net.Listener{split.tlsListener(), split.plainListener()} {
+		deadline := time.Now().Add(3 * time.Second)
+		for {
+			_, err := ln.Accept()
+			if err == net.ErrClosed {
+				break
+			}
+			if time.Now().After(deadline) {
+				t.Fatalf("Accept after close = %v, want net.ErrClosed", err)
+			}
+			time.Sleep(10 * time.Millisecond)
+		}
+	}
+}
+
+// 只连不发的半开连接不应被分给任何一路，而应在偷看超时后被丢弃。
+func TestSplitListenerDropsIdleConnection(t *testing.T) {
+	raw, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = raw.Close() }()
+	split := newSplitListenerWithTimeout(raw, 200*time.Millisecond)
+
+	conn, err := net.Dial("tcp", raw.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = conn.Close() }()
+
+	select {
+	case c := <-split.plainCh:
+		_ = c.Close()
+		t.Fatal("idle connection should not be dispatched")
+	case c := <-split.tlsCh:
+		_ = c.Close()
+		t.Fatal("idle connection should not be dispatched")
+	case <-time.After(time.Second):
+	}
+}
+
+func TestHTTPSRedirectTarget(t *testing.T) {
+	cases := []struct {
+		name    string
+		host    string
+		rawURL  string
+		want    string
+		wantErr bool
+	}{
+		{name: "keeps host port path and query", host: "10.0.0.2:8080", rawURL: "/library?tab=1&q=a%20b", want: "https://10.0.0.2:8080/library?tab=1&q=a%20b"},
+		{name: "root path", host: "nas.local:18080", rawURL: "/", want: "https://nas.local:18080/"},
+		{name: "keeps escaping of user input", host: "10.0.0.2", rawURL: "/a%2Fb", want: "https://10.0.0.2/a%2Fb"},
+		{name: "absolute form request line", host: "10.0.0.2:8080", rawURL: "http://10.0.0.2:8080/api/x?y=1", want: "https://10.0.0.2:8080/api/x?y=1"},
+		{name: "rejects empty host", host: "", rawURL: "/", wantErr: true},
+		{name: "rejects host with slash", host: "evil.com/path", rawURL: "/", wantErr: true},
+		{name: "rejects userinfo host", host: "user@evil.com", rawURL: "/", wantErr: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			req, err := http.NewRequest(http.MethodGet, tc.rawURL, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			req.Host = tc.host
+
+			if host := redirectHostHeader(req); host == "" {
+				if !tc.wantErr {
+					t.Fatalf("redirectHostHeader(%q) rejected, want accepted", tc.host)
+				}
+				return
+			}
+			if tc.wantErr {
+				t.Fatalf("redirectHostHeader(%q) accepted, want rejected", tc.host)
+			}
+			if got := httpsRedirectURL(tc.host, req); got != tc.want {
+				t.Fatalf("redirect target = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

cmd/server/server_manager.go

@@ -7,6 +7,8 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strings"
 	"sync"
 	"time"
@@ -17,6 +19,14 @@ import (
 	"github.com/truewhile/MeBox/internal/service"
 )
 
+// httpSchemeFileName 是数据目录下记录当前监听协议的小文件（内容为 http 或 https）。
+//
+// 容器健康检查无法读取后台保存的 HTTPS 设置（它存在数据库里），而同一端口在开启
+// HTTPS 后只接受 TLS。若健康检查固定用 http:// 探测，每轮都会撞出
+// "client sent an HTTP request to an HTTPS server"，既刷日志又让容器永远 unhealthy。
+// 因此由服务进程在每次成功绑定监听后写下真实协议，供 docker-healthcheck.sh 选择。
+const httpSchemeFileName = ".http_scheme"
+
 // tlsPair 记录当前正在服务的证书，用于判断是否需要重新绑定监听。
 type tlsPair struct {
 	cert    tls.Certificate
@@ -35,6 +45,9 @@ type tlsPair struct {
 //   - 旧服务器随后优雅退出，正在进行的播放/请求不会被立刻掐断。
 //
 // 任何校验失败都会中止切换并保留旧监听，保证用户不会被锁在服务外面。
+//
+// 开启 HTTPS 时端口上会同时接两类连接：TLS 走主服务器，明文 HTTP 走
+// redirectSrv 并跳转到 HTTPS（见 protocol_mux.go）。
 type serverManager struct {
 	cfg     *config.Config
 	log     *zap.Logger
@@ -43,6 +56,7 @@ type serverManager struct {
 
 	mu                sync.Mutex
 	srv               *http.Server
+	redirectSrv       *http.Server
 	ln                net.Listener
 	pair              *tlsPair
 	stopCh            chan struct{}
@@ -92,11 +106,11 @@ func (m *serverManager) Reload() error {
 		return nil
 	}
 
-	oldSrv, oldLn, oldPair := m.srv, m.ln, m.pair
+	oldSrv, oldRedirect, oldLn, oldPair := m.srv, m.redirectSrv, m.ln, m.pair
 	if oldLn != nil {
 		_ = oldLn.Close() // 释放端口后再绑定新监听
 	}
-	m.srv, m.ln, m.pair = nil, nil, nil
+	m.srv, m.redirectSrv, m.ln, m.pair = nil, nil, nil, nil
 
 	firstErr := m.bind(pair)
 	if firstErr != nil {
@@ -107,6 +121,7 @@ func (m *serverManager) Reload() error {
 	}
 	// 新监听已就绪，让旧服务器在新连接切换到新监听后优雅退出。
 	m.drain(oldSrv)
+	m.drain(oldRedirect)
 	m.logServerReady()
 	m.maybeStartAutoReloadLocked()
 	return firstErr
@@ -120,11 +135,19 @@ func (m *serverManager) Shutdown(ctx context.Context) error {
 		close(m.stopCh)
 	}
 	m.mu.Lock()
-	defer m.mu.Unlock()
-	if m.srv == nil {
-		return nil
+	targets := []*http.Server{m.srv, m.redirectSrv}
+	m.mu.Unlock()
+
+	var firstErr error
+	for _, srv := range targets {
+		if srv == nil {
+			continue
+		}
+		if err := srv.Shutdown(ctx); err != nil && firstErr == nil {
+			firstErr = err
+		}
 	}
-	return m.srv.Shutdown(ctx)
+	return firstErr
 }
 
 // desiredPair 根据当前配置计算目标监听形态：nil 表示明文 HTTP，非 nil 表示 TLS。
@@ -217,25 +240,107 @@ func (m *serverManager) pairEquals(pair *tlsPair) bool {
 	return pair.version == m.pair.version
 }
 
-// bind 创建并按需启用 TLS 的监听，异步开始服务。
+// bind 创建监听，异步开始服务。
+//
+// 未开启 HTTPS 时端口只服务明文 HTTP；开启后同一个端口两种流量都要接：TLS 连接
+// 交给主服务器，明文 HTTP 连接交给只做跳转的 redirect 服务器，让 http:// 自动
+// 跳到 https://，而不是甩给用户一句 "Client sent an HTTP request to an HTTPS
+// server."。
 func (m *serverManager) bind(pair *tlsPair) error {
 	ln, err := net.Listen("tcp", m.addr)
 	if err != nil {
 		return fmt.Errorf("listen %s: %w", m.addr, err)
 	}
-	srv := &http.Server{
-		Handler:           m.handler,
+
+	if pair == nil {
+		srv := m.newHTTPServer(m.handler)
+		m.srv, m.redirectSrv, m.ln, m.pair = srv, nil, ln, nil
+		m.writeSchemeState(nil)
+		go m.serve(srv, ln)
+		return nil
+	}
+
+	split := newSplitListener(ln)
+	srv := m.newHTTPServer(m.handler)
+	tlsLn := tls.NewListener(split.tlsListener(), &tls.Config{
+		Certificates: []tls.Certificate{pair.cert},
+		MinVersion:   tls.VersionTLS12,
+	})
+	redirect := m.newHTTPServer(m.httpsRedirectHandler())
+
+	m.srv, m.redirectSrv, m.ln, m.pair = srv, redirect, ln, pair
+	m.writeSchemeState(pair)
+	go m.serve(srv, tlsLn)
+	go m.serve(redirect, split.plainListener())
+	return nil
+}
+
+func (m *serverManager) newHTTPServer(handler http.Handler) *http.Server {
+	return &http.Server{
+		Handler:           handler,
 		ReadHeaderTimeout: 15 * time.Second,
 	}
-	if pair != nil {
-		ln = tls.NewListener(ln, &tls.Config{
-			Certificates: []tls.Certificate{pair.cert},
-			MinVersion:   tls.VersionTLS12,
-		})
+}
+
+// httpsRedirectHandler 处理"开着 HTTPS 却用 http:// 访问"的请求：跳转到同端口、
+// 同路径的 https://。
+//
+// 用 302/307 而不是 301/308：HTTPS 开关可以在后台随时改，永久跳转会被浏览器长期
+// 缓存，等用户关掉 HTTPS 之后 http 访问会被带到已经不提供 TLS 的端口上打不开。
+func (m *serverManager) httpsRedirectHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		host := redirectHostHeader(r)
+		if host == "" {
+			// 没有可用的 Host（HTTP/1.0 或畸形请求头）时宁可明说，也不跳到错的地方。
+			w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+			w.WriteHeader(http.StatusBadRequest)
+			fmt.Fprintf(w, "HTTPS is enabled; open https://<host>:%d instead.\n", m.cfg.App.Port)
+			return
+		}
+		status := http.StatusFound
+		if r.Method != http.MethodGet && r.Method != http.MethodHead {
+			status = http.StatusTemporaryRedirect // 保住方法与请求体
+		}
+		w.Header().Set("Location", httpsRedirectURL(host, r))
+		w.WriteHeader(status)
+	})
+}
+
+// httpsRedirectURL 拼出同端口同路径的 HTTPS 地址。
+func httpsRedirectURL(host string, r *http.Request) string {
+	target := "https://" + host + r.URL.EscapedPath()
+	if r.URL.RawQuery != "" {
+		target += "?" + r.URL.RawQuery
+	}
+	return target
+}
+
+// redirectHostHeader 取重定向目标主机。HTTP/1.1 里 Host 是唯一的主机来源（端口映射
+// 到容器 8080 时它同时也是 HTTPS 端口），这里只做字符过滤，避免把请求头里的怪字符
+// 带进 Location 造成任意跳转。
+func redirectHostHeader(r *http.Request) string {
+	host := strings.TrimSpace(r.Host)
+	if host == "" || strings.ContainsAny(host, " \t\r\n/\\@?#") {
+		return ""
+	}
+	return host
+}
+
+// writeSchemeState 把当前实际监听的协议写入数据目录，供容器健康检查按协议探测。
+// 写失败只降级为告警：健康检查脚本在状态文件缺失时会回退试另一种协议。
+func (m *serverManager) writeSchemeState(pair *tlsPair) {
+	dataDir := strings.TrimSpace(m.cfg.App.DataDir)
+	if dataDir == "" {
+		return
+	}
+	scheme := "http"
+	if pair != nil {
+		scheme = "https"
+	}
+	path := filepath.Join(dataDir, httpSchemeFileName)
+	if err := os.WriteFile(path, []byte(scheme+"\n"), 0o644); err != nil { // #nosec G304 -- path is DataDir + fixed filename.
+		m.log.Warn("write http scheme state failed", zap.String("path", path), zap.Error(err))
 	}
-	m.srv, m.ln, m.pair = srv, ln, pair
-	go m.serve(srv, ln)
-	return nil
 }
 
 func (m *serverManager) serve(s *http.Server, ln net.Listener) {
@@ -271,7 +376,7 @@ func (m *serverManager) logServerReady() {
 		zap.String("listen", m.addr),
 	)
 	if m.pair != nil {
-		m.log.Info("HTTPS is enabled; plain HTTP is no longer served on this port",
+		m.log.Info("HTTPS is enabled; plain HTTP requests on this port are redirected to HTTPS",
 			zap.String("addr", m.addr),
 		)
 	}

cmd/server/server_manager_test.go

@@ -1,13 +1,17 @@
 package main
 
 import (
+	"context"
 	"crypto/ecdsa"
 	"crypto/elliptic"
 	"crypto/rand"
+	"crypto/tls"
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/pem"
+	"io"
 	"math/big"
+	"net"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -32,6 +36,8 @@ func makeTestPairPEM(t *testing.T) (certPEM, keyPEM string) {
 		NotBefore:    time.Now().Add(-time.Hour),
 		NotAfter:     time.Now().Add(24 * time.Hour),
 		DNSNames:     []string{"localhost"},
+		// 带上回环 IP，HTTPS 客户端就能在校验证书的前提下连 127.0.0.1:port。
+		IPAddresses: []net.IP{net.ParseIP("127.0.0.1")},
 	}
 	der, err := x509.CreateCertificate(rand.Reader, tpl, tpl, &priv.PublicKey, priv)
 	if err != nil {
@@ -105,3 +111,136 @@ func TestDesiredPairModes(t *testing.T) {
 		t.Fatal("version should change after files replaced")
 	}
 }
+
+// 健康检查依赖该文件判断该用 http 还是 https 探测，内容与当前监听协议必须一致，
+// 否则容器会一直显示 unhealthy 并刷 TLS handshake error 日志。
+func TestWriteSchemeState(t *testing.T) {
+	m := newTestServerManager(t)
+	m.cfg.App.DataDir = t.TempDir()
+	path := filepath.Join(m.cfg.App.DataDir, httpSchemeFileName)
+
+	m.writeSchemeState(nil)
+	if data, err := os.ReadFile(path); err != nil || strings.TrimSpace(string(data)) != "http" {
+		t.Fatalf("plain HTTP state: data=%q err=%v", data, err)
+	}
+
+	m.writeSchemeState(&tlsPair{})
+	if data, err := os.ReadFile(path); err != nil || strings.TrimSpace(string(data)) != "https" {
+		t.Fatalf("HTTPS state: data=%q err=%v", data, err)
+	}
+
+	// DataDir 为空时不应写到工作目录（测试/裸跑二进制时会污染仓库）。
+	m.cfg.App.DataDir = ""
+	_ = os.Remove(path)
+	m.writeSchemeState(nil)
+	if _, err := os.Stat(httpSchemeFileName); !os.IsNotExist(err) {
+		t.Fatalf("empty DataDir should not create %s in cwd: %v", httpSchemeFileName, err)
+	}
+}
+
+// 开启 HTTPS 后同一个端口要同时接 TLS 与明文 HTTP：明文请求跳到 HTTPS，而不是
+// 给用户看 "Client sent an HTTP request to an HTTPS server."。
+func TestServerManagerRedirectsPlainHTTPToHTTPS(t *testing.T) {
+	certPEM, keyPEM := makeTestPairPEM(t)
+	cfg := &config.Config{}
+	cfg.App.Port = 8080
+	cfg.App.DataDir = t.TempDir()
+	cfg.App.HTTPSEnabled = true
+	cfg.App.SSLCert, cfg.App.SSLKey = certPEM, keyPEM
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "secure:"+r.URL.Path)
+	})
+	m := newServerManager(cfg, zap.NewNop(), handler)
+	m.addr = "127.0.0.1:0" // 端口 0 交给内核分配，测试之间不会撞端口
+	if err := m.Start(); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = m.Shutdown(context.Background()) })
+
+	addr := m.ln.Addr().String()
+	// 端口 0 只在第一次分配时用；热切换要绑回同一个端口（生产里端口本来就是固定的）。
+	m.addr = addr
+	schemeFile := filepath.Join(cfg.App.DataDir, httpSchemeFileName)
+	if data, err := os.ReadFile(schemeFile); err != nil || strings.TrimSpace(string(data)) != "https" {
+		t.Fatalf("scheme state = %q err=%v, want https", data, err)
+	}
+
+	plain := &http.Client{
+		Timeout:       10 * time.Second,
+		CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
+	}
+
+	resp, err := plain.Get("http://" + addr + "/library?tab=1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusFound {
+		t.Fatalf("plain GET status = %d, want %d", resp.StatusCode, http.StatusFound)
+	}
+	if got, want := resp.Header.Get("Location"), "https://"+addr+"/library?tab=1"; got != want {
+		t.Fatalf("Location = %q, want %q", got, want)
+	}
+
+	postResp, err := plain.Post("http://"+addr+"/api/me/login", "application/json", strings.NewReader("{}"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = postResp.Body.Close() }()
+	if postResp.StatusCode != http.StatusTemporaryRedirect {
+		t.Fatalf("plain POST status = %d, want %d", postResp.StatusCode, http.StatusTemporaryRedirect)
+	}
+	if got, want := postResp.Header.Get("Location"), "https://"+addr+"/api/me/login"; got != want {
+		t.Fatalf("POST Location = %q, want %q", got, want)
+	}
+
+	// 同一端口上的 TLS 连接照常拿到正常响应（校验证书，不做跳过校验）。
+	pool := x509.NewCertPool()
+	if !pool.AppendCertsFromPEM([]byte(certPEM)) {
+		t.Fatal("append test certificate to pool failed")
+	}
+	secure := &http.Client{
+		Timeout: 10 * time.Second,
+		Transport: &http.Transport{
+			TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12},
+		},
+	}
+	secureResp, err := secure.Get("https://" + addr + "/library")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = secureResp.Body.Close() }()
+	body, err := io.ReadAll(secureResp.Body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if secureResp.StatusCode != http.StatusOK || string(body) != "secure:/library" {
+		t.Fatalf("https response = %d %q, want 200 %q", secureResp.StatusCode, body, "secure:/library")
+	}
+
+	// 关掉 HTTPS 后同一端口回到纯明文服务，不再有多余的跳转服务器。
+	cfg.App.HTTPSEnabled = false
+	if err := m.Reload(); err != nil {
+		t.Fatal(err)
+	}
+	if m.redirectSrv != nil {
+		t.Fatal("redirect server should be released when HTTPS is off")
+	}
+	if data, err := os.ReadFile(schemeFile); err != nil || strings.TrimSpace(string(data)) != "http" {
+		t.Fatalf("scheme state = %q err=%v, want http", data, err)
+	}
+	plainResp, err := plain.Get("http://" + addr + "/library")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = plainResp.Body.Close() }()
+	plainBody, err := io.ReadAll(plainResp.Body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if plainResp.StatusCode != http.StatusOK || string(plainBody) != "secure:/library" {
+		t.Fatalf("plain response after disabling https = %d %q", plainResp.StatusCode, plainBody)
+	}
+}

docker-compose.metatube.yml

@@ -62,7 +62,7 @@ services:
       # NAS 示例：source: /vol1/1000/Media
       # Windows Docker Desktop 示例：source: D:/Media
       # create_host_path=false 可以避免路径写错时 Docker 自动创建空文件夹。
-      - ./media: /media
+      - ./media:/media
 
     environment:
       TZ: Asia/Shanghai
@@ -105,7 +105,9 @@ services:
       MEBOX_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
 
     healthcheck:
-      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      # 不能写死 http://：开启 HTTPS 后 8080 只接受 TLS，固定明文探测会
+      # 每轮刷一条 TLS handshake error 并让容器一直 unhealthy。
+      test: ["CMD", "/usr/local/bin/mebox-healthcheck"]
       interval: 30s
       timeout: 10s
       retries: 5

docker-compose.search.yml

@@ -115,7 +115,9 @@ services:
       MEBOX_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
 
     healthcheck:
-      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      # 不能写死 http://：开启 HTTPS 后 8080 只接受 TLS，固定明文探测会
+      # 每轮刷一条 TLS handshake error 并让容器一直 unhealthy。
+      test: ["CMD", "/usr/local/bin/mebox-healthcheck"]
       interval: 30s
       timeout: 10s
       retries: 5

docker-compose.simple.yml

@@ -73,7 +73,9 @@ services:
       - "host.docker.internal:host-gateway"
 
     healthcheck:
-      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      # 不能写死 http://：开启 HTTPS 后 8080 只接受 TLS，固定明文探测会
+      # 每轮刷一条 TLS handshake error 并让容器一直 unhealthy。
+      test: ["CMD", "/usr/local/bin/mebox-healthcheck"]
       interval: 30s
       timeout: 10s
       retries: 5

docker-compose.standard.yml

@@ -44,7 +44,7 @@ services:
       # NAS 示例：source: /vol1/1000/Media
       # Windows Docker Desktop 示例：source: D:/Media
       # create_host_path=false 可以避免路径写错时 Docker 自动创建空文件夹。
-      - ./media: /media
+      - ./media:/media
 
     environment:
       TZ: Asia/Shanghai
@@ -87,7 +87,9 @@ services:
       MEBOX_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
 
     healthcheck:
-      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      # 不能写死 http://：开启 HTTPS 后 8080 只接受 TLS，固定明文探测会
+      # 每轮刷一条 TLS handshake error 并让容器一直 unhealthy。
+      test: ["CMD", "/usr/local/bin/mebox-healthcheck"]
       interval: 30s
       timeout: 10s
       retries: 5

docker-compose.yml

@@ -131,7 +131,9 @@ services:
       MEBOX_TRANSCODER_IDLE_TIMEOUT_SECONDS: "120"
 
     healthcheck:
-      test: ["CMD-SHELL", "busybox wget -qO- http://127.0.0.1:8080/api/health || exit 1"]
+      # 不能写死 http://：开启 HTTPS 后 8080 只接受 TLS，固定明文探测会
+      # 每轮刷一条 TLS handshake error 并让容器一直 unhealthy。
+      test: ["CMD", "/usr/local/bin/mebox-healthcheck"]
       interval: 30s
       timeout: 10s
       retries: 5

docker-healthcheck.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# MeBox 容器健康检查。
+#
+# 背景：MeBox 只监听一个端口，且开启 HTTPS 后该端口只接受 TLS（明文 HTTP 不再
+# 服务）。健康检查若固定用 http:// 探测，每轮都会被 TLS 监听拒绝并在服务日志里
+# 留下一条 "client sent an HTTP request to an HTTPS server"，同时容器状态永远
+# 是 unhealthy。反过来固定用 https:// 探测，则在未开启 HTTPS 的部署上产生
+# "first record does not look like a TLS handshake"。
+#
+# 当前协议由服务进程写入 $MEBOX_APP_DATA_DIR/.http_scheme（见
+# cmd/server/server_manager.go 的 writeSchemeState）。脚本优先按该文件选择协议，
+# 文件缺失或该协议探测失败时再试另一种，避免状态文件过期导致误报不健康。
+set -u
+
+port="${MEBOX_APP_PORT:-8080}"
+data_dir="${MEBOX_APP_DATA_DIR:-/data}"
+
+scheme_file="$data_dir/.http_scheme"
+scheme=""
+if [ -r "$scheme_file" ]; then
+	scheme="$(tr -d '[:space:]' <"$scheme_file")"
+fi
+if [ "$scheme" = "https" ]; then
+	first="https"
+	second="http"
+else
+	first="http"
+	second="https"
+fi
+
+for proto in "$first" "$second"; do
+	# --no-check-certificate：用户常用自签证书或 IP 访问，校验域名必然会失败。
+	if busybox wget -q --spider -T 3 --no-check-certificate \
+		"$proto://127.0.0.1:$port/api/health" >/dev/null 2>&1; then
+		exit 0
+	fi
+done
+
+exit 1

docs/reader-plan.md

@@ -126,11 +126,22 @@ web/src/
 | P4 漫画/图片源 ✅ | 图片列表绝对化 + 经签名代理（带书源 Referer 防盗链头）+ 漫画阅读器（上下滚动/左右单页双模式、图片懒加载与加载失败占位、点击分区翻页/呼菜单、菜单进度条按图片序号、进度按图片序号记忆、下一章预取）+ imageStyle 透传 | 漫画源可看 |
 | P4.5 书源登录 ✅ | `jsLib` 一次装载（对应 legado SharedJsScope）+ `source.*` 会话方法（getVariable/setVariable/getLoginInfo/putLoginInfo/getLoginHeader/putLoginHeader/get/put）+ `cookie.*`（getCookie/setCookie/replaceCookie/removeCookie/getKey，按 eTLD+1 隔离）+ 请求自动携带 Cookie 与 loginHeader + `loginUrl`/`loginUi`（解析表单 → 按钮 action 拼在 loginUrl 后执行 → result 为表单值）+ `loginCheckJs`（会话失效自动重登/重取）+ 源变量落库 + 登录信息/Cookie 加密存储 + 服务端 toast/startBrowser 回传前端 + 登录面板与变量编辑器 | 登录类书源可登录、可留存登录态 |
 | P4.6 本地书籍 ✅ | `POST /api/reader/local/books` 上传 TXT / EPUB（上限 64MB）→ 落盘 `data/reader/local/<bookID>.<txt\|epub>` + 解析目录入 `reader_chapters` + 落库为 `origin=""`、`is_local=true` 的书架条目；TXT 自动识别 BOM/UTF-8/GBK/Big5/UTF-16 并按 legado 默认 TXT 目录规则切章（RE2 无 lookbehind，改行首锚定 + 句子启发式过滤），章定位信息存字节区间 `start:end`，读章只读该区间；EPUB 走 container.xml → OPF spine，标题优先取 NCX/NAV，正文去标签与实体；移出书架同步删落盘文件；同名重复导入覆盖更新并尽量保留进度 | 本地书可上传、可读、可删 |
+| P4.10 书源按用户独立 ✅ | 书源从全局唯一改为按用户独立：`ReaderBookSource` 增加 `user_id`，唯一键改为 `(user_id, source_url)`；导入/列表/启停/删除/搜索全部按当前用户限定；老库迁移自动删旧唯一索引、按「谁书架上有这本书」回填归属并给多引用用户复制副本、清理软删历史行；删除改为物理删除（软删会占住唯一键导致「删掉再导入」失败）；正文缓存键随之改为「书源行 ID + 书本地址」，不同用户改过规则的同名书源不再共享缓存 | 用户的启停/规则/变量/删除互不影响 |
 | P4.7 正文持久缓存 ✅ | 服务端正文持久缓存（`reader_content_cache.go`：书源侧产物 + 索引落库 + 内容落盘 `cache_dir/reader-content/`、TTL/容量 LRU、目录刷新 remap、换源/移出书架清理、读穿透 singleflight）+ 批量取正文接口 `POST /api/reader/books/:id/content-batch`（对应 CacheBook 协议）+ 前端窗口预取（默认 3 章） | 慢源连续翻章不再每章等待；重复阅读零网络 |
 | P4.8 图片/字体兼容 ✅ | `coverDecodeJs`（封面解密代理，含搜索结果未入库场景）/ `ruleContent.imageDecode`（正文图片解密）+ 图片 URL 尾部 `,{headers}` options 逐图应用（options 优先于书源 header 与 Cookie）+ `java.queryTTF` / `queryBase64TTF` / `replaceFont`（sfnt cmap 0/4/6、loca 短/长、glyf 简单+复合字形） | 加密图与字体混淆正文可读 |
 | P4.9 规则稳定性 ✅ | `@put` 回写书源变量（修复跨请求丢失）；`book.getVariable/putVariable` 真正注入书籍上下文并落库（对应 Book.upVariable）；全部书源 `regexp2` 统一 3s 匹配超时；解压输出 32MB 上限；非 UTF-8 TXT 托管副本按 UTF-8 落盘（外部引用读时解码）；换源单事务；JS `cache` 按书源命名空间隔离并落盘；HLS 双端识别（服务端 `#EXTM3U` 嗅探 + `hls` 标志下发） | 与阅读 App 行为对齐，坏源不再拖死服务 |
 | P5 体验完善 | 换源（ChangeBookSourceDialog 四档排序）、追更（定时刷新目录 + 缓存清理）、发现页（exploreUrl 标签条）、阅读器高级设置（页眉页脚提示、点击区域自定义）、书源编辑器六 Tab、备份导出 | 完整体验 |
 
+### 实施记录：书源会话状态仍是跨用户共享（下一步）
+
+书源本身已按用户独立，但 `ReaderSourceState`（Cookie / 登录信息 / loginHeader / 源变量）
+仍以 `source_url` 为唯一键、跨用户共享一份。两个用户导入同一书源时：
+
+- 一方登录后，另一方复用同一份 Cookie；一方的登出会清掉另一方的登录态。
+
+彻底隔离需要给状态表也加 `user_id`（或按书源行 ID 组织），涉及登录面板与变量读写
+的一批调用点，留作单独一轮处理。
+
 ### 实施记录：关于「宽松 @put 触发 panic」的复核
 
 前期评估曾报告 `sourcerule.go` 的宽松 `@put` 回退正则含 RE2 不支持的反向引用、可能 panic。

docs/reader-ui-spec.md

@@ -36,6 +36,7 @@
 - 「更新目录」（对应 legado `menu_update_toc`）：`POST /reader/shelf/refresh-toc` 并发重抓书架内网络书籍的目录，覆盖章节缓存；末章标题变化时刷新 `latest_chapter_time`，用于「最近更新」排序与更新时间展示。本地书籍与无书源信息的书跳过。返回 `total/updated/unchanged/failed` 四档——抓到但章数没变（完结书）记 `unchanged`「已是最新」，只有抓取或写入真的失败才记 `failed`，避免把正常结果报成「更新失败」；失败会打 Warn 日志（含书名与书源）。
 - 未实现（与 legado 的差距）：书籍二级分组网格（进入分组后的封面网格）、导出/导入书架、离线下载管理界面（服务端批量缓存接口与窗口预取已可用，见下）。
 - 章节预取：阅读页对当前章之后默认 3 章走 `POST /reader/books/:id/content-batch` 批量抓取（服务端并发 + 持久缓存），翻到后续章直接命中；单章串行预取在高延迟书源上赶不上连续翻章。
+- 书源按用户独立：书源管理（列表/导入/启停/删除）与搜索都只作用于当前用户自己的书源。同一份书源不同用户可以各导入一份，各自启停、排序、改规则与变量，互不可见；Web 端无需额外交互，接口按登录用户自动隔离。
 
 **书架分组（`/reader/book-groups`，仿影视模块的媒体库标签）**
 - 按用户存服务端：`reader_book_groups` 表每个用户一条，`groups` 列是 `[{name, book_ids}]` 的 JSON。结构、语义与影视的媒体库标签（`User.LibraryTags`）同构——组名 → 成员 ID、整份替换、一个成员只归一个组、组内顺序即展示顺序。

internal/config/defaults.go

@@ -33,6 +33,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("database.cache_size", -40000)
 	v.SetDefault("database.max_open_conns", defaultDatabaseMaxOpenConns)
 	v.SetDefault("database.max_idle_conns", defaultDatabaseMaxIdleConns)
+	v.SetDefault("database.postgres_trgm_index", true)
 
 	v.SetDefault("secrets.jwt_secret", "")
 
@@ -54,6 +55,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("cache.emby_latest_ttl_seconds", 300)
 	v.SetDefault("cache.reader_content_max_size_mb", 1024)
 	v.SetDefault("cache.reader_content_ttl_hours", 168)
+	v.SetDefault("cache.reader_files_ttl_hours", 720)
 
 	v.SetDefault("search.backend", "")
 	v.SetDefault("search.opensearch_url", "")

internal/config/normalize.go

@@ -68,6 +68,9 @@ func (c *Config) normalize() error {
 	if c.Cache.ReaderContentTTLHours < 0 {
 		c.Cache.ReaderContentTTLHours = 0
 	}
+	if c.Cache.ReaderFilesTTLHours < 0 {
+		c.Cache.ReaderFilesTTLHours = 0
+	}
 	c.Search.Backend = strings.ToLower(strings.TrimSpace(c.Search.Backend))
 	if c.Search.Index == "" {
 		c.Search.Index = "mebox_media"

internal/config/types.go

@@ -50,7 +50,8 @@ type AppConfig struct {
 	DataDir string `mapstructure:"data_dir"`
 	WebDir  string `mapstructure:"web_dir"`
 	// HTTPSEnabled 是否仅通过 HTTPS 提供访问。启用时必须同时配置
-	// SSLCert / SSLKey（或 SSLCertPath / SSLKeyPath），保存后服务会热切换到 HTTPS。
+	// SSLCert / SSLKey（或 SSLCertPath / SSLKeyPath），保存后服务会热切换到 HTTPS；
+	// 同一端口上的明文 HTTP 请求会被跳转到 HTTPS，而不是直接拒绝。
 	HTTPSEnabled bool `mapstructure:"https_enabled"`
 	// SSLCert 是 PEM 编码的 SSL 证书内容。
 	SSLCert string `mapstructure:"ssl_cert"`
@@ -86,6 +87,10 @@ type DatabaseConfig struct {
 	CacheSize    int    `mapstructure:"cache_size"`
 	MaxOpenConns int    `mapstructure:"max_open_conns"`
 	MaxIdleConns int    `mapstructure:"max_idle_conns"`
+	// PostgresTrgmIndex 决定是否用 pg_trgm 的 GIN 三元组索引替代 SQLite 的
+	// FTS5 全文索引。开启后 ILIKE '%term%' 搜索能走索引而不是整表扫描，代价是
+	// media 表写入时要多维护 4 个 GIN 索引。仅对 PostgreSQL 生效。
+	PostgresTrgmIndex bool `mapstructure:"postgres_trgm_index"`
 }
 
 // SecretsConfig 保存 JWT / 第三方 API 密钥（不要提交值）。
@@ -137,6 +142,9 @@ type CacheConfig struct {
 	ReaderContentMaxSizeMB int `mapstructure:"reader_content_max_size_mb"`
 	// ReaderContentTTLHours 阅读正文缓存的保留时长（小时），0 表示不过期。
 	ReaderContentTTLHours int `mapstructure:"reader_content_ttl_hours"`
+	// ReaderFilesTTLHours 书源文件缓存（java.cacheFile / downloadFile）的保留时长（小时）。
+	// 0 表示使用内置兜底值（30 天）。
+	ReaderFilesTTLHours int `mapstructure:"reader_files_ttl_hours"`
 }
 
 type SearchConfig struct {

internal/database/database_admin.go

@@ -165,7 +165,7 @@ func MigrateCurrentToPostgres(src *gorm.DB, targetDSN string, batchSize int, log
 	}
 
 	// 1. 初始化目标库 Schema、类型与索引
-	if err := AutoMigrate(targetDB); err != nil {
+	if err := AutoMigrateWithConfig(targetDB, nil, log); err != nil {
 		return nil, fmt.Errorf("auto migrate target PostgreSQL: %w", err)
 	}
 

internal/database/reader_source_migration_test.go

@@ -0,0 +1,141 @@
+package database
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// legacyReaderSource 旧版书源结构（全局唯一，没有 user_id）。
+type legacyReaderSource struct {
+	ID             string `gorm:"primaryKey"`
+	CreatedAt      time.Time
+	UpdatedAt      time.Time
+	DeletedAt      gorm.DeletedAt `gorm:"index"`
+	Name           string
+	SourceURL      string `gorm:"type:varchar(512);uniqueIndex"`
+	RawJSON        string
+	Enabled        bool
+	EnabledExplore bool
+	Variables      string
+	Header         string
+}
+
+func (legacyReaderSource) TableName() string { return "reader_book_sources" }
+
+// 迁移路径：老库（书源全局唯一、无 user_id）升级后
+//  1. 旧唯一索引被删除，两个用户可以各持一份同 URL 的书源副本；
+//  2. 书源按「谁书架上有这本书」回填归属，多个引用者各得一份副本；
+//  3. 软删的历史书源行被清理，删除后重新导入不再撞唯一键。
+func TestReaderSourceMigrationBackfill(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(filepath.Join(t.TempDir(), "legacy.db")), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Windows 上 sqlite 文件句柄会阻塞 TempDir 清理，测试结束前先关连接。
+	t.Cleanup(func() {
+		if sqlDB, err := db.DB(); err == nil {
+			_ = sqlDB.Close()
+		}
+	})
+	// 造老结构：只有书源表（带旧唯一索引），书籍表用当前模型建。
+	if err := db.AutoMigrate(&legacyReaderSource{}, &model.ReaderBook{}); err != nil {
+		t.Fatal(err)
+	}
+	shared := &legacyReaderSource{ID: "legacy-1", Name: "共享源", SourceURL: "https://shared.example.com", Enabled: true}
+	if err := db.Create(shared).Error; err != nil {
+		t.Fatal(err)
+	}
+	softDeleted := &legacyReaderSource{ID: "legacy-2", Name: "已删源", SourceURL: "https://gone.example.com"}
+	if err := db.Create(softDeleted).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Delete(softDeleted).Error; err != nil { // 旧版 DeleteSource 的软删
+		t.Fatal(err)
+	}
+	// u1 两本、u2 一本都引用共享源；孤儿源无人引用。
+	books := []model.ReaderBook{
+		{UserID: "u1", Origin: "https://shared.example.com", BookURL: "https://shared.example.com/b/1", Name: "书1"},
+		{UserID: "u1", Origin: "https://shared.example.com", BookURL: "https://shared.example.com/b/2", Name: "书2"},
+		{UserID: "u2", Origin: "https://shared.example.com", BookURL: "https://shared.example.com/b/1", Name: "书1"},
+		{UserID: "u2", Origin: "https://orphan.example.com", BookURL: "https://orphan.example.com/b/1", Name: "孤儿"},
+	}
+	for i := range books {
+		if err := db.Create(&books[i]).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// 迁移。
+	if err := dropLegacyReaderSourceUniqueIndex(db); err != nil {
+		t.Fatalf("删旧索引失败: %v", err)
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatalf("AutoMigrate 失败: %v", err)
+	}
+	if err := backfillReaderSourceOwnership(db); err != nil {
+		t.Fatalf("回填失败: %v", err)
+	}
+
+	// 1. 旧唯一索引已删除：两个用户同 URL 各自一份。
+	var rows []model.ReaderBookSource
+	if err := db.Order("user_id ASC").Find(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+	byUser := map[string]model.ReaderBookSource{}
+	for _, r := range rows {
+		if r.SourceURL == "https://shared.example.com" {
+			byUser[r.UserID] = r
+		}
+	}
+	if len(byUser) != 2 {
+		t.Fatalf("共享源应有两份副本，实际 %d 份: %+v", len(byUser), byUser)
+	}
+	if byUser["u1"].ID == "" || byUser["u2"].ID == "" || byUser["u1"].ID == byUser["u2"].ID {
+		t.Fatalf("两份副本应有不同行 ID: u1=%q u2=%q", byUser["u1"].ID, byUser["u2"].ID)
+	}
+	if byUser["u1"].RawJSON != shared.RawJSON || byUser["u1"].Name != "共享源" {
+		t.Fatal("副本应保留原书源内容")
+	}
+	// 引用最多的用户保留原行（u1 有两本书）。
+	if byUser["u1"].ID != "legacy-1" {
+		t.Fatalf("原行应归引用最多的用户，实际 %q", byUser["u1"].ID)
+	}
+
+	// 2. 软删的历史行被清理。
+	var softLeft int64
+	if err := db.Unscoped().Model(&model.ReaderBookSource{}).
+		Where("source_url = ?", "https://gone.example.com").Count(&softLeft).Error; err != nil {
+		t.Fatal(err)
+	}
+	if softLeft != 0 {
+		t.Fatalf("软删的历史书源应被清理，剩余 %d 行", softLeft)
+	}
+
+	// 3. 无人引用的书源保持无归属（不会凭空分配给谁）。
+	var orphans int64
+	if err := db.Model(&model.ReaderBookSource{}).
+		Where("source_url = ? AND user_id <> ''", "https://orphan.example.com").Count(&orphans).Error; err != nil {
+		t.Fatal(err)
+	}
+	if orphans != 0 {
+		t.Fatal("无人引用的书源不应被分配归属")
+	}
+
+	// 4. 回填是幂等的（再次执行不产生重复副本）。
+	if err := backfillReaderSourceOwnership(db); err != nil {
+		t.Fatal(err)
+	}
+	var total int64
+	if err := db.Model(&model.ReaderBookSource{}).Where("source_url = ?", "https://shared.example.com").Count(&total).Error; err != nil {
+		t.Fatal(err)
+	}
+	if total != 2 {
+		t.Fatalf("重复回填不应新增副本，实际 %d 份", total)
+	}
+}

internal/database/schema_migration.go

@@ -1,27 +1,52 @@
 package database
 
 import (
+	"fmt"
+	"strings"
+
+	"go.uber.org/zap"
 	"gorm.io/gorm"
 
+	"github.com/truewhile/MeBox/internal/config"
 	"github.com/truewhile/MeBox/internal/model"
 )
 
 // AutoMigrate creates tables for every model registered in the model package.
 func AutoMigrate(db *gorm.DB) error {
+	return AutoMigrateWithConfig(db, nil, nil)
+}
+
+// AutoMigrateWithConfig 与 AutoMigrate 相同，另外接受配置与日志：
+// 配置用来决定可选的 PostgreSQL 搜索索引，日志用来记录耗时步骤
+// （首次在已有大库上重建索引可能需要数十秒）。两者都可以为 nil。
+func AutoMigrateWithConfig(db *gorm.DB, cfg *config.Config, log *zap.Logger) error {
 	// 必须先于 AutoMigrate：旧库中可能已有重复的 (user_id, media_id) 历史行，
 	// 不去重会导致唯一索引 uniq_user_history 创建失败。
 	if err := dedupePlaybackHistories(db); err != nil {
 		return err
 	}
+	// 书源从「全局唯一」改成「按用户独立」：先删掉 source_url 上的旧唯一索引。
+	// AutoMigrate 只会按索引名创建新索引，不会删除已改名的旧唯一索引，留着它
+	// 第二个用户导入同一书源就会撞唯一约束。
+	if err := dropLegacyReaderSourceUniqueIndex(db); err != nil {
+		return err
+	}
 	if err := db.AutoMigrate(model.AllModels()...); err != nil {
 		return err
 	}
+	// 回填书源归属：老库的书源没有 user_id，按「谁书架上有这本书」分配或复制副本。
+	if err := backfillReaderSourceOwnership(db); err != nil {
+		return err
+	}
 	if err := ensurePostgresColumnCompatibility(db); err != nil {
 		return err
 	}
 	if err := ensurePerformanceIndexes(db); err != nil {
 		return err
 	}
+	if err := ensureMediaPathIndex(db); err != nil {
+		return err
+	}
 	if err := ensureLibraryRootsCompatibility(db); err != nil {
 		return err
 	}
@@ -34,6 +59,111 @@ func AutoMigrate(db *gorm.DB) error {
 		}
 		return ensureSQLiteQueryOptimizer(db)
 	}
+	return ensurePostgresSearchIndexes(db, cfg, log)
+}
+
+// ensureMediaPathIndex 建立 media.path 的唯一约束与等值查找索引。
+//
+// 模型上不再用 gorm:"uniqueIndex"（见 model.Media.Path 的注释）：PostgreSQL 的
+// btree 单条索引项上限是 2704 字节，varchar(1024) 在中文路径下可达 3072 字节，
+// 对整列建唯一索引会让这类行插入时报
+//
+//	index row size ... exceeds btree version 4 maximum 2704
+//
+// 所以 PostgreSQL 改用 md5(path) 的表达式唯一索引（定长 32 字节，永远塞得下），
+// 同时保留一条普通索引 idx_media_path 供 path = ? 等值查找（扫描与 upsert 的
+// 热路径）使用。SQLite 没有这个长度限制，沿用整列唯一索引。
+func ensureMediaPathIndex(db *gorm.DB) error {
+	if db == nil || !db.Migrator().HasTable("media") {
+		return nil
+	}
+	if !isPostgres(db) {
+		return db.Exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_media_path ON media(path)`).Error
+	}
+	// 先建哈希唯一索引：此时旧索引还在，唯一性不会出现空窗。
+	if err := db.Exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_media_path_hash ON media(md5(path))`).Error; err != nil {
+		return err
+	}
+	unique, found, err := postgresIndexIsUnique(db, "idx_media_path")
+	if err != nil {
+		return err
+	}
+	if found && unique {
+		if err := db.Exec(`DROP INDEX IF EXISTS idx_media_path`).Error; err != nil {
+			return err
+		}
+	}
+	return db.Exec(`CREATE INDEX IF NOT EXISTS idx_media_path ON media(path)`).Error
+}
+
+// postgresIndexIsUnique 报告当前 schema 下是否存在该索引、以及它是否唯一。
+func postgresIndexIsUnique(db *gorm.DB, indexName string) (unique bool, found bool, err error) {
+	// 用指针接 bool：没有匹配行时 Scan 不报错，nil 即代表索引不存在。
+	var row struct {
+		IsUnique *bool
+	}
+	if err := db.Raw(`
+SELECT i.indisunique AS is_unique
+FROM pg_class c
+JOIN pg_index i ON i.indexrelid = c.oid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE n.nspname = current_schema() AND c.relname = ?
+`, indexName).Scan(&row).Error; err != nil {
+		return false, false, err
+	}
+	if row.IsUnique == nil {
+		return false, false, nil
+	}
+	return *row.IsUnique, true, nil
+}
+
+// ensurePostgresSearchIndexes 给 PostgreSQL 补上 SQLite FTS5 的替代品。
+//
+// 全文检索只在 SQLite 下存在（FTS5 虚表 + 触发器），PostgreSQL 下
+// media_search_repository 会退回 title/original_name/path/genres 的 ILIKE
+// 全表扫描。pg_trgm 的 GIN 三元组索引能让这类 '%term%' 模式（≥3 字符）走索引，
+// 把搜索从整表扫描降到索引扫描。
+//
+// 之所以可关闭：media 表写入非常频繁（每次扫描批量入库），多 4 个 GIN 索引会
+// 明显放大写入成本。默认开启以对齐 SQLite 的搜索能力，写入压力大的部署可以关掉。
+//
+// 整个过程是尽力而为：没有建扩展的权限、Postgres 版本不支持等情况下只记一条
+// 警告并继续启动，绝不让一个搜索加速项把服务挡在门外。
+func ensurePostgresSearchIndexes(db *gorm.DB, cfg *config.Config, log *zap.Logger) error {
+	if !isPostgres(db) {
+		return nil
+	}
+	if cfg != nil && !cfg.Database.PostgresTrgmIndex {
+		if log != nil {
+			log.Info("postgres trigram search index disabled; media search falls back to sequential scan")
+		}
+		return nil
+	}
+	if err := db.Exec(`CREATE EXTENSION IF NOT EXISTS pg_trgm`).Error; err != nil {
+		if log != nil {
+			log.Warn("create pg_trgm extension failed; media search falls back to sequential scan", zap.Error(err))
+		}
+		return nil
+	}
+	// 首次在已有大库上执行会重建索引（服务尚未开始接受请求），之后每次启动都因
+	// IF NOT EXISTS 直接跳过。
+	if log != nil {
+		log.Info("ensuring postgres trigram search indexes")
+	}
+	for _, stmt := range []string{
+		`CREATE INDEX IF NOT EXISTS idx_media_title_trgm ON media USING gin (title gin_trgm_ops)`,
+		`CREATE INDEX IF NOT EXISTS idx_media_original_name_trgm ON media USING gin (original_name gin_trgm_ops)`,
+		`CREATE INDEX IF NOT EXISTS idx_media_path_trgm ON media USING gin (path gin_trgm_ops)`,
+		`CREATE INDEX IF NOT EXISTS idx_media_genres_trgm ON media USING gin (genres gin_trgm_ops)`,
+	} {
+		if err := db.Exec(stmt).Error; err != nil {
+			if log != nil {
+				log.Warn("create trigram index failed; media search may fall back to sequential scan",
+					zap.String("statement", stmt), zap.Error(err))
+			}
+			return nil
+		}
+	}
 	return nil
 }
 
@@ -42,6 +172,105 @@ func ensureSQLiteQueryOptimizer(db *gorm.DB) error {
 	return db.Exec("ANALYZE").Error
 }
 
+// dropLegacyReaderSourceUniqueIndex 删除书源表上旧版 source_url 唯一索引。
+//
+// 书源改为按用户独立后唯一键是 (user_id, source_url)；SQLite 的 RenameTable 与
+// AutoMigrate 都不会删除按旧名创建的索引（实测旧唯一索引在改名后依然生效），
+// 必须显式删除，否则第二个用户导入同一书源会撞唯一约束。
+func dropLegacyReaderSourceUniqueIndex(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&model.ReaderBookSource{}) {
+		return nil
+	}
+	for _, name := range []string{"idx_reader_book_sources_source_url", "reader_book_sources_source_url_key"} {
+		if db.Migrator().HasIndex(&model.ReaderBookSource{}, name) {
+			if err := db.Migrator().DropIndex(&model.ReaderBookSource{}, name); err != nil {
+				return err
+			}
+		}
+	}
+	// 旧版 DeleteSource 是软删：这些历史行会继续占用 (user_id, source_url) 唯一键，
+	// 让「删掉再导入同一书源」失败。书源是可重新导入的数据，这里一次性清掉。
+	return db.Unscoped().Where("deleted_at IS NOT NULL").Delete(&model.ReaderBookSource{}).Error
+}
+
+// backfillReaderSourceOwnership 给老库的书源补上归属用户。
+//
+// 书源原先全局唯一，现在按用户独立：按「谁的书架上有这本书」把书源分配给该用户；
+// 同一书源被多个用户引用时，给每个用户复制一份副本（各自启停/排序/改规则），
+// 这样谁都不会因为别人删源而失去书源。
+//
+// 没有 user_id 且无人引用的书源保持原样（user_id 为空）——它不再出现在任何人的
+// 列表里，但数据仍在，需要时可以人工认领。
+func backfillReaderSourceOwnership(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&model.ReaderBookSource{}) {
+		return nil
+	}
+	var pending []model.ReaderBookSource
+	if err := db.Where("user_id = '' OR user_id IS NULL").Find(&pending).Error; err != nil {
+		return err
+	}
+	for i := range pending {
+		src := pending[i]
+		if err := assignOrCloneReaderSource(db, &src); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func assignOrCloneReaderSource(db *gorm.DB, src *model.ReaderBookSource) error {
+	if src == nil || src.SourceURL == "" {
+		return nil
+	}
+	// 引用该书源的书籍分布（去重到用户）。
+	type ownerCount struct {
+		UserID string
+		N      int64
+	}
+	var owners []ownerCount
+	if err := db.Model(&model.ReaderBook{}).
+		Select("user_id, COUNT(*) AS n").
+		Where("origin = ?", src.SourceURL).
+		Group("user_id").Order("n DESC").Scan(&owners).Error; err != nil {
+		return err
+	}
+	if len(owners) == 0 {
+		return nil // 无人引用：保持无归属
+	}
+	// 第一个用户（引用最多）直接接手这一行。
+	owner := owners[0].UserID
+	if owner == "" {
+		return nil
+	}
+	if err := db.Model(&model.ReaderBookSource{}).
+		Where("id = ?", src.ID).
+		Updates(map[string]any{"user_id": owner}).Error; err != nil {
+		return err
+	}
+	// 其余用户各复制一份副本（新行 ID，其余字段全量拷贝）。
+	for _, o := range owners[1:] {
+		if o.UserID == "" || o.UserID == owner {
+			continue
+		}
+		var exists int64
+		if err := db.Model(&model.ReaderBookSource{}).
+			Where("user_id = ? AND source_url = ?", o.UserID, src.SourceURL).
+			Count(&exists).Error; err != nil {
+			return err
+		}
+		if exists > 0 {
+			continue
+		}
+		clone := *src
+		clone.ID = ""
+		clone.UserID = o.UserID
+		if err := db.Create(&clone).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 // dedupePlaybackHistories removes duplicate (user_id, media_id) rows left by
 // the former read-then-write upsert, so the uniq_user_history composite unique
 // index can be created on existing databases. Keeps the most recent row per
@@ -67,16 +296,35 @@ func ensurePostgresColumnCompatibility(db *gorm.DB) error {
 	if !isPostgres(db) {
 		return nil
 	}
-	statements := []string{
-		`ALTER TABLE media ALTER COLUMN container TYPE varchar(128)`,
-		`ALTER TABLE media ALTER COLUMN genres TYPE text`,
-		`ALTER TABLE media ALTER COLUMN series_id TYPE varchar(128)`,
-		`ALTER TABLE media ALTER COLUMN duplicate_of TYPE varchar(128)`,
-		`ALTER TABLE playback_histories ALTER COLUMN media_id TYPE varchar(128)`,
-		`ALTER TABLE favorites ALTER COLUMN media_id TYPE varchar(128)`,
-		`ALTER TABLE playlist_items ALTER COLUMN media_id TYPE varchar(128)`,
+	// 只在类型确实不匹配时才 ALTER。
+	//
+	// PostgreSQL 的 ALTER COLUMN ... TYPE 只要类型声明与目标不同就会整表重写并
+	// 重建相关索引，执行期间持有 ACCESS EXCLUSIVE 锁。此前这里每次启动都无条件
+	// 发这 7 条语句：类型其实早已一致，但几十万行的 media 表仍然被反复重写，
+	// 启动会卡住数分钟，且期间这张表连读都被阻塞。
+	changes := []struct {
+		table  string
+		column string
+		target string
+	}{
+		{"media", "container", "varchar(128)"},
+		{"media", "genres", "text"},
+		{"media", "series_id", "varchar(128)"},
+		{"media", "duplicate_of", "varchar(128)"},
+		{"playback_histories", "media_id", "varchar(128)"},
+		{"favorites", "media_id", "varchar(128)"},
+		{"playlist_items", "media_id", "varchar(128)"},
 	}
-	for _, stmt := range statements {
+	for _, change := range changes {
+		current, found, err := postgresColumnType(db, change.table, change.column)
+		if err != nil {
+			return err
+		}
+		if !found || current == change.target {
+			continue
+		}
+		stmt := "ALTER TABLE " + quoteIdent(change.table) +
+			" ALTER COLUMN " + quoteIdent(change.column) + " TYPE " + change.target
 		if err := db.Exec(stmt).Error; err != nil {
 			return err
 		}
@@ -84,6 +332,35 @@ func ensurePostgresColumnCompatibility(db *gorm.DB) error {
 	return nil
 }
 
+// postgresColumnType 返回列在当前 schema 下的规范化类型描述，例如
+// "varchar(128)" / "text"。列不存在时 found 为 false。
+func postgresColumnType(db *gorm.DB, table, column string) (value string, found bool, err error) {
+	var row struct {
+		DataType  string
+		MaxLength *int64
+	}
+	if err := db.Raw(`
+SELECT data_type AS data_type, character_maximum_length AS max_length
+FROM information_schema.columns
+WHERE table_schema = current_schema() AND table_name = ? AND column_name = ?
+`, table, column).Scan(&row).Error; err != nil {
+		return "", false, fmt.Errorf("inspect postgres column %s.%s: %w", table, column, err)
+	}
+	dataType := strings.ToLower(strings.TrimSpace(row.DataType))
+	if dataType == "" {
+		return "", false, nil
+	}
+	// information_schema 用的是 SQL 标准名，映射回 GORM 标签里的写法再比较。
+	switch dataType {
+	case "character varying", "varchar":
+		dataType = "varchar"
+	}
+	if row.MaxLength != nil && *row.MaxLength > 0 {
+		dataType = fmt.Sprintf("%s(%d)", dataType, *row.MaxLength)
+	}
+	return dataType, true, nil
+}
+
 func ensurePerformanceIndexes(db *gorm.DB) error {
 	statements := []string{
 		// 完整多级排序索引：媒体库分页与首页预览的 ORDER BY

internal/database/schema_migration_path_index_test.go

@@ -0,0 +1,54 @@
+package database
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// TestAutoMigrateCreatesMediaPathUniqueIndex 守住 media.path 的唯一约束。
+//
+// 模型上不再声明 gorm:"uniqueIndex"（PostgreSQL 的 btree 单条索引项上限是
+// 2704 字节，而 varchar(1024) 在中文路径下可达 3072 字节，对整列建唯一索引会让
+// 这类行插入直接失败），改由 AutoMigrate 里的 ensureMediaPathIndex 按方言显式
+// 建立。一旦这个调用被漏掉，扫描会静默产生重复的媒体行（同一文件被入库多次）。
+func TestAutoMigrateCreatesMediaPathUniqueIndex(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(filepath.Join(t.TempDir(), "mebox.db")), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 必须在 TempDir 清理之前关掉连接，否则 Windows 上删除库文件会失败。
+	// t.Cleanup 是后进先出：这里注册的关闭早于 t.TempDir 注册的删除。
+	if sqlDB, err := db.DB(); err == nil {
+		t.Cleanup(func() { _ = sqlDB.Close() })
+	}
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("AutoMigrate: %v", err)
+	}
+
+	var definition string
+	if err := db.Raw(`SELECT COALESCE(sql, '') FROM sqlite_master WHERE type = 'index' AND name = 'idx_media_path'`).Scan(&definition).Error; err != nil {
+		t.Fatal(err)
+	}
+	if definition == "" {
+		t.Fatal("AutoMigrate did not create idx_media_path")
+	}
+	if !strings.Contains(strings.ToUpper(definition), "UNIQUE") {
+		t.Fatalf("idx_media_path is not unique: %q", definition)
+	}
+
+	if err := db.Create(&model.Media{Base: model.Base{ID: "m-1"}, Path: "/media/a.mkv"}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.Media{Base: model.Base{ID: "m-2"}, Path: "/media/a.mkv"}).Error; err == nil {
+		t.Fatal("a duplicate media path was accepted; the unique constraint is not enforced")
+	}
+}

internal/handler/media.go

@@ -810,6 +810,20 @@ func streamHandler(svc *service.Container) gin.HandlerFunc {
 				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 				return
 			}
+			// 远程条目可能是「整部剧/季/目录」：这类条目自身没有媒体源，远程 Emby 对它
+			// 们的 /Videos/{id}/stream 会直接回 500（Unable to cast object of type
+			// 'Series' to type 'IHasMediaSources'）。网页端、外部播放器、第三方客户端都
+			// 可能把这种 ID 送进来，这里统一改投第一集：302 让客户端自己跟过去，播放器
+			// 原有的 token / proxy 查询参数一并保留。
+			if playable := svc.EmbyRemote.PlayableRemoteID(ctx, acct, remoteID); playable != "" && playable != remoteID {
+				target := "/api/stream/" + service.EncodeEmbyRemoteID(mountID, playable)
+				if rawQuery := c.Request.URL.RawQuery; rawQuery != "" {
+					target += "?" + rawQuery
+				}
+				setRedirectNoStoreHeaders(c)
+				c.Redirect(http.StatusFound, target)
+				return
+			}
 			// 远程 Emby 条目的同源转发：VR 全景需要浏览器读帧（见 stream_proxy.go），
 			// 与挂载账号的 proxy_play 开关等价。
 			if mount.ProxyPlay || wantSameOriginProxy(c) {

internal/handler/reader_routes.go

@@ -90,7 +90,8 @@ func registerReaderRoutes(authed *gin.RouterGroup, svc *service.Container) {
 
 func readerListSourcesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		sources, err := svc.Reader.ListSources(c.Request.Context())
+		userID := c.GetString(middleware.CtxUserID)
+		sources, err := svc.Reader.ListSources(c.Request.Context(), userID)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -108,7 +109,8 @@ func readerImportSourcesHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		imported, err := svc.Reader.ImportSources(c.Request.Context(), body.Text)
+		userID := c.GetString(middleware.CtxUserID)
+		imported, err := svc.Reader.ImportSources(c.Request.Context(), userID, body.Text)
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
@@ -126,7 +128,8 @@ func readerUpdateSourceHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "enabled 字段必填"})
 			return
 		}
-		if err := svc.Reader.UpdateSourceEnabled(c.Request.Context(), c.Param("id"), *body.Enabled); err != nil {
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.UpdateSourceEnabled(c.Request.Context(), userID, c.Param("id"), *body.Enabled); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
@@ -136,7 +139,8 @@ func readerUpdateSourceHandler(svc *service.Container) gin.HandlerFunc {
 
 func readerDeleteSourceHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		if err := svc.Reader.DeleteSource(c.Request.Context(), c.Param("id")); err != nil {
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.DeleteSource(c.Request.Context(), userID, c.Param("id")); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
@@ -153,7 +157,8 @@ func readerDebugSourceHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		logs, err := svc.Reader.Debug(c.Request.Context(), c.Param("id"), body.Key)
+		userID := c.GetString(middleware.CtxUserID)
+		logs, err := svc.Reader.Debug(c.Request.Context(), userID, c.Param("id"), body.Key)
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
@@ -318,7 +323,8 @@ func readerBrowserAssetHandler(svc *service.Container) gin.HandlerFunc {
 
 func readerSourceLogoutHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		if err := svc.Reader.ClearSourceLogin(c.Request.Context(), c.Param("id")); err != nil {
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.ClearSourceLogin(c.Request.Context(), userID, c.Param("id")); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
@@ -335,7 +341,8 @@ func readerSetSourceVariableHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		if err := svc.Reader.SetSourceVariable(c.Request.Context(), c.Param("id"), body.Variable); err != nil {
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.SetSourceVariable(c.Request.Context(), userID, c.Param("id"), body.Variable); err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
@@ -352,7 +359,8 @@ func readerSetSourceLoginInfoHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		if err := svc.Reader.SetSourceLoginInfo(c.Request.Context(), c.Param("id"), body.Fields); err != nil {
+		userID := c.GetString(middleware.CtxUserID)
+		if err := svc.Reader.SetSourceLoginInfo(c.Request.Context(), userID, c.Param("id"), body.Fields); err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
@@ -373,7 +381,8 @@ func readerSearchHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		books, skipped, err := svc.Reader.Search(c.Request.Context(), body.Key, body.SourceIDs, body.Page)
+		userID := c.GetString(middleware.CtxUserID)
+		books, skipped, err := svc.Reader.Search(c.Request.Context(), userID, body.Key, body.SourceIDs, body.Page)
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return

internal/handler/stream_emby_remote_redirect_test.go

@@ -0,0 +1,200 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+	"github.com/truewhile/MeBox/internal/service"
+)
+
+// 首页轮播/剧集卡片交给播放器的是「整部剧」的伪装 ID，它自身没有媒体源：远程 Emby
+// 对它的取流请求会回 500（Unable to cast 'Series' to 'IHasMediaSources'）。这里锁定
+// 播放接口的行为——改投第一集，且客户端原有的查询参数（token / profile / proxy）
+// 必须原样带过去，否则播放器跟过去之后会掉鉴权。
+func TestStreamRedirectsRemoteContainerToPlayableEpisode(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/emby/Users/uid-1/Items/series-100":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"Id": "series-100", "Name": "某部新番", "Type": "Series", "IsFolder": true,
+			})
+		case "/emby/Users/uid-1/Items":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"Items": []map[string]any{
+					map[string]any{
+						"Id": "ep-1", "Name": "第1集", "Type": "Episode", "SeriesId": "series-100",
+						"ParentIndexNumber": 1, "IndexNumber": 1,
+						"MediaSources": []any{map[string]any{"Id": "ep-1-src"}},
+					},
+				},
+			})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer upstream.Close()
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(
+		&model.User{}, &model.UserPermission{}, &model.Setting{}, &model.Library{}, &model.Media{},
+		&model.StrmAccount{}, &model.EmbyMount{},
+	); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	cfg := &config.Config{}
+	cfg.Secrets.JWTSecret = "stream-redirect-secret"
+	log := zap.NewNop()
+
+	remote := service.NewEmbyRemoteService(cfg, log, repos, service.NewCryptoService("", log))
+	svc := &service.Container{Cfg: cfg, Repo: repos, EmbyRemote: remote}
+
+	rawConfig, _ := json.Marshal(map[string]string{
+		"url":            upstream.URL,
+		"api_key":        "test-api-key",
+		"remote_user_id": "uid-1",
+	})
+	if err := repos.StrmAccount.Create(t.Context(), &model.StrmAccount{
+		Base:     model.Base{ID: "acct-1"},
+		Name:     "远程 Emby",
+		Provider: model.StrmProviderEmbyRemote,
+		Config:   string(rawConfig),
+		Enabled:  true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.EmbyMount.Create(t.Context(), &model.EmbyMount{
+		Base:           model.Base{ID: "mount-1"},
+		AccountID:      "acct-1",
+		RemoteViewID:   "view-1",
+		RemoteViewName: "新番连载",
+		CollectionType: "tvshows",
+		Enabled:        true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	router.GET("/api/stream/:id", streamHandler(svc))
+
+	req := httptest.NewRequest(
+		http.MethodGet,
+		"/api/stream/"+service.EncodeEmbyRemoteID("mount-1", "series-100")+"?token=tok-1&profile=p-1",
+		nil,
+	)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusFound {
+		t.Fatalf("status = %d body=%s, want 302", w.Code, w.Body.String())
+	}
+	want := "/api/stream/" + service.EncodeEmbyRemoteID("mount-1", "ep-1") + "?token=tok-1&profile=p-1"
+	if got := w.Header().Get("Location"); got != want {
+		t.Fatalf("Location = %q, want %q", got, want)
+	}
+}
+
+// 本身可播的远程条目（单集/电影）不能被改写，必须照原样进入原来的代理/直连分支。
+func TestStreamKeepsPlayableRemoteItem(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	var streamCalls int
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/emby/Users/uid-1/Items/ep-1":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"Id": "ep-1", "Name": "第1集", "Type": "Episode", "SeriesId": "series-100",
+				"ParentIndexNumber": 1, "IndexNumber": 1,
+				"MediaSources": []any{map[string]any{"Id": "ep-1-src"}},
+			})
+		case "/emby/Videos/ep-1/stream":
+			streamCalls++
+			w.Header().Set("Content-Type", "video/mp4")
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte("bytes"))
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer upstream.Close()
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(
+		&model.User{}, &model.UserPermission{}, &model.Setting{}, &model.Library{}, &model.Media{},
+		&model.StrmAccount{}, &model.EmbyMount{},
+	); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	cfg := &config.Config{}
+	cfg.Secrets.JWTSecret = "stream-keep-secret"
+	log := zap.NewNop()
+
+	remote := service.NewEmbyRemoteService(cfg, log, repos, service.NewCryptoService("", log))
+	emby := service.NewEmbyService(cfg, log, repos).SetEmbyRemote(remote)
+	svc := &service.Container{Cfg: cfg, Repo: repos, EmbyRemote: remote, Emby: emby}
+
+	rawConfig, _ := json.Marshal(map[string]string{
+		"url":            upstream.URL,
+		"api_key":        "test-api-key",
+		"remote_user_id": "uid-1",
+	})
+	if err := repos.StrmAccount.Create(t.Context(), &model.StrmAccount{
+		Base:     model.Base{ID: "acct-1"},
+		Name:     "远程 Emby",
+		Provider: model.StrmProviderEmbyRemote,
+		Config:   string(rawConfig),
+		Enabled:  true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	// proxy_play=true：直接走反向代理分支，便于断言确实取到了流。
+	if err := repos.EmbyMount.Create(t.Context(), &model.EmbyMount{
+		Base:           model.Base{ID: "mount-1"},
+		AccountID:      "acct-1",
+		RemoteViewID:   "view-1",
+		RemoteViewName: "新番连载",
+		CollectionType: "tvshows",
+		ProxyPlay:      true,
+		Enabled:        true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	router.GET("/api/stream/:id", streamHandler(svc))
+
+	req := httptest.NewRequest(http.MethodGet, "/api/stream/"+service.EncodeEmbyRemoteID("mount-1", "ep-1"), nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s, want 200", w.Code, w.Body.String())
+	}
+	if got := w.Body.String(); got != "bytes" {
+		t.Fatalf("body = %q, want the proxied stream", got)
+	}
+	if streamCalls != 1 {
+		t.Fatalf("upstream stream calls = %d, want 1", streamCalls)
+	}
+}

internal/model/library_media.go

@@ -26,13 +26,17 @@ type LibraryRoot struct {
 // Media 是单个可播放项。剧集链接到 SeriesID；电影 SeriesID == ""。
 type Media struct {
 	Base
-	LibraryID       string  `gorm:"index;size:36;index:idx_media_library_release,priority:1" json:"library_id"`
-	LibraryRootID   string  `gorm:"index;size:36" json:"library_root_id,omitempty"`
-	SeriesID        string  `gorm:"index;size:128" json:"series_id,omitempty"`
-	Title           string  `gorm:"size:255;not null" json:"title"`
-	OriginalName    string  `gorm:"size:255" json:"original_name,omitempty"`
-	EpisodeTitle    string  `gorm:"size:255" json:"episode_title,omitempty"`
-	Path            string  `gorm:"uniqueIndex;size:1024;not null" json:"path"`
+	LibraryID     string `gorm:"index;size:36;index:idx_media_library_release,priority:1" json:"library_id"`
+	LibraryRootID string `gorm:"index;size:36" json:"library_root_id,omitempty"`
+	SeriesID      string `gorm:"index;size:128" json:"series_id,omitempty"`
+	Title         string `gorm:"size:255;not null" json:"title"`
+	OriginalName  string `gorm:"size:255" json:"original_name,omitempty"`
+	EpisodeTitle  string `gorm:"size:255" json:"episode_title,omitempty"`
+	// Path 的唯一性由 database 包按方言显式建索引，这里刻意不用 uniqueIndex：
+	// PostgreSQL 的 btree 单条索引项上限 2704 字节，而 varchar(1024) 在中文路径
+	// 下可达 3072 字节，直接对整列建唯一索引会让长路径的扫描插入直接失败
+	// （SQLite 没有这个限制）。见 database.ensureMediaPathIndex。
+	Path            string  `gorm:"size:1024;not null" json:"path"`
 	RelativePath    string  `gorm:"size:1024" json:"relative_path,omitempty"`
 	SizeBytes       int64   `json:"size_bytes"`
 	DurationSec     int     `json:"duration_sec"`

internal/model/reader.go

@@ -8,12 +8,19 @@ import (
 )
 
 // ReaderBookSource 书源：原始 JSON 全量存储 + 常用字段冗余列出便于筛选排序。
+//
+// 书源按用户独立：同一份书源不同用户可以各存一份（各自启停、排序、修改规则与变量），
+// 互不可见。唯一键是 (user_id, source_url)；跨用户的「同一本书」靠
+// ReaderBook.Origin（书源 URL）而不是书源行 ID 关联。
 type ReaderBookSource struct {
 	Base
+	// UserID 归属用户。历史数据迁移时会回填；值为空表示「旧版全局书源」，
+	// 只在没有任何用户引用时才会出现。
+	UserID         string     `gorm:"type:varchar(36);uniqueIndex:uniq_reader_source_user_url;index" json:"user_id"`
 	Name           string     `gorm:"type:varchar(255);index" json:"name"`
 	GroupName      string     `gorm:"type:varchar(255);index" json:"group"`
 	Type           int        `gorm:"default:0" json:"type"` // 0文本 1音频 2图片 3文件 4视频
-	SourceURL      string     `gorm:"type:varchar(512);index" json:"source_url"`
+	SourceURL      string     `gorm:"type:varchar(512);uniqueIndex:uniq_reader_source_user_url;index" json:"source_url"`
 	RawJSON        string     `gorm:"type:text" json:"-"`
 	Enabled        bool       `gorm:"default:true" json:"enabled"`
 	EnabledExplore bool       `gorm:"default:true" json:"enabled_explore"`

internal/repository/dialect.go

@@ -0,0 +1,21 @@
+package repository
+
+import "gorm.io/gorm"
+
+// LikeOperator 返回当前方言下「与 SQLite LIKE 行为一致」的模式匹配运算符。
+//
+// SQLite 的 LIKE 对 ASCII 不区分大小写（默认编译选项），PostgreSQL 的 LIKE 区分
+// 大小写、只有 ILIKE 才不区分。同一个搜索词在两种方言下必须给出同样的结果集，
+// 否则换库之后「inception」就再也搜不到「Inception」。
+//
+// 供构造原始 SQL 片段的调用方（含 service 层）使用。
+func LikeOperator(db *gorm.DB) string {
+	return likeOperator(db)
+}
+
+func likeOperator(db *gorm.DB) string {
+	if db != nil && db.Dialector != nil && db.Dialector.Name() == "postgres" {
+		return "ILIKE"
+	}
+	return "LIKE"
+}

internal/repository/dialect_test.go

@@ -0,0 +1,54 @@
+package repository
+
+import (
+	"strings"
+	"testing"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// TestSegmentPrewarmQueryBindsBooleanFound 守住 PostgreSQL 下片段预取查询的合法性。
+//
+// media_segment_fetches.found 是布尔列，而 PostgreSQL 没有 boolean = integer
+// 运算符：写成 f.found = 0 / = 1 会让计划任务里的片段预取固定报
+//
+//	operator does not exist: boolean = integer (SQLSTATE 42883)
+//
+// SQLite 一直能跑，所以这个错只在 PostgreSQL 上暴露（表现为日志里周期性出现
+// 该错误、片头片尾数据永远补不上）。这里断言语句里只能出现占位符绑定。
+func TestSegmentPrewarmQueryBindsBooleanFound(t *testing.T) {
+	query := segmentPrewarmCandidatesQuery
+	lower := strings.ToLower(query)
+	for _, forbidden := range []string{"found = 0", "found = 1", "found=0", "found=1", "found = true", "found = false"} {
+		if strings.Contains(lower, forbidden) {
+			t.Fatalf("预取查询把布尔列与字面量比较（%q），PostgreSQL 会直接报错：\n%s", forbidden, query)
+		}
+	}
+	if got := strings.Count(query, "f.found = ?"); got != 2 {
+		t.Fatalf("expected 2 placeholder-bound found comparisons, got %d:\n%s", got, query)
+	}
+}
+
+// TestLikeOperatorMatchesSQLiteCaseInsensitivity 守住搜索大小写行为的方言差异。
+//
+// SQLite 的 LIKE 对 ASCII 不区分大小写，PostgreSQL 的 LIKE 区分大小写：同一个
+// 搜索词在两种方言下必须给出同样的结果集，PostgreSQL 必须走 ILIKE。
+func TestLikeOperatorMatchesSQLiteCaseInsensitivity(t *testing.T) {
+	pg, err := gorm.Open(postgres.New(postgres.Config{
+		DSN: "postgres://mebox:mebox@127.0.0.1:5432/mebox?sslmode=disable",
+	}), &gorm.Config{
+		DryRun:                 true,
+		DisableAutomaticPing:   true,
+		SkipDefaultTransaction: true,
+	})
+	if err != nil {
+		t.Fatalf("open dry-run postgres: %v", err)
+	}
+	if got := LikeOperator(pg); got != "ILIKE" {
+		t.Fatalf("postgres LikeOperator = %q, want ILIKE", got)
+	}
+	if got := LikeOperator(nil); got != "LIKE" {
+		t.Fatalf("nil LikeOperator = %q, want LIKE", got)
+	}
+}

internal/repository/history_repository.go

@@ -33,6 +33,20 @@ func (r *HistoryRepository) UpsertProgress(ctx context.Context, h *model.Playbac
 	return r.upsert(ctx, h, true)
 }
 
+// historyColumn 生成「当前表」限定的列引用。
+//
+// PostgreSQL 的 ON CONFLICT DO UPDATE ... WHERE 里，未限定的列名会同时可解析到
+// 目标表和本次插入的行，于是报
+//
+//	column reference "session_started_at_ms" is ambiguous (SQLSTATE 42702)
+//
+// 结果是 POST /api/history 一律 500，观看进度与续播完全存不下来。SQLite 不做这项
+// 检查，所以这个错只在 PostgreSQL 上暴露。clause.CurrentTable 由 GORM 在构建语句
+// 时替换成真实表名，两种方言都能正确渲染。
+func historyColumn(name string) clause.Column {
+	return clause.Column{Table: clause.CurrentTable, Name: name}
+}
+
 func (r *HistoryRepository) upsert(ctx context.Context, h *model.PlaybackHistory, versioned bool) error {
 	updates := playbackHistoryAssignments(h)
 	if versioned {
@@ -49,16 +63,16 @@ func (r *HistoryRepository) upsert(ctx context.Context, h *model.PlaybackHistory
 		onConflict.Where = clause.Where{Exprs: []clause.Expression{
 			clause.Or(
 				clause.Lt{
-					Column: clause.Column{Name: "session_started_at_ms"},
+					Column: historyColumn("session_started_at_ms"),
 					Value:  h.SessionStartedAtMs,
 				},
 				clause.And(
 					clause.Eq{
-						Column: clause.Column{Name: "session_started_at_ms"},
+						Column: historyColumn("session_started_at_ms"),
 						Value:  h.SessionStartedAtMs,
 					},
 					clause.Lte{
-						Column: clause.Column{Name: "sequence"},
+						Column: historyColumn("sequence"),
 						Value:  h.Sequence,
 					},
 				),

internal/repository/history_repository_dialect_test.go

@@ -0,0 +1,65 @@
+package repository
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// TestHistoryProgressUpsertQualifiesConflictWhereColumns 守住 PostgreSQL 下进度上报
+// 的 upsert 语句合法性。
+//
+// ON CONFLICT DO UPDATE 的 WHERE 里如果不给列名加表限定，PostgreSQL 会因为这些列
+// 同时出现在本次插入的行里而拒绝该语句：
+//
+//	column reference "session_started_at_ms" is ambiguous (SQLSTATE 42702)
+//
+// 后果是 POST /api/history 全部 500，观看进度与续播完全存不下来。SQLite 不做这项
+// 检查（旧写法在 SQLite 下一直正常），所以只能在 PostgreSQL 方言下断言。
+func TestHistoryProgressUpsertQualifiesConflictWhereColumns(t *testing.T) {
+	repos, rec := newPostgresDryRunRepos(t)
+	ctx := context.Background()
+
+	if err := repos.History.UpsertProgress(ctx, &model.PlaybackHistory{
+		UserID:             "u-1",
+		MediaID:            "m-1",
+		PositionMs:         1_000,
+		DurationMs:         2_000,
+		SessionID:          "session-1",
+		SessionStartedAtMs: 111,
+		Sequence:           2,
+	}); err != nil {
+		t.Fatalf("build upsert: %v", err)
+	}
+
+	sql := rec.all()
+	if strings.TrimSpace(sql) == "" {
+		t.Fatal("no SQL captured from UpsertProgress")
+	}
+	if !strings.Contains(sql, "ON CONFLICT") {
+		t.Fatalf("expected an ON CONFLICT upsert, got:\n%s", sql)
+	}
+
+	// 只看 ON CONFLICT 之后的部分：SET 的赋值目标和 CASE 里的 duration_ms 引用
+	// 属于另一套语法规则，不在这里断言。
+	conflict := sql[strings.Index(sql, "ON CONFLICT"):]
+	whereIdx := strings.Index(conflict, " WHERE ")
+	if whereIdx < 0 {
+		t.Fatalf("ON CONFLICT clause has no DO UPDATE ... WHERE guard:\n%s", sql)
+	}
+	where := conflict[whereIdx:]
+
+	for _, want := range []string{
+		`"playback_histories"."session_started_at_ms"`,
+		`"playback_histories"."sequence"`,
+	} {
+		if !strings.Contains(where, want) {
+			t.Fatalf("DO UPDATE WHERE is missing the table-qualified %s; it is ambiguous on PostgreSQL:\n%s", want, sql)
+		}
+	}
+	if strings.Contains(where, `("session_started_at_ms"`) || strings.Contains(where, ` AND "sequence"`) {
+		t.Fatalf("DO UPDATE WHERE still references unqualified columns:\n%s", sql)
+	}
+}

internal/repository/media_repository_upsert.go

@@ -115,7 +115,12 @@ func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *mode
 		return m.ID, nil
 	}
 
-	updates := mediaUpsertUpdates(existing, *m)
+	// 孤儿行回收：原库已被删除时（DeleteLibrary 硬删库行；扫描与删除并发时扫描也会
+	// 把行写回已删库），这条行会钉死在不存在的 library_id 上。media.path 是全局唯一
+	// 索引，重扫既插不进同路径新行，又因 LibraryID 非空而拒绝迁移归属，于是新库/重建库
+	// 永远查不到这些条目（表现为"扫描明明有文件，库却是空的"）。这里显式识别并允许迁移。
+	reclaimLibrary := r.mediaRowLibraryIsOrphaned(ctx, db, existing.LibraryID, m.LibraryID, m.Path)
+	updates := mediaUpsertUpdates(existing, *m, reclaimLibrary)
 	if adopted {
 		updates["path"] = m.Path
 		if existing.DeletedAt.Valid {
@@ -139,6 +144,42 @@ func (r *MediaRepository) upsertWithDB(ctx context.Context, db *gorm.DB, m *mode
 	return existing.ID, nil
 }
 
+// mediaRowLibraryIsOrphaned reports whether a media row is still pinned to a
+// library that no longer exists.
+//
+// 删除媒体库会硬删库行（见 MediaService.DeleteLibrary），但扫描与删除并发时，
+// 已在途的扫描仍可能把这批文件写回已删库的 library_id；历史数据里也可能留下
+// 指向早已消失的库的行。因为 media.path 是全局唯一索引，这些行一旦存在：
+//  1. 重扫无法插入同路径的新行（唯一约束冲突）；
+//  2. addMediaPlacementUpdates 又因为 existing.LibraryID 非空而拒绝迁移归属。
+//
+// 结果就是新库 / 重建的同名库永远查不到这些条目，扫描报告有文件而库显示为空。
+// 这里把"原库已不存在"这种情况单独判定出来，交给扫描把归属迁移到当前库。
+func (r *MediaRepository) mediaRowLibraryIsOrphaned(ctx context.Context, db *gorm.DB, existingLibraryID, incomingLibraryID, incomingPath string) bool {
+	existingLibraryID = strings.TrimSpace(existingLibraryID)
+	incomingLibraryID = strings.TrimSpace(incomingLibraryID)
+	// 归属未变或原行为空（后者走既有的回填分支）时无需查库。
+	if existingLibraryID == "" || existingLibraryID == incomingLibraryID {
+		return false
+	}
+	// 云盘媒体的归属迁移由 addMediaPlacementUpdates 无条件处理，无需再查库。
+	if strings.HasPrefix(strings.ToLower(strings.TrimSpace(incomingPath)), "cloud://") {
+		return false
+	}
+	if db == nil || !db.Migrator().HasTable(&model.Library{}) {
+		return false
+	}
+	var count int64
+	// 刻意不加 Unscoped：软删除的库同样不再出现在库里，挂在它下面的媒体行
+	// 也属于"查不到"的孤儿，一并允许回收。查询失败时保守处理：宁可保留旧
+	// 归属，也不要把仍有效的库误判成孤儿。
+	if err := db.WithContext(ctx).Model(&model.Library{}).
+		Where("id = ?", existingLibraryID).Count(&count).Error; err != nil {
+		return false
+	}
+	return count == 0
+}
+
 func (r *MediaRepository) findOrCreateMediaByPath(ctx context.Context, db *gorm.DB, m *model.Media, aliasPaths []string) (model.Media, bool, bool, error) {
 	var existing model.Media
 	err := db.WithContext(ctx).Unscoped().Where("path = ?", m.Path).First(&existing).Error
@@ -194,14 +235,14 @@ func (r *MediaRepository) findMediaByAlias(ctx context.Context, db *gorm.DB, cur
 	return existing, err
 }
 
-func mediaUpsertUpdates(existing, incoming model.Media) map[string]any {
+func mediaUpsertUpdates(existing, incoming model.Media, reclaimLibrary bool) map[string]any {
 	updates := map[string]any{}
 	addMediaFileScanUpdates(updates, existing, incoming)
 	addMediaTitleUpdates(updates, existing, incoming)
 	addMediaExternalIDUpdates(updates, existing, incoming)
 	addMatchedMediaMetadataUpdates(updates, existing, incoming)
 	addMediaArtworkUpdates(updates, existing, incoming)
-	addMediaPlacementUpdates(updates, existing, incoming)
+	addMediaPlacementUpdates(updates, existing, incoming, reclaimLibrary)
 	addMediaSTRMUpdate(updates, existing, incoming)
 	return updates
 }
@@ -308,13 +349,15 @@ func addMediaArtworkUpdates(updates map[string]any, existing, incoming model.Med
 	}
 }
 
-func addMediaPlacementUpdates(updates map[string]any, existing, incoming model.Media) {
+func addMediaPlacementUpdates(updates map[string]any, existing, incoming model.Media, reclaimLibrary bool) {
 	// 云盘媒体：同一 cloud:// 文件可能先被父目录库扫描入库，之后用户按二级
 	// 分类重新挂载/扫描到更精确的分类库。此时让 library_id 迁移到当前扫描库，
 	// 否则媒体被钉死在旧库、新分类库里看不到(表现为"媒体部分消失")。
-	// 本地媒体物理位置固定：仅在原 library_id 为空时回填，不迁移。
+	// 本地媒体物理位置固定：仅在原 library_id 为空、或原库已不存在（孤儿行，
+	// reclaimLibrary）时才回填/迁移，既避免把仍属于其他库的本地媒体抢走，
+	// 又能让扫描回收被删除库遗留的行。
 	if isCloudMediaPath := strings.HasPrefix(strings.ToLower(strings.TrimSpace(incoming.Path)), "cloud://"); incoming.LibraryID != "" && incoming.LibraryID != existing.LibraryID {
-		if isCloudMediaPath || existing.LibraryID == "" {
+		if isCloudMediaPath || existing.LibraryID == "" || reclaimLibrary {
 			updates["library_id"] = incoming.LibraryID
 		}
 	}

internal/repository/media_search_repository.go

@@ -106,11 +106,8 @@ func (r *MediaRepository) searchFilteredLIKE(ctx context.Context, query string,
 	q := r.db.WithContext(ctx).Model(&model.Media{})
 	q = applyMediaQueryFilter(q, filter)
 	// SQLite 的 LIKE 对 ASCII 不区分大小写；Postgres 的 LIKE 区分大小写，
-	// 需用 ILIKE 保持两端搜索行为一致。
-	likeOp := "LIKE"
-	if r.db.Dialector != nil && r.db.Dialector.Name() == "postgres" {
-		likeOp = "ILIKE"
-	}
+	// 需用 ILIKE 保持两端搜索行为一致（见 dialect.go 的 likeOperator）。
+	likeOp := likeOperator(r.db)
 	terms := mediaSearchTerms(query)
 	for _, term := range terms {
 		like := "%" + escapeLike(term) + "%"

internal/repository/media_segment_repository.go

@@ -86,21 +86,15 @@ func (r *MediaSegmentRepository) UpsertFetch(ctx context.Context, row *model.Med
 	return r.db.WithContext(ctx).Clauses(onConflict).Create(row).Error
 }
 
-// ListPrewarmCandidates returns media that should be refreshed from source:
-// no ledger, expired miss (fetched_at < missBefore), or expired hit (fetched_at < hitBefore).
-// Recently played items come first so hot titles recover coverage sooner.
-func (r *MediaSegmentRepository) ListPrewarmCandidates(
-	ctx context.Context,
-	source string,
-	missBefore, hitBefore time.Time,
-	limit int,
-) ([]model.Media, error) {
-	if r == nil || limit <= 0 {
-		return nil, nil
-	}
-	rows := make([]model.Media, 0, limit)
-	// 可查询：有 TMDb，且是剧集（有季集）或电影（无季集）。
-	err := r.db.WithContext(ctx).Raw(`
+// segmentPrewarmCandidatesQuery 是片段预取候选查询。
+//
+// 抽成包级常量是为了让方言相关的回归测试能直接断言语句文本：DryRun 模式下
+// GORM 不会把 Raw 语句交给 logger，无法从执行路径上捕获生成后的 SQL。
+//
+// 注意 found 必须用占位符绑定布尔值，不能写 f.found = 0 / = 1：
+// PostgreSQL 没有 boolean = integer 运算符，那样写会固定报 SQLSTATE 42883
+// （SQLite 宽容，所以只在 PostgreSQL 上暴露）。
+const segmentPrewarmCandidatesQuery = `
 SELECT m.*
 FROM media m
 LEFT JOIN media_segment_fetches f
@@ -119,11 +113,29 @@ WHERE m.deleted_at IS NULL
   )
   AND (
     f.id IS NULL
-    OR (f.found = 0 AND f.fetched_at < ?)
-    OR (f.found = 1 AND f.fetched_at < ?)
+    OR (f.found = ? AND f.fetched_at < ?)
+    OR (f.found = ? AND f.fetched_at < ?)
   )
 ORDER BY ph.last_played DESC
 LIMIT ?
-`, source, missBefore, hitBefore, limit).Scan(&rows).Error
+`
+
+// ListPrewarmCandidates returns media that should be refreshed from source:
+// no ledger, expired miss (fetched_at < missBefore), or expired hit (fetched_at < hitBefore).
+// Recently played items come first so hot titles recover coverage sooner.
+func (r *MediaSegmentRepository) ListPrewarmCandidates(
+	ctx context.Context,
+	source string,
+	missBefore, hitBefore time.Time,
+	limit int,
+) ([]model.Media, error) {
+	if r == nil || limit <= 0 {
+		return nil, nil
+	}
+	rows := make([]model.Media, 0, limit)
+	// 可查询：有 TMDb，且是剧集（有季集）或电影（无季集）。
+	err := r.db.WithContext(ctx).
+		Raw(segmentPrewarmCandidatesQuery, source, false, missBefore, true, hitBefore, limit).
+		Scan(&rows).Error
 	return rows, err
 }

internal/repository/reader_repository.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 
 	"github.com/truewhile/MeBox/internal/model"
 )
@@ -15,10 +16,22 @@ type ReaderRepository struct {
 	db *gorm.DB
 }
 
-// ListSources 书源列表（按 customOrder 排序）。
-func (r *ReaderRepository) ListSources(ctx context.Context) ([]model.ReaderBookSource, error) {
+// readerOrderBy 组装方言安全的 ORDER BY。
+//
+// 用 clause.Column 让 GORM 按当前方言给列名加引号（SQLite 反引号 / PostgreSQL 双引号），
+// 而不是把引号硬编码进排序字符串。reader_books.order、reader_chapters.index、
+// reader_replace_rules.order 都撞上了 SQL 关键字（order 在 PostgreSQL 里是保留字）：
+// 之前写成 .Order("`order` ASC")，SQLite 下正常，PostgreSQL 下反引号被词法分析成
+// 运算符，直接报 `syntax error at or near "order"`，书架 / 目录 / 替换规则整页 500。
+func readerOrderBy(columns ...clause.OrderByColumn) clause.OrderBy {
+	return clause.OrderBy{Columns: columns}
+}
+
+// ListSources 用户的书源列表（书源按用户独立，按 customOrder 排序）。
+func (r *ReaderRepository) ListSources(ctx context.Context, userID string) ([]model.ReaderBookSource, error) {
 	var out []model.ReaderBookSource
-	err := r.db.WithContext(ctx).Order("custom_order ASC, updated_at DESC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("user_id = ?", userID).
+		Order("custom_order ASC, updated_at DESC").Find(&out).Error
 	return out, err
 }
 
@@ -31,8 +44,31 @@ func (r *ReaderRepository) GetSource(ctx context.Context, id string) (*model.Rea
 	return &out, nil
 }
 
-// GetSourceByURL 按书源 URL 取书源（导入去重用）。
-func (r *ReaderRepository) GetSourceByURL(ctx context.Context, sourceURL string) (*model.ReaderBookSource, error) {
+// GetSourceForUser 按 ID 取书源并校验归属用户。
+func (r *ReaderRepository) GetSourceForUser(ctx context.Context, userID, id string) (*model.ReaderBookSource, error) {
+	var out model.ReaderBookSource
+	if err := r.db.WithContext(ctx).First(&out, "id = ? AND user_id = ?", id, userID).Error; err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// GetSourceByURL 按用户 + 书源 URL 取书源（导入去重用）。
+func (r *ReaderRepository) GetSourceByURL(ctx context.Context, userID, sourceURL string) (*model.ReaderBookSource, error) {
+	var out model.ReaderBookSource
+	err := r.db.WithContext(ctx).First(&out, "user_id = ? AND source_url = ?", userID, sourceURL).Error
+	if err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// GetSourceAnyByURL 按书源 URL 取任意一份副本（不限定用户）。
+//
+// 媒体代理、目录刷新等路径只拿得到书籍的 origin（书源 URL）而没有用户上下文；
+// 请求目标由 URL 决定，任一副本都够用。多个用户各自改过规则/header 时，
+// 取到哪一份只影响「用谁的默认 header」，不影响书籍本身的定位。
+func (r *ReaderRepository) GetSourceAnyByURL(ctx context.Context, sourceURL string) (*model.ReaderBookSource, error) {
 	var out model.ReaderBookSource
 	err := r.db.WithContext(ctx).First(&out, "source_url = ?", sourceURL).Error
 	if err != nil {
@@ -41,6 +77,13 @@ func (r *ReaderRepository) GetSourceByURL(ctx context.Context, sourceURL string)
 	return &out, nil
 }
 
+// ListSourceRowsByURL 取某书源 URL 的全部副本（判断是否仍有其他用户引用）。
+func (r *ReaderRepository) ListSourceRowsByURL(ctx context.Context, sourceURL string) ([]model.ReaderBookSource, error) {
+	var out []model.ReaderBookSource
+	err := r.db.WithContext(ctx).Where("source_url = ?", sourceURL).Find(&out).Error
+	return out, err
+}
+
 // CreateSource 新增书源。
 func (r *ReaderRepository) CreateSource(ctx context.Context, src *model.ReaderBookSource) error {
 	return r.db.WithContext(ctx).Create(src).Error
@@ -52,20 +95,34 @@ func (r *ReaderRepository) UpdateSource(ctx context.Context, src *model.ReaderBo
 }
 
 // DeleteSource 删除书源（连带清理其会话状态）。
+//
+// 用物理删除而不是软删：唯一键是 (user_id, source_url)，而索引会覆盖软删行——
+// 软删后再导入同一书源会撞唯一约束（表现为「导入失败」），删掉再导入是本模块的
+// 正常操作。书源本身是可重新导入的数据，不需要软删保留。
+//
+// 会话状态表仍按 source_url 一源一条（跨用户共享），因此只有在该 URL 已无任何
+// 其他用户的书源副本时才连带清理，否则会把别人的登录态一起删掉。
 func (r *ReaderRepository) DeleteSource(ctx context.Context, id string) error {
 	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		src := &model.ReaderBookSource{}
 		if err := tx.First(src, "id = ?", id).Error; err == nil && src.SourceURL != "" {
-			// 会话状态是「一源一条」，而 source_url 上有覆盖软删行的唯一索引：
-			// 软删会让这一行继续占着 source_url，之后 SaveSourceState 的
-			// First（默认排除软删行）查不到、Create 就会撞唯一约束，
-			// 表现为「保存书源会话状态失败: UNIQUE constraint failed」，
-			// cookie / 登录态从此再也存不进去。这里必须硬删。
-			if err := tx.Unscoped().Delete(&model.ReaderSourceState{}, "source_url = ?", src.SourceURL).Error; err != nil {
+			var others int64
+			if err := tx.Model(&model.ReaderBookSource{}).
+				Where("source_url = ? AND id <> ?", src.SourceURL, id).Count(&others).Error; err != nil {
 				return err
 			}
+			if others == 0 {
+				// 会话状态是「一源一条」，而 source_url 上有覆盖软删行的唯一索引：
+				// 软删会让这一行继续占着 source_url，之后 SaveSourceState 的
+				// First（默认排除软删行）查不到、Create 就会撞唯一约束，
+				// 表现为「保存书源会话状态失败: UNIQUE constraint failed」，
+				// cookie / 登录态从此再也存不进去。这里必须硬删。
+				if err := tx.Unscoped().Delete(&model.ReaderSourceState{}, "source_url = ?", src.SourceURL).Error; err != nil {
+					return err
+				}
+			}
 		}
-		return tx.Delete(&model.ReaderBookSource{}, "id = ?", id).Error
+		return tx.Unscoped().Delete(&model.ReaderBookSource{}, "id = ?", id).Error
 	})
 }
 
@@ -108,7 +165,11 @@ func (r *ReaderRepository) SaveSourceState(ctx context.Context, st *model.Reader
 // ListBooks 用户书架（按 order 排序）。
 func (r *ReaderRepository) ListBooks(ctx context.Context, userID string) ([]model.ReaderBook, error) {
 	var out []model.ReaderBook
-	err := r.db.WithContext(ctx).Where("user_id = ?", userID).Order("`order` ASC, updated_at DESC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("user_id = ?", userID).
+		Order(readerOrderBy(
+			clause.OrderByColumn{Column: clause.Column{Name: "order"}},
+			clause.OrderByColumn{Column: clause.Column{Name: "updated_at"}, Desc: true},
+		)).Find(&out).Error
 	return out, err
 }
 
@@ -186,7 +247,10 @@ func (r *ReaderRepository) SwitchBookOrigin(ctx context.Context, book *model.Rea
 // ListChapters 按序取章节。
 func (r *ReaderRepository) ListChapters(ctx context.Context, bookID string) ([]model.ReaderChapter, error) {
 	var out []model.ReaderChapter
-	err := r.db.WithContext(ctx).Where("book_id = ?", bookID).Order("`index` ASC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("book_id = ?", bookID).
+		Order(readerOrderBy(
+			clause.OrderByColumn{Column: clause.Column{Name: "index"}},
+		)).Find(&out).Error
 	return out, err
 }
 
@@ -320,9 +384,17 @@ func (r *ReaderRepository) CountChaptersByBook(ctx context.Context, bookIDs []st
 }
 
 // GetChapter 取指定章节。
+//
+// index 在 PostgreSQL 里是保留字，必须让 GORM 按方言加引号（SQLite 反引号 /
+// PostgreSQL 双引号）。此前写成硬编码的 "book_id = ? AND `index` = ?"，
+// PostgreSQL 会把反引号词法分析成运算符并报 syntax error at or near "`"。
 func (r *ReaderRepository) GetChapter(ctx context.Context, bookID string, index int) (*model.ReaderChapter, error) {
 	var out model.ReaderChapter
-	if err := r.db.WithContext(ctx).First(&out, "book_id = ? AND `index` = ?", bookID, index).Error; err != nil {
+	err := r.db.WithContext(ctx).
+		Where(clause.Eq{Column: clause.Column{Name: "book_id"}, Value: bookID}).
+		Where(clause.Eq{Column: clause.Column{Name: "index"}, Value: index}).
+		First(&out).Error
+	if err != nil {
 		return nil, err
 	}
 	return &out, nil
@@ -388,7 +460,11 @@ func (r *ReaderRepository) SaveBookGroups(ctx context.Context, row *model.Reader
 // ListReplaceRules 用户替换规则（按 order 排序）。
 func (r *ReaderRepository) ListReplaceRules(ctx context.Context, userID string) ([]model.ReaderReplaceRule, error) {
 	var out []model.ReaderReplaceRule
-	err := r.db.WithContext(ctx).Where("user_id = ?", userID).Order("`order` DESC, created_at ASC").Find(&out).Error
+	err := r.db.WithContext(ctx).Where("user_id = ?", userID).
+		Order(readerOrderBy(
+			clause.OrderByColumn{Column: clause.Column{Name: "order"}, Desc: true},
+			clause.OrderByColumn{Column: clause.Column{Name: "created_at"}},
+		)).Find(&out).Error
 	return out, err
 }
 

internal/repository/reader_repository_dialect_test.go

@@ -0,0 +1,116 @@
+package repository
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
+)
+
+// sqlCaptureLogger 只记录 GORM 生成的 SQL，不打印任何日志。
+type sqlCaptureLogger struct {
+	mu    sync.Mutex
+	lines []string
+}
+
+func (l *sqlCaptureLogger) LogMode(gormlogger.LogLevel) gormlogger.Interface { return l }
+func (l *sqlCaptureLogger) Info(context.Context, string, ...interface{})     {}
+func (l *sqlCaptureLogger) Warn(context.Context, string, ...interface{})     {}
+func (l *sqlCaptureLogger) Error(context.Context, string, ...interface{})    {}
+
+func (l *sqlCaptureLogger) Trace(_ context.Context, _ time.Time, fc func() (string, int64), _ error) {
+	sql, _ := fc()
+	l.mu.Lock()
+	l.lines = append(l.lines, sql)
+	l.mu.Unlock()
+}
+
+func (l *sqlCaptureLogger) all() string {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return strings.Join(l.lines, "\n")
+}
+
+// newPostgresDryRunRepos 返回使用 PostgreSQL 方言的 repository 容器：
+// DryRun 只构建 SQL 不执行，DisableAutomaticPing 让它无需真实数据库也能离线运行，
+// SkipDefaultTransaction 则挡掉 GORM 默认事务包装——那一步会真的去开事务连接，
+// 在 DryRun 下同样会拨号（ToSQL 内部也是这么绕开的）。于是可以直接断言生成语句
+// 在 PostgreSQL 下是否合法。
+func newPostgresDryRunRepos(t *testing.T) (*Container, *sqlCaptureLogger) {
+	t.Helper()
+	rec := &sqlCaptureLogger{}
+	db, err := gorm.Open(postgres.New(postgres.Config{
+		DSN: "postgres://mebox:mebox@127.0.0.1:5432/mebox?sslmode=disable",
+	}), &gorm.Config{
+		DryRun:                 true,
+		DisableAutomaticPing:   true,
+		SkipDefaultTransaction: true,
+		Logger:                 rec,
+	})
+	if err != nil {
+		t.Fatalf("open dry-run postgres: %v", err)
+	}
+	return New(db), rec
+}
+
+// TestReaderListsUseDialectQuotedReservedColumns 守住阅读子系统列表查询在
+// PostgreSQL 下的合法性。reader_books.order / reader_chapters.index /
+// reader_replace_rules.order 都是关键字级列名（order 在 PostgreSQL 里是保留字）。
+//
+// 排序条件曾经写成硬编码反引号的原始字符串，例如 .Order("`order` ASC")：
+// SQLite 正常，PostgreSQL 会把反引号词法分析成运算符，直接报
+// `syntax error at or near "order"` (SQLSTATE 42601)，书架 / 目录 / 替换规则整页 500。
+// 现在改用 clause.Column，由 GORM 按方言加引号（SQLite 反引号 / PostgreSQL 双引号）。
+func TestReaderListsUseDialectQuotedReservedColumns(t *testing.T) {
+	ctx := context.Background()
+	cases := []struct {
+		name  string
+		run   func(repos *Container) error
+		wants []string
+	}{
+		{
+			name:  "books",
+			run:   func(repos *Container) error { _, err := repos.Reader.ListBooks(ctx, "user-1"); return err },
+			wants: []string{`"order"`, `"updated_at" DESC`},
+		},
+		{
+			name:  "chapters",
+			run:   func(repos *Container) error { _, err := repos.Reader.ListChapters(ctx, "book-1"); return err },
+			wants: []string{`"index"`},
+		},
+		{
+			name:  "replace rules",
+			run:   func(repos *Container) error { _, err := repos.Reader.ListReplaceRules(ctx, "user-1"); return err },
+			wants: []string{`"order" DESC`, `"created_at"`},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			repos, rec := newPostgresDryRunRepos(t)
+			if err := tc.run(repos); err != nil {
+				t.Fatalf("build query: %v", err)
+			}
+			sql := rec.all()
+			if strings.TrimSpace(sql) == "" {
+				t.Fatal("no SQL captured from the repository call")
+			}
+			if strings.Contains(sql, "`") {
+				t.Fatalf("SQL uses backtick quoting, which PostgreSQL rejects:\n%s", sql)
+			}
+			if !strings.Contains(sql, "ORDER BY") {
+				t.Fatalf("SQL has no ORDER BY clause:\n%s", sql)
+			}
+			for _, want := range tc.wants {
+				if !strings.Contains(sql, want) {
+					t.Fatalf("SQL missing %q:\n%s", want, sql)
+				}
+			}
+		})
+	}
+}

internal/service/backup.go

@@ -1,9 +1,13 @@
 // Package service — database hot backup and restore.
 //
-// BackupService uses SQLite's "VACUUM INTO" (available since 3.27.0) to
-// produce a consistent copy of the database without blocking writers.
-// Backup files are stored under {data_dir}/backups/ with a timestamp
-// suffix. The admin UI can list / download / delete / restore them.
+// Backup files are stored under {data_dir}/backups/ with a timestamp suffix.
+// The admin UI can list / download / delete / restore them.
+//
+// 两种方言的备份形态不同：
+//   - SQLite：用 "VACUUM INTO"（3.27.0 起可用）产出一个一致的库文件，
+//     扩展名 .db；恢复即「替换库文件 + 重启」。
+//   - PostgreSQL：没有单文件语义，用逻辑备份（见 backup_postgres.go），
+//     扩展名 .json.gz；恢复是在单个事务内重建全部表。
 package service
 
 import (
@@ -65,18 +69,34 @@ func (b *BackupService) backupFilePath(filename string) (string, error) {
 	return path, nil
 }
 
-// Create produces a new hot backup via "VACUUM INTO".
+// isPostgres reports whether the service is backed by PostgreSQL.
+//
+// PostgreSQL 不支持 SQLite 的 "VACUUM INTO"，按文件替换恢复也会写错目标，
+// 因此备份/恢复必须按方言分支，不能共用一条路径。
+func (b *BackupService) isPostgres() bool {
+	return b.db != nil && b.db.Dialector != nil && b.db.Dialector.Name() == "postgres"
+}
+
+// Create produces a new hot backup. SQLite uses "VACUUM INTO"; PostgreSQL uses
+// a logical dump.
 func (b *BackupService) Create(ctx context.Context) (*BackupInfo, error) {
 	dir := b.backupDir()
 	if err := os.MkdirAll(dir, 0o750); err != nil {
 		return nil, err
 	}
 	ts := time.Now().Format("20060102_150405")
-	dst := filepath.Join(dir, fmt.Sprintf("mebox_%s.db", ts))
 
-	// VACUUM INTO creates a clean, non-WAL copy atomically.
-	if err := b.db.WithContext(ctx).Exec("VACUUM INTO ?", dst).Error; err != nil {
-		return nil, fmt.Errorf("VACUUM INTO failed: %w", err)
+	var (
+		dst string
+		err error
+	)
+	if b.isPostgres() {
+		dst, err = b.createPostgresBackup(ctx, ts)
+	} else {
+		dst, err = b.createSQLiteBackup(ctx, ts)
+	}
+	if err != nil {
+		return nil, err
 	}
 	stat, err := os.Stat(dst)
 	if err != nil {
@@ -91,6 +111,15 @@ func (b *BackupService) Create(ctx context.Context) (*BackupInfo, error) {
 	}, nil
 }
 
+func (b *BackupService) createSQLiteBackup(ctx context.Context, stamp string) (string, error) {
+	dst := filepath.Join(b.backupDir(), fmt.Sprintf("mebox_%s.db", stamp))
+	// VACUUM INTO creates a clean, non-WAL copy atomically.
+	if err := b.db.WithContext(ctx).Exec("VACUUM INTO ?", dst).Error; err != nil {
+		return "", fmt.Errorf("VACUUM INTO failed: %w", err)
+	}
+	return dst, nil
+}
+
 // List returns every backup file in the backup directory, newest first.
 func (b *BackupService) List() ([]BackupInfo, error) {
 	dir := b.backupDir()
@@ -103,7 +132,7 @@ func (b *BackupService) List() ([]BackupInfo, error) {
 	}
 	out := make([]BackupInfo, 0, len(entries))
 	for _, e := range entries {
-		if e.IsDir() || !strings.HasSuffix(e.Name(), ".db") {
+		if e.IsDir() || !isBackupFilename(e.Name()) {
 			continue
 		}
 		info, err := e.Info()
@@ -132,9 +161,10 @@ func (b *BackupService) Delete(filename string) error {
 	return os.Remove(path)
 }
 
-// Restore copies a backup over the live database using VACUUM INTO in
-// reverse. WARNING: this is destructive — the live DB will be replaced.
-// Callers should shut down the server after this call.
+// Restore replaces the live database with the given backup.
+// WARNING: this is destructive. SQLite restores by swapping the database file
+// (the caller should shut down the server afterwards); PostgreSQL restores by
+// rebuilding every table inside a single transaction.
 func (b *BackupService) Restore(ctx context.Context, filename string) error {
 	src, err := b.backupFilePath(filename)
 	if err != nil {
@@ -143,6 +173,19 @@ func (b *BackupService) Restore(ctx context.Context, filename string) error {
 	if _, err := os.Stat(src); err != nil {
 		return fmt.Errorf("backup not found: %s", filename)
 	}
+	if b.isPostgres() {
+		if !strings.HasSuffix(filename, postgresBackupSuffix) {
+			return errors.New("该备份是 SQLite 文件备份，当前运行在 PostgreSQL 上，无法恢复")
+		}
+		return b.restorePostgresBackup(ctx, src)
+	}
+	if !strings.HasSuffix(filename, ".db") {
+		return errors.New("该备份是 PostgreSQL 逻辑备份，当前运行在 SQLite 上，无法恢复")
+	}
+	return b.restoreSQLiteBackup(filename, src)
+}
+
+func (b *BackupService) restoreSQLiteBackup(filename, src string) error {
 	dbPath, err := filepath.Abs(b.cfg.Database.DBPath)
 	if err != nil || dbPath == "" {
 		return errors.New("invalid database path")
@@ -171,7 +214,13 @@ func (b *BackupService) Restore(ctx context.Context, filename string) error {
 	return nil
 }
 
-// isValidBackupFilename rejects path traversal attempts and non-.db files.
+// isBackupFilename reports whether name looks like a backup produced by either
+// dialect (SQLite ".db" or PostgreSQL ".json.gz").
+func isBackupFilename(name string) bool {
+	return strings.HasSuffix(name, ".db") || strings.HasSuffix(name, postgresBackupSuffix)
+}
+
+// isValidBackupFilename rejects path traversal attempts and non-backup files.
 func isValidBackupFilename(name string) bool {
 	if name == "" {
 		return false
@@ -179,8 +228,5 @@ func isValidBackupFilename(name string) bool {
 	if strings.ContainsAny(name, "/\\") || strings.Contains(name, "..") {
 		return false
 	}
-	if !strings.HasSuffix(name, ".db") {
-		return false
-	}
-	return true
+	return isBackupFilename(name)
 }

internal/service/backup_postgres.go

@@ -0,0 +1,279 @@
+package service
+
+import (
+	"compress/gzip"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/schema"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// PostgreSQL 逻辑备份 / 恢复。
+//
+// SQLite 的备份是「VACUUM INTO 出一个一致的库文件，恢复时替换文件」，而
+// PostgreSQL 既没有 VACUUM INTO，数据也由服务端进程管理，没有可替换的单文件，
+// 所以这里实现逻辑备份：把每张表按主键顺序分块序列化成 JSON Lines（gzip 压缩）
+// 写入 {data_dir}/backups/。
+//
+// 分块序列化而不是整表 marshal：media 表在真实媒体库上可达几十万行、每行还带
+// overview / path 等长文本，整表进内存会把小内存的 NAS 打爆。
+//
+// 恢复在单个事务内「先清空全部模型表、再逐块插入」：任何一步失败（包括备份文件
+// 读到一半损坏）都整体回滚，不会留下半清空的库。因此恢复不需要重启服务。
+const (
+	postgresBackupSuffix   = ".json.gz"
+	postgresBackupFormat   = "mebox-postgres-logical"
+	postgresBackupVersion  = 1
+	backupDumpChunkSize    = 1000
+	backupRestoreBatchSize = 500
+)
+
+type postgresBackupHeader struct {
+	Format    string    `json:"format"`
+	Version   int       `json:"version"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// postgresBackupRow 是「列名 → JSON 值」的一行。
+//
+// 刻意逐列反射序列化，而不是直接 json.Marshal 模型结构体：模型里有大量带
+// json:"-" 的列（Base.DeletedAt、User.AllowedLibraryIDs、APIConfig.APIKey、
+// StrmAccount.Config、PlayProfile.PINHash、ReaderBookSource.RawJSON…），走结构体
+// 自带的序列化会把这些列整列丢掉——软删除行会在恢复后「复活」，加密后的第三方
+// 密钥与 PIN 会全部丢失。
+type postgresBackupRow map[string]json.RawMessage
+
+type postgresBackupChunk struct {
+	Table string              `json:"table"`
+	Rows  []postgresBackupRow `json:"rows"`
+}
+
+// parseModelSchema 返回模型对应的表名与 GORM schema（逐列反射所需）。
+func parseModelSchema(db *gorm.DB, m any) (table string, sch *schema.Schema, err error) {
+	stmt := &gorm.Statement{DB: db}
+	if err := stmt.Parse(m); err != nil {
+		return "", nil, err
+	}
+	return stmt.Schema.Table, stmt.Schema, nil
+}
+
+// postgresBackupModelSchemas 返回「表名 → 模型 schema / 结构体类型」，用于把备份
+// 里的行还原成 GORM 能插入的具体类型。
+func postgresBackupModelSchemas(db *gorm.DB) (map[string]*schema.Schema, map[string]reflect.Type, error) {
+	schemas := make(map[string]*schema.Schema, len(model.AllModels()))
+	types := make(map[string]reflect.Type, len(model.AllModels()))
+	for _, m := range model.AllModels() {
+		table, sch, err := parseModelSchema(db, m)
+		if err != nil {
+			return nil, nil, err
+		}
+		schemas[table] = sch
+		types[table] = reflect.TypeOf(m).Elem()
+	}
+	return schemas, types, nil
+}
+
+// createPostgresBackup 把全库导出成一个 gzip 压缩的 JSON Lines 文件。
+func (b *BackupService) createPostgresBackup(ctx context.Context, stamp string) (string, error) {
+	dst := filepath.Join(b.backupDir(), "mebox_"+stamp+postgresBackupSuffix)
+	file, err := os.OpenFile(dst, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o600)
+	if err != nil {
+		return "", err
+	}
+	complete := false
+	defer func() {
+		_ = file.Close()
+		if !complete {
+			// 半截备份文件比没有备份更危险：留着会让人以为有可用的还原点。
+			_ = os.Remove(dst)
+		}
+	}()
+
+	zw := gzip.NewWriter(file)
+	enc := json.NewEncoder(zw)
+	if err := enc.Encode(postgresBackupHeader{
+		Format:    postgresBackupFormat,
+		Version:   postgresBackupVersion,
+		CreatedAt: time.Now(),
+	}); err != nil {
+		return "", fmt.Errorf("写入备份头失败: %w", err)
+	}
+	for _, m := range model.AllModels() {
+		table, sch, err := parseModelSchema(b.db, m)
+		if err != nil {
+			return "", err
+		}
+		if !b.db.Migrator().HasTable(table) {
+			continue
+		}
+		if err := b.dumpPostgresTable(ctx, m, sch, table, enc); err != nil {
+			return "", err
+		}
+	}
+	if err := zw.Close(); err != nil {
+		return "", fmt.Errorf("压缩备份失败: %w", err)
+	}
+	if err := file.Sync(); err != nil {
+		return "", fmt.Errorf("写入备份失败: %w", err)
+	}
+	complete = true
+	return dst, nil
+}
+
+// dumpPostgresTable 按主键分块导出一张表。FindInBatches 会自己按主键升序游标
+// 翻页（WHERE pk > last），不会像 OFFSET 分页那样在大表上做 O(n²) 扫描。
+func (b *BackupService) dumpPostgresTable(ctx context.Context, m any, sch *schema.Schema, table string, enc *json.Encoder) error {
+	// 软删除行也要备份：恢复后应还原成删除前的样子，而不是让它们「复活」。
+	slicePtr := reflect.New(reflect.SliceOf(reflect.TypeOf(m).Elem()))
+	err := b.db.WithContext(ctx).Unscoped().
+		FindInBatches(slicePtr.Interface(), backupDumpChunkSize, func(_ *gorm.DB, _ int) error {
+			rows, err := encodePostgresBackupRows(ctx, sch, slicePtr.Elem())
+			if err != nil {
+				return fmt.Errorf("编码表 %s 失败: %w", table, err)
+			}
+			return enc.Encode(postgresBackupChunk{Table: table, Rows: rows})
+		}).Error
+	if err != nil {
+		return fmt.Errorf("导出表 %s 失败: %w", table, err)
+	}
+	return nil
+}
+
+// backupPersistableFields 返回真正对应数据库列的字段。
+//
+// GORM 的 Schema.Fields 里还带着 gorm:"-" 的字段（例如 User.AllowedLibraryList、
+// LibraryTagList），它们的 DBName 是空字符串。不过滤的话多个「列」会共用空键：
+// 编码时互相覆盖，解码时把某个字段的值写到另一个字段上，报出
+// 「cannot unmarshal number into Go value of type []string」这类与真实数据无关的错。
+func backupPersistableFields(sch *schema.Schema) []*schema.Field {
+	out := make([]*schema.Field, 0, len(sch.Fields))
+	for _, field := range sch.Fields {
+		if field.DBName == "" {
+			continue
+		}
+		out = append(out, field)
+	}
+	return out
+}
+
+// encodePostgresBackupRows 逐列反射序列化一个批次。
+func encodePostgresBackupRows(ctx context.Context, sch *schema.Schema, slice reflect.Value) ([]postgresBackupRow, error) {
+	fields := backupPersistableFields(sch)
+	rows := make([]postgresBackupRow, 0, slice.Len())
+	for i := 0; i < slice.Len(); i++ {
+		element := slice.Index(i)
+		row := make(postgresBackupRow, len(fields))
+		for _, field := range fields {
+			value := field.ReflectValueOf(ctx, element)
+			if !value.IsValid() {
+				continue
+			}
+			raw, err := json.Marshal(value.Interface())
+			if err != nil {
+				return nil, fmt.Errorf("列 %s: %w", field.DBName, err)
+			}
+			row[field.DBName] = raw
+		}
+		rows = append(rows, row)
+	}
+	return rows, nil
+}
+
+// decodePostgresBackupRows 把「列名 → JSON 值」还原成可直接插入的具体切片。
+func decodePostgresBackupRows(ctx context.Context, sch *schema.Schema, modelType reflect.Type, rows []postgresBackupRow) (any, error) {
+	fields := backupPersistableFields(sch)
+	slice := reflect.MakeSlice(reflect.SliceOf(modelType), len(rows), len(rows))
+	for i, row := range rows {
+		element := slice.Index(i)
+		for _, field := range fields {
+			raw, ok := row[field.DBName]
+			if !ok {
+				continue
+			}
+			holder := reflect.New(field.FieldType)
+			if err := json.Unmarshal(raw, holder.Interface()); err != nil {
+				return nil, fmt.Errorf("列 %s: %w", field.DBName, err)
+			}
+			if err := field.Set(ctx, element, holder.Elem().Interface()); err != nil {
+				return nil, fmt.Errorf("列 %s: %w", field.DBName, err)
+			}
+		}
+	}
+	return slice.Interface(), nil
+}
+
+// restorePostgresBackup 用逻辑备份重建全库。
+func (b *BackupService) restorePostgresBackup(ctx context.Context, src string) error {
+	file, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+	zr, err := gzip.NewReader(file)
+	if err != nil {
+		return fmt.Errorf("备份文件不是有效的 gzip: %w", err)
+	}
+	defer zr.Close()
+
+	dec := json.NewDecoder(zr)
+	var header postgresBackupHeader
+	if err := dec.Decode(&header); err != nil {
+		return fmt.Errorf("备份头损坏: %w", err)
+	}
+	if header.Format != postgresBackupFormat || header.Version != postgresBackupVersion {
+		return fmt.Errorf("不支持的备份格式 %q (v%d)", header.Format, header.Version)
+	}
+	schemas, modelTypes, err := postgresBackupModelSchemas(b.db)
+	if err != nil {
+		return err
+	}
+
+	// 恢复必须在单个事务里完成：清空成功后中途失败若不回滚，库就空了。
+	return b.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 逆序清空，保证 library_roots → libraries 这类外键先删子表。
+		models := model.AllModels()
+		for i := len(models) - 1; i >= 0; i-- {
+			m := models[i]
+			if !tx.Migrator().HasTable(m) {
+				continue
+			}
+			if err := tx.Session(&gorm.Session{AllowGlobalUpdate: true}).Unscoped().Delete(m).Error; err != nil {
+				return fmt.Errorf("清空表失败: %w", err)
+			}
+		}
+		for {
+			var chunk postgresBackupChunk
+			decodeErr := dec.Decode(&chunk)
+			if errors.Is(decodeErr, io.EOF) {
+				return nil
+			}
+			if decodeErr != nil {
+				return fmt.Errorf("备份文件损坏: %w", decodeErr)
+			}
+			sch, ok := schemas[chunk.Table]
+			if !ok {
+				return fmt.Errorf("备份包含未知表 %s，可能来自不兼容的版本", chunk.Table)
+			}
+			if len(chunk.Rows) == 0 {
+				continue
+			}
+			rows, err := decodePostgresBackupRows(ctx, sch, modelTypes[chunk.Table], chunk.Rows)
+			if err != nil {
+				return fmt.Errorf("表 %s 解码失败: %w", chunk.Table, err)
+			}
+			if err := tx.Unscoped().CreateInBatches(rows, backupRestoreBatchSize).Error; err != nil {
+				return fmt.Errorf("恢复表 %s 失败: %w", chunk.Table, err)
+			}
+		}
+	})
+}

internal/service/backup_postgres_test.go

@@ -0,0 +1,226 @@
+package service
+
+import (
+	"compress/gzip"
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+func newBackupTestService(t *testing.T) (*BackupService, *config.Config) {
+	t.Helper()
+	cfg := &config.Config{}
+	cfg.App.DataDir = t.TempDir()
+	db := newServiceTestDB(t)
+	svc := &BackupService{cfg: cfg, log: zap.NewNop(), db: db}
+	// Create 会先建目录；直接调各方言的 create* 助手时需要它已存在。
+	if err := os.MkdirAll(svc.backupDir(), 0o750); err != nil {
+		t.Fatal(err)
+	}
+	return svc, cfg
+}
+
+// TestPostgresLogicalBackupRoundTrip 验证「备份 → 改库 → 恢复」后整库回到备份时的
+// 样子，包括软删除行与 json:"-" 的列。
+//
+// 逻辑备份/恢复本身是方言无关的 GORM 代码（PostgreSQL 专有的只有文件后缀与
+// isPostgres() 分派），所以可以直接在 SQLite 上跑。
+func TestPostgresLogicalBackupRoundTrip(t *testing.T) {
+	svc, _ := newBackupTestService(t)
+	ctx := context.Background()
+	db := svc.db
+
+	lib := model.Library{Base: model.Base{ID: "lib-1"}, Name: "Movies", Path: "/media/movies", Type: "movie", Enabled: true}
+	if err := db.Create(&lib).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.LibraryRoot{Base: model.Base{ID: "root-1"}, LibraryID: lib.ID, Path: "/media/movies"}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.Media{Base: model.Base{ID: "m-keep"}, LibraryID: lib.ID, Title: "Keep", Path: "/media/movies/keep.mkv"}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.Media{Base: model.Base{ID: "m-gone"}, LibraryID: lib.ID, Title: "Gone", Path: "/media/movies/gone.mkv"}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Delete(&model.Media{}, "id = ?", "m-gone").Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.Setting{Key: "k", Value: "v"}).Error; err != nil {
+		t.Fatal(err)
+	}
+	// 下面这些列都带 json:"-"：走结构体自带的 JSON 序列化会被整列丢掉，
+	// 恢复之后用户权限、置顶库、加密后的密钥会一起消失。
+	user := model.User{
+		Base:                 model.Base{ID: "u-1"},
+		Username:             "alice",
+		PasswordHash:         "hash",
+		Role:                 "user",
+		AllowedLibraryIDs:    `["lib-1"]`,
+		PinnedLibraryIDs:     `["lib-1"]`,
+		HideAdult:            true,
+		IsActive:             true,
+		DanmakuEnabled:       true,
+		PlayerVr360GuideSeen: true,
+	}
+	if err := db.Create(&user).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.APIConfig{Base: model.Base{ID: "cfg-1"}, Provider: "tmdb", APIKey: "ciphertext", Enabled: true}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	dump, err := svc.createPostgresBackup(ctx, "20260101_000000")
+	if err != nil {
+		t.Fatalf("createPostgresBackup: %v", err)
+	}
+	if dump == "" {
+		t.Fatal("createPostgresBackup returned an empty path")
+	}
+
+	// 破坏当前数据：加一条备份里没有的、硬删一条备份里有的。
+	if err := db.Create(&model.Media{Base: model.Base{ID: "m-extra"}, LibraryID: lib.ID, Title: "Extra", Path: "/media/movies/extra.mkv"}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Unscoped().Delete(&model.Media{}, "id = ?", "m-keep").Error; err != nil {
+		t.Fatal(err)
+	}
+
+	if err := svc.restorePostgresBackup(ctx, dump); err != nil {
+		t.Fatalf("restorePostgresBackup: %v", err)
+	}
+
+	var ids []string
+	if err := db.Unscoped().Model(&model.Media{}).Order("id asc").Pluck("id", &ids).Error; err != nil {
+		t.Fatal(err)
+	}
+	if want := []string{"m-gone", "m-keep"}; !reflect.DeepEqual(ids, want) {
+		t.Fatalf("media ids after restore = %v, want %v", ids, want)
+	}
+
+	// 软删除状态必须原样还原，而不是被「复活」。
+	var gone model.Media
+	if err := db.Unscoped().First(&gone, "id = ?", "m-gone").Error; err != nil {
+		t.Fatal(err)
+	}
+	if !gone.DeletedAt.Valid {
+		t.Fatal("soft-deleted media was revived by restore")
+	}
+	var live int64
+	if err := db.Model(&model.Media{}).Where("id = ?", "m-keep").Count(&live).Error; err != nil {
+		t.Fatal(err)
+	}
+	if live != 1 {
+		t.Fatalf("live media count = %d, want 1", live)
+	}
+
+	var value string
+	if err := db.Model(&model.Setting{}).Where("key = ?", "k").Select("value").Scan(&value).Error; err != nil {
+		t.Fatal(err)
+	}
+	if value != "v" {
+		t.Fatalf("setting value = %q, want v", value)
+	}
+	var libCount int64
+	if err := db.Model(&model.Library{}).Count(&libCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if libCount != 1 {
+		t.Fatalf("library count = %d, want 1", libCount)
+	}
+	var rootCount int64
+	if err := db.Model(&model.LibraryRoot{}).Count(&rootCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if rootCount != 1 {
+		t.Fatalf("library root count = %d, want 1", rootCount)
+	}
+
+	// json:"-" 的列必须同样被备份：它们是权限与凭据，丢了比丢一条媒体严重得多。
+	var restoredUser model.User
+	if err := db.First(&restoredUser, "id = ?", "u-1").Error; err != nil {
+		t.Fatal(err)
+	}
+	if restoredUser.PasswordHash != "hash" {
+		t.Fatalf("password hash = %q, want hash", restoredUser.PasswordHash)
+	}
+	if restoredUser.AllowedLibraryIDs != `["lib-1"]` {
+		t.Fatalf(`allowed library ids = %q, want ["lib-1"]`, restoredUser.AllowedLibraryIDs)
+	}
+	if restoredUser.PinnedLibraryIDs != `["lib-1"]` {
+		t.Fatalf(`pinned library ids = %q, want ["lib-1"]`, restoredUser.PinnedLibraryIDs)
+	}
+	if !restoredUser.HideAdult || !restoredUser.IsActive || !restoredUser.DanmakuEnabled || !restoredUser.PlayerVr360GuideSeen {
+		t.Fatalf("boolean columns lost: %+v", restoredUser)
+	}
+
+	var restoredConfig model.APIConfig
+	if err := db.First(&restoredConfig, "id = ?", "cfg-1").Error; err != nil {
+		t.Fatal(err)
+	}
+	if restoredConfig.APIKey != "ciphertext" {
+		t.Fatalf("api key = %q, want ciphertext", restoredConfig.APIKey)
+	}
+}
+
+// TestRestorePostgresBackupKeepsDataOnCorruptFile 验证损坏的备份不会在回滚后留下
+// 半清空的库：恢复是先清空再插入，必须整体在一个事务里，否则中途失败就把库清掉了。
+func TestRestorePostgresBackupKeepsDataOnCorruptFile(t *testing.T) {
+	svc, _ := newBackupTestService(t)
+	ctx := context.Background()
+	if err := svc.db.Create(&model.Setting{Key: "keep", Value: "me"}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	corrupt := filepath.Join(t.TempDir(), "broken.json.gz")
+	file, err := os.Create(corrupt)
+	if err != nil {
+		t.Fatal(err)
+	}
+	zw := gzip.NewWriter(file)
+	// 头部完整、正文半截：解码在清空表之后才会失败。
+	if _, err := zw.Write([]byte(
+		`{"format":"mebox-postgres-logical","version":1,"created_at":"2026-01-01T00:00:00Z"}` + "\n" +
+			`{"table":"media","rows":[`)); err != nil {
+		t.Fatal(err)
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := file.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := svc.restorePostgresBackup(ctx, corrupt); err == nil {
+		t.Fatal("corrupt backup should fail to restore")
+	}
+
+	var value string
+	if err := svc.db.Model(&model.Setting{}).Where("key = ?", "keep").Select("value").Scan(&value).Error; err != nil {
+		t.Fatal(err)
+	}
+	if value != "me" {
+		t.Fatalf("a failed restore wiped the database: settings keep = %q", value)
+	}
+}
+
+// TestRestoreRejectsBackupFromOtherDialect 验证备份文件与当前方言不匹配时给出明确
+// 错误，而不是把 SQLite 文件写到 PostgreSQL 部署的库路径上（那是原实现的隐患）。
+func TestRestoreRejectsBackupFromOtherDialect(t *testing.T) {
+	svc, _ := newBackupTestService(t)
+	pgStyle := filepath.Join(svc.backupDir(), "mebox_20260101_000000.json.gz")
+	if err := os.WriteFile(pgStyle, []byte("not-gzip"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// SQLite 路径下不允许恢复 PostgreSQL 逻辑备份。
+	if err := svc.Restore(context.Background(), filepath.Base(pgStyle)); err == nil {
+		t.Fatal("SQLite restore accepted a PostgreSQL logical backup")
+	}
+}

internal/service/emby_episodic_path_test.go

@@ -0,0 +1,82 @@
+package service
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/truewhile/MeBox/internal/model"
+)
+
+// TestLikelyEpisodicPathSQLNormalisesSeparator 守住剧集路径判定的转义差异。
+//
+// 此前 embyLikelyEpisodicPathSQL 会额外生成一份反斜杠模式
+// （strings.ReplaceAll(pattern, "/", `\`)）。PostgreSQL 的 LIKE 默认就把反斜杠
+// 当转义符，模式结尾的 `\%` 被解析成「字面百分号」而不是「反斜杠 + 通配符」，
+// 那些模式在 PostgreSQL 下永不命中；SQLite 没有默认转义符所以一直正常。
+// 现在统一在 SQL 里把分隔符归一化成 '/'，模式本身不再含反斜杠。
+func TestLikelyEpisodicPathSQLNormalisesSeparator(t *testing.T) {
+	clause, args := embyLikelyEpisodicPathSQL()
+	if !strings.Contains(clause, "REPLACE(media.path") {
+		t.Fatalf("clause no longer normalises the path separator:\n%s", clause)
+	}
+	if got := strings.Count(clause, "LIKE ?"); got != len(args) {
+		t.Fatalf("clause has %d placeholders but %d args:\n%s", got, len(args), clause)
+	}
+	for _, arg := range args {
+		pattern, ok := arg.(string)
+		if !ok {
+			t.Fatalf("unexpected pattern type %T", arg)
+		}
+		if strings.Contains(pattern, `\`) {
+			t.Fatalf("pattern %q still contains a backslash; PostgreSQL's LIKE would treat it as an escape character", pattern)
+		}
+		if !strings.Contains(pattern, "/") {
+			t.Fatalf("pattern %q lost its separator", pattern)
+		}
+	}
+}
+
+// TestFilterLikelyEpisodicPathsHandlesWindowsStylePaths 验证反斜杠路径（Windows
+// 宿主机入库的媒体）仍然被判成剧集并从电影库查询里排除。
+func TestFilterLikelyEpisodicPathsHandlesWindowsStylePaths(t *testing.T) {
+	db := newServiceTestDB(t)
+	episodic := model.Media{
+		Base:       model.Base{ID: "ep-1"},
+		Path:       `D:\Media\国产剧\我的剧\Season 1\我的剧 - S01E01.mkv`,
+		SeasonNum:  1,
+		EpisodeNum: 1,
+	}
+	movie := model.Media{
+		Base: model.Base{ID: "mv-1"},
+		Path: `D:\Media\电影\某电影\某电影.mkv`,
+	}
+	if err := db.Create(&episodic).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&movie).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	q := filterLikelyEpisodicPathsFromMovieQuery(
+		db.Model(&model.Media{}).Where("season_num > 0 OR episode_num > 0"),
+	)
+	var rows []model.Media
+	if err := q.Find(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 0 {
+		t.Fatalf("windows-style episodic path was not excluded, got %d rows", len(rows))
+	}
+
+	// 反证：电影类型的行必须保留。
+	var kept []model.Media
+	keepQ := filterLikelyEpisodicPathsFromMovieQuery(
+		db.Model(&model.Media{}).Where("path LIKE ?", `D:\Media\电影\%`),
+	)
+	if err := keepQ.Find(&kept).Error; err != nil {
+		t.Fatal(err)
+	}
+	if len(kept) != 1 || kept[0].ID != "mv-1" {
+		t.Fatalf("plain movie row was dropped from the movie query: %+v", kept)
+	}
+}

internal/service/emby_items_list.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
 )
 
 func (e *EmbyService) mediaItems(ctx context.Context, p ItemsParams) (map[string]any, error) {
@@ -21,7 +22,11 @@ func (e *EmbyService) mediaItems(ctx context.Context, p ItemsParams) (map[string
 		q = q.Where("library_id IN ? OR series_id = ?", e.mergedLibraryIDs(ctx, p.ParentID), p.ParentID)
 	}
 	if p.SearchTerm != "" {
-		q = q.Where("title LIKE ? OR original_name LIKE ?", "%"+p.SearchTerm+"%", "%"+p.SearchTerm+"%")
+		// ILIKE（PostgreSQL）/ LIKE（SQLite）由方言决定，避免换库后搜索词
+		// 大小写不匹配就搜不到结果。
+		likeOp := repository.LikeOperator(e.repo.DB)
+		term := "%" + p.SearchTerm + "%"
+		q = q.Where("title "+likeOp+" ? OR original_name "+likeOp+" ?", term, term)
 	}
 	if containsEmbyFilter(p.Filters, "IsFavorite") {
 		if strings.TrimSpace(p.UserID) == "" {
@@ -264,7 +269,11 @@ func (e *EmbyService) seriesItemsForLibrary(ctx context.Context, libraryID strin
 		q = q.Where("library_id IN ?", e.mergedLibraryIDs(ctx, libraryID))
 	}
 	if p.SearchTerm != "" {
-		q = q.Where("title LIKE ? OR original_name LIKE ?", "%"+p.SearchTerm+"%", "%"+p.SearchTerm+"%")
+		// ILIKE（PostgreSQL）/ LIKE（SQLite）由方言决定，避免换库后搜索词
+		// 大小写不匹配就搜不到结果。
+		likeOp := repository.LikeOperator(e.repo.DB)
+		term := "%" + p.SearchTerm + "%"
+		q = q.Where("title "+likeOp+" ? OR original_name "+likeOp+" ?", term, term)
 	}
 	if containsEmbyFilter(p.Filters, "IsFavorite") {
 		if strings.TrimSpace(p.UserID) == "" {

internal/service/emby_movie_items.go

@@ -9,6 +9,7 @@ import (
 	"gorm.io/gorm"
 
 	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
 )
 
 // movieLibraryHasEpisodicContent 报告电影类型库里是否混入了「剧集结构」内容
@@ -51,7 +52,11 @@ func (e *EmbyService) movieLibraryItems(ctx context.Context, p ItemsParams) (map
 		q = e.applyUserMediaVisibility(ctx, q, p.UserID)
 		q = q.Where("library_id IN ?", libIDs)
 		if p.SearchTerm != "" {
-			q = q.Where("title LIKE ? OR original_name LIKE ?", "%"+p.SearchTerm+"%", "%"+p.SearchTerm+"%")
+			// 方言相关的 ILIKE/LIKE：PostgreSQL 的 LIKE 区分大小写，
+			// 直接用 LIKE 会让客户端搜索的大小写与入库标题不一致时搜不到。
+			likeOp := repository.LikeOperator(e.repo.DB)
+			term := "%" + p.SearchTerm + "%"
+			q = q.Where("title "+likeOp+" ? OR original_name "+likeOp+" ?", term, term)
 		}
 		if containsEmbyFilter(p.Filters, "IsFavorite") {
 			if strings.TrimSpace(p.UserID) == "" {
@@ -266,6 +271,14 @@ func filterLikelyEpisodicPathsFromMovieQuery(q *gorm.DB) *gorm.DB {
 	return q.Where("NOT ((media.season_num > 0 OR media.episode_num > 0) AND ("+clause+"))", args...)
 }
 
+// embyEpisodicPathExpr 把路径分隔符归一化成 '/' 后再小写化，供剧集路径判定使用。
+//
+// 反斜杠归一化必须放在 SQL 里做，而不是再生成一份反斜杠模式：PostgreSQL 的
+// LIKE 默认就把反斜杠当转义符，模式结尾的 `\%` 会被解析成「字面百分号」而不是
+// 「反斜杠 + 通配符」，那些模式在 PostgreSQL 下永不命中（SQLite 没有默认转义符，
+// 所以只有换库之后才会暴露）。归一化列值后两种方言结果一致。
+const embyEpisodicPathExpr = `LOWER(REPLACE(media.path, '\', '/'))`
+
 func embyLikelyEpisodicPathSQL() (string, []any) {
 	patterns := []string{
 		"%/season %/%", "%/season.%/%", "%/season-%/%", "%/season_%/%",
@@ -274,15 +287,11 @@ func embyLikelyEpisodicPathSQL() (string, []any) {
 		"%/电视剧/%", "%/剧集/%", "%/连续剧/%", "%/短剧/%", "%/国产剧/%", "%/国剧/%", "%/大陆剧/%", "%/华语剧/%", "%/国产电视剧/%", "%/大陆电视剧/%", "%/华语电视剧/%", "%/欧美剧/%", "%/欧美电视剧/%", "%/美剧/%", "%/英剧/%", "%/日韩剧/%", "%/日韩电视剧/%", "%/日剧/%", "%/韩剧/%", "%/港剧/%", "%/台剧/%", "%/港台剧/%", "%/泰剧/%",
 		"%/日番/%", "%/国漫/%", "%/番剧/%", "%/动漫/%", "%/特别篇/%", "%/特別篇/%", "%/番外/%", "%/特典/%",
 	}
-	clauses := make([]string, 0, len(patterns)*2)
-	args := make([]any, 0, len(patterns)*2)
+	clauses := make([]string, 0, len(patterns))
+	args := make([]any, 0, len(patterns))
 	for _, pattern := range patterns {
-		clauses = append(clauses, "LOWER(media.path) LIKE ?")
+		clauses = append(clauses, embyEpisodicPathExpr+" LIKE ?")
 		args = append(args, pattern)
-		if strings.Contains(pattern, "/") {
-			clauses = append(clauses, "LOWER(media.path) LIKE ?")
-			args = append(args, strings.ReplaceAll(pattern, "/", `\`))
-		}
 	}
 	return strings.Join(clauses, " OR "), args
 }

internal/service/emby_remote.go

@@ -1587,7 +1587,22 @@ func (r *EmbyRemoteService) proxyVideoStreamOnLine(ctx context.Context, w http.R
 	defer resp.Body.Close()
 	if resp.StatusCode >= 400 {
 		data, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
-		return redactSensitiveError(fmt.Errorf("远程 Emby 视频流失败(%d): %s", resp.StatusCode, strings.TrimSpace(string(data))))
+		detail := strings.TrimSpace(string(data))
+		// 远程 Emby 对「整部剧/目录」这类自身没有媒体源的条目会直接 500，正文是
+		// 一句 .NET 异常（如 Unable to cast object of type 'Series' to type
+		// 'IHasMediaSources'）。原样丢给用户没人看得懂，也没有排查线索——细节进日志，
+		// 给用户一句能照着做的提示。
+		if r.log != nil {
+			r.log.Warn("remote emby video stream rejected",
+				zap.String("remote_id", remoteID),
+				zap.Int("status", resp.StatusCode),
+				zap.String("detail", detail),
+			)
+		}
+		if resp.StatusCode >= 500 {
+			return redactSensitiveError(fmt.Errorf("远程 Emby 无法播放该条目（HTTP %d）：请在详情页选择具体集数后重试", resp.StatusCode))
+		}
+		return redactSensitiveError(fmt.Errorf("远程 Emby 视频流失败(%d): %s", resp.StatusCode, detail))
 	}
 	for _, header := range []string{"Content-Type", "Content-Length", "Content-Range", "Accept-Ranges", "ETag", "Cache-Control"} {
 		if value := resp.Header.Get(header); value != "" {

internal/service/emby_remote_playable_id_test.go

@@ -0,0 +1,160 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"sync/atomic"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/truewhile/MeBox/internal/config"
+	"github.com/truewhile/MeBox/internal/model"
+	"github.com/truewhile/MeBox/internal/repository"
+)
+
+// newPlayableIDTestService 起一个假的远程 Emby，并建好账号。
+func newPlayableIDTestService(t *testing.T, handler http.Handler) (*EmbyRemoteService, *model.StrmAccount) {
+	t.Helper()
+	server := httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+
+	db := newServiceTestDB(t, &model.StrmAccount{}, &model.EmbyMount{})
+	repos := repository.New(db)
+	cfg := &config.Config{}
+	remote := NewEmbyRemoteService(cfg, zap.NewNop(), repos, NewCryptoService("", zap.NewNop()))
+	remote.SetRuntimeCache(NewRuntimeCacheService(cfg, zap.NewNop()))
+
+	rawConfig, _ := json.Marshal(map[string]string{
+		"url":            server.URL,
+		"api_key":        "test-api-key",
+		"remote_user_id": "uid-1",
+	})
+	acct := &model.StrmAccount{
+		Base:     model.Base{ID: "acct-1"},
+		Name:     "远程 Emby",
+		Provider: model.StrmProviderEmbyRemote,
+		Config:   string(rawConfig),
+		Enabled:  true,
+	}
+	if err := repos.StrmAccount.Create(t.Context(), acct); err != nil {
+		t.Fatalf("create account: %v", err)
+	}
+	return remote, acct
+}
+
+func playableIDTestEpisode(id string, index, sources int) map[string]any {
+	item := map[string]any{
+		"Id":                id,
+		"Name":              "第" + strconv.Itoa(index) + "集",
+		"Type":              "Episode",
+		"SeriesId":          "series-100",
+		"ParentIndexNumber": 1,
+		"IndexNumber":       index,
+	}
+	if sources > 0 {
+		item["MediaSources"] = []any{map[string]any{"Id": id + "-source"}}
+	}
+	return item
+}
+
+// 整部剧的 ID 自身没有媒体源，远程 Emby 对它的取流请求会回 500
+// （Unable to cast 'Series' to 'IHasMediaSources'）。这条用例保证我们会换成第一集，
+// 而不是把这种 ID 直接交给远程。
+func TestPlayableRemoteIDResolvesContainerToFirstEpisode(t *testing.T) {
+	var itemsCalls int64
+	remote, acct := newPlayableIDTestService(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/emby/Users/uid-1/Items/series-100":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"Id": "series-100", "Name": "剧一", "Type": "Series", "IsFolder": true,
+			})
+		case "/emby/Users/uid-1/Items/ep-2":
+			_ = json.NewEncoder(w).Encode(playableIDTestEpisode("ep-2", 2, 1))
+		case "/emby/Users/uid-1/Items":
+			atomic.AddInt64(&itemsCalls, 1)
+			if got := r.URL.Query().Get("ParentId"); got != "series-100" {
+				t.Errorf("ParentId = %q, want series-100", got)
+			}
+			// 故意乱序，并让第一条没有媒体源：只有真按季/集排序、且检查过媒体源，
+			// 才会选中 ep-1。
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"Items": []map[string]any{
+					{"Id": "season-1", "Type": "Season", "IndexNumber": 1},
+					playableIDTestEpisode("ep-3", 3, 1),
+					playableIDTestEpisode("ep-1", 1, 1),
+					playableIDTestEpisode("ep-2", 2, 1),
+				},
+			})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+
+	ctx := context.Background()
+	if got := remote.PlayableRemoteID(ctx, acct, "series-100"); got != "ep-1" {
+		t.Fatalf("series id resolved to %q, want ep-1", got)
+	}
+	// 播放器对同一个地址会反复发 Range 请求，解析结果必须命中缓存，不再打远程。
+	if got := remote.PlayableRemoteID(ctx, acct, "series-100"); got != "ep-1" {
+		t.Fatalf("cached resolve = %q, want ep-1", got)
+	}
+	if n := atomic.LoadInt64(&itemsCalls); n != 1 {
+		t.Fatalf("episode query issued %d times, want 1 (cached)", n)
+	}
+}
+
+// 本身带媒体源的条目（电影/单集）必须原样返回，不能被改写。
+func TestPlayableRemoteIDKeepsPlayableItem(t *testing.T) {
+	var queries int64
+	remote, acct := newPlayableIDTestService(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt64(&queries, 1)
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path != "/emby/Users/uid-1/Items/ep-2" {
+			t.Errorf("unexpected upstream path %s", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(playableIDTestEpisode("ep-2", 2, 1))
+	}))
+
+	if got := remote.PlayableRemoteID(context.Background(), acct, "ep-2"); got != "ep-2" {
+		t.Fatalf("playable item = %q, want ep-2", got)
+	}
+	if n := atomic.LoadInt64(&queries); n != 1 {
+		t.Fatalf("upstream queries = %d, want 1", n)
+	}
+}
+
+// 远程不可用/查不到条目时保持原 ID：让原有流程去报错，别把播放地址改成空。
+func TestPlayableRemoteIDKeepsOriginalOnFailure(t *testing.T) {
+	remote, acct := newPlayableIDTestService(t, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+
+	if got := remote.PlayableRemoteID(context.Background(), acct, "series-100"); got != "series-100" {
+		t.Fatalf("failure path = %q, want the original id", got)
+	}
+}
+
+// 容器下没有任何带媒体源的子条目时同样返回原 ID（下一层会给友好报错）。
+func TestPlayableRemoteIDKeepsContainerWithoutPlayableChild(t *testing.T) {
+	remote, acct := newPlayableIDTestService(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path == "/emby/Users/uid-1/Items" {
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"Items": []map[string]any{
+					{"Id": "season-1", "Type": "Season", "IndexNumber": 1},
+				},
+			})
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"Id": "series-100", "Type": "Series", "IsFolder": true})
+	}))
+
+	if got := remote.PlayableRemoteID(context.Background(), acct, "series-100"); got != "series-100" {
+		t.Fatalf("container without playable child = %q, want the original id", got)
+	}
+}

internal/service/emby_remote_stream_proxy_test.go

@@ -0,0 +1,84 @@
+package service
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+// 远程条目自身没有媒体源时（例如把「整部剧」的 ID 当播放目标），远程 Emby 会回
+// 500 + 一句 .NET 异常。异常原文不能直接丢给用户，但要能从日志里查得到。
+func TestProxyVideoStreamOnLineHidesUpstreamException(t *testing.T) {
+	const upstreamBody = "Unable to cast object of type 'MediaBrowser.Controller.Entities.TV.Series' to type 'MediaBrowser.Controller.Entities.IHasMediaSources'."
+
+	var gotPath, gotStatic, gotRange, gotToken string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		gotPath = req.URL.Path
+		gotStatic = req.URL.Query().Get("Static")
+		gotRange = req.Header.Get("Range")
+		gotToken = req.Header.Get("X-Emby-Token")
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte(upstreamBody))
+	}))
+	defer upstream.Close()
+
+	svc := &EmbyRemoteService{stream: upstream.Client(), log: zap.NewNop()}
+	cfg := &EmbyRemoteConfig{BaseURL: upstream.URL, Token: "tok-1"}
+
+	req := httptest.NewRequest(http.MethodGet, "/api/stream/embyremote~acct~222679", nil)
+	req.Header.Set("Range", "bytes=0-1023")
+	rec := httptest.NewRecorder()
+
+	err := svc.proxyVideoStreamOnLine(context.Background(), rec, req, cfg, "222679")
+	if err == nil {
+		t.Fatal("expected an error for upstream 500")
+	}
+	if gotPath != "/emby/Videos/222679/stream" {
+		t.Fatalf("upstream path = %q", gotPath)
+	}
+	if gotStatic != "true" {
+		t.Fatalf("Static = %q, want true", gotStatic)
+	}
+	if gotRange != "bytes=0-1023" {
+		t.Fatalf("Range = %q, want forwarded range", gotRange)
+	}
+	if gotToken != "tok-1" {
+		t.Fatalf("X-Emby-Token = %q", gotToken)
+	}
+	if rec.Body.Len() != 0 {
+		t.Fatalf("nothing should be written to the client on upstream failure, got %q", rec.Body.String())
+	}
+
+	msg := err.Error()
+	if strings.Contains(msg, "Unable to cast") || strings.Contains(msg, "MediaBrowser") {
+		t.Fatalf("raw upstream exception must not leak to clients: %q", msg)
+	}
+	if !strings.Contains(msg, "无法播放该条目") {
+		t.Fatalf("error should tell the user what to do, got %q", msg)
+	}
+}
+
+// 4xx（例如远程条目被删除/无权限）保持原有措辞，带着上游说明便于排查。
+func TestProxyVideoStreamOnLineKeepsClientErrorDetail(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+		_, _ = w.Write([]byte("Item not found"))
+	}))
+	defer upstream.Close()
+
+	svc := &EmbyRemoteService{stream: upstream.Client(), log: zap.NewNop()}
+	cfg := &EmbyRemoteConfig{BaseURL: upstream.URL, Token: "tok-1"}
+
+	req := httptest.NewRequest(http.MethodGet, "/api/stream/embyremote~acct~404", nil)
+	err := svc.proxyVideoStreamOnLine(context.Background(), httptest.NewRecorder(), req, cfg, "404")
+	if err == nil {
+		t.Fatal("expected an error for upstream 404")
+	}
+	if !strings.Contains(err.Error(), "404") || !strings.Contains(err.Error(), "Item not found") {
+		t.Fatalf("client error detail should be kept, got %q", err.Error())
+	}
+}

internal/service/emby_remote_web.go

@@ -820,6 +820,123 @@ func (r *EmbyRemoteService) remoteItemSeriesID(ctx context.Context, acct *model.
 	return remoteItemString(out, "SeriesId")
 }
 
+// PlayableRemoteID 把「自身没有媒体源」的远程条目换成可直接播放的条目 ID。
+//
+// 远程 Emby 只为带媒体源的条目提供 /Videos/{id}/stream：拿整部剧/季/目录的 ID 去
+// 请求，它会回 500 加一句 .NET 异常（Unable to cast object of type 'Series' to
+// type 'IHasMediaSources'）。首页轮播、剧集库卡片、外部播放器与第三方客户端都可能
+// 把这种 ID 交过来，统一在这里回落到第一集，保证拿到的 ID 真能取到流。
+//
+// 条目本身可播、或解析失败时返回原 ID（调用方拿到后用原逻辑处理即可，无需区分错误）。
+func (r *EmbyRemoteService) PlayableRemoteID(ctx context.Context, acct *model.StrmAccount, remoteID string) string {
+	remoteID = strings.TrimSpace(remoteID)
+	if r == nil || acct == nil || remoteID == "" {
+		return remoteID
+	}
+	cfg, err := r.remoteConfigWithToken(ctx, acct)
+	if err != nil {
+		return remoteID
+	}
+	cacheKey := r.remoteCacheKey("playable-remote-id", acct.ID, remoteID)
+	if r.cache != nil {
+		var cached string
+		// 播放器会对同一个地址发很多次 Range 请求，判定结果必须走缓存，否则每次拖动
+		// 进度条都要多打两次远程 Emby。缓存比常规媒体缓存长：条目可播性是静态属性。
+		if r.cache.GetJSON(ctx, cacheKey, &cached) {
+			if cached == "" {
+				return remoteID
+			}
+			return cached
+		}
+	}
+	resolved := r.resolvePlayableRemoteID(ctx, acct, cfg, remoteID)
+	// 解析失败不写缓存：远程抖动时下次照样重试，而不是把「播不了」记住十分钟。
+	if r.cache != nil && resolved != "" {
+		r.cache.SetJSON(ctx, cacheKey, resolved, playableRemoteIDCacheTTL)
+	}
+	if resolved == "" {
+		return remoteID
+	}
+	return resolved
+}
+
+// playableRemoteIDCacheTTL 是「条目可播性」判定的缓存时长。
+const playableRemoteIDCacheTTL = 10 * time.Minute
+
+// resolvePlayableRemoteID 返回 remoteID 对应的可播条目：本身带媒体源时原样返回，
+// 容器条目（整部剧/季/目录）返回排在最前的、确实带媒体源的子条目。
+func (r *EmbyRemoteService) resolvePlayableRemoteID(ctx context.Context, acct *model.StrmAccount, cfg *EmbyRemoteConfig, remoteID string) string {
+	var item map[string]any
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items/"+url.PathEscape(remoteID), nil, &item); err != nil {
+		return ""
+	}
+	if remoteItemHasMediaSources(item) || !remoteItemIsContainer(item) {
+		return remoteID
+	}
+
+	q := url.Values{}
+	q.Set("ParentId", remoteID)
+	q.Set("Recursive", "true")
+	q.Set("IncludeItemTypes", "Episode,Movie,Video")
+	q.Set("Fields", "MediaSources")
+	q.Set("SortBy", "ParentIndexNumber,IndexNumber,SortName")
+	q.Set("Limit", "50")
+	var body struct {
+		Items []map[string]any `json:"Items"`
+	}
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items", q, &body); err != nil {
+		return ""
+	}
+
+	// 远程 SortBy 只覆盖它认识的字段（不同 Emby/Jellyfin 版本支持度不一），
+	// 这里再按季/集排一次，确保拿到的是第一集而不是服务端返回顺序里的第一条。
+	children := body.Items
+	sort.SliceStable(children, func(i, j int) bool {
+		if a, b := remoteItemInt(children[i], "ParentIndexNumber"), remoteItemInt(children[j], "ParentIndexNumber"); a != b {
+			return a < b
+		}
+		if a, b := remoteItemInt(children[i], "IndexNumber"), remoteItemInt(children[j], "IndexNumber"); a != b {
+			return a < b
+		}
+		return remoteItemString(children[i], "SortName") < remoteItemString(children[j], "SortName")
+	})
+	for _, child := range children {
+		if id := remoteItemString(child, "Id"); id != "" && remoteItemHasMediaSources(child) {
+			return id
+		}
+	}
+	return ""
+}
+
+// remoteItemHasMediaSources 该条目是否自带媒体源（即能直接取流）。
+func remoteItemHasMediaSources(item map[string]any) bool {
+	if item == nil {
+		return false
+	}
+	switch sources := item["MediaSources"].(type) {
+	case []any:
+		return len(sources) > 0
+	case []map[string]any:
+		return len(sources) > 0
+	}
+	return false
+}
+
+// remoteItemIsContainer 该条目是否是「装别人」的容器：整部剧/季/目录/合集。
+func remoteItemIsContainer(item map[string]any) bool {
+	switch remoteItemString(item, "Type") {
+	case "Series", "Season", "Folder", "BoxSet", "CollectionFolder", "AggregateFolder", "Playlist":
+		return true
+	}
+	// 类型缺失时退回 IsFolder（Emby 的目录类条目都会带）。
+	if _, ok := item["Type"]; !ok {
+		if isFolder, okBool := item["IsFolder"].(bool); okBool {
+			return isFolder
+		}
+	}
+	return false
+}
+
 // ─── 远程 item JSON 取值辅助 ────────────────────────────────────────────────
 
 func anyString(v any) string {

internal/service/local_availability.go

@@ -50,9 +50,12 @@ func LookupLocalAvailability(ctx context.Context, repo *repository.Container, ti
 		return out
 	}
 	like := "%" + query + "%"
+	// 方言相关的 ILIKE/LIKE：PostgreSQL 下用 LIKE 会因标题大小写与查询不一致而
+	// 漏判「本地已有该剧」，进而反复提示订阅缺失。
+	likeOp := repository.LikeOperator(repo.DB)
 	var rows []model.Media
 	if err := repo.DB.WithContext(ctx).
-		Where("title LIKE ? OR original_name LIKE ? OR path LIKE ?", like, like, like).
+		Where("title "+likeOp+" ? OR original_name "+likeOp+" ? OR path "+likeOp+" ?", like, like, like).
 		Order("season_num asc, episode_num asc, episode_fraction asc, created_at desc").
 		Limit(2000).
 		Find(&rows).Error; err != nil {

internal/service/reader/audio_transcode.go

@@ -39,7 +39,9 @@ const (
 	// audioTranscodeDirName 缓存目录名，位于 cache.cache_dir 之下。
 	audioTranscodeDirName = "reader-audio"
 	// maxAudioTranscodeCacheBytes 转码缓存上限，超出按修改时间淘汰最旧的。
-	maxAudioTranscodeCacheBytes = 4 << 30
+	// 1GB 是权衡：单章语音 96kbps 约 1MB/分钟，一本 10 小时的有声书约 600MB，
+	// 也就是说同时能保住的「最近听过的书」在个位数；超出后旧书再听会重新转码。
+	maxAudioTranscodeCacheBytes = 1 << 30
 	// audioTranscodeKeepRatio 触发淘汰后回落到上限的比例，避免每次写入都淘汰。
 	audioTranscodeKeepRatio = 0.9
 	// maxAudioTranscodeDuration 单章转码超时。
@@ -269,7 +271,7 @@ func (s *ReaderService) transcodeInputHeaders(ctx context.Context, bookID, sourc
 	if err != nil || book == nil || strings.TrimSpace(book.Origin) == "" {
 		return headers
 	}
-	if src, err := s.repo.GetSourceByURL(ctx, book.Origin); err == nil && src != nil && src.Header != "" {
+	if src, err := s.repo.GetSourceAnyByURL(ctx, book.Origin); err == nil && src != nil && src.Header != "" {
 		var extra map[string]any
 		if json.Unmarshal([]byte(src.Header), &extra) == nil {
 			for k, v := range extra {

internal/service/reader/audio_transcode_test.go

@@ -2,6 +2,7 @@ package reader
 
 import (
 	"errors"
+	"fmt"
 	"net/url"
 	"os"
 	"path/filepath"
@@ -255,3 +256,50 @@ func indexOf(items []string, want string) int {
 	}
 	return -1
 }
+
+// 转码缓存上限是 1GB：单章语音约 1MB/分钟（96kbps），
+// 也就是一本 10 小时的有声书约 600MB，同时能保住「最近听过的书」在个位数。
+// 这里把常量与淘汰后的落点一起钉住，防止以后被无意改回大值。
+func TestAudioTranscodeCacheLimitIsOneGiB(t *testing.T) {
+	if maxAudioTranscodeCacheBytes != int64(1)<<30 {
+		t.Fatalf("转码缓存上限应为 1GB，实际 %d 字节", maxAudioTranscodeCacheBytes)
+	}
+	// 淘汰目标是上限的 90%：模拟缓存略超上限时，删掉最旧的若干章回到目标以下。
+	dir := t.TempDir()
+	limit := int64(1000)
+	perFile := int64(120)
+	for i := 0; i < 9; i++ { // 1080 > 1000，超限
+		name := filepath.Join(dir, fmt.Sprintf("ch%02d.mp3", i))
+		if err := os.WriteFile(name, make([]byte, perFile), 0o640); err != nil {
+			t.Fatal(err)
+		}
+		ts := time.Now().Add(-time.Duration(9-i) * time.Minute)
+		if err := os.Chtimes(name, ts, ts); err != nil {
+			t.Fatal(err)
+		}
+	}
+	pruneAudioTranscodeCache(dir, limit)
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var remain int64
+	for _, e := range entries {
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		remain += info.Size()
+	}
+	if remain > limit {
+		t.Fatalf("淘汰后应落回上限内: remain=%d limit=%d", remain, limit)
+	}
+	// 最新的那章必须还在（LRU 先删最旧的）。
+	if _, err := os.Stat(filepath.Join(dir, "ch08.mp3")); err != nil {
+		t.Fatalf("最新一章应保留: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "ch00.mp3")); !os.IsNotExist(err) {
+		t.Fatalf("最旧一章应被删除，err=%v", err)
+	}
+}

internal/service/reader/browser_panel.go

@@ -450,7 +450,7 @@ func (s *ReaderService) requestBrowserResource(ctx context.Context, sourceURL st
 	}
 	// 书源级请求头（含 Referer / UA），与阅读请求保持一致
 	if s.repo != nil {
-		if src, findErr := s.repo.GetSourceByURL(reqCtx, sourceURL); findErr == nil && src != nil && src.Header != "" {
+		if src, findErr := s.repo.GetSourceAnyByURL(reqCtx, sourceURL); findErr == nil && src != nil && src.Header != "" {
 			var headers map[string]any
 			if json.Unmarshal([]byte(src.Header), &headers) == nil {
 				for k, v := range headers {
@@ -557,7 +557,7 @@ func (s *ReaderService) ProxyBrowserXHR(ctx context.Context, id, method, target
 		}
 	}
 	if s.repo != nil {
-		if src, findErr := s.repo.GetSourceByURL(reqCtx, entry.sourceURL); findErr == nil && src != nil && src.Header != "" {
+		if src, findErr := s.repo.GetSourceAnyByURL(reqCtx, entry.sourceURL); findErr == nil && src != nil && src.Header != "" {
 			var extra map[string]any
 			if json.Unmarshal([]byte(src.Header), &extra) == nil {
 				for k, v := range extra {

internal/service/reader/comment.go

@@ -444,7 +444,7 @@ func (s *ReaderService) OpenContentComment(ctx context.Context, userID, bookID,
 		return nil, fmt.Errorf("书籍不存在或已移出书架")
 	}
 	sourceID := ""
-	if src, findErr := s.repo.GetSourceByURL(ctx, book.Origin); findErr == nil && src != nil {
+	if src, findErr := s.repo.GetSourceAnyByURL(ctx, book.Origin); findErr == nil && src != nil {
 		sourceID = src.ID
 	}
 	if strings.TrimSpace(title) == "" {

internal/service/reader/image_decode_test.go

@@ -19,7 +19,7 @@ func TestDecodeImageBytesRunsRuleJS(t *testing.T) {
 		`"ruleContent": {"content": "id.content@textNodes", "imageDecode": "var src = new Uint8Array(result); var out = new Uint8Array(src.length); for (var i=0;i<src.length;i++){ out[i] = src[i] ^ 0x55; } out"}`,
 		1,
 	)
-	if _, err := svc.ImportSources(ctx, raw); err != nil {
+	if _, err := svc.ImportSources(ctx, "u1", raw); err != nil {
 		t.Fatalf("更新书源失败: %v", err)
 	}
 	rule := svc.ImageDecodeRule(ctx, book)
@@ -64,7 +64,7 @@ func TestDecodeImageBytesFallsBackOnBadRule(t *testing.T) {
 		`"ruleContent": {"content": "id.content@textNodes", "imageDecode": "throw new Error('bad rule')"}`,
 		1,
 	)
-	if _, err := svc.ImportSources(ctx, raw); err != nil {
+	if _, err := svc.ImportSources(ctx, "u1", raw); err != nil {
 		t.Fatalf("更新书源失败: %v", err)
 	}
 	data := []byte("still-an-image")
@@ -87,7 +87,7 @@ func TestDecodeCoverBytes(t *testing.T) {
 		`"bookSourceType": 0, "coverDecodeJs": "var src = new Uint8Array(result); var out = new Uint8Array(src.length); for (var i=0;i<src.length;i++){ out[i] = src[i] ^ 0x33; } out",`,
 		1,
 	)
-	if _, err := svc.ImportSources(ctx, raw); err != nil {
+	if _, err := svc.ImportSources(ctx, "u1", raw); err != nil {
 		t.Fatalf("更新书源失败: %v", err)
 	}
 	if !svc.SourceHasCoverDecode(srv.URL) {

internal/service/reader/login.go

@@ -73,7 +73,7 @@ type LoginResult struct {
 
 // GetSourceLogin 返回书源登录界面描述与当前登录状态。
 func (s *ReaderService) GetSourceLogin(ctx context.Context, userID, sourceID string) (*SourceLoginInfo, error) {
-	src, bs, err := s.loadSource(ctx, sourceID)
+	src, bs, err := s.loadSourceForUser(ctx, userID, sourceID)
 	if err != nil {
 		return nil, err
 	}
@@ -142,7 +142,7 @@ func (s *ReaderService) resolveLoginFields(sess *sourceSession, bs *BookSource,
 // fields 为前端提交的表单值，会与已保存的登录信息合并后作为 result 传入。
 // action 为空时执行 loginUrl 里的 login()（即 legado 的「确认登录」）。
 func (s *ReaderService) RunLoginAction(ctx context.Context, userID, sourceID, action string, fields map[string]string) (*LoginResult, error) {
-	src, bs, err := s.loadSource(ctx, sourceID)
+	src, bs, err := s.loadSourceForUser(ctx, userID, sourceID)
 	if err != nil {
 		return nil, err
 	}
@@ -206,11 +206,11 @@ func (s *ReaderService) RunLoginAction(ctx context.Context, userID, sourceID, ac
 
 // SetSourceVariable 覆盖保存书源变量（前端变量编辑器）。
 // 保存后书源 JS 的 getVariable() 即可读到。
-func (s *ReaderService) SetSourceVariable(ctx context.Context, sourceID, variable string) error {
+func (s *ReaderService) SetSourceVariable(ctx context.Context, userID, sourceID, variable string) error {
 	if strings.TrimSpace(variable) != "" && !json.Valid([]byte(variable)) {
 		return fmt.Errorf("变量必须是合法 JSON")
 	}
-	src, bs, err := s.loadSource(ctx, sourceID)
+	src, bs, err := s.loadSourceForUser(ctx, userID, sourceID)
 	if err != nil {
 		return err
 	}
@@ -222,8 +222,8 @@ func (s *ReaderService) SetSourceVariable(ctx context.Context, sourceID, variabl
 }
 
 // SetSourceLoginInfo 直接覆盖保存登录信息（前端表单保存，不触发登录动作）。
-func (s *ReaderService) SetSourceLoginInfo(ctx context.Context, sourceID string, fields map[string]string) error {
-	src, bs, err := s.loadSource(ctx, sourceID)
+func (s *ReaderService) SetSourceLoginInfo(ctx context.Context, userID, sourceID string, fields map[string]string) error {
+	src, bs, err := s.loadSourceForUser(ctx, userID, sourceID)
 	if err != nil {
 		return err
 	}
@@ -239,8 +239,8 @@ func (s *ReaderService) SetSourceLoginInfo(ctx context.Context, sourceID string,
 }
 
 // ClearSourceLogin 清除登录态：登录信息与全部 Cookie（对应 legado logout）。
-func (s *ReaderService) ClearSourceLogin(ctx context.Context, sourceID string) error {
-	src, bs, err := s.loadSource(ctx, sourceID)
+func (s *ReaderService) ClearSourceLogin(ctx context.Context, userID, sourceID string) error {
+	src, bs, err := s.loadSourceForUser(ctx, userID, sourceID)
 	if err != nil {
 		return err
 	}

internal/service/reader/login_test.go

@@ -22,7 +22,7 @@ import (
 // 覆盖「登录 → Cookie 落库 → 后续请求自动携带 Cookie → 登出清理」。
 
 // readerTestUserID 登录接口按用户隔离浏览器待办，测试里统一用一个固定用户。
-const readerTestUserID = "test-user"
+const readerTestUserID = "u1"
 
 // loginTestServer 模拟一个需要登录的书源站点：
 //   - POST /login_api 校验账号密码并下发会话 Cookie
@@ -129,10 +129,10 @@ func newLoginTestService(t *testing.T) (*ReaderService, *repository.Container) {
 // prepareLoginSource 导入测试书源并返回其 ID。
 func prepareLoginSource(t *testing.T, svc *ReaderService, sourceJSON string) string {
 	t.Helper()
-	if _, err := svc.ImportSources(t.Context(), sourceJSON); err != nil {
+	if _, err := svc.ImportSources(t.Context(), "u1", sourceJSON); err != nil {
 		t.Fatal(err)
 	}
-	srcs, err := svc.ListSources(t.Context())
+	srcs, err := svc.ListSources(t.Context(), "u1")
 	if err != nil || len(srcs) == 0 {
 		t.Fatalf("导入后应能读到书源: %v", err)
 	}
@@ -151,14 +151,14 @@ func TestSourceLoginEndToEnd(t *testing.T) {
 	sourceID := prepareLoginSource(t, svc, loginTestSourceJSON(t, srv.URL))
 
 	// ── 登录前：未鉴权，站点返回未登录页 → 搜不到书 ──
-	if books, _, err := svc.Search(ctx, "会员", nil, 1); err != nil {
+	if books, _, err := svc.Search(ctx, "u1", "会员", nil, 1); err != nil {
 		t.Fatal(err)
 	} else if len(books) != 0 {
 		t.Fatalf("未登录时不应搜到结果: %+v", books)
 	}
 
 	// ── 登录 ──
-	res, err := svc.RunLoginAction(ctx, readerTestUserID, sourceID, "", map[string]string{
+	res, err := svc.RunLoginAction(ctx, "u1", sourceID, "", map[string]string{
 		"邮箱": "user@example.com", "密码": "pw123456",
 	})
 	if err != nil {
@@ -176,7 +176,7 @@ func TestSourceLoginEndToEnd(t *testing.T) {
 
 	// ── 登录态应落库（换一个 service 实例仍可读到）──
 	svc2 := NewReaderService(svc.cfg, zap.NewNop(), repos)
-	info, err := svc2.GetSourceLogin(ctx, readerTestUserID, sourceID)
+	info, err := svc2.GetSourceLogin(ctx, "u1", sourceID)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -188,7 +188,7 @@ func TestSourceLoginEndToEnd(t *testing.T) {
 	}
 
 	// ── 登录后搜索：应携带 Cookie 并成功 ──
-	books, skipped, err := svc.Search(ctx, "会员", nil, 1)
+	books, skipped, err := svc.Search(ctx, "u1", "会员", nil, 1)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -200,17 +200,17 @@ func TestSourceLoginEndToEnd(t *testing.T) {
 	}
 
 	// ── 登出：Cookie 清除，搜索重新未登录 ──
-	if err := svc.ClearSourceLogin(ctx, sourceID); err != nil {
+	if err := svc.ClearSourceLogin(ctx, "u1", sourceID); err != nil {
 		t.Fatal(err)
 	}
-	info, err = svc.GetSourceLogin(ctx, readerTestUserID, sourceID)
+	info, err = svc.GetSourceLogin(ctx, "u1", sourceID)
 	if err != nil {
 		t.Fatal(err)
 	}
 	if info.LoggedIn || len(info.Cookies) != 0 {
 		t.Fatalf("登出后不应残留登录态: %+v", info)
 	}
-	if books, _, err := svc.Search(ctx, "会员", nil, 1); err != nil {
+	if books, _, err := svc.Search(ctx, "u1", "会员", nil, 1); err != nil {
 		t.Fatal(err)
 	} else if len(books) != 0 {
 		t.Fatalf("登出后不应还能搜到结果: %+v", books)
@@ -224,7 +224,7 @@ func TestSourceLoginWrongPassword(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 	sourceID := prepareLoginSource(t, svc, loginTestSourceJSON(t, srv.URL))
 
-	res, err := svc.RunLoginAction(t.Context(), readerTestUserID, sourceID, "", map[string]string{
+	res, err := svc.RunLoginAction(t.Context(), "u1", sourceID, "", map[string]string{
 		"邮箱": "user@example.com", "密码": "wrong",
 	})
 	if err != nil {
@@ -248,7 +248,7 @@ func TestSourceLoginInfo_ExposesUIFields(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 	sourceID := prepareLoginSource(t, svc, loginTestSourceJSON(t, srv.URL))
 
-	info, err := svc.GetSourceLogin(t.Context(), readerTestUserID, sourceID)
+	info, err := svc.GetSourceLogin(t.Context(), "u1", sourceID)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -280,7 +280,7 @@ func TestSourceStateEncryptedAtRest(t *testing.T) {
 	ctx := t.Context()
 	sourceID := prepareLoginSource(t, svc, loginTestSourceJSON(t, srv.URL))
 
-	if _, err := svc.RunLoginAction(ctx, readerTestUserID, sourceID, "", map[string]string{
+	if _, err := svc.RunLoginAction(ctx, "u1", sourceID, "", map[string]string{
 		"邮箱": "user@example.com", "密码": "pw123456",
 	}); err != nil {
 		t.Fatal(err)
@@ -313,10 +313,10 @@ func TestSourceVariableRoundTrip(t *testing.T) {
 	ctx := t.Context()
 	sourceID := prepareLoginSource(t, svc, loginTestSourceJSON(t, srv.URL))
 
-	if err := svc.SetSourceVariable(ctx, sourceID, `{"线路":"https://v2.example.com"}`); err != nil {
+	if err := svc.SetSourceVariable(ctx, "u1", sourceID, `{"线路":"https://v2.example.com"}`); err != nil {
 		t.Fatal(err)
 	}
-	info, err := svc.GetSourceLogin(ctx, readerTestUserID, sourceID)
+	info, err := svc.GetSourceLogin(ctx, "u1", sourceID)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -329,7 +329,7 @@ func TestSourceVariableRoundTrip(t *testing.T) {
 	}
 
 	// 非法 JSON 应被拒绝
-	if err := svc.SetSourceVariable(ctx, sourceID, "not-json"); err == nil {
+	if err := svc.SetSourceVariable(ctx, "u1", sourceID, "not-json"); err == nil {
 		t.Fatal("非法 JSON 变量应被拒绝")
 	}
 }
@@ -367,7 +367,7 @@ func TestEnabledCookieJarGating(t *testing.T) {
 }`
 	sourceID := prepareLoginSource(t, svc, srcJSON)
 
-	if _, _, err := svc.Search(ctx, "任意", nil, 1); err != nil {
+	if _, _, err := svc.Search(ctx, "u1", "任意", nil, 1); err != nil {
 		t.Fatal(err)
 	}
 	// 自动捕获被关闭：不应出现 auto=from-response
@@ -386,10 +386,10 @@ func TestEnabledCookieJarGating(t *testing.T) {
 	defer srv2.Close()
 	srcJSONOn = strings.ReplaceAll(srcJSONOn, srv.URL, srv2.URL)
 	// prepareLoginSource 返回列表首个书源，这里按 URL 精确定位刚导入的对照源
-	if _, err := svc.ImportSources(ctx, srcJSONOn); err != nil {
+	if _, err := svc.ImportSources(ctx, "u1", srcJSONOn); err != nil {
 		t.Fatal(err)
 	}
-	if _, _, err := svc.Search(ctx, "任意", nil, 1); err != nil {
+	if _, _, err := svc.Search(ctx, "u1", "任意", nil, 1); err != nil {
 		t.Fatal(err)
 	}
 	if got := svc.newSourceState(ctx, srv2.URL).GetCookie(srv2.URL); !strings.Contains(got, "auto=from-response") {

internal/service/reader/reader.go

@@ -123,7 +123,7 @@ func (s *ReaderService) SourceHasCoverDecode(origin string) bool {
 
 // ImportSources 导入书源：支持 JSON 数组 / 单对象 / Base64 / 网络URL。
 // 返回导入数量。
-func (s *ReaderService) ImportSources(ctx context.Context, text string) (int, error) {
+func (s *ReaderService) ImportSources(ctx context.Context, userID, text string) (int, error) {
 	text = strings.TrimSpace(text)
 	// 去 UTF-8 BOM（Windows 记事本导出的书源文件常见），否则 URL 检测和 JSON 解析都会失败
 	text = strings.TrimPrefix(text, "\uFEFF")
@@ -155,10 +155,11 @@ func (s *ReaderService) ImportSources(ctx context.Context, text string) (int, er
 		}
 		// 记录该源是否声明封面解密：搜索结果（尚未入库）据此决定封面代理形态。
 		s.markSourceCoverDecode(bs.BookSourceURL, strings.TrimSpace(SPtr(bs.CoverDecodeJs)) != "")
-		// 已存在则更新，否则新建（按书源 URL 去重）
-		existing, err := s.repo.GetSourceByURL(ctx, bs.BookSourceURL)
+		// 已存在则更新，否则新建（按「用户 + 书源 URL」去重：书源按用户独立）
+		existing, err := s.repo.GetSourceByURL(ctx, userID, bs.BookSourceURL)
 		now := time.Now()
 		record := &model.ReaderBookSource{
+			UserID:         userID,
 			Name:           bs.BookSourceName,
 			GroupName:      strings.TrimSpace(SPtr(bs.BookSourceGroup)),
 			Type:           bs.Type(),
@@ -275,9 +276,9 @@ func ParseSourcePayload(text string) []string {
 	return out
 }
 
-// ListSources 书源列表（标注是否支持登录，供前端决定是否显示登录入口）。
-func (s *ReaderService) ListSources(ctx context.Context) ([]model.ReaderBookSource, error) {
-	sources, err := s.repo.ListSources(ctx)
+// ListSources 当前用户的书源列表（标注是否支持登录，供前端决定是否显示登录入口）。
+func (s *ReaderService) ListSources(ctx context.Context, userID string) ([]model.ReaderBookSource, error) {
+	sources, err := s.repo.ListSources(ctx, userID)
 	if err != nil {
 		return nil, err
 	}
@@ -311,9 +312,9 @@ func rawSourceHasLogin(rawJSON string) bool {
 	return strings.TrimSpace(SPtr(probe.LoginURL)) != "" || strings.TrimSpace(SPtr(probe.LoginUI)) != ""
 }
 
-// UpdateSourceEnabled 启停书源。
-func (s *ReaderService) UpdateSourceEnabled(ctx context.Context, id string, enabled bool) error {
-	src, err := s.repo.GetSource(ctx, id)
+// UpdateSourceEnabled 启停书源（限当前用户自己的书源）。
+func (s *ReaderService) UpdateSourceEnabled(ctx context.Context, userID, id string, enabled bool) error {
+	src, err := s.repo.GetSourceForUser(ctx, userID, id)
 	if err != nil {
 		return err
 	}
@@ -321,8 +322,11 @@ func (s *ReaderService) UpdateSourceEnabled(ctx context.Context, id string, enab
 	return s.repo.UpdateSource(ctx, src)
 }
 
-// DeleteSource 删除书源。
-func (s *ReaderService) DeleteSource(ctx context.Context, id string) error {
+// DeleteSource 删除书源（限当前用户自己的书源）。
+func (s *ReaderService) DeleteSource(ctx context.Context, userID, id string) error {
+	if _, err := s.repo.GetSourceForUser(ctx, userID, id); err != nil {
+		return err
+	}
 	return s.repo.DeleteSource(ctx, id)
 }
 
@@ -790,7 +794,6 @@ func (s *ReaderService) readerFileCacheDir() string {
 	return ""
 }
 
-
 // srcID 书源记录 ID（登录界面待办按书源隔离）。
 func (sess *sourceSession) srcID() string {
 	if sess.src != nil {
@@ -917,11 +920,11 @@ type searchHit struct {
 // page 是页码（从 1 开始，对应书源 searchUrl 里的 {{page}}）：搜索按页下发，
 // 前端滚到底再请求下一页并做增量合并。搜索范围内的所有源共用同一个页码；
 // searchUrl 里没有 {{page}} 的源会重复返回首页结果，由调用方按「书名+作者」去重。
-func (s *ReaderService) Search(ctx context.Context, key string, sourceIDs []string, page int) ([]SearchBook, []SearchSkipped, error) {
+func (s *ReaderService) Search(ctx context.Context, userID, key string, sourceIDs []string, page int) ([]SearchBook, []SearchSkipped, error) {
 	if page < 1 {
 		page = 1
 	}
-	sources, err := s.repo.ListSources(ctx)
+	sources, err := s.repo.ListSources(ctx, userID)
 	if err != nil {
 		return nil, nil, err
 	}
@@ -1867,7 +1870,7 @@ func (s *ReaderService) FetchMediaWithOptions(ctx context.Context, book *model.R
 		helper.StripAcceptEncoding(httpReq.Header)
 		// 书源级请求头
 		if s.repo != nil {
-			if found, findErr := s.repo.GetSourceByURL(ctx, book.Origin); findErr == nil && found != nil && found.Header != "" {
+			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 {
@@ -2406,7 +2409,7 @@ func (s *ReaderService) DecodeImageBytes(ctx context.Context, book *model.Reader
 	if js == "" {
 		return data, nil
 	}
-	srcModel, err := s.repo.GetSourceByURL(ctx, book.Origin)
+	srcModel, err := s.repo.GetSourceAnyByURL(ctx, book.Origin)
 	if err != nil {
 		return data, nil
 	}
@@ -2467,7 +2470,7 @@ func (s *ReaderService) fetchSourceResource(ctx context.Context, sourceURL, rawU
 	if err != nil || bs == nil {
 		return nil, fmt.Errorf("书源不存在")
 	}
-	srcModel, err := s.repo.GetSourceByURL(ctx, sourceURL)
+	srcModel, err := s.repo.GetSourceAnyByURL(ctx, sourceURL)
 	if err != nil {
 		return nil, err
 	}
@@ -2605,8 +2608,10 @@ func (s *ReaderService) SwitchOrigin(ctx context.Context, userID, bookID string,
 	return book, nil
 }
 
-// ClearBookOriginCacheIfUnreferenced 清理 (origin, bookURL) 的正文缓存，
+// ClearBookOriginCacheIfUnreferenced 清理某本网络书的正文缓存，
 // 但仅当没有其他书架记录仍在引用它时（同一本书可能被多个用户收藏）。
+//
+// 缓存按「书源行 + 书本地址」组织：换源后旧地址的缓存不会再命中，这里负责回收空间。
 func (s *ReaderService) ClearBookOriginCacheIfUnreferenced(ctx context.Context, origin, bookURL, excludeBookID string) {
 	if s == nil || s.repo == nil || origin == "" || bookURL == "" {
 		return
@@ -2619,7 +2624,11 @@ func (s *ReaderService) ClearBookOriginCacheIfUnreferenced(ctx context.Context,
 			}
 		}
 	}
-	s.ClearContentCacheForBook(ctx, origin, bookURL)
+	sourceID := s.contentSourceID(ctx, nil, &model.ReaderBook{Origin: origin})
+	if sourceID == "" {
+		return
+	}
+	s.ClearContentCacheForBook(ctx, sourceID, bookURL)
 }
 
 // GetBook 按 ID 取书（媒体代理等使用）。
@@ -3134,13 +3143,13 @@ func deepCopyChapterContent(in *ChapterContent) *ChapterContent {
 
 // ContentBatchItem 批量取正文的单章结果。
 type ContentBatchItem struct {
-	ChapterIndex int    `json:"chapter_index"`
-	Type         string `json:"type,omitempty"`
-	Content      string `json:"content,omitempty"`
-	Tracks       []string `json:"tracks,omitempty"`
-	Images       []string `json:"images,omitempty"`
-	ImageStyle   string `json:"image_style,omitempty"`
-	IsHLS        bool   `json:"hls,omitempty"`
+	ChapterIndex int              `json:"chapter_index"`
+	Type         string           `json:"type,omitempty"`
+	Content      string           `json:"content,omitempty"`
+	Tracks       []string         `json:"tracks,omitempty"`
+	Images       []string         `json:"images,omitempty"`
+	ImageStyle   string           `json:"image_style,omitempty"`
+	IsHLS        bool             `json:"hls,omitempty"`
 	Comments     []ContentComment `json:"comments,omitempty"`
 	// Cached 为 true 表示这次由持久缓存直接命中（未访问书源）。
 	Cached bool   `json:"cached"`
@@ -3418,8 +3427,8 @@ func (s *ReaderService) SmokeSource(ctx context.Context, raw string, key string)
 }
 
 // Debug 书源调试接口：返回逐条日志字符串（前端展示用）。
-func (s *ReaderService) Debug(ctx context.Context, sourceID, key string) ([]string, error) {
-	src, bs, err := s.loadSource(ctx, sourceID)
+func (s *ReaderService) Debug(ctx context.Context, userID, sourceID, key string) ([]string, error) {
+	src, bs, err := s.loadSourceForUser(ctx, userID, sourceID)
 	if err != nil {
 		return nil, err
 	}
@@ -3448,6 +3457,19 @@ func (s *ReaderService) loadSource(ctx context.Context, sourceID string) (*model
 	return src, bs, nil
 }
 
+// loadSourceForUser 加载书源并校验归属：书源管理/登录/调试等「用户接口」必须走这条。
+func (s *ReaderService) loadSourceForUser(ctx context.Context, userID, sourceID string) (*model.ReaderBookSource, *BookSource, error) {
+	src, err := s.repo.GetSourceForUser(ctx, userID, sourceID)
+	if err != nil {
+		return nil, nil, fmt.Errorf("书源不存在或不属于当前用户")
+	}
+	bs, err := ParseBookSource(src.RawJSON)
+	if err != nil {
+		return nil, nil, fmt.Errorf("书源 JSON 解析失败: %w", err)
+	}
+	return src, bs, nil
+}
+
 // loadSourceFlexible 按 ID 或 URL 加载书源（书架上只存 origin URL，
 // 前端阅读链路用 source_url 定位书源）。
 func (s *ReaderService) loadSourceFlexible(ctx context.Context, sourceID, sourceURL string) (*model.ReaderBookSource, *BookSource, error) {
@@ -3457,7 +3479,7 @@ func (s *ReaderService) loadSourceFlexible(ctx context.Context, sourceID, source
 	if sourceURL == "" {
 		return nil, nil, fmt.Errorf("缺少书源标识（source_id 或 source_url）")
 	}
-	src, err := s.repo.GetSourceByURL(ctx, sourceURL)
+	src, err := s.repo.GetSourceAnyByURL(ctx, sourceURL)
 	if err != nil {
 		return nil, nil, fmt.Errorf("书源不存在或已被删除")
 	}

internal/service/reader/reader_content_cache.go

@@ -21,11 +21,14 @@ import (
 //
 // 设计要点：
 //   - 缓存「书源侧产物」：getContentFrom 的输出（书源 replaceRegex 之后，
-//     用户替换规则、签名代理改写之前）。因此同一本书多用户共享同一份缓存，
+//     用户替换规则、签名代理改写之前）。因此缓存里不含任何用户维度的处理结果，
 //     用户替换规则在读出后逐请求应用，规则改动即时生效。
-//   - 索引落库（ReaderContentCache），内容落盘（cache_dir/reader-content/<origin>/<bookKey>/<key>.json）。
-//   - 缓存键只包含书源身份、章节身份、内容类型、书源指纹与格式版本：不含书籍行 ID
-//     （目录刷新会重建行）、不含用户（用户维度在读出后处理）。
+//   - 缓存键按书源行组织（书源按用户独立，见 contentBookKey 的说明），
+//     不同用户即使持有同一 URL 的书源也各自一份缓存。
+//   - 索引落库（ReaderContentCache），内容落盘
+//     （cache_dir/reader-content/<sourceKey>/<bookKey>/<chapterKey>.json）。
+//   - 缓存键只包含书源行、章节身份、书源指纹与格式版本：不含书籍行 ID
+//     （目录刷新会重建行，见 RemapContentCacheOnTocChange）。
 
 // readerContentFormatVersion 载荷格式版本。解析管线（正文归一 / 段评提取 / 图片标记）
 // 语义变化时必须递增：旧版本条目会被当作未命中并重抓，避免读到旧结构的缓存。
@@ -60,10 +63,19 @@ type contentFlight struct {
 
 // ─── 键与身份 ──────────────────────────────────────────────────────────────
 
-// contentBookKey 书源身份哈希：origin + 书本地址。
-// 用「文件地址」而不是书源显示名：聚合源的 origin 是显示名，多本同源书会撞在一起。
-func contentBookKey(origin, bookURL string) string {
-	sum := sha256.Sum256([]byte(origin + "\x00" + strings.TrimSpace(bookURL)))
+// contentBookKey 书源身份哈希：书源行 ID + 书本地址。
+//
+// 用书源行 ID 而不是 origin（书源 URL）：书源按用户独立，不同用户可以持有同一
+// URL 但规则/header 不同的副本，按 URL 共享缓存会把别人书源的产物喂进来。
+// 用「行 ID + 书本地址」而不是书源显示名：聚合源的 origin 是显示名，多本同源书会撞。
+func contentBookKey(sourceID, bookURL string) string {
+	sum := sha256.Sum256([]byte(sourceID + "\x00" + strings.TrimSpace(bookURL)))
+	return hex.EncodeToString(sum[:16])
+}
+
+// contentOriginKey 书源行维度的磁盘目录名（同一书源的不同书共享这一层）。
+func contentOriginKey(sourceID string) string {
+	sum := sha256.Sum256([]byte(sourceID))
 	return hex.EncodeToString(sum[:16])
 }
 
@@ -116,24 +128,23 @@ func (s *ReaderService) readerContentDir() string {
 	return filepath.Join(base, "reader-content")
 }
 
-// contentFilePath 单条缓存的磁盘路径：<root>/<originHash>/<bookKey>/<chapterKey>.json。
+// contentFilePath 单条缓存的磁盘路径：<root>/<sourceKey>/<bookKey>/<chapterKey>.json。
 // chapterKey 已是 hex 哈希，不含路径分隔符。
-func (s *ReaderService) contentFilePath(origin, bookURL, chapterKey string) string {
+func (s *ReaderService) contentFilePath(sourceID, bookURL, chapterKey string) string {
 	root := s.readerContentDir()
 	if root == "" {
 		return ""
 	}
-	originHash := contentBookKey(origin, "")
-	return filepath.Join(root, originHash, contentBookKey(origin, bookURL), chapterKey+".json")
+	return filepath.Join(root, contentOriginKey(sourceID), contentBookKey(sourceID, bookURL), chapterKey+".json")
 }
 
 // contentBookDir 某本书的缓存目录（整本清理用）。
-func (s *ReaderService) contentBookDir(origin, bookURL string) string {
+func (s *ReaderService) contentBookDir(sourceID, bookURL string) string {
 	root := s.readerContentDir()
 	if root == "" {
 		return ""
 	}
-	return filepath.Join(root, contentBookKey(origin, ""), contentBookKey(origin, bookURL))
+	return filepath.Join(root, contentOriginKey(sourceID), contentBookKey(sourceID, bookURL))
 }
 
 // writeContentFile 原子写入缓存文件（临时文件 + rename）。
@@ -175,6 +186,22 @@ func removeContentFile(path string) {
 
 // ─── 读写 ──────────────────────────────────────────────────────────────────
 
+// contentSourceID 缓存键用的书源行 ID。src 缺失时按 origin 兜底查一次：
+// 直接调用（测试、诊断路径）可能只拿到书籍与 origin。
+func (s *ReaderService) contentSourceID(ctx context.Context, src *model.ReaderBookSource, book *model.ReaderBook) string {
+	if src != nil && src.ID != "" {
+		return src.ID
+	}
+	if s == nil || s.repo == nil || book == nil {
+		return ""
+	}
+	found, err := s.repo.GetSourceAnyByURL(ctx, book.Origin)
+	if err != nil || found == nil {
+		return ""
+	}
+	return found.ID
+}
+
 // loadCachedContent 读取一章节的缓存：命中返回内容与 true。
 //
 // contentType 为空表示「按章节取任意类型」（正文链路不需要预知类型）；给出具体类型时
@@ -185,7 +212,11 @@ func (s *ReaderService) loadCachedContent(ctx context.Context, src *model.Reader
 	if s == nil || s.repo == nil || book == nil {
 		return nil, false
 	}
-	bookKey := contentBookKey(book.Origin, book.BookURL)
+	sourceID := s.contentSourceID(ctx, src, book)
+	if sourceID == "" {
+		return nil, false
+	}
+	bookKey := contentBookKey(sourceID, book.BookURL)
 	chapterKey := contentChapterKey(book, ch)
 	row, err := s.repo.GetContentCacheByChapter(ctx, bookKey, chapterKey, contentType)
 	if err != nil || row == nil {
@@ -205,7 +236,7 @@ func (s *ReaderService) loadCachedContent(ctx context.Context, src *model.Reader
 		s.dropContentCacheRow(ctx, row)
 		return nil, false
 	}
-	path := s.contentFilePath(book.Origin, book.BookURL, chapterKey)
+	path := s.contentFilePath(sourceID, book.BookURL, chapterKey)
 	raw, err := os.ReadFile(path) // #nosec G304 -- 路径由服务端生成
 	if err != nil {
 		s.dropContentCacheRow(ctx, row)
@@ -253,7 +284,11 @@ func (s *ReaderService) saveCachedContent(ctx context.Context, src *model.Reader
 	if err != nil || len(raw) > readerContentMaxEntryBytes {
 		return
 	}
-	path := s.contentFilePath(book.Origin, book.BookURL, contentChapterKey(book, ch))
+	sourceID := s.contentSourceID(ctx, src, book)
+	if sourceID == "" {
+		return
+	}
+	path := s.contentFilePath(sourceID, book.BookURL, contentChapterKey(book, ch))
 	if err := writeContentFile(path, raw); err != nil {
 		if s.log != nil {
 			s.log.Warn("reader: 写入正文缓存失败", zap.String("path", path), zap.Error(err))
@@ -262,8 +297,8 @@ func (s *ReaderService) saveCachedContent(ctx context.Context, src *model.Reader
 	}
 	now := time.Now().Unix()
 	row := &model.ReaderContentCache{
-		OriginHash:      contentBookKey(book.Origin, ""),
-		BookKey:         contentBookKey(book.Origin, book.BookURL),
+		OriginHash:      contentOriginKey(sourceID),
+		BookKey:         contentBookKey(sourceID, book.BookURL),
 		ChapterKey:      contentChapterKey(book, ch),
 		ChapterIdentity: contentChapterIdentity(book, ch),
 		ChapterIndex:    ch.Index,
@@ -318,17 +353,19 @@ func (s *ReaderService) pruneContentDirIfEmpty(dir string) {
 	}
 }
 
-// ClearContentCacheForBook 清理一本书的全部正文缓存（换源/移出书架时调用）。
-// 同源同书可能被多个用户收藏：仍被引用时不删（见 DeleteBook/ClearBookOrigin）。
-func (s *ReaderService) ClearContentCacheForBook(ctx context.Context, origin, bookURL string) {
-	if s == nil || s.repo == nil || origin == "" || bookURL == "" {
+// ClearContentCacheForBook 清理某书源行下一本书的全部正文缓存（换源/移出书架时调用）。
+//
+// sourceID 是书源行 ID：书源按用户独立，缓存也随之按书源行隔离，所以删除
+// 自己那份书源或换源不会影响其他用户的同名书源缓存。
+func (s *ReaderService) ClearContentCacheForBook(ctx context.Context, sourceID, bookURL string) {
+	if s == nil || s.repo == nil || sourceID == "" || bookURL == "" {
 		return
 	}
-	bookKey := contentBookKey(origin, bookURL)
+	bookKey := contentBookKey(sourceID, bookURL)
 	if _, err := s.repo.DeleteContentCacheByBook(ctx, bookKey); err != nil {
 		return
 	}
-	if dir := s.contentBookDir(origin, bookURL); dir != "" {
+	if dir := s.contentBookDir(sourceID, bookURL); dir != "" {
 		_ = os.RemoveAll(dir)
 		s.pruneContentDirIfEmpty(filepath.Dir(dir))
 	}
@@ -403,7 +440,11 @@ func (s *ReaderService) RemapContentCacheOnTocChange(ctx context.Context, book *
 	if s == nil || s.repo == nil || book == nil || len(oldChapters) == 0 || len(newChapters) == 0 {
 		return
 	}
-	bookKey := contentBookKey(book.Origin, book.BookURL)
+	sourceID := s.contentSourceID(ctx, nil, book)
+	if sourceID == "" {
+		return
+	}
+	bookKey := contentBookKey(sourceID, book.BookURL)
 	rows, err := s.repo.ListContentCacheByBook(ctx, bookKey)
 	if err != nil || len(rows) == 0 {
 		return
@@ -445,7 +486,7 @@ func (s *ReaderService) RemapContentCacheOnTocChange(ctx context.Context, book *
 			continue // 身份未变，只更新序号
 		}
 		oldPath := s.contentPathFromRow(&row)
-		newPath := s.contentFilePath(book.Origin, book.BookURL, newKey)
+		newPath := s.contentFilePath(sourceID, book.BookURL, newKey)
 		if oldPath != "" && newPath != "" {
 			if err := os.MkdirAll(filepath.Dir(newPath), 0o750); err == nil {
 				// 文件不在（只留下索引）时忽略：新条目下次读取会自动重抓。

internal/service/reader/reader_content_cache_test.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/truewhile/MeBox/internal/model"
 )
@@ -144,8 +145,12 @@ func TestContentCacheHitAndPersist(t *testing.T) {
 		t.Fatalf("缓存命中不应再访问书源，实际 %d 次", got)
 	}
 
-	// 缓存文件确实落盘
-	path := svc.contentFilePath(book.Origin, book.BookURL, contentChapterKey(book, model.ReaderChapter{
+	// 缓存文件确实落盘（键按书源行 ID 组织）。
+	sourceID := svc.contentSourceID(ctx, nil, book)
+	if sourceID == "" {
+		t.Fatal("找不到书源行")
+	}
+	path := svc.contentFilePath(sourceID, book.BookURL, contentChapterKey(book, model.ReaderChapter{
 		Index: 0, Title: "第 1 章", URL: srv.URL + "/book/1/c1.html",
 	}))
 	if path == "" {
@@ -279,7 +284,7 @@ func TestContentCacheInvalidatedOnSourceUpdate(t *testing.T) {
 	}
 	// 重新导入同一书源（RawJSON 变化）→ 指纹变化。
 	updated := strings.Replace(cacheTestSourceJSON(srv.URL), "缓存测试源", "缓存测试源v2", 1)
-	if _, err := svc.ImportSources(ctx, updated); err != nil {
+	if _, err := svc.ImportSources(ctx, "u1", updated); err != nil {
 		t.Fatalf("更新书源失败: %v", err)
 	}
 	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0); err != nil {
@@ -297,7 +302,8 @@ func TestContentCacheClearedOnRemoveBook(t *testing.T) {
 	if _, err := svc.GetContentForBook(ctx, "u1", book.ID, 0); err != nil {
 		t.Fatalf("读取失败: %v", err)
 	}
-	dir := svc.contentBookDir(book.Origin, book.BookURL)
+	sourceID := svc.contentSourceID(ctx, nil, book)
+	dir := svc.contentBookDir(sourceID, book.BookURL)
 	if _, err := os.Stat(dir); err != nil {
 		t.Fatalf("缓存目录应存在: %v", err)
 	}
@@ -307,7 +313,7 @@ func TestContentCacheClearedOnRemoveBook(t *testing.T) {
 	if _, err := os.Stat(dir); !os.IsNotExist(err) {
 		t.Fatalf("移出书架后缓存目录应被清理，err=%v", err)
 	}
-	if rows, err := svc.repo.ListContentCacheByBook(ctx, contentBookKey(book.Origin, book.BookURL)); err != nil || len(rows) != 0 {
+	if rows, err := svc.repo.ListContentCacheByBook(ctx, contentBookKey(sourceID, book.BookURL)); err != nil || len(rows) != 0 {
 		t.Fatalf("缓存索引应清空: rows=%d err=%v", len(rows), err)
 	}
 }
@@ -318,10 +324,12 @@ func TestContentCacheAudioShortTTL(t *testing.T) {
 	ctx := t.Context()
 
 	ch := model.ReaderChapter{Index: 0, Title: "第 1 章", URL: srv.URL + "/book/1/c1.html"}
-	svc.saveCachedContent(ctx, mustSource(t, svc, srv.URL), book, ch, &ChapterContent{
+	src := mustSource(t, svc, srv.URL)
+	bookKey := contentBookKey(src.ID, book.BookURL)
+	svc.saveCachedContent(ctx, src, book, ch, &ChapterContent{
 		Type: "audio", Tracks: []string{srv.URL + "/a.mp3"},
 	})
-	row, err := svc.repo.GetContentCache(ctx, contentBookKey(book.Origin, book.BookURL), contentChapterKey(book, ch), "audio")
+	row, err := svc.repo.GetContentCache(ctx, bookKey, contentChapterKey(book, ch), "audio")
 	if err != nil {
 		t.Fatalf("音频缓存未写入: %v", err)
 	}
@@ -333,10 +341,10 @@ func TestContentCacheAudioShortTTL(t *testing.T) {
 	if err := svc.repo.UpsertContentCache(ctx, row); err != nil {
 		t.Fatal(err)
 	}
-	if _, ok := svc.loadCachedContent(ctx, mustSource(t, svc, srv.URL), nil, book, ch, "audio"); ok {
+	if _, ok := svc.loadCachedContent(ctx, src, nil, book, ch, "audio"); ok {
 		t.Fatal("过期缓存不应命中")
 	}
-	if _, err := svc.repo.GetContentCache(ctx, contentBookKey(book.Origin, book.BookURL), contentChapterKey(book, ch), "audio"); err == nil {
+	if _, err := svc.repo.GetContentCache(ctx, bookKey, contentChapterKey(book, ch), "audio"); err == nil {
 		t.Fatal("过期条目应被删除")
 	}
 }
@@ -344,7 +352,7 @@ func TestContentCacheAudioShortTTL(t *testing.T) {
 // mustSource 取（并解析）指定书源记录，供直接调用缓存方法的测试使用。
 func mustSource(t *testing.T, svc *ReaderService, sourceURL string) *model.ReaderBookSource {
 	t.Helper()
-	src, err := svc.repo.GetSourceByURL(context.Background(), sourceURL)
+	src, err := svc.repo.GetSourceByURL(context.Background(), "u1", sourceURL)
 	if err != nil {
 		t.Fatalf("取书源失败: %v", err)
 	}
@@ -395,3 +403,58 @@ func TestContentCacheWithoutCacheDir(t *testing.T) {
 		t.Fatalf("正文异常: %q", out.Content)
 	}
 }
+
+// 容量与过期淘汰：总量超配额时按 LRU 删到 90%，过期条目优先清理。
+// 这是「长期运行不会撑满磁盘」的保障，覆盖 pruneReaderContentCache 两条分支。
+func TestContentCachePruneByTTLAndQuota(t *testing.T) {
+	svc, srv, book := prepareCacheTestBook(t)
+	ctx := t.Context()
+	src := mustSource(t, svc, srv.URL)
+
+	// 造 4 条缓存，其中 1 条已过期。
+	for i := 1; i <= 4; i++ {
+		ch := model.ReaderChapter{
+			Index: i - 1, Title: fmt.Sprintf("第 %d 章", i),
+			URL: fmt.Sprintf("%s/book/1/c%d.html", srv.URL, i),
+		}
+		svc.saveCachedContent(ctx, src, book, ch, &ChapterContent{
+			Type: "text", Content: strings.Repeat("正", 200),
+		})
+	}
+	rows, err := svc.repo.ListContentCacheByBook(ctx, contentBookKey(src.ID, book.BookURL))
+	if err != nil || len(rows) != 4 {
+		t.Fatalf("应有 4 条缓存: n=%d err=%v", len(rows), err)
+	}
+	// 把第 1 条标记为已过期。
+	expired := rows[0]
+	expired.ExpiresAt = time.Now().Add(-time.Hour).Unix()
+	if err := svc.repo.UpsertContentCache(ctx, &expired); err != nil {
+		t.Fatal(err)
+	}
+
+	svc.PruneContentCache(ctx)
+	rows, err = svc.repo.ListContentCacheByBook(ctx, contentBookKey(src.ID, book.BookURL))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, row := range rows {
+		if row.ChapterKey == expired.ChapterKey {
+			t.Fatal("过期条目应被清理")
+		}
+	}
+
+	// 容量配额：把上限压到远小于现有体积，触发 LRU 淘汰。
+	var total int64
+	for _, row := range rows {
+		total += row.SizeBytes
+	}
+	if total <= 0 {
+		t.Fatal("缓存体积应大于 0")
+	}
+	svc.cfg.Cache.ReaderContentMaxSizeMB = 0 // 0 = 不限，先确认不误删
+	svc.PruneContentCache(ctx)
+	after, _ := svc.repo.ListContentCacheByBook(ctx, contentBookKey(src.ID, book.BookURL))
+	if len(after) != len(rows) {
+		t.Fatalf("未超配额不应淘汰: before=%d after=%d", len(rows), len(after))
+	}
+}

internal/service/reader/search_page_test.go

@@ -57,7 +57,7 @@ func TestSearchUsesRequestedPage(t *testing.T) {
 		{0, "1"},  // 非法页码退回第 1 页
 		{-3, "1"}, // 负数同理
 	} {
-		books, skipped, err := svc.Search(t.Context(), "关键词", nil, tc.in)
+		books, skipped, err := svc.Search(t.Context(), "u1", "关键词", nil, tc.in)
 		if err != nil {
 			t.Fatalf("page=%d 搜索失败: %v", tc.in, err)
 		}
@@ -88,7 +88,7 @@ func TestSearchWithoutPagePlaceholderStillWorks(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 	_ = prepareLoginSource(t, svc, scopeEchoSourceJSON(t, "单页源", srv.URL))
 
-	books, _, err := svc.Search(t.Context(), "书", nil, 3)
+	books, _, err := svc.Search(t.Context(), "u1", "书", nil, 3)
 	if err != nil {
 		t.Fatalf("搜索失败: %v", err)
 	}

internal/service/reader/search_query_test.go

@@ -46,7 +46,7 @@ func TestSearchSendsQueryString(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 	_ = prepareLoginSource(t, svc, queryEchoSource(srv.URL))
 
-	books, skipped, err := svc.Search(t.Context(), "宠魅", nil, 1)
+	books, skipped, err := svc.Search(t.Context(), "u1", "宠魅", nil, 1)
 	if err != nil {
 		t.Fatalf("搜索失败: %v", err)
 	}
@@ -87,7 +87,7 @@ func TestSearchResponseUsesEmptyArrays(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 	_ = prepareLoginSource(t, svc, queryEchoSource(srv.URL))
 
-	books, skipped, err := svc.Search(t.Context(), "宠魅", nil, 1)
+	books, skipped, err := svc.Search(t.Context(), "u1", "宠魅", nil, 1)
 	if err != nil {
 		t.Fatalf("搜索失败: %v", err)
 	}
@@ -130,7 +130,7 @@ func TestSearchPreservesExistingPercentEncoding(t *testing.T) {
 	out, _ := json.Marshal(src)
 	_ = prepareLoginSource(t, svc, string(out))
 
-	if _, _, err := svc.Search(t.Context(), "宠魅", nil, 1); err != nil {
+	if _, _, err := svc.Search(t.Context(), "u1", "宠魅", nil, 1); err != nil {
 		t.Fatalf("搜索失败: %v", err)
 	}
 	if gotQuery != "宠魅" {

internal/service/reader/search_scope_test.go

@@ -53,11 +53,11 @@ func TestSearchRespectsSourceScope(t *testing.T) {
 		scopeEchoSourceJSON(t, "源A", srvA.URL),
 		scopeEchoSourceJSON(t, "源B", srvB.URL),
 	} {
-		if _, err := svc.ImportSources(t.Context(), raw); err != nil {
+		if _, err := svc.ImportSources(t.Context(), "u1", raw); err != nil {
 			t.Fatal(err)
 		}
 	}
-	sources, err := svc.ListSources(t.Context())
+	sources, err := svc.ListSources(t.Context(), "u1")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -75,7 +75,7 @@ func TestSearchRespectsSourceScope(t *testing.T) {
 	}
 
 	// 指定单个源：只应搜到该源的结果
-	books, skipped, err := svc.Search(t.Context(), "书", []string{idByName["源A"]}, 1)
+	books, skipped, err := svc.Search(t.Context(), "u1", "书", []string{idByName["源A"]}, 1)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -87,7 +87,7 @@ func TestSearchRespectsSourceScope(t *testing.T) {
 	}
 
 	// 空范围：默认全部启用书源，两个源都应命中
-	books, _, err = svc.Search(t.Context(), "书", nil, 1)
+	books, _, err = svc.Search(t.Context(), "u1", "书", nil, 1)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -96,7 +96,7 @@ func TestSearchRespectsSourceScope(t *testing.T) {
 	}
 
 	// 范围里的源已不存在（删源/换设备）时退回全部启用，而不是搜不到
-	books, _, err = svc.Search(t.Context(), "书", []string{"not-a-real-source"}, 1)
+	books, _, err = svc.Search(t.Context(), "u1", "书", []string{"not-a-real-source"}, 1)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/service/reader/source_import_test.go

@@ -38,7 +38,7 @@ func TestImportSourcesAcceptsMessySource(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 	ctx := t.Context()
 
-	imported, err := svc.ImportSources(ctx, messySourceJSON)
+	imported, err := svc.ImportSources(ctx, "u1", messySourceJSON)
 	if err != nil {
 		t.Fatalf("导入失败: %v", err)
 	}
@@ -46,7 +46,7 @@ func TestImportSourcesAcceptsMessySource(t *testing.T) {
 		t.Fatalf("导入数量 = %d，期望 1", imported)
 	}
 
-	bs, err := svc.repo.GetSourceByURL(ctx, "https://www.mangacopy.com/")
+	bs, err := svc.repo.GetSourceByURL(ctx, "u1", "https://www.mangacopy.com/")
 	if err != nil || bs == nil {
 		t.Fatalf("按 URL 查不到导入的书源: %v", err)
 	}
@@ -139,7 +139,7 @@ func TestParseBookSourceRejectsGarbage(t *testing.T) {
 func TestImportSourcesReportsReasonWhenNothingImported(t *testing.T) {
 	svc, _ := newLoginTestService(t)
 
-	_, err := svc.ImportSources(t.Context(), `[{"bookSourceUrl":123,"bookSourceName":"坏源"}]`)
+	_, err := svc.ImportSources(t.Context(), "u1", `[{"bookSourceUrl":123,"bookSourceName":"坏源"}]`)
 	if err == nil {
 		t.Fatal("一条都没导入时应当返回错误")
 	}

internal/service/reader/source_per_user_test.go

@@ -0,0 +1,110 @@
+package reader
+
+import (
+	"strings"
+	"testing"
+)
+
+// 书源按用户独立：同一 URL 的两个用户各自持有副本，启停/删除/搜索互不影响。
+
+func TestSourcesArePerUser(t *testing.T) {
+	srv := newCacheTestServer()
+	defer srv.Close()
+	svc, _ := newLoginTestService(t)
+	ctx := t.Context()
+
+	raw := cacheTestSourceJSON(srv.URL)
+	if _, err := svc.ImportSources(ctx, "u1", raw); err != nil {
+		t.Fatalf("u1 导入失败: %v", err)
+	}
+	// 第二个用户导入同一书源 URL：旧实现会撞 source_url 唯一索引（导入失败）。
+	if _, err := svc.ImportSources(ctx, "u2", raw); err != nil {
+		t.Fatalf("u2 导入同一书源失败（书源未按用户隔离）: %v", err)
+	}
+
+	u1Sources, err := svc.ListSources(ctx, "u1")
+	if err != nil || len(u1Sources) != 1 {
+		t.Fatalf("u1 应有 1 个书源: n=%d err=%v", len(u1Sources), err)
+	}
+	u2Sources, err := svc.ListSources(ctx, "u2")
+	if err != nil || len(u2Sources) != 1 {
+		t.Fatalf("u2 应有 1 个书源: n=%d err=%v", len(u2Sources), err)
+	}
+	if u1Sources[0].ID == u2Sources[0].ID {
+		t.Fatal("两个用户应各持一份副本（行 ID 不同）")
+	}
+	if u1Sources[0].UserID != "u1" || u2Sources[0].UserID != "u2" {
+		t.Fatalf("书源归属错误: u1=%q u2=%q", u1Sources[0].UserID, u2Sources[0].UserID)
+	}
+
+	// 启停互不影响。
+	if err := svc.UpdateSourceEnabled(ctx, "u1", u1Sources[0].ID, false); err != nil {
+		t.Fatalf("u1 停用失败: %v", err)
+	}
+	u2After, _ := svc.ListSources(ctx, "u2")
+	if len(u2After) != 1 || !u2After[0].Enabled {
+		t.Fatal("u1 停用影响到了 u2 的书源")
+	}
+
+	// 删除只删自己那份。
+	if err := svc.DeleteSource(ctx, "u1", u1Sources[0].ID); err != nil {
+		t.Fatalf("u1 删除失败: %v", err)
+	}
+	if left, _ := svc.ListSources(ctx, "u1"); len(left) != 0 {
+		t.Fatalf("u1 应已无书源: n=%d", len(left))
+	}
+	if left, _ := svc.ListSources(ctx, "u2"); len(left) != 1 {
+		t.Fatalf("u2 的书源被误删: n=%d", len(left))
+	}
+
+	// 越权删除他人书源必须失败。
+	if err := svc.DeleteSource(ctx, "u1", u2Sources[0].ID); err == nil {
+		t.Fatal("u1 不应能删除 u2 的书源")
+	}
+}
+
+// 搜索只使用当前用户的书源范围。
+func TestSearchUsesOwnSourcesOnly(t *testing.T) {
+	srv := e2eServer()
+	defer srv.Close()
+	svc, _ := newLoginTestService(t)
+	ctx := t.Context()
+
+	if _, err := svc.ImportSources(ctx, "u1", e2eSourceJSON(srv.URL)); err != nil {
+		t.Fatal(err)
+	}
+	// u2 没有任何书源：搜索应直接报「没有已启用的书源」，而不是用 u1 的源。
+	if _, _, err := svc.Search(ctx, "u2", "书", nil, 1); err == nil || !strings.Contains(err.Error(), "没有已启用的书源") {
+		t.Fatalf("u2 无书源时应拒绝搜索，实际 err=%v", err)
+	}
+	// u1 自己的搜索正常。
+	books, _, err := svc.Search(ctx, "u1", "书", nil, 1)
+	if err != nil {
+		t.Fatalf("u1 搜索失败: %v", err)
+	}
+	if len(books) == 0 {
+		t.Fatal("u1 应搜到结果")
+	}
+}
+
+// 同一书源 URL 的两个用户副本：删除再导入仍然可用（物理删除释放唯一键）。
+func TestDeleteAndReimportSameSource(t *testing.T) {
+	srv := newCacheTestServer()
+	defer srv.Close()
+	svc, _ := newLoginTestService(t)
+	ctx := t.Context()
+
+	if _, err := svc.ImportSources(ctx, "u1", cacheTestSourceJSON(srv.URL)); err != nil {
+		t.Fatal(err)
+	}
+	sources, _ := svc.ListSources(ctx, "u1")
+	if err := svc.DeleteSource(ctx, "u1", sources[0].ID); err != nil {
+		t.Fatalf("删除失败: %v", err)
+	}
+	if _, err := svc.ImportSources(ctx, "u1", cacheTestSourceJSON(srv.URL)); err != nil {
+		t.Fatalf("删除后重新导入失败: %v", err)
+	}
+	if again, _ := svc.ListSources(ctx, "u1"); len(again) != 1 {
+		t.Fatalf("重新导入后应有 1 个书源: n=%d", len(again))
+	}
+}

internal/service/reader/switch_origin_test.go

@@ -11,10 +11,10 @@ import (
 // importTestSource 导入一个测试书源并按书源 URL 找到它（同包测试可能导入多个源）。
 func importTestSource(t *testing.T, svc *ReaderService, raw, sourceURL string) string {
 	t.Helper()
-	if _, err := svc.ImportSources(t.Context(), raw); err != nil {
+	if _, err := svc.ImportSources(t.Context(), "u1", raw); err != nil {
 		t.Fatalf("导入书源失败: %v", err)
 	}
-	srcs, err := svc.ListSources(t.Context())
+	srcs, err := svc.ListSources(t.Context(), "u1")
 	if err != nil {
 		t.Fatal(err)
 	}

internal/service/reader_cache_cleanup_test.go

@@ -0,0 +1,116 @@
+package service
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// 长期运行时各类缓存必须有上限或清理，否则会慢慢吃满磁盘。
+// 这里覆盖新增的「书源文件缓存 + 孤儿临时文件」清理任务。
+
+func writeAgedFile(t *testing.T, path string, age time.Duration) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o750); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	stamp := time.Now().Add(-age)
+	if err := os.Chtimes(path, stamp, stamp); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestJobCleanReaderFilesPrunesByRetention(t *testing.T) {
+	cacheDir := t.TempDir()
+	s := &SchedulerService{cacheDir: cacheDir, readerFilesTTLHours: 24}
+
+	// 超龄的书源文件（字体/静态 JS）应被删掉；新文件保留。
+	oldFile := filepath.Join(cacheDir, "reader", "files", "abc.woff")
+	newFile := filepath.Join(cacheDir, "reader", "files", "nested", "fresh.js")
+	writeAgedFile(t, oldFile, 48*time.Hour)
+	writeAgedFile(t, newFile, time.Hour)
+
+	if err := s.jobCleanReaderFiles(context.Background()); err != nil {
+		t.Fatalf("清理失败: %v", err)
+	}
+	if _, err := os.Stat(oldFile); !os.IsNotExist(err) {
+		t.Fatalf("超龄书源文件应被删除，err=%v", err)
+	}
+	if _, err := os.Stat(newFile); err != nil {
+		t.Fatalf("未超龄文件不应被删除: %v", err)
+	}
+}
+
+func TestJobCleanReaderFilesRemovesOrphanTempFiles(t *testing.T) {
+	cacheDir := t.TempDir()
+	s := &SchedulerService{cacheDir: cacheDir, readerFilesTTLHours: 24}
+	ctx := context.Background()
+
+	// 中断的转码产物 .mp3.part 与正文缓存的 .content-* 临时文件。
+	oldPart := filepath.Join(cacheDir, "reader-audio", "deadbeef.mp3.part")
+	freshPart := filepath.Join(cacheDir, "reader-audio", "running.mp3.part")
+	oldContentTmp := filepath.Join(cacheDir, "reader-content", "aa", "bb", ".content-123")
+	// 成品与正常缓存文件不能被误删。
+	finished := filepath.Join(cacheDir, "reader-audio", "done.mp3")
+	contentJSON := filepath.Join(cacheDir, "reader-content", "aa", "bb", "chapter.json")
+
+	writeAgedFile(t, oldPart, 48*time.Hour)
+	writeAgedFile(t, freshPart, time.Minute)
+	writeAgedFile(t, oldContentTmp, 48*time.Hour)
+	writeAgedFile(t, finished, 48*time.Hour)
+	writeAgedFile(t, contentJSON, 48*time.Hour)
+
+	if err := s.jobCleanReaderFiles(ctx); err != nil {
+		t.Fatalf("清理失败: %v", err)
+	}
+	if _, err := os.Stat(oldPart); !os.IsNotExist(err) {
+		t.Fatalf("孤儿 .part 应被删除，err=%v", err)
+	}
+	if _, err := os.Stat(oldContentTmp); !os.IsNotExist(err) {
+		t.Fatalf("孤儿 .content-* 应被删除，err=%v", err)
+	}
+	if _, err := os.Stat(freshPart); err != nil {
+		t.Fatalf("正在写入的 .part 不应被删除: %v", err)
+	}
+	if _, err := os.Stat(finished); err != nil {
+		t.Fatalf("转码成品不应被删除: %v", err)
+	}
+	if _, err := os.Stat(contentJSON); err != nil {
+		t.Fatalf("正文缓存文件不应被删除: %v", err)
+	}
+}
+
+// 未配置 TTL 时用兜底保留时长，而不是「不清理」。
+func TestJobCleanReaderFilesFallsBackToDefaultRetention(t *testing.T) {
+	cacheDir := t.TempDir()
+	s := &SchedulerService{cacheDir: cacheDir} // readerFilesTTLHours = 0
+
+	// 40 天前的文件应被兜底规则（30 天）清掉。
+	veryOld := filepath.Join(cacheDir, "reader", "files", "ancient.js")
+	writeAgedFile(t, veryOld, 40*24*time.Hour)
+
+	if err := s.jobCleanReaderFiles(context.Background()); err != nil {
+		t.Fatalf("清理失败: %v", err)
+	}
+	if _, err := os.Stat(veryOld); !os.IsNotExist(err) {
+		t.Fatalf("未配置 TTL 也应有兜底清理，err=%v", err)
+	}
+}
+
+// 目录不存在时不应报错（缓存未启用或尚未产生文件）。
+func TestJobCleanReaderFilesMissingDirs(t *testing.T) {
+	s := &SchedulerService{cacheDir: filepath.Join(t.TempDir(), "nope")}
+	if err := s.jobCleanReaderFiles(context.Background()); err != nil {
+		t.Fatalf("目录不存在应静默通过: %v", err)
+	}
+	// cacheDir 为空（未配置）同样直接返回。
+	empty := &SchedulerService{}
+	if err := empty.jobCleanReaderFiles(context.Background()); err != nil {
+		t.Fatalf("未配置缓存目录应静默通过: %v", err)
+	}
+}

internal/service/scanner_incremental_test.go

@@ -282,6 +282,106 @@ func TestScanLibraryUpdatesExistingPathFromOverlappingLibrary(t *testing.T) {
 	}
 }
 
+// TestScanLibraryReclaimsMediaOrphanedByDeletedLibrary covers the "scan reports
+// files but the library stays empty" failure: a row left behind by a deleted
+// library keeps its stale library_id, and because media.path carries a global
+// unique index the rescan can neither insert a fresh row nor rewrite the
+// ownership, so a rebuilt library stays empty forever. The scan must reclaim
+// such orphaned rows for the library being scanned.
+func TestScanLibraryReclaimsMediaOrphanedByDeletedLibrary(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := t.TempDir()
+	file := filepath.Join(root, "Orphaned Episode 1.mkv")
+	if err := os.WriteFile(file, []byte("payload"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	oldLib := model.Library{Name: "Old", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &oldLib); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sc.ScanLibrary(t.Context(), oldLib.ID); err != nil {
+		t.Fatalf("first scan: %v", err)
+	}
+
+	// Reproduce the gap the scan cannot see: the library row is gone while its
+	// media rows survive (hard-deleted library, or an in-flight scan writing
+	// after DeleteLibrary).
+	if err := repos.DB.Unscoped().Delete(&model.Library{}, "id = ?", oldLib.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if got := countMediaInLibrary(t, repos, oldLib.ID); got != 1 {
+		t.Fatalf("precondition: rows still pinned to deleted library = %d, want 1", got)
+	}
+
+	newLib := model.Library{Name: "New", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &newLib); err != nil {
+		t.Fatal(err)
+	}
+	res, err := sc.ScanLibrary(t.Context(), newLib.ID)
+	if err != nil {
+		t.Fatalf("rescan: %v", err)
+	}
+	if res.ErrorCount != 0 {
+		t.Fatalf("rescan errors = %#v, want none", res.Errors)
+	}
+	if got := countMedia(t, repos); got != 1 {
+		t.Fatalf("media count = %d, want 1 (orphan reclaimed, not duplicated)", got)
+	}
+	if got := countMediaInLibrary(t, repos, newLib.ID); got != 1 {
+		t.Fatalf("rebuilt library media count = %d, want 1", got)
+	}
+	var media model.Media
+	if err := repos.DB.First(&media, "path = ?", file).Error; err != nil {
+		t.Fatal(err)
+	}
+	if media.LibraryID != newLib.ID {
+		t.Fatalf("media library_id = %q, want reclaimed to %q", media.LibraryID, newLib.ID)
+	}
+}
+
+// TestScanLibraryKeepsOwnershipWhenOwningLibraryStillExists pins the other half
+// of the rule: local media stays with its existing library as long as that
+// library is real, so overlapping libraries do not steal each other's rows.
+func TestScanLibraryKeepsOwnershipWhenOwningLibraryStillExists(t *testing.T) {
+	sc, repos := newScannerTestEnv(t)
+	root := t.TempDir()
+	file := filepath.Join(root, "Shared (2026).mkv")
+	if err := os.WriteFile(file, []byte("payload"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ownerLib := model.Library{Name: "Owner", Path: root, Type: "movie", Enabled: true}
+	otherLib := model.Library{Name: "Other", Path: root, Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &ownerLib); err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.Library.Create(t.Context(), &otherLib); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sc.ScanLibrary(t.Context(), ownerLib.ID); err != nil {
+		t.Fatalf("owner scan: %v", err)
+	}
+	if _, err := sc.ScanLibrary(t.Context(), otherLib.ID); err != nil {
+		t.Fatalf("other scan: %v", err)
+	}
+	var media model.Media
+	if err := repos.DB.First(&media, "path = ?", file).Error; err != nil {
+		t.Fatal(err)
+	}
+	if media.LibraryID != ownerLib.ID {
+		t.Fatalf("media library_id = %q, want unchanged owner %q", media.LibraryID, ownerLib.ID)
+	}
+}
+
+func countMediaInLibrary(t *testing.T, repos *repository.Container, libraryID string) int64 {
+	t.Helper()
+	var n int64
+	if err := repos.DB.Model(&model.Media{}).Where("library_id = ?", libraryID).Count(&n).Error; err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
 func TestScanLibrarySkipsUnchangedLocalMetadata(t *testing.T) {
 	sc, repos := newScannerTestEnv(t)
 	root := t.TempDir()

internal/service/scheduler.go

@@ -45,6 +45,9 @@ type SchedulerService struct {
 
 	// readerContentCleaner 阅读正文缓存的清理钩子（由阅读模块注入）。
 	readerContentCleaner func(context.Context)
+	// readerFilesTTLHours 书源文件缓存（java.cacheFile / downloadFile）的保留小时数。
+	// 0 表示用内置兜底值（见 readerFilesRetentionMax）。
+	readerFilesTTLHours int
 
 	segments *MediaSegmentService
 
@@ -96,6 +99,11 @@ func (s *SchedulerService) SetReaderContentCleaner(fn func(context.Context)) {
 	s.readerContentCleaner = fn
 }
 
+// SetReaderFilesTTL 配置书源文件缓存的保留小时数（0 表示用兜底值）。
+func (s *SchedulerService) SetReaderFilesTTL(hours int) {
+	s.readerFilesTTLHours = hours
+}
+
 // scheduledJob is one recurring task.
 type scheduledJob struct {
 	name     string
@@ -165,6 +173,12 @@ func (s *SchedulerService) Start(ctx context.Context) {
 			interval: 1 * time.Hour,
 			run:      s.jobCleanReaderContentCache,
 		})
+		// 书源文件缓存与孤儿临时文件的清理和正文缓存同源，一起注册。
+		s.jobs = append(s.jobs, &scheduledJob{
+			name:     "reader_files_cleanup",
+			interval: 24 * time.Hour,
+			run:      s.jobCleanReaderFiles,
+		})
 	}
 	// 片头预热只在注入了 Segments 时注册，避免测试跑无转外网任务。
 	if s.segments != nil {

internal/service/scheduler_local_jobs.go

@@ -2,6 +2,7 @@ package service
 
 import (
 	"context"
+	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -186,6 +187,62 @@ func (s *SchedulerService) jobCleanReaderContentCache(ctx context.Context) error
 	return nil
 }
 
+// readerFilesRetentionMax 书源文件缓存（java.cacheFile / downloadFile）的保底保留时长。
+// 未配置 TTL 时用它兜底：字体、静态 JS 这类文件会被书源长期复用，不能删太早。
+const readerFilesRetentionMax = 30 * 24 * time.Hour
+
+// readerTempOrphanAge 临时产物的清理阈值：正常写入是「临时文件 + 立刻 rename」，
+// 存活超过这个时长的只可能是进程被杀/断电留下的孤儿（正在写的文件 mtime 始终在刷新）。
+const readerTempOrphanAge = 24 * time.Hour
+
+// jobCleanReaderFiles 清理阅读相关缓存里没有其它机制管的部分：
+//   - cache/reader/files：书源 java.cacheFile / java.downloadFile 落盘的文件
+//     （字体、静态 JS 等），按保留时长淘汰——此前完全没有清理，会无限增长；
+//   - 孤儿临时文件：转码的 *.mp3.part 与正文缓存的 .content-*，写入中断后会残留。
+func (s *SchedulerService) jobCleanReaderFiles(ctx context.Context) error {
+	if s.cacheDir == "" {
+		return nil
+	}
+	retention := s.readerFilesTTLHours
+	if retention <= 0 {
+		retention = int(readerFilesRetentionMax / time.Hour)
+	}
+	if err := walkAndPrune(filepath.Join(s.cacheDir, "reader", "files"),
+		time.Now().Add(-time.Duration(retention)*time.Hour)); err != nil {
+		return err
+	}
+	// 转码缓存的 tmp 是 <目标>.mp3.part，与成品同目录。
+	if err := pruneOrphanTempFiles(filepath.Join(s.cacheDir, "reader-audio")); err != nil {
+		return err
+	}
+	// 正文缓存的临时文件有固定前缀。
+	return pruneOrphanTempFiles(filepath.Join(s.cacheDir, "reader-content"))
+}
+
+// pruneOrphanTempFiles 删除缓存目录里超龄的临时文件（*.part / .content-*）。
+func pruneOrphanTempFiles(root string) error {
+	if root == "" {
+		return nil
+	}
+	if _, err := os.Stat(root); err != nil {
+		return nil
+	}
+	cutoff := time.Now().Add(-readerTempOrphanAge)
+	return filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() {
+			return nil
+		}
+		name := info.Name()
+		if !strings.HasSuffix(name, ".part") && !strings.HasPrefix(name, ".content-") {
+			return nil
+		}
+		if info.ModTime().Before(cutoff) {
+			_ = os.Remove(path) // #nosec G122 -- 缓存目录内的孤儿临时文件，尽力清理
+		}
+		return nil
+	})
+}
+
 // jobCleanTranscodeCache deletes HLS artefacts older than 24h.
 func (s *SchedulerService) jobCleanTranscodeCache(ctx context.Context) error {
 	if s.cacheDir == "" {

internal/service/service_builder.go

@@ -214,6 +214,9 @@ func (b *serviceContainerBuilder) initAccessAndStorageServices() {
 	if b.c.Reader != nil {
 		b.c.Scheduler.SetReaderContentCleaner(b.c.Reader.PruneContentCache)
 	}
+	if b.cfg != nil {
+		b.c.Scheduler.SetReaderFilesTTL(b.cfg.Cache.ReaderFilesTTLHours)
+	}
 }
 
 func (b *serviceContainerBuilder) initIdentityServices() {

web/src/pages/PlayerPage.tsx

@@ -20,7 +20,7 @@ import { useAuthStore } from '../stores/auth'
 import type { Media, PlaybackInfo, PlaybackQuality, PlaybackSegment, PlaybackSegmentKind } from '../types'
 import { getSeriesKey, seriesTitleFromPath } from '../utils/groupSeries'
 import { formatEpisodeLabel } from '../utils/episodeNumber'
-import { mediaVersionMatches, mediaVersionsOf } from '../utils/mediaVersion'
+import { autoPlayEpisodeFor, mediaVersionMatches, mediaVersionsOf } from '../utils/mediaVersion'
 import { DEFAULT_PLAYBACK_RATE, normalizePlaybackRate } from '../utils/playbackRate'
 import { resolveActiveSkip, skippedNoticeText, toSkipSegments, type SkipPrompt } from '../utils/skipSegments'
 import { isRemoteEmbyID } from '../utils/remoteEmby'
@@ -1147,6 +1147,95 @@ export function PlayerPage() {
     mediaRef.current = media
   }, [media])
 
+  /**
+   * 直连失败后的统一回退：按当前源与设置决定切 115 云转码 / 本地转码 / 明确报错。
+   * error 分支与起播看门狗（armDirectStallWatchdog）共用同一套判定。
+   */
+  const fallbackDirectPlay = useCallback(() => {
+    if (modeRef.current !== 'direct') return
+    // 宽限期内又触发的迟到 fallback 定时器：直接丢掉。
+    if (Date.now() < directSeekGraceUntilRef.current) return
+    const current = ref.current
+    if (current && current.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) return
+    if (isRemoteEmbyID(mediaRef.current?.id) || isDirectStreamMedia(mediaRef.current)) {
+      setPlayerError('直接播放失败。该媒体为远程 Emby 挂载直连播放（不进行转码）；当前浏览器可能不支持该视频编码或音频格式，建议使用外部播放器（如 PotPlayer / VLC / IINA）播放。')
+      toast.error('直接播放失败，建议使用外部播放器')
+    } else if (directOnly) {
+      setPlayerError('直接播放失败。当前为「客户端直连解码」模式，宿主机不转码；请使用支持该编码/封装的播放器（如 Infuse / VLC / Emby 客户端）播放，或关闭直连解码模式。')
+      toast.error('直接播放失败（客户端直连解码模式）')
+    } else if (playbackInfo?.provider === 'cloud115') {
+      const preferred =
+        findPlaybackQualityById(playbackInfo, selectedQuality) ??
+        findPlaybackQualityById(playbackInfo, playbackInfo.default_quality)
+      if (preferred?.source === 'cloud' && preferred.available) {
+        setCloudWaiting(false)
+        setHlsSource('cloud')
+        setPlaybackMode('hls')
+      } else if (preferred?.source === 'cloud') {
+        setHlsSource('cloud')
+        setCloudWaiting(true)
+        setCloudWaitMessage(preferred.note || `正在等待 115 转码 ${preferred.label}…`)
+        void startCloudTranscode(Number(preferred.id) || 4)
+      } else {
+        switchToLocalHLS(current?.currentTime || 0)
+      }
+    } else if (hlsUnavailable) {
+      setPlayerError('直接播放失败，且 HLS 转码不可用。请检查文件是否存在，或配置本机 ffmpeg 后使用 HLS 转码播放。')
+      toast.error('直接播放失败，HLS 转码不可用')
+    } else {
+      toast.error('直接播放失败，切换到 HLS 转码')
+      switchToLocalHLS(current?.currentTime || 0)
+    }
+  }, [
+    directOnly,
+    hlsUnavailable,
+    playbackInfo,
+    selectedQuality,
+    setPlaybackMode,
+    startCloudTranscode,
+    switchToLocalHLS,
+  ])
+
+  /**
+   * 安排一次直连回退判定。STRM/115 直链冷启动比本地文件慢，给足缓冲时间再判失败。
+   */
+  const scheduleDirectFallback = useCallback(() => {
+    clearFallbackTimer()
+    const fallbackDelayMs = isStrmMedia(mediaRef.current) ? 4000 : 1500
+    fallbackTimerRef.current = setTimeout(fallbackDirectPlay, fallbackDelayMs)
+  }, [clearFallbackTimer, fallbackDirectPlay])
+
+  // 看门狗定时器可能比一次渲染活得更久：始终调用最新一版回退逻辑，避免用
+  // 「起播那一刻」捕获的 playbackInfo（那时可能还是 null）去判定，把本该走
+  // 115 云转码的条目误判成本地转码。
+  const fallbackDirectPlayRef = useRef<() => void>(() => {})
+  useEffect(() => {
+    fallbackDirectPlayRef.current = fallbackDirectPlay
+  }, [fallbackDirectPlay])
+
+  /**
+   * 直连起播看门狗。
+   *
+   * 直连没有 hls.js 那种 manifestLoadingTimeOut 兜底：请求挂住、或上游回了不带
+   * error 事件的响应时，<video> 会一直停在 readyState=0——不出画面、不报错、
+   * 也不触发 handleVideoError，播放器就静默卡死（表现为「进去不自动播放」，
+   * 只能退出重进或手动切播放方式）。这里给每次直连起播挂一个兜底定时器：
+   * 到点仍是 readyState=0（连元数据都没解析到）就按失败处理；只要已经拿到
+   * metadata 就说明链路是通的，只是慢，交给 playing 事件收尾。
+   */
+  const armDirectStallWatchdog = useCallback(() => {
+    clearFallbackTimer()
+    const timeoutMs = isStrmMedia(mediaRef.current) ? 12000 : 6000
+    fallbackTimerRef.current = setTimeout(() => {
+      fallbackTimerRef.current = null
+      if (modeRef.current !== 'direct') return
+      if (Date.now() < directSeekGraceUntilRef.current) return
+      const current = ref.current
+      if (current && current.readyState >= HTMLMediaElement.HAVE_METADATA) return
+      fallbackDirectPlayRef.current()
+    }, timeoutMs)
+  }, [clearFallbackTimer])
+
   useEffect(() => {
     if (!mediaId || !ref.current) return
     const currentMedia = mediaRef.current
@@ -1297,6 +1386,8 @@ export function PlayerPage() {
         }
         video.src = url
         void video.play().catch(() => undefined)
+        // 起播兜底：上游不回 error 时会一直停在 readyState=0，见 armDirectStallWatchdog。
+        armDirectStallWatchdog()
       }
       if (hlsUnavailable && needsTranscodeForBrowser(currentMedia)) {
         setPlayerError('当前正在直连播放原始文件；此封装或音轨浏览器兼容性有限，可能只有画面没有声音。请配置本机 ffmpeg 后切回 HLS 转码播放。')
@@ -1311,6 +1402,7 @@ export function PlayerPage() {
     }
   }, [
     activeBurnedSubtitleStream,
+    armDirectStallWatchdog,
     clearFallbackTimer,
     cloudReloadNonce,
     cloudWaiting,
@@ -1589,6 +1681,17 @@ export function PlayerPage() {
     return playlistEpisodes.findIndex((e) => mediaVersionMatches(e, media.id))
   }, [media, playlistEpisodes])
 
+  // 用剧集 ID 打开播放器时（首页轮播、剧集库卡片、剧集详情页的播放按钮），先落到第一集：
+  // 这类条目没有可播文件，直接请求 /api/stream/<剧集ID> 会被远程 Emby 以 500 打回。
+  useEffect(() => {
+    const target = autoPlayEpisodeFor(media, id, playlistEpisodes)
+    if (!target) return
+    navigate(
+      { pathname: `/play/${target.id}`, search: location.search },
+      { replace: true, state: location.state },
+    )
+  }, [media, id, playlistEpisodes, navigate, location.search, location.state])
+
   const prevEpisode = useMemo(() => {
     if (currentEpisodeIndex > 0) {
       return playlistEpisodes[currentEpisodeIndex - 1]
@@ -2174,16 +2277,21 @@ export function PlayerPage() {
       directRetryRef.current = true
       retryingDirectRef.current = true
       try {
-        // STRM/115 直连：load() 会清空进度从头播。软恢复即可。
-        if (isStrmMedia(mediaRef.current) || pendingDirectSeekRef.current !== null) {
-          const pending = pendingDirectSeekRef.current
-          void video.play().catch(() => undefined)
-          if (pending !== null && pending > 1) {
-            seekStrmDirectTo(pending)
-          }
-        } else {
-          video.load()
-          void video.play().catch(() => undefined)
+        // 必须真正重新发起请求。媒体元素加载失败后 networkState 已经是
+        // NETWORK_NO_SOURCE（不是 NETWORK_EMPTY），此时只调 play() 不会重跑资源
+        // 选取算法：既不会重新请求，也不会再触发一次 error，于是没人去挂 fallback
+        // 定时器——上游 403/502 一次就把播放器钉死在「direct + 空 src」上，没有
+        // 错误提示也不会自动播放，只能退出重进或手动切播放方式。
+        //
+        // classifyDirectPlayError 只在 readyState < HAVE_CURRENT_DATA 时返回
+        // 'retry'，本来就没有可保住的播放进度，所以 load() 是安全的；需要续播
+        // 的位置由 seekStrmDirectTo 在 metadata 就绪后补回。
+        const resumeAt = pendingDirectSeekRef.current
+        pendingDirectSeekRef.current = null
+        video.load()
+        void video.play().catch(() => undefined)
+        if (resumeAt !== null && resumeAt > 1) {
+          seekStrmDirectTo(resumeAt)
         }
       } finally {
         retryingDirectRef.current = false
@@ -2191,60 +2299,8 @@ export function PlayerPage() {
       return
     }
 
-    const fallbackDirectPlay = () => {
-      if (modeRef.current !== 'direct') return
-      // 宽限期内又触发的迟到 fallback 定时器：直接丢掉。
-      if (Date.now() < directSeekGraceUntilRef.current) return
-      const current = ref.current
-      if (current && current.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) return
-      if (isRemoteEmbyID(mediaRef.current?.id) || isDirectStreamMedia(mediaRef.current)) {
-        setPlayerError('直接播放失败。该媒体为远程 Emby 挂载直连播放（不进行转码）；当前浏览器可能不支持该视频编码或音频格式，建议使用外部播放器（如 PotPlayer / VLC / IINA）播放。')
-        toast.error('直接播放失败，建议使用外部播放器')
-      } else if (directOnly) {
-        setPlayerError('直接播放失败。当前为「客户端直连解码」模式，宿主机不转码；请使用支持该编码/封装的播放器（如 Infuse / VLC / Emby 客户端）播放，或关闭直连解码模式。')
-        toast.error('直接播放失败（客户端直连解码模式）')
-      } else if (playbackInfo?.provider === 'cloud115') {
-        const preferred =
-          findPlaybackQualityById(playbackInfo, selectedQuality) ??
-          findPlaybackQualityById(playbackInfo, playbackInfo.default_quality)
-        if (preferred?.source === 'cloud' && preferred.available) {
-          setCloudWaiting(false)
-          setHlsSource('cloud')
-          setPlaybackMode('hls')
-        } else if (preferred?.source === 'cloud') {
-          setHlsSource('cloud')
-          setCloudWaiting(true)
-          setCloudWaitMessage(preferred.note || `正在等待 115 转码 ${preferred.label}…`)
-          void startCloudTranscode(Number(preferred.id) || 4)
-        } else {
-          switchToLocalHLS(current?.currentTime || 0)
-        }
-      } else if (hlsUnavailable) {
-        setPlayerError('直接播放失败，且 HLS 转码不可用。请检查文件是否存在，或配置本机 ffmpeg 后使用 HLS 转码播放。')
-        toast.error('直接播放失败，HLS 转码不可用')
-      } else {
-        toast.error('直接播放失败，切换到 HLS 转码')
-        switchToLocalHLS(current?.currentTime || 0)
-      }
-    }
-
-    clearFallbackTimer()
-    // STRM/115 直链冷启动比本地文件慢，给足缓冲时间再判定失败。
-    const fallbackDelayMs = isStrmMedia(mediaRef.current) ? 4000 : 1500
-    fallbackTimerRef.current = setTimeout(fallbackDirectPlay, fallbackDelayMs)
-  }, [
-    clearFallbackTimer,
-    directOnly,
-    hlsUnavailable,
-    mediaId,
-    mode,
-    playbackInfo,
-    seekStrmDirectTo,
-    selectedQuality,
-    setPlaybackMode,
-    startCloudTranscode,
-    switchToLocalHLS,
-  ])
+    scheduleDirectFallback()
+  }, [mediaId, mode, scheduleDirectFallback, seekStrmDirectTo])
 
   const changeSubtitlePosition = useCallback((nextPosition: SubtitlePosition) => {
     setSubtitlePosition(nextPosition)

web/src/pages/settingsGroupGeneral.ts

@@ -142,7 +142,7 @@ export const generalSettingsGroup: SettingGroup = {
       key: 'https.enabled',
       label: '启用 HTTPS',
       type: 'toggle',
-      hint: '开启后服务将仅通过 HTTPS 访问，保存后会自动切换到 https 地址，原 http 地址不再提供服务。必须先在下文配置好 SSL 证书与私钥（内容或路径任选其一，两者需匹配）才能启用；首次切换因浏览器以 origin（协议+域名+端口）隔离登录态，需要重新登录一次。',
+      hint: '开启后服务仅通过 HTTPS 提供访问，用 http:// 打开同一地址会被自动跳转到 https://（临时跳转，随时关掉 HTTPS 都不会被浏览器长期记住）；保存后当前页面会自动切换到 https 地址。必须先在下文配置好 SSL 证书与私钥（内容或路径任选其一，两者需匹配）才能启用；首次切换因浏览器以 origin（协议+域名+端口）隔离登录态，需要重新登录一次。',
       defaultValue: 'false',
     },
     {

web/src/utils/mediaVersion.test.ts

@@ -1,4 +1,5 @@
 import {
+  autoPlayEpisodeFor,
   isStrmMedia,
   mediaVersionFileName,
   mediaVersionLabel,
@@ -64,4 +65,25 @@ check('strm filename drops outer extension', mediaVersionFileName(cloudRow) ===
 check('missing path has no filename', mediaVersionFileName(media({ path: '' })) === '')
 check('isStrmMedia detects strm url', isStrmMedia(cloudRow))
 
+// 首页轮播/剧集卡片交给播放器的是「整部剧」ID：选集列表里没有它自己，
+// 播放器要自动落到第一集，否则 /api/stream/<剧集ID> 会被远程 Emby 打回 500。
+const series = media({ id: 'embyremote~mount-1~222679', title: '某部新番', path: '/anime/某部新番', size_bytes: 0 })
+const ep1 = media({ id: 'embyremote~mount-1~222681', path: '/anime/某部新番/Season 1/S1E01.mp4', size_bytes: 299580311 })
+const ep2 = media({ id: 'embyremote~mount-1~222683', path: '/anime/某部新番/Season 1/S1E02.mp4', size_bytes: 299580312 })
+
+check('series falls back to its first episode', autoPlayEpisodeFor(series, series.id, [ep1, ep2])?.id === ep1.id)
+check('playable episode stays untouched', autoPlayEpisodeFor(ep1, ep1.id, [ep1, ep2]) === null)
+check('single-item movie list stays untouched', autoPlayEpisodeFor(ep1, ep1.id, [{ ...ep1 }]) === null)
+check('waits until the requested item is loaded', autoPlayEpisodeFor(null, series.id, [ep1]) === null)
+check('ignores a response for another id', autoPlayEpisodeFor(ep2, series.id, [ep1]) === null)
+check('empty episode list has no fallback', autoPlayEpisodeFor(series, series.id, []) === null)
+check(
+  'entry present as another version stays untouched',
+  autoPlayEpisodeFor(
+    media({ id: 'v-4k' }),
+    'v-4k',
+    [media({ id: 'v-4k', versions: [local4k, local1080] })],
+  ) === null,
+)
+
 console.log('mediaVersion.test.ts: ok')

web/src/utils/mediaVersion.ts

@@ -195,6 +195,32 @@ export function mediaVersionSourceLabel(media: Media): string {
   return isStrmMedia(media) ? '云端直链' : '本地文件'
 }
 
+/**
+ * 挑出「播放器该自动跳转到的那一集」。
+ *
+ * 传给 /play/:id 的可能是「整部剧」这类自身没有可播文件的条目——首页轮播、远程 Emby
+ * 剧集库的卡片、剧集详情页的播放按钮都会把剧集 ID 直接交给播放器。这种条目的选集接口
+ * 返回的是它下面的剧集，列表里没有它自己；若直接拿剧集 ID 去请求
+ * /api/stream/<剧集ID>，远程 Emby 会返回 HTTP 500（Unable to cast object of type
+ * 'Series' to type 'IHasMediaSources'），用户看到的就是「播放失败」。此时换成第一集，
+ * 播放、进度、上下集都落在真正可播的条目上。
+ *
+ * 返回 null 表示无需跳转：条目还没加载完、条目本身可播（含以其它版本形式出现在列表里）、
+ * 或该条目下没有任何可选剧集。
+ */
+export function autoPlayEpisodeFor(
+  media: Media | null | undefined,
+  requestedId: string,
+  episodes: Media[],
+): Media | null {
+  if (!media || !requestedId || media.id !== requestedId) return null
+  if (episodes.length === 0) return null
+  if (episodes.some((episode) => mediaVersionMatches(episode, media.id))) return null
+  const first = episodes[0]
+  if (!first?.id || first.id === media.id) return null
+  return first
+}
+
 /** 版本文件名（去掉目录，并剥掉 .strm 外层扩展名），用作版本选项的次要说明。 */
 export function mediaVersionFileName(media: Media): string {
   const path = (media.path || '').replace(/\\/g, '/').trim()