chore: bump version to 0.0.70 [skip ci]

fix: prevent mobile sidebar nav items from stacking on short screens (#7 )
Narrow drawers rendered media links in a flex-1 overflow region above a non-shrinking admin block, so the browse items were clipped into a compressed active pill. Scroll media and admin together, and distinguish /libraries from /libraries?from=admin when highlighting. Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: truewhile <truewhile@users.noreply.github.com>
2026-09-28 11:16:37 +08:00 · 2026-09-02 02:49:11 +00:00 · 2026-09-02 10:48:58 +08:00 · 2026-09-02 02:44:26 +00:00 · 2026-09-02 10:44:10 +08:00 · 2026-09-02 02:30:14 +00:00
188 changed files with 11067 additions and 2265 deletions
@@ -4,9 +4,7 @@ name: AuTo Docker Image
 on:
  push:
    branches: [main]
-  pull_request:
-    branches: [main]
-  
+
  # 保留手动触发作为备选
  workflow_dispatch:
    inputs:
@@ -0,0 +1,133 @@
+# Beta 分支自动构建流水线
+#
+# 触发：push 到 beta 分支 / PR 到 beta / 手动触发。
+# 产出：
+#   1. 前端 + 后端编译验证（go vet / go test / go build）
+#   2. 多平台可执行二进制 artifact（linux/amd64、linux/arm64、windows/amd64）
+#   3. ghcr.io/{owner}/mmtl:beta 多架构 Docker 镜像（linux/amd64 + linux/arm64）
+#
+# 与 main 分支的发布流（Auto-docker-publish.yml）隔离：beta 不做版本递增、
+# 不打 release tag，只构建带 -beta 标识的产物供测试。
+
+name: Beta Build
+
+on:
+  push:
+    branches: [beta]
+  pull_request:
+    branches: [beta]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  BETA_VERSION_PREFIX: beta
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────────────
+  # 1) 编译验证 + 多平台二进制产物
+  # ─────────────────────────────────────────────────────────────────────────────
+  test-and-build:
+    name: Test & build artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve beta version
+        id: version
+        run: |
+          BASE_VERSION=$(cat VERSION 2>/dev/null || echo "0.0.0")
+          SHA_SHORT=${GITHUB_SHA:0:7}
+          echo "full_version=${BASE_VERSION}-beta.${SHA_SHORT}" >> "$GITHUB_OUTPUT"
+
+      # The binary embeds the SPA (web/dist) via go:embed, so dist must exist
+      # before the Go toolchain touches the web package.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: web/package-lock.json
+      - name: Build SPA
+        working-directory: web
+        run: |
+          npm ci
+          npm run build
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+
+      - name: go vet
+        run: go vet ./...
+
+      - name: go test
+        run: go test ./...
+
+      - name: go build (host)
+        run: go build ./...
+
+      # 多平台可执行文件（嵌入刚构建的 web/dist）
+      - name: Build linux/amd64
+        run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w -X main.version=${{ steps.version.outputs.full_version }}" -o dist/mmtl-beta-linux-amd64 ./cmd/server
+      - name: Build linux/arm64
+        run: CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w -X main.version=${{ steps.version.outputs.full_version }}" -o dist/mmtl-beta-linux-arm64 ./cmd/server
+      - name: Build windows/amd64
+        run: CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w -X main.version=${{ steps.version.outputs.full_version }}" -o dist/mmtl-beta-windows-amd64.exe ./cmd/server
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: mmtl-beta-binaries
+          path: dist/*
+          if-no-files-found: error
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # 2) Beta Docker 镜像（ghcr.io/{owner}/mmtl:beta）
+  # ─────────────────────────────────────────────────────────────────────────────
+  docker-beta:
+    name: Build & push beta Docker image
+    needs: test-and-build
+    runs-on: ubuntu-latest
+    # PR 事件不推送镜像，仅 push beta / 手动触发时推送
+    if: github.event_name != 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve beta version
+        id: version
+        run: |
+          BASE_VERSION=$(cat VERSION 2>/dev/null || echo "0.0.0")
+          SHA_SHORT=${GITHUB_SHA:0:7}
+          echo "full_version=${BASE_VERSION}-beta.${SHA_SHORT}" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build & push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          provenance: false
+          sbom: false
+          tags: ghcr.io/${{ github.repository_owner }}/mmtl:beta
+          labels: |
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.source=${{ github.repository }}
+          build-args: |
+            VERSION=${{ steps.version.outputs.full_version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
@@ -4,20 +4,20 @@
  <img src="web/public/brand/logo-192.png" width="96" height="96" alt="MMTL Logo" />
 </p>

-<h3 align="center">适合 NAS、家庭共享和多端播放的私人媒体中心</h3>
+<h3 align="center">面向 NAS 与家庭影音场景的私人媒体中心</h3>

 <p align="center">
-  <strong>Docker 一键部署 · PostgreSQL 主库 · Redis 热缓存 · OpenSearch 搜索增强 · Emby 协议兼容 · Bot 通知</strong>
+  <strong>媒体库 · 刮削整理 · 网盘 STRM · Emby 协议 · 远程 Emby 挂载 · 多用户权限 · Docker 一键部署</strong>
 </p>

 <p align="center">
+  <a href="#项目简介">项目简介</a> ·
  <a href="#快速开始">快速开始</a> ·
-  <a href="#三挡部署">三挡部署</a> ·
-  <a href="#路径映射">路径映射</a> ·
-  <a href="#旧-sqlite-迁移">旧 SQLite 迁移</a> ·
+  <a href="#部署档位">部署档位</a> ·
+  <a href="#鸣谢">鸣谢</a> ·
  <a href="#开发构建">开发构建</a> ·
-  <a href="CONTRIBUTING.md">贡献规范</a> ·
-  <a href="https://mgo.3jzs.com">在线演示</a>
+  <a href="README_EN.md">English</a> ·
+  <a href="CONTRIBUTING.md">贡献规范</a>
 </p>

 <p align="center">
@@ -31,400 +31,223 @@

 ## 项目简介

-MMTL 是一个自托管媒体管理系统，面向 NAS、小主机、家庭影音和多用户共享场景。它把媒体库、刮削、下载整理、订阅、网盘播放、Emby 协议兼容、用户权限和 Bot 通知放在一个后台里，目标是让用户只维护一套服务，就能给网页端、手机端、电视端和第三方播放器使用。
+**MMTL** 是一个自托管私人媒体管理系统，适合 NAS、小主机、家庭共享和多端播放场景。本项目由 [MediaStationGo](https://github.com/ShukeBta/MediaStationGo) fork 并持续二开维护，在保留「一套服务覆盖网页、手机、电视与第三方播放器」思路的同时，围绕网盘播放、任务队列、远程挂载和权限体系做了大量增强。

-核心能力：
+你可以把 MMTL 理解为：
+
+- 一个带现代 Web UI 的**媒体库后台**
+- 一个兼容 Emby/Jellyfin 客户端的**协议网关**
+- 一个连接本地硬盘、下载目录与网盘存储的**整理与播放入口**
+
+### 核心能力
+
+| 模块 | 说明 |
+| --- | --- |
+| **媒体库** | 电影、电视剧、动漫、综艺、音乐与自定义库；多根目录、扫库、海报墙、继续观看 |
+| **元数据刮削** | TMDb、Bangumi、Douban、TheTVDB、Fanart 等；支持 NFO、手动匹配、刮削队列 |
+| **播放** | 网页播放器、HLS 转码、弹幕、字幕、播放配置档、观看历史与收藏 |
+| **Emby 协议** | Infuse、SenPlayer、Fileball 等客户端可直接添加本服务，使用 MMTL 账号登录 |
+| **远程 Emby 挂载** | 将远程 Emby 媒体库挂载到本地界面统一浏览（无需单独开 Emby 客户端） |
+| **网盘与 STRM** | OpenList、CloudDrive2、115、WebDAV 等；STRM 同步、上传/下载队列、直链/302 播放 |
+| **下载与整理** | qBittorrent 接入、站点搜索与订阅、下载后自动整理、文件管理器（复制/移动/硬链/软链） |
+| **用户与权限** | 管理员/普通用户、有效期、成人内容开关、播放配置 PIN、细粒度操作权限 |
+| **运维能力** | 统一任务队列、回收站、存储统计、DLNA 投屏、系统设置与日志 |
+
+### 技术栈
+
+- **后端**：Go · Gin · GORM · SQLite / PostgreSQL · 可选 Redis · 可选 OpenSearch
+- **前端**：React 18 · Vite · TypeScript · Tailwind CSS · Zustand
+- **部署**：Docker Compose 多档模板，支持 amd64 / arm64 镜像与单文件可执行发布
+
+---

- **媒体库管理**：电影、电视剧、动漫、综艺、音乐和自定义媒体库统一管理。
- **Emby 协议兼容**：Infuse、VidHub、SenPlayer、Fileball 等客户端可按 Emby/Jellyfin 方式添加服务器。
- **本地 + 网盘**：支持本地硬盘、下载目录、OpenList、CloudDrive2、WebDAV、STRMURL 和 302 反代播放。
- **订阅下载入库**：连接 qBittorrent 后支持搜索、订阅、下载完成整理、刮削和入库通知。
- **多用户与权限**：管理员/普通用户、有效期、成人内容开关、设备管理、注册码和 Telegram Bot 绑定。
- **灵活部署**：单镜像 SQLite 一键起步，或按规模选择 PostgreSQL、Redis、OpenSearch，低配 NAS 到大库检索都能覆盖。
 ## 快速开始

-最推荐使用 Docker Compose。仓库提供四份独立完整模板，全部不依赖 `.env`。想最省心就下载单镜像档（SQLite，只有一个镜像）；只需要按需修改访问端口、媒体目录、下载目录和可选硬件设备。需要多用户/高并发再选第一档起的 PostgreSQL 档位。
+推荐使用 Docker Compose。仓库提供四份**互相独立**的完整模板，无需 `.env` 即可起步。

 ```bash
-mkdir -p MMTL
-cd MMTL
-# 最省心：单镜像 + SQLite，只启动一个容器
+mkdir -p MMTL && cd MMTL
+
+# 最省心：单镜像 + 内置 SQLite
 curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.simple.yml -o docker-compose.yml
-# 或第一档：PostgreSQL（多用户/高并发更稳）
+
+# 或多用户场景：PostgreSQL 第一档
 # curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.yml -o docker-compose.yml
+
 docker compose up -d
 ```

-启动后访问：
+浏览器访问：

 ```text
 http://服务器IP:18080
 ```

-默认账号：
-
-```text
-admin / admin123
-```
-
-首次登录后请立刻修改管理员密码。
+默认账号：`admin` / `admin123`（首次登录后请立即修改密码）

 镜像地址：

 ```text
-GHCR：ghcr.io/truewhile/mmtl:latest
+ghcr.io/truewhile/mmtl:latest
 ```

+---
+
 ## 部署档位

-MMTL 推荐按机器资源和用户规模选择部署档位。每份 Compose 文件都是完整文件，不需要再叠加多个 `-f`。想一个镜像跑起来就选单镜像档（SQLite）；需要多用户 / 高并发时再用 PostgreSQL 三档。Redis 和 OpenSearch 是增强组件，不替代 PostgreSQL。
+按机器资源选择档位。每份 Compose 文件均可单独使用，**不要**叠加多个 `-f`。

-| 档位 | 完整配置文件 | 组件 | 适合场景 |
+| 档位 | 配置文件 | 组件 | 适合场景 |
 | --- | --- | --- | --- |
-| 单镜像档 | `docker-compose.simple.yml` | MMTL + 内置 SQLite | 新手、单人使用、只想一个镜像跑起来的低配机器 |
-| 第一档 | `docker-compose.yml` | MMTL + PostgreSQL | 大多数 NAS、个人/家庭使用、低内存机器 |
-| 第二档 | `docker-compose.standard.yml` | MMTL + PostgreSQL + Redis | 多用户、Emby 客户端频繁刷新、首页/媒体列表访问较多 |
-| 第三档 | `docker-compose.search.yml` | MMTL + PostgreSQL + Redis + OpenSearch | 超大媒体库、复杂全文搜索、后续需要独立搜索索引 |
+| 单镜像档 | `docker-compose.simple.yml` | MMTL + SQLite | 新手、单人、低配 NAS，只想一个容器跑起来 |
+| 第一档 | `docker-compose.yml` | MMTL + PostgreSQL | 大多数家庭 NAS，多用户更稳 |
+| 第二档 | `docker-compose.standard.yml` | + Redis | 多用户、Emby 客户端频繁刷新、首页/列表访问多 |
+| 第三档 | `docker-compose.search.yml` | + OpenSearch | 超大媒体库、复杂全文搜索（内存占用更高） |

-### 单镜像档：SQLite（最省心）
+### 单镜像档要点

-只启动 MMTL 一个镜像，主数据库用内置 SQLite，不需要 PostgreSQL / Redis / `.env`。变量最少、资源占用最低，适合新手和单人使用。日后需要多用户或更高并发时，保留 `./data` 后切换到第一档的 PostgreSQL 即可。
-
-```bash
-mkdir -p MMTL
-cd MMTL
-curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.simple.yml -o docker-compose.yml
-docker compose up -d
-```
-
-第一次部署通常只需要改 `docker-compose.yml` 里的这几处：
+- 只启动 **一个** MMTL 容器，数据在 `./data/mmtl.db`
+- 通常只需改端口与媒体目录挂载
+- **不要**设置 `MMTL_DATABASE_DSN`，否则会切到 PostgreSQL

 ```yaml
 ports:
-  - "18080:8080"          # 改左边 18080 即可
+  - "18080:8080"
 volumes:
  - ./data:/data          # 必须备份
-  - ./media:/media        # 改左边为你的媒体目录，例如 /vol1/1000/Media:/media
-  # - /dev/dri:/dev/dri   # Intel 核显硬解需要时取消注释
+  - ./cache:/cache        # 可重建
+  - ./media:/media        # 改成你的媒体目录
 ```

-网页后台添加媒体库时填写容器内路径：
+网页添加媒体库时填写容器内路径，例如 `/media`、`/media/电影`。

-```text
-/media
-/media/电影
-/media/电视剧
-```
+### PostgreSQL 档位要点

-关键数据目录：
-
-```text
-./data       JWT 密钥、运行配置、SQLite 主数据库（mmtl.db）——必须备份
-./cache      海报/临时缓存，可重建
-./media      媒体库
-```
-
-> 单镜像模式请不要配置 `MMTL_DATABASE_DSN`；一旦填了 DSN 就会切回 PostgreSQL。
-
-### 第一档：PostgreSQL
-
-第一档是默认推荐部署。它只启动主服务和 PostgreSQL，资源占用最低，适合绝大多数 NAS。
-
-```bash
-mkdir -p MMTL
-cd MMTL
-curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.yml -o docker-compose.yml
-docker compose up -d
-```
-
-关键数据目录：
-
-```text
-./postgres   PostgreSQL 主数据库，必须备份
-./data       JWT 密钥、运行配置、旧 SQLite 迁移源
-./cache      海报、临时文件、转码缓存，可删除重建
-```
-
-### 第二档：PostgreSQL + Redis
-
-第二档是独立完整文件，包含第一档全部配置并额外启用 Redis。Redis 用作热缓存，能减轻多用户和 Emby 客户端频繁刷新时的数据库压力。
-
-```bash
-mkdir -p MMTL
-cd MMTL
-curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.standard.yml -o docker-compose.yml
-docker compose up -d
-```
-
-Redis 数据目录是 `./redis`。它主要保存缓存，通常可重建；真正需要备份的仍然是 `./postgres` 和 `./data`。
-
-### 第三档：PostgreSQL + Redis + OpenSearch
-
-第三档是独立完整文件，包含第二档全部配置并额外启用 OpenSearch，用于大库全文搜索和独立搜索索引。OpenSearch 常驻内存明显更高，低配 NAS 不建议开启。
-
-```bash
-mkdir -p MMTL
-cd MMTL
-curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.search.yml -o docker-compose.yml
-docker compose up -d
-```
-
-OpenSearch 数据目录是 `./opensearch`。搜索索引可重建，但重建大库索引会花时间；机器资源足够时再开启第三档。
-
-## 配置示例
-
-仓库内提供四份推荐 Compose 文件：
-
-```text
-docker-compose.simple.yml     单镜像档：MMTL + 内置 SQLite
-docker-compose.yml            第一档：MMTL + PostgreSQL
-docker-compose.standard.yml   第二档：MMTL + PostgreSQL + Redis
-docker-compose.search.yml     第三档：MMTL + PostgreSQL + Redis + OpenSearch
-```
-
-仓库只保留面向用户部署和项目维护的必要文件。旧的本地部署脚本、发包脚本、开发机辅助脚本、`.env` 示例和旧高级 Compose 模板已经移除；Linux / Docker 用户按上面四个 Compose 文件部署即可。开发者本地生成的 `bin/`、`data/`、`cache/`、`logs/`、`.tmp/`、`tools/` 等目录已列入 `.gitignore`，不应提交到仓库。
-
-如果直接下载为 `docker-compose.yml`，启动命令统一是：
-
-```bash
-docker compose up -d
-```
-
-如果保留原始文件名，也可以这样启动：
-
-```bash
-docker compose -f docker-compose.simple.yml up -d
-docker compose -f docker-compose.standard.yml up -d
-docker compose -f docker-compose.search.yml up -d
-```
-
-常用配置片段如下，注释保留为中文，方便直接复制到 NAS 上调整：
+- 主库在 `./postgres`，配置与密钥在 `./data`
+- 若存在旧版 `./data/mmtl.db`，首次启动会自动迁移到 PostgreSQL
+- 迁移完成后可将 `MMTL_DATABASE_DB_PATH` 改为不存在路径，避免重复检查：

 ```yaml
-services:
-  mmtl:
-    image: ghcr.io/truewhile/MMTL:latest
-    ports:
-      # 左边是宿主机访问端口，右边是容器内端口。
-      - "18080:8080"
-    volumes:
-      # 运行数据：JWT 密钥、配置、旧 SQLite 迁移源。
-      - ./data:/data
-
-      # 缓存目录：海报、临时文件、转码缓存，可删除重建。
-      - ./cache:/cache
-
-      # 媒体库目录：自动整理/重命名/入库需要写权限。
-      - /vol1/1000/Media:/media
-    environment:
-      TZ: Asia/Shanghai
-
-      # PostgreSQL 主数据库。
-      MMTL_DATABASE_TYPE: postgres
-      MMTL_DATABASE_DSN: postgres://mmtl:mmtl@postgres:5432/mmtl?sslmode=disable
-
-      # 旧 SQLite 迁移源：只在从旧版 data/mmtl.db 导入时使用。
-      MMTL_DATABASE_DB_PATH: /data/mmtl.db
-
-      # 路径换算：宿主机路径和容器路径必须一一对应。
-      MMTL_MEDIA_DIR: /vol1/1000/Media
-      MMTL_MEDIA_CONTAINER_DIR: /media
-      MMTL_DOWNLOAD_DIR: /vol1/1000/Downloads
-      MMTL_DOWNLOAD_CONTAINER_DIR: /downloads
+MMTL_DATABASE_DB_PATH: /data/no-sqlite-migration.db
 ```

-## 路径映射
+### 必须备份与可重建

-路径映射是 Docker 部署里最容易填错的地方。原则是：`volumes` 左边是宿主机真实路径，右边是容器内路径；环境变量里也要保持对应关系。
+| 路径 | 说明 |
+| --- | --- |
+| `./data` | JWT 密钥、运行配置、SQLite 主库或迁移源 |
+| `./postgres` | PostgreSQL 主库（PG 档位） |
+| `./cache` | 海报/转码缓存，可重建 |
+| `./redis` | 热缓存，可重建 |
+| `./opensearch` | 搜索索引，可重建 |

-NAS 示例：
-
-```yaml
-volumes:
-  - /vol1/1000/Docker/moviepilot-v2/media:/vol1/1000/Docker/moviepilot-v2/media
-  - /vol1/1000/qBittorrent/downloads:/vol1/1000/qBittorrent/downloads
-environment:
-  MMTL_MEDIA_DIR: /vol1/1000/Docker/moviepilot-v2/media
-  MMTL_MEDIA_CONTAINER_DIR: /vol1/1000/Docker/moviepilot-v2/media
-  MMTL_DOWNLOAD_DIR: /vol1/1000/qBittorrent/downloads
-  MMTL_DOWNLOAD_CONTAINER_DIR: /vol1/1000/qBittorrent/downloads
-```
-
-Windows Docker Desktop 示例：
-
-```yaml
-volumes:
-  - D:/Media:/media
-environment:
-  MMTL_MEDIA_DIR: D:/Media
-  MMTL_MEDIA_CONTAINER_DIR: /media
-```
-
-如果后台添加媒体库时填的是 `/vol1/...`，Compose 里也建议把同一个 `/vol1/...` 挂进容器，避免自动整理和下载入库时路径不可访问。
-
-## 旧 SQLite 迁移
-
-新版推荐 PostgreSQL 作为主数据库。`MMTL_DATABASE_DB_PATH` 不是主库路径，而是旧 SQLite 数据的迁移源。
-
-迁移步骤：
-
-1. 把旧版 `mmtl.db` 放到 `./data/mmtl.db`。
-2. 保持 `MMTL_DATABASE_DB_PATH: /data/mmtl.db`。
-3. 启动一次，确认日志显示迁移完成，网页数据正常。
-4. 备份 `./postgres` 和 `./data`。
-5. 确认不再需要 SQLite 后，把迁移源改成不存在的路径，例如：
-
-```yaml
-environment:
-  # 已完成 SQLite 迁移后，建议改成不存在的路径，避免下次启动重复检查旧库。
-  MMTL_DATABASE_DB_PATH: /data/no-sqlite-migration.db
-```
-
-不要删除 `./postgres`。PostgreSQL 已经是主数据库，删除它会丢失账号、媒体库、订阅、配置和历史数据。
-
-## 日志与 STRM 路径
-
-Compose 模板默认把完整应用日志写入 `./data/logs/app.log`，同时拆分 `./data/logs/warn.log` 和 `./data/logs/error.log`。Docker 自身日志也会保留 10 个 50MB 文件：
-
-```bash
-docker compose logs -f mmtl
-tail -f ./data/logs/app.log
-tail -f ./data/logs/error.log
-```
-
-如果要排查订阅、站点搜索、自动整理或 STRM 生成问题，保持 `MMTL_LOGGING_LEVEL: info`；需要更细日志时临时改成 `debug`，确认后再改回 `info`。
-
-STRM 输出目录请使用容器内可写路径，例如 `/data/strm`，或你已经挂载进容器的媒体目录。旧版本保存过 `/app/data/strm` 的部署会在生成时自动迁移到当前 `MMTL_APP_DATA_DIR`，默认就是 `/data`。
-
-## 更新与备份
-
-更新镜像：
+### 更新镜像

 ```bash
 docker compose pull mmtl
 docker compose up -d --no-deps mmtl
 ```

-不要执行裸 `docker compose pull` 做日常更新。PostgreSQL / Redis / OpenSearch 是数据与缓存基础组件，compose 已设置为 `pull_policy: missing`，首次部署缺镜像时会拉取，日常更新只建议拉取 `mmtl`。需要升级这些基础组件时，请先备份 `./postgres`，再手动修改镜像版本并单独拉取。
+日常更新只拉 `mmtl` 服务即可，不要随意 `docker compose pull` 升级 PostgreSQL/Redis/OpenSearch 基础镜像。

-如果第二档或第三档保留了原始文件名，更新时指定对应完整文件：
+---

-```bash
-# 第二档
-docker compose -f docker-compose.standard.yml pull mmtl
-docker compose -f docker-compose.standard.yml up -d --no-deps mmtl
+## 路径映射

-# 第三档
-docker compose -f docker-compose.search.yml pull mmtl
-docker compose -f docker-compose.search.yml up -d --no-deps mmtl
+Docker 部署最常见的问题是路径填错。记住：
+
+- `volumes` **左侧**是宿主机真实路径，**右侧**是容器内路径
+- 网页后台添加媒体库时，应填写**容器内**路径（如 `/media/电影`）
+- 若使用自动整理/下载入库，`MMTL_MEDIA_DIR` 与 `MMTL_DOWNLOAD_DIR` 需与挂载一致
+
+NAS 示例：
+
+```yaml
+volumes:
+  - /vol1/1000/Media:/media
+  - /vol1/1000/Downloads:/downloads
+environment:
+  MMTL_MEDIA_DIR: /vol1/1000/Media
+  MMTL_MEDIA_CONTAINER_DIR: /media
+  MMTL_DOWNLOAD_DIR: /vol1/1000/Downloads
+  MMTL_DOWNLOAD_CONTAINER_DIR: /downloads
 ```

-必须备份：
+---

-```text
-./postgres   PostgreSQL 主数据库
-./data       JWT 密钥、运行配置、旧 SQLite 迁移源
-```
+## 首次使用建议

-可重建：
+1. **创建媒体库** → 填写 `/media/...` → 执行扫库
+2. **配置元数据源** → 系统设置中添加 TMDb、Bangumi 等 API
+3. **（可选）连接 qBittorrent** → 下载客户端设置，宿主机可用 `http://host.docker.internal:8085`
+4. **（可选）配置网盘账号** → STRM 管理中添加 OpenList / 115 / WebDAV 等
+5. **第三方播放器** → 以 Emby 服务器添加 `http://服务器IP:18080`，使用 MMTL 账号登录

-```text
-./cache      图片缓存、临时文件、转码缓存
-./redis      Redis 热缓存
-./opensearch 搜索索引
-```
+---

 ## 常见问题

-**启动后还是反复迁移 SQLite？**
+**扫库或入库很慢？**  
+先确认路径映射与数据库档位。网盘扫描还受接口限速与目录规模影响；大库可考虑第二档 Redis 或第三档 OpenSearch。

-确认旧数据已经迁移成功后，把 `MMTL_DATABASE_DB_PATH` 改成不存在的路径，例如 `/data/no-sqlite-migration.db`，然后重启容器。
+**qBittorrent 下载后无法整理？**  
+确认下载目录已通过 `volumes` 挂进容器，且 `MMTL_DOWNLOAD_*` 环境变量对应正确。

-**扫库或入库速度很慢？**
+**硬链接失败（cross-device link）？**  
+硬链接要求源与目标在同一文件系统/子卷；跨盘、跨 btrfs 子卷或网盘挂载时请改用复制或软链接。

-先确认数据库档位和路径映射正确。第一档已经足够大多数场景；第二档 Redis 能缓解频繁刷新造成的数据库压力；第三档主要增强搜索，不会替代媒体扫描本身。网盘扫描还会受网盘接口响应、目录数量和网络质量影响。
+**第三方播放器连不上？**  
+确认地址为 `http://IP:18080`，使用 MMTL 用户账号；反代部署需正确配置外部 URL 与 HTTPS 头。

-**qBittorrent 下载完成后无法整理？**
-
-确认 qBittorrent 保存路径已经通过 `volumes` 挂载进 MMTL 容器，并且 `MMTL_DOWNLOAD_DIR` 与 `MMTL_DOWNLOAD_CONTAINER_DIR` 对应正确。
-
-**硬链接目录在 Docker / NAS 上看不到内容？**
-
-硬链接不能直接链接“目录”本身，只能链接目录里的文件。文件管理器执行目录硬链接时会递归创建目标目录结构，并为每个文件创建硬链接。硬链接还要求源文件和目标文件在容器内属于同一个文件系统/子卷；如果下载目录和媒体目录是两个独立 bind mount、不同硬盘、不同 btrfs 子卷或网盘挂载，系统会返回 `invalid cross-device link`，此时请选择“复制”或“软链接”。
-
-**第三方播放器无法连接？**
-
-确认播放器填写的是 `http://服务器IP:18080`，账号密码使用 MMTL 用户账号。反代部署时需要正确设置外部访问地址和 HTTPS 头。
+---

 ## 开发构建

-本地开发需要 Go、Node.js 和 npm。
-
-后端会将 `web/dist` 通过 `go:embed` 编进二进制，因此**在编译 / 运行后端之前要先构建前端**，否则 `web` 包会因为缺少嵌入资源而编译失败。
+后端通过 `go:embed` 嵌入 `web/dist`，**编译前必须先构建前端**。

 ```bash
-# 前端依赖与构建（必须先做，产物被 go:embed 打进二进制）
 npm --prefix web ci
 npm --prefix web run build

-# 后端测试
 go test ./...
-
-# 本地运行后端（二进制自带前端界面，无需额外 web 目录）
-go run ./cmd/server
-
-# 本地运行前端开发服务器
-npm --prefix web run dev
+go run ./cmd/server          # http://127.0.0.1:8080
+npm --prefix web run dev     # http://127.0.0.1:3000
 ```

-前端开发服务器默认访问：
+CI 会在 Release 中提供 Windows / Linux / macOS 的 amd64、arm64 单文件可执行程序。

-```text
-http://127.0.0.1:3000
-```
+---

-后端健康检查：
+## 鸣谢

-```text
-http://127.0.0.1:8080/api/health
-```
+MMTL 在 [MediaStationGo](https://github.com/ShukeBta/MediaStationGo) 的基础上 fork 并持续演进。感谢上游项目在媒体库架构、Emby 协议兼容和自托管体验上的奠基工作。

-### 交叉编译单文件发布物
+项目中许多网盘同步、STRM 与媒体整理相关的设计与实现，也参考了 [qmediasync](https://github.com/qicfan/qmediasync)。感谢该项目的思路与实践经验。

-CI（`.github/workflows/Auto-docker-publish.yml`）每次发布会自动为 Windows / Linux(含 Debian) / macOS 交叉编译 amd64 + arm64 的单文件可执行程序，并上传到对应的 GitHub Release。你可以在 Releases 页面下载 `.zip`（Windows）或 `.tar.gz`（Linux / macOS）附件，解压后直接运行其中的 `mmtl`（Windows 为 `mmtl.exe`），无需额外携带前端目录。
-
-本地手动交叉编译某个平台：
-
-```bash
-# 先构建前端
-npm --prefix web ci && npm --prefix web run build
-
-# 例如：构建 Linux amd64 单文件
-CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
-  go build -trimpath -ldflags="-s -w" -o mmtl-linux-amd64 ./cmd/server
-```
+---

 ## 贡献与反馈

-提交 Bug、功能建议或 Pull Request 前，请先阅读 [贡献规范](CONTRIBUTING.md)。
+提交 Issue 或 Pull Request 前，请阅读 [贡献规范](CONTRIBUTING.md) 与 [安全策略](SECURITY.md)。

- Bug 反馈请使用 Issue 模板，并提供部署方式、复现步骤、日志和关键配置。
- 功能建议请说明使用场景、期望行为和可接受的替代方案。
- 安全漏洞请不要公开发 Issue，按 [安全策略](SECURITY.md) 使用私密渠道报告。
- Pull Request 请从独立分支或 fork 分支发起，不要直接向 `main` 推送。
- 分支名建议使用 `fix/...`、`feat/...`、`docs/...` 或 `test/...`，例如 `docs/contribution-guidelines`。
- 提交前按改动范围运行 `go test ./...`、`npm --prefix web run build` 或定向测试，并在 PR 中说明验证结果。
+- Bug 请附部署方式、复现步骤与相关日志
+- 功能建议请说明使用场景与期望行为
+- PR 请从独立分支发起，提交前运行 `go test ./...` 与 `npm --prefix web run build`
+
+---

 ## Star History

-<a href="https://www.star-history.com/?repos=ShukeBta%2FMMTL&type=date&legend=top-left">
+<a href="https://www.star-history.com/?repos=truewhile%2FMMTL&type=date&legend=top-left">
 <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=ShukeBta/MMTL&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=ShukeBta/MMTL&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=ShukeBta/MMTL&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=truewhile/MMTL&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=truewhile/MMTL&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=truewhile/MMTL&type=date&legend=top-left" />
 </picture>
 </a>

+---
+
 ## 许可证

-本项目使用 GPL-3.0 License。详见 [LICENSE](LICENSE)。
+本项目采用 [GPL-3.0](LICENSE) 许可证。
@@ -4,18 +4,19 @@
  <img src="web/public/brand/logo-192.png" width="96" height="96" alt="MMTL Logo" />
 </p>

-<h3 align="center">A lightweight, polished, NAS-friendly private media center</h3>
+<h3 align="center">A self-hosted media center for NAS and home theater</h3>

 <p align="center">
-  <strong>Docker-first setup · Multi-user management · Media library · Metadata · Downloads · Emby-protocol clients · Cloud playback</strong>
+  <strong>Libraries · Metadata · Cloud STRM · Emby protocol · Remote Emby mounts · Multi-user · Docker-first</strong>
 </p>

 <p align="center">
  <a href="README.md">中文</a> ·
+  <a href="#overview">Overview</a> ·
  <a href="#quick-start">Quick Start</a> ·
-  <a href="#docker-compose-recommended">Docker Compose</a> ·
-  <a href="#faq">FAQ</a> ·
-  <a href="https://mgo.3jzs.com">Live Demo</a>
+  <a href="#deployment-tiers">Deployment</a> ·
+  <a href="#acknowledgements">Acknowledgements</a> ·
+  <a href="#development">Development</a>
 </p>

 <p align="center">
@@ -27,78 +28,51 @@

 ---

-## What is it?
+## Overview

-MMTL is a self-hosted media center for personal libraries, home NAS, and home-theater users.
+**MMTL** is a self-hosted private media management system for NAS, mini PCs, family sharing, and multi-device playback. This repository is a maintained fork of [MediaStationGo](https://github.com/ShukeBta/MediaStationGo), extended with stronger cloud playback, task queues, remote mounts, and permission controls.

-It helps you:
+In practice, MMTL gives you:

- Manage movies, TV shows, anime, variety shows, music, and adult libraries.
- Create multiple user accounts for family members, friends, or different devices.
- Scan files and enrich posters, summaries, years, seasons, and episodes.
- Play in the web UI, or log in with a MMTL account from Emby-protocol apps such as Infuse, VidHub, SenPlayer, and Emby clients.
- Connect qBittorrent for search, subscriptions, downloads, and post-download organization.
- Connect OpenList, CloudDrive2, WebDAV, and other storage backends with STRMURL or 302 redirect playback.
- Run on NAS, mini PCs, VPS, Linux, Windows Docker Desktop, or any Docker-friendly host.
+- A modern **web media library**
+- An **Emby/Jellyfin-compatible protocol gateway** for third-party players
+- A single panel for **local disks, download folders, and cloud storage**

-> The project is moving fast. With the default PostgreSQL deployment, back up both `data/` and `postgres/`.
+### Key capabilities

---
+| Area | Highlights |
+| --- | --- |
+| **Libraries** | Movies, TV, anime, variety, music, custom libraries; multi-root scanning; poster wall; continue watching |
+| **Metadata** | TMDb, Bangumi, Douban, TheTVDB, Fanart, NFO import, manual matching, scrape queue |
+| **Playback** | Web player, HLS transcoding, danmaku, subtitles, play profiles, history and favourites |
+| **Emby protocol** | Add MMTL in Infuse, SenPlayer, Fileball, etc. and sign in with MMTL accounts |
+| **Remote Emby mounts** | Browse remote Emby libraries inside MMTL without a separate Emby client |
+| **Cloud & STRM** | OpenList, CloudDrive2, 115, WebDAV; STRM sync; upload/download queues; direct or 302 playback |
+| **Downloads & organize** | qBittorrent, site search/subscriptions, post-download organization, file manager |
+| **Users & permissions** | Admin/regular users, expiry, NSFW toggle, play-profile PIN, granular permissions |
+| **Operations** | Unified task queue, recycle bin, storage stats, DLNA casting, settings and logs |

-## Key Highlights
+### Tech stack

- **One server, many clients**: deploy MMTL once; you do not need to run a separate Emby server.
- **Emby-protocol compatibility**: add the server in third-party players as an Emby/Jellyfin-compatible server, then log in with your MMTL username and password.
- **Multi-user management**: supports admins, regular users, account enable/disable, expiry dates, device management, Bot registration, and redeem codes.
- **Local + cloud media in one place**: manage local disks, download folders, OpenList, CloudDrive2, WebDAV, and other storage backends from one panel.
- **Download-to-library workflow**: connect qBittorrent for search, subscriptions, download completion organization, and metadata matching.
- **NAS-friendly**: simple Docker Compose deployment. The primary database lives under `postgres/`, while runtime secrets and files live under `data/`.
-
---
-
-## Who is it for?
-
- **Beginners** who want to edit one `docker-compose.yml` and start the service.
- **NAS users** who want a low-resource media center for local disks and cloud storage.
- **PT/download users** who want downloads, organization, metadata, and playback in one panel.
- **External-player users** who want to log in to Emby-protocol third-party apps with one MMTL account.
- **Family-sharing users** who want separate user accounts without deploying a separate media server for each person.
- **Developers** who want to study or extend a Go + React self-hosted media app.
-
---
-
-## Live Demo
-
- URL: [https://mgo.3jzs.com](https://mgo.3jzs.com)
- Username: `admin`
- Password: `admin123`
-
-> The demo is for feature preview only. Do not save private API keys, tracker cookies, or personal data there.
+- **Backend**: Go, Gin, GORM, SQLite or PostgreSQL, optional Redis and OpenSearch
+- **Frontend**: React 18, Vite, TypeScript, Tailwind CSS, Zustand
+- **Deployment**: Standalone Docker Compose templates, amd64/arm64 images, single-binary releases

 ---

 ## Quick Start

-Docker Compose is the recommended path. Beginners do not need `.env`, bare-metal binaries, or source builds. Use the single-image SQLite template if you want the smallest possible setup.
+Docker Compose is the recommended path. The repo ships four **standalone** templates; no `.env` is required.

 ```bash
-mkdir -p MMTL
-cd MMTL
-# Simplest option: one MMTL container + SQLite
-curl -fsSL https://raw.githubusercontent.com/ShukeBta/MMTL/main/docker-compose.simple.yml -o docker-compose.yml
-# Or tier 1: MMTL + PostgreSQL
-# curl -fsSL https://raw.githubusercontent.com/ShukeBta/MMTL/main/docker-compose.yml -o docker-compose.yml
-```
+mkdir -p MMTL && cd MMTL

-Edit `docker-compose.yml`:
+# Simplest: one container with built-in SQLite
+curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.simple.yml -o docker-compose.yml

-```bash
-vi docker-compose.yml
-```
+# Or PostgreSQL tier for multi-user setups
+# curl -fsSL https://raw.githubusercontent.com/truewhile/MMTL/main/docker-compose.yml -o docker-compose.yml

-Start:
-
-```bash
 docker compose up -d
 ```

@@ -108,295 +82,46 @@ Open:
 http://SERVER_IP:18080
 ```

-Default login:
+Default login: `admin` / `admin123` — change the password immediately.
+
+Image:

 ```text
-Username: admin
-Password: admin123
+ghcr.io/truewhile/mmtl:latest
 ```

 ---

-## Docker Compose Recommended
+## Deployment tiers

-The repository `docker-compose.yml` is the lightweight recommended template: no `.env` required, and by default it only starts `MMTL + PostgreSQL`. This is the best starting point for most NAS users.
+Pick one compose file. Do **not** stack multiple `-f` files.

-If you already have an older `./data/mmtl.db`, the first start with the new compose file automatically imports it into PostgreSQL. Keep `./data`; it still stores the JWT secret, runtime data, and the old SQLite migration source.
+| Tier | File | Stack | Best for |
+| --- | --- | --- | --- |
+| Single image | `docker-compose.simple.yml` | MMTL + SQLite | Beginners, single-user, low-resource NAS |
+| Tier 1 | `docker-compose.yml` | MMTL + PostgreSQL | Most home NAS deployments |
+| Tier 2 | `docker-compose.standard.yml` | + Redis | Multi-user, frequent Emby client refreshes |
+| Tier 3 | `docker-compose.search.yml` | + OpenSearch | Very large libraries, advanced full-text search |

-### Deployment modes
+### Single-image notes

-| Mode | Command | Best for |
-| --- | --- | --- |
-| Single image: SQLite | `docker compose -f docker-compose.simple.yml up -d` | Beginners and single-user setups that want one image only, no PostgreSQL/Redis |
-| Lightweight: PG only | `docker compose up -d` | Most NAS devices, lowest resource use |
-| Standard: PG + Redis | `docker compose -f docker-compose.standard.yml up -d` | Multi-user use and frequent Emby client refreshes |
-| Search enhanced: PG + Redis + OpenSearch | `docker compose -f docker-compose.search.yml up -d` | Huge libraries and future standalone search indexing |
+- Only one MMTL container; database lives in `./data/mmtl.db`
+- Do **not** set `MMTL_DATABASE_DSN` or it switches to PostgreSQL
+- Back up `./data`; `./cache` can be rebuilt

-Each compose file is standalone. Do not stack multiple `-f` files together.
+### PostgreSQL notes

-The single-image `docker-compose.simple.yml` runs only MMTL with a built-in SQLite database — the simplest starting point. Do not set `MMTL_DATABASE_DSN` there, or it switches back to PostgreSQL. Move up to the PostgreSQL modes for multi-user or high-concurrency use (keep `./data` when you switch). Redis and OpenSearch are enhancement layers, not source databases. Do not enable OpenSearch by default on low-memory NAS devices.
+- Primary DB: `./postgres`; secrets and runtime files: `./data`
+- Existing `./data/mmtl.db` migrates automatically on first start
+- After migration, point `MMTL_DATABASE_DB_PATH` at a non-existent file to disable re-checks

-### Database Choice And Disabling SQLite
+### Backup

-The current Docker Compose setup uses PostgreSQL by default. SQLite is no longer the primary database in the recommended Docker deployment. The runtime database is controlled by:
-
-```yaml
-environment:
-  MMTL_DATABASE_TYPE: postgres
-  MMTL_DATABASE_DSN: postgres://mmtl:mmtl@postgres:5432/mmtl?sslmode=disable
-```
-
-`MMTL_DATABASE_DB_PATH` is only used as a one-time migration source for old SQLite data:
-
- Fresh installs: `docker compose up -d` uses PostgreSQL and does not create a new SQLite primary database.
- Upgrades: if `./data/mmtl.db` exists, the first start with the new compose file imports it into PostgreSQL.
- Migration fills missing rows by primary key and skips rows that already exist. If it fails partway through, a later start continues the remaining tables.
- After a successful import, PostgreSQL gets a completion marker in the `settings` table, so the old SQLite file is not imported again.
- Redis is a hot cache and OpenSearch is a search index; neither is a source database.
-
-Recommended SQLite to PostgreSQL upgrade flow:
-
-```bash
-docker compose pull mmtl
-docker compose up -d --no-deps mmtl
-docker compose logs -f mmtl
-```
-
-After you see `sqlite data migrated to postgres`, or after the web UI shows your users, libraries, and settings correctly, you can stop using the old SQLite file as a migration source.
-
-To make the deployment PostgreSQL-only after migration, keep PostgreSQL selected and point the old SQLite migration path at a non-existent file:
-
-> Only do this after the web UI confirms that users, libraries, settings, and media rows are already present in PostgreSQL.
-
-```yaml
-environment:
-  MMTL_DATABASE_TYPE: postgres
-  MMTL_DATABASE_DSN: postgres://mmtl:mmtl@postgres:5432/mmtl?sslmode=disable
-  MMTL_DATABASE_DB_PATH: /data/disabled-sqlite-migration.db
-```
-
-Then rename or move the old host-side SQLite file as an offline backup:
-
-```bash
-mv data/mmtl.db data/mmtl.sqlite.bak
-```
-
-For bare-metal or custom `config.yaml` deployments, use the same idea:
-
-```yaml
-database:
-  type: postgres
-  dsn: postgres://mmtl:mmtl@127.0.0.1:5432/mmtl?sslmode=disable
-  db_path: ""
-```
-
-Do not delete `./postgres`. After migration, it is the real primary database. Keep `./data` too, because it stores the JWT secret and runtime files.
-
-### Choose an image source
-
-Both image sources are supported. Pick one and put it in `image:`:
-
-| Source | Image | Best for |
-| --- | --- | --- |
-| GitHub Container Registry (GHCR) | `ghcr.io/shukebta/mmtl:latest` | Recommended default, follows repository releases |
-| Docker Hub | `shukbet/mmtl:latest` | Backup source when GHCR is slow or unavailable |
-
-To pin a version, first confirm the tag exists on the repository Packages page. Use this format:
-
-```yaml
-image: ghcr.io/shukebta/mmtl:<version-tag>
-# If GHCR does not have that tag, use Docker Hub as the backup:
-# image: shukbet/mmtl:MMTL-v0.0.72
-```
-
-For the simplest setup, keep GHCR `latest`.
-
-Manual pull examples:
-
-```bash
-# GitHub Container Registry
-docker pull ghcr.io/shukebta/mmtl:latest
-
-# Docker Hub backup
-docker pull shukbet/mmtl:latest
-```
-
-Focus on this part:
-
-```yaml
-volumes:
-  - ./data:/data
-  - ./cache:/cache
-  - ./media:/media
-  - ./downloads:/downloads
-```
-
-Meaning:
-
-| Host path | Container path | Purpose |
-| --- | --- | --- |
-| `./data` | app `/data` | Settings, JWT secret, old SQLite migration source; the primary DB is under `./postgres` |
-| `./cache` | app `/cache` | Cache; safe to clean when needed |
-| `./media` | `/media` | Media libraries; use `/media/...` in the web UI |
-| `./downloads` | `/downloads` | Download directory and organization source |
-| `./postgres` | PostgreSQL `/var/lib/postgresql/data` | New default primary database; back this up |
-| `./redis` | Redis `/data` | Used only in standard mode; hot cache, rebuildable |
-| `./opensearch` | OpenSearch `/usr/share/opensearch/data` | Used only in search-enhanced mode; higher memory use |
-
-If your NAS paths are:
-
-```text
-/vol1/1000/Media
-/vol1/1000/Downloads
-```
-
-change the compose file to:
-
-```yaml
-volumes:
-  - ./data:/data
-  - ./cache:/cache
-  - /vol1/1000/Media:/media
-  - /vol1/1000/Downloads:/downloads
-
-environment:
-  MMTL_MEDIA_DIR: /vol1/1000/Media
-  MMTL_DOWNLOAD_DIR: /vol1/1000/Downloads
-```
-
-Rules:
-
- The left side of `volumes` is the real path on your host/NAS.
- The right side is the container path. Keep `/media` and `/downloads` unless you know why you are changing them.
- In the web UI, create libraries with container paths such as `/media/Movies` or `/media/TV`.
- Do not write NAS absolute paths as `./vol1/...`; `./` means a folder under the current compose directory.
- On Windows Docker Desktop, paths like `D:/Media:/media` and `D:/Downloads:/downloads` are fine.
- If you only scan/play existing media and never organize into the library, you may add `:ro`; if you use organize/rename/ingest, the media mount must stay writable.
-
-### Minimal compose example
-
-The root `docker-compose.yml` follows this style:
-
-```yaml
-services:
-  mmtl:
-    # Pick one image source:
-    # GitHub Container Registry (GHCR):
-    image: ghcr.io/shukebta/mmtl:latest
-    # Docker Hub backup:
-    # image: shukbet/mmtl:latest
-
-    restart: unless-stopped
-    init: true
-    depends_on:
-      postgres:
-        condition: service_healthy
-
-    # Browser: http://SERVER_IP:18080
-    ports:
-      - "18080:8080"
-
-    # Let the container reach qBittorrent running on the host:
-    # qB URL example: http://host.docker.internal:8085
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-
-    volumes:
-      # Application data. Back this up before upgrades.
-      - ./data:/data
-      - ./cache:/cache
-
-      # Beginners can create ./media and ./downloads.
-      # NAS users should replace source with real absolute paths.
-      # create_host_path=false prevents Docker from silently creating an empty
-      # folder when the host path is wrong.
-      - type: bind
-        source: ./media
-        target: /media
-        bind:
-          create_host_path: false
-      - type: bind
-        source: ./downloads
-        target: /downloads
-        bind:
-          create_host_path: false
-
-    environment:
-      TZ: Asia/Shanghai
-      PUID: "1000"
-      PGID: "1000"
-
-      MMTL_APP_HOST: 0.0.0.0
-      MMTL_APP_PORT: 8080
-      MMTL_APP_WEB_DIR: /app/web/dist
-      MMTL_APP_DATA_DIR: /data
-
-      # Lightweight mode uses PostgreSQL by default.
-      # Old SQLite data migrates from this path on first start.
-      MMTL_DATABASE_TYPE: postgres
-      MMTL_DATABASE_DSN: postgres://mmtl:mmtl@postgres:5432/mmtl?sslmode=disable
-      # After migration, change this to /data/disabled-sqlite-migration.db to disable the SQLite migration source.
-      MMTL_DATABASE_DB_PATH: /data/mmtl.db
-      MMTL_CACHE_CACHE_DIR: /cache
-
-      # Use /media and /downloads in the web UI and downloader by default.
-      # Only set MMTL_*_DIR to real host paths when migrating old
-      # libraries/tasks that already stored host paths.
-      MMTL_MEDIA_DIR: /media
-      MMTL_MEDIA_CONTAINER_DIR: /media
-      MMTL_DOWNLOAD_DIR: /downloads
-      MMTL_DOWNLOAD_CONTAINER_DIR: /downloads
-
-  postgres:
-    image: postgres:16-alpine
-    restart: unless-stopped
-    environment:
-      POSTGRES_DB: mmtl
-      POSTGRES_USER: mmtl
-      POSTGRES_PASSWORD: mmtl
-    volumes:
-      - ./postgres:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U mmtl -d mmtl"]
-      interval: 10s
-      timeout: 5s
-      retries: 10
-
-```
-
-> Note: PostgreSQL is the primary database. Lightweight mode still has short in-process caching. Redis is a cross-process hot cache, and OpenSearch is a search enhancement layer; neither is a source database.
-
---
-
-## First-time Setup
-
-1. **Create a library**
-   - Go to the library page.
-   - Use a container path such as `/media/Movies`.
-   - Start a scan.
-
-2. **Connect qBittorrent**
-   - Go to download client settings.
-   - If qBittorrent runs on the host, try `http://host.docker.internal:8085`.
-
-3. **Configure metadata providers**
-   - Go to system settings / external APIs.
-   - Add TMDb, Bangumi, TheTVDB, Fanart, Douban, or other providers when needed.
-
-4. **Use external players**
-   - Add the server as an Emby/Jellyfin-compatible server.
-   - Server URL: `http://SERVER_IP:18080`.
-   - Use the username and password created in MMTL. No separate Emby server is required.
-   - Admins can create regular users in the web UI or Bot so each person can log in with their own account.
-
-5. **Use cloud playback**
-   - Configure OpenList, CloudDrive2, WebDAV, or another provider in storage settings.
-   - Choose STRMURL or 302 redirect playback in the admin settings.
-   - The enabled option takes priority. If both are disabled, playback falls back to the normal server playback path.
-
---
-
-## Update, Backup, Logs
+| Path | Notes |
+| --- | --- |
+| `./data` | JWT secret, config, SQLite DB or migration source |
+| `./postgres` | PostgreSQL primary DB |
+| `./cache`, `./redis`, `./opensearch` | Rebuildable |

 ### Update

@@ -405,181 +130,100 @@ docker compose pull mmtl
 docker compose up -d --no-deps mmtl
 ```

-### Logs
+---

-```bash
-docker compose logs -f mmtl
-tail -f ./data/logs/app.log
-tail -f ./data/logs/error.log
+## Path mapping
+
+The most common Docker mistake is mixing host paths with container paths.
+
+- Left side of `volumes` = real host/NAS path
+- Right side = container path; use `/media/...` in the web UI
+- Keep `MMTL_MEDIA_DIR` / `MMTL_DOWNLOAD_DIR` aligned with mounts when organizing or ingesting downloads
+
+Example:
+
+```yaml
+volumes:
+  - /vol1/1000/Media:/media
+  - /vol1/1000/Downloads:/downloads
+environment:
+  MMTL_MEDIA_DIR: /vol1/1000/Media
+  MMTL_MEDIA_CONTAINER_DIR: /media
+  MMTL_DOWNLOAD_DIR: /vol1/1000/Downloads
+  MMTL_DOWNLOAD_CONTAINER_DIR: /downloads
 ```

-The compose templates keep full application logs in `./data/logs/app.log` and split warnings/errors into `warn.log` and `error.log`. Keep `MMTL_LOGGING_LEVEL=info` while diagnosing subscription, site search, organizer, or STRM generation issues; temporarily switch to `debug` only when deeper tracing is needed.
+---

-Use a writable container path for STRM output, such as `/data/strm` or a mounted media path. Deployments that previously saved `/app/data/strm` are migrated automatically to the configured `MMTL_APP_DATA_DIR`, which defaults to `/data`.
+## First-time setup

-### Backup
-
-For the default PostgreSQL deployment, back up:
-
-```text
-data/
-postgres/
-```
-
-`postgres/` is the primary database and contains users, libraries, settings, and media metadata. `data/` stores the JWT secret, runtime files, and optional old SQLite migration source.
-
-If you enabled the extended modes, these are optional:
-
-```text
-redis/        # hot cache, safe to rebuild
-opensearch/   # search index, rebuildable; backing it up can save reindex time on huge libraries
-```
-
-`cache/` is usually not important. If you explicitly still use `database.type=sqlite`, the primary database remains `data/mmtl.db`.
-
-### Stop
-
-```bash
-docker compose down
-```
+1. Create a library with a container path such as `/media/Movies`, then scan
+2. Add metadata providers (TMDb, Bangumi, etc.) in system settings
+3. Optionally connect qBittorrent (`http://host.docker.internal:8085` when qB runs on the host)
+4. Optionally configure cloud accounts under STRM management
+5. Add the server in Emby-compatible players at `http://SERVER_IP:18080` using MMTL credentials

 ---

 ## FAQ

-### 1. The web page does not open
+**Library scan is slow**  
+Check path mapping and DB tier. Cloud scans also depend on API limits and folder size.

-Check the container:
+**qBittorrent downloads are not organized**  
+Ensure the download directory is mounted into the container and env vars match.

-```bash
-docker ps
-docker compose logs --tail=100 mmtl
-```
+**Hardlink fails with cross-device link**  
+Hardlinks require the same filesystem/subvolume; use copy or symlink across disks or cloud mounts.

-Then open:
-
-```text
-http://SERVER_IP:18080
-```
-
-### 2. The library cannot find files
-
-Most cases are path mistakes.
-
- Docker maps media to `/media`.
- In the web UI, use `/media/Movies`, not the original NAS path.
- Docker maps downloads to `/downloads`; use `/downloads` as the organization source when possible.
-
-### 3. qBittorrent cannot connect
-
-If qBittorrent is on the host, try:
-
-```text
-http://host.docker.internal:8085
-```
-
-If qBittorrent is on another machine, use that machine's LAN IP.
-
-### 4. NAS CPU usage is high
-
-Suggested settings:
-
- Set `ffprobe.max_concurrent` to `1`.
- Enable automatic organization, scrape-after-scan, and boot cloud scan only when you really need them.
- Avoid frequent full-library scans on large libraries. Prefer manual scan or scheduled night sync.
-
-### 5. Should I use `.env`?
-
-Beginners should not. Editing `docker-compose.yml` directly is easier to understand.
-
-`.env` is not required by the provided deployment templates. For the single-image template, edit `docker-compose.simple.yml` directly and only adjust the port, volume paths, and optional hardware device mapping.
+**External player cannot connect**  
+Use `http://IP:18080` and a MMTL user account; reverse proxies need correct external URL and HTTPS headers.

 ---

-## Features
-
-| Area | Features |
-| --- | --- |
-| Libraries | Movies, TV shows, anime, variety, music, adult content |
-| Metadata | NFO, local artwork, TMDb, TheTVDB, Bangumi, Douban, Fanart, JavBus/JavDB |
-| Playback | Web playback, HTTP Range, HLS transcoding, direct links, STRMURL, 302 redirect |
-| External clients | Emby-protocol compatible APIs; MMTL accounts can log in to third-party players |
-| User management | Multi-user accounts, admin/regular users, expiry dates, device management, Bot registration and redeem codes |
-| Downloads | qBittorrent, site search, subscriptions, post-download organization |
-| File manager | Browse, organize, copy, move, hardlink, symlink |
-| Operations | Task queue, recycle bin, duplicate files, notifications, logs |
-| AI | OpenAI-compatible API, AI search, recommendations, assistant |
-
-Directory hardlinks are handled by recreating the directory tree and hardlinking
-each contained file. Linux cannot hardlink a directory itself. Hardlinks still
-require the source and target files to be on the same filesystem/subvolume from
-inside the container; if media and downloads are separate bind mounts, disks,
-btrfs subvolumes, or cloud mounts, use copy or symlink instead.
-
 ## Development

-Regular users should use Docker. Developers can run:
+The backend embeds `web/dist` via `go:embed`. Build the frontend first.

 ```bash
-go run ./cmd/server
-```
+npm --prefix web ci
+npm --prefix web run build

-Frontend:
-
-```bash
-cd web
-npm install
-npm run dev
-```
-
-Tests:
-
-```bash
 go test ./...
-cd web && npm run build
+go run ./cmd/server
+npm --prefix web run dev
 ```

---
-
-## Community and Friends
-
- Telegram group: <https://t.me/MMTL>
- NodeSeek: [https://www.nodeseek.com/](https://www.nodeseek.com/)
- LINUX DO: [https://linux.do/](https://linux.do/)
+Release builds ship single-file binaries for Windows, Linux, and macOS on amd64 and arm64.

 ---

-## Donation
+## Acknowledgements

-If MMTL saves you time, feel free to buy the author a bowl of noodles.
+MMTL is forked from and continues to evolve [MediaStationGo](https://github.com/ShukeBta/MediaStationGo). Thank you to the upstream project for the media-library architecture, Emby-protocol compatibility, and self-hosted foundation.

-<img width="200" height="200" alt="WeChat Donation QR" src="https://github.com/user-attachments/assets/d6077de5-8305-400d-8b82-470ef05d926e" />
+Many cloud sync, STRM, and media-organization ideas in this project were also informed by [qmediasync](https://github.com/qicfan/qmediasync). Thank you for the reference implementation and design patterns.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before opening issues or pull requests.

 ---

 ## Star History

-<a href="https://www.star-history.com/?repos=ShukeBta%2FMMTL&type=date&legend=top-left">
+<a href="https://www.star-history.com/?repos=truewhile%2FMMTL&type=date&legend=top-left">
 <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=ShukeBta/MMTL&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=ShukeBta/MMTL&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=ShukeBta/MMTL&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=truewhile/MMTL&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=truewhile/MMTL&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=truewhile/MMTL&type=date&legend=top-left" />
 </picture>
 </a>

 ---

-## License and Non-Commercial Statement
+## License

-This project uses `GPL-3.0` as its base license. See [LICENSE](LICENSE).
-
-The maintainers also state and request:
-
- The project is intended for personal learning, home NAS, self-hosted media, non-commercial research, and community collaboration.
- Without explicit written permission from the author, do not use this project or derivative versions for commercial resale, paid hosting, paid SaaS, pre-installed commercial devices, closed-source redistribution, or other profit-oriented commercial use.
- For commercial cooperation, enterprise deployment, custom development, integrated redistribution, or commercial authorization, contact the author first.
- If there is any interpretive difference between this README and the formal `GPL-3.0` license text, the code license is governed by [LICENSE](LICENSE); commercial usage should additionally obtain author permission.
-
---
-
-<p align="center">Made with ❤️ by ShukeBta</p>
+This project is licensed under [GPL-3.0](LICENSE).
@@ -7,7 +7,7 @@ MMTL 是自托管媒体系统，常部署在 NAS、家庭网络、Docker、反
 我们优先支持以下版本和部署方式的安全修复：

 - 当前 `main` 分支。
- 最新发布镜像：`ghcr.io/shukebta/mmtl:latest`。
+- 最新发布镜像：`ghcr.io/truewhile/mmtl:latest`。
 - README 中推荐的 Docker Compose 第一档、第二档、第三档部署方式。

 历史版本、私有魔改镜像、未公开补丁分支和非标准部署仍可报告，但维护者可能要求先在最新 `main` 或最新镜像中复现。
@@ -1 +1 @@
-0.0.49
+0.0.70
@@ -173,6 +173,11 @@ func isFrontendLibraryRoute(path string) bool {
 	if strings.Contains(id, "/") {
 		return false
 	}
+	// 远程 Emby 挂载库的伪装 ID（embyremote~account~remote）也是前端库路由，
+	// 需要交给 SPA 而非当作 Emby API 路径 404。
+	if strings.HasPrefix(id, "embyremote~") {
+		return true
+	}
 	if len(id) != 36 {
 		return false
 	}
@@ -20,11 +20,7 @@

 services:
  mmtl:
-    # 镜像二选一：
-    # 方式一：GitHub 仓库镜像 GHCR（默认，推荐）
-    image: ghcr.io/shukebta/mmtl:latest
-    # 方式二：Docker Hub 备用（GHCR 拉取慢或不可用时使用）
-    # image: shukbet/mmtl:latest
+    image: ghcr.io/truewhile/mmtl:latest

    restart: unless-stopped
    init: true
@@ -101,7 +97,7 @@ services:
      MMTL_SEARCH_OPENSEARCH_URL: http://opensearch:9200
      MMTL_SEARCH_INDEX: mmtl_media

-      MMTL_UPDATE_IMAGE: ghcr.io/shukebta/mmtl:latest
+      MMTL_UPDATE_IMAGE: ghcr.io/truewhile/mmtl:latest

      # 默认推荐在网页里使用容器路径 /media。
      # 如果旧媒体库已经保存了宿主机路径 /vol1/1000/Media，
@@ -13,9 +13,7 @@

 services:
  mmtl:
-    image: ghcr.io/shukebta/mmtl:latest
-    # Docker Hub 备用：
-    # image: shukbet/mmtl:latest
+    image: ghcr.io/truewhile/mmtl:latest

    container_name: mmtl
    restart: unless-stopped
@@ -17,11 +17,7 @@

 services:
  mmtl:
-    # 镜像二选一：
-    # 方式一：GitHub 仓库镜像 GHCR（默认，推荐）
-    image: ghcr.io/shukebta/mmtl:latest
-    # 方式二：Docker Hub 备用（GHCR 拉取慢或不可用时使用）
-    # image: shukbet/mmtl:latest
+    image: ghcr.io/truewhile/mmtl:latest

    restart: unless-stopped
    init: true
@@ -92,7 +88,7 @@ services:
      MMTL_CACHE_REDIS_URL: redis://redis:6379/0
      MMTL_CACHE_CACHE_DIR: /cache

-      MMTL_UPDATE_IMAGE: ghcr.io/shukebta/mmtl:latest
+      MMTL_UPDATE_IMAGE: ghcr.io/truewhile/mmtl:latest

      # 路径换算配置。左边宿主机真实路径要和 volumes 左边保持一致。
      MMTL_MEDIA_DIR: /media
@@ -16,11 +16,7 @@

 services:
  mmtl:
-    # 镜像二选一：
-    # 方式一：GitHub 仓库镜像 GHCR（默认，推荐）
-    image: ghcr.io/shukebta/mmtl:latest
-    # 方式二：Docker Hub 备用（GHCR 拉取慢或不可用时使用）
-    # image: shukbet/mmtl:latest
+    image: ghcr.io/truewhile/mmtl:latest

    restart: unless-stopped
    init: true
@@ -112,7 +108,7 @@ services:
      MMTL_CACHE_CACHE_DIR: /cache

      # 管理面板热更新默认拉取此镜像，并用 Watchtower 一次性重建当前容器。
-      MMTL_UPDATE_IMAGE: ghcr.io/shukebta/mmtl:latest
+      MMTL_UPDATE_IMAGE: ghcr.io/truewhile/mmtl:latest

      # 路径换算配置。
      # 默认推荐在网页里使用容器路径 /media。
@@ -68,6 +68,7 @@ require (
 	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.11 // indirect
+	github.com/ulikunitz/xz v0.5.12 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	golang.org/x/arch v0.3.0 // indirect
@@ -152,6 +152,8 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU=
 github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
+github.com/ulikunitz/xz v0.5.12 h1:37Nm15o69RwBkXM0J6A5OlE67RZTfzUxTj8fB3dfcsc=
+github.com/ulikunitz/xz v0.5.12/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
@@ -29,7 +29,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("database.dsn", "")
 	v.SetDefault("database.wal_mode", true)
 	v.SetDefault("database.busy_timeout", 5000)
-	v.SetDefault("database.cache_size", -20000)
+	v.SetDefault("database.cache_size", -40000)
 	v.SetDefault("database.max_open_conns", defaultDatabaseMaxOpenConns)
 	v.SetDefault("database.max_idle_conns", defaultDatabaseMaxIdleConns)

@@ -43,6 +43,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("logging.max_backups", 10)

 	v.SetDefault("cache.cache_dir", "./cache")
+	v.SetDefault("cache.images_max_size_mb", 500)
 	v.SetDefault("cache.cleanup_interval_min", 60)
 	v.SetDefault("cache.redis_url", "")
 	v.SetDefault("cache.redis_prefix", "mmtl")
@@ -44,6 +44,9 @@ func (c *Config) normalize() error {
 	if c.Cache.CacheDir == "" {
 		c.Cache.CacheDir = filepath.Join(c.App.DataDir, "cache")
 	}
+	if c.Cache.ImagesMaxSizeMB < 0 {
+		c.Cache.ImagesMaxSizeMB = 0
+	}
 	if c.Cache.RedisPrefix == "" {
 		c.Cache.RedisPrefix = "mmtl"
 	}
@@ -44,11 +44,11 @@ type TranscoderConfig struct {

 // AppConfig 保存运行时应用参数。
 type AppConfig struct {
-	Port        int    `mapstructure:"port"`
-	Debug       bool   `mapstructure:"debug"`
-	Env         string `mapstructure:"env"`
-	DataDir     string `mapstructure:"data_dir"`
-	WebDir      string `mapstructure:"web_dir"`
+	Port    int    `mapstructure:"port"`
+	Debug   bool   `mapstructure:"debug"`
+	Env     string `mapstructure:"env"`
+	DataDir string `mapstructure:"data_dir"`
+	WebDir  string `mapstructure:"web_dir"`
 	// HTTPSEnabled 是否仅通过 HTTPS 提供访问。启用时必须同时配置
 	// SSLCert / SSLKey（或 SSLCertPath / SSLKeyPath），保存后服务会热切换到 HTTPS。
 	HTTPSEnabled bool `mapstructure:"https_enabled"`
@@ -59,7 +59,7 @@ type AppConfig struct {
 	// SSLCertPath 是 SSL 证书文件路径；非空时优先于 SSLCert 从文件读取。
 	SSLCertPath string `mapstructure:"ssl_cert_path"`
 	// SSLKeyPath 是 SSL 私钥文件路径；非空时优先于 SSLKey 从文件读取。
-	SSLKeyPath string `mapstructure:"ssl_key_path"`
+	SSLKeyPath  string `mapstructure:"ssl_key_path"`
 	FFmpegPath  string `mapstructure:"ffmpeg_path"`
 	FFprobePath string `mapstructure:"ffprobe_path"`
 	// FFprobeMaxConcurrent limits concurrent ffprobe/ffmpeg metadata probes.
@@ -116,6 +116,7 @@ type LoggingConfig struct {
 // CacheConfig 控制磁盘转码/刮削缓存。
 type CacheConfig struct {
 	CacheDir           string `mapstructure:"cache_dir"`
+	ImagesMaxSizeMB    int    `mapstructure:"images_max_size_mb"`
 	MaxDiskUsageMB     int    `mapstructure:"max_disk_usage_mb"`
 	TTLHours           int    `mapstructure:"ttl_hours"`
 	AutoCleanup        bool   `mapstructure:"auto_cleanup"`
@@ -408,13 +408,13 @@ func TestOpenSQLiteMigrationSourceUsesFallbackSourcePath(t *testing.T) {
 			_ = sqlDB2.Close()
 		}
 	}()
-		_, copied, err := copyModelTables(src2, dst, 2)
-		if err != nil {
-			t.Fatal(err)
-		}
-		if copied != 2 {
-			t.Fatalf("copied rows = %d, want 2", copied)
-		}
+	_, copied, err := copyModelTables(src2, dst, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if copied != 2 {
+		t.Fatalf("copied rows = %d, want 2", copied)
+	}
 	var userCount int64
 	if err := dst.Model(&model.User{}).Where("username = ?", "real-admin").Count(&userCount).Error; err != nil {
 		t.Fatal(err)
@@ -20,12 +20,23 @@ func AutoMigrate(db *gorm.DB) error {
 	if err := ensureLibraryRootsCompatibility(db); err != nil {
 		return err
 	}
+	if err := ensureEmbyMountsCompatibility(db); err != nil {
+		return err
+	}
 	if isSQLite(db) {
-		return ensureMediaSearchIndex(db)
+		if err := ensureMediaSearchIndex(db); err != nil {
+			return err
+		}
+		return ensureSQLiteQueryOptimizer(db)
 	}
 	return nil
 }

+func ensureSQLiteQueryOptimizer(db *gorm.DB) error {
+	// Refresh planner statistics so indexes on large media tables are used.
+	return db.Exec("ANALYZE").Error
+}
+
 func ensurePostgresColumnCompatibility(db *gorm.DB) error {
 	if !isPostgres(db) {
 		return nil
@@ -77,3 +88,25 @@ func ensurePerformanceIndexes(db *gorm.DB) error {
 	}
 	return nil
 }
+
+func ensureEmbyMountsCompatibility(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&model.EmbyMount{}) {
+		return nil
+	}
+	if !db.Migrator().HasColumn(&model.EmbyMount{}, "sort_order") {
+		if err := db.Migrator().AddColumn(&model.EmbyMount{}, "sort_order"); err != nil {
+			return err
+		}
+	}
+	// 针对已有数据：如果存在多个 sort_order=0/NULL 的记录，按创建时间顺序赋予稳定递增的序号
+	var zeroCount int64
+	if err := db.Model(&model.EmbyMount{}).Where("sort_order = 0 OR sort_order IS NULL").Count(&zeroCount).Error; err == nil && zeroCount > 1 {
+		var mounts []model.EmbyMount
+		if err := db.Order("created_at asc, id asc").Find(&mounts).Error; err == nil {
+			for i, m := range mounts {
+				_ = db.Exec("UPDATE emby_mounts SET sort_order = ? WHERE id = ?", i, m.ID).Error
+			}
+		}
+	}
+	return nil
+}
@@ -0,0 +1,62 @@
+package database
+
+import (
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+func TestEnsureEmbyMountsCompatibility(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Create a table without sort_order simulating an older schema
+	if err := db.Exec(`CREATE TABLE emby_mounts (
+		id varchar(36) PRIMARY KEY,
+		created_at datetime,
+		updated_at datetime,
+		deleted_at datetime,
+		account_id text,
+		remote_view_id text,
+		remote_view_name text,
+		collection_type text,
+		name text,
+		proxy_play numeric DEFAULT false,
+		enabled numeric DEFAULT true
+	)`).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// Insert older rows
+	now := time.Now()
+	_ = db.Exec("INSERT INTO emby_mounts (id, name, created_at) VALUES (?, ?, ?)", "m1", "Mount 1", now.Add(-2*time.Hour)).Error
+	_ = db.Exec("INSERT INTO emby_mounts (id, name, created_at) VALUES (?, ?, ?)", "m2", "Mount 2", now.Add(-1*time.Hour)).Error
+
+	// Run compatibility migration
+	if err := ensureEmbyMountsCompatibility(db); err != nil {
+		t.Fatalf("ensureEmbyMountsCompatibility failed: %v", err)
+	}
+
+	// Verify column sort_order exists and values are initialized sequentially
+	if !db.Migrator().HasColumn(&model.EmbyMount{}, "sort_order") {
+		t.Fatal("expected sort_order column to be added")
+	}
+
+	var m1, m2 model.EmbyMount
+	if err := db.Where("id = ?", "m1").First(&m1).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Where("id = ?", "m2").First(&m2).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	if m1.SortOrder != 0 || m2.SortOrder != 1 {
+		t.Fatalf("unexpected sort orders: m1=%d, m2=%d", m1.SortOrder, m2.SortOrder)
+	}
+}
@@ -114,7 +114,10 @@ func buildSQLiteDSN(cfg *config.Config) string {
 	if cfg.Database.CacheSize != 0 {
 		dsn += fmt.Sprintf("&_pragma=cache_size(%d)", cfg.Database.CacheSize)
 	}
-	dsn += "&_pragma=temp_store(MEMORY)&_pragma=mmap_size(268435456)"
+	dsn += "&_pragma=temp_store(MEMORY)&_pragma=mmap_size(536870912)"
+	if cfg.Database.WALMode {
+		dsn += "&_pragma=wal_autocheckpoint(1000)"
+	}
 	return dsn
 }

@@ -3,6 +3,7 @@ package handler

 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"net/http"
 	"strings"
@@ -27,6 +28,9 @@ func listUsersHandler(svc *service.Container) gin.HandlerFunc {
 		if svc.Sessions != nil {
 			svc.Sessions.ApplyToUsers(c.Request.Context(), users)
 		}
+		for i := range users {
+			users[i].PopulateComputedFields()
+		}
 		c.JSON(http.StatusOK, users)
 	}
 }
@@ -198,6 +202,64 @@ func updateUserStatusHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
+		updated.PopulateComputedFields()
+		c.JSON(http.StatusOK, updated)
+	}
+}
+
+type adminUpdateUserLibrariesReq struct {
+	AllowedLibraryIDs *[]string `json:"allowed_library_ids"`
+}
+
+func updateUserLibrariesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req adminUpdateUserLibrariesReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		userID := c.Param("id")
+		user, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if user == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+			return
+		}
+
+		var rawJSON string
+		if req.AllowedLibraryIDs != nil && len(*req.AllowedLibraryIDs) > 0 {
+			var cleanIDs []string
+			for _, id := range *req.AllowedLibraryIDs {
+				trimmed := strings.TrimSpace(id)
+				if trimmed != "" {
+					cleanIDs = append(cleanIDs, trimmed)
+				}
+			}
+			if len(cleanIDs) > 0 {
+				data, err := json.Marshal(cleanIDs)
+				if err != nil {
+					c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+					return
+				}
+				rawJSON = string(data)
+			}
+		}
+
+		updates := map[string]any{"allowed_library_ids": rawJSON}
+		if err := svc.Repo.User.UpdateFields(c.Request.Context(), userID, updates); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		updated, err := svc.Repo.User.FindByID(c.Request.Context(), userID)
+		if err != nil || updated == nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to reload user"})
+			return
+		}
+		updated.PopulateComputedFields()
 		c.JSON(http.StatusOK, updated)
 	}
 }
@@ -64,6 +64,9 @@ func updateSettingHandler(svc *service.Container) gin.HandlerFunc {
 		if req.Key == "transcode.hw_enabled" || req.Key == "transcode.hw_accel" || req.Key == "transcoder.hardware_accel" || req.Key == "transcoder.encoder" {
 			svc.Transcoder.StopAll()
 		}
+		if req.Key == "cache.images_max_size_mb" && svc.Scheduler != nil {
+			_ = svc.Scheduler.RunNowAsync(c.Request.Context(), "image_cache_cleanup")
+		}
 		c.Status(http.StatusNoContent)
 	}
 }
@@ -3,6 +3,7 @@ package handler
 import (
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"

 	"github.com/gin-gonic/gin"
@@ -47,3 +48,88 @@ func TestDeleteUserRefusesRecentRealtimeSession(t *testing.T) {
 		t.Fatal("recent realtime user should not be deleted")
 	}
 }
+
+func TestUpdateUserLibraries(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	user := model.User{Base: model.Base{ID: "u1"}, Username: "alice", PasswordHash: "x", Role: "user", IsActive: true}
+	lib1 := model.Library{Base: model.Base{ID: "lib-1"}, Name: "电影", Type: "movie", Path: "/movie"}
+	lib2 := model.Library{Base: model.Base{ID: "lib-2"}, Name: "剧集", Type: "tv", Path: "/tv"}
+	lib3 := model.Library{Base: model.Base{ID: "lib-3"}, Name: "动漫", Type: "anime", Path: "/anime"}
+	if err := repos.DB.Create(&user).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.DB.Create(&[]model.Library{lib1, lib2, lib3}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	svc := &service.Container{Repo: repos}
+	router := gin.New()
+	router.PATCH("/admin/users/:id/libraries", updateUserLibrariesHandler(svc))
+
+	// 1. 设置限制为 lib-1 和 lib-2
+	body := `{"allowed_library_ids":["lib-1","lib-2"]}`
+	req := httptest.NewRequest(http.MethodPatch, "/admin/users/u1/libraries", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body = %s", w.Code, w.Body.String())
+	}
+
+	found, err := repos.User.FindByID(t.Context(), "u1")
+	if err != nil || found == nil {
+		t.Fatal("user not found")
+	}
+	allowed := found.DecodeAllowedLibraryIDs()
+	if len(allowed) != 2 || allowed[0] != "lib-1" || allowed[1] != "lib-2" {
+		t.Fatalf("expected [lib-1, lib-2], got %v", allowed)
+	}
+
+	// 验证可见性
+	vis := service.UserDefaultMediaVisibility(t.Context(), repos, "u1")
+	if len(vis.AllowedLibraryIDs) != 2 {
+		t.Fatalf("expected 2 allowed libraries, got %v", vis.AllowedLibraryIDs)
+	}
+	if !service.LibraryVisibleForUser(t.Context(), repos, lib1, vis) {
+		t.Fatal("lib1 should be visible")
+	}
+	if !service.LibraryVisibleForUser(t.Context(), repos, lib2, vis) {
+		t.Fatal("lib2 should be visible")
+	}
+	if service.LibraryVisibleForUser(t.Context(), repos, lib3, vis) {
+		t.Fatal("lib3 should not be visible")
+	}
+
+	// 2. 清空限制，恢复全部可见
+	bodyEmpty := `{"allowed_library_ids":[]}`
+	reqEmpty := httptest.NewRequest(http.MethodPatch, "/admin/users/u1/libraries", strings.NewReader(bodyEmpty))
+	reqEmpty.Header.Set("Content-Type", "application/json")
+	wEmpty := httptest.NewRecorder()
+	router.ServeHTTP(wEmpty, reqEmpty)
+
+	if wEmpty.Code != http.StatusOK {
+		t.Fatalf("status = %d body = %s", wEmpty.Code, wEmpty.Body.String())
+	}
+
+	foundReset, _ := repos.User.FindByID(t.Context(), "u1")
+	if len(foundReset.DecodeAllowedLibraryIDs()) != 0 {
+		t.Fatalf("expected nil or empty, got %v", foundReset.DecodeAllowedLibraryIDs())
+	}
+
+	visReset := service.UserDefaultMediaVisibility(t.Context(), repos, "u1")
+	if len(visReset.AllowedLibraryIDs) != 0 {
+		t.Fatalf("expected no library restrictions, got %v", visReset.AllowedLibraryIDs)
+	}
+	if !service.LibraryVisibleForUser(t.Context(), repos, lib3, visReset) {
+		t.Fatal("lib3 should now be visible")
+	}
+}
@@ -89,6 +89,7 @@ func meHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 			return
 		}
+		u.PopulateComputedFields()
 		c.JSON(http.StatusOK, u)
 	}
 }
@@ -0,0 +1,148 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"github.com/golang-jwt/jwt/v5"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+	"github.com/ShukeBta/MMTL/internal/middleware"
+	"github.com/ShukeBta/MMTL/internal/model"
+	"github.com/ShukeBta/MMTL/internal/repository"
+	"github.com/ShukeBta/MMTL/internal/service"
+)
+
+func TestMountedEmbyPlayingProgressAndResumePipeline(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(model.AllModels()...); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+
+	repos := repository.New(db)
+	user := &model.User{
+		Base:         model.Base{ID: "user-1"},
+		Username:     "test_viewer",
+		PasswordHash: "x",
+		Role:         "user",
+		Tier:         "free",
+		IsActive:     true,
+	}
+	if err := repos.User.Create(t.Context(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	cfg := &config.Config{}
+	logger := zap.NewNop()
+	svc := &service.Container{
+		Repo:     repos,
+		Emby:     service.NewEmbyService(cfg, logger, repos),
+		Sessions: service.NewSessionTrackerService(logger),
+		Playback: service.NewPlaybackService(logger, repos),
+	}
+
+	router := gin.New()
+	// 注册带认证的路由，模拟已登录用户
+	router.Use(func(c *gin.Context) {
+		c.Set(middleware.CtxUserID, user.ID)
+		c.Next()
+	})
+	router.POST("/Sessions/Playing/Progress", embyPlayingProgressHandler(svc))
+	router.GET("/Items", embyItemsHandler(svc))
+	router.GET("/Users/:userId/Items/Resume", embyResumeItemsHandler(svc))
+	router.GET("/Sessions", embySessionsHandler(svc))
+
+	remoteMediaID := service.EncodeEmbyRemoteID("mount-1", "remote-item-123")
+
+	// 1. 测试上报进度：客户端使用小写 query 参数 itemId / positionTicks
+	progressReq := httptest.NewRequest(
+		http.MethodPost,
+		"/Sessions/Playing/Progress?itemId="+remoteMediaID+"&positionTicks=300000000&runTimeTicks=1000000000",
+		nil,
+	)
+	wProgress := httptest.NewRecorder()
+	router.ServeHTTP(wProgress, progressReq)
+	if wProgress.Code != http.StatusNoContent {
+		t.Fatalf("progress status = %d, body = %s", wProgress.Code, wProgress.Body.String())
+	}
+
+	// 验证已持久化到 PlaybackHistory
+	var hist model.PlaybackHistory
+	if err := db.Where("user_id = ? AND media_id = ?", user.ID, remoteMediaID).First(&hist).Error; err != nil {
+		t.Fatalf("playback history not saved: %v", err)
+	}
+	if hist.PositionMs != 30000 {
+		t.Fatalf("expected position_ms = 30000, got %d", hist.PositionMs)
+	}
+
+	// 2. 测试 Filters=IsResumable 能够包含该远程条目
+	resumableReq := httptest.NewRequest(
+		http.MethodGet,
+		"/Items?Filters=IsResumable",
+		nil,
+	)
+	wResumable := httptest.NewRecorder()
+	router.ServeHTTP(wResumable, resumableReq)
+	if wResumable.Code != http.StatusOK {
+		t.Fatalf("items resumable status = %d, body = %s", wResumable.Code, wResumable.Body.String())
+	}
+	var resumableEnvelope map[string]any
+	if err := json.Unmarshal(wResumable.Body.Bytes(), &resumableEnvelope); err != nil {
+		t.Fatalf("decode resumable: %v", err)
+	}
+	// 因为没有配置真实的远程客户端连接，该远程条目在当前离线测试中不会 panic 崩溃，并且正常响应 Envelope
+	if resumableEnvelope["TotalRecordCount"] == nil {
+		t.Fatalf("missing TotalRecordCount in resumable envelope")
+	}
+
+	// 3. 测试 /Users/:userId/Items/Resume 别名路由
+	resumeAliasReq := httptest.NewRequest(
+		http.MethodGet,
+		"/Users/"+user.ID+"/Items/Resume",
+		nil,
+	)
+	wResumeAlias := httptest.NewRecorder()
+	router.ServeHTTP(wResumeAlias, resumeAliasReq)
+	if wResumeAlias.Code != http.StatusOK {
+		t.Fatalf("resume alias status = %d, body = %s", wResumeAlias.Code, wResumeAlias.Body.String())
+	}
+
+	// 4. 测试 /Sessions 返回 NowPlayingItem
+	sessionsReq := httptest.NewRequest(http.MethodGet, "/Sessions", nil)
+	wSessions := httptest.NewRecorder()
+	router.ServeHTTP(wSessions, sessionsReq)
+	if wSessions.Code != http.StatusOK {
+		t.Fatalf("sessions status = %d, body = %s", wSessions.Code, wSessions.Body.String())
+	}
+	var sessionsList []map[string]any
+	if err := json.Unmarshal(wSessions.Body.Bytes(), &sessionsList); err != nil {
+		t.Fatalf("decode sessions: %v", err)
+	}
+	if len(sessionsList) == 0 {
+		t.Fatalf("expected at least 1 session")
+	}
+	nowPlaying, ok := sessionsList[0]["NowPlayingItem"].(map[string]any)
+	if !ok || nowPlaying["Id"] != remoteMediaID {
+		t.Fatalf("expected NowPlayingItem with id %q, got %#v", remoteMediaID, sessionsList[0]["NowPlayingItem"])
+	}
+}
+
+func signMockToken(secret, userID string) string {
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
+		"sub": userID,
+		"exp": time.Now().Add(time.Hour).Unix(),
+	})
+	s, _ := token.SignedString([]byte(secret))
+	return s
+}
@@ -0,0 +1,222 @@
+// Emby 挂载管理 HTTP 层：远程 Emby 服务器（账号）下的媒体库挂载 CRUD，
+// 以及账号远程媒体库（View）列表预览。
+package handler
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+	"github.com/ShukeBta/MMTL/internal/service"
+)
+
+// embyMountView 挂载的对外 JSON（附带账号信息）。
+type embyMountView struct {
+	model.EmbyMount
+	AccountName string `json:"account_name"`
+}
+
+// embyMountInput 创建挂载的请求体（单个或批量）。
+type embyMountInput struct {
+	AccountID string          `json:"account_id" binding:"required"`
+	Views     []embyViewInput `json:"views" binding:"required,min=1"`
+}
+
+type embyViewInput struct {
+	RemoteViewID   string `json:"remote_view_id" binding:"required"`
+	RemoteViewName string `json:"remote_view_name"`
+	CollectionType string `json:"collection_type"`
+	Name           string `json:"name"`
+	ProxyPlay      bool   `json:"proxy_play"`
+}
+
+func embyMountViews(mounts []model.EmbyMount, accounts map[string]string) []embyMountView {
+	out := make([]embyMountView, 0, len(mounts))
+	for _, m := range mounts {
+		out = append(out, embyMountView{EmbyMount: m, AccountName: accounts[m.AccountID]})
+	}
+	return out
+}
+
+// embyAccountViewsHandler 列出账号上的远程媒体库（View），供挂载选择。
+func embyAccountViewsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		acct := svc.EmbyRemote.AccountByID(c.Request.Context(), c.Param("id"))
+		if acct == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "账号不存在或已禁用"})
+			return
+		}
+		views, err := svc.EmbyRemote.RemoteViews(c.Request.Context(), acct)
+		if err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		type viewEntry struct {
+			RemoteViewID   string `json:"remote_view_id"`
+			RemoteViewName string `json:"remote_view_name"`
+			CollectionType string `json:"collection_type"`
+			ChildCount     int    `json:"child_count"`
+			AlreadyMounted bool   `json:"already_mounted"`
+		}
+		mounted := map[string]bool{}
+		if mounts, err := svc.EmbyRemote.ListMountsByAccount(c.Request.Context(), acct.ID); err == nil {
+			for _, m := range mounts {
+				mounted[m.RemoteViewID] = true
+			}
+		}
+		out := make([]viewEntry, 0, len(views))
+		for _, v := range views {
+			viewID := service.RemoteItemIDString(v)
+			if strings.TrimSpace(viewID) == "" {
+				continue
+			}
+			out = append(out, viewEntry{
+				RemoteViewID:   viewID,
+				RemoteViewName: service.RemoteItemNameString(v),
+				CollectionType: service.RemoteItemCollectionType(v),
+				ChildCount:     service.RemoteItemChildCount(v),
+				AlreadyMounted: mounted[viewID],
+			})
+		}
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+// listEmbyMountsHandler 列出全部挂载。
+func listEmbyMountsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		mounts, err := svc.EmbyRemote.ListMounts(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		names := map[string]string{}
+		if accounts, err := svc.EmbyRemote.ListAccounts(c.Request.Context()); err == nil {
+			for _, a := range accounts {
+				names[a.ID] = a.Name
+			}
+		}
+		out := embyMountViews(mounts, names)
+		if out == nil {
+			out = []embyMountView{}
+		}
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+// createEmbyMountsHandler 批量创建挂载（同一账号下的多个远程媒体库）。
+func createEmbyMountsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req embyMountInput
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		mounts := make([]*model.EmbyMount, 0, len(req.Views))
+		for _, v := range req.Views {
+			mounts = append(mounts, &model.EmbyMount{
+				AccountID:      req.AccountID,
+				RemoteViewID:   v.RemoteViewID,
+				RemoteViewName: v.RemoteViewName,
+				CollectionType: v.CollectionType,
+				Name:           v.Name,
+				ProxyPlay:      v.ProxyPlay,
+				Enabled:        true,
+			})
+		}
+		if _, err := svc.EmbyRemote.CreateMounts(c.Request.Context(), mounts); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true, "created": len(mounts)})
+	}
+}
+
+// fullMountEmbyAccountHandler 全量挂载：把账号所有远程媒体库一次挂载进来。
+func fullMountEmbyAccountHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		acct := svc.EmbyRemote.AccountByID(c.Request.Context(), c.Param("id"))
+		if acct == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "账号不存在或已禁用"})
+			return
+		}
+		proxy := c.Query("proxy") == "1" || c.Query("proxy") == "true"
+		n, err := svc.EmbyRemote.FullMountAccount(c.Request.Context(), acct, proxy)
+		if err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true, "created": n})
+	}
+}
+
+// updateEmbyMountHandler 更新挂载（显示名 / 代理开关 / 启用）。
+func updateEmbyMountHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req struct {
+			Name      *string `json:"name"`
+			ProxyPlay *bool   `json:"proxy_play"`
+			Enabled   *bool   `json:"enabled"`
+		}
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		mount, err := svc.EmbyRemote.MountByID(c.Request.Context(), c.Param("id"))
+		if err != nil || mount == nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": "挂载不存在"})
+			return
+		}
+		if req.Name != nil {
+			mount.Name = *req.Name
+		}
+		if req.ProxyPlay != nil {
+			mount.ProxyPlay = *req.ProxyPlay
+		}
+		if req.Enabled != nil {
+			mount.Enabled = *req.Enabled
+		}
+		if _, err := svc.EmbyRemote.UpdateMount(c.Request.Context(), mount.ID, mount); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, mount)
+	}
+}
+
+// deleteEmbyMountHandler 删除挂载。
+func deleteEmbyMountHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if err := svc.EmbyRemote.DeleteMount(c.Request.Context(), c.Param("id")); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true})
+	}
+}
+
+type reorderEmbyMountsReq struct {
+	IDs []string `json:"ids" binding:"required"`
+}
+
+// reorderEmbyMountsHandler 批量重排挂载媒体库顺序。
+func reorderEmbyMountsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var req reorderEmbyMountsReq
+		if err := c.ShouldBindJSON(&req); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		if svc.EmbyRemote == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "emby remote service not available"})
+			return
+		}
+		if err := svc.EmbyRemote.ReorderMounts(c.Request.Context(), req.IDs); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true})
+	}
+}
@@ -0,0 +1,65 @@
+package handler
+
+import (
+	"bytes"
+	"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/ShukeBta/MMTL/internal/database"
+	"github.com/ShukeBta/MMTL/internal/model"
+	"github.com/ShukeBta/MMTL/internal/repository"
+	"github.com/ShukeBta/MMTL/internal/service"
+)
+
+func TestReorderEmbyMountsHandler(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := database.AutoMigrate(db); err != nil {
+		t.Fatal(err)
+	}
+	repos := repository.New(db)
+	ctx := t.Context()
+
+	m1 := &model.EmbyMount{AccountID: "acct-1", RemoteViewID: "view-1", Name: "Mount 1"}
+	m2 := &model.EmbyMount{AccountID: "acct-1", RemoteViewID: "view-2", Name: "Mount 2"}
+	_ = repos.EmbyMount.Create(ctx, m1)
+	_ = repos.EmbyMount.Create(ctx, m2)
+
+	svc := &service.Container{
+		Repo:       repos,
+		EmbyRemote: service.NewEmbyRemoteService(nil, zap.NewNop(), repos, nil),
+	}
+
+	router := gin.New()
+	router.PUT("/admin/emby/mounts/reorder", reorderEmbyMountsHandler(svc))
+
+	body, _ := json.Marshal(map[string]any{
+		"ids": []string{m2.ID, m1.ID},
+	})
+	req := httptest.NewRequest(http.MethodPut, "/admin/emby/mounts/reorder", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	list, err := repos.EmbyMount.List(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(list) != 2 || list[0].ID != m2.ID || list[1].ID != m1.ID {
+		t.Fatalf("expected order [m2, m1], got [m%s, m%s]", list[0].ID, list[1].ID)
+	}
+}
@@ -34,10 +34,19 @@ func embyPlaybackInfoHandler(svc *service.Container) gin.HandlerFunc {
 // embySubtitleStreamHandler serves an external subtitle track advertised in a
 // MediaSource's MediaStreams via its Emby index
 // (/Videos/:id/Subtitles/:index/Stream). The index maps to a discovered
-// sideloaded subtitle file next to the video (SRT/ASS/SSA/VTT, local or
-// cloud://), following the same layout appended by mediaStreams.
+// sideloaded subtitle track next to the video (SRT/ASS/SSA/VTT, local or
+// cloud://), following the same layout appended by mediaStreams. 远程 Emby
+// 条目的字幕直接反向代理远程。
 func embySubtitleStreamHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		encodedID := c.Param("id")
+		if accountID, remoteID, ok := service.DecodeEmbyRemoteID(encodedID); ok {
+			if err := svc.Emby.ProxyRemoteSubtitle(c.Request.Context(), c.Writer, c.Request, accountID, remoteID, c.Param("index")); err != nil {
+				embyError(c, http.StatusNotFound, "subtitle not found")
+				return
+			}
+			return
+		}
 		uid := c.Param("userId")
 		if uid == "" {
 			uid = embyUserID(c)
@@ -213,12 +222,26 @@ func embyAppendAPIKey(raw, token string) string {
 	return u.String()
 }

-// embyVideoStreamHandler 是 GET /Videos/{id}/stream 的入口，
-// 直接代理到我们的 /api/stream/{id}（同一个 ServeFile）。
+// embyVideoStreamHandler 是 GET /Videos/{id}/stream 的入口。
+// 远程 Emby 条目（embyremote~ 前缀）走反向代理；本地条目直接代理到
+// /api/stream/{id}（同一个 ServeFile）。
 func embyVideoStreamHandler(svc *service.Container, cloudMode string) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		encodedID := c.Param("id")
+		if accountID, remoteID, ok := service.DecodeEmbyRemoteID(encodedID); ok {
+			if err := svc.Emby.ProxyRemoteVideoStream(c.Request.Context(), c.Writer, c.Request, accountID, remoteID); err != nil {
+				if errors.Is(err, service.ErrEmbyRemoteNotFound) {
+					c.Status(http.StatusNotFound)
+					return
+				}
+				if !c.Writer.Written() {
+					c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+				}
+			}
+			return
+		}
 		uid := embyUserID(c)
-		item, err := svc.Emby.Item(c.Request.Context(), c.Param("id"), uid)
+		item, err := svc.Emby.Item(c.Request.Context(), encodedID, uid)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -296,6 +319,11 @@ func embyShouldRedirectVideoStreamToSTRM(c *gin.Context, svc *service.Container,

 func embyVideoHLSPlaylistHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		// 远程 Emby 条目不做本地转码（播放地址已由 PlaybackInfo 指向远程/代理直连）。
+		if service.IsEmbyRemoteID(c.Param("id")) {
+			c.Status(http.StatusNotFound)
+			return
+		}
 		uid := embyUserID(c)
 		item, err := svc.Emby.Item(c.Request.Context(), c.Param("id"), uid)
 		if err != nil || item == nil || svc.Stream == nil {
@@ -319,6 +347,10 @@ func embyVideoHLSPlaylistHandler(svc *service.Container) gin.HandlerFunc {

 func embyVideoHLSSegmentHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		if service.IsEmbyRemoteID(c.Param("id")) {
+			c.Status(http.StatusNotFound)
+			return
+		}
 		uid := embyUserID(c)
 		item, err := svc.Emby.Item(c.Request.Context(), c.Param("id"), uid)
 		if err != nil || item == nil || svc.Stream == nil {
@@ -12,8 +12,13 @@ import (

 type embyPlayingReq struct {
 	ItemId        string `json:"ItemId"`
+	ItemIDLower   string `json:"itemId"`
+	ID            string `json:"Id"`
+	IDLower       string `json:"id"`
 	PositionTicks int64  `json:"PositionTicks"`
+	PositionLower int64  `json:"positionTicks"`
 	RunTimeTicks  int64  `json:"RunTimeTicks"`
+	RunTimeLower  int64  `json:"runTimeTicks"`
 }

 func embyPlayingProgressHandler(svc *service.Container) gin.HandlerFunc {
@@ -25,16 +30,25 @@ func embyPlayingProgressHandler(svc *service.Container) gin.HandlerFunc {
 		}
 		var req embyPlayingReq
 		_ = c.ShouldBindJSON(&req)
-		if req.ItemId == "" {
-			req.ItemId = c.Query("ItemId")
+		itemID := embyFirstNonEmptyString(req.ItemId, req.ItemIDLower, req.ID, req.IDLower)
+		if itemID == "" {
+			itemID = embyFirstNonEmptyString(firstQueryValue(c, "ItemId", "itemId", "Id", "id"))
 		}
-		if req.PositionTicks == 0 {
-			req.PositionTicks, _ = strconv.ParseInt(c.Query("PositionTicks"), 10, 64)
+		pos := req.PositionTicks
+		if pos == 0 {
+			pos = req.PositionLower
 		}
-		if req.RunTimeTicks == 0 {
-			req.RunTimeTicks, _ = strconv.ParseInt(c.Query("RunTimeTicks"), 10, 64)
+		if pos == 0 {
+			pos, _ = strconv.ParseInt(firstQueryValue(c, "PositionTicks", "positionTicks"), 10, 64)
 		}
-		if req.ItemId == "" {
+		runTime := req.RunTimeTicks
+		if runTime == 0 {
+			runTime = req.RunTimeLower
+		}
+		if runTime == 0 {
+			runTime, _ = strconv.ParseInt(firstQueryValue(c, "RunTimeTicks", "runTimeTicks"), 10, 64)
+		}
+		if itemID == "" {
 			c.Status(http.StatusOK)
 			return
 		}
@@ -43,7 +57,10 @@ func embyPlayingProgressHandler(svc *service.Container) gin.HandlerFunc {
 			c.Status(http.StatusUnauthorized)
 			return
 		}
-		_ = svc.Emby.RecordProgress(c.Request.Context(), uid, req.ItemId, req.PositionTicks, req.RunTimeTicks)
+		if err := svc.Emby.RecordProgress(c.Request.Context(), uid, itemID, pos, runTime); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
 		stopped := strings.Contains(strings.ToLower(c.FullPath()+" "+c.Request.URL.Path), "stopped")
 		if svc.Sessions != nil {
 			svc.Sessions.RecordPlayback(c.Request.Context(), uid, "",
@@ -51,9 +68,9 @@ func embyPlayingProgressHandler(svc *service.Container) gin.HandlerFunc {
 				clientInfo.DeviceName,
 				clientInfo.Client,
 				c.ClientIP(),
-				req.ItemId,
-				req.PositionTicks,
-				req.RunTimeTicks,
+				itemID,
+				pos,
+				runTime,
 				stopped)
 		}
 		if svc.Device != nil && !stopped {
@@ -161,6 +161,8 @@ func registerEmbyAuthenticatedItemRoutes(auth *gin.RouterGroup, svc *service.Con
 	auth.GET("/Users/:userId/Items/Counts", embyItemsCountsHandler(svc))
 	auth.GET("/Items/Latest", embyLatestItemsHandler(svc))
 	auth.GET("/Items/Resume", embyResumeItemsHandler(svc))
+	auth.GET("/Users/:userId/Items/Resume", embyResumeItemsHandler(svc))
+	auth.GET("/UserItems/Resume", embyResumeItemsHandler(svc))
 	auth.GET("/Items/:id", embyItemByIDHandler(svc))
 	auth.GET("/Users/:userId/Items/:id", embyUserItemByIDHandler(svc))
 	auth.GET("/Shows/:id/Seasons", embyShowSeasonsHandler(svc))
@@ -32,6 +32,8 @@ func registerLowercaseEmbyItemRoutes(auth *gin.RouterGroup, svc *service.Contain
 	auth.GET("/users/:userId/items/counts", embyItemsCountsHandler(svc))
 	auth.GET("/items/latest", embyLatestItemsHandler(svc))
 	auth.GET("/items/resume", embyResumeItemsHandler(svc))
+	auth.GET("/users/:userId/items/resume", embyResumeItemsHandler(svc))
+	auth.GET("/useritems/resume", embyResumeItemsHandler(svc))
 	auth.GET("/items/:id", embyItemByIDHandler(svc))
 	auth.GET("/users/:userId/items/:id", embyUserItemByIDHandler(svc))
 	auth.GET("/shows/:id/seasons", embyShowSeasonsHandler(svc))
@@ -41,7 +41,17 @@ func embySessionsHandler(svc *service.Container) gin.HandlerFunc {
 				"SupportsRemoteControl": true,
 			}
 			if itemID != "" && sess.IsPlaying {
-				row["NowPlayingItem"] = gin.H{"Id": itemID}
+				nowPlaying := gin.H{"Id": itemID}
+				if svc.Emby != nil {
+					if item, _ := svc.Emby.Item(c.Request.Context(), itemID, sess.UserID); item != nil {
+						for _, key := range []string{"Name", "Type", "RunTimeTicks", "PrimaryImageItemId", "ImageTags", "SeriesName", "SeasonName", "IndexNumber", "ParentIndexNumber"} {
+							if val, ok := item[key]; ok && val != nil {
+								nowPlaying[key] = val
+							}
+						}
+					}
+				}
+				row["NowPlayingItem"] = nowPlaying
 			}
 			out = append(out, row)
 		}
@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"strconv"
 	"strings"
+	"sync"

 	"github.com/gin-gonic/gin"

@@ -16,18 +17,41 @@ import (
 )

 type createLibraryReq struct {
-	Name              string                     `json:"name"`
-	Path              string                     `json:"path"`
-	Paths             []string                   `json:"paths"`
-	Roots             []service.LibraryRootInput `json:"roots"`
-	Type              string                     `json:"type"`
-	CoverURL          string                     `json:"cover_url"`
-	CreatePerSubfolder bool                      `json:"create_per_subfolder"`
+	Name               string                     `json:"name"`
+	Path               string                     `json:"path"`
+	Paths              []string                   `json:"paths"`
+	Roots              []service.LibraryRootInput `json:"roots"`
+	Type               string                     `json:"type"`
+	CoverURL           string                     `json:"cover_url"`
+	CreatePerSubfolder bool                       `json:"create_per_subfolder"`
+}
+
+// webLibraryPayload 是 /api/libraries 返回的库条目：本地库与远程 Emby 挂载库
+// 统一结构（远程库附加 is_remote_emby / remote_source 只读标记）。
+type webLibraryPayload struct {
+	model.Library
+	IsRemoteEmby bool                 `json:"is_remote_emby,omitempty"`
+	RemoteSource string               `json:"remote_source,omitempty"`
+	Total        int64                `json:"total,omitempty"`
+	Cards        []service.SeriesCard `json:"cards,omitempty"`
+}
+
+// remoteLibraryItemTypes 远程库内容拉取时按 CollectionType 过滤直属条目，
+// 避免电影库里的合集文件夹(Folder) 漏出为电影卡片。
+func remoteLibraryItemTypes(collectionType string) string {
+	switch collectionType {
+	case "movies":
+		return "Movie"
+	case "tvshows":
+		return "Series"
+	}
+	return ""
 }

 func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		libs, err := svc.Media.ListLibraries(c.Request.Context())
+		ctx := c.Request.Context()
+		libs, err := svc.Media.ListLibraries(ctx)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -35,23 +59,102 @@ func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
 		role, _ := c.Get(middleware.CtxUserRole)
 		includeHidden := role == "admin" && (c.Query("include_hidden") == "1" || c.Query("include_hidden") == "true" || c.Query("all") == "1")
 		if !includeHidden {
-			libs = service.FilterDisplayCloudLibraries(c.Request.Context(), svc.Repo, libs)
+			libs = service.FilterDisplayCloudLibraries(ctx, svc.Repo, libs)
 			visibility := mediaVisibilityForRequest(c, svc)
 			filtered := libs[:0]
 			for _, lib := range libs {
-				if service.LibraryVisibleForUser(c.Request.Context(), svc.Repo, lib, visibility) {
+				if service.LibraryVisibleForUser(ctx, svc.Repo, lib, visibility) {
 					filtered = append(filtered, lib)
 				}
 			}
 			libs = filtered
 		}
-		c.JSON(http.StatusOK, libs)
+		withPreview := c.Query("with_preview") == "1" || c.Query("with_preview") == "true"
+		limit := 10
+		if withPreview {
+			limit, _ = strconv.Atoi(c.DefaultQuery("preview_limit", c.DefaultQuery("limit", "10")))
+			if limit <= 0 {
+				limit = 10
+			} else if limit > 100 {
+				limit = 100
+			}
+		}
+		out := make([]webLibraryPayload, 0, len(libs)+8)
+		if withPreview {
+			previews, err := svc.Media.ListLibrariesWithPreview(ctx, libs, mediaVisibilityForRequest(c, svc), limit)
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+			for _, p := range previews {
+				out = append(out, webLibraryPayload{Library: p.Library, Total: p.Total, Cards: p.Cards})
+			}
+		} else {
+			for _, l := range libs {
+				out = append(out, webLibraryPayload{Library: l})
+			}
+		}
+		// 远程 Emby 挂载库追加在本地库之后。
+		if svc.EmbyRemote != nil {
+			if views, err := svc.EmbyRemote.RemoteLibraries(ctx); err == nil {
+				remotePayloads := make([]webLibraryPayload, len(views))
+				for i, v := range views {
+					remotePayloads[i] = webLibraryPayload{Library: v.Library, IsRemoteEmby: true, RemoteSource: v.AccountName}
+				}
+				if withPreview && len(views) > 0 {
+					const maxRemotePreviewWorkers = 6
+					sem := make(chan struct{}, maxRemotePreviewWorkers)
+					var wg sync.WaitGroup
+					for i, v := range views {
+						i, v := i, v
+						wg.Add(1)
+						go func() {
+							defer wg.Done()
+							select {
+							case sem <- struct{}{}:
+								defer func() { <-sem }()
+							case <-ctx.Done():
+								return
+							}
+							acct := svc.EmbyRemote.AccountByID(ctx, v.AccountID)
+							if acct == nil {
+								return
+							}
+							tmpMount := &model.EmbyMount{Base: model.Base{ID: v.MountID}}
+							itemTypes := remoteLibraryItemTypes(v.CollectionType)
+							if _, total, err := svc.EmbyRemote.RemoteLibraryMedia(ctx, tmpMount, acct, v.RemoteID, itemTypes, 0, 1); err == nil {
+								remotePayloads[i].Total = total
+							}
+							if cards, err := svc.EmbyRemote.RemoteLatestCards(ctx, tmpMount, acct, v.RemoteID, limit); err == nil {
+								remotePayloads[i].Cards = cards
+							}
+						}()
+					}
+					wg.Wait()
+				}
+				out = append(out, remotePayloads...)
+			}
+		}
+		c.JSON(http.StatusOK, out)
 	}
 }

 func getLibraryHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		lib, err := svc.Repo.Library.FindByID(c.Request.Context(), c.Param("id"))
+		ctx := c.Request.Context()
+		id := c.Param("id")
+		// 远程 Emby 挂载库详情。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(id)
+			view, err := svc.EmbyRemote.RemoteLibraryByID(ctx, mountID, remoteID)
+			if err != nil || view == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			c.JSON(http.StatusOK, webLibraryPayload{Library: view.Library, IsRemoteEmby: true, RemoteSource: view.AccountName})
+			return
+		}
+		lib, err := svc.Repo.Library.FindByID(ctx, id)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -63,14 +166,14 @@ func getLibraryHandler(svc *service.Container) gin.HandlerFunc {
 		role, _ := c.Get(middleware.CtxUserRole)
 		includeHidden := role == "admin" && (c.Query("include_hidden") == "1" || c.Query("include_hidden") == "true" || c.Query("all") == "1")
 		if !includeHidden {
-			libs := service.FilterDisplayCloudLibraries(c.Request.Context(), svc.Repo, []model.Library{*lib})
-			if len(libs) == 0 || !service.LibraryVisibleForUser(c.Request.Context(), svc.Repo, libs[0], mediaVisibilityForRequest(c, svc)) {
+			libs := service.FilterDisplayCloudLibraries(ctx, svc.Repo, []model.Library{*lib})
+			if len(libs) == 0 || !service.LibraryVisibleForUser(ctx, svc.Repo, libs[0], mediaVisibilityForRequest(c, svc)) {
 				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 				return
 			}
-			c.JSON(http.StatusOK, libs[0])
+			c.JSON(http.StatusOK, webLibraryPayload{Library: libs[0]})
 		} else {
-			c.JSON(http.StatusOK, lib)
+			c.JSON(http.StatusOK, webLibraryPayload{Library: *lib})
 		}
 	}
 }
@@ -89,38 +192,38 @@ func createLibraryHandler(svc *service.Container) gin.HandlerFunc {
 			}
 		}
 		if len(roots) == 0 && strings.TrimSpace(req.Path) != "" {
-roots = append(roots, service.LibraryRootInput{Path: req.Path})
-	}
-	var l *model.Library
-	if req.CreatePerSubfolder {
-		parent := ""
-		if len(roots) > 0 {
-			parent = roots[0].Path
-		} else if strings.TrimSpace(req.Path) != "" {
-			parent = req.Path
+			roots = append(roots, service.LibraryRootInput{Path: req.Path})
 		}
-		created, err := svc.Media.CreateLibrariesPerSubfolder(c.Request.Context(), parent, req.Type, req.CoverURL)
-		if err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-			return
-		}
-		uid, _ := c.Get("ctx_user_id")
-		for i := range created {
-			lib := &created[i]
-			svc.Audit.Record(c.Request.Context(), toString(uid), "library.create", lib.ID, c.ClientIP(), lib.Path)
-			if svc.Watcher != nil {
-				go func() { _ = svc.Watcher.Refresh(context.Background()) }()
+		var l *model.Library
+		if req.CreatePerSubfolder {
+			parent := ""
+			if len(roots) > 0 {
+				parent = roots[0].Path
+			} else if strings.TrimSpace(req.Path) != "" {
+				parent = req.Path
 			}
-			for _, root := range lib.Roots {
-				if root.Enabled {
-					queueLibraryRootScan(svc, lib.ID, root.ID)
+			created, err := svc.Media.CreateLibrariesPerSubfolder(c.Request.Context(), parent, req.Type, req.CoverURL)
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+			uid, _ := c.Get("ctx_user_id")
+			for i := range created {
+				lib := &created[i]
+				svc.Audit.Record(c.Request.Context(), toString(uid), "library.create", lib.ID, c.ClientIP(), lib.Path)
+				if svc.Watcher != nil {
+					go func() { _ = svc.Watcher.Refresh(context.Background()) }()
+				}
+				for _, root := range lib.Roots {
+					if root.Enabled {
+						queueLibraryRootScan(svc, lib.ID, root.ID)
+					}
 				}
 			}
+			c.JSON(http.StatusCreated, gin.H{"libraries": created})
+			return
 		}
-		c.JSON(http.StatusCreated, gin.H{"libraries": created})
-		return
-	}
-	l, err := svc.Media.CreateLibraryWithRootsAndCover(c.Request.Context(), req.Name, req.Type, req.CoverURL, roots)
+		l, err := svc.Media.CreateLibraryWithRootsAndCover(c.Request.Context(), req.Name, req.Type, req.CoverURL, roots)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -216,8 +319,37 @@ func deleteLibraryHandler(svc *service.Container) gin.HandlerFunc {
 func listMediaHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		id := c.Param("id")
+		ctx := c.Request.Context()
 		page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
 		size, _ := strconv.Atoi(c.DefaultQuery("page_size", "50"))
+		// 远程 Emby 库：转发远程直属条目并映射为本地 Media 结构（分页由远程承接）。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(id)
+			mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			itemTypes := ""
+			if view, err := svc.EmbyRemote.RemoteLibraryByID(ctx, mountID, remoteID); err == nil && view != nil {
+				itemTypes = remoteLibraryItemTypes(view.CollectionType)
+			}
+			items, total, err := svc.EmbyRemote.RemoteLibraryMedia(ctx, mount, acct, remoteID, itemTypes, (page-1)*size, size)
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+			if items == nil {
+				items = []model.Media{}
+			}
+			c.JSON(http.StatusOK, gin.H{
+				"items":     items,
+				"total":     total,
+				"page":      page,
+				"page_size": size,
+			})
+			return
+		}
 		groupVersions := c.DefaultQuery("group_versions", "1") != "0"
 		if !groupVersions {
 			items, total, err := svc.Media.ListMediaVisible(c.Request.Context(), id, page, size, mediaVisibilityForRequest(c, svc))
@@ -255,7 +387,33 @@ func listMediaHandler(svc *service.Container) gin.HandlerFunc {

 func getMediaHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		ctx := c.Request.Context()
+		id := c.Param("id")
+		// 远程 Emby 条目：拉远程详情并映射为本地 Media 结构。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(id)
+			mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			m, err := svc.EmbyRemote.RemoteMediaDetail(ctx, mount, acct, remoteID)
+			if err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+			if m == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			if !mediaVisibleForRequest(c, svc, m) {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			c.JSON(http.StatusOK, m)
+			return
+		}
+		m, err := svc.Media.GetMedia(ctx, id)
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -349,7 +507,37 @@ func searchMediaHandler(svc *service.Container) gin.HandlerFunc {

 func streamHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		ctx := c.Request.Context()
+		id := c.Param("id")
+		// 远程 Emby 条目：按挂载代理配置分流——代理走 MMTL 反代，否则 302 直连。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			if !enforceScopedPlaybackToken(c, id) {
+				return
+			}
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(id)
+			mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			if mount.ProxyPlay {
+				if err := svc.Emby.ProxyRemoteVideoStream(ctx, c.Writer, c.Request, mountID, remoteID); err != nil {
+					if !c.Writer.Written() {
+						c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+					}
+				}
+				return
+			}
+			target, err := svc.EmbyRemote.WebStreamURL(ctx, acct, remoteID)
+			if err != nil {
+				c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+				return
+			}
+			setRedirectNoStoreHeaders(c)
+			c.Redirect(http.StatusFound, target)
+			return
+		}
+		m, err := svc.Media.GetMedia(ctx, id)
 		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 			return
@@ -19,21 +19,40 @@ import (
 	"github.com/ShukeBta/MMTL/internal/service"
 )

+func findMediaForPlaybackEndpoint(c *gin.Context, svc *service.Container, id string) (*model.Media, error) {
+	ctx := c.Request.Context()
+	if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+		mountID, remoteID, _ := service.DecodeEmbyRemoteID(id)
+		mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+		if mount == nil || acct == nil {
+			return nil, nil
+		}
+		return svc.EmbyRemote.RemoteMediaDetail(ctx, mount, acct, remoteID)
+	}
+	return svc.Repo.Media.FindByID(ctx, id)
+}
+
 // playbackInfoHandler returns the media row + a `stream_url` the React
 // player can hit. Mirrors the Python project's surface.
 func playbackInfoHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Repo.Media.FindByID(c.Request.Context(), c.Param("id"))
+		id := c.Param("id")
+		m, err := findMediaForPlaybackEndpoint(c, svc, id)
 		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
 			return
 		}
 		token := externalPlaybackToken(c, svc, m.ID, m.DurationSec)
 		profileQuery := externalProfileQuery(c)
+		hlsURL := "/api/hls/" + m.ID + "/index.m3u8?token=" + url.QueryEscape(token) + profileQuery
+		if service.IsEmbyRemoteID(m.ID) || service.IsStrmMediaRow(m) {
+			// Emby 远程挂载与 STRM 媒体一样，默认直连播放，不提供转码地址
+			hlsURL = ""
+		}
 		c.JSON(http.StatusOK, gin.H{
 			"media":      m,
 			"stream_url": "/api/stream/" + m.ID + "?token=" + url.QueryEscape(token) + profileQuery,
-			"hls_url":    "/api/hls/" + m.ID + "/index.m3u8?token=" + url.QueryEscape(token) + profileQuery,
+			"hls_url":    hlsURL,
 		})
 	}
 }
@@ -68,7 +87,8 @@ func playbackProgressHandler(svc *service.Container) gin.HandlerFunc {
 // produce the per-player launch URL.
 func externalPlayersHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Repo.Media.FindByID(c.Request.Context(), c.Param("id"))
+		id := c.Param("id")
+		m, err := findMediaForPlaybackEndpoint(c, svc, id)
 		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
 			return
@@ -93,7 +113,8 @@ func externalPlayersHandler(svc *service.Container) gin.HandlerFunc {
 // token query string the external player needs.
 func externalURLHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Repo.Media.FindByID(c.Request.Context(), c.Param("id"))
+		id := c.Param("id")
+		m, err := findMediaForPlaybackEndpoint(c, svc, id)
 		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "media not found"})
 			return
@@ -404,8 +404,77 @@ func newPlaybackScopeTestRouter(t *testing.T) (*gin.Engine, *service.Container,
 	router := gin.New()
 	api := router.Group("/api")
 	api.Use(middleware.AuthRequired(cfg.Secrets.JWTSecret))
+	api.GET("/playback/:id/info", playbackInfoHandler(svc))
 	api.GET("/playback/:id/external-url", externalURLHandler(svc))
 	api.GET("/playback/:id/external-players", externalPlayersHandler(svc))
 	api.GET("/stream/:id", streamHandler(svc))
+	api.GET("/hls/:id/index.m3u8", hlsPlaylistHandler(svc))
+	api.GET("/media/:id/subtitles", listSubtitlesHandler(svc))
 	return router, svc, cfg.Secrets.JWTSecret
 }
+
+func TestPlaybackInfoForSTRMMediaDisablesHLS(t *testing.T) {
+	router, _, secret := newPlaybackScopeTestRouter(t)
+	loginToken := signedTestToken(t, secret)
+
+	req := httptest.NewRequest(http.MethodGet, "http://nas.local/api/playback/media-1/info", nil)
+	req.Header.Set("Authorization", "Bearer "+loginToken)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", w.Code, w.Body.String())
+	}
+	var payload struct {
+		StreamURL string `json:"stream_url"`
+		HlsURL    string `json:"hls_url"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if payload.StreamURL == "" {
+		t.Fatalf("expected non-empty stream_url")
+	}
+	if payload.HlsURL != "" {
+		t.Fatalf("expected empty hls_url for STRM media, got %q", payload.HlsURL)
+	}
+}
+
+func TestHLSPlaylistForRemoteEmbyMediaDisabled(t *testing.T) {
+	router, svc, secret := newPlaybackScopeTestRouter(t)
+	svc.EmbyRemote = &service.EmbyRemoteService{}
+	loginToken := signedTestToken(t, secret)
+
+	req := httptest.NewRequest(http.MethodGet, "http://nas.local/api/hls/embyremote~acct1~item1/index.m3u8", nil)
+	req.Header.Set("Authorization", "Bearer "+loginToken)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusConflict {
+		t.Fatalf("status = %d, want %d (409 StatusConflict)", w.Code, http.StatusConflict)
+	}
+}
+
+func TestListSubtitlesForRemoteEmbyMediaReturnsEmptyTracks(t *testing.T) {
+	router, svc, secret := newPlaybackScopeTestRouter(t)
+	svc.EmbyRemote = &service.EmbyRemoteService{}
+	loginToken := signedTestToken(t, secret)
+
+	req := httptest.NewRequest(http.MethodGet, "http://nas.local/api/media/embyremote~acct1~item1/subtitles", nil)
+	req.Header.Set("Authorization", "Bearer "+loginToken)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 OK", w.Code)
+	}
+	var payload struct {
+		Tracks []any `json:"tracks"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if payload.Tracks == nil || len(payload.Tracks) != 0 {
+		t.Fatalf("expected empty tracks array, got %v", payload.Tracks)
+	}
+}
@@ -22,6 +22,10 @@ func registerAdminRoutes(api *gin.RouterGroup, cfg *config.Config, svc *service.
 	registerAdminStrmRoutes(admin, svc)
 	registerAdminScraperRoutes(admin, svc)
 	registerAdminDatabaseRoutes(admin, svc)
+
+	// FFmpeg/FFprobe 工具：状态查询 + 一键下载安装（自动匹配当前平台）。
+	admin.GET("/tools/ffmpeg/status", ffToolsStatusHandler(svc))
+	admin.POST("/tools/ffmpeg/install", ffToolsInstallHandler(svc))
 }

 func registerAdminScraperRoutes(admin *gin.RouterGroup, svc *service.Container) {
@@ -42,6 +46,15 @@ func registerAdminScraperRoutes(admin *gin.RouterGroup, svc *service.Container)
 }

 func registerAdminStrmRoutes(admin *gin.RouterGroup, svc *service.Container) {
+	// Emby 挂载管理：远程 Emby 媒体库挂载（账号复用 strm/accounts）
+	admin.GET("/emby/accounts/:id/views", embyAccountViewsHandler(svc))
+	admin.POST("/emby/accounts/:id/full-mount", fullMountEmbyAccountHandler(svc))
+	admin.GET("/emby/mounts", listEmbyMountsHandler(svc))
+	admin.POST("/emby/mounts", createEmbyMountsHandler(svc))
+	admin.PUT("/emby/mounts/reorder", reorderEmbyMountsHandler(svc))
+	admin.PUT("/emby/mounts/:id", updateEmbyMountHandler(svc))
+	admin.DELETE("/emby/mounts/:id", deleteEmbyMountHandler(svc))
+
 	admin.GET("/strm/accounts", listStrmAccountsHandler(svc))
 	admin.POST("/strm/accounts", createStrmAccountHandler(svc))
 	admin.PUT("/strm/accounts/:id", updateStrmAccountHandler(svc))
@@ -81,8 +94,11 @@ func registerAdminStrmRoutes(admin *gin.RouterGroup, svc *service.Container) {
 	admin.POST("/strm/uploads/:id/retry", retryStrmUploadHandler(svc))
 	admin.DELETE("/strm/uploads/:id", deleteStrmUploadHandler(svc))
 	admin.POST("/strm/uploads/batch", batchActionUploadsHandler(svc))
-	admin.POST("/strm/uploads/cancel-pending", cancelPendingUploadsHandler(svc))
+	admin.POST("/strm/uploads/clear-done", clearDoneUploadsHandler(svc))
+	admin.POST("/strm/uploads/clear-finished", clearFinishedUploadsHandler(svc))
 	admin.POST("/strm/uploads/clear-canceled", clearCanceledUploadsHandler(svc))
+	admin.POST("/strm/uploads/retry-failed", retryAllFailedUploadsHandler(svc))
+	admin.POST("/strm/uploads/cancel-pending", cancelPendingUploadsHandler(svc))
 }

 func registerAdminUserRoutes(admin *gin.RouterGroup, svc *service.Container) {
@@ -92,6 +108,7 @@ func registerAdminUserRoutes(admin *gin.RouterGroup, svc *service.Container) {
 	admin.PATCH("/users/:id/password", resetUserPasswordHandler(svc))
 	admin.PATCH("/users/:id/status", updateUserStatusHandler(svc))
 	admin.PATCH("/users/:id/role", adminUpdateRoleHandler(svc))
+	admin.PATCH("/users/:id/libraries", updateUserLibrariesHandler(svc))
 	admin.DELETE("/users/:id", deleteUserHandler(svc))
 	admin.GET("/settings", listSettingsHandler(svc))
 	admin.PUT("/settings", updateSettingHandler(svc))
@@ -39,6 +39,7 @@ func registerAuthedLibraryRoutes(authed *gin.RouterGroup, svc *service.Container

 func registerAuthedMediaRoutes(authed *gin.RouterGroup, svc *service.Container) {
 	authed.GET("/media/:id", getMediaHandler(svc))
+	authed.GET("/media/:id/episodes", listMediaEpisodesHandler(svc))
 	authed.GET("/media", searchMediaHandler(svc))
 	authed.PATCH("/media/:id/metadata", middleware.AdminRequired(), updateMediaMetadataHandler(svc))
 	authed.POST("/media/:id/scrape", middleware.AdminRequired(), scrapeOneHandler(svc))
@@ -65,7 +65,49 @@ func listSeasonsHandler(svc *service.Container) gin.HandlerFunc {
 func listLibrarySeriesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		libID := c.Param("id")
-		if lib, err := svc.Repo.Library.FindByID(c.Request.Context(), libID); err == nil && lib != nil {
+		ctx := c.Request.Context()
+		// 远程剧集库：远程 Series 映射为系列卡片。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(libID) {
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(libID)
+			mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			cards, err := svc.EmbyRemote.RemoteSeriesCards(ctx, mount, acct, remoteID)
+			if err != nil {
+				writeInternalOrCanceled(c, err)
+				return
+			}
+			page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+			size, _ := strconv.Atoi(c.DefaultQuery("page_size", "500"))
+			if page < 1 {
+				page = 1
+			}
+			if size <= 0 || size > 1000 {
+				size = 500
+			}
+			start := (page - 1) * size
+			if start > len(cards) {
+				start = len(cards)
+			}
+			end := start + size
+			if end > len(cards) {
+				end = len(cards)
+			}
+			pageItems := cards[start:end]
+			if pageItems == nil {
+				pageItems = []service.SeriesCard{}
+			}
+			c.JSON(http.StatusOK, gin.H{
+				"items":     pageItems,
+				"total":     len(cards),
+				"page":      page,
+				"page_size": size,
+			})
+			return
+		}
+		if lib, err := svc.Repo.Library.FindByID(ctx, libID); err == nil && lib != nil {
 			if !service.LibraryVisibleForUser(c.Request.Context(), svc.Repo, *lib, mediaVisibilityForRequest(c, svc)) {
 				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 				return
@@ -114,7 +156,27 @@ func listLibrarySeriesEpisodesHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "key is required"})
 			return
 		}
-		if lib, err := svc.Repo.Library.FindByID(c.Request.Context(), libID); err == nil && lib != nil {
+		ctx := c.Request.Context()
+		// 远程系列 key（伪装系列 ID）：转发远程该系列全部剧集。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(key) {
+			mountID, remoteSeriesID, _ := service.DecodeEmbyRemoteID(key)
+			mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			items, err := svc.EmbyRemote.RemoteEpisodes(ctx, mount, acct, remoteSeriesID)
+			if err != nil {
+				writeInternalOrCanceled(c, err)
+				return
+			}
+			if items == nil {
+				items = []model.Media{}
+			}
+			c.JSON(http.StatusOK, gin.H{"items": items, "total": len(items)})
+			return
+		}
+		if lib, err := svc.Repo.Library.FindByID(ctx, libID); err == nil && lib != nil {
 			if !service.LibraryVisibleForUser(c.Request.Context(), svc.Repo, *lib, mediaVisibilityForRequest(c, svc)) {
 				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 				return
@@ -128,3 +190,39 @@ func listLibrarySeriesEpisodesHandler(svc *service.Container) gin.HandlerFunc {
 		c.JSON(http.StatusOK, gin.H{"items": items, "total": len(items)})
 	}
 }
+
+func listMediaEpisodesHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		id := c.Param("id")
+		if id == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "id is required"})
+			return
+		}
+		ctx := c.Request.Context()
+		// 远程条目：单集→同系列集列表；系列/季/文件夹→子集；电影→自身单条。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			mountID, remoteID, _ := service.DecodeEmbyRemoteID(id)
+			mount, acct, _ := svc.EmbyRemote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+				return
+			}
+			items, err := svc.EmbyRemote.RemoteEpisodes(ctx, mount, acct, remoteID)
+			if err != nil {
+				writeInternalOrCanceled(c, err)
+				return
+			}
+			if items == nil {
+				items = []model.Media{}
+			}
+			c.JSON(http.StatusOK, gin.H{"items": items, "total": len(items)})
+			return
+		}
+		items, err := svc.Media.ListMediaEpisodes(ctx, id, mediaVisibilityForRequest(c, svc))
+		if err != nil {
+			writeInternalOrCanceled(c, err)
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"items": items, "total": len(items)})
+	}
+}
@@ -13,7 +13,13 @@ import (

 func hlsPlaylistHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		id := c.Param("id")
+		// 远程 Emby 挂载媒体与 STRM 一样，默认直连播放，不进行转码。
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			c.JSON(http.StatusConflict, gin.H{"error": "transcode disabled"})
+			return
+		}
+		m, err := svc.Media.GetMedia(c.Request.Context(), id)
 		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 			return
@@ -43,7 +49,12 @@ func hlsPlaylistHandler(svc *service.Container) gin.HandlerFunc {

 func hlsSegmentHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		m, err := svc.Media.GetMedia(c.Request.Context(), c.Param("id"))
+		id := c.Param("id")
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			c.JSON(http.StatusConflict, gin.H{"error": "transcode disabled"})
+			return
+		}
+		m, err := svc.Media.GetMedia(c.Request.Context(), id)
 		if err != nil || m == nil || !mediaVisibleForRequest(c, svc, m) {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 			return
@@ -28,17 +28,25 @@ type strmAccountView struct {
 	model.StrmAccount
 	HasCredential bool   `json:"has_credential"`
 	ProviderLabel string `json:"provider_label"`
+	// ProxyPlay 仅远程 Emby 挂载账号返回：播放流量是否经过 MMTL 代理（编辑回显用）。
+	ProxyPlay *bool `json:"proxy_play,omitempty"`
 }

-func strmAccountViews(accounts []model.StrmAccount) []strmAccountView {
+func strmAccountViews(svc *service.Container, accounts []model.StrmAccount) []strmAccountView {
 	out := make([]strmAccountView, 0, len(accounts))
 	for i := range accounts {
 		a := accounts[i]
-		out = append(out, strmAccountView{
+		view := strmAccountView{
 			StrmAccount:   a,
 			HasCredential: service.HasStrmAccountCredential(&a),
 			ProviderLabel: providerLabelOf(a.Provider),
-		})
+		}
+		if a.Provider == model.StrmProviderEmbyRemote && svc != nil && svc.EmbyRemote != nil {
+			if proxyPlay, err := svc.EmbyRemote.ProxyPlayOf(&a); err == nil {
+				view.ProxyPlay = &proxyPlay
+			}
+		}
+		out = append(out, view)
 	}
 	return out
 }
@@ -58,7 +66,7 @@ func listStrmAccountsHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
-		c.JSON(http.StatusOK, strmAccountViews(accounts))
+		c.JSON(http.StatusOK, strmAccountViews(svc, accounts))
 	}
 }

@@ -74,7 +82,7 @@ func createStrmAccountHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		views := strmAccountViews([]model.StrmAccount{*acct})
+		views := strmAccountViews(svc, []model.StrmAccount{*acct})
 		c.JSON(http.StatusOK, views[0])
 	}
 }
@@ -92,7 +100,7 @@ func updateStrmAccountHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
-		views := strmAccountViews([]model.StrmAccount{*acct})
+		views := strmAccountViews(svc, []model.StrmAccount{*acct})
 		c.JSON(http.StatusOK, views[0])
 	}
 }
@@ -114,7 +122,7 @@ func testStrmAccountHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusNotFound, gin.H{"error": "网盘账号不存在"})
 			return
 		}
-		views := strmAccountViews([]model.StrmAccount{*acct})
+		views := strmAccountViews(svc, []model.StrmAccount{*acct})
 		c.JSON(http.StatusOK, views[0])
 	}
 }
@@ -496,6 +504,28 @@ func clearCanceledUploadsHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }

+func clearDoneUploadsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		n, err := svc.Strm.ClearDoneUploadTasks(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"deleted": n})
+	}
+}
+
+func clearFinishedUploadsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		n, err := svc.Strm.ClearFinishedUploadTasks(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"deleted": n})
+	}
+}
+
 func retryAllFailedDownloadsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		n, err := svc.Strm.RetryAllFailedDownloadTasks(c.Request.Context())
@@ -507,6 +537,17 @@ func retryAllFailedDownloadsHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }

+func retryAllFailedUploadsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		n, err := svc.Strm.RetryAllFailedUploadTasks(c.Request.Context())
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"retried": n})
+	}
+}
+
 func cancelPendingDownloadsHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		n, err := svc.Strm.CancelPendingDownloadTasks(c.Request.Context())
@@ -50,16 +50,19 @@ func TestStrmAdminRoutesAreRegistered(t *testing.T) {
 		"GET /api/admin/strm/downloads",
 		"POST /api/admin/strm/downloads/:id/cancel",
 		"POST /api/admin/strm/downloads/:id/retry",
-			"POST /api/admin/strm/downloads/clear-finished",
-			"POST /api/admin/strm/downloads/clear-canceled",
-			"POST /api/admin/strm/downloads/retry-failed",
-			"POST /api/admin/strm/downloads/cancel-pending",
-			"GET /api/admin/strm/uploads",
-			"POST /api/admin/strm/uploads/:id/cancel",
-			"POST /api/admin/strm/uploads/:id/retry",
-			"POST /api/admin/strm/uploads/cancel-pending",
-			"POST /api/admin/strm/uploads/clear-canceled",
-			"GET /api/strm/play/:provider/:file",
+		"POST /api/admin/strm/downloads/clear-finished",
+		"POST /api/admin/strm/downloads/clear-canceled",
+		"POST /api/admin/strm/downloads/retry-failed",
+		"POST /api/admin/strm/downloads/cancel-pending",
+		"GET /api/admin/strm/uploads",
+		"POST /api/admin/strm/uploads/:id/cancel",
+		"POST /api/admin/strm/uploads/:id/retry",
+		"POST /api/admin/strm/uploads/clear-done",
+		"POST /api/admin/strm/uploads/clear-finished",
+		"POST /api/admin/strm/uploads/clear-canceled",
+		"POST /api/admin/strm/uploads/retry-failed",
+		"POST /api/admin/strm/uploads/cancel-pending",
+		"GET /api/strm/play/:provider/:file",
 	} {
 		if !routes[want] {
 			t.Fatalf("%s route is not registered", want)
@@ -11,7 +11,12 @@ import (

 func listSubtitlesHandler(svc *service.Container) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		tracks, err := svc.Subtitle.Discover(c.Request.Context(), c.Param("id"))
+		id := c.Param("id")
+		if svc.EmbyRemote != nil && service.IsEmbyRemoteID(id) {
+			c.JSON(http.StatusOK, gin.H{"tracks": []service.SubtitleTrack{}})
+			return
+		}
+		tracks, err := svc.Subtitle.Discover(c.Request.Context(), id)
 		if err != nil {
 			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
 			return
@@ -31,7 +36,7 @@ func serveSubtitleHandler(svc *service.Container) gin.HandlerFunc {
 			return
 		}
 		c.Header("Content-Type", "text/vtt; charset=utf-8")
-		c.Header("Cache-Control", "public, max-age=3600")
+		c.Header("Cache-Control", "no-cache, no-store, must-revalidate")
 		if err := svc.Subtitle.Serve(c.Request.Context(), c.Param("id"), path, c.Writer); err != nil {
 			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
 			return
@@ -1,144 +0,0 @@
-// Package handler — system tools detection.
-package handler
-
-import (
-	"net/http"
-	"os/exec"
-	"strings"
-
-	"github.com/gin-gonic/gin"
-	"go.uber.org/zap"
-
-	"github.com/ShukeBta/MMTL/internal/config"
-	"github.com/ShukeBta/MMTL/internal/service"
-)
-
-// SystemHandler handles system-related endpoints.
-type SystemHandler struct {
-	cfg *config.Config
-	log *zap.Logger
-	svc *service.Container
-}
-
-// NewSystemHandler is the constructor.
-func NewSystemHandler(cfg *config.Config, log *zap.Logger, svc *service.Container) *SystemHandler {
-	return &SystemHandler{cfg: cfg, log: log, svc: svc}
-}
-
-// ToolStatus represents the detection status of a system tool.
-type ToolStatus struct {
-	Name        string `json:"name"`
-	DisplayName string `json:"display_name"`
-	ConfigKey   string `json:"config_key"`
-	Path        string `json:"path,omitempty"`
-	Detected    bool   `json:"detected"`
-	Version     string `json:"version,omitempty"`
-}
-
-// GetToolsStatus returns the status of system tools.
-func (h *SystemHandler) GetToolsStatus(c *gin.Context) {
-	tools := []ToolStatus{
-		{Name: "ffprobe", DisplayName: "FFprobe", ConfigKey: "app.ffprobe_path"},
-		{Name: "ffmpeg", DisplayName: "FFmpeg", ConfigKey: "app.ffmpeg_path"},
-	}
-
-	for i := range tools {
-		// Check configured path first
-		var configuredPath string
-		switch tools[i].ConfigKey {
-		case "app.ffprobe_path":
-			configuredPath = h.cfg.App.FFprobePath
-			if configuredPath == "" {
-				configuredPath = "ffprobe"
-			}
-		case "app.ffmpeg_path":
-			configuredPath = h.cfg.App.FFmpegPath
-			if configuredPath == "" {
-				configuredPath = "ffmpeg"
-			}
-		}
-
-		// Try to find the tool
-		path, err := exec.LookPath(configuredPath)
-		if err == nil {
-			tools[i].Detected = true
-			tools[i].Path = path
-			// Try to get version
-			tools[i].Version = getToolVersion(path)
-		}
-	}
-
-	c.JSON(http.StatusOK, gin.H{
-		"tools": tools,
-	})
-}
-
-// getToolVersion attempts to get the version of a tool.
-func getToolVersion(path string) string {
-	out, err := exec.Command(path, "-version").Output()
-	if err != nil {
-		return ""
-	}
-
-	// Extract first line as version info
-	lines := strings.Split(string(out), "\n")
-	if len(lines) > 0 {
-		return strings.TrimSpace(lines[0])
-	}
-	return ""
-}
-
-// InstallTools attempts to auto-install system tools (ffmpeg/ffprobe)
-func (h *SystemHandler) InstallTools(c *gin.Context) {
-	h.log.Info("Received tools auto-install request")
-
-	// Call service layer to auto-install
-	ffprobePath, ffmpegPath := service.AutoInstallFFmpeg(h.log, h.cfg)
-
-	result := gin.H{
-		"installed": ffprobePath != "" || ffmpegPath != "",
-	}
-
-	if ffprobePath != "" {
-		result["ffprobe_path"] = ffprobePath
-		result["ffprobe_installed"] = true
-	}
-	if ffmpegPath != "" {
-		result["ffmpeg_path"] = ffmpegPath
-		result["ffmpeg_installed"] = true
-	}
-
-	// Re-detect tool status
-	tools := []ToolStatus{
-		{Name: "ffprobe", DisplayName: "FFprobe", ConfigKey: "app.ffprobe_path"},
-		{Name: "ffmpeg", DisplayName: "FFmpeg", ConfigKey: "app.ffmpeg_path"},
-	}
-
-	for i := range tools {
-		var configuredPath string
-		switch tools[i].ConfigKey {
-		case "app.ffprobe_path":
-			configuredPath = h.cfg.App.FFprobePath
-			if configuredPath == "" {
-				configuredPath = "ffprobe"
-			}
-		case "app.ffmpeg_path":
-			configuredPath = h.cfg.App.FFmpegPath
-			if configuredPath == "" {
-				configuredPath = "ffmpeg"
-			}
-		}
-
-		path, err := exec.LookPath(configuredPath)
-		if err == nil {
-			tools[i].Detected = true
-			tools[i].Path = path
-			tools[i].Version = getToolVersion(path)
-		}
-	}
-
-	result["tools"] = tools
-
-	h.log.Info("Tool installation completed", zap.Any("result", result))
-	c.JSON(http.StatusOK, result)
-}
@@ -0,0 +1,38 @@
+// Package handler — FFmpeg/FFprobe 工具安装端点。
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/ShukeBta/MMTL/internal/service"
+)
+
+// ffToolsStatusHandler 返回 ffmpeg/ffprobe 当前安装状态
+// （GET /api/admin/tools/ffmpeg/status）。
+func ffToolsStatusHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.FFTools == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "FFmpeg 工具服务不可用"})
+			return
+		}
+		c.JSON(http.StatusOK, svc.FFTools.Status(c.Request.Context()))
+	}
+}
+
+// ffToolsInstallHandler 触发后台下载安装（POST /api/admin/tools/ffmpeg/install）。
+// 自动匹配当前运行环境（OS+架构），安装到 data/tools/ffmpeg/ 并把路径写入设置。
+func ffToolsInstallHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if svc == nil || svc.FFTools == nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "FFmpeg 工具服务不可用"})
+			return
+		}
+		if err := svc.FFTools.StartInstall(c.Request.Context()); err != nil {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, svc.FFTools.Status(c.Request.Context()))
+	}
+}
@@ -32,7 +32,14 @@ func mediaVisibilityForRequest(c *gin.Context, svc *service.Container) service.M
 		return visibility
 	}
 	visibility.IncludeNSFW = adultEnabled && profile.AllowAdult && !userHidesAdult
-	visibility.AllowedLibraryIDs = profileAllowedLibraryIDs(*profile)
+	profileAllowed := profileAllowedLibraryIDs(*profile)
+	if len(profileAllowed) > 0 {
+		if len(visibility.AllowedLibraryIDs) > 0 {
+			visibility.AllowedLibraryIDs = service.IntersectStrings(visibility.AllowedLibraryIDs, profileAllowed)
+		} else {
+			visibility.AllowedLibraryIDs = profileAllowed
+		}
+	}
 	if !visibility.IncludeNSFW {
 		visibility.HiddenLibraryIDs = service.AdultLibraryIDs(c.Request.Context(), svc.Repo)
 	} else {
@@ -125,6 +125,18 @@ func historyContinueHandler(svc *service.Container) gin.HandlerFunc {
 		for _, r := range rows {
 			m, ok := mIdx[r.MediaID]
 			if !ok {
+				if svc.EmbyRemote != nil && service.IsEmbyRemoteID(r.MediaID) {
+					mountID, remoteID, _ := service.DecodeEmbyRemoteID(r.MediaID)
+					if mount, acct, _ := svc.EmbyRemote.ResolveMount(c.Request.Context(), mountID); mount != nil && acct != nil {
+						if rm, err := svc.EmbyRemote.RemoteMediaDetail(c.Request.Context(), mount, acct, remoteID); err == nil && rm != nil {
+							out = append(out, gin.H{
+								"history": r,
+								"media":   *rm,
+							})
+							continue
+						}
+					}
+				}
 				continue
 			}
 			out = append(out, gin.H{
@@ -163,7 +175,7 @@ func historyDeleteHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "status must be completed or incomplete"})
 			return
 		}
-			res := q.Unscoped().Delete(&model.PlaybackHistory{})
+		res := q.Unscoped().Delete(&model.PlaybackHistory{})
 		if err := res.Error; err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
@@ -0,0 +1,20 @@
+// Emby 媒体库挂载模型。
+//
+// 远程 Emby 账号（StrmAccount.Provider = emby_remote）只是一个服务器连接；
+// 「挂载」才决定把该服务器的哪个媒体库（View）暴露到本项目的媒体库中。
+// 这样同一个 Emby 服务器可以按库选择挂载，且每个挂载独立控制是否由 MMTL
+// 代理播放流量。
+package model
+
+// EmbyMount 是远程 Emby 服务器上一个媒体库（View）的挂载配置。
+type EmbyMount struct {
+	Base
+	AccountID      string `gorm:"size:36;index" json:"account_id"`   // StrmAccount.ID（provider=emby_remote）
+	RemoteViewID   string `gorm:"size:128" json:"remote_view_id"`    // 远程 Emby 的 View Id
+	RemoteViewName string `gorm:"size:255" json:"remote_view_name"`  // 远程媒体库原名（展示冗余）
+	CollectionType string `gorm:"size:32" json:"collection_type"`    // movies / tvshows / music ...
+	Name           string `gorm:"size:255" json:"name,omitempty"`    // 覆盖显示名（可选，默认「账号 · 库名」）
+	SortOrder      int    `gorm:"default:0;index" json:"sort_order"` // 手动排序用，越小越靠前
+	ProxyPlay      bool   `gorm:"default:false" json:"proxy_play"`   // 该挂载播放流量是否经 MMTL 反向代理
+	Enabled        bool   `gorm:"default:true" json:"enabled"`       // 是否在媒体库中展示
+}
@@ -8,8 +8,8 @@ type Library struct {
 	Type            string        `gorm:"size:16;not null;default:movie" json:"type"` // movie / tv / anime / music
 	CoverURL        string        `gorm:"size:1024" json:"cover_url,omitempty"`
 	Enabled         bool          `gorm:"default:true" json:"enabled"`
-	SortOrder       int           `gorm:"index;default:0" json:"sort_order"`            // 手动拖拽排序用，越小越靠前
-	CarouselEnabled bool          `gorm:"default:false" json:"carousel_enabled"`        // 是否参与首页海报轮播（默认不参与）
+	SortOrder       int           `gorm:"index;default:0" json:"sort_order"`     // 手动拖拽排序用，越小越靠前
+	CarouselEnabled bool          `gorm:"default:false" json:"carousel_enabled"` // 是否参与首页海报轮播（默认不参与）
 	Roots           []LibraryRoot `gorm:"foreignKey:LibraryID" json:"roots,omitempty"`
 }

@@ -54,9 +54,10 @@ func AllModels() []interface{} {
 		&StrmAccount{},
 		&StrmSyncPath{},
 		&StrmSyncRecord{},
-			&StrmDownloadTask{},
-			&StrmUploadTask{},
-			&StrmDirCache{},
-			&ScrapeTask{},
-		}
+		&StrmDownloadTask{},
+		&StrmUploadTask{},
+		&StrmDirCache{},
+		&ScrapeTask{},
+		&EmbyMount{},
+	}
 }
@@ -18,8 +18,8 @@ type ScrapeTask struct {
 	LibraryName    string     `gorm:"size:128" json:"library_name"`
 	MediaTitle     string     `gorm:"size:255;not null" json:"media_title"`
 	MediaPath      string     `gorm:"size:1024;not null" json:"media_path"`
-	MediaType      string     `gorm:"size:16" json:"media_type"`                   // movie / tv / anime / adult
-	Provider       string     `gorm:"size:32" json:"provider"`                     // tmdb / douban / bangumi / thetvdb / metatube
+	MediaType      string     `gorm:"size:16" json:"media_type"` // movie / tv / anime / adult
+	Provider       string     `gorm:"size:32" json:"provider"`   // tmdb / douban / bangumi / thetvdb / metatube
 	MatchedTitle   string     `gorm:"size:255" json:"matched_title"`
 	MatchedYear    int        `json:"matched_year"`
 	PosterURL      string     `gorm:"size:1024" json:"poster_url"`
@@ -13,6 +13,7 @@ const (
 	StrmProviderCloudDrive = "clouddrive2" // CloudDrive2（WebDAV 桥接）
 	StrmProviderOpenList   = "openlist"    // OpenList / AList 兼容桥接
 	StrmProviderLocal      = "local"       // 本地目录（无账号）
+	StrmProviderEmbyRemote = "emby_remote" // 远程 Emby 服务器（API 网关聚合挂载，不走 STRM 同步）
 )

 // StrmAccount 是一个网盘账号（STRM 同步数据源凭据）。
@@ -37,17 +38,17 @@ type StrmSyncPath struct {
 	RemotePath string `gorm:"size:1024" json:"remote_path"`    // 远端目录：115=目录ID，OpenList/CD2=路径，local=源目录
 	LocalPath  string `gorm:"size:1024" json:"local_path"`     // STRM/元数据本地输出目录
 	// STRM 链接配置（空值继承全局 strm.* 设置）
-	StrmBaseURL     string     `gorm:"size:512" json:"strm_base_url"`     // 覆盖 strm.base_url
-	VideoExt        string     `gorm:"size:512" json:"video_ext"`         // 逗号分隔，覆盖 strm.video_ext
-	MetaExt         string     `gorm:"size:512" json:"meta_ext"`          // 逗号分隔，覆盖 strm.meta_ext
-	ExcludeName     string     `gorm:"size:512" json:"exclude_name"`      // 逗号分隔，文件名包含即跳过
-	MinVideoSizeMB  int64      `json:"min_video_size_mb"`                 // 小于该大小（MB）的视频不生成 STRM
-	AddPath         int        `json:"add_path"`                          // STRM 链接 path 参数：1=完整远端路径 2=仅文件名 3=不带
-	DownloadMeta    bool       `gorm:"default:true" json:"download_meta"` // 同步时下载元数据文件（nfo/图片/字幕）
-	UploadMeta      bool       `json:"upload_meta"`                       // 同步时把本地元数据上传到远端
-	DeleteDir       bool       `json:"delete_dir"`                        // 清理多余文件时删除空目录
-	Cron            string     `gorm:"size:128" json:"cron"`              // 5 段 cron 表达式（可选）
-	EnableCron      bool       `json:"enable_cron"`                       // 是否按 Cron 定时同步
+	StrmBaseURL     string     `gorm:"size:512" json:"strm_base_url"`                  // 覆盖 strm.base_url
+	VideoExt        string     `gorm:"size:512" json:"video_ext"`                      // 逗号分隔，覆盖 strm.video_ext
+	MetaExt         string     `gorm:"size:512" json:"meta_ext"`                       // 逗号分隔，覆盖 strm.meta_ext
+	ExcludeName     string     `gorm:"size:512" json:"exclude_name"`                   // 逗号分隔，文件名包含即跳过
+	MinVideoSizeMB  int64      `json:"min_video_size_mb"`                              // 小于该大小（MB）的视频不生成 STRM
+	AddPath         int        `json:"add_path"`                                       // STRM 链接 path 参数：1=完整远端路径 2=仅文件名 3=不带
+	DownloadMeta    bool       `gorm:"default:true" json:"download_meta"`              // 同步时下载元数据文件（nfo/图片/字幕）
+	UploadMeta      bool       `json:"upload_meta"`                                    // 同步时把本地元数据上传到远端
+	DeleteDir       bool       `json:"delete_dir"`                                     // 清理多余文件时删除空目录
+	Cron            string     `gorm:"size:128" json:"cron"`                           // 5 段 cron 表达式（可选）
+	EnableCron      bool       `json:"enable_cron"`                                    // 是否按 Cron 定时同步
 	SyncMode        string     `gorm:"size:32;default:'incremental'" json:"sync_mode"` // 默认同步模式：incremental / full
 	Enabled         bool       `gorm:"default:true" json:"enabled"`
 	LastSyncAt      *time.Time `json:"last_sync_at"`
@@ -139,4 +140,3 @@ type StrmDirCache struct {
 	DirID      string `gorm:"size:128;index:idx_strm_dir_cache,priority:2" json:"dir_id"`
 	Path       string `gorm:"size:1024" json:"path"` // 相对根目录的路径
 }
-
@@ -1,6 +1,10 @@
 package model

-import "time"
+import (
+	"encoding/json"
+	"strings"
+	"time"
+)

 // User 是本地账户。第一个注册的管理员（或种子管理员）获得 "admin" 角色；
 // 其他所有用户默认为 "user"。
@@ -17,6 +21,10 @@ type User struct {
 	ForcePasswordReset bool       `gorm:"default:false" json:"force_password_reset"`
 	IsActive           bool       `gorm:"default:true" json:"is_active"`
 	LastLoginAt        *time.Time `json:"last_login_at,omitempty"`
+	// AllowedLibraryIDs 存储管理员为该用户指定的受限可访问媒体库 ID 列表（JSON 字符串）。
+	// 为空时代表不限制（全库可访问）。
+	AllowedLibraryIDs  string   `gorm:"type:text" json:"-"`
+	AllowedLibraryList []string `gorm:"-" json:"allowed_library_ids,omitempty"`
 	// ExpiredAt is the account expiry time. Nil means the account never
 	// expires. When set and in the past, the account is treated as expired
 	// (login blocked) until an admin or a redemption code renews it.
@@ -31,3 +39,30 @@ type User struct {
 	RealtimeOnline      bool       `gorm:"-" json:"realtime_online,omitempty"`
 	RealtimeDeviceCount int        `gorm:"-" json:"realtime_device_count,omitempty"`
 }
+
+// DecodeAllowedLibraryIDs 解析 AllowedLibraryIDs 字段。
+func (u *User) DecodeAllowedLibraryIDs() []string {
+	if u == nil || strings.TrimSpace(u.AllowedLibraryIDs) == "" {
+		return nil
+	}
+	var ids []string
+	if err := json.Unmarshal([]byte(u.AllowedLibraryIDs), &ids); err != nil {
+		return nil
+	}
+	var out []string
+	for _, id := range ids {
+		trimmed := strings.TrimSpace(id)
+		if trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+// PopulateComputedFields 填充非 DB 虚拟计算字段（如 AllowedLibraryList）。
+func (u *User) PopulateComputedFields() {
+	if u == nil {
+		return
+	}
+	u.AllowedLibraryList = u.DecodeAllowedLibraryIDs()
+}
@@ -0,0 +1,127 @@
+package repository
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+// EmbyMountRepository 持久化远程 Emby 媒体库挂载。
+type EmbyMountRepository struct{ db *gorm.DB }
+
+func (r *EmbyMountRepository) Create(ctx context.Context, m *model.EmbyMount) error {
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+			if m != nil && m.SortOrder == 0 {
+				var maxSort int
+				_ = tx.Model(&model.EmbyMount{}).Select("COALESCE(MAX(sort_order), -1)").Scan(&maxSort)
+				m.SortOrder = maxSort + 1
+			}
+			return tx.Create(m).Error
+		})
+	})
+}
+
+func (r *EmbyMountRepository) CreateInBatches(ctx context.Context, mounts []*model.EmbyMount, batchSize int) error {
+	if len(mounts) == 0 {
+		return nil
+	}
+	if batchSize <= 0 {
+		batchSize = 50
+	}
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+			var maxSort int
+			_ = tx.Model(&model.EmbyMount{}).Select("COALESCE(MAX(sort_order), -1)").Scan(&maxSort)
+			for _, m := range mounts {
+				if m != nil && m.SortOrder == 0 {
+					maxSort++
+					m.SortOrder = maxSort
+				}
+			}
+			return tx.CreateInBatches(mounts, batchSize).Error
+		})
+	})
+}
+
+func (r *EmbyMountRepository) FindByID(ctx context.Context, id string) (*model.EmbyMount, error) {
+	var m model.EmbyMount
+	err := r.db.WithContext(ctx).Where("id = ?", id).First(&m).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &m, nil
+}
+
+func (r *EmbyMountRepository) List(ctx context.Context) ([]model.EmbyMount, error) {
+	var rows []model.EmbyMount
+	err := r.db.WithContext(ctx).Order("sort_order asc, created_at asc").Find(&rows).Error
+	return rows, err
+}
+
+func (r *EmbyMountRepository) ListByAccountID(ctx context.Context, accountID string) ([]model.EmbyMount, error) {
+	var rows []model.EmbyMount
+	err := r.db.WithContext(ctx).Where("account_id = ?", accountID).Order("sort_order asc, created_at asc").Find(&rows).Error
+	return rows, err
+}
+
+func (r *EmbyMountRepository) SetSortOrder(ctx context.Context, ids []string) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+			for i, id := range ids {
+				if err := tx.Model(&model.EmbyMount{}).Where("id = ?", id).
+					Update("sort_order", i).Error; err != nil {
+					return err
+				}
+			}
+			return nil
+		})
+	})
+}
+
+func (r *EmbyMountRepository) CountByAccountID(ctx context.Context, accountID string) (int64, error) {
+	var count int64
+	err := r.db.WithContext(ctx).Model(&model.EmbyMount{}).Where("account_id = ?", accountID).Count(&count).Error
+	return count, err
+}
+
+func (r *EmbyMountRepository) Update(ctx context.Context, m *model.EmbyMount) error {
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Model(&model.EmbyMount{}).Where("id = ?", m.ID).Updates(map[string]any{
+			"name":             m.Name,
+			"proxy_play":       m.ProxyPlay,
+			"enabled":          m.Enabled,
+			"remote_view_id":   m.RemoteViewID,
+			"remote_view_name": m.RemoteViewName,
+			"collection_type":  m.CollectionType,
+			"updated_at":       time.Now(),
+		}).Error
+	})
+}
+
+func (r *EmbyMountRepository) Delete(ctx context.Context, id string) error {
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Where("id = ?", id).Delete(&model.EmbyMount{}).Error
+	})
+}
+
+// DeleteByAccountID 删除账号下全部挂载（删除账号时级联清理）。
+func (r *EmbyMountRepository) DeleteByAccountID(ctx context.Context, accountID string) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Where("account_id = ?", accountID).Delete(&model.EmbyMount{})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
@@ -0,0 +1,74 @@
+package repository
+
+import (
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/ShukeBta/MMTL/internal/database"
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+func TestEmbyMountSortOrderAndReorder(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := database.AutoMigrate(db); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := New(db)
+	ctx := t.Context()
+
+	// 1. Create mounts and verify auto-assigned sort_order
+	m1 := &model.EmbyMount{AccountID: "acct-1", RemoteViewID: "view-1", Name: "Mount 1"}
+	m2 := &model.EmbyMount{AccountID: "acct-1", RemoteViewID: "view-2", Name: "Mount 2"}
+	m3 := &model.EmbyMount{AccountID: "acct-1", RemoteViewID: "view-3", Name: "Mount 3"}
+
+	if err := repos.EmbyMount.Create(ctx, m1); err != nil {
+		t.Fatalf("create m1: %v", err)
+	}
+	if err := repos.EmbyMount.Create(ctx, m2); err != nil {
+		t.Fatalf("create m2: %v", err)
+	}
+	if err := repos.EmbyMount.Create(ctx, m3); err != nil {
+		t.Fatalf("create m3: %v", err)
+	}
+
+	if m1.SortOrder >= m2.SortOrder || m2.SortOrder >= m3.SortOrder {
+		t.Fatalf("expected ascending sort order on create: m1=%d, m2=%d, m3=%d",
+			m1.SortOrder, m2.SortOrder, m3.SortOrder)
+	}
+
+	// 2. Query list and verify initial order
+	list, err := repos.EmbyMount.List(ctx)
+	if err != nil {
+		t.Fatalf("list mounts: %v", err)
+	}
+	if len(list) != 3 || list[0].ID != m1.ID || list[1].ID != m2.ID || list[2].ID != m3.ID {
+		t.Fatalf("unexpected list order: %+v", list)
+	}
+
+	// 3. Reorder: m3, m1, m2
+	if err := repos.EmbyMount.SetSortOrder(ctx, []string{m3.ID, m1.ID, m2.ID}); err != nil {
+		t.Fatalf("SetSortOrder failed: %v", err)
+	}
+
+	// 4. Query list again and verify updated order
+	reordered, err := repos.EmbyMount.List(ctx)
+	if err != nil {
+		t.Fatalf("list mounts after reorder: %v", err)
+	}
+	if len(reordered) != 3 {
+		t.Fatalf("expected 3 mounts, got %d", len(reordered))
+	}
+	if reordered[0].ID != m3.ID || reordered[1].ID != m1.ID || reordered[2].ID != m2.ID {
+		t.Fatalf("expected order [m3, m1, m2], got: %s, %s, %s",
+			reordered[0].ID, reordered[1].ID, reordered[2].ID)
+	}
+	if reordered[0].SortOrder != 0 || reordered[1].SortOrder != 1 || reordered[2].SortOrder != 2 {
+		t.Fatalf("unexpected sort orders: %d, %d, %d",
+			reordered[0].SortOrder, reordered[1].SortOrder, reordered[2].SortOrder)
+	}
+}
@@ -23,7 +23,7 @@ func (r *FavoriteRepository) Toggle(ctx context.Context, userID, mediaID string)
 	if err != nil {
 		return false, err
 	}
-		return false, r.db.WithContext(ctx).Unscoped().Delete(&f).Error
+	return false, r.db.WithContext(ctx).Unscoped().Delete(&f).Error
 }

 // ListByUser returns all favourite media IDs for a user.
@@ -3,6 +3,8 @@ package repository
 import (
 	"context"
 	"errors"
+	"fmt"
+	"strings"
 	"sync"

 	"gorm.io/gorm"
@@ -87,6 +89,18 @@ func (r *MediaRepository) ListByLibraryFiltered(ctx context.Context, libraryID s
 }

 func (r *MediaRepository) ListByLibrariesFiltered(ctx context.Context, libraryIDs []string, offset, limit int, filter MediaQueryFilter) ([]model.Media, int64, error) {
+	items, total, err := r.listByLibrariesFiltered(ctx, libraryIDs, offset, limit, filter, true)
+	return items, total, err
+}
+
+// ListByLibrariesFilteredNoCount skips the COUNT query when the caller already
+// knows totals or only needs a bounded slice (e.g. home-page previews).
+func (r *MediaRepository) ListByLibrariesFilteredNoCount(ctx context.Context, libraryIDs []string, offset, limit int, filter MediaQueryFilter) ([]model.Media, error) {
+	items, _, err := r.listByLibrariesFiltered(ctx, libraryIDs, offset, limit, filter, false)
+	return items, err
+}
+
+func (r *MediaRepository) listByLibrariesFiltered(ctx context.Context, libraryIDs []string, offset, limit int, filter MediaQueryFilter, withCount bool) ([]model.Media, int64, error) {
 	var items []model.Media
 	var total int64
 	if len(libraryIDs) == 0 {
@@ -99,8 +113,10 @@ func (r *MediaRepository) ListByLibrariesFiltered(ctx context.Context, libraryID
 		q = q.Where("library_id IN ?", libraryIDs)
 	}
 	q = applyMediaQueryFilter(q, filter)
-	if err := q.Count(&total).Error; err != nil {
-		return nil, 0, err
+	if withCount {
+		if err := q.Count(&total).Error; err != nil {
+			return nil, 0, err
+		}
 	}
 	// 多级排序消除"随机"观感:
 	//  1. release_date desc — 精确上映/首播日期新→旧
@@ -114,6 +130,104 @@ func (r *MediaRepository) ListByLibrariesFiltered(ctx context.Context, libraryID
 	return items, total, err
 }

+type rankedMediaRow struct {
+	model.Media
+	MmtlRN int `gorm:"column:mmtl_rn"`
+}
+
+// ListRecentByLibraries returns up to perLibrary recent items for each library
+// in a single query using a window function (avoids N+1 on home preview).
+func (r *MediaRepository) ListRecentByLibraries(ctx context.Context, libraryIDs []string, perLibrary int, filter MediaQueryFilter) (map[string][]model.Media, error) {
+	out := make(map[string][]model.Media, len(libraryIDs))
+	if len(libraryIDs) == 0 || perLibrary <= 0 {
+		return out, nil
+	}
+
+	var libClause string
+	var args []interface{}
+	if len(libraryIDs) == 1 {
+		libClause = "library_id = ?"
+		args = append(args, libraryIDs[0])
+	} else {
+		libClause = "library_id IN ?"
+		args = append(args, libraryIDs)
+	}
+	where := "deleted_at IS NULL AND " + libClause
+	if filterSQL, filterArgs := mediaQueryFilterSQL(filter); filterSQL != "" {
+		where += " AND " + filterSQL
+		args = append(args, filterArgs...)
+	}
+	args = append(args, perLibrary)
+
+	sql := fmt.Sprintf(`
+		SELECT * FROM (
+			SELECT *, ROW_NUMBER() OVER (
+				PARTITION BY library_id
+				ORDER BY release_date DESC, year DESC, updated_at DESC, created_at DESC, id DESC
+			) AS mmtl_rn
+			FROM media
+			WHERE %s
+		) ranked
+		WHERE mmtl_rn <= ?
+	`, where)
+
+	var rows []rankedMediaRow
+	if err := r.db.WithContext(ctx).Raw(sql, args...).Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	for _, row := range rows {
+		out[row.LibraryID] = append(out[row.LibraryID], row.Media)
+	}
+	return out, nil
+}
+
+func mediaQueryFilterSQL(filter MediaQueryFilter) (string, []interface{}) {
+	var parts []string
+	var args []interface{}
+	if !filter.IncludeNSFW {
+		parts = append(parts, "nsfw = ?")
+		args = append(args, false)
+	}
+	if len(filter.HiddenLibraryIDs) > 0 {
+		parts = append(parts, "library_id NOT IN ?")
+		args = append(args, filter.HiddenLibraryIDs)
+	}
+	if len(filter.AllowedLibraryIDs) > 0 {
+		parts = append(parts, "library_id IN ?")
+		args = append(args, filter.AllowedLibraryIDs)
+	}
+	return strings.Join(parts, " AND "), args
+}
+
+type libraryCountRow struct {
+	LibraryID string `gorm:"column:library_id"`
+	Total     int64  `gorm:"column:total"`
+}
+
+// CountByLibraries returns a map of library_id -> total media count for the given library IDs.
+func (r *MediaRepository) CountByLibraries(ctx context.Context, libraryIDs []string, filter MediaQueryFilter) (map[string]int64, error) {
+	out := make(map[string]int64, len(libraryIDs))
+	if len(libraryIDs) == 0 {
+		return out, nil
+	}
+	var rows []libraryCountRow
+	q := r.db.WithContext(ctx).Model(&model.Media{}).
+		Select("library_id, count(*) as total")
+	if len(libraryIDs) == 1 {
+		q = q.Where("library_id = ?", libraryIDs[0])
+	} else {
+		q = q.Where("library_id IN ?", libraryIDs)
+	}
+	q = applyMediaQueryFilter(q, filter)
+	if err := q.Group("library_id").Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	for _, row := range rows {
+		out[row.LibraryID] = row.Total
+	}
+	return out, nil
+}
+
 // DeleteByLibrary purges all media tied to a library.
 func (r *MediaRepository) DeleteByLibrary(ctx context.Context, libraryID string) error {
 	// FTS 行由 media 表上的触发器同步清理（物理删除触发 FTS 清理）。
@@ -0,0 +1,72 @@
+package repository
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/ShukeBta/MMTL/internal/database"
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+func TestListRecentByLibraries(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := database.AutoMigrate(db); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repos := New(db)
+
+	lib1 := model.Library{Name: "电影", Path: "/media/movies", Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib1); err != nil {
+		t.Fatal(err)
+	}
+	lib2 := model.Library{Name: "动漫", Path: "/media/anime", Type: "anime", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib2); err != nil {
+		t.Fatal(err)
+	}
+
+	now := time.Date(2026, 7, 2, 12, 0, 0, 0, time.UTC)
+	var rows []model.Media
+	for i := 1; i <= 5; i++ {
+		rows = append(rows, model.Media{
+			Base:      model.Base{ID: fmt.Sprintf("movie-%02d", i), CreatedAt: now.Add(time.Duration(i) * time.Hour)},
+			LibraryID: lib1.ID,
+			Title:     fmt.Sprintf("电影%d", i),
+			Path:      fmt.Sprintf("/media/movies/电影%d/movie%d.mp4", i, i),
+		})
+	}
+	for i := 1; i <= 8; i++ {
+		rows = append(rows, model.Media{
+			Base:       model.Base{ID: fmt.Sprintf("anime-ep-%02d", i), CreatedAt: now.Add(time.Duration(i) * time.Minute)},
+			LibraryID:  lib2.ID,
+			Title:      fmt.Sprintf("某动漫 第%d集", i),
+			Path:       fmt.Sprintf("/media/anime/某动漫/Season 01/某动漫.S01E%02d.mp4", i),
+			SeasonNum:  1,
+			EpisodeNum: i,
+		})
+	}
+	if err := repos.DB.Create(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	filter := MediaQueryFilter{IncludeNSFW: true}
+	got, err := repos.Media.ListRecentByLibraries(t.Context(), []string{lib1.ID, lib2.ID}, 3, filter)
+	if err != nil {
+		t.Fatalf("ListRecentByLibraries failed: %v", err)
+	}
+	if len(got[lib1.ID]) != 3 {
+		t.Fatalf("lib1 recent count = %d, want 3", len(got[lib1.ID]))
+	}
+	if len(got[lib2.ID]) != 3 {
+		t.Fatalf("lib2 recent count = %d, want 3", len(got[lib2.ID]))
+	}
+	if got[lib1.ID][0].ID != "movie-05" {
+		t.Fatalf("lib1 newest = %q, want movie-05", got[lib1.ID][0].ID)
+	}
+}
@@ -30,10 +30,11 @@ type Container struct {
 	StrmSyncPath   *StrmSyncPathRepository
 	StrmSyncRecord *StrmSyncRecordRepository
 	StrmDownload   *StrmDownloadTaskRepository
-		StrmUpload     *StrmUploadTaskRepository
-		StrmDirCache   *StrmDirCacheRepository
-		ScrapeTask     *ScrapeTaskRepository
-	}
+	StrmUpload     *StrmUploadTaskRepository
+	StrmDirCache   *StrmDirCacheRepository
+	ScrapeTask     *ScrapeTaskRepository
+	EmbyMount      *EmbyMountRepository
+}

 // New 将每个 repository 连接到单个 *gorm.DB。
 func New(db *gorm.DB) *Container {
@@ -62,5 +63,6 @@ func New(db *gorm.DB) *Container {
 		StrmUpload:     &StrmUploadTaskRepository{db: db},
 		StrmDirCache:   &StrmDirCacheRepository{db: db},
 		ScrapeTask:     &ScrapeTaskRepository{db: db},
+		EmbyMount:      &EmbyMountRepository{db: db},
 	}
 }
@@ -675,6 +675,29 @@ func (r *StrmUploadTaskRepository) CancelBatch(ctx context.Context, ids []string
 	return count, err
 }

+// ClearDone 清空全部已完成上传任务。
+func (r *StrmUploadTaskRepository) ClearDone(ctx context.Context) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Unscoped().Where("status = ?", model.StrmTaskDone).Delete(&model.StrmUploadTask{})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
+
+// ClearFinished 清空全部已完成与失败上传任务（包括已完成、失败及取消）。
+func (r *StrmUploadTaskRepository) ClearFinished(ctx context.Context) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Unscoped().Where("status IN ?", []string{model.StrmTaskDone, model.StrmTaskFailed, model.StrmTaskCanceled}).
+			Delete(&model.StrmUploadTask{})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
+
 // ClearCanceled 清空全部已取消上传任务。
 func (r *StrmUploadTaskRepository) ClearCanceled(ctx context.Context) (int64, error) {
 	var count int64
@@ -686,6 +709,27 @@ func (r *StrmUploadTaskRepository) ClearCanceled(ctx context.Context) (int64, er
 	return count, err
 }

+// RetryAllFailed 把所有失败任务重置回待处理，清空错误与重试计数。
+func (r *StrmUploadTaskRepository) RetryAllFailed(ctx context.Context) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Model(&model.StrmUploadTask{}).
+			Where("status = ?", model.StrmTaskFailed).
+			Updates(map[string]any{
+				"status":      model.StrmTaskPending,
+				"error":       "",
+				"retry_count": 0,
+				"next_try_at": nil,
+				"started_at":  nil,
+				"finished_at": nil,
+				"updated_at":  time.Now(),
+			})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
+
 // CancelPending 批量取消所有排队中和进行中的任务。
 func (r *StrmUploadTaskRepository) CancelPending(ctx context.Context) (int64, error) {
 	now := time.Now()
@@ -777,5 +821,3 @@ func (r *StrmDirCacheRepository) DeleteBySyncPathID(ctx context.Context, syncPat
 		return r.db.WithContext(ctx).Unscoped().Where("sync_path_id = ?", syncPathID).Delete(&model.StrmDirCache{}).Error
 	})
 }
-
-
@@ -4,8 +4,11 @@
 package service

 import (
+	"errors"
 	"os"
 	"path/filepath"
+	"sort"
+	"strings"
 	"time"
 )

@@ -42,3 +45,96 @@ func walkAndPrune(root string, cutoff time.Time) error {
 	}
 	return nil
 }
+
+// PruneImageCacheResult holds stats from an image cache prune operation.
+type PruneImageCacheResult struct {
+	TotalFilesBefore int
+	TotalBytesBefore int64
+	DeletedFiles     int
+	FreedBytes       int64
+	RemainingBytes   int64
+}
+
+type imageCacheFileEntry struct {
+	path    string
+	size    int64
+	modTime time.Time
+}
+
+// PruneImageCache scans imagesDir for cached image files. If the total disk usage
+// exceeds maxSizeBytes, it removes files starting from the oldest (by ModTime)
+// until disk usage falls to or below targetSizeBytes (80% of maxSizeBytes).
+//
+// In-flight temporary files (*.tmp) are skipped to avoid corrupting concurrent writes.
+// Empty subdirectories left behind are best-effort removed.
+func PruneImageCache(imagesDir string, maxSizeBytes int64) (PruneImageCacheResult, error) {
+	var result PruneImageCacheResult
+	if imagesDir == "" || maxSizeBytes <= 0 {
+		return result, nil
+	}
+	if _, err := os.Stat(imagesDir); err != nil {
+		return result, nil
+	}
+
+	var (
+		dirs    []string
+		entries []imageCacheFileEntry
+	)
+
+	_ = filepath.Walk(imagesDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+		if info.IsDir() {
+			if path != imagesDir {
+				dirs = append(dirs, path)
+			}
+			return nil
+		}
+		// Skip temporary files created during image download.
+		name := info.Name()
+		if strings.HasSuffix(name, ".tmp") || strings.HasPrefix(name, "img-") && strings.Contains(name, ".tmp") {
+			return nil
+		}
+		size := info.Size()
+		result.TotalFilesBefore++
+		result.TotalBytesBefore += size
+		entries = append(entries, imageCacheFileEntry{
+			path:    path,
+			size:    size,
+			modTime: info.ModTime(),
+		})
+		return nil
+	})
+
+	result.RemainingBytes = result.TotalBytesBefore
+	if result.TotalBytesBefore <= maxSizeBytes {
+		return result, nil
+	}
+
+	// High/Low watermark: prune down to 80% of max size to leave headroom
+	// and prevent disk thrashing on consecutive writes.
+	targetSizeBytes := maxSizeBytes * 80 / 100
+
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].modTime.Before(entries[j].modTime)
+	})
+
+	for _, entry := range entries {
+		if result.RemainingBytes <= targetSizeBytes {
+			break
+		}
+		if err := os.Remove(entry.path); err == nil || errors.Is(err, os.ErrNotExist) {
+			result.DeletedFiles++
+			result.FreedBytes += entry.size
+			result.RemainingBytes -= entry.size
+		}
+	}
+
+	// Clean up emptied subdirectories from deepest to shallowest.
+	for i := len(dirs) - 1; i >= 0; i-- {
+		_ = os.Remove(dirs[i])
+	}
+
+	return result, nil
+}
@@ -0,0 +1,162 @@
+package service
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+func TestPruneImageCache_UnderLimit(t *testing.T) {
+	dir := t.TempDir()
+
+	file1 := filepath.Join(dir, "img1")
+	file2 := filepath.Join(dir, "img2")
+	if err := os.WriteFile(file1, make([]byte, 100), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(file2, make([]byte, 200), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	// Max limit is 500 bytes, total is 300 bytes -> no prune
+	res, err := PruneImageCache(dir, 500)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if res.DeletedFiles != 0 {
+		t.Fatalf("expected 0 deleted files, got %d", res.DeletedFiles)
+	}
+	if res.TotalFilesBefore != 2 || res.TotalBytesBefore != 300 || res.RemainingBytes != 300 {
+		t.Fatalf("unexpected stats: %+v", res)
+	}
+}
+
+func TestPruneImageCache_OverLimitLRU(t *testing.T) {
+	dir := t.TempDir()
+
+	now := time.Now()
+	// Create 4 files of 100 bytes each, with distinct mtime
+	fOldest := filepath.Join(dir, "oldest")
+	fMidOld := filepath.Join(dir, "mid_old")
+	fMidNew := filepath.Join(dir, "mid_new")
+	fNewest := filepath.Join(dir, "newest")
+
+	for _, f := range []string{fOldest, fMidOld, fMidNew, fNewest} {
+		if err := os.WriteFile(f, make([]byte, 100), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	_ = os.Chtimes(fOldest, now.Add(-4*time.Hour), now.Add(-4*time.Hour))
+	_ = os.Chtimes(fMidOld, now.Add(-3*time.Hour), now.Add(-3*time.Hour))
+	_ = os.Chtimes(fMidNew, now.Add(-2*time.Hour), now.Add(-2*time.Hour))
+	_ = os.Chtimes(fNewest, now.Add(-1*time.Hour), now.Add(-1*time.Hour))
+
+	// Total = 400 bytes. Max limit = 300 bytes.
+	// Target = 300 * 80 / 100 = 240 bytes.
+	// Deleting oldest (100) brings total to 300 (> 240).
+	// Deleting mid_old (100) brings total to 200 (<= 240).
+	// Total deleted = 2 files (200 bytes), remaining = 200 bytes.
+	res, err := PruneImageCache(dir, 300)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if res.DeletedFiles != 2 {
+		t.Fatalf("expected 2 deleted files, got %d", res.DeletedFiles)
+	}
+	if res.FreedBytes != 200 {
+		t.Fatalf("expected 200 freed bytes, got %d", res.FreedBytes)
+	}
+	if res.RemainingBytes != 200 {
+		t.Fatalf("expected 200 remaining bytes, got %d", res.RemainingBytes)
+	}
+
+	// Verify oldest and mid_old were deleted, mid_new and newest still exist
+	if _, err := os.Stat(fOldest); !os.IsNotExist(err) {
+		t.Fatalf("expected oldest file to be deleted, got err=%v", err)
+	}
+	if _, err := os.Stat(fMidOld); !os.IsNotExist(err) {
+		t.Fatalf("expected mid_old file to be deleted, got err=%v", err)
+	}
+	if _, err := os.Stat(fMidNew); err != nil {
+		t.Fatalf("expected mid_new file to exist, got err=%v", err)
+	}
+	if _, err := os.Stat(fNewest); err != nil {
+		t.Fatalf("expected newest file to exist, got err=%v", err)
+	}
+}
+
+func TestPruneImageCache_SkipsTmpFiles(t *testing.T) {
+	dir := t.TempDir()
+
+	fTmp := filepath.Join(dir, "img-123.tmp")
+	fImg := filepath.Join(dir, "cached_img")
+
+	if err := os.WriteFile(fTmp, make([]byte, 500), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(fImg, make([]byte, 100), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	// Limit is 200 bytes. fTmp (500) is ignored, only fImg (100) is counted <= 200.
+	res, err := PruneImageCache(dir, 200)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if res.DeletedFiles != 0 {
+		t.Fatalf("expected 0 deleted files, got %d", res.DeletedFiles)
+	}
+	if _, err := os.Stat(fTmp); err != nil {
+		t.Fatalf("expected tmp file to remain untouched, got %v", err)
+	}
+}
+
+func TestPruneImageCache_ZeroOrNegativeLimit(t *testing.T) {
+	dir := t.TempDir()
+	f := filepath.Join(dir, "img")
+	if err := os.WriteFile(f, make([]byte, 100), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	res, err := PruneImageCache(dir, 0)
+	if err != nil || res.DeletedFiles != 0 {
+		t.Fatalf("expected no-op for 0 limit, got %+v, err=%v", res, err)
+	}
+
+	res, err = PruneImageCache(dir, -10)
+	if err != nil || res.DeletedFiles != 0 {
+		t.Fatalf("expected no-op for negative limit, got %+v, err=%v", res, err)
+	}
+}
+
+func TestSchedulerJobCleanImageCache(t *testing.T) {
+	cacheRoot := t.TempDir()
+	imagesDir := filepath.Join(cacheRoot, "images")
+	if err := os.MkdirAll(imagesDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+
+	f := filepath.Join(imagesDir, "old_poster")
+	if err := os.WriteFile(f, make([]byte, 2*1024*1024), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	scheduler := NewSchedulerService(zap.NewNop(), nil, nil, nil, nil, nil, cacheRoot)
+	// Set limit to 1MB; our file is 2MB -> should be pruned
+	scheduler.SetImagesMaxSizeMBProvider(func() int {
+		return 1
+	})
+
+	if err := scheduler.jobCleanImageCache(context.Background()); err != nil {
+		t.Fatalf("jobCleanImageCache failed: %v", err)
+	}
+
+	if _, err := os.Stat(f); !os.IsNotExist(err) {
+		t.Fatalf("expected file to be pruned, got err=%v", err)
+	}
+}
@@ -30,6 +30,7 @@ const (
 	Type115         = "cloud115"    // 115 网盘
 	TypeCloudDrive2 = "clouddrive2" // CloudDrive2 桥接网盘
 	TypeOpenList    = "openlist"    // OpenList / AList-compatible bridge
+	TypeEmbyRemote  = "emby_remote" // 远程 Emby 服务器（API 网关挂载）
 )

 // ErrUnsupported is returned for an unknown provider type.
@@ -37,11 +38,11 @@ var ErrUnsupported = errors.New("unsupported cloud provider")

 // FileEntry is one item in a cloud directory listing.
 type FileEntry struct {
-	ID       string `json:"id"` // provider-native file id
-	Name     string `json:"name"`
-	IsDir    bool   `json:"is_dir"`
-	Size     int64  `json:"size"`
-	MTime    int64  `json:"mtime,omitempty"`
+	ID    string `json:"id"` // provider-native file id
+	Name  string `json:"name"`
+	IsDir bool   `json:"is_dir"`
+	Size  int64  `json:"size"`
+	MTime int64  `json:"mtime,omitempty"`
 	// PickCode is 115-specific; other providers use ID directly.
 	PickCode string `json:"pick_code,omitempty"`
 }
@@ -101,6 +102,8 @@ func New(typ string, cfg map[string]any, client *http.Client) (Provider, error)
 		return newCloudDrive2(cfg, client), nil
 	case TypeOpenList:
 		return newOpenList(cfg, client), nil
+	case TypeEmbyRemote:
+		return newEmby(cfg, client), nil
 	default:
 		return nil, ErrUnsupported
 	}
@@ -108,7 +111,7 @@ func New(typ string, cfg map[string]any, client *http.Client) (Provider, error)

 // IsCloudType reports whether typ is a cloud-disk provider.
 func IsCloudType(typ string) bool {
-	return typ == Type115 || typ == TypeCloudDrive2 || typ == TypeOpenList
+	return typ == Type115 || typ == TypeCloudDrive2 || typ == TypeOpenList || typ == TypeEmbyRemote
 }

 // str coerces a config value to a trimmed string.
@@ -0,0 +1,246 @@
+// Emby remote provider: exposes a remote Emby server through the same
+// Provider interface used by cloud disks, so account CRUD / connectivity
+// test / directory browser work unchanged. This is a thin adapter — the
+// federated Emby API aggregation (Views / Items / PlaybackInfo / streaming
+// proxy) lives in service.EmbyRemoteService and does not go through the
+// cloud-disk sync machinery.
+package cloud
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+)
+
+// Emby 远程挂载类型（service 层聚合走 EmbyRemoteService，不走 STRM 同步）。
+
+// embyProvider implements Provider against a remote Emby server using an
+// api_key (token) for authentication. DirectLink.Resolve returns the remote
+// stream URL; whether MMTL reverse-proxies the bytes is decided by the
+// emby.proxy_play account config (defaults to off).
+type embyProvider struct {
+	base      string // e.g. http://host:8096（自动补 /emby 前缀）
+	username  string
+	password  string
+	token     string // api_key
+	userID    string // 远程用户 Id
+	proxyPlay bool
+	client    *http.Client
+}
+
+type embyUserPayload struct {
+	Id string `json:"Id"`
+}
+
+type embyLoginResponse struct {
+	AccessToken string          `json:"AccessToken"`
+	User        embyUserPayload `json:"User"`
+}
+
+type embyPingResponse struct {
+	ServerName string `json:"ServerName"`
+}
+
+// newEmby builds the provider from the account config map.
+func newEmby(cfg map[string]any, client *http.Client) Provider {
+	p := &embyProvider{
+		base:      strings.TrimRight(str(cfg["url"]), "/"),
+		username:  str(cfg["username"]),
+		password:  str(cfg["password"]),
+		token:     firstNonEmpty(str(cfg["api_key"]), str(cfg["token"])),
+		userID:    str(cfg["remote_user_id"]),
+		proxyPlay: boolish(cfg["proxy_play"]),
+		client:    client,
+	}
+	if p.client == nil {
+		p.client = &http.Client{Transport: &embyUATransport{base: http.DefaultTransport}}
+	}
+	return p
+}
+
+// embyUATransport 给远程 Emby 请求注入浏览器 UA（防 Cloudflare 风控拦截）。
+type embyUATransport struct {
+	base http.RoundTripper
+}
+
+func (t *embyUATransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if strings.TrimSpace(req.Header.Get("User-Agent")) == "" {
+		req.Header.Set("User-Agent", defaultUA)
+	}
+	return t.base.RoundTrip(req)
+}
+
+// embyBase normalizes the address so requests go to /emby/... endpoints.
+func (p *embyProvider) embyBase() string {
+	base := strings.TrimRight(p.base, "/")
+	if !strings.Contains(base, "/emby") {
+		base += "/emby"
+	}
+	return base
+}
+
+// externalBase 不追加 /emby（内嵌媒体资源 URL 使用 /emby 会更贴近习惯，此处
+// 与 embyBase 保持一致：所有端点统一以 /emby 开头）。
+func (p *embyProvider) apiBase() string { return p.embyBase() }
+
+func (p *embyProvider) Type() string { return TypeEmbyRemote }
+
+// Ping 验证地址连通性与凭据（/System/Info）。
+func (p *embyProvider) Ping(ctx context.Context) error {
+	if p.base == "" {
+		return errors.New("缺少 Emby 地址")
+	}
+	token, err := p.ensureToken(ctx)
+	if err != nil {
+		return err
+	}
+	return p.doJSON(ctx, http.MethodGet, "/System/Info", nil, token, &embyPingResponse{})
+}
+
+// doJSON 向远程 Emby 发起带 api_key 的请求并解析 JSON 响应。
+func (p *embyProvider) doJSON(ctx context.Context, method, path string, body io.Reader, token string, out any) error {
+	endpoint := p.apiBase() + path
+	if token != "" {
+		sep := "?"
+		if strings.Contains(endpoint, "?") {
+			sep = "&"
+		}
+		endpoint += sep + "api_key=" + url.QueryEscape(token)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, endpoint, body)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("X-Emby-Token", token)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		if resp.StatusCode == http.StatusUnauthorized {
+			return ErrEmbyUnauthorized
+		}
+		data, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return fmt.Errorf("emby 请求失败(%d): %s", resp.StatusCode, strings.TrimSpace(string(data)))
+	}
+	if out == nil {
+		return nil
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+// ErrEmbyUnauthorized 表示远程凭据失效（触发重新认证/打回测试）。
+var ErrEmbyUnauthorized = errors.New("emby 认证失败或凭据已失效")
+
+// ensureToken 返回可用 api_key：已有则直接用，否则尝试账号密码认证。
+func (p *embyProvider) ensureToken(ctx context.Context) (string, error) {
+	if strings.TrimSpace(p.token) != "" {
+		return p.token, nil
+	}
+	if strings.TrimSpace(p.username) == "" {
+		return "", errors.New("缺少 Emby 凭据（token 或 用户名/密码）")
+	}
+	payload := map[string]string{"Username": p.username, "Pw": p.password}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.apiBase()+"/Users/AuthenticateByName", strings.NewReader(string(data)))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Emby-Authorization", `MediaBrowser Client="MMTL", Device="MMTL-Federated", DeviceId="mmtl-federated", Version="1.0"`)
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		return "", fmt.Errorf("emby 登录失败(%d)", resp.StatusCode)
+	}
+	var login embyLoginResponse
+	if err := json.NewDecoder(resp.Body).Decode(&login); err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(login.AccessToken) == "" {
+		return "", errors.New("emby 登录成功但未返回 AccessToken")
+	}
+	p.token = login.AccessToken
+	if login.User.Id != "" {
+		p.userID = login.User.Id
+	}
+	return p.token, nil
+}
+
+// embyItemSummary 目录浏览所需的最小 Emby 条目字段。
+type embyItemSummary struct {
+	Id           string `json:"Id"`
+	Name         string `json:"Name"`
+	Type         string `json:"Type"`
+	IsFolder     bool   `json:"IsFolder"`
+	ChildCount   int    `json:"ChildCount"`
+	RunTimeTicks int64  `json:"RunTimeTicks"`
+}
+
+type embyItemListResponse struct {
+	Items []embyItemSummary `json:"Items"`
+}
+
+// List 把远程媒体库(View)展开为目录树：dirID 为空=媒体库列表；否则返回该
+// 目录(Movie/Series/Season/Folder)下的条目。用于账号「浏览目录」调试入口。
+func (p *embyProvider) List(ctx context.Context, dirID string) ([]FileEntry, error) {
+	token, err := p.ensureToken(ctx)
+	if err != nil {
+		return nil, err
+	}
+	userID := p.userID
+	if userID == "" {
+		userID = "0" // 某些 Emby 允许用 0 代表管理员
+	}
+	path := "/Users/" + url.PathEscape(userID) + "/Items"
+	if dirID != "" {
+		path += "?ParentId=" + url.QueryEscape(dirID)
+	} else {
+		path += "?IncludeItemTypes=CollectionFolder"
+	}
+	var out embyItemListResponse
+	if err := p.doJSON(ctx, http.MethodGet, path, nil, token, &out); err != nil {
+		return nil, err
+	}
+	entries := make([]FileEntry, 0, len(out.Items))
+	for _, it := range out.Items {
+		size := int64(0)
+		if it.RunTimeTicks > 0 {
+			size = it.RunTimeTicks / 10_000_000 // 秒
+		}
+		entries = append(entries, FileEntry{
+			ID:    it.Id,
+			Name:  it.Name,
+			IsDir: it.IsFolder || it.Type != "Movie",
+			Size:  size,
+		})
+	}
+	return entries, nil
+}
+
+// Resolve 返回远程 Emby 直链。Proxy=true 时由调用方(StrmService.ProxyDirect)
+// 反向代理流量；false 时 302 到直链。默认不代理（播放字节不经过 MMTL）。
+func (p *embyProvider) Resolve(ctx context.Context, fileRef string) (*DirectLink, error) {
+	token, err := p.ensureToken(ctx)
+	if err != nil {
+		return nil, err
+	}
+	u := p.apiBase() + "/Videos/" + url.PathEscape(fileRef) + "/stream"
+	u += "?api_key=" + url.QueryEscape(token) + "&Static=true&MediaSourceId=" + url.QueryEscape(fileRef)
+	return &DirectLink{URL: u, Headers: map[string]string{"X-Emby-Token": token}, Proxy: p.proxyPlay}, nil
+}
@@ -0,0 +1,136 @@
+package cloud
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// fakeEmbyServer 记录请求，按路径返回远程 Emby 风格响应。
+func fakeEmbyServer(t *testing.T) *httptest.Server {
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodPost && r.URL.Path == "/emby/Users/AuthenticateByName":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"AccessToken":"remote-token","User":{"Id":"user-9"}}`))
+		case r.URL.Path == "/emby/System/Info":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"ServerName":"RemoteEmby"}`))
+		case r.URL.Path == "/emby/Users/user-9/Items" && r.URL.Query().Get("ParentId") == "":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"Items":[{"Id":"view-1","Name":"Movies","Type":"CollectionFolder","IsFolder":true}]}`))
+		case r.URL.Path == "/emby/Users/user-9/Items":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"Items":[{"Id":"movie-1","Name":"Avatar","Type":"Movie","IsFolder":false}]}`))
+		case strings.Contains(r.URL.Path, "/emby/Videos/movie-1/stream"):
+			w.Header().Set("Content-Type", "video/mp4")
+			_, _ = w.Write([]byte("fake-video-bytes"))
+		default:
+			t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
+		}
+	}))
+}
+
+func TestEmbyProviderPingAuthenticatesAndGetsToken(t *testing.T) {
+	srv := fakeEmbyServer(t)
+	defer srv.Close()
+
+	p, err := New(TypeEmbyRemote, map[string]any{
+		"url":      srv.URL,
+		"username": "alice",
+		"password": "secret",
+	}, srv.Client())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := p.Ping(context.Background()); err != nil {
+		t.Fatalf("ping: %v", err)
+	}
+	// 认证成功后 token 被记住，第二次 Ping 不应再走登录。
+	if err := p.Ping(context.Background()); err != nil {
+		t.Fatalf("ping 2: %v", err)
+	}
+}
+
+func TestEmbyProviderListViewsAndChildren(t *testing.T) {
+	srv := fakeEmbyServer(t)
+	defer srv.Close()
+
+	p, err := New(TypeEmbyRemote, map[string]any{
+		"url":            srv.URL,
+		"api_key":        "fixed-token",
+		"remote_user_id": "user-9",
+	}, srv.Client())
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := p.List(context.Background(), "")
+	if err != nil {
+		t.Fatalf("list root: %v", err)
+	}
+	if len(root) != 1 || root[0].Name != "Movies" || !root[0].IsDir {
+		t.Fatalf("root listing = %+v", root)
+	}
+	children, err := p.List(context.Background(), "view-1")
+	if err != nil {
+		t.Fatalf("list children: %v", err)
+	}
+	if len(children) != 1 || children[0].Name != "Avatar" || children[0].ID != "movie-1" {
+		t.Fatalf("children = %+v", children)
+	}
+}
+
+func TestEmbyProviderResolveDirectURLByDefault(t *testing.T) {
+	srv := fakeEmbyServer(t)
+	defer srv.Close()
+
+	p, err := New(TypeEmbyRemote, map[string]any{
+		"url":            srv.URL,
+		"api_key":        "fixed-token",
+		"remote_user_id": "user-9",
+	}, srv.Client())
+	if err != nil {
+		t.Fatal(err)
+	}
+	link, err := p.Resolve(context.Background(), "movie-1")
+	if err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+	if !strings.Contains(link.URL, "/emby/Videos/movie-1/stream") {
+		t.Fatalf("url = %q", link.URL)
+	}
+	if !strings.Contains(link.URL, "api_key=fixed-token") {
+		t.Fatalf("url missing api_key: %q", link.URL)
+	}
+	// 默认不代理播放流量。
+	if link.Proxy {
+		t.Fatal("emby remote must not proxy by default")
+	}
+}
+
+func TestEmbyProviderResolveProxyWhenConfigured(t *testing.T) {
+	srv := fakeEmbyServer(t)
+	defer srv.Close()
+
+	p, err := New(TypeEmbyRemote, map[string]any{
+		"url":            srv.URL,
+		"api_key":        "fixed-token",
+		"remote_user_id": "user-9",
+		"proxy_play":     "true",
+	}, srv.Client())
+	if err != nil {
+		t.Fatal(err)
+	}
+	link, err := p.Resolve(context.Background(), "movie-1")
+	if err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+	if !link.Proxy {
+		t.Fatal("proxy_play=true must mark link as proxied")
+	}
+	if link.URL == "" {
+		t.Fatal("proxy link must still carry the remote URL")
+	}
+}
@@ -185,7 +185,7 @@ func (c *OpenClient) doJSON(ctx context.Context, method, rawURL string, form map
 		// refresh_token 刷新后重试一次。刷新失败或重试后仍失败才返回，
 		// 避免长时间同步因 token 过期而整体失败。
 		if isTokenCode(base.Code) {
-			if access && c.tryRefreshTokenLocked() {
+			if access && c.tryRefreshTokenLocked(ctx) {
 				continue
 			}
 			if access {
@@ -259,19 +259,43 @@ func (c *OpenClient) doAuthJSONWithUA(ctx context.Context, method, rawURL string
 }

 // tryRefreshTokenLocked 并发安全地刷新 access_token；成功返回 true（调用方
-// 应使用内存中的新 token 重试原请求）。refresh_token 已失效时也会清空内存 token。
-func (c *OpenClient) tryRefreshTokenLocked() bool {
+// 应使用内存中的新 token 重试原请求）。
+//
+// 对"refresh_token 本身已失效/被吊销"（IsRefreshTokenDead，如 40140114/116/119/120）
+// 这类不可恢复的错误直接放弃并清空内存 token（提示需重新授权）。
+// 对其它失败（网络瞬时抖动、刷新接口可重试错误码等）做指数退避重试几次再放弃，
+// 避免同步长任务中途 token 到期时恰好撞上一个短暂的刷新失败就整体失败。
+func (c *OpenClient) tryRefreshTokenLocked(ctx context.Context) bool {
 	c.tokenMu.Lock()
 	defer c.tokenMu.Unlock()
-	token, err := c.RefreshToken(c.RefreshTokenStr)
-	if err != nil {
+	for attempt := 0; attempt < refreshAttempts; attempt++ {
+		token, err := c.RefreshToken(c.RefreshTokenStr)
+		if err == nil {
+			c.SetAuthToken(token.AccessToken, token.RefreshToken)
+			return true
+		}
 		if IsRefreshTokenDead(err) {
 			c.SetAuthToken("", "")
+			return false
+		}
+		// 可恢复失败：退避后重试。ctx 取消时立即放弃。
+		if attempt < refreshAttempts-1 {
+			select {
+			case <-ctx.Done():
+				return false
+			case <-time.After(refreshBackoff(attempt)):
+			}
 		}
-		return false
 	}
-	c.SetAuthToken(token.AccessToken, token.RefreshToken)
-	return true
+	return false
+}
+
+// refreshAttempts 是刷新 access_token 失败时的最大尝试次数（含首次）。
+const refreshAttempts = 3
+
+// refreshBackoff 返回第 attempt 次（从 0 计）刷新失败后的退避时长（指数退避）。
+func refreshBackoff(attempt int) time.Duration {
+	return time.Duration(200*(1<<attempt)) * time.Millisecond // 200ms, 400ms
 }

 // IsThrottleCode 判断是否为限流错误码。
@@ -429,3 +429,46 @@ func TestRemoteFileDetailRelativePath(t *testing.T) {
 		t.Errorf("d3.RelativePath = %q, want %q", got, "")
 	}
 }
+
+// TestFsListRefreshContinue 验证 access_token 在请求中途过期（40140126）时：
+// 自动用 refresh_token 刷新得到新 token，然后对原请求重试成功（同步得以继续）。
+func TestFsListRefreshContinue(t *testing.T) {
+	var filesCalls int
+	var refreshCalls int
+	mockAPI(t, func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/open/refreshToken":
+			refreshCalls++
+			w.Write([]byte(`{"state":true,"data":{"access_token":"at2","refresh_token":"rt2","expires_in":7200}}`))
+		case "/open/ufile/files":
+			filesCalls++
+			switch filesCalls {
+			case 1:
+				// 第一次用旧 access_token，返回过期错误，应触发刷新
+				w.Write([]byte(`{"state":false,"code":40140126,"message":"access_token 校验失败"}`))
+			default:
+				// 刷新后续请求应使用新 access_token
+				if got := r.Header.Get("Authorization"); got != "Bearer at2" {
+					t.Errorf("retried request auth = %q, want Bearer at2", got)
+				}
+				w.Write([]byte(`{"state":true,"path":[],"data":[{"fid":"200","fc":"1","fn":"a.mkv","fs":123,"pc":"pickA"}]}`))
+			}
+		default:
+			t.Errorf("unexpected path %s", r.URL.Path)
+		}
+	})
+	c := NewOpenClient("100195125", "at1", "rt1")
+	files, _, err := c.GetFsList(context.Background(), "0", 0, 100)
+	if err != nil {
+		t.Fatalf("expected sync to continue after refresh, got error: %v", err)
+	}
+	if filesCalls != 2 {
+		t.Fatalf("want 2 files calls (original + retried), got %d", filesCalls)
+	}
+	if refreshCalls == 0 {
+		t.Fatal("expected refresh_token to be used once")
+	}
+	if len(files) != 1 {
+		t.Fatalf("want 1 file, got %d", len(files))
+	}
+}
@@ -62,4 +62,4 @@ func xorDecode(hexStr string) string {
 func dandanplaySignature(appID, appSecret string, ts int64, path string) string {
 	sum := sha256.Sum256([]byte(appID + strconv.FormatInt(ts, 10) + path + appSecret))
 	return base64.StdEncoding.EncodeToString(sum[:])
-}
+}
@@ -81,4 +81,4 @@ func TestDanmakuCredentialsSelection(t *testing.T) {
 	require.False(t, ok)
 	require.Empty(t, id)
 	require.Empty(t, key)
-}
+}
@@ -278,69 +278,171 @@ func TestDanmakuSameBase(t *testing.T) {
 	require.False(t, sameDanmakuBase("", "https://api.dandanplay.net"))
 }

-	// fetchCommentWithFallback：配置源与官方同源时不重复请求；
-	// 全失败时带出最后一跳错误。
-	func TestDanmakuFetchCommentWithFallback(t *testing.T) {
-		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			w.WriteHeader(http.StatusInternalServerError)
-		}))
-		t.Cleanup(srv.Close)
+// fetchCommentWithFallback：配置源与官方同源时不重复请求；
+// 全失败时带出最后一跳错误。
+func TestDanmakuFetchCommentWithFallback(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	t.Cleanup(srv.Close)

-		svc := newDanmakuTestService(t)
-		ctx := context.Background()
-		raw, st, err := svc.fetchCommentWithFallback(ctx, srv.URL, srv.URL, "25484")
-		require.Error(t, err)
-		require.Empty(t, raw)
-		require.Equal(t, "auto", st)
-	}
+	svc := newDanmakuTestService(t)
+	ctx := context.Background()
+	raw, st, err := svc.fetchCommentWithFallback(ctx, srv.URL, srv.URL, "25484")
+	require.Error(t, err)
+	require.Empty(t, raw)
+	require.Equal(t, "auto", st)
+}

-	// 视频即便能命中 Hash 自动识别，当用户传入手动搜索关键词时应跳过 Hash 匹配，走关键词搜索。
-	func TestDanmakuFetchHashMatchSkippedOnManualKeyword(t *testing.T) {
-		videoPath, _ := writeDanmakuTestVideo(t, "测试动画.第01话.mkv")
+// 视频即便能命中 Hash 自动识别，当用户传入手动搜索关键词时应跳过 Hash 匹配，走关键词搜索。
+func TestDanmakuFetchHashMatchSkippedOnManualKeyword(t *testing.T) {
+	videoPath, _ := writeDanmakuTestVideo(t, "测试动画.第01话.mkv")

-		// 官方服务同时提供 match 和 search：
-		// match 会返回 episodeId=25484（动画A）
-		// search 会根据关键词返回 episodeId=99999（动画B）
-		mux := http.NewServeMux()
-		var matchCalled bool
-		mux.HandleFunc("/api/v2/match", func(w http.ResponseWriter, r *http.Request) {
-			matchCalled = true
-			w.Header().Set("Content-Type", "application/json")
-			fmt.Fprint(w, `{"success":true,"isMatched":true,"matches":[{"episodeId":25484,"animeId":1001,"animeTitle":"自动识别动画A","episodeTitle":"第1话"}]}`)
-		})
-		mux.HandleFunc("/api/v2/search/episodes", func(w http.ResponseWriter, r *http.Request) {
-			w.Header().Set("Content-Type", "application/json")
-			fmt.Fprint(w, `{"hasMore":false,"animes":[{"animeId":2002,"animeTitle":"手动搜索动画B","episodes":[{"episodeId":99999,"episodeTitle":"第1话"}]}]}`)
-		})
-		mux.HandleFunc("/api/v2/comment/25484", func(w http.ResponseWriter, r *http.Request) {
-			w.Header().Set("Content-Type", "application/xml")
-			fmt.Fprint(w, `<?xml version="1.0"?><i><d p="0.5,1,16777215,user1">自动识别弹幕</d></i>`)
-		})
-		mux.HandleFunc("/api/v2/comment/99999", func(w http.ResponseWriter, r *http.Request) {
-			w.Header().Set("Content-Type", "application/xml")
-			fmt.Fprint(w, `<?xml version="1.0"?><i><d p="0.5,1,16777215,user2">手动搜索弹幕</d></i>`)
-		})
-		official := httptest.NewServer(mux)
-		t.Cleanup(official.Close)
-		overrideDanmakuOfficialBase(t, official.URL)
+	// 官方服务同时提供 match 和 search：
+	// match 会返回 episodeId=25484（动画A）
+	// search 会根据关键词返回 episodeId=99999（动画B）
+	mux := http.NewServeMux()
+	var matchCalled bool
+	mux.HandleFunc("/api/v2/match", func(w http.ResponseWriter, r *http.Request) {
+		matchCalled = true
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprint(w, `{"success":true,"isMatched":true,"matches":[{"episodeId":25484,"animeId":1001,"animeTitle":"自动识别动画A","episodeTitle":"第1话"}]}`)
+	})
+	mux.HandleFunc("/api/v2/search/episodes", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprint(w, `{"hasMore":false,"animes":[{"animeId":2002,"animeTitle":"手动搜索动画B","episodes":[{"episodeId":99999,"episodeTitle":"第1话"}]}]}`)
+	})
+	mux.HandleFunc("/api/v2/comment/25484", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/xml")
+		fmt.Fprint(w, `<?xml version="1.0"?><i><d p="0.5,1,16777215,user1">自动识别弹幕</d></i>`)
+	})
+	mux.HandleFunc("/api/v2/comment/99999", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/xml")
+		fmt.Fprint(w, `<?xml version="1.0"?><i><d p="0.5,1,16777215,user2">手动搜索弹幕</d></i>`)
+	})
+	official := httptest.NewServer(mux)
+	t.Cleanup(official.Close)
+	overrideDanmakuOfficialBase(t, official.URL)

-		svc := newDanmakuTestService(t)
-		ctx := context.Background()
-		seedDanmakuVideoMedia(t, svc, "mManual", "自动识别动画A", videoPath, 32000, 1)
+	svc := newDanmakuTestService(t)
+	ctx := context.Background()
+	seedDanmakuVideoMedia(t, svc, "mManual", "自动识别动画A", videoPath, 32000, 1)

-		// 1) 默认自动识别：命中 Hash 识别
-		resAuto, err := svc.Fetch(ctx, "mManual", "", "")
-		require.NoError(t, err)
-		require.True(t, matchCalled)
-		require.Equal(t, "hash", resAuto.MatchMode)
-		require.Equal(t, int64(25484), resAuto.EpisodeID)
-		require.Contains(t, resAuto.Raw, "自动识别弹幕")
+	// 1) 默认自动识别：命中 Hash 识别
+	resAuto, err := svc.Fetch(ctx, "mManual", "", "")
+	require.NoError(t, err)
+	require.True(t, matchCalled)
+	require.Equal(t, "hash", resAuto.MatchMode)
+	require.Equal(t, int64(25484), resAuto.EpisodeID)
+	require.Contains(t, resAuto.Raw, "自动识别弹幕")

-		// 2) 用户传入手动搜索关键词：跳过 Hash 识别，命中搜索结果动画B
-		resManual, err := svc.Fetch(ctx, "mManual", "手动搜索动画B", "")
-		require.NoError(t, err)
-		require.Equal(t, "search", resManual.MatchMode)
-		require.Equal(t, int64(99999), resManual.EpisodeID)
-		require.Equal(t, "手动搜索动画B", resManual.AnimeTitle)
-		require.Contains(t, resManual.Raw, "手动搜索弹幕")
-	}
+	// 2) 用户传入手动搜索关键词：跳过 Hash 识别，命中搜索结果动画B
+	resManual, err := svc.Fetch(ctx, "mManual", "手动搜索动画B", "")
+	require.NoError(t, err)
+	require.Equal(t, "search", resManual.MatchMode)
+	require.Equal(t, int64(99999), resManual.EpisodeID)
+	require.Equal(t, "手动搜索动画B", resManual.AnimeTitle)
+	require.Contains(t, resManual.Raw, "手动搜索弹幕")
+}
+
+// Emby 远程挂载条目：通过伪装 ID 解析出流直链，通过 Range 提取 16MB 前缀计算 hash 并匹配弹幕。
+func TestDanmakuFetchEmbyRemoteHashViaDirectLink(t *testing.T) {
+	content := bytes.Repeat([]byte("emby-remote-video-bytes-9876543210"), 300)
+	sum := md5.Sum(content)
+	wantHash := hex.EncodeToString(sum[:])
+
+	var gotRange string
+	var rangeHits int
+	rangeSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		rangeHits++
+		gotRange = r.Header.Get("Range")
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(content)
+	}))
+	t.Cleanup(rangeSrv.Close)
+
+	var seen string
+	official := danmakuOfficialServer(t,
+		`{"success":true,"isMatched":true,"matches":[{"episodeId":25484,"animeId":2001,"animeTitle":"芙莉莲","episodeTitle":"第1话"}]}`,
+		`<?xml version="1.0"?><i><d p="1.2,1,16777215,user1">Emby远程弹幕命中</d></i>`,
+		&seen)
+	overrideDanmakuOfficialBase(t, official.URL)
+
+	remoteMediaID := EncodeEmbyRemoteID("mount-123", "remote-item-456")
+	svc := newDanmakuTestService(t)
+	svc.SetRemoteMediaResolver(func(_ context.Context, encodedID string) (*model.Media, string, error) {
+		require.Equal(t, remoteMediaID, encodedID)
+		return &model.Media{
+			Base:         model.Base{ID: remoteMediaID},
+			Title:        "葬送的芙莉莲",
+			EpisodeTitle: "第1话",
+			EpisodeNum:   1,
+			Path:         "/mnt/emby/anime/Frieren/S01E01.mkv",
+			SizeBytes:    int64(len(content)),
+			DurationSec:  1400,
+		}, rangeSrv.URL, nil
+	})
+
+	ctx := context.Background()
+	res, err := svc.Fetch(ctx, remoteMediaID, "", "")
+	require.NoError(t, err)
+	require.True(t, res.Enabled)
+	require.Equal(t, "hash", res.MatchMode)
+	require.Equal(t, int64(25484), res.EpisodeID)
+	require.Equal(t, "芙莉莲", res.AnimeTitle)
+	require.Contains(t, res.Raw, "Emby远程弹幕命中")
+	require.Contains(t, gotRange, "bytes=0-")
+	require.Contains(t, seen, `"fileHash":"`+wantHash+`"`)
+	require.Contains(t, seen, `"fileName":"`+url.QueryEscape("S01E01")+`"`)
+	require.Equal(t, 1, rangeHits)
+
+	// 第二次拉取验证 hashCache 命中，不重复请求 rangeSrv
+	res2, err := svc.Fetch(ctx, remoteMediaID, "", "")
+	require.NoError(t, err)
+	require.Equal(t, "hash", res2.MatchMode)
+	require.Equal(t, 1, rangeHits)
+}
+
+// Emby 远程直链拉取失败时（如网络异常），能平滑降级走番剧原名/标题关键词搜索。
+func TestDanmakuFetchEmbyRemoteStreamFailedFallsBackToSearch(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/api/v2/search/episodes", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		// 文件名搜索 ep01 时无结果，模拟文件名未匹配
+		if r.URL.Query().Get("anime") == "ep01" {
+			fmt.Fprint(w, `{"hasMore":false,"animes":[]}`)
+			return
+		}
+		// 降级到番剧名搜索命中
+		fmt.Fprint(w, `{"hasMore":false,"animes":[{"animeId":3001,"animeTitle":"降级搜索番剧","episodes":[{"episodeId":7799,"episodeTitle":"第1话"}]}]}`)
+	})
+	mux.HandleFunc("/api/v2/comment/7799", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/xml")
+		fmt.Fprint(w, `<?xml version="1.0"?><i><d p="0.8,1,16777215,user1">降级搜索弹幕</d></i>`)
+	})
+	official := httptest.NewServer(mux)
+	t.Cleanup(official.Close)
+	overrideDanmakuOfficialBase(t, official.URL)
+
+	remoteMediaID := EncodeEmbyRemoteID("mount-123", "remote-item-789")
+	svc := newDanmakuTestService(t)
+	// 返回一个不存在的流服务地址模拟 Range 拉取失败
+	svc.SetRemoteMediaResolver(func(_ context.Context, encodedID string) (*model.Media, string, error) {
+		return &model.Media{
+			Base:        model.Base{ID: remoteMediaID},
+			Title:       "降级搜索番剧",
+			EpisodeNum:  1,
+			Path:        "/mnt/emby/anime/fallback/ep01.mkv",
+			DurationSec: 1200,
+		}, "http://127.0.0.1:1/invalid-stream", nil
+	})
+
+	ctx := context.Background()
+	res, err := svc.Fetch(ctx, remoteMediaID, "", "")
+	require.NoError(t, err)
+	require.True(t, res.Enabled)
+	require.Equal(t, "search", res.MatchMode)
+	require.Equal(t, int64(7799), res.EpisodeID)
+	require.Equal(t, "降级搜索番剧", res.AnimeTitle)
+	require.Contains(t, res.Raw, "降级搜索弹幕")
+}
@@ -94,6 +94,10 @@ type DanmakuEpisode struct {
 	EpisodeTitle string `json:"episodeTitle"`
 }

+// DanmakuRemoteMediaResolver resolves an Emby remote pseudo-ID (e.g. embyremote~mount~id)
+// into a memory model.Media and a direct stream URL.
+type DanmakuRemoteMediaResolver func(ctx context.Context, encodedID string) (*model.Media, string, error)
+
 // DanmakuService fetches danmaku for a media item through the dandanplay
 // protocol: match by 16MB-prefix hash, then search for an episode id by the
 // video's name, then fetch the comment library XML. The React player parses
@@ -108,6 +112,10 @@ type DanmakuService struct {
 	// StrmService.ResolvePlay; nil means strm sources are skipped.
 	strmResolve func(ctx context.Context, provider string, q url.Values) (*StrmPlayResult, error)

+	// remoteResolve resolves an Emby remote pseudo-ID into *model.Media and
+	// direct stream URL for range hashing.
+	remoteResolve DanmakuRemoteMediaResolver
+
 	hashCacheMu sync.Mutex
 	hashCache   map[string]string // stamp → 16MB-prefix MD5
 }
@@ -136,6 +144,14 @@ func (s *DanmakuService) SetStrmResolver(resolve func(ctx context.Context, provi
 	}
 }

+// SetRemoteMediaResolver wires the resolver used to fetch metadata and direct
+// stream URLs for Emby remote mounted media.
+func (s *DanmakuService) SetRemoteMediaResolver(resolve DanmakuRemoteMediaResolver) {
+	if s != nil {
+		s.remoteResolve = resolve
+	}
+}
+
 // Config reads danmaku settings from the runtime settings table.
 func (s *DanmakuService) Config(ctx context.Context) DanmakuRenderConfig {
 	cfg := DanmakuRenderConfig{
@@ -190,90 +206,94 @@ func (s *DanmakuService) Fetch(ctx context.Context, mediaID, keyword, episodeID
 	configured := strings.TrimRight(strings.TrimSpace(res.Source), "/")
 	official := danmakuOfficialBase

-		// 手动指定弹幕库：跳过识别，直接拉取该库（自定义源失败回退官方）。
-		if target := strings.TrimSpace(episodeID); target != "" {
-			raw, st, err := s.fetchCommentWithFallback(ctx, configured, official, target)
-			if err != nil {
-				s.log.Warn("danmaku comment fetch failed", zap.String("media_id", mediaID), zap.String("episode_id", target), zap.Error(err))
-				return res, err
-			}
-			res.Raw, res.SourceType = raw, st
-			if id, parseErr := strconv.ParseInt(target, 10, 64); parseErr == nil {
-				res.EpisodeID = id
-			}
-			res.MatchMode = "manual"
-			return res, nil
-		}
-
-		term, media, err := s.searchTerms(ctx, mediaID)
+	// 手动指定弹幕库：跳过识别，直接拉取该库（自定义源失败回退官方）。
+	if target := strings.TrimSpace(episodeID); target != "" {
+		raw, st, err := s.fetchCommentWithFallback(ctx, configured, official, target)
 		if err != nil {
+			s.log.Warn("danmaku comment fetch failed", zap.String("media_id", mediaID), zap.String("episode_id", target), zap.Error(err))
 			return res, err
 		}
-		manualKeyword := strings.TrimSpace(keyword) != ""
-		if kw := strings.TrimSpace(keyword); kw != "" {
-			term.name = kw
+		res.Raw, res.SourceType = raw, st
+		if id, parseErr := strconv.ParseInt(target, 10, 64); parseErr == nil {
+			res.EpisodeID = id
 		}
-		if strings.TrimSpace(term.name) == "" {
+		res.MatchMode = "manual"
+		return res, nil
+	}
+
+	term, media, err := s.searchTerms(ctx, mediaID)
+	if err != nil {
+		return res, err
+	}
+	manualKeyword := strings.TrimSpace(keyword) != ""
+	if kw := strings.TrimSpace(keyword); kw != "" {
+		term.name = kw
+	}
+	if strings.TrimSpace(term.name) == "" {
+		return res, nil
+	}
+
+	target := ""
+
+	// 1) hash 识别：始终走官方 /api/v2/match（keyword 手动覆盖时跳过，直接走第 3 层）。
+	if target == "" && !manualKeyword && media != nil && (media.Path != "" || IsEmbyRemoteID(media.ID)) {
+		if hash, ok := s.mediaHash(ctx, media); ok {
+			fileSize := media.SizeBytes
+			if media.Path != "" && strings.EqualFold(filepath.Ext(media.Path), ".strm") {
+				fileSize = 0 // strm 行的 SizeBytes 是文本大小，不是视频大小
+			}
+			matchName := danmakuMatchFileName(media.Path)
+			if matchName == "" {
+				matchName = term.name
+			}
+			matches, err := s.matchOfficial(ctx, matchName, hash, fileSize, media.DurationSec)
+			if err != nil {
+				s.log.Warn("danmaku hash match failed", zap.String("media_id", mediaID), zap.Error(err))
+			} else if len(matches) > 0 {
+				target = fmt.Sprintf("%d", matches[0].EpisodeID)
+				res.AnimeTitle = matches[0].AnimeTitle
+				res.EpisodeTitle = matches[0].EpisodeTitle
+				res.EpisodeID = matches[0].EpisodeID
+				res.MatchMode = "hash"
+			}
+		}
+	}
+
+	// 2) 按播放的文件名 + 集数搜索（keyword 手动覆盖时跳过，直接走第 3 层）。
+	if target == "" && !manualKeyword && media != nil && media.Path != "" {
+		if fileName := danmakuMatchFileName(media.Path); fileName != "" && fileName != term.name {
+			if candidates, err := s.searchCandidatesWithFallback(ctx, configured, official, fileName, term.episode); err == nil &&
+				len(candidates) == 1 && len(candidates[0].Episodes) > 0 {
+				target = fmt.Sprintf("%d", candidates[0].Episodes[0].EpisodeID)
+				res.AnimeTitle = candidates[0].AnimeTitle
+				res.EpisodeTitle = candidates[0].Episodes[0].EpisodeTitle
+				res.EpisodeID = candidates[0].Episodes[0].EpisodeID
+				res.MatchMode = "filename"
+			}
+		}
+	}
+
+	// 3) 现有自动识别：标题层级（original_name → title → 文件名）+ 集数，
+	//    多结果返回候选列表交给播放器（歧义处理）。
+	if target == "" {
+		candidates, err := s.searchCandidatesWithFallback(ctx, configured, official, term.name, term.episode)
+		if err != nil {
+			s.log.Warn("danmaku search failed", zap.String("media_id", mediaID), zap.String("name", term.name), zap.String("episode", term.episode), zap.Error(err))
+			return res, err
+		}
+		if len(candidates) != 1 {
+			res.Candidates = candidates
 			return res, nil
 		}
-
-		target := ""
-
-		// 1) hash 识别：始终走官方 /api/v2/match（keyword 手动覆盖时跳过，直接走第 3 层）。
-		if target == "" && !manualKeyword && media != nil && media.Path != "" {
-			if hash, ok := s.mediaHash(ctx, media); ok {
-				fileSize := media.SizeBytes
-				if strings.EqualFold(filepath.Ext(media.Path), ".strm") {
-					fileSize = 0 // strm 行的 SizeBytes 是文本大小，不是视频大小
-				}
-				matches, err := s.matchOfficial(ctx, danmakuMatchFileName(media.Path), hash, fileSize, media.DurationSec)
-				if err != nil {
-					s.log.Warn("danmaku hash match failed", zap.String("media_id", mediaID), zap.Error(err))
-				} else if len(matches) > 0 {
-					target = fmt.Sprintf("%d", matches[0].EpisodeID)
-					res.AnimeTitle = matches[0].AnimeTitle
-					res.EpisodeTitle = matches[0].EpisodeTitle
-					res.EpisodeID = matches[0].EpisodeID
-					res.MatchMode = "hash"
-				}
-			}
-		}
-
-		// 2) 按播放的文件名 + 集数搜索（keyword 手动覆盖时跳过，直接走第 3 层）。
-		if target == "" && !manualKeyword && media != nil && media.Path != "" {
-			if fileName := danmakuMatchFileName(media.Path); fileName != "" && fileName != term.name {
-				if candidates, err := s.searchCandidatesWithFallback(ctx, configured, official, fileName, term.episode); err == nil &&
-					len(candidates) == 1 && len(candidates[0].Episodes) > 0 {
-					target = fmt.Sprintf("%d", candidates[0].Episodes[0].EpisodeID)
-					res.AnimeTitle = candidates[0].AnimeTitle
-					res.EpisodeTitle = candidates[0].Episodes[0].EpisodeTitle
-					res.EpisodeID = candidates[0].Episodes[0].EpisodeID
-					res.MatchMode = "filename"
-				}
-			}
-		}
-
-		// 3) 现有自动识别：标题层级（original_name → title → 文件名）+ 集数，
-		//    多结果返回候选列表交给播放器（歧义处理）。
-		if target == "" {
-			candidates, err := s.searchCandidatesWithFallback(ctx, configured, official, term.name, term.episode)
-			if err != nil {
-				s.log.Warn("danmaku search failed", zap.String("media_id", mediaID), zap.String("name", term.name), zap.String("episode", term.episode), zap.Error(err))
-				return res, err
-			}
-			if len(candidates) != 1 {
-				res.Candidates = candidates
-				return res, nil
-			}
-			if len(candidates[0].Episodes) == 0 {
-				return res, errors.New("no danmaku library found for this video")
-			}
-			target = fmt.Sprintf("%d", candidates[0].Episodes[0].EpisodeID)
-			res.AnimeTitle = candidates[0].AnimeTitle
-			res.EpisodeTitle = candidates[0].Episodes[0].EpisodeTitle
-			res.EpisodeID = candidates[0].Episodes[0].EpisodeID
-			res.MatchMode = "search"
+		if len(candidates[0].Episodes) == 0 {
+			return res, errors.New("no danmaku library found for this video")
 		}
+		target = fmt.Sprintf("%d", candidates[0].Episodes[0].EpisodeID)
+		res.AnimeTitle = candidates[0].AnimeTitle
+		res.EpisodeTitle = candidates[0].Episodes[0].EpisodeTitle
+		res.EpisodeID = candidates[0].Episodes[0].EpisodeID
+		res.MatchMode = "search"
+	}

 	raw, st, err := s.fetchCommentWithFallback(ctx, configured, official, target)
 	if err != nil {
@@ -311,6 +331,29 @@ type danmakuSearchTerms struct {
 // (movies / unknown) is left empty so the search does not filter by episode.
 func (s *DanmakuService) searchTerms(ctx context.Context, mediaID string) (danmakuSearchTerms, *model.Media, error) {
 	var term danmakuSearchTerms
+	if IsEmbyRemoteID(mediaID) {
+		if s == nil || s.remoteResolve == nil {
+			return term, nil, errors.New("remote emby resolver unavailable")
+		}
+		m, _, err := s.remoteResolve(ctx, mediaID)
+		if err != nil || m == nil {
+			if err != nil {
+				return term, nil, err
+			}
+			return term, nil, errors.New("media not found")
+		}
+		if name := strings.TrimSpace(m.OriginalName); name != "" {
+			term.name = name
+		} else if name := strings.TrimSpace(m.Title); name != "" {
+			term.name = name
+		} else {
+			term.name = danmakuMatchFileName(m.Path)
+		}
+		if m.EpisodeNum > 0 {
+			term.episode = strconv.Itoa(m.EpisodeNum)
+		}
+		return term, m, nil
+	}
 	if s == nil || s.repo == nil || s.repo.Media == nil {
 		return term, nil, errors.New("media repository unavailable")
 	}
@@ -484,7 +527,14 @@ func (s *DanmakuService) hashCachePut(stamp, hash string) {
 // ("xxx.mkv.strm") — so a second strip removes a real video extension only
 // (filepath.Ext would misread names like "xxx.第01话" as having an extension).
 func danmakuMatchFileName(path string) string {
-	base := filepath.Base(path)
+	if path == "" {
+		return ""
+	}
+	clean := strings.ReplaceAll(path, "\\", "/")
+	if idx := strings.LastIndex(clean, "/"); idx >= 0 {
+		clean = clean[idx+1:]
+	}
+	base := filepath.Base(clean)
 	if ext := filepath.Ext(base); ext != "" {
 		base = strings.TrimSuffix(base, ext)
 	}
@@ -493,14 +543,20 @@ func danmakuMatchFileName(path string) string {
 			base = strings.TrimSuffix(base, filepath.Ext(base))
 		}
 	}
-	return base
+	return strings.TrimSpace(base)
 }

 // mediaHash returns the dandanplay match hash (MD5 of the first 16MB of the
-// video). Local videos are hashed straight from disk; .strm indirections are
-// resolved (local path / direct link) and only the 16MB prefix is downloaded.
+// video). Local videos are hashed straight from disk; .strm indirections and
+// remote Emby streams are range-fetched and only the 16MB prefix is downloaded.
 func (s *DanmakuService) mediaHash(ctx context.Context, media *model.Media) (string, bool) {
-	if media == nil || media.Path == "" {
+	if media == nil {
+		return "", false
+	}
+	if IsEmbyRemoteID(media.ID) {
+		return s.hashEmbyRemote(ctx, media)
+	}
+	if media.Path == "" {
 		return "", false
 	}
 	if strings.EqualFold(filepath.Ext(media.Path), ".strm") {
@@ -517,6 +573,43 @@ func (s *DanmakuService) mediaHash(ctx context.Context, media *model.Media) (str
 	return s.hashLocalFile(media.Path)
 }

+// hashEmbyRemote computes the 16MB-prefix MD5 of a remote Emby stream via HTTP Range.
+func (s *DanmakuService) hashEmbyRemote(ctx context.Context, media *model.Media) (string, bool) {
+	if media == nil || media.ID == "" {
+		return "", false
+	}
+	if h, ok := s.hashCacheGet("e|" + media.ID); ok {
+		return h, true
+	}
+	if s.remoteResolve == nil {
+		return "", false
+	}
+	_, streamURL, err := s.remoteResolve(ctx, media.ID)
+	if err != nil || strings.TrimSpace(streamURL) == "" {
+		if err != nil {
+			s.log.Warn("danmaku emby stream url resolve failed, hash layer skipped",
+				zap.String("media_id", media.ID), zap.Error(err))
+		}
+		return "", false
+	}
+	body, err := s.openRangeBody(ctx, streamURL, nil)
+	if err != nil || body == nil {
+		if err != nil {
+			s.log.Warn("danmaku emby range fetch failed, hash layer skipped",
+				zap.String("media_id", media.ID), zap.Error(err))
+		}
+		return "", false
+	}
+	defer body.Close()
+	h := md5.New()
+	if _, err := io.Copy(h, io.LimitReader(body, danmakuHashPrefixBytes)); err != nil {
+		return "", false
+	}
+	hash := hex.EncodeToString(h.Sum(nil))
+	s.hashCachePut("e|"+media.ID, hash)
+	return hash, true
+}
+
 // hashLocalFile computes the MD5 of the first 16MB of a local video, cached
 // by path+size+mtime so repeated danmaku loads skip the disk read.
 func (s *DanmakuService) hashLocalFile(path string) (string, bool) {
@@ -694,7 +787,7 @@ func (s *DanmakuService) matchOfficial(ctx context.Context, fileName, fileHash s
 		return nil, fmt.Errorf("danmaku match returned HTTP %d", resp.StatusCode)
 	}
 	var out struct {
-		Success bool          `json:"success"`
+		Success bool           `json:"success"`
 		Matches []danmakuMatch `json:"matches"`
 	}
 	if err := json.Unmarshal(raw, &out); err != nil {
@@ -11,6 +11,15 @@ import (

 // ImageURL returns artwork for a media/series/season item id.
 func (e *EmbyService) ImageURL(ctx context.Context, id, imageType string) (string, error) {
+	// 远程 Emby 条目：直接返回远程图片绝对地址，由 ImageProxy 拉取透传。
+	if e.remote != nil && IsEmbyRemoteID(id) {
+		mountID, remoteID, _ := DecodeEmbyRemoteID(id)
+		mount, acct, _ := e.remote.ResolveMount(ctx, mountID)
+		if mount == nil || acct == nil {
+			return "", nil
+		}
+		return e.remote.RemoteImageURL(ctx, acct, remoteID, imageType)
+	}
 	pick := func(primary, backdrop string) string {
 		switch strings.ToLower(imageType) {
 		case "backdrop", "art":
@@ -48,6 +48,7 @@ type EmbyService struct {
 	repo     *repository.Container
 	cache    *RuntimeCacheService
 	subtitle *SubtitleService
+	remote   *EmbyRemoteService // 远程 Emby 联邦聚合（可为 nil：未启用）

 	virtualMu      sync.RWMutex
 	virtualSeries  map[string]embySeriesCacheEntry
@@ -66,6 +67,14 @@ func NewEmbyService(cfg *config.Config, log *zap.Logger, repo *repository.Contai
 	return &EmbyService{cfg: cfg, log: log, repo: repo}
 }

+// SetEmbyRemote 注入远程 Emby 联邦聚合服务（nil 表示未启用）。
+func (e *EmbyService) SetEmbyRemote(remote *EmbyRemoteService) *EmbyService {
+	if e != nil {
+		e.remote = remote
+	}
+	return e
+}
+
 func (e *EmbyService) SetRuntimeCache(cache *RuntimeCacheService) *EmbyService {
 	if e != nil {
 		e.cache = cache
@@ -123,7 +132,8 @@ type embyVisibilityCacheEntry struct {

 // Items paginates media in Emby's hierarchy. Episodic libraries are exposed as
 // Series -> Season -> Episode so Infuse/Vidhub/SenPlayer stop treating every
-// episode as a separate movie card.
+// episode as a separate movie card. 带 embyremote~ 前缀的 ParentID / 搜索自动
+// 路由到远程 Emby（联邦聚合，远程数据不落库）。
 func (e *EmbyService) Items(ctx context.Context, p ItemsParams) (map[string]any, error) {
 	if p.Limit <= 0 || p.Limit > 500 {
 		p.Limit = 50
@@ -135,6 +145,33 @@ func (e *EmbyService) Items(ctx context.Context, p ItemsParams) (map[string]any,
 		return emptyItemsEnvelope(p.StartIndex), nil
 	}

+	if e.remote != nil {
+		// 远程目录浏览：ParentId 带远程前缀 → 完整转发给远程 Emby 承接分页。
+		if IsEmbyRemoteID(p.ParentID) {
+			mountID, _, _ := DecodeEmbyRemoteID(p.ParentID)
+			mount, acct, _ := e.remote.ResolveMount(ctx, mountID)
+			if mount == nil || acct == nil {
+				return emptyItemsEnvelope(p.StartIndex), nil
+			}
+			out, err := e.remote.RemoteItems(ctx, mount, acct, p)
+			if err != nil {
+				return nil, err
+			}
+			if err := e.mergeRemoteUserData(ctx, p.UserID, out); err != nil {
+				return nil, err
+			}
+			return out, nil
+		}
+		// 全局搜索：无 ParentId 且带搜索词 → 聚合本地 + 全部远程。
+		if p.ParentID == "" && p.SearchTerm != "" {
+			return e.aggregatedSearch(ctx, p)
+		}
+	}
+
+	if containsEmbyFilter(p.Filters, "IsResumable") {
+		return e.resumableItems(ctx, p)
+	}
+
 	if len(p.IDs) > 0 {
 		items := make([]map[string]any, 0, len(p.IDs))
 		for _, id := range p.IDs {
@@ -212,3 +249,88 @@ func (e *EmbyService) Items(ctx context.Context, p ItemsParams) (map[string]any,
 	}
 	return e.mediaItems(ctx, p)
 }
+
+// aggregatedSearch 把本地媒体库与全部启用的远程 Emby 的搜索结果合并为一个
+// 分页载荷。本地结果保持原有分页语义，远程各自取一页（Limit 同款）后按
+// SortBy 做稳定排序切片。
+func (e *EmbyService) aggregatedSearch(ctx context.Context, p ItemsParams) (map[string]any, error) {
+	local, err := e.mediaItems(ctx, p)
+	if err != nil {
+		return nil, err
+	}
+	type remoteResult struct {
+		items []any
+	}
+	mounts, aerr := e.remote.ListMounts(ctx)
+	results := make([]remoteResult, 0, len(mounts))
+	if aerr == nil {
+		for i := range mounts {
+			m := mounts[i]
+			if !m.Enabled {
+				continue
+			}
+			acct := e.remote.AccountByID(ctx, m.AccountID)
+			if acct == nil {
+				continue
+			}
+			// 按挂载逐个搜索：搜索结果归属明确（伪装 ID 正确），也天然只搜已
+			// 挂载的媒体库。
+			searchParams := p
+			searchParams.ParentID = "" // RemoteSearchMount 内部设 ParentId
+			remote, rerr := e.remote.RemoteSearchMount(ctx, &m, acct, p)
+			if rerr != nil {
+				if e.log != nil {
+					e.log.Warn("remote emby search failed",
+						zap.String("account", acct.Name), zap.Error(rerr))
+				}
+				continue
+			}
+			if err := e.mergeRemoteUserData(ctx, p.UserID, remote); err != nil {
+				return nil, err
+			}
+			if raw, ok := remote["Items"].([]any); ok {
+				results = append(results, remoteResult{items: raw})
+			} else if rawMap, ok := remote["Items"].([]map[string]any); ok {
+				converted := make([]any, 0, len(rawMap))
+				for _, m := range rawMap {
+					converted = append(converted, any(m))
+				}
+				results = append(results, remoteResult{items: converted})
+			}
+		}
+	}
+	items := make([]any, 0, len(localItemsAsAny(local))+len(results)*p.Limit)
+	items = append(items, localItemsAsAny(local)...)
+	for _, res := range results {
+		items = append(items, res.items...)
+	}
+	return sliceSearchItems(items, p), nil
+}
+
+func localItemsAsAny(envelope map[string]any) []any {
+	if envelope == nil {
+		return nil
+	}
+	if raw, ok := envelope["Items"].([]any); ok {
+		return raw
+	}
+	if raw, ok := envelope["Items"].([]map[string]any); ok {
+		converted := make([]any, 0, len(raw))
+		for _, m := range raw {
+			converted = append(converted, any(m))
+		}
+		return converted
+	}
+	return nil
+}
+
+// sliceSearchItems 对合并结果按请求排序做简单归类后分页。远程返回已按远程
+// 排序规则排好，这里保持稳定顺序，只做首/尾切片，避免过度重排造成分页跳动。
+func sliceSearchItems(items []any, p ItemsParams) map[string]any {
+	total := len(items)
+	if p.StartIndex >= total {
+		return map[string]any{"Items": []any{}, "TotalRecordCount": total, "StartIndex": p.StartIndex}
+	}
+	end := minInt(p.StartIndex+p.Limit, total)
+	return map[string]any{"Items": items[p.StartIndex:end], "TotalRecordCount": total, "StartIndex": p.StartIndex}
+}
@@ -11,6 +11,25 @@ import (

 // Item 单条目详情。
 func (e *EmbyService) Item(ctx context.Context, mediaID, userID string) (map[string]any, error) {
+	if e == nil {
+		return nil, nil
+	}
+	// 远程 Emby 条目：不查本地库，直接向远程转发（保持远程最新元数据）。
+	if e.remote != nil && IsEmbyRemoteID(mediaID) {
+		mountID, remoteID, _ := DecodeEmbyRemoteID(mediaID)
+		mount, acct, _ := e.remote.ResolveMount(ctx, mountID)
+		if mount == nil || acct == nil {
+			return nil, nil
+		}
+		out, err := e.remote.RemoteItem(ctx, mount, acct, remoteID)
+		if err != nil || out == nil {
+			return out, err
+		}
+		if err := e.mergeRemoteUserData(ctx, userID, out); err != nil {
+			return nil, err
+		}
+		return out, nil
+	}
 	if lib, err := e.repo.Library.FindByID(ctx, mediaID); err != nil {
 		return nil, err
 	} else if lib != nil {
@@ -71,11 +90,26 @@ func (e *EmbyService) Item(ctx context.Context, mediaID, userID string) (map[str
 	return e.itemPayload(ctx, m, fav, pos), nil
 }

-// LatestItems 最近添加，全库或指定库。
+// LatestItems 最近添加，全库或指定库。远程媒体库(parentID 带前缀)直接透传远程。
 func (e *EmbyService) LatestItems(ctx context.Context, userID, parentID string, limit int) ([]map[string]any, error) {
 	if limit <= 0 || limit > 100 {
 		limit = 20
 	}
+	if e.remote != nil && IsEmbyRemoteID(parentID) {
+		mountID, remoteParent, _ := DecodeEmbyRemoteID(parentID)
+		mount, acct, _ := e.remote.ResolveMount(ctx, mountID)
+		if mount == nil || acct == nil {
+			return nil, nil
+		}
+		out, err := e.remote.RemoteLatest(ctx, mount, acct, remoteParent, limit)
+		if err != nil {
+			return nil, err
+		}
+		if err := e.mergeRemoteUserData(ctx, userID, out); err != nil {
+			return nil, err
+		}
+		return out, nil
+	}
 	cacheKey := e.embyLatestCacheKey(userID, parentID, limit)
 	var cached embyLatestCacheValue
 	if e.cache != nil && e.cache.GetJSON(ctx, cacheKey, &cached) {
@@ -143,41 +177,88 @@ func (e *EmbyService) latestSeriesItemsForLibrary(ctx context.Context, userID, l

 // ResumeItems 列出有未完成播放进度的媒体。
 func (e *EmbyService) ResumeItems(ctx context.Context, userID string, limit int) (map[string]any, error) {
-	if limit <= 0 || limit > 100 {
-		limit = 20
+	return e.resumableItems(ctx, ItemsParams{UserID: userID, Limit: limit})
+}
+
+// resumableItems 返回未完成播放进度的媒体（包含本地媒体与挂载的远程媒体），支持分页。
+func (e *EmbyService) resumableItems(ctx context.Context, p ItemsParams) (map[string]any, error) {
+	if p.Limit <= 0 || p.Limit > 100 {
+		p.Limit = 50
 	}
+	if p.StartIndex < 0 {
+		p.StartIndex = 0
+	}
+	if strings.TrimSpace(p.UserID) == "" {
+		return map[string]any{"Items": []any{}, "TotalRecordCount": int64(0), "StartIndex": p.StartIndex}, nil
+	}
+
 	var hist []model.PlaybackHistory
 	if err := e.repo.DB.WithContext(ctx).
-		Where("user_id = ? AND completed = ? AND position_ms > 0", userID, false).
-		Order("watched_at desc").Limit(limit).Find(&hist).Error; err != nil {
+		Where("user_id = ? AND completed = ? AND position_ms > 0", p.UserID, false).
+		Order("watched_at desc").Find(&hist).Error; err != nil {
 		return nil, err
 	}
 	if len(hist) == 0 {
-		return map[string]any{"Items": []any{}, "TotalRecordCount": 0}, nil
+		return map[string]any{"Items": []any{}, "TotalRecordCount": int64(0), "StartIndex": p.StartIndex}, nil
 	}
-	ids := make([]string, 0, len(hist))
-	posByID := map[string]int64{}
+
+	localIDs := make([]string, 0, len(hist))
 	for _, h := range hist {
-		ids = append(ids, h.MediaID)
-		posByID[h.MediaID] = h.PositionMs
-	}
-	var medias []model.Media
-	q := e.repo.DB.WithContext(ctx).Where("id IN ?", ids)
-	q = e.applyUserMediaVisibility(ctx, q, userID)
-	if err := q.Find(&medias).Error; err != nil {
-		return nil, err
+		if !IsEmbyRemoteID(h.MediaID) {
+			localIDs = append(localIDs, h.MediaID)
+		}
 	}
 	byID := map[string]*model.Media{}
-	for i := range medias {
-		byID[medias[i].ID] = &medias[i]
+	if len(localIDs) > 0 {
+		var medias []model.Media
+		q := e.repo.DB.WithContext(ctx).Where("id IN ?", localIDs)
+		q = e.applyUserMediaVisibility(ctx, q, p.UserID)
+		if err := q.Find(&medias).Error; err != nil {
+			return nil, err
+		}
+		for i := range medias {
+			byID[medias[i].ID] = &medias[i]
+		}
 	}
+
 	items := make([]map[string]any, 0, len(hist))
 	for _, h := range hist {
 		if m, ok := byID[h.MediaID]; ok {
-			items = append(items, e.itemPayload(ctx, m, false, posByID[h.MediaID]))
+			if p.ParentID != "" && m.LibraryID != p.ParentID && m.SeriesID != p.ParentID {
+				continue
+			}
+			items = append(items, e.itemPayload(ctx, m, false, h.PositionMs))
+			continue
 		}
+		if e.remote == nil || !IsEmbyRemoteID(h.MediaID) {
+			continue
+		}
+		mountID, remoteID, _ := DecodeEmbyRemoteID(h.MediaID)
+		mount, acct, err := e.remote.ResolveMount(ctx, mountID)
+		if err != nil || mount == nil || acct == nil {
+			continue
+		}
+		item, err := e.remote.RemoteItem(ctx, mount, acct, remoteID)
+		if err != nil || item == nil {
+			continue
+		}
+		if p.ParentID != "" {
+			parentID, _ := item["ParentId"].(string)
+			seriesID, _ := item["SeriesId"].(string)
+			if parentID != p.ParentID && seriesID != p.ParentID && mountID != p.ParentID {
+				continue
+			}
+		}
+		item["UserData"] = mergedRemoteUserData(item["UserData"], &h)
+		items = append(items, item)
 	}
-	return map[string]any{"Items": items, "TotalRecordCount": len(items)}, nil
+
+	total := int64(len(items))
+	if p.StartIndex >= len(items) {
+		return map[string]any{"Items": []map[string]any{}, "TotalRecordCount": total, "StartIndex": p.StartIndex}, nil
+	}
+	end := minInt(p.StartIndex+p.Limit, len(items))
+	return map[string]any{"Items": items[p.StartIndex:end], "TotalRecordCount": total, "StartIndex": p.StartIndex}, nil
 }

 func (e *EmbyService) itemPayload(ctx context.Context, m *model.Media, fav bool, posMs int64) map[string]any {
@@ -199,7 +199,9 @@ func (e *EmbyService) appendSubtitleStreams(ctx context.Context, streams []map[s
 	if e == nil || e.subtitle == nil || m == nil {
 		return streams
 	}
-	tracks, err := e.subtitle.Discover(ctx, m.ID)
+	// Emby 字幕只列表外挂字幕文件：云盘/strm 媒体的容器内嵌字幕不做服务端
+	// 提取，客户端直连播放直链时自行解析。
+	tracks, err := e.subtitle.DiscoverExternalOnly(ctx, m.ID)
 	if err != nil || len(tracks) == 0 {
 		return streams
 	}
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"net/http"
 	"net/url"
 	"path/filepath"
 	"strconv"
@@ -14,7 +15,28 @@ import (
 )

 // PlaybackInfo returns a PlaybackInfoResponse usable by Emby clients.
+// 远程 Emby 条目直接转发远程 PlaybackInfo，并按账号 proxy_play 配置决定
+// 播放地址指向远程（直连）还是 MMTL 本地代理端点。
 func (e *EmbyService) PlaybackInfo(ctx context.Context, mediaID, userID string) (map[string]any, error) {
+	if e.remote != nil && IsEmbyRemoteID(mediaID) {
+		mountID, remoteID, _ := DecodeEmbyRemoteID(mediaID)
+		mount, acct, err := e.remote.ResolveMount(ctx, mountID)
+		if err != nil {
+			return nil, ErrEmbyRemoteNotFound
+		}
+		out, err := e.remote.RemotePlaybackInfo(ctx, mount, acct, remoteID, userID)
+		if err != nil {
+			return nil, err
+		}
+		if out == nil {
+			return nil, ErrEmbyRemoteNotFound
+		}
+		if err := e.mergeRemoteUserData(ctx, userID, out); err != nil {
+			return nil, err
+		}
+		out["PlaySessionId"] = fmt.Sprintf("remote-%s-%d", mountID, time.Now().Unix())
+		return out, nil
+	}
 	m, err := e.playableMedia(ctx, mediaID, userID)
 	if err != nil || m == nil {
 		return nil, err
@@ -25,6 +47,65 @@ func (e *EmbyService) PlaybackInfo(ctx context.Context, mediaID, userID string)
 	}, nil
 }

+// ErrEmbyRemoteNotFound 表示伪装 ID 对应的远程挂载账号不存在/已禁用。
+var ErrEmbyRemoteNotFound = fmt.Errorf("remote emby account not found")
+
+// RemoteAccountByID 供 handler 层解码伪装 ID 后获取远程账号。
+func (e *EmbyService) RemoteAccountByID(ctx context.Context, accountID string) *model.StrmAccount {
+	if e == nil || e.remote == nil {
+		return nil
+	}
+	return e.remote.AccountByID(ctx, accountID)
+}
+
+// ProxyRemoteVideoStream 反向代理远程 Emby 视频流（保留 Range）。
+func (e *EmbyService) ProxyRemoteVideoStream(ctx context.Context, w http.ResponseWriter, r *http.Request, mountID, remoteID string) error {
+	if e == nil || e.remote == nil {
+		return ErrEmbyRemoteNotFound
+	}
+	_, acct, err := e.remote.ResolveMount(ctx, mountID)
+	if err != nil {
+		return ErrEmbyRemoteNotFound
+	}
+	return e.remote.ProxyVideoStream(ctx, w, r, acct, remoteID)
+}
+
+// ProxyRemoteSubtitle 反向代理远程 Emby 字幕流。
+func (e *EmbyService) ProxyRemoteSubtitle(ctx context.Context, w http.ResponseWriter, r *http.Request, mountID, remoteID, index string) error {
+	if e == nil || e.remote == nil {
+		return ErrSubtitleNotFound
+	}
+	_, acct, err := e.remote.ResolveMount(ctx, mountID)
+	if err != nil {
+		return ErrSubtitleNotFound
+	}
+	return e.remote.ProxySubtitle(ctx, w, r, acct, remoteID, index)
+}
+
+// ProxyRemoteSetPlayed 把已看/未看状态透传到远程 Emby。
+func (e *EmbyService) ProxyRemoteSetPlayed(ctx context.Context, mountID, remoteID string, played bool) error {
+	if e == nil || e.remote == nil {
+		return ErrEmbyRemoteNotFound
+	}
+	_, acct, err := e.remote.ResolveMount(ctx, mountID)
+	if err != nil {
+		return ErrEmbyRemoteNotFound
+	}
+	return e.remote.ProxySetPlayed(ctx, acct, remoteID, played)
+}
+
+// ProxyRemoteSetFavorite 把收藏/取消收藏状态透传到远程 Emby。
+func (e *EmbyService) ProxyRemoteSetFavorite(ctx context.Context, mountID, remoteID string, favorite bool) error {
+	if e == nil || e.remote == nil {
+		return ErrEmbyRemoteNotFound
+	}
+	_, acct, err := e.remote.ResolveMount(ctx, mountID)
+	if err != nil {
+		return ErrEmbyRemoteNotFound
+	}
+	return e.remote.ProxySetFavorite(ctx, acct, remoteID, favorite)
+}
+
 // ServeSubtitleStream resolves the Emby /Videos/:id/Subtitles/:index/Stream
 // request to one of the media's sideloaded external subtitle tracks and writes
 // the original (unconverted) subtitle bytes to w — matching the source Codec
@@ -32,10 +113,18 @@ func (e *EmbyService) PlaybackInfo(ctx context.Context, mediaID, userID string)
 // so the DeliveryUrl advertised in MediaStreams lines up exactly with the
 // served track: subtitles start at 1 when no audio stream is present, otherwise
 // at 2 (after Video 0 + Audio 1).
+//
+// 只服务外挂字幕文件（DiscoverExternalOnly）：云盘/strm 媒体的容器内嵌字幕
+// 不做服务端提取，客户端直连播放直链时自行解析。
 func (e *EmbyService) ServeSubtitleStream(ctx context.Context, w io.Writer, mediaID, indexStr string, userID string) error {
 	if e == nil || e.subtitle == nil {
 		return ErrSubtitleUnavailable
 	}
+	if e.remote != nil && IsEmbyRemoteID(mediaID) {
+		// 远程字幕由反向代理透传（需要 http.ResponseWriter 能力），handler 层
+		// 已对远程 ID 走 ProxyRemoteSubtitle，这里不重复处理。
+		return ErrSubtitleNotFound
+	}
 	m, err := e.playableMedia(ctx, mediaID, userID)
 	if err != nil || m == nil {
 		return ErrSubtitleNotFound
@@ -44,7 +133,7 @@ func (e *EmbyService) ServeSubtitleStream(ctx context.Context, w io.Writer, medi
 	if err != nil || index < 1 {
 		return ErrSubtitleNotFound
 	}
-	tracks, err := e.subtitle.Discover(ctx, m.ID)
+	tracks, err := e.subtitle.DiscoverExternalOnly(ctx, m.ID)
 	if err != nil || len(tracks) == 0 {
 		return ErrSubtitleNotFound
 	}
@@ -74,7 +163,7 @@ func (e *EmbyService) SubtitleStreamCodec(ctx context.Context, mediaID, indexStr
 	if err != nil || index < 1 {
 		return ""
 	}
-	tracks, err := e.subtitle.Discover(ctx, m.ID)
+	tracks, err := e.subtitle.DiscoverExternalOnly(ctx, m.ID)
 	if err != nil || len(tracks) == 0 {
 		return ""
 	}
@@ -0,0 +1,921 @@
+// EmbyRemoteService 是「远程 Emby 联邦聚合」核心：把挂载的远程 Emby 服务器
+// 作为外部媒体源，通过 MMTL 的 Emby 兼容 API 透出。
+//
+// 设计要点：
+//   - 远程媒体的元数据完全不落库：每次请求实时向远程 Emby 拉取；
+//   - 条目 ID 用 embyremote~{accountID}~{remoteID} 伪装（见 emby_remote_ids.go），
+//     客户端拿伪装 ID 回来时按账号路由回远程；
+//   - 播放分流由账号级 proxy_play 配置决定：
+//     不代理（默认）= MediaSource 下发热门远程绝对 URL，播放字节完全不经过 MMTL；
+//     代理 = 下发 MMTL 本地 /Videos/{encoded} 端点，由 ProxyVideoStream 反向拉流。
+//
+// 配置复用 STRM 账号体系（StrmAccount.Provider = emby_remote），CRUD/加密/连通
+// 测试全部走既有 /admin/strm/accounts 接口，不需要新增数据表。
+package service
+
+import (
+	"context"
+	"crypto/sha1"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+	"github.com/ShukeBta/MMTL/internal/model"
+	"github.com/ShukeBta/MMTL/internal/repository"
+)
+
+// embyRemoteHTTPTimeout 远程 Emby 常规 API 请求超时（流式代理不在此列）。
+const embyRemoteHTTPTimeout = 15 * time.Second
+
+// embyRemoteUA 桌面浏览器 UA：远程 Emby 前方若有 Cloudflare/WAF 会拦截
+// Go-http-client 等非浏览器 UA（403 error code: 1010），必须伪装浏览器。
+const embyRemoteUA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+
+// embyRemoteTransport 统一给远程请求注入浏览器 UA。
+type embyRemoteTransport struct {
+	base http.RoundTripper
+}
+
+func (t *embyRemoteTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if strings.TrimSpace(req.Header.Get("User-Agent")) == "" {
+		req.Header.Set("User-Agent", embyRemoteUA)
+	}
+	return t.base.RoundTrip(req)
+}
+
+// EmbyRemoteConfig 是一个远程 Emby 账号的解密配置。
+type EmbyRemoteConfig struct {
+	BaseURL      string // http://host:8096（无需 /emby 后缀）
+	Username     string
+	Password     string
+	Token        string // api_key（手动填写或自动认证获得）
+	RemoteUserID string // 远程用户 Id（自动认证后回填）
+	ProxyPlay    bool   // true=播放流量经 MMTL 反向代理；false=客户端直连远程
+}
+
+// EmbyRemoteService 提供对远程 Emby 服务器的读写封装。
+type EmbyRemoteService struct {
+	cfg    *config.Config
+	log    *zap.Logger
+	repo   *repository.Container
+	crypto *CryptoService
+	http   *http.Client
+	cache  *RuntimeCacheService
+}
+
+// NewEmbyRemoteService 构造远程 Emby 聚合服务。
+func NewEmbyRemoteService(cfg *config.Config, log *zap.Logger, repo *repository.Container, crypto *CryptoService) *EmbyRemoteService {
+	return &EmbyRemoteService{
+		cfg:    cfg,
+		log:    log,
+		repo:   repo,
+		crypto: crypto,
+		http: &http.Client{
+			Timeout:   embyRemoteHTTPTimeout,
+			Transport: &embyRemoteTransport{base: http.DefaultTransport},
+		},
+	}
+}
+
+func (r *EmbyRemoteService) SetRuntimeCache(cache *RuntimeCacheService) *EmbyRemoteService {
+	if r != nil {
+		r.cache = cache
+	}
+	return r
+}
+
+func (r *EmbyRemoteService) remoteMediaCacheTTL() time.Duration {
+	seconds := 15
+	if r != nil && r.cfg != nil && r.cfg.Cache.MediaTTLSeconds > 0 {
+		seconds = r.cfg.Cache.MediaTTLSeconds
+	}
+	return time.Duration(seconds) * time.Second
+}
+
+func (r *EmbyRemoteService) remoteCacheKey(parts ...string) string {
+	sum := sha1.Sum([]byte(strings.Join(parts, "|")))
+	return "media:embyremote:" + hex.EncodeToString(sum[:])
+}
+
+func (r *EmbyRemoteService) invalidateRemoteMediaCache(ctx context.Context) {
+	if r != nil && r.cache != nil {
+		r.cache.DeletePrefix(ctx, "media:embyremote:")
+	}
+}
+
+// ListAccounts 返回全部启用的远程 Emby 挂载账号。
+func (r *EmbyRemoteService) ListAccounts(ctx context.Context) ([]model.StrmAccount, error) {
+	accounts, err := r.repo.StrmAccount.List(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]model.StrmAccount, 0, len(accounts))
+	for i := range accounts {
+		if accounts[i].Provider == model.StrmProviderEmbyRemote {
+			out = append(out, accounts[i])
+		}
+	}
+	return out, nil
+}
+
+// AccountByID 按 ID 查找远程 Emby 挂载账号（不存在或类型不符返回 nil）。
+func (r *EmbyRemoteService) AccountByID(ctx context.Context, id string) *model.StrmAccount {
+	if strings.TrimSpace(id) == "" {
+		return nil
+	}
+	acct, err := r.repo.StrmAccount.FindByID(ctx, id)
+	if err != nil || acct == nil {
+		return nil
+	}
+	if acct.Provider != model.StrmProviderEmbyRemote || !acct.Enabled {
+		return nil
+	}
+	return acct
+}
+
+// ─── 媒体库挂载管理 ─────────────────────────────────────────────────────────────
+
+// ListMounts 返回全部挂载。
+func (r *EmbyRemoteService) ListMounts(ctx context.Context) ([]model.EmbyMount, error) {
+	return r.repo.EmbyMount.List(ctx)
+}
+
+// ListMountsByAccount 返回指定账号的挂载。
+func (r *EmbyRemoteService) ListMountsByAccount(ctx context.Context, accountID string) ([]model.EmbyMount, error) {
+	return r.repo.EmbyMount.ListByAccountID(ctx, accountID)
+}
+
+// MountByID 按 ID 查挂载。
+func (r *EmbyRemoteService) MountByID(ctx context.Context, id string) (*model.EmbyMount, error) {
+	return r.repo.EmbyMount.FindByID(ctx, id)
+}
+
+// CreateMount 创建一个挂载（校验账号类型与远程 View 编号）。
+func (r *EmbyRemoteService) CreateMount(ctx context.Context, m *model.EmbyMount) (*model.EmbyMount, error) {
+	if strings.TrimSpace(m.AccountID) == "" || strings.TrimSpace(m.RemoteViewID) == "" {
+		return nil, errors.New("缺少账号或远程媒体库")
+	}
+	if r.AccountByID(ctx, m.AccountID) == nil {
+		return nil, errors.New("远程 Emby 账号不存在或已禁用")
+	}
+	if err := r.repo.EmbyMount.Create(ctx, m); err != nil {
+		return nil, err
+	}
+	r.invalidateRemoteMediaCache(ctx)
+	return m, nil
+}
+
+// CreateMounts 批量创建挂载（幂等：已存在的远程库自动跳过）。
+func (r *EmbyRemoteService) CreateMounts(ctx context.Context, mounts []*model.EmbyMount) (int, error) {
+	if len(mounts) == 0 {
+		return 0, nil
+	}
+	existing, err := r.repo.EmbyMount.ListByAccountID(ctx, mounts[0].AccountID)
+	if err != nil {
+		return 0, err
+	}
+	have := make(map[string]bool, len(existing))
+	for _, e := range existing {
+		have[e.RemoteViewID] = true
+	}
+	fresh := make([]*model.EmbyMount, 0, len(mounts))
+	for _, m := range mounts {
+		if m == nil || have[m.RemoteViewID] {
+			continue
+		}
+		fresh = append(fresh, m)
+	}
+	if len(fresh) == 0 {
+		return 0, nil
+	}
+	if err := r.repo.EmbyMount.CreateInBatches(ctx, fresh, 50); err != nil {
+		return 0, err
+	}
+	r.invalidateRemoteMediaCache(ctx)
+	return len(fresh), nil
+}
+
+// UpdateMount 更新挂载（名称 / 代理 / 启用）。
+func (r *EmbyRemoteService) UpdateMount(ctx context.Context, id string, m *model.EmbyMount) (*model.EmbyMount, error) {
+	existing, err := r.repo.EmbyMount.FindByID(ctx, id)
+	if err != nil || existing == nil {
+		return nil, errNotFoundOr(err, "挂载不存在")
+	}
+	existing.Name = strings.TrimSpace(m.Name)
+	existing.ProxyPlay = m.ProxyPlay
+	existing.Enabled = m.Enabled
+	if err := r.repo.EmbyMount.Update(ctx, existing); err != nil {
+		return nil, err
+	}
+	r.invalidateRemoteMediaCache(ctx)
+	return existing, nil
+}
+
+// DeleteMount 删除挂载。
+func (r *EmbyRemoteService) DeleteMount(ctx context.Context, id string) error {
+	err := r.repo.EmbyMount.Delete(ctx, id)
+	if err == nil {
+		r.invalidateRemoteMediaCache(ctx)
+	}
+	return err
+}
+
+// ReorderMounts 批量重排挂载媒体库顺序。
+func (r *EmbyRemoteService) ReorderMounts(ctx context.Context, ids []string) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	if err := r.repo.EmbyMount.SetSortOrder(ctx, ids); err != nil {
+		return err
+	}
+	r.invalidateRemoteMediaCache(ctx)
+	return nil
+}
+
+// FullMountAccount 把账号的全部远程媒体库（View）挂载进来（幂等，已存在跳过）。
+func (r *EmbyRemoteService) FullMountAccount(ctx context.Context, acct *model.StrmAccount, proxyPlayDefault bool) (int, error) {
+	views, err := r.RemoteViews(ctx, acct)
+	if err != nil {
+		return 0, err
+	}
+	mounts := make([]*model.EmbyMount, 0, len(views))
+	for _, v := range views {
+		viewID := remoteItemString(v, "Id")
+		if viewID == "" {
+			continue
+		}
+		mounts = append(mounts, &model.EmbyMount{
+			AccountID:      acct.ID,
+			RemoteViewID:   viewID,
+			RemoteViewName: remoteItemString(v, "Name"),
+			CollectionType: remoteItemString(v, "CollectionType"),
+			ProxyPlay:      proxyPlayDefault,
+			Enabled:        true,
+		})
+	}
+	return r.CreateMounts(ctx, mounts)
+}
+
+// ResolveMount 按伪装 ID 的第一段（挂载 ID）解析挂载与其所属账号。
+// 远程条目/媒体库的伪装 ID 格式：embyremote~{mountID}~{remoteID}。
+func (r *EmbyRemoteService) ResolveMount(ctx context.Context, mountID string) (*model.EmbyMount, *model.StrmAccount, error) {
+	mount, err := r.repo.EmbyMount.FindByID(ctx, mountID)
+	if err != nil || mount == nil || !mount.Enabled {
+		return nil, nil, errors.New("挂载不存在或已禁用")
+	}
+	acct := r.AccountByID(ctx, mount.AccountID)
+	if acct == nil {
+		return nil, nil, errors.New("远程 Emby 账号不存在或已禁用")
+	}
+	return mount, acct, nil
+}
+
+// AutoSeedMounts 兼容迁移：已有 emby_remote 账号但没有任何挂载时，自动把
+// 其全部媒体库挂载进来（代理沿用账号旧配置），保证旧部署升级后媒体库不消失。
+// 幂等：每个账号只在挂载数为 0 时执行一次。
+func (r *EmbyRemoteService) AutoSeedMounts(ctx context.Context) {
+	accounts, err := r.ListAccounts(ctx)
+	if err != nil || len(accounts) == 0 {
+		return
+	}
+	for i := range accounts {
+		acct := &accounts[i]
+		count, err := r.repo.EmbyMount.CountByAccountID(ctx, acct.ID)
+		if err != nil || count > 0 {
+			continue
+		}
+		cfg, cfgErr := r.configOf(acct)
+		if cfgErr != nil {
+			continue
+		}
+		n, seedErr := r.FullMountAccount(ctx, acct, cfg.ProxyPlay)
+		if seedErr != nil {
+			if r.log != nil {
+				r.log.Warn("auto-seed emby mounts failed",
+					zap.String("account", acct.Name), zap.Error(seedErr))
+			}
+		} else if n > 0 {
+			if r.log != nil {
+				r.log.Info("auto-seeded emby mounts",
+					zap.String("account", acct.Name), zap.Int("mounts", n))
+			}
+		}
+	}
+}
+
+// configOf 解密账号配置。
+func (r *EmbyRemoteService) configOf(acct *model.StrmAccount) (*EmbyRemoteConfig, error) {
+	raw := map[string]string{}
+	if acct != nil && strings.TrimSpace(acct.Config) != "" {
+		if err := json.Unmarshal([]byte(acct.Config), &raw); err != nil {
+			return nil, fmt.Errorf("decode emby account config: %w", err)
+		}
+	}
+	cfg := &EmbyRemoteConfig{
+		BaseURL:      strings.TrimRight(strings.TrimSpace(raw["url"]), "/"),
+		Username:     strings.TrimSpace(raw["username"]),
+		Password:     r.crypto.Decrypt(raw["password"]),
+		Token:        firstNonEmptyStr(r.crypto.Decrypt(raw["api_key"]), r.crypto.Decrypt(raw["token"])),
+		RemoteUserID: strings.TrimSpace(raw["remote_user_id"]),
+		ProxyPlay:    parseBoolSetting(raw["proxy_play"], false),
+	}
+	if cfg.BaseURL == "" {
+		return nil, errors.New("缺少 Emby 地址")
+	}
+	if !strings.HasPrefix(cfg.BaseURL, "http://") && !strings.HasPrefix(cfg.BaseURL, "https://") {
+		return nil, errors.New("Emby 地址必须以 http:// 或 https:// 开头")
+	}
+	return cfg, nil
+}
+
+func firstNonEmptyStr(values ...string) string {
+	for _, v := range values {
+		if strings.TrimSpace(v) != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+// embyBase 把地址规范为不带尾部斜杠的 /emby 根。
+func (r *EmbyRemoteService) embyBase(cfg *EmbyRemoteConfig) string {
+	base := strings.TrimRight(cfg.BaseURL, "/")
+	if !strings.HasSuffix(base, "/emby") {
+		base += "/emby"
+	}
+	return base
+}
+
+// ensureToken 返回可用的 api_key：已有则直接用；否则用用户名/密码认证并回写
+// 数据库（自动获得的 token 与 remote_user_id 会加密保存在账号配置里）。
+func (r *EmbyRemoteService) ensureToken(ctx context.Context, acct *model.StrmAccount, cfg *EmbyRemoteConfig) error {
+	if strings.TrimSpace(cfg.Token) != "" {
+		return nil
+	}
+	if strings.TrimSpace(cfg.Username) == "" || strings.TrimSpace(cfg.Password) == "" {
+		return errors.New("缺少 Emby 凭据：请填写 api_key 或 用户名/密码")
+	}
+	body, _ := json.Marshal(map[string]string{"Username": cfg.Username, "Pw": cfg.Password})
+	endpoint := r.embyBase(cfg) + "/Users/AuthenticateByName"
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(string(body)))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Emby-Authorization", `MediaBrowser Client="MMTL", Device="MMTL-Federated", DeviceId="mmtl-federated", Version="1.0"`)
+	resp, err := r.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("连接远程 Emby 失败: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		data, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return fmt.Errorf("远程 Emby 登录失败(%d): %s", resp.StatusCode, strings.TrimSpace(string(data)))
+	}
+	var login struct {
+		AccessToken string `json:"AccessToken"`
+		User        struct {
+			Id string `json:"Id"`
+		} `json:"User"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&login); err != nil {
+		return err
+	}
+	if strings.TrimSpace(login.AccessToken) == "" {
+		return errors.New("远程 Emby 未返回 AccessToken")
+	}
+	cfg.Token = login.AccessToken
+	if login.User.Id != "" {
+		cfg.RemoteUserID = login.User.Id
+	}
+	return r.persistToken(ctx, acct, cfg)
+}
+
+// persistToken 把认证得到的 token / user id 加密写回账号配置（下次请求免登录）。
+func (r *EmbyRemoteService) persistToken(ctx context.Context, acct *model.StrmAccount, cfg *EmbyRemoteConfig) error {
+	if acct == nil {
+		return nil
+	}
+	raw := map[string]string{}
+	if strings.TrimSpace(acct.Config) != "" {
+		_ = json.Unmarshal([]byte(acct.Config), &raw)
+	}
+	raw["api_key"] = r.crypto.Encrypt(cfg.Token)
+	raw["remote_user_id"] = cfg.RemoteUserID
+	if strings.TrimSpace(raw["username"]) == "" {
+		raw["username"] = cfg.Username
+	}
+	data, err := json.Marshal(raw)
+	if err != nil {
+		return err
+	}
+	acct.Config = string(data)
+	return r.repo.StrmAccount.Update(ctx, acct)
+}
+
+// doGet 向远程 Emby 发起带 api_key 的 GET，把响应 JSON 解码到 out。
+// 401 时自动重认证一次再重试（凭据过期场景）。
+func (r *EmbyRemoteService) doGet(ctx context.Context, acct *model.StrmAccount, cfg *EmbyRemoteConfig, path string, q url.Values, out any) error {
+	for attempt := 0; attempt < 2; attempt++ {
+		if err := r.ensureToken(ctx, acct, cfg); err != nil {
+			return err
+		}
+		endpoint := r.embyBase(cfg) + path
+		if q != nil {
+			endpoint += "?" + q.Encode()
+		} else {
+			endpoint += "?api_key=" + url.QueryEscape(cfg.Token)
+		}
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+		if err != nil {
+			return err
+		}
+		req.Header.Set("X-Emby-Token", cfg.Token)
+		resp, err := r.http.Do(req)
+		if err != nil {
+			return fmt.Errorf("请求远程 Emby 失败: %w", err)
+		}
+		data, readErr := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+		resp.Body.Close()
+		if readErr != nil {
+			return readErr
+		}
+		if resp.StatusCode == http.StatusUnauthorized && attempt == 0 {
+			// token 失效：清空后重认证重试一次。
+			cfg.Token = ""
+			if acct != nil {
+				raw := map[string]string{}
+				_ = json.Unmarshal([]byte(acct.Config), &raw)
+				delete(raw, "api_key")
+				enc, _ := json.Marshal(raw)
+				acct.Config = string(enc)
+				_ = r.repo.StrmAccount.Update(ctx, acct)
+			}
+			continue
+		}
+		if resp.StatusCode >= 300 {
+			return fmt.Errorf("远程 Emby 请求失败(%d): %s", resp.StatusCode, strings.TrimSpace(string(data)))
+		}
+		if out == nil {
+			return nil
+		}
+		return json.Unmarshal(data, out)
+	}
+	return errors.New("远程 Emby 认证重试失败")
+}
+
+// TestConnection 连通性测试：确保地址可达且凭据有效；成功时回写自动认证信息。
+func (r *EmbyRemoteService) TestConnection(ctx context.Context, acct *model.StrmAccount) error {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return err
+	}
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return err
+	}
+	var out json.RawMessage
+	return r.doGet(ctx, acct, cfg, "/System/Info", nil, &out)
+}
+
+// ProxyPlayOf 返回账号是否配置了播放代理（供账号列表/编辑回显）。
+func (r *EmbyRemoteService) ProxyPlayOf(acct *model.StrmAccount) (bool, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return false, err
+	}
+	return cfg.ProxyPlay, nil
+}
+
+// ─── 元数据 / 目录聚合 ─────────────────────────────────────────────────────────
+
+// RemoteViews 拉取远程媒体库（View）列表，返回远程原始 view map（未重写）。
+func (r *EmbyRemoteService) RemoteViews(ctx context.Context, acct *model.StrmAccount) ([]map[string]any, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	cacheKey := r.remoteCacheKey("views", acct.ID, r.remoteUserID(cfg))
+	var cached []map[string]any
+	if r.cache != nil && r.cache.GetJSON(ctx, cacheKey, &cached) {
+		return cached, nil
+	}
+	q := url.Values{"api_key": {cfg.Token}}
+	var body struct {
+		Items []map[string]any `json:"Items"`
+	}
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Views", q, &body); err != nil {
+		return nil, err
+	}
+	if body.Items == nil {
+		body.Items = []map[string]any{}
+	}
+	if r.cache != nil {
+		r.cache.SetJSON(ctx, cacheKey, body.Items, r.remoteMediaCacheTTL())
+	}
+	return body.Items, nil
+}
+
+func (r *EmbyRemoteService) remoteUserID(cfg *EmbyRemoteConfig) string {
+	if strings.TrimSpace(cfg.RemoteUserID) != "" {
+		return cfg.RemoteUserID
+	}
+	return "0" // 未认证出的兜底：部分 Emby 接受 0 代表管理员
+}
+
+// RemoteItems 向远程 Emby 转发 /Items 浏览/搜索请求，返回重写后的响应载荷。
+// p 的分页/排序/过滤参数原样转发，分页语义完全由远程承接。
+func (r *EmbyRemoteService) RemoteItems(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, p ItemsParams) (map[string]any, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	_, remoteParent, _ := DecodeEmbyRemoteID(p.ParentID)
+	q := url.Values{}
+	if remoteParent != "" {
+		q.Set("ParentId", remoteParent)
+	}
+	q.Set("UserId", r.remoteUserID(cfg))
+	q.Set("Limit", strconv.Itoa(p.Limit))
+	q.Set("StartIndex", strconv.Itoa(p.StartIndex))
+	if p.SearchTerm != "" {
+		q.Set("SearchTerm", p.SearchTerm)
+	}
+	if p.Recursive {
+		q.Set("Recursive", "true")
+	}
+	if p.SortBy != "" {
+		q.Set("SortBy", p.SortBy)
+	}
+	if p.SortOrder != "" {
+		q.Set("SortOrder", p.SortOrder)
+	}
+	if len(p.IncludeItemTypes) > 0 {
+		q.Set("IncludeItemTypes", strings.Join(p.IncludeItemTypes, ","))
+	}
+	if len(p.Filters) > 0 {
+		q.Set("Filters", strings.Join(p.Filters, ","))
+	}
+	path := "/Users/" + url.PathEscape(r.remoteUserID(cfg)) + "/Items"
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, path, q, &out); err != nil {
+		return nil, err
+	}
+	if out == nil {
+		out = map[string]any{"Items": []any{}, "TotalRecordCount": 0, "StartIndex": p.StartIndex}
+	}
+	RewriteEmbyRemoteIDs(out, mount.ID)
+	return out, nil
+}
+
+// RemoteSearchMount 对单个挂载的媒体库执行全局搜索（ParentId=挂载的远程库，
+// Recursive 返回库内全部命中），结果归属明确可直接伪装。
+func (r *EmbyRemoteService) RemoteSearchMount(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, p ItemsParams) (map[string]any, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	q := url.Values{}
+	q.Set("ParentId", mount.RemoteViewID)
+	q.Set("Recursive", "true")
+	q.Set("SearchTerm", p.SearchTerm)
+	q.Set("UserId", r.remoteUserID(cfg))
+	q.Set("Limit", strconv.Itoa(p.Limit))
+	q.Set("StartIndex", strconv.Itoa(p.StartIndex))
+	if p.SortBy != "" {
+		q.Set("SortBy", p.SortBy)
+	}
+	if p.SortOrder != "" {
+		q.Set("SortOrder", p.SortOrder)
+	}
+	if len(p.IncludeItemTypes) > 0 {
+		q.Set("IncludeItemTypes", strings.Join(p.IncludeItemTypes, ","))
+	}
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items", q, &out); err != nil {
+		return nil, err
+	}
+	if out == nil {
+		out = map[string]any{"Items": []any{}, "TotalRecordCount": 0}
+	}
+	RewriteEmbyRemoteIDs(out, mount.ID)
+	return out, nil
+}
+
+// RemoteItem 拉取远程单条目详情（含响应的重写）。
+func (r *EmbyRemoteService) RemoteItem(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteID string) (map[string]any, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	path := "/Users/" + url.PathEscape(r.remoteUserID(cfg)) + "/Items/" + url.PathEscape(remoteID)
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, path, nil, &out); err != nil {
+		return nil, err
+	}
+	RewriteEmbyRemoteIDs(out, mount.ID)
+	return out, nil
+}
+
+// RemoteLatest 拉取远程「最近添加」（用于 /Items/Latest 聚合）。
+func (r *EmbyRemoteService) RemoteLatest(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, parentID string, limit int) ([]map[string]any, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	q := url.Values{"Limit": {strconv.Itoa(limit)}}
+	if parentID != "" {
+		q.Set("ParentId", parentID)
+	}
+	path := "/Users/" + url.PathEscape(r.remoteUserID(cfg)) + "/Items/Latest"
+	var out []map[string]any
+	if err := r.doGet(ctx, acct, cfg, path, q, &out); err != nil {
+		return nil, err
+	}
+	RewriteEmbyRemoteIDs(out, mount.ID)
+	return out, nil
+}
+
+// RemotePlaybackInfo 拉取远程 PlaybackInfo，并按挂载的 proxy_play 配置重写
+// 播放 URL：不代理=指向远程绝对地址（播放字节不过 MMTL）；代理=指向 MMTL
+// 本地 /Videos/{encodedID} 端点（由 ProxyVideoStream 反代）。
+func (r *EmbyRemoteService) RemotePlaybackInfo(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteID, userID string) (map[string]any, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	q := url.Values{"UserId": {r.remoteUserID(cfg)}}
+	path := "/Items/" + url.PathEscape(remoteID) + "/PlaybackInfo"
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, path, q, &out); err != nil {
+		return nil, err
+	}
+	RewriteEmbyRemoteIDs(out, mount.ID)
+	r.rewritePlayURLs(out, mount, cfg, remoteID)
+	return out, nil
+}
+
+// rewritePlayURLs 按挂载代理模式重写载荷内 MediaSources 的播放地址。
+// 远程 Emby 的 PlaybackInfo 通常不返回 DirectStreamUrl（客户端靠它拼
+// /Videos/{Id}/stream），因此这里总是强制构造播放地址，完全由 MMTL 掌控
+// 直连（远程绝对 URL）或代理（本地 /Videos/{encoded}）的最终去向。
+func (r *EmbyRemoteService) rewritePlayURLs(value any, mount *model.EmbyMount, cfg *EmbyRemoteConfig, remoteID string) {
+	encoded := EncodeEmbyRemoteID(mount.ID, remoteID)
+	sources := collectMediaSources(value)
+	if sources == nil {
+		return
+	}
+	for _, src := range sources {
+		mediaSourceID, _ := src["Id"].(string)
+		var streamPath, subtitlePlayURL string
+		if mount.ProxyPlay {
+			streamPath = "/Videos/" + url.PathEscape(encoded) + "/stream"
+			subtitlePlayURL = "/Videos/" + url.PathEscape(encoded)
+		} else {
+			base := r.embyBase(cfg)
+			streamPath = base + "/Videos/" + url.PathEscape(remoteID) + "/stream?api_key=" + url.QueryEscape(cfg.Token) + "&Static=true"
+			if mediaSourceID != "" {
+				streamPath += "&MediaSourceId=" + url.QueryEscape(mediaSourceID)
+			}
+			subtitlePlayURL = base + "/Videos/" + url.PathEscape(remoteID)
+		}
+		// 直连/代理地址总是下发（PlaybackInfo 语义：客户端直接请求该 URL）。
+		src["DirectStreamUrl"] = streamPath
+		if _, exists := src["TranscodingUrl"]; exists {
+			src["TranscodingUrl"] = streamPath
+		}
+		rewriteSubtitleDeliveryURLs(src, subtitlePlayURL, cfg)
+	}
+}
+
+// collectMediaSources 从载荷中取出所有 MediaSources（顶层或嵌套 Items 内）。
+func collectMediaSources(value any) []map[string]any {
+	var out []map[string]any
+	switch typed := value.(type) {
+	case map[string]any:
+		if sources, ok := typed["MediaSources"].([]map[string]any); ok {
+			out = append(out, sources...)
+		} else if sources, ok := typed["MediaSources"].([]any); ok {
+			for _, s := range sources {
+				if m, isMap := s.(map[string]any); isMap {
+					out = append(out, m)
+				}
+			}
+		}
+		if items, ok := typed["Items"]; ok {
+			out = append(out, collectMediaSources(items)...)
+		}
+	case []any:
+		for _, item := range typed {
+			out = append(out, collectMediaSources(item)...)
+		}
+	case []map[string]any:
+		for _, item := range typed {
+			out = append(out, collectMediaSources(item)...)
+		}
+	}
+	return out
+}
+
+var embySubtitleDeliveryRE = regexp.MustCompile(`/Subtitles/(\d+)/Stream(\.[A-Za-z0-9]+)?`)
+
+// rewriteSubtitleDeliveryURLs 把 MediaSource 内字幕轨道的 DeliveryUrl 改写到
+// subtitlePlayURL 前缀（客户端请求本地代理端点 / 远程绝对地址）。
+func rewriteSubtitleDeliveryURLs(src map[string]any, playURL string, cfg *EmbyRemoteConfig) {
+	if src == nil {
+		return
+	}
+	streams, ok := src["MediaStreams"].([]any)
+	if !ok {
+		return
+	}
+	for _, s := range streams {
+		stream, isMap := s.(map[string]any)
+		if !isMap || stream["Type"] != "Subtitle" {
+			continue
+		}
+		raw, _ := stream["DeliveryUrl"].(string)
+		if raw == "" {
+			continue
+		}
+		idx := "1"
+		if m := embySubtitleDeliveryRE.FindStringSubmatch(raw); len(m) >= 2 {
+			idx = m[1]
+		}
+		ext := ""
+		if m := embySubtitleDeliveryRE.FindStringSubmatch(raw); len(m) >= 3 {
+			ext = m[2]
+		}
+		base := strings.TrimRight(playURL, "/")
+		delivery := base + "/Subtitles/" + idx + "/Stream" + ext
+		if !cfg.ProxyPlay && strings.TrimSpace(cfg.Token) != "" {
+			delivery += "?api_key=" + url.QueryEscape(cfg.Token)
+		}
+		stream["DeliveryUrl"] = delivery
+	}
+}
+
+// RemoteImageURL 构造远程图片绝对地址（由既有 ImageProxy 拉取透传）。
+func (r *EmbyRemoteService) RemoteImageURL(ctx context.Context, acct *model.StrmAccount, remoteID, imageType string) (string, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return "", err
+	}
+	return r.embyBase(cfg) + "/Items/" + url.PathEscape(remoteID) + "/Images/" + url.PathEscape(strings.ToLower(imageType)) +
+		"?api_key=" + url.QueryEscape(cfg.Token), nil
+}
+
+// ─── 播放代理 ─────────────────────────────────────────────────────────────────
+
+// ProxyVideoStream 反向代理远程 Emby 视频流（保留 Range 以支持拖动）。
+func (r *EmbyRemoteService) ProxyVideoStream(ctx context.Context, w http.ResponseWriter, req *http.Request, acct *model.StrmAccount, remoteID string) error {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return err
+	}
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return err
+	}
+	endpoint := r.embyBase(cfg) + "/Videos/" + url.PathEscape(remoteID) + "/stream"
+	q := url.Values{}
+	if mediaSourceID := strings.TrimSpace(req.URL.Query().Get("MediaSourceId")); mediaSourceID != "" {
+		q.Set("MediaSourceId", mediaSourceID)
+	}
+	// 代理是纯 byte 中继：始终要求远程原文件直连（Static=true 阻止远程触发
+	// ffmpeg 转码调度——远程转码可能未配置/故障，导致整个代理 500）。
+	q.Set("Static", "true")
+	q.Set("api_key", cfg.Token)
+	if encoded := q.Encode(); encoded != "" {
+		endpoint += "?" + encoded
+	}
+	upstream, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return err
+	}
+	upstream.Header.Set("X-Emby-Token", cfg.Token)
+	if rangeHeader := req.Header.Get("Range"); rangeHeader != "" {
+		upstream.Header.Set("Range", rangeHeader)
+	}
+	resp, err := r.http.Do(upstream)
+	if err != nil {
+		return fmt.Errorf("连接远程 Emby 视频流失败: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		data, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
+		return fmt.Errorf("远程 Emby 视频流失败(%d): %s", resp.StatusCode, strings.TrimSpace(string(data)))
+	}
+	for _, header := range []string{"Content-Type", "Content-Length", "Content-Range", "Accept-Ranges", "ETag", "Cache-Control"} {
+		if value := resp.Header.Get(header); value != "" {
+			w.Header().Set(header, value)
+		}
+	}
+	if resp.StatusCode == http.StatusPartialContent || resp.StatusCode == http.StatusOK {
+		w.WriteHeader(resp.StatusCode)
+	} else {
+		w.WriteHeader(resp.StatusCode)
+	}
+	if resp.StatusCode == http.StatusPartialContent || resp.StatusCode == http.StatusOK {
+		_, _ = io.Copy(w, resp.Body)
+	}
+	return nil
+}
+
+// ProxySubtitle 反向代理远程 Emby 字幕流。
+func (r *EmbyRemoteService) ProxySubtitle(ctx context.Context, w http.ResponseWriter, req *http.Request, acct *model.StrmAccount, remoteID, index string) error {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return err
+	}
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return err
+	}
+	endpoint := r.embyBase(cfg) + "/Videos/" + url.PathEscape(remoteID) + "/Subtitles/" + url.PathEscape(index) + "/Stream"
+	endpoint += "?api_key=" + url.QueryEscape(cfg.Token)
+	upstream, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return err
+	}
+	upstream.Header.Set("X-Emby-Token", cfg.Token)
+	resp, err := r.http.Do(upstream)
+	if err != nil {
+		return fmt.Errorf("连接远程 Emby 字幕流失败: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return fmt.Errorf("远程 Emby 字幕流失败(%d)", resp.StatusCode)
+	}
+	if value := resp.Header.Get("Content-Type"); value != "" {
+		w.Header().Set("Content-Type", value)
+	}
+	w.WriteHeader(resp.StatusCode)
+	if resp.StatusCode == http.StatusOK {
+		_, _ = io.Copy(w, resp.Body)
+	}
+	return nil
+}
+
+// ─── 播放状态透传 ──────────────────────────────────────────────────────────────
+
+// ProxySetPlayed 把「已看/未看」状态透传到远程 Emby（MMTL 本地不落库）。
+func (r *EmbyRemoteService) ProxySetPlayed(ctx context.Context, acct *model.StrmAccount, remoteID string, played bool) error {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return err
+	}
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return err
+	}
+	method := http.MethodPost
+	path := "/Users/" + url.PathEscape(r.remoteUserID(cfg)) + "/PlayedItems/" + url.PathEscape(remoteID)
+	if !played {
+		method = http.MethodDelete
+	}
+	return r.doMutate(ctx, acct, cfg, method, path)
+}
+
+// ProxySetFavorite 把「收藏/取消收藏」状态透传到远程 Emby。
+func (r *EmbyRemoteService) ProxySetFavorite(ctx context.Context, acct *model.StrmAccount, remoteID string, favorite bool) error {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return err
+	}
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return err
+	}
+	method := http.MethodPost
+	path := "/Users/" + url.PathEscape(r.remoteUserID(cfg)) + "/FavoriteItems/" + url.PathEscape(remoteID)
+	if !favorite {
+		method = http.MethodDelete
+	}
+	return r.doMutate(ctx, acct, cfg, method, path)
+}
+
+func (r *EmbyRemoteService) doMutate(ctx context.Context, acct *model.StrmAccount, cfg *EmbyRemoteConfig, method, path string) error {
+	endpoint := r.embyBase(cfg) + path + "?api_key=" + url.QueryEscape(cfg.Token)
+	req, err := http.NewRequestWithContext(ctx, method, endpoint, nil)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("X-Emby-Token", cfg.Token)
+	resp, err := r.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("请求远程 Emby 失败: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		data, _ := io.ReadAll(io.LimitReader(resp.Body, 256))
+		return fmt.Errorf("远程 Emby 状态同步失败(%d): %s", resp.StatusCode, strings.TrimSpace(string(data)))
+	}
+	return nil
+}
@@ -0,0 +1,109 @@
+// 远程 Emby 聚合的 ID 伪装。
+//
+// MMTL 作为 Emby 联邦网关把多个远程 Emby 服务器的媒体库透明聚合到自身的
+// Emby API 之下，远程条目完全不落库。为了把本地 ID 与多个远程服务器的 ID
+// 隔离开，远程条目在返回给客户端之前统一被改写为：
+//
+//	embyremote~{accountID}~{remoteID}
+//
+// 客户端后续对图片 / 详情 / 播放 / 播放状态 的请求都会携带这个伪装 ID，
+// 服务端据此解码出对应账号与原始 ID，直接向远程 Emby 转发。
+package service
+
+import (
+	"strings"
+)
+
+// EmbyRemoteIDPrefix 远程条目伪装 ID 的前缀（本地 UUID 与 Emby ID 不会出现 "~"）。
+const EmbyRemoteIDPrefix = "embyremote~"
+
+// IsEmbyRemoteID 报告 id 是否是伪装过的远程 Emby 条目 ID。
+func IsEmbyRemoteID(id string) bool {
+	return strings.HasPrefix(id, EmbyRemoteIDPrefix)
+}
+
+// EncodeEmbyRemoteID 把 (账号 ID, 远程条目 ID) 伪装为对外暴露的 ID。
+func EncodeEmbyRemoteID(accountID, remoteID string) string {
+	return EmbyRemoteIDPrefix + accountID + "~" + remoteID
+}
+
+// DecodeEmbyRemoteID 拆分伪装 ID 为 (账号 ID, 远程原始 ID)。不是伪装 ID 时返回
+// ok=false。远程 ID 本身允许包含 "~"（使用 SplitN 只切第一刀）。
+func DecodeEmbyRemoteID(id string) (accountID, remoteID string, ok bool) {
+	if !IsEmbyRemoteID(id) {
+		return "", "", false
+	}
+	rest := strings.TrimPrefix(id, EmbyRemoteIDPrefix)
+	parts := strings.SplitN(rest, "~", 2)
+	if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" || strings.TrimSpace(parts[1]) == "" {
+		return "", "", false
+	}
+	return parts[0], parts[1], true
+}
+
+// embyRemoteStringIDs 是条目 JSON 中需要伪装（编码）成远程 ID 的字符串字段。
+// 图片 / 详情 / 播放请求都会以这些字段的值作为 ID 回指 MMTL。
+var embyRemoteStringIDs = []string{
+	"Id",
+	"ParentId",
+	"SeriesId",
+	"SeasonId",
+	"PrimaryImageItemId",
+	"DisplayPreferencesId",
+}
+
+// RewriteEmbyRemoteIDs 在内存中把远程 Emby 返回的载荷里的所有条目 ID 替换为
+// 伪装 ID（防止与本地、多远程冲突），嵌套 Items / Map 数组递归处理。
+//
+// MediaSources 里的 Id / MediaSourceId 保持不变：客户端只把它们作为查询
+// 参数原样带回，转发时直接送回远程即可。播放 URL 的重写由服务层
+// （rewriteEmbyRemotePlayURLs）按直连/代理模式处理。
+func RewriteEmbyRemoteIDs(value any, accountID string) {
+	switch typed := value.(type) {
+	case map[string]any:
+		rewriteEmbyRemoteIDsMap(typed, accountID)
+	case []any:
+		for _, item := range typed {
+			RewriteEmbyRemoteIDs(item, accountID)
+		}
+	case []map[string]any:
+		for _, item := range typed {
+			rewriteEmbyRemoteIDsMap(item, accountID)
+		}
+	}
+}
+
+func rewriteEmbyRemoteIDsMap(m map[string]any, accountID string) {
+	if m == nil {
+		return
+	}
+	for _, key := range embyRemoteStringIDs {
+		if raw, ok := m[key].(string); ok && raw != "" {
+			m[key] = EncodeEmbyRemoteID(accountID, raw)
+		}
+	}
+	if tags, ok := m["ImageTags"].(map[string]any); ok {
+		for k, v := range tags {
+			if s, isStr := v.(string); isStr && s != "" {
+				tags[k] = EncodeEmbyRemoteID(accountID, s)
+			}
+		}
+	}
+	if tags, ok := m["ImageTags"].(map[string]string); ok {
+		for k, v := range tags {
+			if v != "" {
+				tags[k] = EncodeEmbyRemoteID(accountID, v)
+			}
+		}
+	}
+	if tags, ok := m["BackdropImageTags"].([]any); ok {
+		for i := range tags {
+			if s, isStr := tags[i].(string); isStr && s != "" {
+				tags[i] = EncodeEmbyRemoteID(accountID, s)
+			}
+		}
+	}
+	if items, ok := m["Items"]; ok {
+		RewriteEmbyRemoteIDs(items, accountID)
+	}
+}
@@ -0,0 +1,102 @@
+package service
+
+import (
+	"testing"
+)
+
+func TestEmbyRemoteIDEncodeDecode(t *testing.T) {
+	encoded := EncodeEmbyRemoteID("acct-1", "item-123")
+	want := "embyremote~acct-1~item-123"
+	if encoded != want {
+		t.Fatalf("encoded = %q, want %q", encoded, want)
+	}
+	if !IsEmbyRemoteID(encoded) {
+		t.Fatalf("IsEmbyRemoteID(%q) = false", encoded)
+	}
+	acctID, remoteID, ok := DecodeEmbyRemoteID(encoded)
+	if !ok || acctID != "acct-1" || remoteID != "item-123" {
+		t.Fatalf("decode = (%q, %q, %v)", acctID, remoteID, ok)
+	}
+}
+
+func TestDecodeEmbyRemoteIDAllowsTildeInRemoteID(t *testing.T) {
+	// 远程 ID 本身允许包含 "~"：只切第一刀。
+	encoded := EncodeEmbyRemoteID("acct-1", "a~b~c")
+	acctID, remoteID, ok := DecodeEmbyRemoteID(encoded)
+	if !ok || acctID != "acct-1" || remoteID != "a~b~c" {
+		t.Fatalf("decode = (%q, %q, %v)", acctID, remoteID, ok)
+	}
+}
+
+func TestDecodeEmbyRemoteIDRejectsLocalUUIDs(t *testing.T) {
+	if _, _, ok := DecodeEmbyRemoteID("550e8400-e29b-41d4-a716-446655440000"); ok {
+		t.Fatal("local UUID must not decode as remote id")
+	}
+	if _, _, ok := DecodeEmbyRemoteID("embyremote~only-acct"); ok {
+		t.Fatal("malformed remote id must not decode")
+	}
+	if _, _, ok := DecodeEmbyRemoteID("embyremote~~"); ok {
+		t.Fatal("empty parts must not decode")
+	}
+}
+
+func TestRewriteEmbyRemoteIDs(t *testing.T) {
+	payload := map[string]any{
+		"Id":                   "item-1",
+		"ParentId":             "folder-1",
+		"SeriesId":             "series-1",
+		"SeasonId":             "season-1",
+		"PrimaryImageItemId":   "item-1",
+		"DisplayPreferencesId": "folder-1",
+		"ImageTags": map[string]any{
+			"Primary": "item-1",
+		},
+		"BackdropImageTags": []any{"item-1-bd"},
+		"Items": []any{
+			map[string]any{"Id": "item-2", "ParentId": "folder-2"},
+		},
+		// MediaSource 的 Id 保持原样（客户端仅作为 MediaSourceId 查询参数）。
+		"MediaSources": []any{
+			map[string]any{
+				"Id":              "ms-9",
+				"DirectStreamUrl": "/Videos/item-1/stream",
+				"MediaStreams": []any{
+					map[string]any{"Type": "Subtitle", "DeliveryUrl": "/Videos/item-1/Subtitles/2/Stream.srt"},
+				},
+			},
+		},
+	}
+	RewriteEmbyRemoteIDs(payload, "acct-1")
+
+	if got := payload["Id"]; got != "embyremote~acct-1~item-1" {
+		t.Fatalf("Id = %v", got)
+	}
+	if got := payload["ParentId"]; got != "embyremote~acct-1~folder-1" {
+		t.Fatalf("ParentId = %v", got)
+	}
+	if got := payload["SeriesId"]; got != "embyremote~acct-1~series-1" {
+		t.Fatalf("SeriesId = %v", got)
+	}
+	if got := payload["SeasonId"]; got != "embyremote~acct-1~season-1" {
+		t.Fatalf("SeasonId = %v", got)
+	}
+	if got := payload["ImageTags"].(map[string]any)["Primary"]; got != "embyremote~acct-1~item-1" {
+		t.Fatalf("ImageTags.Primary = %v", got)
+	}
+	if got := payload["BackdropImageTags"].([]any)[0]; got != "embyremote~acct-1~item-1-bd" {
+		t.Fatalf("BackdropImageTags[0] = %v", got)
+	}
+	nested := payload["Items"].([]any)[0].(map[string]any)
+	if nested["Id"] != "embyremote~acct-1~item-2" {
+		t.Fatalf("nested Id = %v", nested["Id"])
+	}
+
+	// MediaSource.Id 与 URL 不被 ID 重写器触碰（URL 由代理模式函数改写）。
+	ms := payload["MediaSources"].([]any)[0].(map[string]any)
+	if ms["Id"] != "ms-9" {
+		t.Fatalf("MediaSource.Id must stay raw, got %v", ms["Id"])
+	}
+	if ms["DirectStreamUrl"] != "/Videos/item-1/stream" {
+		t.Fatalf("DirectStreamUrl must stay raw, got %v", ms["DirectStreamUrl"])
+	}
+}
@@ -0,0 +1,99 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+// rewriteSubtitleDeliveryURLs 只应改动字幕轨道的 DeliveryUrl，其余媒体流不动。
+func TestRewriteSubtitleDeliveryURLsProxyMode(t *testing.T) {
+	src := map[string]any{
+		"MediaStreams": []any{
+			map[string]any{"Type": "Video", "DeliveryUrl": "/Videos/x/stream"},
+			map[string]any{"Type": "Audio", "DeliveryUrl": "/Videos/x/stream"},
+			map[string]any{"Type": "Subtitle", "DeliveryUrl": "/Videos/item-1/ms-9/Subtitles/2/Stream.srt"},
+		},
+	}
+	rewriteSubtitleDeliveryURLs(src, "/Videos/embyremote~acct-1~item-1", &EmbyRemoteConfig{})
+	streams := src["MediaStreams"].([]any)
+	if got := streams[0].(map[string]any)["DeliveryUrl"]; got != "/Videos/x/stream" {
+		t.Fatalf("video DeliveryUrl must stay, got %v", got)
+	}
+	want := "/Videos/embyremote~acct-1~item-1/Subtitles/2/Stream.srt"
+	if got := streams[2].(map[string]any)["DeliveryUrl"]; got != want {
+		t.Fatalf("subtitle DeliveryUrl = %v, want %v", got, want)
+	}
+}
+
+func TestRewriteSubtitleDeliveryURLsDirectMode(t *testing.T) {
+	src := map[string]any{
+		"MediaStreams": []any{
+			map[string]any{"Type": "Subtitle", "DeliveryUrl": "/Videos/item-1/ms-9/Subtitles/1/Stream.ass"},
+		},
+	}
+	cfg := &EmbyRemoteConfig{Token: "tok123"}
+	rewriteSubtitleDeliveryURLs(src, "http://remote:8096/emby/Videos/item-1", cfg)
+	streams := src["MediaStreams"].([]any)
+	want := "http://remote:8096/emby/Videos/item-1/Subtitles/1/Stream.ass?api_key=tok123"
+	if got := streams[0].(map[string]any)["DeliveryUrl"]; got != want {
+		t.Fatalf("subtitle DeliveryUrl = %v, want %v", got, want)
+	}
+}
+
+func TestRewriteSubtitleDeliveryURLsFallsBackIndexOne(t *testing.T) {
+	src := map[string]any{
+		"MediaStreams": []any{
+			map[string]any{"Type": "Subtitle", "DeliveryUrl": "custom/url"},
+		},
+	}
+	rewriteSubtitleDeliveryURLs(src, "/Videos/embyremote~acct-1~item-1", &EmbyRemoteConfig{})
+	streams := src["MediaStreams"].([]any)
+	want := "/Videos/embyremote~acct-1~item-1/Subtitles/1/Stream"
+	if got := streams[0].(map[string]any)["DeliveryUrl"]; got != want {
+		t.Fatalf("subtitle DeliveryUrl = %v, want %v", got, want)
+	}
+}
+
+func TestMapRemoteItemToMediaExtractsCodecsAndContainer(t *testing.T) {
+	r := &EmbyRemoteService{}
+	item := map[string]any{
+		"Id":        "item-100",
+		"Name":      "Test Movie",
+		"Container": "mkv",
+		"MediaStreams": []any{
+			map[string]any{
+				"Type":   "Video",
+				"Codec":  "h264",
+				"Width":  1920,
+				"Height": 1080,
+			},
+			map[string]any{
+				"Type":  "Audio",
+				"Codec": "aac",
+			},
+		},
+		"MediaSources": []any{
+			map[string]any{
+				"Container": "mkv",
+				"Size":      int64(104857600),
+			},
+		},
+	}
+	media := r.MapRemoteItemToMedia(t.Context(), nil, &model.StrmAccount{Base: model.Base{ID: "acct-1"}}, &EmbyRemoteConfig{}, item)
+	if media.Container != "mkv" {
+		t.Fatalf("media.Container = %v, want mkv", media.Container)
+	}
+	if media.VideoCodec != "h264" {
+		t.Fatalf("media.VideoCodec = %v, want h264", media.VideoCodec)
+	}
+	if media.AudioCodec != "aac" {
+		t.Fatalf("media.AudioCodec = %v, want aac", media.AudioCodec)
+	}
+	if media.Width != 1920 || media.Height != 1080 {
+		t.Fatalf("resolution = %dx%d, want 1920x1080", media.Width, media.Height)
+	}
+	if media.SizeBytes != 104857600 {
+		t.Fatalf("size = %d, want 104857600", media.SizeBytes)
+	}
+}
@@ -0,0 +1,735 @@
+// 网页端远程 Emby 库映射。
+//
+// 网页端（React UI）的媒体库/媒体浏览走项目自有 REST API（/api/libraries、
+// /api/libraries/:id/media、/api/media/:id 等），数据结构为 model.Library /
+// model.Media / SeriesCard。远程 Emby 挂载的数据不落库，因此这里把远程
+// Emby 的 JSON item 映射为与本地完全一致的结构，让网页端无感知地浏览
+// 远程库；播放统一走 /api/stream/{伪装ID}（302 到远程 Emby 原地址）。
+package service
+
+import (
+	"context"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+// RemoteLibraryView 是一个网页端可见的远程媒体库（对应一个挂载的远程 View）。
+type RemoteLibraryView struct {
+	Library        model.Library
+	MountID        string
+	AccountID      string
+	RemoteID       string
+	CollectionType string
+	AccountName    string
+}
+
+// RemoteLibraries 把所有启用挂载的远程媒体库映射为网页媒体库列表
+// （只有显式挂载的库才出现在本项目媒体库中）。
+func (r *EmbyRemoteService) RemoteLibraries(ctx context.Context) ([]RemoteLibraryView, error) {
+	mounts, err := r.ListMounts(ctx)
+	if err != nil || len(mounts) == 0 {
+		return nil, err
+	}
+	type accountData struct {
+		acct       *model.StrmAccount
+		cfg        *EmbyRemoteConfig
+		viewByName map[string]map[string]any
+	}
+	acctData := map[string]*accountData{}
+	for i := range mounts {
+		m := &mounts[i]
+		if !m.Enabled {
+			continue
+		}
+		if _, ok := acctData[m.AccountID]; ok {
+			continue
+		}
+		acct := r.AccountByID(ctx, m.AccountID)
+		if acct == nil {
+			acctData[m.AccountID] = nil
+			continue
+		}
+		cfg, cfgErr := r.configOf(acct)
+		if cfgErr != nil {
+			acctData[m.AccountID] = nil
+			continue
+		}
+		views, viewErr := r.RemoteViews(ctx, acct)
+		if viewErr != nil {
+			if r.log != nil {
+				r.log.Warn("web remote emby views failed",
+					zap.String("account", acct.Name), zap.Error(viewErr))
+			}
+			acctData[m.AccountID] = nil
+			continue
+		}
+		viewByName := map[string]map[string]any{}
+		for _, v := range views {
+			viewByName[remoteItemString(v, "Id")] = v
+		}
+		acctData[m.AccountID] = &accountData{
+			acct:       acct,
+			cfg:        cfg,
+			viewByName: viewByName,
+		}
+	}
+
+	out := make([]RemoteLibraryView, 0, len(mounts))
+	for i := range mounts {
+		m := &mounts[i]
+		if !m.Enabled {
+			continue
+		}
+		data := acctData[m.AccountID]
+		if data == nil || data.viewByName == nil {
+			continue
+		}
+		v, ok := data.viewByName[m.RemoteViewID]
+		if !ok {
+			continue // 远程已删除该媒体库
+		}
+		lib := r.mapRemoteMountToLibrary(m, data.acct, data.cfg, v)
+		if lib == nil {
+			continue
+		}
+		out = append(out, RemoteLibraryView{
+			Library:        *lib,
+			MountID:        m.ID,
+			AccountID:      data.acct.ID,
+			RemoteID:       m.RemoteViewID,
+			CollectionType: m.CollectionType,
+			AccountName:    data.acct.Name,
+		})
+	}
+	return out, nil
+}
+
+// RemoteLibraryByID 按伪装 ID 查远程库视图（详情接口用）。
+func (r *EmbyRemoteService) RemoteLibraryByID(ctx context.Context, mountID, remoteViewID string) (*RemoteLibraryView, error) {
+	views, err := r.RemoteLibraries(ctx)
+	if err != nil {
+		return nil, err
+	}
+	for _, v := range views {
+		if v.MountID == mountID && v.RemoteID == remoteViewID {
+			cp := v
+			return &cp, nil
+		}
+	}
+	return nil, nil
+}
+
+// mapRemoteMountToLibrary 把挂载信息 + 远程 View item 映射为网页库结构。
+func (r *EmbyRemoteService) mapRemoteMountToLibrary(mount *model.EmbyMount, acct *model.StrmAccount, cfg *EmbyRemoteConfig, item map[string]any) *model.Library {
+	if mount == nil {
+		return nil
+	}
+	name := strings.TrimSpace(mount.Name)
+	if name == "" {
+		name = strings.TrimSpace(remoteItemString(item, "Name"))
+	}
+	if name == "" {
+		name = acct.Name
+	} else if !strings.Contains(name, acct.Name) {
+		name = acct.Name + " · " + name
+	}
+	libType := "movie"
+	switch mount.CollectionType {
+	case "tvshows":
+		libType = "tv"
+	case "music":
+		libType = "music"
+	}
+	lib := &model.Library{
+		Base:      model.Base{ID: EncodeEmbyRemoteID(mount.ID, mount.RemoteViewID)},
+		Name:      name,
+		Type:      libType,
+		Enabled:   true,
+		SortOrder: 1000 + mount.SortOrder, // 远程库排在本地库之后，且保持挂载库排序
+	}
+	// 远程媒体库封面只有真实存在图片标签才下发。
+	if remoteItemHasImageTag(item, "Primary") {
+		lib.CoverURL = r.remoteItemImageURL(cfg, mount.RemoteViewID, "Primary")
+	}
+	return lib
+}
+
+// MapRemoteItemToMedia 把远程 Emby item JSON 映射为本地 Media 结构。
+// poster/backdrop 只有在远程确实存在图片标签时才填 URL（避免对无图条目
+// 发出必失败的图片请求导致前端破图）；剧集回退到系列海报（SeriesPrimaryImage）。
+func (r *EmbyRemoteService) MapRemoteItemToMedia(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, cfg *EmbyRemoteConfig, item map[string]any) model.Media {
+	encodeScope := acct.ID
+	if mount != nil {
+		encodeScope = mount.ID
+	}
+	remoteID := remoteItemString(item, "Id")
+	// 条目可能已被 RewriteEmbyRemoteIDs 伪装（图片/嵌套 ID 需要原始远程 ID）。
+	if _, rid, ok := DecodeEmbyRemoteID(remoteID); ok {
+		remoteID = rid
+	}
+	seriesID := remoteItemString(item, "SeriesId")
+	if _, rid, ok := DecodeEmbyRemoteID(seriesID); ok {
+		seriesID = rid
+	}
+	rating := remoteItemFloat(item, "CommunityRating")
+	if rating == 0 {
+		rating = remoteItemFloat(item, "CriticRating")
+	}
+	media := model.Media{
+		Base:         model.Base{ID: EncodeEmbyRemoteID(encodeScope, remoteID)},
+		Title:        remoteItemString(item, "Name"),
+		OriginalName: remoteItemString(item, "OriginalTitle"),
+		Overview:     remoteItemString(item, "Overview"),
+		Year:         remoteItemInt(item, "ProductionYear"),
+		Rating:       float32(rating),
+		Path:         remoteItemString(item, "Path"),
+		Genres:       remoteItemGenres(item),
+		ScrapeStatus: "done",
+	}
+	if date, ok := parseEmbyRemoteDate(remoteItemString(item, "DateCreated")); ok {
+		media.CreatedAt = date
+		media.UpdatedAt = date
+	}
+	// 只有远程明确存在图片标签才下发图片 URL。
+	if remoteItemHasImageTag(item, "Primary") {
+		media.PosterURL = r.remoteItemImageURL(cfg, remoteID, "Primary")
+	}
+	if remoteItemHasImageTag(item, "Backdrop") || len(remoteBackdropTags(item)) > 0 {
+		media.BackdropURL = r.remoteItemImageURL(cfg, remoteID, "Backdrop")
+	}
+	if ticks := remoteItemInt64(item, "RunTimeTicks"); ticks > 0 {
+		media.DurationSec = int(ticks / 10_000_000)
+	}
+	if date, ok := parseEmbyRemoteDate(remoteItemString(item, "PremiereDate")); ok {
+		media.ReleaseDate = date.Format("2006-01-02")
+		if media.Year == 0 {
+			media.Year = date.Year()
+		}
+	} else if date, ok := embyPremiereDate(remoteItemString(item, "PremiereDate")); ok {
+		media.ReleaseDate = date.Format("2006-01-02")
+		if media.Year == 0 {
+			media.Year = date.Year()
+		}
+	}
+	if providerIDs, ok := item["ProviderIds"].(map[string]any); ok {
+		if v := anyString(providerIDs["Tmdb"]); v != "" {
+			media.TMDbID, _ = strconv.Atoi(v)
+		}
+		if v := anyString(providerIDs["Imdb"]); v != "" {
+			media.TheTVDBID = v
+		}
+		if v := anyString(providerIDs["Douban"]); v != "" {
+			media.DoubanID = v
+		}
+	}
+	media.Container = remoteItemString(item, "Container")
+	media.Width = remoteItemInt(item, "Width")
+	media.Height = remoteItemInt(item, "Height")
+
+	extractStreamInfo := func(streams []any) {
+		for _, s := range streams {
+			sm, ok := s.(map[string]any)
+			if !ok {
+				continue
+			}
+			typ := remoteItemString(sm, "Type")
+			if strings.EqualFold(typ, "Video") {
+				if media.VideoCodec == "" {
+					media.VideoCodec = remoteItemString(sm, "Codec")
+				}
+				if media.Width == 0 {
+					media.Width = remoteItemInt(sm, "Width")
+				}
+				if media.Height == 0 {
+					media.Height = remoteItemInt(sm, "Height")
+				}
+			} else if strings.EqualFold(typ, "Audio") {
+				if media.AudioCodec == "" {
+					media.AudioCodec = remoteItemString(sm, "Codec")
+				}
+			}
+		}
+	}
+
+	if streams, ok := item["MediaStreams"].([]any); ok {
+		extractStreamInfo(streams)
+	} else if streams, ok := item["MediaStreams"].([]map[string]any); ok {
+		anyStreams := make([]any, len(streams))
+		for i, v := range streams {
+			anyStreams[i] = v
+		}
+		extractStreamInfo(anyStreams)
+	}
+
+	if sources, ok := item["MediaSources"].([]any); ok && len(sources) > 0 {
+		if sourceMap, ok := sources[0].(map[string]any); ok {
+			if media.Container == "" {
+				media.Container = remoteItemString(sourceMap, "Container")
+			}
+			if media.SizeBytes == 0 {
+				media.SizeBytes = remoteItemInt64(sourceMap, "Size")
+			}
+			if streams, ok := sourceMap["MediaStreams"].([]any); ok && (media.VideoCodec == "" || media.AudioCodec == "") {
+				extractStreamInfo(streams)
+			}
+		}
+	}
+
+	switch remoteItemString(item, "Type") {
+	case "Episode":
+		media.SeasonNum = remoteItemInt(item, "ParentIndexNumber")
+		media.EpisodeNum = remoteItemInt(item, "IndexNumber")
+		media.EpisodeTitle = remoteItemString(item, "Name")
+		if seriesName := remoteItemString(item, "SeriesName"); seriesName != "" {
+			media.Title = seriesName
+		}
+		// 单集通常无独立海报：若远程返回 SeriesPrimaryImageTag（需要
+		// Fields=SeriesPrimaryImage）且系列有图，则回退到系列海报。
+		if media.PosterURL == "" && seriesID != "" &&
+			strings.TrimSpace(remoteItemString(item, "SeriesPrimaryImageTag")) != "" {
+			media.PosterURL = r.remoteItemImageURL(cfg, seriesID, "Primary")
+		}
+	default: // Movie / Series / Season / Folder
+		media.SeasonNum = 0
+		media.EpisodeNum = 0
+	}
+	return media
+}
+
+// RemoteLibraryMedia 拉远程库直属条目（电影库=Movie，剧集库=Series），映射分页。
+func (r *EmbyRemoteService) RemoteLibraryMedia(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteViewID string, itemTypes string, offset, limit int) ([]model.Media, int64, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, 0, err
+	}
+	if itemTypes == "" {
+		itemTypes = "Movie,Series" // 未知类型时两者都取（前端自行按 episode-like 分组）
+	}
+	cacheKey := r.remoteCacheKey("library-media", acct.ID, mount.ID, remoteViewID, itemTypes, strconv.Itoa(offset), strconv.Itoa(limit))
+	var cached struct {
+		Items            []model.Media `json:"items"`
+		TotalRecordCount int64         `json:"total_record_count"`
+	}
+	if r.cache != nil && r.cache.GetJSON(ctx, cacheKey, &cached) {
+		return cached.Items, cached.TotalRecordCount, nil
+	}
+	q := url.Values{}
+	q.Set("ParentId", remoteViewID)
+	q.Set("IncludeItemTypes", itemTypes)
+	q.Set("Recursive", "false")
+	q.Set("StartIndex", strconv.Itoa(offset))
+	q.Set("Limit", strconv.Itoa(limit))
+	q.Set("Fields", "Overview,Genres,ProviderIds,Path,SeriesPrimaryImage,MediaStreams,MediaSources,DateCreated,PremiereDate,ProductionYear,CommunityRating,CriticRating")
+	var body struct {
+		Items            []map[string]any `json:"Items"`
+		TotalRecordCount int64            `json:"TotalRecordCount"`
+	}
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items", q, &body); err != nil {
+		return nil, 0, err
+	}
+	items := make([]model.Media, 0, len(body.Items))
+	for _, it := range body.Items {
+		RewriteEmbyRemoteIDs(it, mount.ID) // 嵌套/关联 ID 一并伪装
+		items = append(items, r.MapRemoteItemToMedia(ctx, mount, acct, cfg, it))
+	}
+	if r.cache != nil {
+		r.cache.SetJSON(ctx, cacheKey, struct {
+			Items            []model.Media `json:"items"`
+			TotalRecordCount int64         `json:"total_record_count"`
+		}{Items: items, TotalRecordCount: body.TotalRecordCount}, r.remoteMediaCacheTTL())
+	}
+	return items, body.TotalRecordCount, nil
+}
+
+// RemoteMediaDetail 拉远程单条目映射为 Media（网页详情页）。
+func (r *EmbyRemoteService) RemoteMediaDetail(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteID string) (*model.Media, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	path := "/Users/" + url.PathEscape(r.remoteUserID(cfg)) + "/Items/" + url.PathEscape(remoteID)
+	path += "?Fields=Overview,Genres,ProviderIds,People,Studios,Path,MediaStreams,MediaSources,DateCreated,PremiereDate,ProductionYear,CommunityRating,CriticRating"
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, path, nil, &out); err != nil {
+		return nil, err
+	}
+	RewriteEmbyRemoteIDs(out, mount.ID)
+	m := r.MapRemoteItemToMedia(ctx, mount, acct, cfg, out)
+	return &m, nil
+}
+
+// RemoteEpisodes 拉远程条目下的集列表（Series/Season/Folder→子集；Episode→同系列；
+// Movie→自身单条），按季/集排序，与本地 ListMediaEpisodes 行为一致。
+func (r *EmbyRemoteService) RemoteEpisodes(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteID string) ([]model.Media, error) {
+	detail, err := r.RemoteMediaDetail(ctx, mount, acct, remoteID)
+	if err != nil {
+		return nil, err
+	}
+	// 用远程详情载荷精判类型（Episode→同系列；Series/Season/Folder→子集；Movie→单条）。
+	itemType := r.remoteItemType(ctx, acct, remoteID)
+	if itemType == "" {
+		itemType = remoteItemTypeOf(detail)
+	}
+	var parentID string
+	switch itemType {
+	case "Episode":
+		parentID = r.remoteItemSeriesID(ctx, acct, remoteID)
+		if parentID == "" {
+			parentID = remoteID
+		}
+	case "Season", "Folder", "Series":
+		parentID = remoteID
+	default: // Movie
+		return []model.Media{*detail}, nil
+	}
+	rows, _, err := r.remoteEpisodesOf(ctx, mount, acct, parentID)
+	if err != nil {
+		return nil, err
+	}
+	sort.SliceStable(rows, func(i, j int) bool {
+		if rows[i].SeasonNum != rows[j].SeasonNum {
+			return rows[i].SeasonNum < rows[j].SeasonNum
+		}
+		if rows[i].EpisodeNum != rows[j].EpisodeNum {
+			return rows[i].EpisodeNum < rows[j].EpisodeNum
+		}
+		return rows[i].Title < rows[j].Title
+	})
+	return rows, nil
+}
+
+func (r *EmbyRemoteService) remoteEpisodesOf(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, parentID string) ([]model.Media, int64, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, 0, err
+	}
+	q := url.Values{}
+	q.Set("ParentId", parentID)
+	q.Set("IncludeItemTypes", "Episode")
+	q.Set("Recursive", "true")
+	q.Set("StartIndex", "0")
+	q.Set("Limit", "500")
+	q.Set("Fields", "Overview,Genres,ProviderIds,Path,SeriesPrimaryImage,MediaStreams,MediaSources,DateCreated,PremiereDate,ProductionYear,CommunityRating,CriticRating")
+	var body struct {
+		Items            []map[string]any `json:"Items"`
+		TotalRecordCount int64            `json:"TotalRecordCount"`
+	}
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items", q, &body); err != nil {
+		return nil, 0, err
+	}
+	items := make([]model.Media, 0, len(body.Items))
+	for _, it := range body.Items {
+		RewriteEmbyRemoteIDs(it, mount.ID)
+		m := r.MapRemoteItemToMedia(ctx, mount, acct, cfg, it)
+		items = append(items, m)
+	}
+	return items, body.TotalRecordCount, nil
+}
+
+// RemoteSeriesCards 远程剧集库的系列卡片（ChildCount 作为集数）。
+func (r *EmbyRemoteService) RemoteSeriesCards(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteViewID string) ([]SeriesCard, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	cacheKey := r.remoteCacheKey("series-cards", acct.ID, mount.ID, remoteViewID)
+	var cached []SeriesCard
+	if r.cache != nil && r.cache.GetJSON(ctx, cacheKey, &cached) {
+		return cached, nil
+	}
+	q := url.Values{}
+	q.Set("ParentId", remoteViewID)
+	q.Set("IncludeItemTypes", "Series")
+	q.Set("Recursive", "false")
+	q.Set("StartIndex", "0")
+	q.Set("Limit", "1000")
+	q.Set("Fields", "Overview,Genres,ProviderIds,Path,RecursiveItemCount,SeriesPrimaryImage,DateCreated,PremiereDate,ProductionYear,CommunityRating,CriticRating")
+	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 nil, err
+	}
+	cards := make([]SeriesCard, 0, len(body.Items))
+	for _, it := range body.Items {
+		RewriteEmbyRemoteIDs(it, mount.ID)
+		m := r.MapRemoteItemToMedia(ctx, mount, acct, cfg, it)
+		// 集数优先用递归条目数（ChildCount 只算直属 Season 文件夹数）。
+		count := remoteItemInt(it, "RecursiveItemCount")
+		if count == 0 {
+			count = remoteItemInt(it, "ChildCount")
+		}
+		if count == 0 {
+			count = 1
+		}
+		cards = append(cards, SeriesCard{Key: m.ID, Rep: m, LinkMedia: m, Count: count})
+	}
+	if r.cache != nil {
+		r.cache.SetJSON(ctx, cacheKey, cards, r.remoteMediaCacheTTL())
+	}
+	return cards, nil
+}
+
+// RemoteLatestCards 远程库最新条目（首页预览卡片），映射 SeriesCard。
+func (r *EmbyRemoteService) RemoteLatestCards(ctx context.Context, mount *model.EmbyMount, acct *model.StrmAccount, remoteViewID string, limit int) ([]SeriesCard, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return nil, err
+	}
+	cacheKey := r.remoteCacheKey("latest-cards", acct.ID, mount.ID, remoteViewID, strconv.Itoa(limit))
+	var cached []SeriesCard
+	if r.cache != nil && r.cache.GetJSON(ctx, cacheKey, &cached) {
+		return cached, nil
+	}
+	items, err := r.RemoteLatest(ctx, mount, acct, remoteViewID, limit)
+	if err != nil {
+		return nil, err
+	}
+	cards := make([]SeriesCard, 0, len(items))
+	for _, it := range items {
+		m := r.MapRemoteItemToMedia(ctx, mount, acct, cfg, it)
+		cards = append(cards, SeriesCard{Key: m.ID, Rep: m, LinkMedia: m, Count: 0})
+	}
+	if r.cache != nil {
+		r.cache.SetJSON(ctx, cacheKey, cards, r.remoteMediaCacheTTL())
+	}
+	return cards, nil
+}
+
+// WebStreamURL 远程条目的网页播放地址（302 直连远程 Emby 流端点）。
+func (r *EmbyRemoteService) WebStreamURL(ctx context.Context, acct *model.StrmAccount, remoteID string) (string, error) {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return "", err
+	}
+	if err := r.ensureToken(ctx, acct, cfg); err != nil {
+		return "", err
+	}
+	return r.embyBase(cfg) + "/Videos/" + url.PathEscape(remoteID) +
+		"/stream?api_key=" + url.QueryEscape(cfg.Token) + "&Static=true", nil
+}
+
+// remoteItemType 轻量查询远程条目 Type（避免依赖映射载荷）。
+func (r *EmbyRemoteService) remoteItemType(ctx context.Context, acct *model.StrmAccount, remoteID string) string {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return ""
+	}
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items/"+url.PathEscape(remoteID), nil, &out); err != nil {
+		return ""
+	}
+	return remoteItemString(out, "Type")
+}
+
+// remoteItemSeriesID 轻量查询 Episode 的 SeriesId。
+func (r *EmbyRemoteService) remoteItemSeriesID(ctx context.Context, acct *model.StrmAccount, remoteID string) string {
+	cfg, err := r.configOf(acct)
+	if err != nil {
+		return ""
+	}
+	var out map[string]any
+	if err := r.doGet(ctx, acct, cfg, "/Users/"+url.PathEscape(r.remoteUserID(cfg))+"/Items/"+url.PathEscape(remoteID), nil, &out); err != nil {
+		return ""
+	}
+	return remoteItemString(out, "SeriesId")
+}
+
+// ─── 远程 item JSON 取值辅助 ────────────────────────────────────────────────
+
+func anyString(v any) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return ""
+}
+
+func remoteItemString(item map[string]any, key string) string {
+	if item == nil {
+		return ""
+	}
+	if s, ok := item[key].(string); ok {
+		return s
+	}
+	return ""
+}
+
+func remoteItemInt(item map[string]any, key string) int {
+	if item == nil {
+		return 0
+	}
+	switch v := item[key].(type) {
+	case float64:
+		return int(v)
+	case int:
+		return v
+	case int64:
+		return int(v)
+	case string:
+		n, _ := strconv.Atoi(v)
+		return n
+	}
+	return 0
+}
+
+func remoteItemInt64(item map[string]any, key string) int64 {
+	if item == nil {
+		return 0
+	}
+	switch v := item[key].(type) {
+	case float64:
+		return int64(v)
+	case int64:
+		return v
+	case int:
+		return int64(v)
+	case string:
+		n, _ := strconv.ParseInt(v, 10, 64)
+		return n
+	}
+	return 0
+}
+
+func remoteItemFloat(item map[string]any, key string) float64 {
+	if item == nil {
+		return 0
+	}
+	switch v := item[key].(type) {
+	case float64:
+		return v
+	case int:
+		return float64(v)
+	case string:
+		f, _ := strconv.ParseFloat(v, 64)
+		return f
+	}
+	return 0
+}
+
+// remoteItemGenres 合并 GenreItems / Genres 数组为逗号分隔字符串（前端 parseCSV 消费）。
+func remoteItemGenres(item map[string]any) string {
+	seen := map[string]bool{}
+	var parts []string
+	collect := func(arr any) {
+		list, ok := arr.([]any)
+		if !ok {
+			return
+		}
+		for _, it := range list {
+			var name string
+			if m, isMap := it.(map[string]any); isMap {
+				name = remoteItemString(m, "Name")
+			} else if s, isStr := it.(string); isStr {
+				name = s
+			}
+			if name != "" && !seen[name] {
+				seen[name] = true
+				parts = append(parts, name)
+			}
+		}
+	}
+	collect(item["GenreItems"])
+	collect(item["Genres"])
+	return strings.Join(parts, ",")
+}
+
+// remoteItemImageURL 构造远程条目图片绝对地址（带 api_key；前端经 /api/img 代理）。
+func (r *EmbyRemoteService) remoteItemImageURL(cfg *EmbyRemoteConfig, remoteID, imageType string) string {
+	if remoteID == "" {
+		return ""
+	}
+	imageType = strings.ToLower(imageType)
+	if imageType == "" {
+		imageType = "primary"
+	}
+	return r.embyBase(cfg) + "/Items/" + url.PathEscape(remoteID) + "/Images/" + url.PathEscape(imageType) +
+		"?api_key=" + url.QueryEscape(cfg.Token)
+}
+
+// remoteItemHasImageTag 远程 item 是否带某类型图片标签（Emby 的 ImageTags map）。
+func remoteItemHasImageTag(item map[string]any, typ string) bool {
+	if item == nil {
+		return false
+	}
+	switch tags := item["ImageTags"].(type) {
+	case map[string]any:
+		_, ok := tags[typ]
+		return ok
+	case map[string]string:
+		_, ok := tags[typ]
+		return ok
+	}
+	return false
+}
+
+// remoteBackdropTags 远程 item 的 BackdropImageTags 数组。
+func remoteBackdropTags(item map[string]any) []any {
+	if item == nil {
+		return nil
+	}
+	switch tags := item["BackdropImageTags"].(type) {
+	case []any:
+		return tags
+	case []string:
+		out := make([]any, 0, len(tags))
+		for _, s := range tags {
+			out = append(out, s)
+		}
+		return out
+	}
+	return nil
+}
+
+// remoteItemTypeOf 从映射后的 Media 推断远程类型（无详情载荷时兜底）。
+func remoteItemTypeOf(m *model.Media) string {
+	if m == nil {
+		return "Movie"
+	}
+	if m.EpisodeNum > 0 || m.SeasonNum > 0 {
+		return "Episode"
+	}
+	return "Movie"
+}
+
+// ─── 供 handler 层使用的远程 View 条目取值（导出薄封装） ──────────────────────
+
+// RemoteItemIDString 提取远程 View 条目的 Id。
+func RemoteItemIDString(item map[string]any) string { return remoteItemString(item, "Id") }
+
+// RemoteItemNameString 提取远程 View 条目的 Name。
+func RemoteItemNameString(item map[string]any) string { return remoteItemString(item, "Name") }
+
+// RemoteItemCollectionType 提取远程 View 条目的 CollectionType。
+func RemoteItemCollectionType(item map[string]any) string {
+	return remoteItemString(item, "CollectionType")
+}
+
+// RemoteItemChildCount 提取远程 View 条目的 ChildCount。
+func RemoteItemChildCount(item map[string]any) int { return remoteItemInt(item, "ChildCount") }
+
+func parseEmbyRemoteDate(s string) (time.Time, bool) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return time.Time{}, false
+	}
+	for _, layout := range []string{
+		time.RFC3339Nano,
+		time.RFC3339,
+		"2006-01-02T15:04:05.9999999Z",
+		"2006-01-02T15:04:05.9999999",
+		"2006-01-02T15:04:05",
+		"2006-01-02",
+	} {
+		if t, err := time.Parse(layout, s); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}
@@ -0,0 +1,67 @@
+package service
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+func TestMapRemoteItemToMediaSortingFields(t *testing.T) {
+	svc := &EmbyRemoteService{}
+	mount := &model.EmbyMount{Base: model.Base{ID: "mount-1"}}
+	acct := &model.StrmAccount{Base: model.Base{ID: "acct-1"}}
+	cfg := &EmbyRemoteConfig{BaseURL: "http://localhost:8096"}
+
+	item := map[string]any{
+		"Id":              "item-1",
+		"Name":            "测试电影",
+		"OriginalTitle":   "Test Movie",
+		"ProductionYear":  2023,
+		"CommunityRating": 8.5,
+		"PremiereDate":    "2023-05-12T00:00:00.0000000Z",
+		"DateCreated":     "2024-01-15T08:30:00.0000000Z",
+	}
+
+	media := svc.MapRemoteItemToMedia(context.Background(), mount, acct, cfg, item)
+
+	if media.ReleaseDate != "2023-05-12" {
+		t.Fatalf("ReleaseDate = %q, want %q", media.ReleaseDate, "2023-05-12")
+	}
+	if media.Year != 2023 {
+		t.Fatalf("Year = %d, want 2023", media.Year)
+	}
+	if media.Rating != 8.5 {
+		t.Fatalf("Rating = %f, want 8.5", media.Rating)
+	}
+	expectedCreated, _ := time.Parse(time.RFC3339, "2024-01-15T08:30:00Z")
+	if !media.CreatedAt.Equal(expectedCreated) {
+		t.Fatalf("CreatedAt = %v, want %v", media.CreatedAt, expectedCreated)
+	}
+	if !media.UpdatedAt.Equal(expectedCreated) {
+		t.Fatalf("UpdatedAt = %v, want %v", media.UpdatedAt, expectedCreated)
+	}
+}
+
+func TestMapRemoteItemToMediaCriticRatingFallback(t *testing.T) {
+	svc := &EmbyRemoteService{}
+	mount := &model.EmbyMount{Base: model.Base{ID: "mount-1"}}
+	acct := &model.StrmAccount{Base: model.Base{ID: "acct-1"}}
+	cfg := &EmbyRemoteConfig{BaseURL: "http://localhost:8096"}
+
+	item := map[string]any{
+		"Id":           "item-2",
+		"Name":         "评分测试",
+		"CriticRating": 9.2,
+		"PremiereDate": "2022-10-01",
+	}
+
+	media := svc.MapRemoteItemToMedia(context.Background(), mount, acct, cfg, item)
+	if media.Rating != 9.2 {
+		t.Fatalf("Rating = %f, want 9.2 from CriticRating", media.Rating)
+	}
+	if media.Year != 2022 {
+		t.Fatalf("Year = %d, want 2022 from PremiereDate", media.Year)
+	}
+}
@@ -124,7 +124,8 @@ func (e *EmbyService) userPayload(u *model.User) map[string]any {
 	}
 }

-// Views 返回 Emby 中"虚拟根目录"——每个 library 一个条目。
+// Views 返回 Emby 中"虚拟根目录"——每个 library 一个条目，外加所有启用的
+// 远程 Emby 挂载的媒体库（联邦聚合）。
 func (e *EmbyService) Views(ctx context.Context, userID string) (map[string]any, error) {
 	libs, err := e.repo.Library.List(ctx)
 	if err != nil {
@@ -132,16 +133,92 @@ func (e *EmbyService) Views(ctx context.Context, userID string) (map[string]any,
 	}
 	libs = FilterDisplayCloudLibraries(ctx, e.repo, libs)
 	visibility := e.mediaVisibility(ctx, userID)
-	items := make([]map[string]any, 0, len(libs))
+	items := make([]map[string]any, 0, len(libs)+4)
 	for _, l := range libs {
 		if !e.libraryVisibleFromCachedVisibility(l, visibility) {
 			continue
 		}
 		items = append(items, e.libraryAsView(ctx, &l))
 	}
+	for _, remote := range e.remoteViews(ctx) {
+		items = append(items, remote)
+	}
 	return map[string]any{"Items": items, "TotalRecordCount": len(items), "StartIndex": 0}, nil
 }

+// remoteViews 返回全部启用挂载的远程媒体库视图（只有显式挂载的库才出现）。
+func (e *EmbyService) remoteViews(ctx context.Context) []map[string]any {
+	if e == nil || e.remote == nil {
+		return nil
+	}
+	views, err := e.remote.RemoteLibraries(ctx)
+	if err != nil || len(views) == 0 {
+		return nil
+	}
+	out := make([]map[string]any, 0, len(views))
+	for _, v := range views {
+		out = append(out, remoteLibraryViewPayload(v))
+	}
+	return out
+}
+
+// remoteLibraryViewPayload 把挂载库展示信息标准化为 Emby View payload
+// （ID 用挂载伪装，名称=挂载显示名）。
+func remoteLibraryViewPayload(v RemoteLibraryView) map[string]any {
+	encoded := EncodeEmbyRemoteID(v.MountID, v.RemoteID)
+	collectionType := v.CollectionType
+	if !isSupportedEmbyCollectionType(collectionType) {
+		collectionType = "mixed"
+	}
+	name := strings.TrimSpace(v.Library.Name)
+	imageTags := map[string]string{}
+	if strings.TrimSpace(v.Library.CoverURL) != "" {
+		imageTags["Primary"] = encoded
+	}
+	return map[string]any{
+		"Id":                       encoded,
+		"Name":                     name,
+		"CollectionType":           collectionType,
+		"ServerId":                 embyServerID,
+		"Type":                     "CollectionFolder",
+		"IsFolder":                 true,
+		"Path":                     "",
+		"SortName":                 strings.ToLower(name),
+		"DateCreated":              time.Now().UTC().Format(time.RFC3339),
+		"CanDelete":                false,
+		"CanDownload":              false,
+		"DisplayPreferencesId":     encoded,
+		"PrimaryImageItemId":       encoded,
+		"PrimaryImageAspectRatio":  1.7777777777777777,
+		"RecursiveItemCount":       0,
+		"ChildCount":               0,
+		"SpecialFeatureCount":      0,
+		"EnableMediaSourceDisplay": true,
+		"PlayAccess":               "Full",
+		"ExternalUrls":             []any{},
+		"ProviderIds":              map[string]string{},
+		"Genres":                   []string{},
+		"Tags":                     []string{},
+		"ImageTags":                imageTags,
+		"BackdropImageTags":        []string{},
+		"UserData": map[string]any{
+			"PlaybackPositionTicks": 0,
+			"PlayCount":             0,
+			"IsFavorite":            false,
+			"Played":                false,
+			"UnplayedItemCount":     0,
+		},
+	}
+}
+
+func isSupportedEmbyCollectionType(t string) bool {
+	switch t {
+	case "movies", "tvshows", "music", "mixed", "homevideos", "boxsets":
+		return true
+	}
+	return false
+}
+
 func (e *EmbyService) libraryAsView(ctx context.Context, l *model.Library) map[string]any {
 	collectionType := "movies"
 	switch l.Type {
@@ -12,8 +12,16 @@ import (
 	"github.com/ShukeBta/MMTL/internal/model"
 )

-// SetFavorite 把 mediaID 标为 userID 的收藏。
+// SetFavorite 把 mediaID 标为 userID 的收藏。远程 Emby 条目直接透传到对应
+// 服务器（本地不落库）。
 func (e *EmbyService) SetFavorite(ctx context.Context, userID, mediaID string, favorite bool) error {
+	if e.remote != nil && IsEmbyRemoteID(mediaID) {
+		acctID, remoteID, _ := DecodeEmbyRemoteID(mediaID)
+		if err := e.ProxyRemoteSetFavorite(ctx, acctID, remoteID, favorite); err != nil {
+			return err
+		}
+		return nil
+	}
 	if favorite {
 		var f model.Favorite
 		err := e.repo.DB.WithContext(ctx).
@@ -31,11 +39,23 @@ func (e *EmbyService) SetFavorite(ctx context.Context, userID, mediaID string, f
 }

 // MarkPlayed 把 mediaID 标为已看（写一个 100% 进度的 history 行）。
+// 远程 Emby 条目直接透传到对应服务器（本地不落库）。
 func (e *EmbyService) MarkPlayed(ctx context.Context, userID, mediaID string, played bool) error {
+	if e.remote != nil && IsEmbyRemoteID(mediaID) {
+		acctID, remoteID, _ := DecodeEmbyRemoteID(mediaID)
+		if err := e.ProxyRemoteSetPlayed(ctx, acctID, remoteID, played); err != nil {
+			return err
+		}
+		return nil
+	}
 	if !played {
-		return e.repo.DB.WithContext(ctx).
+		err := e.repo.DB.WithContext(ctx).
 			Where("user_id = ? AND media_id = ?", userID, mediaID).
 			Delete(&model.PlaybackHistory{}).Error
+		if err == nil {
+			e.invalidateEmbyItemsCache(ctx)
+		}
+		return err
 	}
 	m, err := e.repo.Media.FindByID(ctx, mediaID)
 	if err != nil || m == nil {
@@ -45,7 +65,7 @@ func (e *EmbyService) MarkPlayed(ctx context.Context, userID, mediaID string, pl
 	if dur <= 0 {
 		dur = 1
 	}
-	return e.repo.History.Upsert(ctx, &model.PlaybackHistory{
+	err = e.repo.History.Upsert(ctx, &model.PlaybackHistory{
 		UserID:     userID,
 		MediaID:    mediaID,
 		PositionMs: dur,
@@ -53,6 +73,10 @@ func (e *EmbyService) MarkPlayed(ctx context.Context, userID, mediaID string, pl
 		WatchedAt:  time.Now(),
 		Completed:  true,
 	})
+	if err == nil {
+		e.invalidateEmbyItemsCache(ctx)
+	}
+	return err
 }

 // RecordProgress 记录播放进度（来自 Emby 客户端的 /Sessions/Playing/Progress）。
@@ -63,10 +87,27 @@ func (e *EmbyService) RecordProgress(ctx context.Context, userID, mediaID string
 		// runtimeTicks 缺失时回退到 media.DurationSec
 		if m, _ := e.repo.Media.FindByID(ctx, mediaID); m != nil {
 			dur = int64(m.DurationSec) * 1000
+		} else if IsEmbyRemoteID(mediaID) {
+			// 远程挂载条目：尝试从既有历史记录或远程详情补齐时长
+			var oldHist model.PlaybackHistory
+			if err := e.repo.DB.WithContext(ctx).Where("user_id = ? AND media_id = ?", userID, mediaID).First(&oldHist).Error; err == nil && oldHist.DurationMs > 0 {
+				dur = oldHist.DurationMs
+			} else if e.remote != nil {
+				mountID, remoteID, _ := DecodeEmbyRemoteID(mediaID)
+				if mount, acct, _ := e.remote.ResolveMount(ctx, mountID); mount != nil && acct != nil {
+					if item, _ := e.remote.RemoteItem(ctx, mount, acct, remoteID); item != nil {
+						if ticks, ok := item["RunTimeTicks"].(float64); ok && ticks > 0 {
+							dur = int64(ticks) / 10_000
+						} else if ticks, ok := item["RunTimeTicks"].(int64); ok && ticks > 0 {
+							dur = ticks / 10_000
+						}
+					}
+				}
+			}
 		}
 	}
 	completed := dur > 0 && pos >= dur*9/10
-	return e.repo.History.Upsert(ctx, &model.PlaybackHistory{
+	err := e.repo.History.Upsert(ctx, &model.PlaybackHistory{
 		UserID:     userID,
 		MediaID:    mediaID,
 		PositionMs: pos,
@@ -74,6 +115,115 @@ func (e *EmbyService) RecordProgress(ctx context.Context, userID, mediaID string
 		WatchedAt:  time.Now(),
 		Completed:  completed,
 	})
+	if err == nil {
+		e.invalidateEmbyItemsCache(ctx)
+	}
+	return err
+}
+
+// mergeRemoteUserData applies the current MMTL user's locally recorded playback
+// state to remote Emby payloads. Remote metadata remains authoritative unless the
+// user has played the item through MMTL.
+func (e *EmbyService) mergeRemoteUserData(ctx context.Context, userID string, payload any) error {
+	if strings.TrimSpace(userID) == "" || payload == nil {
+		return nil
+	}
+	items := remoteItemMaps(payload)
+	ids := make([]string, 0, len(items))
+	seen := make(map[string]struct{}, len(items))
+	for _, item := range items {
+		id, _ := item["Id"].(string)
+		if !IsEmbyRemoteID(id) {
+			continue
+		}
+		if _, ok := seen[id]; !ok {
+			ids = append(ids, id)
+			seen[id] = struct{}{}
+		}
+	}
+	if len(ids) == 0 {
+		return nil
+	}
+	var histories []model.PlaybackHistory
+	if err := e.repo.DB.WithContext(ctx).Where("user_id = ? AND media_id IN ?", userID, ids).Find(&histories).Error; err != nil {
+		return err
+	}
+	byMediaID := make(map[string]*model.PlaybackHistory, len(histories))
+	for i := range histories {
+		byMediaID[histories[i].MediaID] = &histories[i]
+	}
+	for _, item := range items {
+		id, _ := item["Id"].(string)
+		if h := byMediaID[id]; h != nil {
+			item["UserData"] = mergedRemoteUserData(item["UserData"], h)
+		}
+	}
+	return nil
+}
+
+func remoteItemMaps(payload any) []map[string]any {
+	items := make([]map[string]any, 0)
+	var visit func(any)
+	visit = func(value any) {
+		switch typed := value.(type) {
+		case map[string]any:
+			if _, ok := typed["Id"].(string); ok {
+				items = append(items, typed)
+			}
+			if nested, ok := typed["Items"]; ok {
+				visit(nested)
+			}
+		case []any:
+			for _, value := range typed {
+				visit(value)
+			}
+		case []map[string]any:
+			for _, value := range typed {
+				visit(value)
+			}
+		}
+	}
+	visit(payload)
+	return items
+}
+
+func mergedRemoteUserData(raw any, history *model.PlaybackHistory) map[string]any {
+	userData := map[string]any{}
+	if existing, ok := raw.(map[string]any); ok {
+		for key, value := range existing {
+			userData[key] = value
+		}
+	}
+	duration := history.DurationMs
+	position := history.PositionMs
+	percentage := float64(0)
+	if duration > 0 {
+		percentage = float64(position) / float64(duration) * 100
+	}
+	userData["PlaybackPositionTicks"] = position * 10_000
+	userData["Played"] = history.Completed
+	userData["PlayedPercentage"] = percentage
+	if history.Completed {
+		playCount := 0
+		switch value := userData["PlayCount"].(type) {
+		case int:
+			playCount = value
+		case int64:
+			playCount = int(value)
+		case float64:
+			playCount = int(value)
+		}
+		if playCount < 1 {
+			userData["PlayCount"] = 1
+		}
+	}
+	return userData
+}
+
+func (e *EmbyService) invalidateEmbyItemsCache(ctx context.Context) {
+	if e.cache != nil {
+		e.cache.DeletePrefix(ctx, "media:emby:")
+	}
 }

 func splitCSV(s string) []string {
@@ -0,0 +1,110 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/ShukeBta/MMTL/internal/model"
+)
+
+func TestMergedRemoteUserData(t *testing.T) {
+	tests := []struct {
+		name     string
+		raw      any
+		history  model.PlaybackHistory
+		position int64
+		played   bool
+		percent  float64
+		count    int
+		preserve any
+	}{
+		{
+			name: "in-progress preserves remote fields",
+			raw: map[string]any{
+				"PlayCount": 2,
+				"Custom":    "remote-value",
+			},
+			history:  model.PlaybackHistory{PositionMs: 25_000, DurationMs: 100_000},
+			position: 250_000_000,
+			played:   false,
+			percent:  25,
+			count:    2,
+			preserve: "remote-value",
+		},
+		{
+			name:     "completed ensures a play count",
+			raw:      map[string]any{"PlayCount": 0},
+			history:  model.PlaybackHistory{PositionMs: 100_000, DurationMs: 100_000, Completed: true},
+			position: 1_000_000_000,
+			played:   true,
+			percent:  100,
+			count:    1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			out := mergedRemoteUserData(tt.raw, &tt.history)
+			if got := out["PlaybackPositionTicks"]; got != tt.position {
+				t.Fatalf("PlaybackPositionTicks = %#v, want %d", got, tt.position)
+			}
+			if got := out["Played"]; got != tt.played {
+				t.Fatalf("Played = %#v, want %t", got, tt.played)
+			}
+			if got := out["PlayedPercentage"]; got != tt.percent {
+				t.Fatalf("PlayedPercentage = %#v, want %v", got, tt.percent)
+			}
+			if got := out["PlayCount"]; got != tt.count {
+				t.Fatalf("PlayCount = %#v, want %d", got, tt.count)
+			}
+			if tt.preserve != nil && out["Custom"] != tt.preserve {
+				t.Fatalf("Custom = %#v, want %#v", out["Custom"], tt.preserve)
+			}
+		})
+	}
+}
+
+func TestRemoteItemMapsFindsEnvelopeItems(t *testing.T) {
+	remoteID := EncodeEmbyRemoteID("mount-1", "item-1")
+	payload := map[string]any{
+		"Items": []any{
+			map[string]any{"Id": remoteID},
+			map[string]any{"Id": "local-item"},
+		},
+	}
+	items := remoteItemMaps(payload)
+	if len(items) != 2 {
+		t.Fatalf("item count = %d, want 2", len(items))
+	}
+	if items[0]["Id"] != remoteID {
+		t.Fatalf("first item ID = %#v, want %q", items[0]["Id"], remoteID)
+	}
+}
+
+func TestRecordProgressFallbacksToExistingHistoryDuration(t *testing.T) {
+	svc := newTestEmbyService(t)
+	remoteID := EncodeEmbyRemoteID("mount-test", "item-999")
+	user := &model.User{Username: "resume_test_user", Role: "user", Tier: "free", IsActive: true}
+	if err := svc.repo.User.Create(t.Context(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	// 先以有 runtimeTicks 写入首次进度
+	if err := svc.RecordProgress(t.Context(), user.ID, remoteID, 10_000_000, 100_000_000); err != nil {
+		t.Fatalf("first record progress: %v", err)
+	}
+	// 再次上报，但某些客户端此时发了 0 runtimeTicks
+	if err := svc.RecordProgress(t.Context(), user.ID, remoteID, 95_000_000, 0); err != nil {
+		t.Fatalf("second record progress: %v", err)
+	}
+
+	var hist model.PlaybackHistory
+	if err := svc.repo.DB.Where("user_id = ? AND media_id = ?", user.ID, remoteID).First(&hist).Error; err != nil {
+		t.Fatalf("find hist: %v", err)
+	}
+	if hist.DurationMs != 10_000 {
+		t.Fatalf("expected duration 10000ms, got %d", hist.DurationMs)
+	}
+	if !hist.Completed {
+		t.Fatalf("expected 95%% progress to be completed")
+	}
+}
@@ -1,196 +1,358 @@
 package service

 import (
+	"archive/tar"
 	"context"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"time"

+	"github.com/ulikunitz/xz"
 	"go.uber.org/zap"

 	"github.com/ShukeBta/MMTL/internal/config"
 )

-// AutoInstallFFmpeg is only called by the admin tool-install endpoint. The
-// server must not auto-download or keep ffmpeg/ffprobe running during startup.
-func AutoInstallFFmpeg(log *zap.Logger, cfg *config.Config) (ffprobePath, ffmpegPath string) {
-	// 1. 优先使用配置 / PATH / 本机常见软件目录中的现有工具。
-	if path, err := resolveLocalExecutable(cfg.App.FFprobePath, "ffprobe"); err == nil {
-		ffprobePath = path
-		cfg.App.FFprobePath = path
-		log.Info("found local ffprobe", zap.String("path", path))
-	}
-	if path, err := resolveLocalExecutable(cfg.App.FFmpegPath, "ffmpeg"); err == nil {
-		ffmpegPath = path
-		cfg.App.FFmpegPath = path
-		log.Info("found local ffmpeg", zap.String("path", path))
-	}
-	if ffprobePath != "" || ffmpegPath != "" {
-		return ffprobePath, ffmpegPath
-	}
+// ffmpegDownloadTarget 描述某个平台对应的官方构建下载源。
+type ffmpegDownloadTarget struct {
+	Label    string   // 展示名，如 "Windows x86_64"
+	Kind     string   // 压缩包类型：zip / tar.xz
+	Archives []string // 依次尝试的下载地址（主源 + 备用源）
+}

-	// 2. 检查默认安装位置。
-	defaultDir := getDefaultInstallDir()
-	ffprobeDefault := filepath.Join(defaultDir, "bin", "ffprobe.exe")
-	ffmpegDefault := filepath.Join(defaultDir, "bin", "ffmpeg.exe")
-
-	if _, err := os.Stat(ffprobeDefault); err == nil {
-		log.Info("在默认位置找到 ffprobe", zap.String("path", ffprobeDefault))
-		return ffprobeDefault, ffmpegDefault
-	}
-
-	// 3. 尝试自动安装。
-	log.Warn("未找到 ffmpeg/ffprobe，尝试自动安装...")
-	installed, err := tryAutoInstall(log, defaultDir)
-	if err != nil {
-		log.Error("自动安装失败，请手动安装 ffmpeg", zap.Error(err))
-		return "", ""
-	}
-
-	if installed {
-		if _, err := os.Stat(ffprobeDefault); err == nil {
-			log.Info("自动安装成功", zap.String("path", ffprobeDefault))
-			// 更新配置
-			updateConfigPaths(cfg, ffprobeDefault, ffmpegDefault)
-			return ffprobeDefault, ffmpegDefault
+// ffmpegTargetForPlatform 按当前运行环境（OS+架构）选择下载源。
+func ffmpegTargetForPlatform() (*ffmpegDownloadTarget, error) {
+	switch runtime.GOOS {
+	case "windows":
+		switch runtime.GOARCH {
+		case "amd64":
+			return &ffmpegDownloadTarget{
+				Label: "Windows x86_64",
+				Kind:  "zip",
+				Archives: []string{
+					"https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip",
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip",
+				},
+			}, nil
+		case "386":
+			return &ffmpegDownloadTarget{
+				Label: "Windows x86",
+				Kind:  "zip",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win32-gpl.zip",
+				},
+			}, nil
+		}
+	case "linux":
+		switch runtime.GOARCH {
+		case "amd64":
+			return &ffmpegDownloadTarget{
+				Label: "Linux x86_64",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl.tar.xz",
+					"https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz",
+				},
+			}, nil
+		case "arm64":
+			return &ffmpegDownloadTarget{
+				Label: "Linux ARM64",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxarm64-gpl.tar.xz",
+					"https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-arm64-static.tar.xz",
+				},
+			}, nil
+		case "arm":
+			return &ffmpegDownloadTarget{
+				Label: "Linux ARM (32 位)",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxarmhf-gpl.tar.xz",
+				},
+			}, nil
+		case "loong64":
+			return &ffmpegDownloadTarget{
+				Label: "Linux LoongArch64",
+				Kind:  "tar.xz",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxloongarch64-gpl.tar.xz",
+				},
+			}, nil
+		}
+	case "darwin":
+		switch runtime.GOARCH {
+		case "amd64":
+			return &ffmpegDownloadTarget{
+				Label: "macOS x86_64",
+				Kind:  "zip",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-osx64-gpl.zip",
+				},
+			}, nil
+		case "arm64":
+			return &ffmpegDownloadTarget{
+				Label: "macOS Apple Silicon",
+				Kind:  "zip",
+				Archives: []string{
+					"https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-osxarm64-gpl.zip",
+				},
+			}, nil
 		}
 	}
-
-	return "", ""
+	return nil, fmt.Errorf("暂不支持自动下载的平台 %s/%s，请手动填写 ffmpeg/ffprobe 路径", runtime.GOOS, runtime.GOARCH)
 }

-// getDefaultInstallDir 返回默认安装目录
-func getDefaultInstallDir() string {
-	exePath, err := os.Executable()
+// installFFmpegTools 按平台下载并安装 ffmpeg/ffprobe 到 data/tools/ffmpeg/，
+// 返回两个可执行文件的绝对路径。progress 用于回传阶段消息（UI 展示）。
+func installFFmpegTools(ctx context.Context, log *zap.Logger, cfg *config.Config, progress func(string)) (ffmpegPath, ffprobePath string, err error) {
+	target, err := ffmpegTargetForPlatform()
 	if err != nil {
-		return "./tools/ffmpeg"
+		return "", "", err
 	}
-	exeDir := filepath.Dir(exePath)
-	return filepath.Join(exeDir, "tools", "ffmpeg")
-}
-
-// tryAutoInstall 尝试自动下载并安装 ffmpeg
-func tryAutoInstall(log *zap.Logger, installDir string) (bool, error) {
-	if runtime.GOOS == "windows" {
-		return downloadFFmpegWindows(log, installDir)
-	}
-
-	return false, fmt.Errorf("不支持的操作系统: %s", runtime.GOOS)
-}
-
-// downloadFFmpegWindows 下载 Windows 版本的 ffmpeg
-func downloadFFmpegWindows(log *zap.Logger, installDir string) (bool, error) {
-	log.Info("开始下载 ffmpeg...")
-
-	// 创建安装目录
+	installDir := filepath.Join(cfg.App.DataDir, "tools", "ffmpeg")
 	if err := os.MkdirAll(installDir, 0o750); err != nil {
-		return false, fmt.Errorf("创建安装目录失败: %w", err)
+		return "", "", fmt.Errorf("创建安装目录失败: %w", err)
 	}

 	tempDir, err := os.MkdirTemp("", "mmtl-ffmpeg-*")
 	if err != nil {
-		return false, fmt.Errorf("创建临时目录失败: %w", err)
+		return "", "", fmt.Errorf("创建临时目录失败: %w", err)
 	}
 	defer os.RemoveAll(tempDir)

-	// 下载 URL (使用 gyani.org 的静态构建)
-	arch := "win64"
-	if !is64Bit() {
-		arch = "win32"
+	progress("下载 " + target.Label + " 版本…")
+	archivePath := filepath.Join(tempDir, "ffmpeg-archive."+target.Kind)
+	if err := downloadFFmpegArchive(ctx, log, target.Archives, archivePath); err != nil {
+		return "", "", err
 	}

-	// 先尝试从 gyan.dev 下载（更可靠）
-	downloadURL := fmt.Sprintf("https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip")
+	progress("解压…")
+	extractDir := filepath.Join(tempDir, "extract")
+	if err := extractFFmpegArchive(target.Kind, archivePath, extractDir); err != nil {
+		return "", "", fmt.Errorf("解压失败: %w", err)
+	}

-	log.Info("下载 ffmpeg", zap.String("url", downloadURL))
+	exeSuffix := ""
+	if runtime.GOOS == "windows" {
+		exeSuffix = ".exe"
+	}
+	srcFFmpeg, srcFFprobe, err := locateFFmpegBinaries(extractDir, exeSuffix)
+	if err != nil {
+		return "", "", err
+	}

-	// 使用 Go 下载
-	zipPath := filepath.Join(tempDir, "ffmpeg.zip")
-	if err := downloadFile(log, downloadURL, zipPath); err != nil {
-		// 尝试备用 URL
-		backupURL := fmt.Sprintf("https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-%s-gpl.zip", arch)
-		log.Info("尝试备用下载地址", zap.String("url", backupURL))
-		if err2 := downloadFile(log, backupURL, zipPath); err2 != nil {
-			return false, fmt.Errorf("下载失败: %v, %v", err, err2)
+	progress("安装到 data 目录…")
+	ffmpegPath = filepath.Join(installDir, "ffmpeg"+exeSuffix)
+	ffprobePath = filepath.Join(installDir, "ffprobe"+exeSuffix)
+	if err := copyFileMode(srcFFmpeg, ffmpegPath); err != nil {
+		return "", "", fmt.Errorf("复制 ffmpeg 失败: %w", err)
+	}
+	if err := copyFileMode(srcFFprobe, ffprobePath); err != nil {
+		_ = os.Remove(ffmpegPath)
+		return "", "", fmt.Errorf("复制 ffprobe 失败: %w", err)
+	}
+
+	// 验证两个工具都能运行（失败则回滚，避免留下坏文件）。
+	for _, bin := range []string{ffmpegPath, ffprobePath} {
+		cmd := exec.CommandContext(ctx, bin, "-version") // #nosec G204 -- bin 是安装目录中刚写入的固定文件名。
+		if out, verr := cmd.Output(); verr != nil {
+			_ = os.Remove(ffmpegPath)
+			_ = os.Remove(ffprobePath)
+			return "", "", fmt.Errorf("安装后 %s 无法运行：%v", filepath.Base(bin), verr)
+		} else if log != nil {
+			log.Info("ffmpeg 工具安装验证通过", zap.String("bin", filepath.Base(bin)),
+				zap.String("version", strings.TrimSpace(strings.SplitN(string(out), "\n", 2)[0])))
 		}
 	}
-
-	// 解压
-	log.Info("解压 ffmpeg...")
-	extractDir := filepath.Join(tempDir, "extract")
-	if err := unzip(log, zipPath, extractDir); err != nil {
-		return false, fmt.Errorf("解压失败: %w", err)
-	}
-
-	packageRoot, err := findFFmpegPackageRoot(extractDir)
-	if err != nil {
-		return false, err
-	}
-	if err := copyDirContents(packageRoot, installDir); err != nil {
-		return false, fmt.Errorf("复制 ffmpeg 文件失败: %w", err)
-	}
-
-	ffmpegBin := filepath.Join(installDir, "bin", "ffmpeg.exe")
-	ffprobeBin := filepath.Join(installDir, "bin", "ffprobe.exe")
-	if _, err := os.Stat(ffmpegBin); err != nil {
-		return false, fmt.Errorf("安装后未找到 ffmpeg: %w", err)
-	}
-	if _, err := os.Stat(ffprobeBin); err != nil {
-		return false, fmt.Errorf("安装后未找到 ffprobe: %w", err)
-	}
-
-	log.Info("ffmpeg 安装完成", zap.String("dir", installDir))
-	return true, nil
+	progress("安装完成")
+	return ffmpegPath, ffprobePath, nil
 }

-// downloadFile 下载文件
-func downloadFile(log *zap.Logger, url, filepath string) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
-	defer cancel()
+// downloadFFmpegArchive 按顺序尝试下载源，全部失败才返回错误。
+func downloadFFmpegArchive(ctx context.Context, log *zap.Logger, urls []string, dest string) error {
+	var lastErr error
+	for i, u := range urls {
+		if i > 0 && log != nil {
+			log.Warn("ffmpeg 主下载源不可用，切换备用源", zap.String("url", u))
+		}
+		if err := downloadFFmpegFile(ctx, log, u, dest); err != nil {
+			lastErr = err
+			if log != nil {
+				log.Warn("ffmpeg 下载失败", zap.String("url", u), zap.Error(err))
+			}
+			continue
+		}
+		return nil
+	}
+	return fmt.Errorf("所有下载源均失败：%v", lastErr)
+}

-	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+// downloadFFmpegFile 下载单个归档文件（最多 10 分钟，限制大小上限）。
+func downloadFFmpegFile(ctx context.Context, log *zap.Logger, url, dest string) error {
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return err
 	}
-
+	req.Header.Set("User-Agent", "MMTL/ffmpeg-installer ("+runtime.GOOS+"/"+runtime.GOARCH+")")
 	resp, err := http.DefaultClient.Do(req)
 	if err != nil {
 		return err
 	}
 	defer resp.Body.Close()
-
 	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("下载失败，HTTP 状态码: %d", resp.StatusCode)
+		return fmt.Errorf("下载失败，HTTP 状态码 %d", resp.StatusCode)
 	}
-
-	out, err := os.Create(filepath) // #nosec G304 -- filepath is generated by the installer under its temporary download directory.
+	out, err := os.Create(dest) // #nosec G304 -- dest 是安装器在临时目录下生成的文件。
 	if err != nil {
 		return err
 	}
 	defer out.Close()
-
-	_, err = io.Copy(out, resp.Body)
-	return err
+	n, err := io.Copy(out, io.LimitReader(resp.Body, 500<<20+1)) // 归档上限 500MB
+	if err != nil {
+		return err
+	}
+	if n > 500<<20 {
+		return fmt.Errorf("归档文件过大（>500MB）: %s", url)
+	}
+	if log != nil {
+		log.Info("ffmpeg 归档下载完成", zap.String("url", url), zap.Int64("bytes", n))
+	}
+	return nil
 }

-// updateConfigPaths 更新配置文件中的路径
-func updateConfigPaths(cfg *config.Config, ffprobePath, ffmpegPath string) {
-	cfg.App.FFprobePath = ffprobePath
-	cfg.App.FFmpegPath = ffmpegPath
-
-	// 保存到配置文件
-	// 这里需要调用 config 包的保存函数
-	log := zap.L().Named("config")
-	log.Info("已更新 ffmpeg 路径配置",
-		zap.String("ffprobe", ffprobePath),
-		zap.String("ffmpeg", ffmpegPath))
+// extractFFmpegArchive 按类型解压 zip 或 tar.xz。
+func extractFFmpegArchive(kind, archivePath, destDir string) error {
+	switch kind {
+	case "zip":
+		return unzip(nil, archivePath, destDir)
+	case "tar.xz":
+		return untarXZ(archivePath, destDir)
+	default:
+		return fmt.Errorf("不支持的归档类型: %s", kind)
+	}
 }

-// is64Bit 检查是否为 64 位系统
-func is64Bit() bool {
-	return true // 简化处理，假设为 64 位
+// untarXZ 解压 .tar.xz 归档（GNU tar + xz 流式解压，纯 Go 无外部依赖），
+// 路径安全校验与 ZIP 解压一致。
+func untarXZ(archivePath, destDir string) error {
+	if err := os.MkdirAll(destDir, 0o750); err != nil {
+		return err
+	}
+	destRoot, err := filepath.Abs(destDir)
+	if err != nil {
+		return err
+	}
+	f, err := os.Open(archivePath) // #nosec G304 -- archivePath 是安装器在临时目录下生成的文件。
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	xzReader, err := xz.NewReader(f)
+	if err != nil {
+		return err
+	}
+	tr := tar.NewReader(xzReader)
+	var totalWritten int64
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		target, err := safeZipTarget(destRoot, hdr.Name) // 与 ZIP 相同的路径穿越防护
+		if err != nil {
+			return err
+		}
+		switch hdr.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(target, 0o750); err != nil {
+				return err
+			}
+		case tar.TypeReg, tar.TypeRegA:
+			if err := os.MkdirAll(filepath.Dir(target), 0o750); err != nil {
+				return err
+			}
+			dst, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, os.FileMode(hdr.Mode).Perm())
+			if err != nil {
+				return err
+			}
+			written, copyErr := io.Copy(dst, io.LimitReader(tr, maxFFmpegZipEntryBytes+1))
+			totalWritten += written
+			closeErr := dst.Close()
+			if copyErr != nil {
+				return copyErr
+			}
+			if closeErr != nil {
+				return closeErr
+			}
+			if written > maxFFmpegZipEntryBytes || totalWritten > maxFFmpegZipTotalBytes {
+				return fmt.Errorf("tar 内容过大: %s", hdr.Name)
+			}
+		default:
+			// 符号链接/设备等一律跳过（静态构建不会依赖它们）。
+			continue
+		}
+	}
+}
+
+// locateFFmpegBinaries 在解压目录中查找 ffmpeg/ffprobe 可执行文件（兼容
+// 不同构建包的目录布局：gyan 的 bin/、BtbN/johnvansickle 的根目录等）。
+func locateFFmpegBinaries(root, exeSuffix string) (ffmpeg, ffprobe string, err error) {
+	wantFFmpeg := "ffmpeg" + strings.ToLower(exeSuffix)
+	wantFFprobe := "ffprobe" + strings.ToLower(exeSuffix)
+	err = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		switch strings.ToLower(d.Name()) {
+		case wantFFmpeg:
+			if ffmpeg == "" {
+				ffmpeg = path
+			}
+		case wantFFprobe:
+			if ffprobe == "" {
+				ffprobe = path
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return "", "", fmt.Errorf("扫描解压目录失败: %w", err)
+	}
+	if ffmpeg == "" || ffprobe == "" {
+		return "", "", fmt.Errorf("解压内容中未找到 ffmpeg/ffprobe 可执行文件")
+	}
+	return ffmpeg, ffprobe, nil
+}
+
+// copyFileMode 复制文件并赋予可执行权限。
+func copyFileMode(src, dst string) error {
+	in, err := os.Open(src) // #nosec G304 -- src 来自解压目录遍历结果。
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+	out, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o755)
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		_ = out.Close()
+		return err
+	}
+	return out.Close()
 }
@@ -41,7 +41,9 @@ func unzip(log *zap.Logger, zipPath, destDir string) error {
 		}
 		info := file.FileInfo()
 		if info.Mode()&os.ModeSymlink != 0 {
-			log.Warn("跳过 ZIP 符号链接", zap.String("name", file.Name))
+			if log != nil {
+				log.Warn("跳过 ZIP 符号链接", zap.String("name", file.Name))
+			}
 			continue
 		}
 		if info.IsDir() {
@@ -109,94 +111,3 @@ func safeZipTarget(destRoot, name string) (string, error) {
 	}
 	return targetAbs, nil
 }
-
-func findFFmpegPackageRoot(root string) (string, error) {
-	var ffmpegPath string
-	var ffprobePath string
-
-	err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
-		if err != nil {
-			return err
-		}
-		if d.IsDir() {
-			return nil
-		}
-
-		switch strings.ToLower(d.Name()) {
-		case "ffmpeg.exe":
-			ffmpegPath = path
-		case "ffprobe.exe":
-			ffprobePath = path
-		}
-		return nil
-	})
-	if err != nil {
-		return "", fmt.Errorf("扫描解压目录失败: %w", err)
-	}
-	if ffmpegPath == "" || ffprobePath == "" {
-		return "", fmt.Errorf("解压后未找到 ffmpeg/ffprobe 可执行文件")
-	}
-
-	return filepath.Dir(filepath.Dir(ffmpegPath)), nil
-}
-
-func copyDirContents(srcDir, dstDir string) error {
-	entries, err := os.ReadDir(srcDir)
-	if err != nil {
-		return err
-	}
-
-	for _, entry := range entries {
-		srcPath := filepath.Join(srcDir, entry.Name())
-		dstPath := filepath.Join(dstDir, entry.Name())
-		if err := copyTree(srcPath, dstPath); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func copyTree(srcPath, dstPath string) error {
-	info, err := os.Stat(srcPath)
-	if err != nil {
-		return err
-	}
-
-	if info.IsDir() {
-		if err := os.MkdirAll(dstPath, info.Mode()); err != nil {
-			return err
-		}
-		entries, err := os.ReadDir(srcPath)
-		if err != nil {
-			return err
-		}
-		for _, entry := range entries {
-			if err := copyTree(filepath.Join(srcPath, entry.Name()), filepath.Join(dstPath, entry.Name())); err != nil {
-				return err
-			}
-		}
-		return nil
-	}
-
-	in, err := os.Open(srcPath) // #nosec G304 -- srcPath is produced by walking the validated extracted ffmpeg package tree.
-	if err != nil {
-		return err
-	}
-	defer in.Close()
-
-	if err := os.MkdirAll(filepath.Dir(dstPath), 0o750); err != nil {
-		return err
-	}
-
-	out, err := os.Create(dstPath) // #nosec G304 -- dstPath is generated under the configured ffmpeg install directory.
-	if err != nil {
-		return err
-	}
-	defer out.Close()
-
-	if _, err := io.Copy(out, in); err != nil {
-		return err
-	}
-
-	return out.Close()
-}
@@ -1,57 +0,0 @@
-package service
-
-import (
-	"bytes"
-	"os"
-	"os/exec"
-	"runtime"
-)
-
-// CheckFFmpegStatus 检查 ffmpeg/ffprobe 状态 (供 API 使用)
-func CheckFFmpegStatus(ffprobePath, ffmpegPath string) map[string]interface{} {
-	status := map[string]interface{}{
-		"ffprobe_installed": false,
-		"ffmpeg_installed":  false,
-		"auto_installable":  runtime.GOOS == "windows",
-	}
-
-	if ffprobePath != "" {
-		if _, err := os.Stat(ffprobePath); err == nil {
-			status["ffprobe_installed"] = true
-			status["ffprobe_path"] = ffprobePath
-
-			// 获取版本
-			cmd := exec.Command(ffprobePath, "-version")
-			out, err := cmd.Output()
-			if err == nil {
-				// 提取版本信息（第一行）
-				lines := bytes.Split(out, []byte("\n"))
-				if len(lines) > 0 {
-					version := string(bytes.TrimSpace(lines[0]))
-					status["ffprobe_version"] = version
-					status["ffprobe_security"] = EvaluateFFmpegSecurity(version)
-				}
-			}
-		}
-	}
-
-	if ffmpegPath != "" {
-		if _, err := os.Stat(ffmpegPath); err == nil {
-			status["ffmpeg_installed"] = true
-			status["ffmpeg_path"] = ffmpegPath
-
-			cmd := exec.Command(ffmpegPath, "-version")
-			out, err := cmd.Output()
-			if err == nil {
-				lines := bytes.Split(out, []byte("\n"))
-				if len(lines) > 0 {
-					version := string(bytes.TrimSpace(lines[0]))
-					status["ffmpeg_version"] = version
-					status["ffmpeg_security"] = EvaluateFFmpegSecurity(version)
-				}
-			}
-		}
-	}
-
-	return status
-}
@@ -0,0 +1,211 @@
+// Package service — ffmpeg/ffprobe 自动下载安装。
+//
+// FFmpegToolsService 负责「一键下载」：点击后按当前运行平台（OS+架构）选择
+// 官方构建包（Windows: gyan.dev / BtbN；Linux: BtbN / johnvansickle；
+// macOS: BtbN），下载解压 ffmpeg/ffprobe 到 data 目录（data/tools/ffmpeg/），
+// 并把绝对路径写入设置（ffmpeg.path / ffprobe.path），系统随即使用安装的
+// 工具，无需手动填写路径。
+package service
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+	"github.com/ShukeBta/MMTL/internal/repository"
+)
+
+// FFmpegToolsService 管理 ffmpeg/ffprobe 的自动下载安装状态（单飞：同一时间
+// 只允许一个安装任务）。
+type FFmpegToolsService struct {
+	cfg  *config.Config
+	log  *zap.Logger
+	repo *repository.Container
+
+	mu      sync.Mutex
+	running bool
+	msg     string    // 最近阶段/结果消息
+	errMsg  string    // 最近一次失败原因
+	started time.Time // 最近一次安装开始时间
+	done    time.Time // 最近一次安装结束时间
+}
+
+// NewFFmpegToolsService 构造工具安装服务。
+func NewFFmpegToolsService(cfg *config.Config, log *zap.Logger, repo *repository.Container) *FFmpegToolsService {
+	return &FFmpegToolsService{cfg: cfg, log: log, repo: repo}
+}
+
+// ffmpegInstallDir 返回 data 目录下的安装位置。
+func (s *FFmpegToolsService) ffmpegInstallDir() string {
+	return filepath.Join(s.cfg.App.DataDir, "tools", "ffmpeg")
+}
+
+// installedBinaries 检查安装目录中是否已存在 ffmpeg/ffprobe 可执行文件。
+func (s *FFmpegToolsService) installedBinaries() (ffmpeg, ffprobe string) {
+	exe := ""
+	if runtime.GOOS == "windows" {
+		exe = ".exe"
+	}
+	ffmpeg = filepath.Join(s.ffmpegInstallDir(), "ffmpeg"+exe)
+	ffprobe = filepath.Join(s.ffmpegInstallDir(), "ffprobe"+exe)
+	if _, err := os.Stat(ffmpeg); err != nil {
+		return "", ""
+	}
+	if _, err := os.Stat(ffprobe); err != nil {
+		return "", ""
+	}
+	return ffmpeg, ffprobe
+}
+
+// ffToolVersion 取工具第一行版本信息。
+func ffToolVersion(path string) string {
+	if path == "" {
+		return ""
+	}
+	out, err := exec.Command(path, "-version").Output() // #nosec G204 -- path 来自配置/安装目录中的已知工具。
+	if err != nil {
+		return ""
+	}
+	line := strings.SplitN(strings.TrimSpace(string(out)), "\n", 2)
+	if len(line) == 0 || strings.TrimSpace(line[0]) == "" {
+		return ""
+	}
+	return strings.TrimSpace(line[0])
+}
+
+// ffToolInfo 是单个工具的安装状态（返回给前端展示）。
+type ffToolInfo struct {
+	Installed bool   `json:"installed"`
+	Path      string `json:"path,omitempty"`
+	Version   string `json:"version,omitempty"`
+}
+
+// Status 返回当前安装状态（供 GET /api/admin/tools/ffmpeg/status 使用）。
+func (s *FFmpegToolsService) Status(ctx context.Context) map[string]any {
+	s.mu.Lock()
+	running, msg, errMsg, started, done := s.running, s.msg, s.errMsg, s.started, s.done
+	s.mu.Unlock()
+
+	startedAt, doneAt := "", ""
+	if !started.IsZero() {
+		startedAt = started.Format(time.RFC3339)
+	}
+	if !done.IsZero() {
+		doneAt = done.Format(time.RFC3339)
+	}
+
+	out := map[string]any{
+		"installing":  running,
+		"message":     msg,
+		"error":       errMsg,
+		"started_at":  startedAt,
+		"finished_at": doneAt,
+		"install_dir": s.ffmpegInstallDir(),
+	}
+	target, targetErr := ffmpegTargetForPlatform()
+	if targetErr != nil {
+		out["target"] = map[string]any{"label": targetErr.Error()}
+	} else {
+		out["target"] = map[string]any{
+			"os":    runtime.GOOS,
+			"arch":  runtime.GOARCH,
+			"label": target.Label,
+		}
+	}
+	// 报告「系统当前实际会使用」的工具：优先已生效配置（安装完成会把设置指到
+	// data 目录），其次 PATH / 常见目录。
+	ffmpegPath, ferr := resolveLocalExecutable(s.cfg.App.FFmpegPath, "ffmpeg")
+	ffprobePath, perr := resolveLocalExecutable(s.cfg.App.FFprobePath, "ffprobe")
+	out["ffmpeg"] = ffToolInfo{Installed: ferr == nil, Path: ffmpegPath, Version: ffToolVersion(ffmpegPath)}
+	out["ffprobe"] = ffToolInfo{Installed: perr == nil, Path: ffprobePath, Version: ffToolVersion(ffprobePath)}
+	return out
+}
+
+// StartInstall 启动后台安装（幂等）。正在安装时返回错误；data 目录已有完整
+// 工具时直接应用路径设置并返回（无需重新下载）。
+func (s *FFmpegToolsService) StartInstall(ctx context.Context) error {
+	s.mu.Lock()
+	if s.running {
+		s.mu.Unlock()
+		return errors.New("工具正在安装中，请稍候")
+	}
+	if ffmpeg, ffprobe := s.installedBinaries(); ffmpeg != "" && ffprobe != "" {
+		s.mu.Unlock()
+		s.setMessage("检测到已安装，直接应用配置")
+		if err := s.applyInstalledPaths(ctx, ffmpeg, ffprobe); err != nil {
+			return err
+		}
+		return nil
+	}
+	s.running = true
+	s.errMsg = ""
+	s.started = time.Now()
+	s.mu.Unlock()
+
+	s.setMessage("准备下载…")
+	go s.runInstall()
+	return nil
+}
+
+// runInstall 在后台执行下载、解压、验证与配置落盘。
+func (s *FFmpegToolsService) runInstall() {
+	defer func() {
+		s.mu.Lock()
+		s.running = false
+		s.done = time.Now()
+		s.mu.Unlock()
+	}()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
+	defer cancel()
+
+	ffmpegPath, ffprobePath, err := installFFmpegTools(ctx, s.log, s.cfg, s.setMessage)
+	if err != nil {
+		s.mu.Lock()
+		s.errMsg = err.Error()
+		s.msg = "安装失败"
+		s.mu.Unlock()
+		s.log.Error("ffmpeg 工具安装失败", zap.Error(err))
+		return
+	}
+	if err := s.applyInstalledPaths(ctx, ffmpegPath, ffprobePath); err != nil {
+		s.mu.Lock()
+		s.errMsg = "安装完成，但写入设置失败：" + err.Error()
+		s.msg = "安装完成，设置写入失败"
+		s.mu.Unlock()
+		s.log.Error("写入 ffmpeg 工具路径设置失败", zap.Error(err))
+		return
+	}
+	s.setMessage("安装完成")
+	s.log.Info("ffmpeg 工具安装完成",
+		zap.String("ffmpeg", ffmpegPath), zap.String("ffprobe", ffprobePath))
+}
+
+// applyInstalledPaths 把安装后的路径写入设置表并热应用到运行配置。
+func (s *FFmpegToolsService) applyInstalledPaths(ctx context.Context, ffmpeg, ffprobe string) error {
+	if s.repo != nil && s.repo.Setting != nil {
+		if err := s.repo.Setting.Set(ctx, "ffmpeg.path", ffmpeg); err != nil {
+			return err
+		}
+		if err := s.repo.Setting.Set(ctx, "ffprobe.path", ffprobe); err != nil {
+			return err
+		}
+	}
+	ApplyRuntimeSetting(s.cfg, "ffmpeg.path", ffmpeg)
+	ApplyRuntimeSetting(s.cfg, "ffprobe.path", ffprobe)
+	return nil
+}
+
+func (s *FFmpegToolsService) setMessage(msg string) {
+	s.mu.Lock()
+	s.msg = msg
+	s.mu.Unlock()
+}
@@ -0,0 +1,80 @@
+package service
+
+import (
+	"context"
+	"runtime"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+)
+
+func TestFFmpegTargetForPlatform(t *testing.T) {
+	target, err := ffmpegTargetForPlatform()
+	switch runtime.GOOS {
+	case "windows", "linux", "darwin":
+		if err != nil {
+			t.Fatalf("supported platform %s/%s should resolve a target: %v", runtime.GOOS, runtime.GOARCH, err)
+		}
+		if target == nil || target.Label == "" || len(target.Archives) == 0 {
+			t.Fatalf("target incomplete: %#v", target)
+		}
+		if target.Kind != "zip" && target.Kind != "tar.xz" {
+			t.Fatalf("unexpected archive kind: %s", target.Kind)
+		}
+		for _, u := range target.Archives {
+			if !strings.HasPrefix(u, "https://") {
+				t.Fatalf("archive url not https: %s", u)
+			}
+		}
+	default:
+		if err == nil {
+			t.Fatalf("unsupported platform %s/%s should fail", runtime.GOOS, runtime.GOARCH)
+		}
+	}
+}
+
+func TestSafeZipTargetRejectsTraversal(t *testing.T) {
+	root := t.TempDir()
+	for _, name := range []string{"../evil", "..\\evil", "/etc/passwd", "a/../../evil"} {
+		if _, err := safeZipTarget(root, name); err == nil {
+			t.Fatalf("expected traversal rejection for %q", name)
+		}
+	}
+	if _, err := safeZipTarget(root, "bin/ffmpeg.exe"); err != nil {
+		t.Fatalf("valid relative path should pass: %v", err)
+	}
+}
+
+func TestFFmpegToolsStatusNoPanic(t *testing.T) {
+	svc := NewFFmpegToolsService(&config.Config{}, zap.NewNop(), nil)
+	st := svc.Status(context.Background())
+	for _, key := range []string{"installing", "message", "error", "install_dir", "target", "ffmpeg", "ffprobe"} {
+		if _, ok := st[key]; !ok {
+			t.Fatalf("status missing key %q: %#v", key, st)
+		}
+	}
+	ffmpeg, ok := st["ffmpeg"].(ffToolInfo)
+	if !ok {
+		t.Fatalf("ffmpeg field not ffToolInfo: %T", st["ffmpeg"])
+	}
+	if ffmpeg.Installed {
+		t.Fatalf("empty config should not report installed ffmpeg: %#v", st)
+	}
+}
+
+func TestStartInstallRejectsConcurrent(t *testing.T) {
+	svc := NewFFmpegToolsService(&config.Config{App: config.AppConfig{DataDir: t.TempDir()}}, zap.NewNop(), nil)
+	// 不真实运行：直接占用 running 标记模拟进行中的安装。
+	svc.mu.Lock()
+	svc.running = true
+	svc.mu.Unlock()
+	if err := svc.StartInstall(context.Background()); err == nil {
+		t.Fatalf("second install while running should be rejected")
+	}
+	svc.mu.Lock()
+	svc.running = false
+	svc.mu.Unlock()
+}
@@ -50,11 +50,11 @@ func TestResolveSSLMaterial(t *testing.T) {
 	}

 	cases := []struct {
-		name   string
+		name    string
 		content string
-		path   string
-		want   string
-		err    bool
+		path    string
+		want    string
+		err     bool
 	}{
 		{name: "content only", content: certPEM, want: certPEM},
 		{name: "path only", path: path, want: certPEM},
@@ -84,3 +84,12 @@ func (p *ImageProxy) libraryRoots() []string {
 	p.libRootsAt = time.Now()
 	return p.libRootsCache
 }
+
+// Prune removes oldest cached images until disk usage is within the configured limit.
+func (p *ImageProxy) Prune() (PruneImageCacheResult, error) {
+	if p.cfg == nil || p.cfg.Cache.ImagesMaxSizeMB <= 0 {
+		return PruneImageCacheResult{}, nil
+	}
+	maxBytes := int64(p.cfg.Cache.ImagesMaxSizeMB) * 1024 * 1024
+	return PruneImageCache(p.cacheDir, maxBytes)
+}
@@ -179,9 +179,9 @@ func TestManualSearchFallsBackToMovieFolderForGenericQuery(t *testing.T) {
 	if len(results) != 1 || results[0].TMDbID != 27205 {
 		t.Fatalf("manual search results=%#v, want folder fallback candidate; queries=%v", results, queries)
 	}
-		if len(queries) < 2 || queries[0] != "00000" || queries[len(queries)-1] != "inception" {
-			t.Fatalf("manual search queries=%v, want explicit query then folder fallback", queries)
-		}
+	if len(queries) < 2 || queries[0] != "00000" || queries[len(queries)-1] != "inception" {
+		t.Fatalf("manual search queries=%v, want explicit query then folder fallback", queries)
+	}
 }

 func TestManualSearchReturnsMovieFallbackForTVTypedTMDbSearch(t *testing.T) {
@@ -34,6 +34,40 @@ func (s *MediaService) mediaListCacheKey(libraryID string, libraryIDs []string,
 	return "media:list:" + hex.EncodeToString(sum[:])
 }

+func (s *MediaService) libraryPreviewCacheKey(libraries []model.Library, cardLimit int, filter repository.MediaQueryFilter) string {
+	libIDs := make([]string, len(libraries))
+	for i, lib := range libraries {
+		libIDs[i] = lib.ID
+	}
+	sort.Strings(libIDs)
+	allowed := append([]string(nil), filter.AllowedLibraryIDs...)
+	hidden := append([]string(nil), filter.HiddenLibraryIDs...)
+	sort.Strings(allowed)
+	sort.Strings(hidden)
+	sum := sha1.Sum([]byte(strings.Join([]string{
+		"preview",
+		strings.Join(libIDs, ","),
+		fmt.Sprintf("%d:%t", cardLimit, filter.IncludeNSFW),
+		strings.Join(allowed, ","),
+		strings.Join(hidden, ","),
+	}, "|")))
+	return "media:preview:" + hex.EncodeToString(sum[:])
+}
+
+func (s *MediaService) seriesCardsCacheKey(libraryID string, visibility MediaVisibility) string {
+	allowed := append([]string(nil), visibility.AllowedLibraryIDs...)
+	hidden := append([]string(nil), visibility.HiddenLibraryIDs...)
+	sort.Strings(allowed)
+	sort.Strings(hidden)
+	sum := sha1.Sum([]byte(strings.Join([]string{
+		libraryID,
+		fmt.Sprintf("%t", visibility.IncludeNSFW),
+		strings.Join(allowed, ","),
+		strings.Join(hidden, ","),
+	}, "|")))
+	return "media:series-cards:" + hex.EncodeToString(sum[:])
+}
+
 func (s *MediaService) mediaCacheTTLSeconds() int {
 	if s == nil || s.cfg == nil || s.cfg.Cache.MediaTTLSeconds < 1 {
 		return 15
@@ -2,16 +2,121 @@ package service

 import (
 	"context"
+	"time"

 	"github.com/ShukeBta/MMTL/internal/model"
+	"github.com/ShukeBta/MMTL/internal/repository"
 	"gorm.io/gorm"
 )

+type LibraryPreviewItem struct {
+	model.Library
+	Total int64        `json:"total"`
+	Cards []SeriesCard `json:"cards"`
+}
+
+type libraryPreviewCacheValue struct {
+	Items []LibraryPreviewItem `json:"items"`
+}
+
 // ListLibraries returns every library configured on the server.
 func (s *MediaService) ListLibraries(ctx context.Context) ([]model.Library, error) {
 	return s.repo.Library.List(ctx)
 }

+// ListLibrariesWithPreview returns libraries populated with item counts and latest preview cards.
+func (s *MediaService) ListLibrariesWithPreview(ctx context.Context, libraries []model.Library, visibility MediaVisibility, cardLimit int) ([]LibraryPreviewItem, error) {
+	if cardLimit <= 0 {
+		cardLimit = 10
+	}
+	out := make([]LibraryPreviewItem, len(libraries))
+	if len(libraries) == 0 {
+		return out, nil
+	}
+
+	visibility = ExpandMediaVisibilityForMergedCloudLibraries(ctx, s.repo, visibility)
+	filter := repository.MediaQueryFilter{
+		IncludeNSFW:       visibility.IncludeNSFW,
+		AllowedLibraryIDs: visibility.AllowedLibraryIDs,
+		HiddenLibraryIDs:  visibility.HiddenLibraryIDs,
+	}
+	cacheKey := s.libraryPreviewCacheKey(libraries, cardLimit, filter)
+	var cached libraryPreviewCacheValue
+	if s.cache != nil && s.cache.GetJSON(ctx, cacheKey, &cached) {
+		return cached.Items, nil
+	}
+
+	libIDs := make([]string, 0, len(libraries))
+	for i, lib := range libraries {
+		out[i] = LibraryPreviewItem{
+			Library: lib,
+			Total:   0,
+			Cards:   []SeriesCard{},
+		}
+		libIDs = append(libIDs, lib.ID)
+	}
+
+	counts, err := s.repo.Media.CountByLibraries(ctx, libIDs, filter)
+	if err != nil {
+		return nil, err
+	}
+
+	for i := range out {
+		if total, ok := counts[out[i].ID]; ok {
+			out[i].Total = total
+		}
+	}
+
+	fetchCount := cardLimit * 4
+	if fetchCount < 60 {
+		fetchCount = 60
+	} else if fetchCount > 200 {
+		fetchCount = 200
+	}
+
+	recentByLibrary, err := s.repo.Media.ListRecentByLibraries(ctx, libIDs, fetchCount, filter)
+	if err != nil {
+		return nil, err
+	}
+
+	allPreviewItems := make([]model.Media, 0, len(libIDs)*fetchCount)
+	for i := range out {
+		if out[i].Total == 0 {
+			continue
+		}
+		items := recentByLibrary[out[i].ID]
+		if len(items) == 0 {
+			continue
+		}
+		allPreviewItems = append(allPreviewItems, items...)
+	}
+	s.attachLibraryMetadata(ctx, allPreviewItems)
+
+	for i := range out {
+		if out[i].Total == 0 {
+			continue
+		}
+		items := recentByLibrary[out[i].ID]
+		if len(items) == 0 {
+			continue
+		}
+		cards := groupMediaSeriesCards(items)
+		if len(cards) > cardLimit {
+			cards = cards[:cardLimit]
+		}
+		if cards == nil {
+			cards = []SeriesCard{}
+		}
+		out[i].Cards = cards
+	}
+
+	if s.cache != nil {
+		s.cache.SetJSON(ctx, cacheKey, libraryPreviewCacheValue{Items: out}, time.Duration(s.mediaCacheTTLSeconds())*time.Second)
+	}
+
+	return out, nil
+}
+
 // DeleteLibrary removes a library and its media rows. The on-disk files are
 // left untouched.
 func (s *MediaService) DeleteLibrary(ctx context.Context, id string) error {
@@ -43,10 +148,10 @@ func (s *MediaService) DeleteLibrary(ctx context.Context, id string) error {
 		if err := tx.Unscoped().Where("library_id = ?", id).Delete(&model.Media{}).Error; err != nil {
 			return err
 		}
-			if err := hardDeleteLibraryRoots(ctx, tx, id); err != nil {
-				return err
-			}
-			return tx.Unscoped().Delete(&model.Library{}, "id = ?", id).Error
+		if err := hardDeleteLibraryRoots(ctx, tx, id); err != nil {
+			return err
+		}
+		return tx.Unscoped().Delete(&model.Library{}, "id = ?", id).Error
 	})
 	if err == nil {
 		s.invalidateMediaCache(ctx)
@@ -0,0 +1,94 @@
+package service
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/ShukeBta/MMTL/internal/config"
+	"github.com/ShukeBta/MMTL/internal/model"
+	"github.com/ShukeBta/MMTL/internal/repository"
+)
+
+func TestListLibrariesWithPreview(t *testing.T) {
+	db := newServiceTestDB(t, &model.Library{}, &model.Media{})
+	repos := repository.New(db)
+
+	lib1 := model.Library{Name: "电影", Path: "/media/movies", Type: "movie", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib1); err != nil {
+		t.Fatal(err)
+	}
+	lib2 := model.Library{Name: "动漫", Path: "/media/anime", Type: "anime", Enabled: true}
+	if err := repos.Library.Create(t.Context(), &lib2); err != nil {
+		t.Fatal(err)
+	}
+
+	now := time.Date(2026, 7, 2, 12, 0, 0, 0, time.UTC)
+	var rows []model.Media
+
+	// Add 5 movies to lib1
+	for i := 1; i <= 5; i++ {
+		rows = append(rows, model.Media{
+			Base:      model.Base{ID: fmt.Sprintf("movie-%02d", i), CreatedAt: now.Add(time.Duration(i) * time.Hour)},
+			LibraryID: lib1.ID,
+			Title:     fmt.Sprintf("电影%d", i),
+			Path:      fmt.Sprintf("/media/movies/电影%d/movie%d.mp4", i, i),
+			PosterURL: fmt.Sprintf("/api/media/movie-%02d/poster", i),
+		})
+	}
+
+	// Add 12 episodes of 1 anime to lib2
+	for i := 1; i <= 12; i++ {
+		rows = append(rows, model.Media{
+			Base:       model.Base{ID: fmt.Sprintf("anime-ep-%02d", i), CreatedAt: now.Add(time.Duration(i) * time.Minute)},
+			LibraryID:  lib2.ID,
+			Title:      fmt.Sprintf("某动漫 第%d集", i),
+			Path:       fmt.Sprintf("/media/anime/某动漫/Season 01/某动漫.S01E%02d.mp4", i),
+			SeasonNum:  1,
+			EpisodeNum: i,
+			PosterURL:  "/api/media/anime-01/poster",
+		})
+	}
+
+	if err := repos.DB.Create(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	svc := NewMediaService(&config.Config{}, zap.NewNop(), repos)
+
+	previews, err := svc.ListLibrariesWithPreview(t.Context(), []model.Library{lib1, lib2}, MediaVisibility{IncludeNSFW: true}, 10)
+	if err != nil {
+		t.Fatalf("ListLibrariesWithPreview failed: %v", err)
+	}
+
+	if len(previews) != 2 {
+		t.Fatalf("got %d previews, want 2", len(previews))
+	}
+
+	// Verify lib1 (movies)
+	if previews[0].ID != lib1.ID {
+		t.Errorf("preview[0].ID = %q, want %q", previews[0].ID, lib1.ID)
+	}
+	if previews[0].Total != 5 {
+		t.Errorf("preview[0].Total = %d, want 5", previews[0].Total)
+	}
+	if len(previews[0].Cards) != 5 {
+		t.Errorf("preview[0].Cards count = %d, want 5", len(previews[0].Cards))
+	}
+
+	// Verify lib2 (anime)
+	if previews[1].ID != lib2.ID {
+		t.Errorf("preview[1].ID = %q, want %q", previews[1].ID, lib2.ID)
+	}
+	if previews[1].Total != 12 {
+		t.Errorf("preview[1].Total = %d, want 12", previews[1].Total)
+	}
+	// 12 episodes should be grouped into 1 SeriesCard with Count = 12
+	if len(previews[1].Cards) != 1 {
+		t.Errorf("preview[1].Cards count = %d, want 1", len(previews[1].Cards))
+	} else if previews[1].Cards[0].Count != 12 {
+		t.Errorf("preview[1].Cards[0].Count = %d, want 12", previews[1].Cards[0].Count)
+	}
+}
@@ -2,6 +2,8 @@ package service

 import (
 	"context"
+	"errors"
+	"path/filepath"
 	"regexp"
 	"sort"
 	"strings"
@@ -10,6 +12,11 @@ import (
 	"github.com/ShukeBta/MMTL/internal/model"
 )

+type seriesCardsCacheValue struct {
+	Cards []SeriesCard `json:"cards"`
+	Total int64        `json:"total"`
+}
+
 type SeriesCard struct {
 	Key       string      `json:"key"`
 	Rep       model.Media `json:"rep"`
@@ -23,12 +30,25 @@ type seriesCardGroup struct {
 }

 func (s *MediaService) ListLibrarySeriesCards(ctx context.Context, libraryID string, visibility MediaVisibility) ([]SeriesCard, int64, error) {
+	visibility = ExpandMediaVisibilityForMergedCloudLibraries(ctx, s.repo, visibility)
+	cacheKey := s.seriesCardsCacheKey(libraryID, visibility)
+	var cached seriesCardsCacheValue
+	if s.cache != nil && s.cache.GetJSON(ctx, cacheKey, &cached) {
+		return cached.Cards, cached.Total, nil
+	}
 	rows, _, err := s.listAllMediaVisible(ctx, libraryID, visibility)
 	if err != nil {
 		return nil, 0, err
 	}
 	cards := groupMediaSeriesCards(rows)
-	return cards, int64(len(cards)), nil
+	if cards == nil {
+		cards = []SeriesCard{}
+	}
+	total := int64(len(cards))
+	if s.cache != nil {
+		s.cache.SetJSON(ctx, cacheKey, seriesCardsCacheValue{Cards: cards, Total: total}, time.Duration(s.mediaCacheTTLSeconds())*time.Second)
+	}
+	return cards, total, nil
 }

 func (s *MediaService) ListRecentSeriesCards(ctx context.Context, limit int, visibility MediaVisibility) ([]SeriesCard, error) {
@@ -75,6 +95,74 @@ func (s *MediaService) ListLibrarySeriesEpisodes(ctx context.Context, libraryID,
 	return out, nil
 }

+func (s *MediaService) ListMediaEpisodes(ctx context.Context, mediaID string, visibility MediaVisibility) ([]model.Media, error) {
+	target, err := s.repo.Media.FindByID(ctx, mediaID)
+	if err != nil {
+		return nil, err
+	}
+	if target == nil {
+		return nil, errors.New("media not found")
+	}
+	if !visibility.Allows(target) {
+		return nil, errors.New("media not found")
+	}
+	if target.LibraryID == "" {
+		return []model.Media{*target}, nil
+	}
+	rows, _, err := s.listAllMediaVisible(ctx, target.LibraryID, visibility)
+	if err != nil {
+		return nil, err
+	}
+	if len(rows) == 0 {
+		return []model.Media{*target}, nil
+	}
+
+	resolver := newMediaSeriesKeyResolver(rows)
+	targetKey := resolver.key(*target)
+
+	out := make([]model.Media, 0)
+	if targetKey != "" {
+		for _, row := range rows {
+			if resolver.key(row) == targetKey {
+				out = append(out, row)
+			}
+		}
+	}
+
+	// 如果没有聚合到多集，尝试同父目录匹配
+	if len(out) <= 1 && target.Path != "" {
+		targetDir := filepath.Dir(strings.ReplaceAll(target.Path, "\\", "/"))
+		dirMatches := make([]model.Media, 0)
+		for _, row := range rows {
+			if row.Path != "" && filepath.Dir(strings.ReplaceAll(row.Path, "\\", "/")) == targetDir {
+				dirMatches = append(dirMatches, row)
+			}
+		}
+		if len(dirMatches) > 1 {
+			out = dirMatches
+		}
+	}
+
+	if len(out) == 0 {
+		out = []model.Media{*target}
+	}
+
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].SeasonNum != out[j].SeasonNum {
+			return out[i].SeasonNum < out[j].SeasonNum
+		}
+		if out[i].EpisodeNum != out[j].EpisodeNum {
+			return out[i].EpisodeNum < out[j].EpisodeNum
+		}
+		if out[i].Path != out[j].Path {
+			return out[i].Path < out[j].Path
+		}
+		return out[i].CreatedAt.Before(out[j].CreatedAt)
+	})
+
+	return out, nil
+}
+
 func (s *MediaService) listAllMediaVisible(ctx context.Context, libraryID string, visibility MediaVisibility) ([]model.Media, int64, error) {
 	const pageSize = 2000
 	var all []model.Media
@@ -229,9 +229,9 @@ func (o *OrganizerService) replaceVersions(ctx context.Context, src string, exis
 			o.log.Warn("organize replace remove existing failed",
 				zap.String("path", e), zap.Error(err))
 		}
-			if o.repo != nil && o.repo.DB != nil {
-				_ = o.repo.DB.WithContext(ctx).Unscoped().Where("path = ?", e).Delete(&model.Media{}).Error
-			}
+		if o.repo != nil && o.repo.DB != nil {
+			_ = o.repo.DB.WithContext(ctx).Unscoped().Where("path = ?", e).Delete(&model.Media{}).Error
+		}
 	}
 	// Move staged file + sidecars into the final path.
 	if err := os.Rename(stage, dst); err != nil {
@@ -19,8 +19,9 @@ import (

 // PlaybackService bundles history / favourite / playlist business logic.
 type PlaybackService struct {
-	log  *zap.Logger
-	repo *repository.Container
+	log    *zap.Logger
+	repo   *repository.Container
+	remote *EmbyRemoteService
 }

 // NewPlaybackService is the constructor.
@@ -28,6 +29,14 @@ func NewPlaybackService(log *zap.Logger, repo *repository.Container) *PlaybackSe
 	return &PlaybackService{log: log, repo: repo}
 }

+// SetEmbyRemote wires the remote Emby service for hydrating mounted remote items.
+func (p *PlaybackService) SetEmbyRemote(remote *EmbyRemoteService) *PlaybackService {
+	if p != nil {
+		p.remote = remote
+	}
+	return p
+}
+
 // ─── History ────────────────────────────────────────────────────────────────

 // RecordProgress upserts the resume position for a (user, media) pair. A
@@ -84,9 +93,19 @@ func (p *PlaybackService) RecentHistory(ctx context.Context, userID string, limi
 		if m, ok := mediaByID[rows[i].MediaID]; ok {
 			media := m
 			items = append(items, HistoryItem{PlaybackHistory: rows[i], Media: &media})
-		} else {
-			items = append(items, HistoryItem{PlaybackHistory: rows[i]})
+			continue
 		}
+		if p.remote != nil && IsEmbyRemoteID(rows[i].MediaID) {
+			mountID, remoteID, _ := DecodeEmbyRemoteID(rows[i].MediaID)
+			if mount, acct, _ := p.remote.ResolveMount(ctx, mountID); mount != nil && acct != nil {
+				if rm, err := p.remote.RemoteMediaDetail(ctx, mount, acct, remoteID); err == nil && rm != nil {
+					media := *rm
+					items = append(items, HistoryItem{PlaybackHistory: rows[i], Media: &media})
+					continue
+				}
+			}
+		}
+		items = append(items, HistoryItem{PlaybackHistory: rows[i]})
 	}
 	return items, nil
 }
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
github-actions[bot]	0b1fe52e24	chore: bump version to 0.0.70 [skip ci]	2026-09-02 02:49:11 +00:00
truewhile	2fc2c17b05	fix: prevent mobile sidebar nav items from stacking on short screens (#7 ) Narrow drawers rendered media links in a flex-1 overflow region above a non-shrinking admin block, so the browse items were clipped into a compressed active pill. Scroll media and admin together, and distinguish /libraries from /libraries?from=admin when highlighting. Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 10:48:58 +08:00
github-actions[bot]	be96acb035	chore: bump version to 0.0.69 [skip ci]	2026-09-02 02:44:26 +00:00
truewhile	6a72e7ab82	Merge pull request #6 from truewhile/cursor/frontend-nav-mobile-af8f Improve mobile navigation and fix playlists page routing	2026-09-02 10:44:10 +08:00
Cursor Agent	4ebd477ca2	Fix playlists route matching /play and improve playlists page UI - Add isPlayerRoute() so /playlists no longer hides header and bottom nav - Add mobile back navigation for playlists, favourites, and history - Redesign PlaylistsPage with PageHeader, empty state, and card list Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 02:30:14 +00:00
github-actions[bot]	0320d956ed	chore: bump version to 0.0.68 [skip ci]	2026-09-02 02:23:41 +00:00
truewhile	95395c479a	优化前端返回导航与移动端操作体验优化前端返回导航与移动端操作体验	2026-09-02 10:23:30 +08:00
Cursor Agent	eba7904c99	Improve frontend navigation and mobile UX - Add mobile bottom tab bar for media browsing (Home, Libraries, Favourites, Playlists, More) - Split mobile drawer: media links first, admin links under a Management section - Show contextual back button in mobile header for deep routes - Add reusable PageBackButton and PageHeader components - Add back navigation to playlist detail, library page, and missing media state - Embed queue panels in TaskQueuePage to avoid duplicate page titles - Expose theme toggle in user menu on small screens Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 02:19:25 +00:00
github-actions[bot]	1171fe9464	chore: bump version to 0.0.67 [skip ci]	2026-09-02 02:09:43 +00:00
truewhile	06b96102c8	Merge pull request #4 from truewhile/cursor/rewrite-readme-af8f 更新 README 与 Docker 镜像为 truewhile 仓库	2026-09-02 10:09:31 +08:00
Cursor Agent	077458df31	Update Docker images to ghcr.io/truewhile/mmtl Replace legacy shukebta/shukbet image references across all compose templates, system update defaults, and security docs. Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 01:59:48 +00:00
github-actions[bot]	9124c9be9c	chore: bump version to 0.0.66 [skip ci]	2026-09-02 01:56:22 +00:00
truewhile	3ae3c6540d	重写 README：更新 fork 说明与当前项目描述重写 README：更新 fork 说明与当前项目描述	2026-09-02 09:56:06 +08:00
Cursor Agent	313ebdd402	Rewrite README for truewhile fork and current feature set - Clarify fork lineage from MediaStationGo - Document current capabilities: Emby mounts, STRM queues, task queue, etc. - Add acknowledgements for MediaStationGo and qmediasync - Update repo/image URLs to truewhile/MMTL - Streamline deployment docs while keeping essential guidance Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 01:53:59 +00:00
github-actions[bot]	db52792ada	chore: bump version to 0.0.65 [skip ci]	2026-09-02 01:49:22 +00:00
truewhile	a8065680bb	优化首页/媒体库加载速度与 SQLite 查询性能优化首页/媒体库加载速度与 SQLite 查询性能	2026-09-02 09:49:07 +08:00
Cursor Agent	3304f09b1d	Fix Auto Docker workflow failing on pull requests The publish workflow bumps VERSION, pushes commits/tags, and publishes images. It must not run on pull_request events where checkout is a detached HEAD and git push fails. PR validation is already covered by ci.yml. Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 01:45:32 +00:00
Cursor Agent	ba621cfc4a	Optimize home/library loading and SQLite query performance - Replace home preview N+1 queries with a single window-function batch query - Cache library previews and series card lists (15s TTL, shared with media cache) - Tune SQLite: larger page cache, mmap, wal_autocheckpoint, ANALYZE on migrate - Defer history fetch on library page until last_played sort is selected - Yield to browser between paginated library loads to keep UI responsive Co-authored-by: truewhile <truewhile@users.noreply.github.com>	2026-09-02 01:39:28 +00:00
github-actions[bot]	deca7735a7	chore: bump version to 0.0.64 [skip ci]	2026-09-01 15:16:32 +00:00
truewhile	b503fdee7a	优化续播	2026-09-01 23:16:11 +08:00
github-actions[bot]	3fe37e050b	chore: bump version to 0.0.63 [skip ci]	2026-09-01 14:43:48 +00:00
truewhile	d3233a62c0	优化	2026-09-01 22:43:30 +08:00
github-actions[bot]	165eee7b36	chore: bump version to 0.0.62 [skip ci]	2026-09-01 13:25:14 +00:00
truewhile	78526afc9c	优化	2026-09-01 21:24:55 +08:00
github-actions[bot]	f534e0607a	chore: bump version to 0.0.61 [skip ci]	2026-09-01 10:55:32 +00:00
truewhile	db64a6c093	优化	2026-09-01 18:55:05 +08:00
github-actions[bot]	5c9e7fcaa6	chore: bump version to 0.0.60 [skip ci]	2026-09-01 08:26:41 +00:00
truewhile	af67f4cd6e	优化	2026-09-01 16:26:25 +08:00
github-actions[bot]	73de139d1f	chore: bump version to 0.0.59 [skip ci]	2026-09-01 06:33:57 +00:00
truewhile	e0cc481b96	Merge pull request #1 from truewhile/beta 添加emby挂载功能，整合上传，下载，刮削队列到任务队列	2026-09-01 14:33:38 +08:00
truewhile	7ac75ec69a	fix: 修复 beta CI 失败的两个平台/网络敏感测试 - TestSanitizePathWithSpecialChars：Windows 盘符断言按 runtime.GOOS 分支（Linux 下反斜杠统一为分隔符，期望 D/test/...） - TestEnrichOneAdultScrapesArtwork：AdultProvider 改用 RoundTripper 全量 mock，拦截所有外网请求（CI 环境可达 javdb/dmm 时会把真实封面写入断言导致失败）；断言放宽为封面路径后缀	2026-09-01 14:22:52 +08:00
truewhile	0e73e43cbd	ci: 新增 beta 分支自动构建流水线 - 触发：push beta / PR 到 beta / 手动触发 - test-and-build：SPA 构建 + go vet/test/build + 三平台交叉编译（linux/amd64、linux/arm64、windows/amd64），版本号为 {VERSION}-beta.{sha}，二进制上传为 artifact - docker-beta：多架构构建并推送 ghcr.io/{owner}/mmtl:beta （PR 事件不推镜像，仅推送 beta / 手动触发时推） - 与 main 的发布流隔离：不做版本递增、不打 release tag	2026-09-01 14:12:31 +08:00
truewhile	bd41ab3fb4	feat: 整合刮削/下载/上传队列为统一的「任务队列」 - 新增 /queue 任务队列页：全部 / 刮削 / 下载 / 上传类型 Tab（URL 参数 ?type= 同步），Tab 上实时显示各自任务计数徽章 - 「全部」视图纵向堆叠三类队列，单类视图直接复用原队列组件（ScraperQueuePage / StrmQueuePanel，后者已导出） - 侧边栏导航：删除「刮削队列 / 下载队列 / 上传队列」三个入口，合并为「任务队列」单一菜单项；旧路由 /scraper/queue、/strm/downloads、 /strm/uploads 保留直达	2026-09-01 14:02:25 +08:00
truewhile	73b95a8e38	feat: Emby 挂载独立管理（媒体库级选择挂载 + 每库代理开关） - 新增 EmbyMount 表与 /admin/emby/mounts CRUD：把远程 Emby 的媒体库按需挂载到本项目（同一服务器可选择性挂载/全量挂载），代理开关下沉到每个挂载（一个 Emby 服务器可部分库代理、部分库直连） - 伪装 ID 改为 embyremote~{mountID}~{remoteID}：播放/详情/状态/图片链路全部经 ResolveMount 解析挂载与账号 - 新增「Emby 挂载」独立菜单页（/emby-mount）：账号管理（添加/测试/编辑/ 删除）+ 挂载列表（代理切换/停用/取消）+ 选择挂载对话框（多选+全量） - STRM 管理页过滤 emby_remote 账号；账号表单移除 emby 类型 - Boot 幂等 AutoSeedMounts：旧 emby 账号自动全量挂载（沿用旧代理配置），升级后媒体库不消失 - 修复：远程流请求注入浏览器 UA（防 Cloudflare 风控）+ 代理强制 Static=true （阻止远程 ffmpeg 转码调度，反代纯字节中继） - 全局搜索改为按挂载逐个搜索（结果归属与伪装 ID 正确）	2026-09-01 13:53:15 +08:00
truewhile	5a5555d28a	fix: 远程 Emby 无图条目不再下发无效图片 URL（封面破图修复） - 远程条目仅当 ImageTags 含 Primary/Backdrop 时才生成图片 URL；无图条目 poster_url 为空，前端走 No Poster 优雅占位而非裂图 - 剧集海报回退使用 Emby 的 SeriesPrimaryImageTag（Fields=SeriesPrimaryImage），仅当系列真实有图时才回退，避免连环无效请求 - 列表/剧集接口带 SeriesPrimaryImage 字段	2026-09-01 13:26:57 +08:00
truewhile	4dc9cbe2e7	feat: 网页端完整浏览/播放远程 Emby 挂载库 - 后端新增远程库→本地结构映射（emby_remote_web.go）：Library/Media/SeriesCard 与本地完全同构，前端无感知 - /api/libraries（含 with_preview）、/api/libraries/:id、/api/libraries/:id/media、 /api/libraries/:id/series、/api/libraries/:id/series/episodes、/api/media/:id、 /api/media/:id/episodes 全部支持远程伪装 ID 透传映射 - /api/stream/:id 对远程条目 302 直连远程 Emby 原地址（播放不经过本机） - 库内容按 CollectionType 过滤（电影库取 Movie、剧集库取 Series）， RecursiveItemCount 作为系列集数；修复伪装 ID 双重编码导致的图片/详情 500 - SPA fallback 放行 /library/embyremote~ 前缀（不再被当作 Emby API 路由 404） - 前端：远程库/条目标记 is_remote_emby，隐藏扫描/刮削/编辑/NFO/回收站/ HLS 转码等不适用操作；后台管理面板过滤远程库	2026-09-01 11:32:54 +08:00
truewhile	6af0e5fdcf	fix: Emby 远程挂载播放地址强制下发 + 凭据状态显示修正 - PlaybackInfo 始终构造 DirectStreamUrl（远程 PlaybackInfo 默认不带该字段，此前客户端拿不到播放地址）：默认指向远程 Emby 原地址（不代理），开启代理时指向 MMTL /Videos/{encoded} 反代端点 - HasStrmAccountCredential 对 emby_remote 放宽为 url+用户名/密码即视为已配置（此前只认 api_key，导致列表误显示「凭据：未配置」）	2026-09-01 11:06:36 +08:00
truewhile	f0055b76fe	fix: Emby 远程挂载账号编辑保留凭据 + 代理开关回显 - UpdateStrmAccount 对 emby_remote 做合并式更新：只覆盖传入键，未提及的地址/用户名/密码/token 密文保留，避免编辑代理开关时清空凭据 - 账号列表/编辑表单回显 proxy_play（服务端解密后下发） - 前端 StrmAccount 类型与编辑对话框支持 proxy_play 回显	2026-09-01 10:45:52 +08:00
truewhile	0eb3f104f4	feat: Emby 远程挂载（联邦聚合）功能 beta - 新增 emby_remote 提供方：通过 STRM 账号体系配置远程 Emby 地址/用户名/密码 - EmbyService 聚合远程媒体库 Views/Items/详情/最近添加/全局搜索，远程数据不落库 - 条目 ID 统一伪装为 embyremote~{account}~{id}，请求按账号路由回远程 - 播放支持账号级 proxy_play 配置：默认客户端直连远程；开启后由 MMTL 反向代理流/字幕 - 图片/元数据全部实时透传远程，播放状态（已看/收藏）透传回远程 Emby - cloud 包新增 emby Provider（Ping/List/Resolve），账号测试/目录浏览自动生效 - 前端 STRM 页面支持 Emby 远程挂载账号（地址+凭据+代理开关）	2026-09-01 10:44:01 +08:00
github-actions[bot]	c171b38155	chore: bump version to 0.0.58 [skip ci]	2026-08-30 14:32:56 +00:00
truewhile	89d7a6cbb2	优化	2026-08-30 22:32:39 +08:00
github-actions[bot]	85918d1196	chore: bump version to 0.0.57 [skip ci]	2026-08-30 13:41:17 +00:00
truewhile	fa9307e2e1	优化	2026-08-30 21:40:58 +08:00
github-actions[bot]	5ab18c2725	chore: bump version to 0.0.56 [skip ci]	2026-08-30 12:05:41 +00:00
truewhile	a4a2bde1a4	优化	2026-08-30 20:05:27 +08:00
github-actions[bot]	28113f5fdc	chore: bump version to 0.0.55 [skip ci]	2026-08-30 10:50:29 +00:00
truewhile	42b8805e94	优化	2026-08-30 18:50:15 +08:00
github-actions[bot]	51a64f41b9	chore: bump version to 0.0.54 [skip ci]	2026-08-30 09:28:16 +00:00
truewhile	a7bd9a942c	优化显示	2026-08-30 17:28:00 +08:00
github-actions[bot]	97491a6175	chore: bump version to 0.0.53 [skip ci]	2026-08-29 14:16:40 +00:00
truewhile	ea5cb3a130	优化	2026-08-29 22:16:21 +08:00
github-actions[bot]	921010926b	chore: bump version to 0.0.52 [skip ci]	2026-08-28 14:38:24 +00:00
truewhile	7425c3d57b	优化	2026-08-28 22:38:09 +08:00
github-actions[bot]	1b7d4eef46	chore: bump version to 0.0.51 [skip ci]	2026-08-28 14:20:18 +00:00
truewhile	c30dab56a3	优化	2026-08-28 22:20:01 +08:00
github-actions[bot]	e365250440	chore: bump version to 0.0.50 [skip ci]	2026-08-28 10:28:29 +00:00
truewhile	47d10e1f58	优化	2026-08-28 18:28:09 +08:00
@@ -1 +1 @@
 .0.49
 .0.70