chore: bump version to 0.0.43 [skip ci]

优化上传逻辑

.github/workflows/Auto-docker-publish.yml

@@ -27,6 +27,9 @@ permissions:
 jobs:
   version-and-publish:
     runs-on: ubuntu-latest
+    outputs:
+      new_version: ${{ steps.bump_version.outputs.new_version }}
+      tag: ${{ steps.bump_version.outputs.tag }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -149,3 +152,117 @@ jobs:
             VERSION=${{ steps.bump_version.outputs.new_version }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
+
+  # 单文件可执行构建：把前端打包进二进制（go:embed），交叉编译 Windows /
+  # Linux / macOS 的 amd64 / arm64 产物，作为 GitHub Release 附件发布。
+  build-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: web/package-lock.json
+      - name: Install
+        working-directory: web
+        run: npm ci
+      - name: Build SPA
+        working-directory: web
+        run: npm run build
+      - name: Upload web/dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-dist
+          path: web/dist
+          retention-days: 1
+
+  # 先创建（幂等）空的 GitHub Release，供后续 build-binaries 并行上传附件，
+  # 也避免矩阵各 job 并发 upload 时 release 尚不存在而互相竞争。
+  publish-create-release:
+    needs: [version-and-publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ needs.version-and-publish.outputs.tag }}
+        run: |
+          set -eux
+          # tag 已由 version-and-publish 推送；若 release 已存在则忽略（--verify-tag 幂等）
+          gh release create "$RELEASE_TAG" \
+            --title "MMTL ${{ needs.version-and-publish.outputs.new_version }}" \
+            --notes "自动化发布 ${{ needs.version-and-publish.outputs.new_version }}" \
+            --verify-tag --latest || true
+
+  build-binaries:
+    needs: [version-and-publish, build-frontend, publish-create-release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            ext: ""
+          - goos: linux
+            goarch: arm64
+            ext: ""
+          - goos: windows
+            goarch: amd64
+            ext: .exe
+          - goos: windows
+            goarch: arm64
+            ext: .exe
+          - goos: darwin
+            goarch: amd64
+            ext: ""
+          - goos: darwin
+            goarch: arm64
+            ext: ""
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+      - name: Download web/dist
+        uses: actions/download-artifact@v4
+        with:
+          name: web-dist
+          path: web/dist
+      - name: Build binary
+        run: |
+          CGO_ENABLED=0 GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} \
+            go build -trimpath -ldflags="-s -w -X main.version=${{ needs.version-and-publish.outputs.tag }}" \
+            -o "dist/mmtl-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.ext }}" ./cmd/server
+      - name: Package
+        run: |
+          mkdir -p package/mmtl
+          cp "dist/mmtl-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.ext }}" package/mmtl/mmtl${{ matrix.ext }}
+          cp README.md package/mmtl/ 2>/dev/null || true
+          if [ "${{ matrix.goos }}" = "windows" ]; then
+            (cd package && zip -r "../mmtl_${{ matrix.goos }}_${{ matrix.goarch }}.zip" mmtl)
+          else
+            tar -czf "mmtl_${{ matrix.goos }}_${{ matrix.goarch }}.tar.gz" -C package mmtl
+          fi
+      - name: Upload to GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ needs.version-and-publish.outputs.tag }}
+        run: |
+          set -eux
+          PKG="mmtl_${{ matrix.goos }}_${{ matrix.goarch }}.zip"
+          TAR="mmtl_${{ matrix.goos }}_${{ matrix.goarch }}.tar.gz"
+          # 并发上传到同一 release 各自文件，--clobber 幂等覆盖
+          if [ -f "$PKG" ]; then
+            for i in 1 2 3; do gh release upload "$RELEASE_TAG" "$PKG" --clobber && break || sleep 5; done
+          fi
+          if [ -f "$TAR" ]; then
+            for i in 1 2 3; do gh release upload "$RELEASE_TAG" "$TAR" --clobber && break || sleep 5; done
+          fi

.github/workflows/ci.yml

@@ -18,6 +18,19 @@ jobs:
           go-version: '1.25'
           cache: true
 
+      # The binary embeds the SPA (web/dist) via go:embed, so the 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
+
       - name: go vet
         run: go vet ./...
 

README.md

@@ -360,15 +360,17 @@ docker compose -f docker-compose.search.yml up -d --no-deps mmtl
 
 本地开发需要 Go、Node.js 和 npm。
 
+后端会将 `web/dist` 通过 `go:embed` 编进二进制，因此**在编译 / 运行后端之前要先构建前端**，否则 `web` 包会因为缺少嵌入资源而编译失败。
+
 ```bash
+# 前端依赖与构建（必须先做，产物被 go:embed 打进二进制）
+npm --prefix web ci
+npm --prefix web run build
+
 # 后端测试
 go test ./...
 
-# 前端依赖与构建
-npm --prefix web install
-npm --prefix web run build
-
-# 本地运行后端
+# 本地运行后端（二进制自带前端界面，无需额外 web 目录）
 go run ./cmd/server
 
 # 本地运行前端开发服务器
@@ -387,6 +389,21 @@ http://127.0.0.1:3000
 http://127.0.0.1:8080/api/health
 ```
 
+### 交叉编译单文件发布物
+
+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)。

VERSION

@@ -1 +1 @@
-0.0.32
+0.0.43

cmd/server/main_test.go

@@ -52,7 +52,7 @@ func TestServeSPANoCachesIndexAndServesRoutes(t *testing.T) {
 	}
 
 	router := gin.New()
-	serveSPA(router, webDir)
+	serveSPA(router, os.DirFS(webDir))
 
 	for _, path := range []string{"/", "/login", "/library/e1c3507e-2878-40ae-a0e1-6b6e44b7fa7a", "/media/abc"} {
 		req := httptest.NewRequest(http.MethodGet, path, nil)
@@ -93,7 +93,7 @@ func TestServeSPAServesAssetsImmutableAndBypassesAPIRoutes(t *testing.T) {
 	}
 
 	router := gin.New()
-	serveSPA(router, webDir)
+	serveSPA(router, os.DirFS(webDir))
 
 	assetReq := httptest.NewRequest(http.MethodGet, "/assets/app.js", nil)
 	assetResp := httptest.NewRecorder()
@@ -155,7 +155,7 @@ func TestServeSPAServesAssetsImmutableAndBypassesAPIRoutes(t *testing.T) {
 func TestServeSPAMissingIndexReportsExplicit404(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	router := gin.New()
-	serveSPA(router, t.TempDir())
+	serveSPA(router, os.DirFS(t.TempDir()))
 
 	req := httptest.NewRequest(http.MethodGet, "/", nil)
 	w := httptest.NewRecorder()

cmd/server/router.go

@@ -1,6 +1,8 @@
 package main
 
 import (
+	"io/fs"
+	"mime"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -13,6 +15,8 @@ import (
 	"github.com/ShukeBta/MMTL/internal/handler"
 	"github.com/ShukeBta/MMTL/internal/middleware"
 	"github.com/ShukeBta/MMTL/internal/service"
+
+	"github.com/ShukeBta/MMTL/web"
 )
 
 func buildRouter(cfg *config.Config, logger *zap.Logger, svc *service.Container) *gin.Engine {
@@ -29,31 +33,41 @@ func buildRouter(cfg *config.Config, logger *zap.Logger, svc *service.Container)
 
 	handler.Register(r, cfg, logger, svc)
 
-	if cfg.App.WebDir != "" {
-		serveSPA(r, cfg.App.WebDir)
+	// Prefer a directory on disk when configured explicitly (e.g. the Docker image
+	// mounts web/dist from the build stage, or an operator overrides app.web_dir
+	// with a custom skin). Otherwise fall back to the SPA embedded into the binary,
+	// which is what makes the cross-platform single-file artifacts work.
+	uiFS := webui.DistFS()
+	if dir := cfg.App.WebDir; dir != "" {
+		disk := os.DirFS(dir)
+		if index, err := fs.Stat(disk, "index.html"); err == nil && !index.IsDir() {
+			uiFS = disk
+		}
 	}
+	serveSPA(r, uiFS)
 	return r
 }
 
 // serveSPA serves the React build artifacts and falls back to index.html for
-// non-API, non-asset paths so client-side routing keeps working.
-func serveSPA(r *gin.Engine, webDir string) {
+// non-API, non-asset paths so client-side routing keeps working. The UI tree
+// comes from root, which is either the compiled-in SPA or an on-disk web dir.
+func serveSPA(r *gin.Engine, root fs.FS) {
 	assets := r.Group("/assets")
 	assets.Use(func(c *gin.Context) {
 		c.Header("Cache-Control", "public, max-age=31536000, immutable")
 		c.Next()
 	})
-	assets.Static("/", filepath.Join(webDir, "assets"))
+	assets.GET("/*filepath", serveFSDir(root, "assets"))
 	brand := r.Group("/brand")
 	brand.Use(func(c *gin.Context) {
 		setNoCacheHeaders(c)
 		c.Next()
 	})
-	brand.Static("/", filepath.Join(webDir, "brand"))
+	brand.GET("/*filepath", serveFSDir(root, "brand"))
 	for _, rootFile := range []string{"/favicon.ico", "/favicon.svg", "/artwork-cache-sw.js"} {
-		filePath := filepath.Join(webDir, strings.TrimPrefix(rootFile, "/"))
-		r.GET(rootFile, serveNoCacheFile(filePath))
-		r.HEAD(rootFile, serveNoCacheFile(filePath))
+		name := strings.TrimPrefix(rootFile, "/")
+		r.GET(rootFile, serveFSFile(root, name))
+		r.HEAD(rootFile, serveFSFile(root, name))
 	}
 	r.NoRoute(func(c *gin.Context) {
 		path := c.Request.URL.Path
@@ -61,28 +75,50 @@ func serveSPA(r *gin.Engine, webDir string) {
 			c.Status(http.StatusNotFound)
 			return
 		}
-		serveSPAIndex(c, filepath.Join(webDir, "index.html"))
+		setNoCacheHeaders(c)
+		data, err := fs.ReadFile(root, "index.html")
+		if err != nil {
+			c.String(http.StatusNotFound, "MMTL web UI not found")
+			return
+		}
+		c.Data(http.StatusOK, "text/html; charset=utf-8", data)
 	})
 }
 
-func serveNoCacheFile(filePath string) gin.HandlerFunc {
+// serveFSDir serves a static subdirectory of root. A missing asset returns 404.
+func serveFSDir(root fs.FS, dir string) gin.HandlerFunc {
+	sub, err := fs.Sub(root, dir)
+	if err != nil {
+		return func(c *gin.Context) { c.Status(http.StatusNotFound) }
+	}
+	handler := http.StripPrefix("/"+dir, http.FileServerFS(sub))
 	return func(c *gin.Context) {
-		setNoCacheHeaders(c)
-		if _, err := os.Stat(filePath); err != nil {
-			c.Status(http.StatusNotFound)
-			return
-		}
-		c.File(filePath)
+		handler.ServeHTTP(c.Writer, c.Request)
 	}
 }
 
-func serveSPAIndex(c *gin.Context, indexPath string) {
-	setNoCacheHeaders(c)
-	if _, err := os.Stat(indexPath); err != nil {
-		c.String(http.StatusNotFound, "MMTL web UI not found: %s", indexPath)
-		return
+// serveFSFile serves a single root-level file (favicon / service worker) with
+// no-cache headers. It reads from root, which may be the embedded SPA or disk.
+func serveFSFile(root fs.FS, name string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		setNoCacheHeaders(c)
+		data, err := fs.ReadFile(root, name)
+		if err != nil {
+			c.Status(http.StatusNotFound)
+			return
+		}
+		c.Data(http.StatusOK, mimeTypeByName(name), data)
+	}
+}
+
+// mimeTypeByName returns an HTTP content type guessed from a file extension.
+func mimeTypeByName(name string) string {
+	switch mime.TypeByExtension(filepath.Ext(name)) {
+	case "":
+		return "application/octet-stream"
+	default:
+		return mime.TypeByExtension(filepath.Ext(name))
 	}
-	c.File(indexPath)
 }
 
 func setNoCacheHeaders(c *gin.Context) {

go.mod

@@ -3,6 +3,7 @@ module github.com/ShukeBta/MMTL
 go 1.25.0
 
 require (
+	github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.2
 	github.com/fsnotify/fsnotify v1.7.0
 	github.com/gin-gonic/gin v1.9.1
 	github.com/glebarez/sqlite v1.11.0
@@ -16,6 +17,7 @@ require (
 	go.uber.org/zap v1.27.0
 	golang.org/x/crypto v0.21.0
 	golang.org/x/sys v0.20.0
+	golang.org/x/time v0.15.0
 	gorm.io/driver/postgres v1.5.7
 	gorm.io/gorm v1.30.0
 )
@@ -72,7 +74,6 @@ require (
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
 	golang.org/x/net v0.21.0 // indirect
 	golang.org/x/text v0.20.0 // indirect
-	golang.org/x/time v0.15.0 // indirect
 	google.golang.org/protobuf v1.31.0 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -1,3 +1,5 @@
+github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.2 h1:40yUSXwdkWN851BHCq6uiDhleh7A4+0yIBS+IUAqZVY=
+github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.2/go.mod h1:FTzydeQVmR24FI0D6XWUOMKckjXehM/jgMn1xC+DA9M=
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
 github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
 github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=

internal/handler/media.go

@@ -16,12 +16,13 @@ import (
 )
 
 type createLibraryReq struct {
-	Name     string                     `json:"name" binding:"required"`
-	Path     string                     `json:"path"`
-	Paths    []string                   `json:"paths"`
-	Roots    []service.LibraryRootInput `json:"roots"`
-	Type     string                     `json:"type"`
-	CoverURL string                     `json:"cover_url"`
+	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"`
 }
 
 func listLibrariesHandler(svc *service.Container) gin.HandlerFunc {
@@ -88,9 +89,38 @@ func createLibraryHandler(svc *service.Container) gin.HandlerFunc {
 			}
 		}
 		if len(roots) == 0 && strings.TrimSpace(req.Path) != "" {
-			roots = append(roots, service.LibraryRootInput{Path: 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
 		}
-		l, err := svc.Media.CreateLibraryWithRootsAndCover(c.Request.Context(), req.Name, req.Type, req.CoverURL, roots)
+		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
+	}
+	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

internal/handler/routes_admin.go

@@ -43,6 +43,8 @@ func registerAdminStrmRoutes(admin *gin.RouterGroup, svc *service.Container) {
 	admin.POST("/strm/paths/:id/sync", startStrmSyncHandler(svc))
 	admin.POST("/strm/paths/:id/cancel", cancelStrmSyncHandler(svc))
 	admin.GET("/strm/records", listStrmSyncRecordsHandler(svc))
+	admin.DELETE("/strm/records/:id", deleteStrmSyncRecordHandler(svc))
+	admin.DELETE("/strm/records", clearStrmSyncRecordsHandler(svc))
 	admin.GET("/strm/local-dirs", listStrmLocalDirsHandler(svc))
 
 	admin.GET("/strm/downloads", downloadQueueHandler(svc))
@@ -50,12 +52,14 @@ func registerAdminStrmRoutes(admin *gin.RouterGroup, svc *service.Container) {
 	admin.POST("/strm/downloads/:id/retry", retryStrmDownloadHandler(svc))
 	admin.POST("/strm/downloads/clear-done", clearDoneDownloadsHandler(svc))
 	admin.POST("/strm/downloads/clear-finished", clearFinishedDownloadsHandler(svc))
+	admin.POST("/strm/downloads/clear-canceled", clearCanceledDownloadsHandler(svc))
 	admin.POST("/strm/downloads/retry-failed", retryAllFailedDownloadsHandler(svc))
 	admin.POST("/strm/downloads/cancel-pending", cancelPendingDownloadsHandler(svc))
 	admin.GET("/strm/uploads", uploadQueueHandler(svc))
 	admin.POST("/strm/uploads/:id/cancel", cancelStrmUploadHandler(svc))
 	admin.POST("/strm/uploads/:id/retry", retryStrmUploadHandler(svc))
 	admin.POST("/strm/uploads/cancel-pending", cancelPendingUploadsHandler(svc))
+	admin.POST("/strm/uploads/clear-canceled", clearCanceledUploadsHandler(svc))
 }
 
 func registerAdminUserRoutes(admin *gin.RouterGroup, svc *service.Container) {

internal/handler/strm.go

@@ -300,6 +300,31 @@ func listStrmSyncRecordsHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+func deleteStrmSyncRecordHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if c.Param("id") == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "缺少记录 ID"})
+			return
+		}
+		if err := svc.Strm.DeleteSyncRecord(c.Request.Context(), c.Param("id")); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true})
+	}
+}
+
+func clearStrmSyncRecordsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		deleted, err := svc.Strm.ClearSyncRecords(c.Request.Context(), c.Query("path_id"))
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"ok": true, "deleted": deleted})
+	}
+}
+
 // ─── 下载/上传队列 ─────────────────────────────────────────────────────────────
 
 func downloadQueueHandler(svc *service.Container) gin.HandlerFunc {
@@ -392,6 +417,28 @@ func clearFinishedDownloadsHandler(svc *service.Container) gin.HandlerFunc {
 	}
 }
 
+func clearCanceledDownloadsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		n, err := svc.Strm.ClearCanceledDownloadTasks(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 clearCanceledUploadsHandler(svc *service.Container) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		n, err := svc.Strm.ClearCanceledUploadTasks(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())

internal/handler/strm_routes_test.go

@@ -50,10 +50,16 @@ func TestStrmAdminRoutesAreRegistered(t *testing.T) {
 		"GET /api/admin/strm/downloads",
 		"POST /api/admin/strm/downloads/:id/cancel",
 		"POST /api/admin/strm/downloads/:id/retry",
-		"GET /api/admin/strm/uploads",
-		"POST /api/admin/strm/uploads/:id/cancel",
-		"POST /api/admin/strm/uploads/:id/retry",
-		"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/cancel-pending",
+			"POST /api/admin/strm/uploads/clear-canceled",
+			"GET /api/strm/play/:provider/:file",
 	} {
 		if !routes[want] {
 			t.Fatalf("%s route is not registered", want)

internal/handler/watch_history.go

@@ -163,7 +163,7 @@ func historyDeleteHandler(svc *service.Container) gin.HandlerFunc {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "status must be completed or incomplete"})
 			return
 		}
-		res := q.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

internal/repository/api_config_repository.go

@@ -62,9 +62,9 @@ func (r *ApiConfigRepository) Update(ctx context.Context, c *model.ApiConfig) er
 	}).Error
 }
 
-// Delete removes an API config.
+// Delete 物理删除 API 配置。
 func (r *ApiConfigRepository) Delete(ctx context.Context, provider string) error {
-	return r.db.WithContext(ctx).Where("provider = ?", provider).Delete(&model.ApiConfig{}).Error
+	return r.db.WithContext(ctx).Unscoped().Where("provider = ?", provider).Delete(&model.ApiConfig{}).Error
 }
 
 // UpdateTestResult 更新测试结果。

internal/repository/favorite_repository.go

@@ -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).Delete(&f).Error
+		return false, r.db.WithContext(ctx).Unscoped().Delete(&f).Error
 }
 
 // ListByUser returns all favourite media IDs for a user.

internal/repository/library_repository.go

@@ -79,10 +79,9 @@ func (r *LibraryRepository) FindByID(ctx context.Context, id string) (*model.Lib
 	return &l, nil
 }
 
-// Delete removes a library and (soft) cascades to its media via repository
-// callers; we do not run CASCADE here to keep this method narrow.
+// Delete 物理删除媒体库。
 func (r *LibraryRepository) Delete(ctx context.Context, id string) error {
-	return r.db.WithContext(ctx).Delete(&model.Library{}, "id = ?", id).Error
+	return r.db.WithContext(ctx).Unscoped().Delete(&model.Library{}, "id = ?", id).Error
 }
 
 func (r *LibraryRepository) ListRoots(ctx context.Context, libraryID string) ([]model.LibraryRoot, error) {
@@ -149,7 +148,7 @@ func (r *LibraryRepository) DeleteRoot(ctx context.Context, libraryID, rootID st
 	if !r.hasLibraryRootsTable() {
 		return nil
 	}
-	return r.db.WithContext(ctx).Where("library_id = ?", libraryID).Delete(&model.LibraryRoot{}, "id = ?", rootID).Error
+	return r.db.WithContext(ctx).Unscoped().Where("library_id = ?", libraryID).Delete(&model.LibraryRoot{}, "id = ?", rootID).Error
 }
 
 func (r *LibraryRepository) hasLibraryRootsTable() bool {

internal/repository/media_repository.go

@@ -116,12 +116,12 @@ func (r *MediaRepository) ListByLibrariesFiltered(ctx context.Context, libraryID
 
 // DeleteByLibrary purges all media tied to a library.
 func (r *MediaRepository) DeleteByLibrary(ctx context.Context, libraryID string) error {
-	// FTS 行由 media 表上的触发器同步清理（软删/硬删都覆盖）。
-	return r.db.WithContext(ctx).Where("library_id = ?", libraryID).Delete(&model.Media{}).Error
+	// FTS 行由 media 表上的触发器同步清理（物理删除触发 FTS 清理）。
+	return r.db.WithContext(ctx).Unscoped().Where("library_id = ?", libraryID).Delete(&model.Media{}).Error
 }
 
 func (r *MediaRepository) DeleteByLibraryRoot(ctx context.Context, libraryID, rootID string) error {
-	return r.db.WithContext(ctx).
+	return r.db.WithContext(ctx).Unscoped().
 		Where("library_id = ? AND library_root_id = ?", libraryID, rootID).
 		Delete(&model.Media{}).Error
 }

internal/repository/permission_repository.go

@@ -51,9 +51,9 @@ func (r *PermissionRepository) Upsert(ctx context.Context, p *model.UserPermissi
 	})
 }
 
-// Delete removes a permission record.
+// Delete 物理删除权限记录。
 func (r *PermissionRepository) Delete(ctx context.Context, userID string) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("user_id = ?", userID).Delete(&model.UserPermission{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("user_id = ?", userID).Delete(&model.UserPermission{}).Error
 	})
 }

internal/repository/play_profile_repo.go

@@ -59,9 +59,9 @@ func (r *PlayProfileRepository) Update(ctx context.Context, id string, patch map
 		Where("id = ?", id).Updates(patch).Error
 }
 
-// Delete soft-deletes a profile.
+// Delete 物理删除播放档案。
 func (r *PlayProfileRepository) Delete(ctx context.Context, id string) error {
-	return r.db.WithContext(ctx).Delete(&model.PlayProfile{}, "id = ?", id).Error
+	return r.db.WithContext(ctx).Unscoped().Delete(&model.PlayProfile{}, "id = ?", id).Error
 }
 
 // ClearDefaultsFor resets is_default for all of a user's profiles.

internal/repository/refresh_token_repository.go

@@ -72,10 +72,10 @@ func (r *RefreshTokenRepository) RevokeOldestActiveByUserID(ctx context.Context,
 	})
 }
 
-// DeleteExpired removes all expired refresh tokens.
+// DeleteExpired 物理清理所有过期的 refresh tokens。
 func (r *RefreshTokenRepository) DeleteExpired(ctx context.Context) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("expires_at < ?", time.Now()).Delete(&model.RefreshToken{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("expires_at < ?", time.Now()).Delete(&model.RefreshToken{}).Error
 	})
 }
 

internal/repository/setting_repository.go

@@ -29,9 +29,9 @@ func (r *SettingRepository) Set(ctx context.Context, key, value string) error {
 	return r.db.WithContext(ctx).Save(&s).Error
 }
 
-// Delete removes a setting key.
+// Delete 物理删除设置键。
 func (r *SettingRepository) Delete(ctx context.Context, key string) error {
-	return r.db.WithContext(ctx).Where("key = ?", key).Delete(&model.Setting{}).Error
+	return r.db.WithContext(ctx).Unscoped().Where("key = ?", key).Delete(&model.Setting{}).Error
 }
 
 // All returns every key/value pair (used by the admin UI).

internal/repository/storage_config_repo.go

@@ -66,9 +66,9 @@ func (r *StorageConfigRepository) Upsert(ctx context.Context, c *model.StorageCo
 	}).Error
 }
 
-// Delete removes a storage config by ID.
+// Delete 物理删除存储配置。
 func (r *StorageConfigRepository) Delete(ctx context.Context, id string) error {
-	return r.db.WithContext(ctx).Where("id = ?", id).Delete(&model.StorageConfig{}).Error
+	return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StorageConfig{}).Error
 }
 
 // FindByID returns a storage config by ID.

internal/repository/strm_repository.go

@@ -59,7 +59,7 @@ func (r *StrmAccountRepository) Update(ctx context.Context, a *model.StrmAccount
 
 func (r *StrmAccountRepository) Delete(ctx context.Context, id string) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("id = ?", id).Delete(&model.StrmAccount{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmAccount{}).Error
 	})
 }
 
@@ -123,7 +123,7 @@ func (r *StrmSyncPathRepository) Update(ctx context.Context, p *model.StrmSyncPa
 
 func (r *StrmSyncPathRepository) Delete(ctx context.Context, id string) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("id = ?", id).Delete(&model.StrmSyncPath{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmSyncPath{}).Error
 	})
 }
 
@@ -170,6 +170,24 @@ func (r *StrmSyncRecordRepository) List(ctx context.Context, syncPathID string,
 	return rows, err
 }
 
+// Delete 删除单条同步记录（物理删除）。
+func (r *StrmSyncRecordRepository) Delete(ctx context.Context, id string) error {
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmSyncRecord{}).Error
+	})
+}
+
+// DeleteBySyncPathID 删除某同步目录下的全部同步记录（删除同步目录时级联清理）。
+func (r *StrmSyncRecordRepository) DeleteBySyncPathID(ctx context.Context, syncPathID string) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Unscoped().Where("sync_path_id = ?", syncPathID).Delete(&model.StrmSyncRecord{})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
+
 // ─── StrmDownloadTask ──────────────────────────────────────────────────────────
 
 // StrmDownloadTaskRepository persists model.StrmDownloadTask.
@@ -286,7 +304,7 @@ func (r *StrmDownloadTaskRepository) Update(ctx context.Context, t *model.StrmDo
 
 func (r *StrmDownloadTaskRepository) Delete(ctx context.Context, id string) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("id = ?", id).Delete(&model.StrmDownloadTask{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmDownloadTask{}).Error
 	})
 }
 
@@ -294,7 +312,7 @@ func (r *StrmDownloadTaskRepository) Delete(ctx context.Context, id string) erro
 func (r *StrmDownloadTaskRepository) ClearDone(ctx context.Context) (int64, error) {
 	var count int64
 	err := withSQLiteBusyRetry(ctx, func() error {
-		res := r.db.WithContext(ctx).Where("status = ?", model.StrmTaskDone).Delete(&model.StrmDownloadTask{})
+		res := r.db.WithContext(ctx).Unscoped().Where("status = ?", model.StrmTaskDone).Delete(&model.StrmDownloadTask{})
 		count = res.RowsAffected
 		return res.Error
 	})
@@ -305,7 +323,7 @@ func (r *StrmDownloadTaskRepository) ClearDone(ctx context.Context) (int64, erro
 func (r *StrmDownloadTaskRepository) ClearFinished(ctx context.Context) (int64, error) {
 	var count int64
 	err := withSQLiteBusyRetry(ctx, func() error {
-		res := r.db.WithContext(ctx).Where("status IN ?", []string{model.StrmTaskDone, model.StrmTaskFailed}).
+		res := r.db.WithContext(ctx).Unscoped().Where("status IN ?", []string{model.StrmTaskDone, model.StrmTaskFailed, model.StrmTaskCanceled}).
 			Delete(&model.StrmDownloadTask{})
 		count = res.RowsAffected
 		return res.Error
@@ -313,6 +331,17 @@ func (r *StrmDownloadTaskRepository) ClearFinished(ctx context.Context) (int64,
 	return count, err
 }
 
+// ClearCanceled 清空全部已取消下载任务。
+func (r *StrmDownloadTaskRepository) ClearCanceled(ctx context.Context) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Unscoped().Where("status = ?", model.StrmTaskCanceled).Delete(&model.StrmDownloadTask{})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
+
 // RetryAllFailed 把所有失败任务重置回待处理，清空错误与重试计数。
 func (r *StrmDownloadTaskRepository) RetryAllFailed(ctx context.Context) (int64, error) {
 	var count int64
@@ -381,7 +410,7 @@ func (r *StrmDownloadTaskRepository) GetActiveLocalPathMap(ctx context.Context,
 
 func (r *StrmDownloadTaskRepository) DeleteFinishedOlderThan(ctx context.Context, before time.Time) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("status IN ? AND finished_at < ?",
+		return r.db.WithContext(ctx).Unscoped().Where("status IN ? AND finished_at < ?",
 			[]string{model.StrmTaskDone, model.StrmTaskFailed, model.StrmTaskCanceled}, before).
 			Delete(&model.StrmDownloadTask{}).Error
 	})
@@ -522,10 +551,21 @@ func (r *StrmUploadTaskRepository) Update(ctx context.Context, t *model.StrmUplo
 
 func (r *StrmUploadTaskRepository) Delete(ctx context.Context, id string) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("id = ?", id).Delete(&model.StrmUploadTask{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.StrmUploadTask{}).Error
 	})
 }
 
+// ClearCanceled 清空全部已取消上传任务。
+func (r *StrmUploadTaskRepository) ClearCanceled(ctx context.Context) (int64, error) {
+	var count int64
+	err := withSQLiteBusyRetry(ctx, func() error {
+		res := r.db.WithContext(ctx).Unscoped().Where("status = ?", model.StrmTaskCanceled).Delete(&model.StrmUploadTask{})
+		count = res.RowsAffected
+		return res.Error
+	})
+	return count, err
+}
+
 // CancelPending 批量取消所有排队中和进行中的任务。
 func (r *StrmUploadTaskRepository) CancelPending(ctx context.Context) (int64, error) {
 	now := time.Now()
@@ -573,7 +613,7 @@ func (r *StrmUploadTaskRepository) GetActiveLocalPathMap(ctx context.Context, sy
 
 func (r *StrmUploadTaskRepository) DeleteFinishedOlderThan(ctx context.Context, before time.Time) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("status IN ? AND finished_at < ?",
+		return r.db.WithContext(ctx).Unscoped().Where("status IN ? AND finished_at < ?",
 			[]string{model.StrmTaskDone, model.StrmTaskFailed, model.StrmTaskCanceled}, before).
 			Delete(&model.StrmUploadTask{}).Error
 	})
@@ -614,7 +654,7 @@ func (r *StrmDirCacheRepository) Set(ctx context.Context, syncPathID, dirID, pat
 
 func (r *StrmDirCacheRepository) DeleteBySyncPathID(ctx context.Context, syncPathID string) error {
 	return withSQLiteBusyRetry(ctx, func() error {
-		return r.db.WithContext(ctx).Where("sync_path_id = ?", syncPathID).Delete(&model.StrmDirCache{}).Error
+		return r.db.WithContext(ctx).Unscoped().Where("sync_path_id = ?", syncPathID).Delete(&model.StrmDirCache{}).Error
 	})
 }
 

internal/repository/user_repository.go

@@ -133,26 +133,17 @@ func (r *UserRepository) TouchLogin(ctx context.Context, id string) error {
 	})
 }
 
-// Delete removes a user (soft-delete via gorm.DeletedAt), releases the unique
-// username, and drops Telegram bindings so future re-created users bind cleanly.
+// Delete 物理删除用户并级联清理其关联记录。
 func (r *UserRepository) Delete(ctx context.Context, id string) error {
-	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		var user model.User
-		if err := tx.Where("id = ?", id).First(&user).Error; err != nil {
-			return err
-		}
-		released := user.Username + "__deleted__" + time.Now().Format("20060102150405.000000000")
-		if len(released) > 64 {
-			sum := sha256.Sum256([]byte(user.ID + user.Username))
-			base := user.Username
-			if len(base) > 43 {
-				base = base[:43]
-			}
-			released = base + "__deleted__" + hex.EncodeToString(sum[:])[:10]
-		}
-		if err := tx.Model(&model.User{}).Where("id = ?", id).Update("username", released).Error; err != nil {
-			return err
-		}
-		return tx.Delete(&model.User{}, "id = ?", id).Error
+	return withSQLiteBusyRetry(ctx, func() error {
+		return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+			_ = tx.Unscoped().Where("user_id = ?", id).Delete(&model.RefreshToken{})
+			_ = tx.Unscoped().Where("user_id = ?", id).Delete(&model.UserPermission{})
+			_ = tx.Unscoped().Where("user_id = ?", id).Delete(&model.PlayProfile{})
+			_ = tx.Unscoped().Where("user_id = ?", id).Delete(&model.PlaybackHistory{})
+			_ = tx.Unscoped().Where("user_id = ?", id).Delete(&model.Favorite{})
+			_ = tx.Unscoped().Where("user_id = ?", id).Delete(&model.UserDevice{})
+			return tx.Unscoped().Delete(&model.User{}, "id = ?", id).Error
+		})
 	})
 }

internal/service/cloud/pan115_openapi.go

@@ -17,6 +17,9 @@ package cloud
 import (
 	"context"
 	"fmt"
+	"io"
+	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/ShukeBta/MMTL/internal/service/cloud115"
@@ -61,16 +64,16 @@ func (p *openAPI115Provider) List(ctx context.Context, dirID string) ([]FileEntr
 		if err != nil {
 			return nil, err
 		}
-			for _, f := range files {
-				out = append(out, FileEntry{
-					ID:       f.FileId,
-					Name:     f.FileName,
-					IsDir:    f.Category == cloud115.TypeDir,
-					Size:     f.FileSize,
-					MTime:    f.Utime,
-					PickCode: f.PickCode,
-				})
-			}
+		for _, f := range files {
+			out = append(out, FileEntry{
+				ID:       f.FileId,
+				Name:     f.FileName,
+				IsDir:    f.Category == cloud115.TypeDir,
+				Size:     f.FileSize,
+				MTime:    f.Utime,
+				PickCode: f.PickCode,
+			})
+		}
 		if len(files) < pageSize {
 			break
 		}
@@ -105,6 +108,39 @@ func (p *openAPI115Provider) ResolveWithUA(ctx context.Context, fileRef, ua stri
 // OpenClient 暴露底层客户端（token 刷新用）。
 func (p *openAPI115Provider) OpenClient() *cloud115.OpenClient { return p.c }
 
+// PutFileNamed 把本地元数据上传到 115 指定父目录（parentCID 为父目录 cid）。
+// io.Reader 无法携带文件名，因此走独立的 named 上传接口。将内容落为临时文件后
+// 重命名为目标文件名，再交给 115 上传（/open/upload/init 的 file_name 取真实文件名）。
+func (p *openAPI115Provider) PutFileNamed(ctx context.Context, parentCID, fileName string, r io.Reader) error {
+	tmp, err := os.CreateTemp("", "mmtl-upload-*")
+	if err != nil {
+		return fmt.Errorf("115: 创建临时文件失败：%w", err)
+	}
+	tmpPath := tmp.Name()
+	defer func() {
+		_ = tmp.Close()
+		_ = os.Remove(tmpPath)
+	}()
+	if _, err := io.Copy(tmp, r); err != nil {
+		return fmt.Errorf("115: 写入临时文件失败：%w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("115: 关闭临时文件失败：%w", err)
+	}
+	// 重命名为目标文件名，保证上传到 115 后保留原始文件名
+	if fileName != "" && fileName != filepath.Base(tmpPath) {
+		namedPath := filepath.Join(filepath.Dir(tmpPath), fileName)
+		if err := os.Rename(tmpPath, namedPath); err == nil {
+			tmpPath = namedPath
+		}
+	}
+	_, err = p.c.Upload(ctx, tmpPath, parentCID, "", "")
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
 // RefreshToken 刷新访问令牌并返回新令牌；refresh_token 失效时返回
 // cloud115.IsRefreshTokenDead(err) 为 true 的错误。
 func (p *openAPI115Provider) RefreshToken(refreshToken string) (*cloud115.TokenData, error) {

internal/service/cloud115/cloud115_test.go

@@ -371,62 +371,61 @@ func TestThrottleCodeHandling(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected throttle error")
 	}
-		if !tm.IsThrottled() {
-			t.Fatal("code 770004 should trigger throttle status")
-		}
+	if !tm.IsThrottled() {
+		t.Fatal("code 770004 should trigger throttle status")
+	}
+}
+
+func TestRemoteFileDetailRelativePath(t *testing.T) {
+	rootCID := "3238787832374488117" // 影视库
+
+	// 场景 1：115 目录 paths 中只有祖先目录链，不包含自身
+	d1 := &RemoteFileDetail{
+		FileId:   "3251154147730910635",
+		FileName: "出包王女",
+		Paths: []struct {
+			FileId string `json:"file_id"`
+			Name   string `json:"file_name"`
+		}{
+			{FileId: "0", Name: "根目录"},
+			{FileId: "3238787832374488117", Name: "影视库"},
+			{FileId: "3238787913223892116", Name: "动漫"},
+		},
+	}
+	if got := d1.RelativePath(rootCID); got != "动漫/出包王女" {
+		t.Errorf("d1.RelativePath = %q, want %q", got, "动漫/出包王女")
 	}
 
-	func TestRemoteFileDetailRelativePath(t *testing.T) {
-		rootCID := "3238787832374488117" // 影视库
-
-		// 场景 1：115 目录 paths 中只有祖先目录链，不包含自身
-		d1 := &RemoteFileDetail{
-			FileId:   "3251154147730910635",
-			FileName: "出包王女",
-			Paths: []struct {
-				FileId string `json:"file_id"`
-				Name   string `json:"file_name"`
-			}{
-				{FileId: "0", Name: "根目录"},
-				{FileId: "3238787832374488117", Name: "影视库"},
-				{FileId: "3238787913223892116", Name: "动漫"},
-			},
-		}
-		if got := d1.RelativePath(rootCID); got != "动漫/出包王女" {
-			t.Errorf("d1.RelativePath = %q, want %q", got, "动漫/出包王女")
-		}
-
-		// 场景 2：祖先中间目录，自身在 paths 末尾
-		d2 := &RemoteFileDetail{
-			FileId:   "3238787913223892116",
-			FileName: "动漫",
-			Paths: []struct {
-				FileId string `json:"file_id"`
-				Name   string `json:"file_name"`
-			}{
-				{FileId: "0", Name: "根目录"},
-				{FileId: "3238787832374488117", Name: "影视库"},
-				{FileId: "3238787913223892116", Name: "动漫"},
-			},
-		}
-		if got := d2.RelativePath(rootCID); got != "动漫" {
-			t.Errorf("d2.RelativePath = %q, want %q", got, "动漫")
-		}
-
-		// 场景 3：根同步目录自身
-		d3 := &RemoteFileDetail{
-			FileId:   rootCID,
-			FileName: "影视库",
-			Paths: []struct {
-				FileId string `json:"file_id"`
-				Name   string `json:"file_name"`
-			}{
-				{FileId: "0", Name: "根目录"},
-				{FileId: rootCID, Name: "影视库"},
-			},
-		}
-		if got := d3.RelativePath(rootCID); got != "" {
-			t.Errorf("d3.RelativePath = %q, want %q", got, "")
-		}
+	// 场景 2：祖先中间目录，自身在 paths 末尾
+	d2 := &RemoteFileDetail{
+		FileId:   "3238787913223892116",
+		FileName: "动漫",
+		Paths: []struct {
+			FileId string `json:"file_id"`
+			Name   string `json:"file_name"`
+		}{
+			{FileId: "0", Name: "根目录"},
+			{FileId: "3238787832374488117", Name: "影视库"},
+			{FileId: "3238787913223892116", Name: "动漫"},
+		},
+	}
+	if got := d2.RelativePath(rootCID); got != "动漫" {
+		t.Errorf("d2.RelativePath = %q, want %q", got, "动漫")
 	}
 
+	// 场景 3：根同步目录自身
+	d3 := &RemoteFileDetail{
+		FileId:   rootCID,
+		FileName: "影视库",
+		Paths: []struct {
+			FileId string `json:"file_id"`
+			Name   string `json:"file_name"`
+		}{
+			{FileId: "0", Name: "根目录"},
+			{FileId: rootCID, Name: "影视库"},
+		},
+	}
+	if got := d3.RelativePath(rootCID); got != "" {
+		t.Errorf("d3.RelativePath = %q, want %q", got, "")
+	}
+}

internal/service/cloud115/open.go

@@ -185,7 +185,6 @@ func (d *RemoteFileDetail) RelativePath(rootCID string) string {
 	return strings.Join(segments, "/")
 }
 
-
 // ─── 下载直链 ──────────────────────────────────────────────────────────────────
 
 type downloadURLData struct {

internal/service/cloud115/oss_multipart.go

@@ -0,0 +1,347 @@
+// 阿里云 OSS multipart 分片上传（用于 115 元数据上传直传）。
+// 使用 115 下发的临时 STS 凭证，将本地文件分片上传到 OSS，并经 complete 回调
+// 通知 115 完成落盘。参考 QMediaSync 的 OSSMultipartUploader 实现。
+package cloud115
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"sort"
+
+	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
+	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
+)
+
+const (
+	defaultMultipartPartSize int64 = 32 * 1024 * 1024
+	multipartPartAlign       int64 = 1024 * 1024
+	maxMultipartParts        int64 = 9999
+	maxMultipartPartSize     int64 = 5 * 1024 * 1024 * 1024
+)
+
+type ossMultipartClient interface {
+	InitiateMultipartUpload(context.Context, *oss.InitiateMultipartUploadRequest, ...func(*oss.Options)) (*oss.InitiateMultipartUploadResult, error)
+	UploadPart(context.Context, *oss.UploadPartRequest, ...func(*oss.Options)) (*oss.UploadPartResult, error)
+	ListParts(context.Context, *oss.ListPartsRequest, ...func(*oss.Options)) (*oss.ListPartsResult, error)
+	CompleteMultipartUpload(context.Context, *oss.CompleteMultipartUploadRequest, ...func(*oss.Options)) (*oss.CompleteMultipartUploadResult, error)
+	AbortMultipartUpload(context.Context, *oss.AbortMultipartUploadRequest, ...func(*oss.Options)) (*oss.AbortMultipartUploadResult, error)
+}
+
+// OSSMultipartUploader 封装 OSS multipart 上传。
+type OSSMultipartUploader struct {
+	client ossMultipartClient
+}
+
+// OSSMultipartUploadInput 是 multipart 上传输入。
+type OSSMultipartUploadInput struct {
+	Bucket        string
+	Object        string
+	Callback      string
+	CallbackVar   string
+	FilePath      string
+	FileSize      int64
+	UploadId      string
+	PartSize      int64
+	PartRetryMax  int
+	refreshClient func(context.Context) (ossMultipartClient, error)
+}
+
+// OSSMultipartUploadResult 是 multipart 上传后的结果。
+type OSSMultipartUploadResult struct {
+	CallbackResult map[string]any
+	UploadId       string
+	PartSize       int64
+	TotalParts     int
+	UploadedBytes  int64
+	UploadedParts  int
+}
+
+// CalculateMultipartPartSize 计算 OSS multipart 分片大小与分片数量。
+func CalculateMultipartPartSize(fileSize int64) (int64, int, error) {
+	if fileSize < 0 {
+		return 0, 0, fmt.Errorf("文件大小不能为负数：%d", fileSize)
+	}
+	partSize := defaultMultipartPartSize
+	minPartSize := ceilDiv(fileSize, maxMultipartParts)
+	if minPartSize > partSize {
+		partSize = roundUp(minPartSize, multipartPartAlign)
+	}
+	if partSize > maxMultipartPartSize {
+		return 0, 0, fmt.Errorf("文件过大，所需分片大小 %d 超过 OSS 上限 %d", partSize, maxMultipartPartSize)
+	}
+	totalParts := int(ceilDiv(fileSize, partSize))
+	if totalParts == 0 {
+		totalParts = 1
+	}
+	if int64(totalParts) > maxMultipartParts {
+		return 0, 0, fmt.Errorf("分片数量 %d 超过上限 %d", totalParts, maxMultipartParts)
+	}
+	return partSize, totalParts, nil
+}
+
+// NewOSSMultipartUploader 创建 OSS multipart 上传器。
+func NewOSSMultipartUploader(endpoint, accessKeyId, accessKeySecret, securityToken string) *OSSMultipartUploader {
+	return &OSSMultipartUploader{client: newOSSMultipartClient(endpoint, accessKeyId, accessKeySecret, securityToken)}
+}
+
+func newOSSMultipartClient(endpoint, accessKeyId, accessKeySecret, securityToken string) ossMultipartClient {
+	cfg := oss.LoadDefaultConfig().
+		WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKeyId, accessKeySecret, securityToken)).
+		WithRegion("cn-shenzhen").
+		WithEndpoint(endpoint)
+	return oss.NewClient(cfg)
+}
+
+// UploadFile 上传文件并完成 OSS multipart，返回 complete callback 结果。
+func (u *OSSMultipartUploader) UploadFile(ctx context.Context, input OSSMultipartUploadInput) (map[string]any, error) {
+	result, err := u.UploadFileWithResult(ctx, input)
+	if err != nil {
+		return nil, err
+	}
+	return result.CallbackResult, nil
+}
+
+// UploadFileWithResult 上传文件并返回 multipart 结果。
+func (u *OSSMultipartUploader) UploadFileWithResult(ctx context.Context, input OSSMultipartUploadInput) (OSSMultipartUploadResult, error) {
+	if input.PartRetryMax <= 0 {
+		input.PartRetryMax = 3
+	}
+	partSize := input.PartSize
+	totalParts := 0
+	var err error
+	if partSize <= 0 {
+		partSize, totalParts, err = CalculateMultipartPartSize(input.FileSize)
+		if err != nil {
+			return OSSMultipartUploadResult{}, err
+		}
+	} else {
+		totalParts = int(ceilDiv(input.FileSize, partSize))
+	}
+
+	uploadId := input.UploadId
+	if uploadId == "" {
+		initResult, err := u.client.InitiateMultipartUpload(ctx, &oss.InitiateMultipartUploadRequest{
+			Bucket: oss.Ptr(input.Bucket),
+			Key:    oss.Ptr(input.Object),
+			RequestCommon: oss.RequestCommon{
+				Parameters: map[string]string{"sequential": "1"},
+			},
+		})
+		if err != nil {
+			return OSSMultipartUploadResult{}, fmt.Errorf("初始化 OSS multipart 失败：%w", err)
+		}
+		if initResult.UploadId == nil || *initResult.UploadId == "" {
+			return OSSMultipartUploadResult{}, fmt.Errorf("初始化 OSS multipart 返回空 upload_id")
+		}
+		uploadId = *initResult.UploadId
+	}
+
+	existingPartMap := make(map[int32]int64)
+	existingParts, err := u.ListUploadedParts(ctx, input.Bucket, input.Object, uploadId)
+	if err == nil {
+		for _, part := range existingParts {
+			existingPartMap[part.PartNumber] = part.Size
+		}
+	}
+
+	file, err := os.Open(input.FilePath)
+	if err != nil {
+		return OSSMultipartUploadResult{}, fmt.Errorf("打开待上传文件失败：%w", err)
+	}
+	defer file.Close()
+
+	var uploadedBytes int64
+	uploadedParts := 0
+	completeParts := make([]oss.UploadPart, 0, totalParts)
+	for partNumber := 1; partNumber <= totalParts; partNumber++ {
+		offset := int64(partNumber-1) * partSize
+		length := minInt64(partSize, input.FileSize-offset)
+		if length < 0 {
+			length = 0
+		}
+		if existingSize, ok := existingPartMap[int32(partNumber)]; ok && existingSize == length {
+			uploadedBytes += length
+			uploadedParts++
+		}
+		etag, err := u.uploadPartWithRetry(ctx, input, uploadId, int32(partNumber), file, offset, length)
+		if err != nil {
+			return OSSMultipartUploadResult{}, err
+		}
+		uploadedBytes += length
+		uploadedParts++
+		completeParts = append(completeParts, oss.UploadPart{
+			PartNumber: int32(partNumber),
+			ETag:       oss.Ptr(etag),
+		})
+	}
+	sort.Slice(completeParts, func(i, j int) bool {
+		return completeParts[i].PartNumber < completeParts[j].PartNumber
+	})
+
+	completeResult, err := u.client.CompleteMultipartUpload(ctx, &oss.CompleteMultipartUploadRequest{
+		Bucket:   oss.Ptr(input.Bucket),
+		Key:      oss.Ptr(input.Object),
+		UploadId: oss.Ptr(uploadId),
+		CompleteMultipartUpload: &oss.CompleteMultipartUpload{
+			Parts: completeParts,
+		},
+		Callback:    oss.Ptr(input.Callback),
+		CallbackVar: oss.Ptr(input.CallbackVar),
+	})
+	if err != nil {
+		return OSSMultipartUploadResult{}, fmt.Errorf("完成 OSS multipart 失败：%w", err)
+	}
+	return OSSMultipartUploadResult{
+		CallbackResult: completeResult.CallbackResult,
+		UploadId:       uploadId,
+		PartSize:       partSize,
+		TotalParts:     totalParts,
+		UploadedBytes:  uploadedBytes,
+		UploadedParts:  uploadedParts,
+	}, nil
+}
+
+// ListUploadedParts 查询 OSS 已上传分片。
+func (u *OSSMultipartUploader) ListUploadedParts(ctx context.Context, bucket, object, uploadId string) ([]struct {
+	PartNumber int32
+	Size       int64
+}, error) {
+	parts := []struct {
+		PartNumber int32
+		Size       int64
+	}{}
+	result, err := u.client.ListParts(ctx, &oss.ListPartsRequest{
+		Bucket:   oss.Ptr(bucket),
+		Key:      oss.Ptr(object),
+		UploadId: oss.Ptr(uploadId),
+		MaxParts: 1000,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("查询 OSS 已上传分片失败：%w", err)
+	}
+	for _, part := range result.Parts {
+		parts = append(parts, struct {
+			PartNumber int32
+			Size       int64
+		}{PartNumber: part.PartNumber, Size: part.Size})
+	}
+	return parts, nil
+}
+
+func (u *OSSMultipartUploader) uploadPartWithRetry(
+	ctx context.Context,
+	input OSSMultipartUploadInput,
+	uploadId string,
+	partNumber int32,
+	file *os.File,
+	offset, length int64,
+) (string, error) {
+	var lastErr error
+	for attempt := 0; attempt < input.PartRetryMax; attempt++ {
+		reader := io.NewSectionReader(file, offset, length)
+		result, err := u.client.UploadPart(ctx, &oss.UploadPartRequest{
+			Bucket:        oss.Ptr(input.Bucket),
+			Key:           oss.Ptr(input.Object),
+			PartNumber:    partNumber,
+			UploadId:      oss.Ptr(uploadId),
+			Body:          reader,
+			ContentLength: oss.Ptr(length),
+		})
+		if err == nil {
+			if result.ETag == nil || *result.ETag == "" {
+				return "", fmt.Errorf("OSS part %d 返回空 ETag", partNumber)
+			}
+			return *result.ETag, nil
+		}
+		lastErr = err
+		if attempt < input.PartRetryMax-1 && input.refreshClient != nil {
+			refreshed, refreshErr := input.refreshClient(ctx)
+			if refreshErr != nil {
+				lastErr = refreshErr
+				continue
+			}
+			u.client = refreshed
+		}
+	}
+	return "", fmt.Errorf("上传 OSS part %d 失败：%w", partNumber, lastErr)
+}
+
+// ParseCompleteCallbackResult 校验并解析 OSS complete 后的 115 callback 结果。
+func ParseCompleteCallbackResult(result map[string]any) (UploadCompleteResult, error) {
+	if result == nil {
+		return UploadCompleteResult{}, errors.New("OSS complete callback 结果为空")
+	}
+	if state, ok := result["state"].(bool); ok && !state {
+		return UploadCompleteResult{}, fmt.Errorf("115 callback 返回失败：%s", anyToString(result["message"]))
+	}
+	if message := anyToString(result["message"]); message != "" {
+		return UploadCompleteResult{}, fmt.Errorf("115 callback 返回错误：%s", message)
+	}
+	data, ok := result["data"].(map[string]any)
+	if !ok {
+		return UploadCompleteResult{}, errors.New("115 callback 缺少 data")
+	}
+	complete := UploadCompleteResult{
+		FileId:   anyToString(data["file_id"]),
+		PickCode: anyToString(data["pick_code"]),
+		ParentId: anyToString(data["parent_id"]),
+		Sha1:     anyToString(data["sha1"]),
+		Size:     anyToInt64(data["size"]),
+		Mtime:    anyToInt64(data["mtime"]),
+	}
+	if complete.FileId == "" || complete.PickCode == "" {
+		return UploadCompleteResult{}, errors.New("115 callback 缺少 file_id/pick_code")
+	}
+	return complete, nil
+}
+
+func ceilDiv(n, d int64) int64 {
+	if d <= 0 {
+		return 0
+	}
+	if n <= 0 {
+		return 0
+	}
+	return (n + d - 1) / d
+}
+
+func roundUp(n, align int64) int64 {
+	if align <= 0 {
+		return n
+	}
+	return ceilDiv(n, align) * align
+}
+
+func minInt64(a, b int64) int64 {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func anyToInt64(v any) int64 {
+	switch t := v.(type) {
+	case string:
+		var n int64
+		fmt.Sscanf(t, "%d", &n)
+		return n
+	case float64:
+		return int64(t)
+	case int64:
+		return t
+	case int:
+		return int64(t)
+	default:
+		return 0
+	}
+}
+
+func anyToString(v any) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return fmt.Sprintf("%v", v)
+}

internal/service/cloud115/queue_executor.go

@@ -26,10 +26,15 @@ var (
 	executorOnce   sync.Once
 )
 
-// GetGlobalExecutor 获取全局队列执行器单例（默认 QPS=2, QPM=120, QPH=6000，保障 115 API 调用安全不超频）。
+// GetGlobalExecutor 获取全局队列执行器单例（默认 QPS=3, QPM=200, QPH=12000，保障 115 API 调用安全不超频）。
+//
+// 历史教训：QPS 提到 8 后，下载换直链接口（/open/ufile/downurl，WAF 重点盯防对象）
+// 瞬时突发撞上 115 风控，返回阿里云 405 阻断页（HTTP 405），导致全量同步失败。
+// 因此回调到 3——这是经过实测的安全上限：宁慢勿触发风控，一旦 405 冷却 180 秒，
+// 整体吞吐反而更低。下载实际走 CDN 不受此限速影响，瓶颈仅在换链环节。
 func GetGlobalExecutor() *QueueExecutor {
 	executorOnce.Do(func() {
-		globalExecutor = NewQueueExecutor(2, 120, 6000)
+		globalExecutor = NewQueueExecutor(3, 200, 12000)
 	})
 	return globalExecutor
 }

internal/service/cloud115/sha1.go

@@ -0,0 +1,47 @@
+package cloud115
+
+import (
+	"crypto/sha1"
+	"encoding/hex"
+	"io"
+	"os"
+)
+
+// FileSHA1 计算文件完整 SHA1（小写 hex）。
+func FileSHA1(path string) (string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	h := sha1.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+// FileSHA1Partial 计算文件 [start,end]（含）字节区间的 SHA1（小写 hex）。
+// 用于 115 上传二次签名按 sign_check 指定的区间重算哈希。
+func FileSHA1Partial(path string, start, end int64) (string, error) {
+	if start < 0 {
+		start = 0
+	}
+	if end < start {
+		end = start
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	if _, err := f.Seek(start, io.SeekStart); err != nil {
+		return "", err
+	}
+	length := end - start + 1
+	h := sha1.New()
+	if _, err := io.CopyN(h, f, length); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}

internal/service/cloud115/upload.go

@@ -0,0 +1,355 @@
+// 115 网盘元数据上传能力：115 开放平台调度 + 阿里云 OSS 直传。
+// 参考 QMediaSync 的上传流程实现：
+//
+//	POST /open/upload/init           上传初始化/秒传调度（含二次签名）
+//	GET  /open/upload/get_token      获取 OSS 临时上传凭证（STS）
+//	OSS  multipart 分片直传 + callback 完成
+//
+// 上传目标父目录为 115 目录 ID（cid），而非路径字符串。
+package cloud115
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// 115 上传状态码。
+const (
+	UploadInitStatusNeedUpload    = 1 // 需要真实上传
+	UploadInitStatusRapidUploaded = 2 // 秒传成功
+	UploadInitStatusSignFailed    = 6 // 签名验证失败
+	UploadInitStatusNeedSign      = 7 // 需要二次签名
+	UploadInitStatusSignRejected  = 8 // 签名认证失败
+)
+
+// UploadInitRequest 是 /open/upload/init 的结构化请求。
+type UploadInitRequest struct {
+	FileName     string
+	FileSize     int64
+	ParentFileId string
+	FileSha1     string
+	Preid        string
+	PickCode     string
+	TopUpload    string
+	SignKey      string
+	SignVal      string
+}
+
+// UploadInitResult 是 /open/upload/init 的调度结果。
+type UploadInitResult struct {
+	PickCode  string
+	Status    int
+	FileId    string
+	Target    string
+	Bucket    string
+	Object    string
+	SignKey   string
+	SignCheck string
+	Callback  UploadResultCallBack
+}
+
+type uploadScheduleAPIResult struct {
+	PickCode  string          `json:"pick_code"`
+	Status    int             `json:"status"`
+	FileId    string          `json:"file_id"`
+	Target    string          `json:"target"`
+	Version   string          `json:"version"`
+	Bucket    string          `json:"bucket"`
+	Object    string          `json:"object"`
+	SignKey   string          `json:"sign_key"`
+	SignCheck string          `json:"sign_check"`
+	Callback  json.RawMessage `json:"callback"`
+}
+
+// UploadResultCallBack 是 init 返回给 OSS complete 使用的 callback 内容。
+type UploadResultCallBack struct {
+	Callback    string `json:"callback"`
+	CallbackVar string `json:"callback_var"`
+}
+
+// UploadToken 是 /open/upload/get_token 返回的 OSS STS 临时凭证。
+type UploadToken struct {
+	Endpoint         string `json:"endpoint"`
+	AccessKeySecret  string `json:"AccessKeySecret"`
+	AccessKeySecrett string `json:"AccessKeySecrett"`
+	SecurityToken    string `json:"SecurityToken"`
+	Expiration       string `json:"Expiration"`
+	AccessKeyId      string `json:"AccessKeyId"`
+}
+
+func (token *UploadToken) normalize() {
+	if token == nil {
+		return
+	}
+	if token.AccessKeySecret == "" {
+		token.AccessKeySecret = token.AccessKeySecrett
+	}
+}
+
+// UploadCompleteResult 是 OSS complete callback 成功后的远端文件定位结果。
+type UploadCompleteResult struct {
+	FileId   string
+	PickCode string
+	ParentId string
+	Sha1     string
+	Size     int64
+	Mtime    int64
+}
+
+// SignCheckRange 是 115 二次认证要求的闭区间 [start,end]。
+type SignCheckRange struct {
+	Start int64
+	End   int64
+}
+
+// UploadInit 调用 115 上传初始化/秒传调度接口。
+func (c *OpenClient) UploadInit(ctx context.Context, input UploadInitRequest) (*UploadInitResult, error) {
+	params := buildUploadInitForm(input)
+	resp, err := c.doAuthJSON(ctx, "POST", ProAPIBase+"/open/upload/init", params, 2)
+	if err != nil {
+		return nil, err
+	}
+	var raw uploadScheduleAPIResult
+	if err := json.Unmarshal(resp.Data, &raw); err != nil {
+		return nil, fmt.Errorf("115: 解析 upload/init 结果失败：%w", err)
+	}
+	callback, err := decodeUploadCallback(raw.Callback)
+	if err != nil {
+		return nil, err
+	}
+	return &UploadInitResult{
+		PickCode:  raw.PickCode,
+		Status:    raw.Status,
+		FileId:    raw.FileId,
+		Target:    raw.Target,
+		Bucket:    raw.Bucket,
+		Object:    raw.Object,
+		SignKey:   raw.SignKey,
+		SignCheck: raw.SignCheck,
+		Callback:  callback,
+	}, nil
+}
+
+func buildUploadInitForm(input UploadInitRequest) map[string]string {
+	topUpload := input.TopUpload
+	if topUpload == "" {
+		topUpload = "0"
+	}
+	params := map[string]string{
+		"file_name": input.FileName,
+		"file_size": strconv.FormatInt(input.FileSize, 10),
+		"target":    fmt.Sprintf("U_1_%s", input.ParentFileId),
+		"fileid":    input.FileSha1,
+		"preid":     input.Preid,
+		"topupload": topUpload,
+	}
+	if input.PickCode != "" {
+		params["pick_code"] = input.PickCode
+	}
+	if input.SignKey != "" && input.SignVal != "" {
+		params["sign_key"] = input.SignKey
+		params["sign_val"] = input.SignVal
+	}
+	return params
+}
+
+func decodeUploadCallback(raw json.RawMessage) (UploadResultCallBack, error) {
+	if len(raw) == 0 || string(raw) == "null" {
+		return UploadResultCallBack{}, nil
+	}
+	if raw[0] == '[' {
+		var callbacks []UploadResultCallBack
+		if err := json.Unmarshal(raw, &callbacks); err != nil {
+			return UploadResultCallBack{}, err
+		}
+		if len(callbacks) == 0 {
+			return UploadResultCallBack{}, nil
+		}
+		return callbacks[0], nil
+	}
+	var callback UploadResultCallBack
+	if err := json.Unmarshal(raw, &callback); err != nil {
+		return UploadResultCallBack{}, err
+	}
+	return callback, nil
+}
+
+func parseSignCheckRange(value string) (SignCheckRange, error) {
+	parts := strings.Split(value, "-")
+	if len(parts) != 2 {
+		return SignCheckRange{}, fmt.Errorf("sign_check 格式错误：%s", value)
+	}
+	start, err := strconv.ParseInt(strings.TrimSpace(parts[0]), 10, 64)
+	if err != nil {
+		return SignCheckRange{}, err
+	}
+	end, err := strconv.ParseInt(strings.TrimSpace(parts[1]), 10, 64)
+	if err != nil {
+		return SignCheckRange{}, err
+	}
+	if start < 0 || end < start {
+		return SignCheckRange{}, fmt.Errorf("sign_check 范围非法：%s", value)
+	}
+	return SignCheckRange{Start: start, End: end}, nil
+}
+
+// GetUploadToken 获取 115 下发的 OSS 临时上传凭证。
+func (c *OpenClient) GetUploadToken(ctx context.Context) (*UploadToken, error) {
+	resp, err := c.doAuthJSON(ctx, "GET", ProAPIBase+"/open/upload/get_token", nil, 2)
+	if err != nil {
+		return nil, err
+	}
+	var token UploadToken
+	if err := json.Unmarshal(resp.Data, &token); err != nil {
+		return nil, fmt.Errorf("115: 解析 get_token 结果失败：%w", err)
+	}
+	token.normalize()
+	return &token, nil
+}
+
+// Upload 上传单个本地文件到 115 指定父目录（cid），返回成功后的远端文件信息。
+// filePath 必须是落到磁盘的真实文件路径（调用方负责把 io.Reader 落盘为临时文件）。
+func (c *OpenClient) Upload(ctx context.Context, filePath, parentCID, signKey, signVal string) (*UploadCompleteResult, error) {
+	fileSize := fileSizeOf(filePath)
+	if fileSize < 0 {
+		return nil, fmt.Errorf("115: 无法获取文件大小：%s", filePath)
+	}
+	fileSha1, err := FileSHA1(filePath)
+	if err != nil {
+		return nil, fmt.Errorf("115: 计算文件 SHA1 失败：%w", err)
+	}
+	preSha1, err := FileSHA1Partial(filePath, 0, 128*1024-1)
+	if err != nil {
+		return nil, fmt.Errorf("115: 计算文件前 128 KiB SHA1 失败：%w", err)
+	}
+	request := UploadInitRequest{
+		FileName:     baseNameOf(filePath),
+		FileSize:     fileSize,
+		ParentFileId: parentCID,
+		FileSha1:     fileSha1,
+		Preid:        preSha1,
+		TopUpload:    "0",
+		SignKey:      signKey,
+		SignVal:      signVal,
+	}
+	initResult, err := c.UploadInit(ctx, request)
+	if err != nil {
+		return nil, fmt.Errorf("115: 上传初始化失败：%w", err)
+	}
+	status := initResult.Status
+	if status == UploadInitStatusNeedSign {
+		// 二次签名：按 sign_check 指定区间重算 sha1
+		rng, err := parseSignCheckRange(initResult.SignCheck)
+		if err != nil {
+			return nil, err
+		}
+		signValue, err := FileSHA1Partial(filePath, rng.Start, rng.End)
+		if err != nil {
+			return nil, err
+		}
+		request.SignKey = initResult.SignKey
+		request.SignVal = signValue
+		initResult, err = c.UploadInit(ctx, request)
+		if err != nil {
+			return nil, fmt.Errorf("115: 上传二次签名失败：%w", err)
+		}
+		status = initResult.Status
+	}
+	switch status {
+	case UploadInitStatusRapidUploaded:
+		// 秒传成功
+		return &UploadCompleteResult{FileId: initResult.FileId, PickCode: initResult.PickCode}, nil
+	case UploadInitStatusSignFailed:
+		return nil, fmt.Errorf("115: 签名验证后失败")
+	case UploadInitStatusSignRejected:
+		return nil, fmt.Errorf("115: 签名认证失败")
+	case UploadInitStatusNeedUpload:
+		// 真实上传：OSS multipart
+	default:
+		return &UploadCompleteResult{FileId: initResult.FileId, PickCode: initResult.PickCode}, nil
+	}
+
+	if initResult.Bucket == "" || initResult.Object == "" {
+		return nil, fmt.Errorf("115: upload/init 缺少 bucket/object 信息")
+	}
+	token, err := c.GetUploadToken(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("115: 获取上传凭证失败：%w", err)
+	}
+	if token == nil || token.Endpoint == "" || token.AccessKeyId == "" || token.AccessKeySecret == "" {
+		return nil, fmt.Errorf("115: 上传凭证不完整")
+	}
+	uploader := NewOSSMultipartUploader(token.Endpoint, token.AccessKeyId, token.AccessKeySecret, token.SecurityToken)
+	result, err := uploader.UploadFile(ctx, OSSMultipartUploadInput{
+		Bucket:      initResult.Bucket,
+		Object:      initResult.Object,
+		Callback:    initResult.Callback.Callback,
+		CallbackVar: initResult.Callback.CallbackVar,
+		FilePath:    filePath,
+		FileSize:    fileSize,
+		refreshClient: func(ctx context.Context) (ossMultipartClient, error) {
+			refreshed, rerr := c.GetUploadToken(ctx)
+			if rerr != nil || refreshed == nil {
+				return nil, rerr
+			}
+			return newOSSMultipartClient(refreshed.Endpoint, refreshed.AccessKeyId, refreshed.AccessKeySecret, refreshed.SecurityToken), nil
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("115: OSS 上传失败：%w", err)
+	}
+	complete, err := ParseCompleteCallbackResult(result)
+	if err != nil {
+		return nil, err
+	}
+	return &complete, nil
+}
+
+// MkDir 在 115 的 parentCid 下创建目录，返回新目录 cid。
+func (c *OpenClient) MkDir(ctx context.Context, parentCID, name string) (string, error) {
+	params := map[string]string{
+		"cname": name,
+		"pid":   parentCID,
+	}
+	resp, err := c.doAuthJSON(ctx, "POST", ProAPIBase+"/open/folder/add", params, 2)
+	if err != nil {
+		return "", err
+	}
+	// /open/folder/add 结构：{ aid, cid, fid, name, pid, ... }，单一对象
+	var r struct {
+		Cid string `json:"cid"`
+	}
+	if err := json.Unmarshal(resp.Data, &r); err != nil {
+		return "", fmt.Errorf("115: 解析 folder/add 结果失败：%w", err)
+	}
+	if r.Cid == "" {
+		return "", errors.New("115: folder/add 未返回 cid")
+	}
+	return r.Cid, nil
+}
+
+func fileSizeOf(path string) int64 {
+	info, err := os.Stat(path)
+	if err != nil {
+		return -1
+	}
+	if info.IsDir() {
+		return -1
+	}
+	return info.Size()
+}
+
+func baseNameOf(path string) string {
+	s := path
+	for i := len(s) - 1; i >= 0; i-- {
+		if s[i] == '/' || s[i] == '\\' {
+			return s[i+1:]
+		}
+	}
+	return s
+}

internal/service/cloud115/upload_test.go

@@ -0,0 +1,94 @@
+package cloud115
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFileSHA1(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "a.txt")
+	if err := os.WriteFile(path, []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	sum, err := FileSHA1(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// sha1("hello") = aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
+	if sum != "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d" {
+		t.Errorf("unexpected sha1: %s", sum)
+	}
+}
+
+func TestFileSHA1Partial(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "b.txt")
+	// 10 bytes: "0123456789"
+	if err := os.WriteFile(path, []byte("0123456789"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// bytes [2,4] = "234"
+	sum, err := FileSHA1Partial(path, 2, 4)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum != "0ec09ef9836da03f1add21e3ef607627e687e790" {
+		t.Errorf("unexpected partial sha1: %s", sum)
+	}
+}
+
+func TestParseSignCheckRange(t *testing.T) {
+	rng, err := parseSignCheckRange("0-131071")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rng.Start != 0 || rng.End != 131071 {
+		t.Errorf("unexpected range: %+v", rng)
+	}
+	if _, err := parseSignCheckRange("bad"); err == nil {
+		t.Error("expected error for bad range")
+	}
+	if _, err := parseSignCheckRange("100-50"); err == nil {
+		t.Error("expected error for end<start")
+	}
+}
+
+func TestCalculateMultipartPartSize(t *testing.T) {
+	// small file: 1 MiB -> partSize 32MiB, 1 part
+	ps, parts, err := CalculateMultipartPartSize(1 << 20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ps != defaultMultipartPartSize {
+		t.Errorf("partSize=%d, want %d", ps, defaultMultipartPartSize)
+	}
+	if parts != 1 {
+		t.Errorf("parts=%d, want 1", parts)
+	}
+	// zero-size -> 1 part
+	_, parts, err = CalculateMultipartPartSize(0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if parts != 1 {
+		t.Errorf("zero-size parts=%d, want 1", parts)
+	}
+	// negative -> error
+	if _, _, err := CalculateMultipartPartSize(-1); err == nil {
+		t.Error("expected error for negative size")
+	}
+}
+
+func TestBaseNameOf(t *testing.T) {
+	if got := baseNameOf("/a/b/file.nfo"); got != "file.nfo" {
+		t.Errorf("got %s", got)
+	}
+	if got := baseNameOf("a\\b\\c.jpg"); got != "c.jpg" {
+		t.Errorf("got %s", got)
+	}
+	if got := baseNameOf("top.txt"); got != "top.txt" {
+		t.Errorf("got %s", got)
+	}
+}

internal/service/local_metadata_read.go

@@ -49,7 +49,7 @@ func findMovieNFO(mediaPath, libraryRoot string) (*nfoDocument, string, error) {
 			continue
 		}
 		seen[key] = struct{}{}
-		if doc, _, err := readNFO(path); err == nil {
+		if doc, _, err := decodeNFOFile(path); err == nil && doc != nil {
 			return doc, path, nil
 		} else if err != nil && !errors.Is(err, os.ErrNotExist) {
 			return nil, "", err
@@ -62,7 +62,7 @@ func findMovieNFO(mediaPath, libraryRoot string) (*nfoDocument, string, error) {
 			for _, match := range matches {
 				baseKey := strings.ToLower(strings.ReplaceAll(strings.TrimSuffix(filepath.Base(match), filepath.Ext(match)), "-", ""))
 				if strings.Contains(baseKey, codeKey) || strings.Contains(codeKey, baseKey) {
-					if doc, _, err := readNFO(match); err == nil {
+					if doc, _, err := decodeNFOFile(match); err == nil && doc != nil {
 						return doc, match, nil
 					} else if err != nil && !errors.Is(err, os.ErrNotExist) {
 						return nil, "", err
@@ -71,7 +71,7 @@ func findMovieNFO(mediaPath, libraryRoot string) (*nfoDocument, string, error) {
 			}
 		}
 		if len(matches) == 1 {
-			if doc, _, err := readNFO(matches[0]); err == nil {
+			if doc, _, err := decodeNFOFile(matches[0]); err == nil && doc != nil {
 				return doc, matches[0], nil
 			} else if err != nil && !errors.Is(err, os.ErrNotExist) {
 				return nil, "", err
@@ -84,21 +84,33 @@ func findMovieNFO(mediaPath, libraryRoot string) (*nfoDocument, string, error) {
 func readSeriesMetadata(mediaPath, libraryRoot string) (*LocalMetadata, error) {
 	var meta *LocalMetadata
 	showBaseDir := ""
-	if showDoc, showPath, err := findShowNFO(mediaPath, libraryRoot); err == nil && showDoc != nil {
+	if showDoc, showPath, partial, err := findShowNFO(mediaPath, libraryRoot); err == nil && showDoc != nil {
 		showBaseDir = filepath.Dir(showPath)
 		meta = metadataFromDoc(showDoc, showBaseDir, true)
+		// A truncated show NFO still yields a usable title/poster (decodePartialNFO
+		// only surfaces docs with recoverable fields). Keep HasNFO so the recovered
+		// title participates in series grouping; a fully partial episode match
+		// below can still demote it.
+		meta.HasNFO = !partial || meta.HasNFO
 	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
-		return nil, err
+		// A damaged show NFO must not discard the whole series: readLocalScanMetadata
+		// treats this as a hard failure and leaves every episode without local
+		// metadata. When the show level fails we still merge the episode NFO and
+		// local artwork below instead of returning early.
+		meta = nil
 	}
 
-	if episodeDoc, episodePath, err := readNFO(nfoPath(mediaPath)); err == nil {
+	if episodeDoc, episodePath, episodePartial, err := readEpisodeNFO(nfoPath(mediaPath)); err == nil && episodeDoc != nil {
 		episodeMeta := metadataFromDoc(episodeDoc, filepath.Dir(episodePath), true)
 		if meta == nil {
 			meta = &LocalMetadata{}
 		}
 		mergeEpisodeMetadata(meta, episodeMeta, episodeDoc)
-	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
-		return nil, err
+		// Only a fully valid episode NFO can confirm the match; a truncated one
+		// keeps whatever the show NFO supplied but must not force scrape_status.
+		if episodePartial {
+			meta.HasNFO = false
+		}
 	}
 	if meta == nil {
 		meta = metadataFromArtwork(mediaPath, showBaseDir)
@@ -108,19 +120,49 @@ func readSeriesMetadata(mediaPath, libraryRoot string) (*LocalMetadata, error) {
 	return meta, nil
 }
 
-func readNFO(path string) (*nfoDocument, string, error) {
+// readEpisodeNFO reads the sidecar NFO next to an episode file and reports both
+// the recovered document and whether it came from a truncated/malformed file.
+func readEpisodeNFO(path string) (*nfoDocument, string, bool, error) {
 	body, err := os.ReadFile(path) // #nosec G304 -- path is a discovered NFO sidecar under the configured library root.
 	if err != nil {
-		return nil, "", err
+		return nil, "", false, err
 	}
-	var doc nfoDocument
-	if err := xml.Unmarshal(body, &doc); err != nil {
-		return nil, "", err
+	doc, partial, err := decodePartialNFO(body)
+	if err != nil {
+		return nil, "", false, err
 	}
-	return &doc, path, nil
+	return doc, path, partial, nil
 }
 
-func findShowNFO(mediaPath, libraryRoot string) (*nfoDocument, string, error) {
+func decodePartialNFO(body []byte) (*nfoDocument, bool, error) {
+	var doc nfoDocument
+	err := xml.Unmarshal(body, &doc)
+	if err == nil {
+		return &doc, false, nil
+	}
+	if !isLikelyTruncatedXMLError(err) {
+		// A real parse error unrelated to truncation: don't trust partial fields.
+		return nil, false, err
+	}
+	// Unmarshal still fills the elements it closed before hitting the cut; treat
+	// those as partial show metadata instead of dropping everything.
+	if doc.Title == "" && doc.OriginalTitle == "" && len(doc.Thumbs) == 0 &&
+		doc.Premiered == "" && doc.Plot == "" {
+		return nil, false, err
+	}
+	return &doc, true, nil
+}
+
+func isLikelyTruncatedXMLError(err error) bool {
+	for _, msg := range []string{"unexpected EOF", "EOF"} {
+		if strings.Contains(strings.ToLower(err.Error()), strings.ToLower(msg)) {
+			return true
+		}
+	}
+	return false
+}
+
+func findShowNFO(mediaPath, libraryRoot string) (*nfoDocument, string, bool, error) {
 	dir := filepath.Dir(mediaPath)
 	root := filepath.Clean(libraryRoot)
 	for {
@@ -133,19 +175,33 @@ func findShowNFO(mediaPath, libraryRoot string) (*nfoDocument, string, error) {
 		names = append(names, base+".nfo")
 		for _, name := range names {
 			path := filepath.Join(dir, name)
-			if doc, _, err := readNFO(path); err == nil {
-				return doc, path, nil
-			} else if err != nil && !errors.Is(err, os.ErrNotExist) {
-				return nil, "", err
+			doc, partial, err := decodeNFOFile(path)
+			if doc != nil {
+				return doc, path, partial, nil
+			}
+			if err != nil && !errors.Is(err, os.ErrNotExist) {
+				return nil, "", false, err
 			}
 		}
 		if samePath(dir, root) {
-			return nil, "", os.ErrNotExist
+			return nil, "", false, os.ErrNotExist
 		}
 		parent := filepath.Dir(dir)
 		if parent == dir {
-			return nil, "", os.ErrNotExist
+			return nil, "", false, os.ErrNotExist
 		}
 		dir = parent
 	}
 }
+
+func decodeNFOFile(path string) (*nfoDocument, bool, error) {
+	body, err := os.ReadFile(path) // #nosec G304 -- path is a discovered NFO sidecar under the configured library root.
+	if err != nil {
+		return nil, false, err
+	}
+	doc, partial, err := decodePartialNFO(body)
+	if err != nil {
+		return nil, false, err
+	}
+	return doc, partial, nil
+}

internal/service/local_metadata_test.go

@@ -267,3 +267,111 @@ func TestReadLocalMetadataWithoutNFOStillFindsArtwork(t *testing.T) {
 		t.Fatalf("unexpected artwork metadata: %+v", got)
 	}
 }
+
+// TestReadLocalMetadataRecoversFromTruncatedShowNFO mirrors a real-world issue:
+// some anime tvshow.nfo files are truncated mid-URL (unexpected EOF). Before the
+// fix this discarded the whole series, leaving episodes pending with per-episode
+// titles and no poster. The recoverable fields (title/year) and the matching
+// episode NFO + local artwork must still be applied.
+func TestReadLocalMetadataRecoversFromTruncatedShowNFO(t *testing.T) {
+	root := t.TempDir()
+	showDir := filepath.Join(root, "夏日重现 (2022)")
+	seasonDir := filepath.Join(showDir, "Season 1")
+	if err := os.MkdirAll(seasonDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mediaPath := filepath.Join(seasonDir, "S01E01.mkv")
+	if err := os.WriteFile(mediaPath, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// tvshow.nfo cut off inside a <thumb> URL, like the broken real files.
+	truncated := `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<tvshow>
+  <title>夏日重现</title>
+  <originaltitle>サマータイムレンダ</originaltitle>
+  <year>2022</year>
+  <plot>听闻自己青梅竹马死讯。</plot>
+  <thumb aspect="poster">https://image.tmdb.org/t/p/original/2koyWLm6iVn5OTEExTjKzVms5Iz.jpg</thumb>
+  <fanart>
+    <thumb>https://image.tmdb.org/t/p/original/p2eZlGwd8OjkWpwD2hSoBiIlHBZ.jpg</thu`
+	if err := os.WriteFile(filepath.Join(showDir, "tvshow.nfo"), []byte(truncated), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// The episode sidecar NFO is complete and should still be merged.
+	if err := os.WriteFile(nfoPath(mediaPath), []byte(`<episodedetails><title>再见了夏日</title><season>1</season><episode>1</episode></episodedetails>`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Local artwork next to the show folder.
+	poster := filepath.Join(showDir, "poster.jpg")
+	if err := os.WriteFile(poster, []byte("jpg"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := ReadLocalMetadata(mediaPath, root, true)
+	if err != nil {
+		t.Fatalf("ReadLocalMetadata returned error on truncated show NFO: %v", err)
+	}
+	if got == nil {
+		t.Fatal("metadata is nil; truncated show NFO discarded the series")
+	}
+	// The recovered show title takes precedence over the episode title.
+	if got.Title != "夏日重现" {
+		t.Fatalf("Title = %q, want recovered show title 夏日重现", got.Title)
+	}
+	if got.Year != 2022 {
+		t.Fatalf("Year = %d, want 2022", got.Year)
+	}
+	if got.EpisodeTitle != "再见了夏日" || got.SeasonNum != 1 || got.EpisodeNum != 1 {
+		t.Fatalf("episode metadata not preserved: %+v", got)
+	}
+	// Prior to the fix the episode metadata was dropped entirely; the poster comes
+	// from the local poster.jpg next to the show.
+	if got.PosterURL != poster {
+		t.Fatalf("PosterURL = %q, want local poster %q", got.PosterURL, poster)
+	}
+	// A truncated show NFO must not be treated as an authoritative match by
+	// itself; since the episode NFO is valid we still mark it matched so the
+	// recovered series title participates in grouping.
+	if !got.HasNFO {
+		t.Fatalf("HasNFO = false, want true (episode NFO is valid)")
+	}
+}
+
+// TestReadLocalMetadataKeepsArtworkOnlyWhenNoUsableNFO verifies that when a show
+// NFO is truncated AND yields no recoverable fields, we still fall back to local
+// artwork instead of returning an error.
+func TestReadLocalMetadataArtworkFallbackOnGarbageShowNFO(t *testing.T) {
+	root := t.TempDir()
+	showDir := filepath.Join(root, "Some Show")
+	seasonDir := filepath.Join(showDir, "Season 1")
+	if err := os.MkdirAll(seasonDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	mediaPath := filepath.Join(seasonDir, "S01E01.mkv")
+	if err := os.WriteFile(mediaPath, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Severely truncated: no recoverable title/fields at all.
+	if err := os.WriteFile(filepath.Join(showDir, "tvshow.nfo"), []byte(`<tvshow><title>半截`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Episode-level backdrop sits next to the episode file.
+	backdrop := filepath.Join(seasonDir, "S01E01-backdrop.jpg")
+	if err := os.WriteFile(backdrop, []byte("jpg"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := ReadLocalMetadata(mediaPath, root, true)
+	if err != nil {
+		t.Fatalf("ReadLocalMetadata should not error when NFO is unusable: %v", err)
+	}
+	if got == nil {
+		t.Fatal("metadata is nil; artwork fallback missing")
+	}
+	if got.HasNFO {
+		t.Fatalf("HasNFO = true, want false for unusable NFO")
+	}
+	if got.BackdropURL != backdrop {
+		t.Fatalf("expected episode artwork fallback, got %+v", got)
+	}
+}

internal/service/media_library.go

@@ -43,10 +43,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.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)

internal/service/media_library_roots.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"os"
 	"path/filepath"
 	"strings"
 
@@ -59,6 +60,46 @@ func (s *MediaService) CreateLibraryWithRootsAndCover(ctx context.Context, name,
 	return lib, nil
 }
 
+// CreateLibrariesPerSubfolder 为 parent 目录下的每个直接子目录各建一个媒体库，
+// 媒体库名取子目录名，路径指向该子目录。kind 为空时按子目录名推断类型。
+func (s *MediaService) CreateLibrariesPerSubfolder(ctx context.Context, parent, kind, coverURL string) ([]model.Library, error) {
+	parent = strings.TrimSpace(parent)
+	if parent == "" {
+		return nil, errors.New("parent path required")
+	}
+	dir, err := resolveAccessibleLibraryPath(parent)
+	if err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, fmt.Errorf("read directory failed: %w", err)
+	}
+	subdirs := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		if strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		subdirs = append(subdirs, filepath.Join(dir, entry.Name()))
+	}
+	if len(subdirs) == 0 {
+		return nil, errors.New("no subfolders found")
+	}
+	created := make([]model.Library, 0, len(subdirs))
+	for _, subdir := range subdirs {
+		name := filepath.Base(subdir)
+		lib, err := s.CreateLibraryWithRootsAndCover(ctx, name, kind, coverURL, []LibraryRootInput{{Path: subdir}})
+		if err != nil {
+			return nil, fmt.Errorf("create library for %s: %w", subdir, err)
+		}
+		created = append(created, *lib)
+	}
+	return created, nil
+}
+
 func (s *MediaService) UpdateLibraryCover(ctx context.Context, libraryID, coverURL string) error {
 	return s.repo.DB.WithContext(ctx).Model(&model.Library{}).Where("id = ?", libraryID).
 		Update("cover_url", strings.TrimSpace(coverURL)).Error

internal/service/media_recycle.go

@@ -10,25 +10,10 @@ import (
 
 const maxRecycleBinRecords = 200
 
-// SoftDelete moves a media row to the recycle bin (gorm soft delete).
-// The on-disk file is kept; admins can purge it later.
+// SoftDelete 物理删除媒体记录（统一硬删除以降低 SQLite 存储与索引压力）。
 func (s *MediaService) SoftDelete(ctx context.Context, id string) error {
-	media, err := s.repo.Media.FindByID(ctx, id)
-	if err != nil {
-		return err
-	}
-	if media != nil && isCloudMediaPath(media.Path) {
-		err := s.repo.DB.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.Media{}).Error
-		if err == nil {
-			s.invalidateMediaCache(ctx)
-		}
-		return err
-	}
-	err = s.repo.DB.WithContext(ctx).Where("id = ?", id).Delete(&model.Media{}).Error
+	err := s.repo.DB.WithContext(ctx).Unscoped().Where("id = ?", id).Delete(&model.Media{}).Error
 	if err == nil {
-		if pruneErr := pruneRecycleBinRows(ctx, s.repo.DB, maxRecycleBinRecords); pruneErr != nil {
-			return pruneErr
-		}
 		s.invalidateMediaCache(ctx)
 	}
 	return err

internal/service/organizer_directory_versions.go

@@ -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).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 {

internal/service/organizer_reclassify_media_rows.go

@@ -97,7 +97,7 @@ func (o *OrganizerService) deleteMediaRowForPath(ctx context.Context, path strin
 	if o == nil || o.repo == nil || o.repo.DB == nil {
 		return
 	}
-	_ = o.repo.DB.WithContext(ctx).Where("path = ?", path).Delete(&model.Media{}).Error
+	_ = o.repo.DB.WithContext(ctx).Unscoped().Where("path = ?", path).Delete(&model.Media{}).Error
 }
 
 func (o *OrganizerService) mediaPathExists(ctx context.Context, path string) bool {

internal/service/playback.go

@@ -196,18 +196,18 @@ func (p *PlaybackService) AddToPlaylist(ctx context.Context, playlistID, mediaID
 	return p.repo.DB.Create(item).Error
 }
 
-// RemoveFromPlaylist removes a media item from a playlist (idempotent).
+// RemoveFromPlaylist 物理删除播放列表项（幂等）。
 func (p *PlaybackService) RemoveFromPlaylist(ctx context.Context, playlistID, mediaID string) error {
-	return p.repo.DB.
+	return p.repo.DB.WithContext(ctx).Unscoped().
 		Where("playlist_id = ? AND media_id = ?", playlistID, mediaID).
 		Delete(&model.PlaylistItem{}).Error
 }
 
-// DeletePlaylist removes a playlist and all of its items.
+// DeletePlaylist 物理删除播放列表及其全部条目。
 func (p *PlaybackService) DeletePlaylist(ctx context.Context, playlistID string) error {
-	if err := p.repo.DB.Where("playlist_id = ?", playlistID).
+	if err := p.repo.DB.WithContext(ctx).Unscoped().Where("playlist_id = ?", playlistID).
 		Delete(&model.PlaylistItem{}).Error; err != nil {
 		return err
 	}
-	return p.repo.DB.Where("id = ?", playlistID).Delete(&model.Playlist{}).Error
+	return p.repo.DB.WithContext(ctx).Unscoped().Where("id = ?", playlistID).Delete(&model.Playlist{}).Error
 }

internal/service/scanner_prune.go

@@ -11,13 +11,12 @@ import (
 	"github.com/ShukeBta/MMTL/internal/model"
 )
 
-// RemovePath deletes the media row for a path that has disappeared from disk
-// (incremental delete used by the watcher on Remove/Rename events).
+// RemovePath 物理删除磁盘上已不存在的媒体记录。
 func (s *ScannerService) RemovePath(ctx context.Context, path string) (int64, error) {
 	if _, err := os.Stat(path); err == nil {
 		return 0, nil // still exists; nothing to remove
 	}
-	res := s.repo.DB.WithContext(ctx).
+	res := s.repo.DB.WithContext(ctx).Unscoped().
 		Where("path = ?", path).
 		Delete(&model.Media{})
 	if res.Error == nil && res.RowsAffected > 0 {
@@ -55,7 +54,7 @@ func (s *ScannerService) pruneMissingMedia(ctx context.Context, libraryID string
 		}
 		stale = append(stale, row.ID)
 	}
-	return s.deleteMediaByIDs(ctx, stale, false)
+	return s.deleteMediaByIDs(ctx, stale, true)
 }
 
 func (s *ScannerService) pruneMissingMediaForRoot(ctx context.Context, libraryID, rootID, rootPath string, seen map[string]struct{}) (int64, error) {
@@ -92,7 +91,7 @@ func (s *ScannerService) pruneMissingMediaForRoot(ctx context.Context, libraryID
 		}
 		stale = append(stale, row.ID)
 	}
-	return s.deleteMediaByIDs(ctx, stale, false)
+	return s.deleteMediaByIDs(ctx, stale, true)
 }
 
 func pathBelongsToRoot(pathValue, rootPath string) bool {

internal/service/strm_queue.go

@@ -13,6 +13,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
 
 	"go.uber.org/zap"
@@ -27,7 +28,12 @@ const (
 )
 
 // downloadWorker 下载队列 worker：认领 → 解析直链 → 下载 → 落盘。
+//
+// 采用「批量认领 + 全局并发限流」：一次认领数个任务，用 StrmService 上的全局信号量
+// 限制整个进程「同时换直链+下载」的并发数（与 115 换链风控匹配，见 strmDownloadSemCap），
+// 同时让下载充分并行。换链走全局令牌桶（QPS=3）兜底，下载走 CDN 不限速。
 func (s *StrmService) downloadWorker(ctx context.Context) {
+	const claimBatch = 12 // 每次批量认领的任务数
 	for {
 		select {
 		case <-ctx.Done():
@@ -42,7 +48,7 @@ func (s *StrmService) downloadWorker(ctx context.Context) {
 			sleepContext(ctx, left)
 			continue
 		}
-		tasks, err := s.repo.StrmDownload.ClaimPendingDownload(ctx, 1)
+		tasks, err := s.repo.StrmDownload.ClaimPendingDownload(ctx, claimBatch)
 		if err != nil {
 			s.log.Warn("claim strm download task failed", zap.Error(err))
 			sleepContext(ctx, 3*time.Second)
@@ -52,9 +58,21 @@ func (s *StrmService) downloadWorker(ctx context.Context) {
 			sleepContext(ctx, 2*time.Second)
 			continue
 		}
+		// 并发处理本批任务：每个任务先获取全局下载槽位，槽位内部执行换链+下载。
+		// 信号量与令牌桶双重限速，确保任意时刻并发换链请求不超过安全阈值。
+		var wg sync.WaitGroup
 		for i := range tasks {
-			s.processDownloadTask(ctx, &tasks[i])
+			wg.Add(1)
+			go func(i int) {
+				defer wg.Done()
+				if !s.acquireDownloadSlot(ctx) {
+					return
+				}
+				defer s.releaseDownloadSlot()
+				s.processDownloadTask(ctx, &tasks[i])
+			}(i)
 		}
+		wg.Wait()
 	}
 }
 
@@ -139,7 +157,7 @@ func (s *StrmService) processUploadTask(ctx context.Context, task *model.StrmUpl
 		}
 	}
 	if task.Provider == model.StrmProvider115 {
-		finish(model.StrmTaskFailed, "115 网盘暂不支持元数据上传")
+		s.processUpload115(ctx, task)
 		return
 	}
 	acct, err := s.repo.StrmAccount.FindByID(ctx, task.AccountID)
@@ -178,6 +196,48 @@ func (s *StrmService) processUploadTask(ctx context.Context, task *model.StrmUpl
 	finish(model.StrmTaskDone, "")
 }
 
+// processUpload115 115 元数据上传：task.RemotePath 存的是父目录 cid，FileName 为远端文件名。
+func (s *StrmService) processUpload115(ctx context.Context, task *model.StrmUploadTask) {
+	finish := func(status, message string) {
+		now := time.Now()
+		task.Status = status
+		task.Error = message
+		task.FinishedAt = &now
+		if err := s.repo.StrmUpload.Update(context.Background(), task); err != nil {
+			s.log.Warn("update strm upload task failed", zap.Error(err))
+		}
+	}
+	acct, err := s.repo.StrmAccount.FindByID(ctx, task.AccountID)
+	if err != nil || acct == nil {
+		finish(model.StrmTaskFailed, "网盘账号不存在")
+		return
+	}
+	provider, err := s.providerFor(ctx, acct)
+	if err != nil {
+		s.uploadTaskFailWithRetry(task, err.Error())
+		return
+	}
+	named, ok := provider.(interface {
+		PutFileNamed(ctx context.Context, parentCID, fileName string, r io.Reader) error
+	})
+	if !ok {
+		finish(model.StrmTaskFailed, "该网盘不支持元数据上传")
+		return
+	}
+	f, err := os.Open(task.LocalPath)
+	if err != nil {
+		s.uploadTaskFailWithRetry(task, "打开本地文件失败："+err.Error())
+		return
+	}
+	if err := named.PutFileNamed(ctx, task.RemotePath, task.FileName, f); err != nil {
+		_ = f.Close()
+		s.uploadTaskFailWithRetry(task, "上传失败："+err.Error())
+		return
+	}
+	_ = f.Close()
+	finish(model.StrmTaskDone, "")
+}
+
 // downloadTaskFailWithRetry 下载失败任务按退避重试，超过上限标记 failed。
 func (s *StrmService) downloadTaskFailWithRetry(task *model.StrmDownloadTask, message string) {
 	if !retryTask(&task.RetryCount, &task.Status, &task.Error, &task.NextTryAt, &task.FinishedAt, message) {
@@ -501,6 +561,16 @@ func (s *StrmService) ClearFinishedDownloadTasks(ctx context.Context) (int64, er
 	return s.repo.StrmDownload.ClearFinished(ctx)
 }
 
+// ClearCanceledDownloadTasks 清空全部已取消的下载记录，返回删除数量。
+func (s *StrmService) ClearCanceledDownloadTasks(ctx context.Context) (int64, error) {
+	return s.repo.StrmDownload.ClearCanceled(ctx)
+}
+
+// ClearCanceledUploadTasks 清空全部已取消的上传记录，返回删除数量。
+func (s *StrmService) ClearCanceledUploadTasks(ctx context.Context) (int64, error) {
+	return s.repo.StrmUpload.ClearCanceled(ctx)
+}
+
 // RetryAllFailedDownloadTasks 批量重试所有失败下载任务，返回重新入队数量。
 func (s *StrmService) RetryAllFailedDownloadTasks(ctx context.Context) (int64, error) {
 	return s.repo.StrmDownload.RetryAllFailed(ctx)

internal/service/strm_service.go

@@ -90,11 +90,48 @@ type StrmService struct {
 	running       map[string]context.CancelFunc // sync path id -> cancel
 	oauthSessions map[string]*strm115AuthSession
 	wafUntil      time.Time // 115 风控/限流熔断截止时间（由 mu 保护）
+
+	downloadSem chan struct{} // 全局下载并发信号量：限制整个进程同时进行「换直链+下载」的并发数
+	downloadSemOnce sync.Once
 }
 
 // strmWAFCooldown 检测到 115 风控/限流后下载队列的全局冷却时长。
 const strmWAFCooldown = 3 * time.Minute
 
+// strmDownloadSemCap 全局同时进行「换直链+下载」的并发上限。
+//
+// 115 对换直链接口（/open/ufile/downurl）风控极严：过去把全局 QPS 提到 8 或让多
+// worker 高并发换链，会瞬时撞上 WAF 返回 405 阻断页并触发 180 秒冷却，反而更慢。
+// 因此用信号量把整个进程同时换直链的并发数压到 3，与令牌桶限速共同兜底：
+// 宁可下载稍慢，也绝不触发风控。下载本身走 CDN 不限速。
+const strmDownloadSemCap = 3
+
+// ensureDownloadSem 惰性初始化全局共享的下载并发信号量。
+func (s *StrmService) ensureDownloadSem() {
+	s.downloadSemOnce.Do(func() {
+		s.downloadSem = make(chan struct{}, strmDownloadSemCap)
+	})
+}
+
+// acquireDownloadSlot 获取一个下载并发槽位（等待/取消安全）。
+func (s *StrmService) acquireDownloadSlot(ctx context.Context) bool {
+	s.ensureDownloadSem()
+	select {
+	case s.downloadSem <- struct{}{}:
+		return true
+	case <-ctx.Done():
+		return false
+	}
+}
+
+// releaseDownloadSlot 释放一个下载并发槽位。
+func (s *StrmService) releaseDownloadSlot() {
+	if s.downloadSem == nil {
+		return
+	}
+	<-s.downloadSem
+}
+
 // NewStrmService constructs the STRM service.
 func NewStrmService(cfg *config.Config, log *zap.Logger, repos *repository.Container, crypto *CryptoService) *StrmService {
 	return &StrmService{
@@ -113,6 +150,7 @@ func NewStrmService(cfg *config.Config, log *zap.Logger, repos *repository.Conta
 // Start 启动下载/上传队列 worker、定时同步巡检、115 token 刷新与队列清理。
 func (s *StrmService) Start(ctx context.Context) {
 	s.sync115RelayKey(ctx)
+	s.recoverInterruptedSyncs(ctx)
 	downloadThreads := s.strmIntSetting(ctx, StrmSettingDownloadThreads, 3)
 	if downloadThreads < 1 {
 		downloadThreads = 1
@@ -141,6 +179,21 @@ func (s *StrmService) Start(ctx context.Context) {
 		zap.Int("upload_threads", uploadThreads))
 }
 
+// recoverInterruptedSyncs 在服务启动时自愈重置因服务重启遗留的 running 状态。
+func (s *StrmService) recoverInterruptedSyncs(ctx context.Context) {
+	paths, err := s.repo.StrmSyncPath.List(ctx)
+	if err == nil {
+		for i := range paths {
+			p := &paths[i]
+			if p.LastSyncStatus == model.StrmSyncRecordRunning {
+				p.LastSyncStatus = model.StrmSyncRecordCanceled
+				p.LastSyncMessage = "服务重启，已重置同步状态"
+				_ = s.repo.StrmSyncPath.Update(ctx, p)
+			}
+		}
+	}
+}
+
 func (s *StrmService) Stop() {
 	s.stopOnce.Do(func() { close(s.stopCh) })
 }
@@ -396,6 +449,38 @@ func (s *StrmService) ListSyncRecords(ctx context.Context, pathID string, limit
 	return s.repo.StrmSyncRecord.List(ctx, pathID, limit)
 }
 
+// DeleteSyncRecord 删除单条同步记录。
+func (s *StrmService) DeleteSyncRecord(ctx context.Context, id string) error {
+	if err := s.repo.StrmSyncRecord.Delete(ctx, id); err != nil {
+		return err
+	}
+	return nil
+}
+
+// ClearSyncRecords 清空某同步目录（pathID 为空则全部）的同步记录，返回删除条数。
+func (s *StrmService) ClearSyncRecords(ctx context.Context, pathID string) (int64, error) {
+	if pathID != "" {
+		return s.repo.StrmSyncRecord.DeleteBySyncPathID(ctx, pathID)
+	}
+	var total int64
+	// 全量清空：分页拉取物理删除所有记录
+	for {
+		rows, err := s.repo.StrmSyncRecord.List(ctx, "", 200)
+		if err != nil {
+			return total, err
+		}
+		if len(rows) == 0 {
+			return total, nil
+		}
+		for _, rec := range rows {
+			if err := s.repo.StrmSyncRecord.Delete(ctx, rec.ID); err != nil {
+				return total, err
+			}
+		}
+		total += int64(len(rows))
+	}
+}
+
 // CreateSyncPath 校验并创建同步目录。
 func (s *StrmService) CreateSyncPath(ctx context.Context, p *model.StrmSyncPath) (*model.StrmSyncPath, error) {
 	if err := s.validateSyncPath(ctx, p); err != nil {

internal/service/strm_sync.go

@@ -40,11 +40,16 @@ type strmSyncState struct {
 	seenVideo           map[string]bool  // "v:"+去掉扩展名的相对路径 → 远端存在该视频
 	seenMeta            map[string]bool  // "m:"+相对路径 → 远端存在该元数据
 	remoteMeta          map[string]int64 // 远端元数据大小（上传比对用）
-	activeDownloadPaths map[string]bool  // 本地已在排队/进行的下载任务路径（内存去重）
-	activeUploadPaths   map[string]bool  // 本地已在排队/进行的上传任务路径（内存去重）
+	seenMetaTarget      map[string]cloud.FileEntry
+	seenVideoTarget     map[string]cloud.FileEntry
+	activeDownloadPaths map[string]bool // 本地已在排队/进行的下载任务路径（内存去重）
+	activeUploadPaths   map[string]bool // 本地已在排队/进行的上传任务路径（内存去重）
 	pendingDownloads    []*model.StrmDownloadTask
 	pendingUploads      []*model.StrmUploadTask
-	dirCache            sync.Map // dirID (string) -> relativePath (string)
+	dirCache            sync.Map          // dirID (string) -> relativePath (string)
+	dirPathToID         map[string]string // relativePath (string) -> dirID（115 上传父目录寻址用，walk 后构建）
+
+	scanIncomplete atomic.Bool // 远端目录树/文件列表本次扫描不完整 → 禁止增量 prune 误删本地文件
 }
 
 // StartSync 启动一次同步（异步执行，同一目录同时只允许一个任务）。
@@ -104,15 +109,27 @@ func (s *StrmService) StartSync(ctx context.Context, pathID string, syncType ...
 	return nil
 }
 
-// CancelSync 取消正在进行的同步。
+// CancelSync 取消正在进行的同步（若为僵尸运行状态则直接自愈重置）。
 func (s *StrmService) CancelSync(ctx context.Context, pathID string) error {
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	cancel, exists := s.running[pathID]
-	if !exists {
-		return errors.New("该目录当前没有进行中的同步")
+	if exists {
+		delete(s.running, pathID)
+	}
+	s.mu.Unlock()
+
+	if exists && cancel != nil {
+		cancel()
+	}
+
+	// 无论内存中是否活跃，确保同步目录状态正确重置为已取消
+	if p, err := s.repo.StrmSyncPath.FindByID(ctx, pathID); err == nil && p != nil {
+		if p.LastSyncStatus == model.StrmSyncRecordRunning {
+			p.LastSyncStatus = model.StrmSyncRecordCanceled
+			p.LastSyncMessage = "已取消"
+			_ = s.repo.StrmSyncPath.Update(ctx, p)
+		}
 	}
-	cancel()
 	return nil
 }
 
@@ -160,15 +177,17 @@ func (s *StrmService) runSync(ctx context.Context, p *model.StrmSyncPath, rec *m
 		return
 	}
 	st := &strmSyncState{
-		s:          s,
-		ctx:        ctx,
-		p:          p,
-		cfg:        cfg,
-		rec:        rec,
-		syncType:   rec.SyncType,
-		seenVideo:  map[string]bool{},
-		seenMeta:   map[string]bool{},
-		remoteMeta: map[string]int64{},
+		s:               s,
+		ctx:             ctx,
+		p:               p,
+		cfg:             cfg,
+		rec:             rec,
+		syncType:        rec.SyncType,
+		seenVideo:       map[string]bool{},
+		seenMeta:        map[string]bool{},
+		remoteMeta:      map[string]int64{},
+		seenMetaTarget:  map[string]cloud.FileEntry{},
+		seenVideoTarget: map[string]cloud.FileEntry{},
 	}
 	if p.Provider != model.StrmProviderLocal {
 		acct, err := s.repo.StrmAccount.FindByID(ctx, p.AccountID)
@@ -216,8 +235,8 @@ func (s *StrmService) finishSync(p *model.StrmSyncPath, rec *model.StrmSyncRecor
 		if rec.SyncType == model.StrmSyncTypeFull {
 			syncTypeLabel = "全量"
 		}
-		p.LastSyncMessage = fmt.Sprintf("[%s] 完成：新增/更新 %d 个 strm，跳过 %d 个，下载 %d 个元数据，清理 %d 个文件",
-			syncTypeLabel, rec.NewStrm, rec.Skipped, rec.NewMeta, rec.Pruned)
+		p.LastSyncMessage = fmt.Sprintf("[%s] 完成：新增/更新 %d 个 strm，跳过 %d 个，下载 %d 个元数据，上传 %d 个元数据，清理 %d 个文件",
+			syncTypeLabel, rec.NewStrm, rec.Skipped, rec.NewMeta, rec.Uploaded, rec.Pruned)
 	}
 	if err := s.repo.StrmSyncPath.Update(context.Background(), p); err != nil {
 		s.log.Warn("update strm sync path failed", zap.Error(err))
@@ -225,7 +244,7 @@ func (s *StrmService) finishSync(p *model.StrmSyncPath, rec *model.StrmSyncRecor
 	s.log.Info("strm sync finished",
 		zap.String("path_id", p.ID), zap.String("sync_type", rec.SyncType), zap.String("status", status),
 		zap.Int64("new_strm", rec.NewStrm), zap.Int64("skipped", rec.Skipped), zap.Int64("new_meta", rec.NewMeta),
-		zap.Int64("pruned", rec.Pruned), zap.String("message", message))
+		zap.Int64("uploaded", rec.Uploaded), zap.Int64("pruned", rec.Pruned), zap.String("message", message))
 }
 
 func (st *strmSyncState) run() error {
@@ -264,7 +283,21 @@ func (st *strmSyncState) run() error {
 	}
 	st.flushPendingDownloads()
 	st.flushProgress()
-	if st.cfg.UploadMeta && st.provider != nil && st.p.Provider != model.StrmProvider115 {
+	if st.cfg.UploadMeta && st.provider != nil {
+		// 115 上传需要父目录 cid，先用 dirCache 构建「路径 → cid」反向索引
+		if st.p.Provider == model.StrmProvider115 {
+			reversed := map[string]string{}
+			st.dirCache.Range(func(key, value any) bool {
+				path, ok := value.(string)
+				if ok && path != "" {
+					if id, ok2 := key.(string); ok2 {
+						reversed[path] = id
+					}
+				}
+				return true
+			})
+			st.dirPathToID = reversed
+		}
 		if err := st.scanLocalMetaForUpload(); err != nil {
 			return err
 		}
@@ -423,6 +456,29 @@ func (st *strmSyncState) isMetaExt(ext string) bool {
 	return false
 }
 
+// cleanDirRel 对 115 扁平化拉取的目录相对路径逐段套用目录级文件名清洗，
+// 确保与 walkRemote / joinLocalRel（sanitizeRelativePath）使用同一套清洗规则。
+// 若不清洗，目录名中的冒号等非法字符会直达 rel，而 seenVideo/seenMeta 的 key
+// 与磁盘实际路径不一致，导致 pruneLocal 误删已下载的 strm / 元数据。
+// 空 rel（根目录）原样返回。
+func cleanDirRel(rel string) string {
+	if rel == "" {
+		return ""
+	}
+	parts := strings.Split(rel, "/")
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if part == "" {
+			continue
+		}
+		clean := cleanEntryName(part, true)
+		if clean != "" && clean != "." && clean != ".." {
+			out = append(out, clean)
+		}
+	}
+	return strings.Join(out, "/")
+}
+
 // walk115Flat 使用 115 开放平台扁平化分页批量拉取机制与目录拓扑缓存（参考 QMediaSync）。
 // 极大地降低 API 请求次数并支持毫秒级/秒级增量同步。
 func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
@@ -440,23 +496,23 @@ func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
 		if err := st.s.repo.StrmDirCache.DeleteBySyncPathID(ctx, st.p.ID); err != nil {
 			st.s.log.Warn("delete strm dir cache failed", zap.Error(err))
 		}
-		} else {
-			// 增量同步：预加载历史目录缓存（过滤历史一对多塌陷冲突的脏数据以自愈刷新）
-			cached, err := st.s.repo.StrmDirCache.ListBySyncPathID(ctx, st.p.ID)
-			if err == nil {
-				pathCounts := make(map[string]int, len(cached))
-				for _, item := range cached {
-					pathCounts[item.Path]++
-				}
-				for _, item := range cached {
-					// 若同一个 path 对应了多个不同 dir_id，说明包含历史层级塌陷的脏数据，不预加载，让后续步骤重新向 115 获取精确路径
-					if pathCounts[item.Path] > 1 {
-						continue
-					}
-					st.dirCache.Store(item.DirID, item.Path)
+	} else {
+		// 增量同步：预加载历史目录缓存（过滤历史一对多塌陷冲突的脏数据以自愈刷新）
+		cached, err := st.s.repo.StrmDirCache.ListBySyncPathID(ctx, st.p.ID)
+		if err == nil {
+			pathCounts := make(map[string]int, len(cached))
+			for _, item := range cached {
+				pathCounts[item.Path]++
+			}
+			for _, item := range cached {
+				// 若同一个 path 对应了多个不同 dir_id，说明包含历史层级塌陷的脏数据，不预加载，让后续步骤重新向 115 获取精确路径
+				if pathCounts[item.Path] > 1 {
+					continue
 				}
+				st.dirCache.Store(item.DirID, cleanDirRel(item.Path))
 			}
 		}
+	}
 
 	// 2. 探测文件总数
 	const pageSize = 1150
@@ -465,6 +521,8 @@ func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
 		return fmt.Errorf("115: 获取文件列表失败：%w", err)
 	}
 
+	st.updateSyncMessage(fmt.Sprintf("正在拉取远端文件列表 (共 %d 个文件)...", totalCount))
+
 	allFiles := make([]cloud115.RemoteFile, 0, totalCount)
 	allFiles = append(allFiles, firstBatch...)
 
@@ -492,7 +550,7 @@ func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
 		}
 		close(taskCh)
 
-		workers := 4
+		workers := 8
 		if len(pageTasks) < workers {
 			workers = len(pageTasks)
 		}
@@ -557,12 +615,16 @@ func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
 
 		var (
 			pwg        sync.WaitGroup
-			dirWorkers = 4
+			dirWorkers = 8
+			doneDirs   atomic.Int64
+			totalDirs  = len(pidList)
 		)
 		if len(pidList) < dirWorkers {
 			dirWorkers = len(pidList)
 		}
 
+		st.updateSyncMessage(fmt.Sprintf("正在解析目录树 (0/%d)...", totalDirs))
+
 		for i := 0; i < dirWorkers; i++ {
 			pwg.Add(1)
 			go func() {
@@ -571,47 +633,58 @@ func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
 					if ctx.Err() != nil {
 						return
 					}
+					if _, loaded := st.dirCache.Load(pid); loaded {
+						if n := doneDirs.Add(1); n%20 == 0 || n == int64(totalDirs) {
+							st.updateSyncMessage(fmt.Sprintf("正在解析目录树 (%d/%d)...", n, totalDirs))
+						}
+						continue
+					}
 					detail, err := open115.GetFsDetailByCid(ctx, pid)
 					if err != nil {
 						st.s.log.Warn("115: 获取目录详情失败", zap.String("pid", pid), zap.Error(err))
-						continue
-					}
-					if detail == nil {
-						continue
-					}
-					// 解析相对路径
-					relPath := detail.RelativePath(rootCID)
-					st.dirCache.Store(pid, relPath)
-					_ = st.s.repo.StrmDirCache.Set(ctx, st.p.ID, pid, relPath)
+						// 目录详情解析失败会导致下游文件 rel 无法还原真实父路径，
+						// seen key 与磁盘路径对不上，增量 prune 会误删本地文件，标记本次扫描不完整。
+						st.scanIncomplete.Store(true)
+					} else if detail != nil {
+						// 解析相对路径
+						relPath := cleanDirRel(detail.RelativePath(rootCID))
+						st.dirCache.Store(pid, relPath)
+						_ = st.s.repo.StrmDirCache.Set(ctx, st.p.ID, pid, relPath)
 
-					// 顺便解析并缓存 detail.Paths 中包含的中间各层级目录
-					for _, ancestor := range detail.Paths {
-						if ancestor.FileId == "0" || ancestor.FileId == rootCID {
-							continue
-						}
-						if _, loaded := st.dirCache.Load(ancestor.FileId); !loaded {
+						// 顺便解析并缓存 detail.Paths 中包含的中间各层级目录
+						for _, ancestor := range detail.Paths {
+							if ancestor.FileId == "0" || ancestor.FileId == rootCID {
+								continue
+							}
+							if _, loaded := st.dirCache.Load(ancestor.FileId); !loaded {
 								subDetail := &cloud115.RemoteFileDetail{
 									FileId:   ancestor.FileId,
 									FileName: ancestor.Name,
 									Paths:    nil,
 								}
-							for _, p := range detail.Paths {
-								subDetail.Paths = append(subDetail.Paths, p)
-								if p.FileId == ancestor.FileId {
-									break
+								for _, p := range detail.Paths {
+									subDetail.Paths = append(subDetail.Paths, p)
+									if p.FileId == ancestor.FileId {
+										break
+									}
 								}
+								ancestorRel := cleanDirRel(subDetail.RelativePath(rootCID))
+								st.dirCache.Store(ancestor.FileId, ancestorRel)
+								_ = st.s.repo.StrmDirCache.Set(ctx, st.p.ID, ancestor.FileId, ancestorRel)
 							}
-							ancestorRel := subDetail.RelativePath(rootCID)
-							st.dirCache.Store(ancestor.FileId, ancestorRel)
-							_ = st.s.repo.StrmDirCache.Set(ctx, st.p.ID, ancestor.FileId, ancestorRel)
 						}
 					}
+					if n := doneDirs.Add(1); n%10 == 0 || n == int64(totalDirs) {
+						st.updateSyncMessage(fmt.Sprintf("正在解析目录树 (%d/%d)...", n, totalDirs))
+					}
 				}
 			}()
 		}
 		pwg.Wait()
 	}
 
+	st.updateSyncMessage(fmt.Sprintf("正在生成 STRM 与同步文件 (共 %d 个)...", len(allFiles)))
+
 	// 5. 分类处理所有文件
 	for _, f := range allFiles {
 		if ctx.Err() != nil {
@@ -623,8 +696,13 @@ func (st *strmSyncState) walk115Flat(open115 *cloud115.OpenClient) error {
 			rel = cleanName
 		} else {
 			if parentVal, ok := st.dirCache.Load(f.Pid); ok && parentVal.(string) != "" {
-				rel = parentVal.(string) + "/" + cleanName
+				rel = cleanDirRel(parentVal.(string)) + "/" + cleanName
 			} else {
+				// 父目录不在目录缓存（目录详情先前解析失败），无法还原真实相对路径。
+				// 该文件会落到根/错误路径，seen key 与磁盘路径不符，增量 prune 会误删，标记扫描不完整。
+				if st.syncType == model.StrmSyncTypeIncremental {
+					st.scanIncomplete.Store(true)
+				}
 				rel = cleanName
 			}
 		}
@@ -660,6 +738,18 @@ func (st *strmSyncState) handleVideo(entry cloud.FileEntry, rel, ext string) {
 		return
 	}
 
+	st.mu.Lock()
+	if st.seenVideoTarget == nil {
+		st.seenVideoTarget = map[string]cloud.FileEntry{}
+	}
+	if _, exists := st.seenVideoTarget[target]; exists {
+		st.mu.Unlock()
+		st.touchProgress()
+		return
+	}
+	st.seenVideoTarget[target] = entry
+	st.mu.Unlock()
+
 	// 增量同步模式快速检查：本地 strm 文件存在、非空且修改时间与远端 mtime 一致，直接跳过无需读磁盘
 	if st.syncType == model.StrmSyncTypeIncremental && entry.MTime > 0 {
 		if info, err := os.Stat(target); err == nil && info.Size() > 0 && info.ModTime().Unix() == entry.MTime {
@@ -809,6 +899,20 @@ func (st *strmSyncState) handleMeta(entry cloud.FileEntry, rel, ext string) {
 	if err != nil {
 		return
 	}
+
+	st.mu.Lock()
+	if st.seenMetaTarget == nil {
+		st.seenMetaTarget = map[string]cloud.FileEntry{}
+	}
+	if _, exists := st.seenMetaTarget[target]; exists {
+		// 该本地目标路径在当前批次中已被处理（存在同名/重名冲突），直接忽略重复项，避免多份不同大小的文件在本地交替覆盖导致增量死循环
+		st.mu.Unlock()
+		st.touchProgress()
+		return
+	}
+	st.seenMetaTarget[target] = entry
+	st.mu.Unlock()
+
 	if info, err := os.Stat(target); err == nil && info.Size() == entry.Size {
 		st.touchProgress()
 		return
@@ -910,124 +1014,124 @@ func (st *strmSyncState) walkLocalSource() error {
 		if err != nil {
 			return nil
 		}
-			target, err := joinLocalRel(st.p.LocalPath, relSansExt+".strm")
-			if err != nil {
-				return nil
-			}
-			mTime := info.ModTime()
-			if st.syncType == model.StrmSyncTypeIncremental {
-				if tInfo, err := os.Stat(target); err == nil && tInfo.Size() > 0 && tInfo.ModTime().Unix() == mTime.Unix() {
-					st.mu.Lock()
-					st.rec.Skipped++
-					st.mu.Unlock()
-					st.touchProgress()
-					return nil
-				}
-			}
-			if data, err := os.ReadFile(target); err == nil && string(data) == content {
-				_ = os.Chtimes(target, mTime, mTime)
+		target, err := joinLocalRel(st.p.LocalPath, relSansExt+".strm")
+		if err != nil {
+			return nil
+		}
+		mTime := info.ModTime()
+		if st.syncType == model.StrmSyncTypeIncremental {
+			if tInfo, err := os.Stat(target); err == nil && tInfo.Size() > 0 && tInfo.ModTime().Unix() == mTime.Unix() {
 				st.mu.Lock()
 				st.rec.Skipped++
 				st.mu.Unlock()
 				st.touchProgress()
 				return nil
 			}
-			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
-				return nil
-			}
-			tmp := target + ".tmp"
-			if err := os.WriteFile(tmp, []byte(content), 0o644); err == nil {
-				_ = os.Rename(tmp, target)
-				_ = os.Chtimes(target, mTime, mTime)
-			} else {
-				_ = os.Remove(tmp)
-			}
+		}
+		if data, err := os.ReadFile(target); err == nil && string(data) == content {
+			_ = os.Chtimes(target, mTime, mTime)
 			st.mu.Lock()
-			st.rec.NewStrm++
+			st.rec.Skipped++
 			st.mu.Unlock()
 			st.touchProgress()
 			return nil
+		}
+		if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+			return nil
+		}
+		tmp := target + ".tmp"
+		if err := os.WriteFile(tmp, []byte(content), 0o644); err == nil {
+			_ = os.Rename(tmp, target)
+			_ = os.Chtimes(target, mTime, mTime)
+		} else {
+			_ = os.Remove(tmp)
+		}
+		st.mu.Lock()
+		st.rec.NewStrm++
+		st.mu.Unlock()
+		st.touchProgress()
+		return nil
 	})
 }
 
-	// scanLocalMetaForUpload 扫描本地元数据，与远端比对后入上传队列。
-	func (st *strmSyncState) scanLocalMetaForUpload() error {
-		defer st.flushPendingUploads()
-		if st.activeUploadPaths == nil {
-			if active, err := st.s.repo.StrmUpload.GetActiveLocalPathMap(st.ctx, st.p.ID); err == nil {
-				st.activeUploadPaths = active
-			} else {
-				st.activeUploadPaths = map[string]bool{}
-			}
+// scanLocalMetaForUpload 扫描本地元数据，与远端比对后入上传队列。
+func (st *strmSyncState) scanLocalMetaForUpload() error {
+	defer st.flushPendingUploads()
+	if st.activeUploadPaths == nil {
+		if active, err := st.s.repo.StrmUpload.GetActiveLocalPathMap(st.ctx, st.p.ID); err == nil {
+			st.activeUploadPaths = active
+		} else {
+			st.activeUploadPaths = map[string]bool{}
 		}
-		localRoot := filepath.Clean(st.p.LocalPath)
-		return filepath.WalkDir(localRoot, func(path string, d os.DirEntry, err error) error {
-			if err != nil {
-				return nil
-			}
-			if path == localRoot {
-				return nil
-			}
-			select {
-			case <-st.ctx.Done():
-				return st.ctx.Err()
-			default:
-			}
-			if d.IsDir() {
-				return nil
-			}
-			rel, err := filepath.Rel(localRoot, path)
-			if err != nil {
-				return nil
-			}
-			rel = filepath.ToSlash(rel)
-			ext := strings.ToLower(filepath.Ext(rel))
-			if !st.isMetaExt(ext) {
-				return nil
-			}
-			info, err := d.Info()
-			if err != nil {
-				return nil
-			}
-			st.mu.Lock()
-			_, exists := st.remoteMeta["m:"+rel]
-			st.mu.Unlock()
-			if exists {
-				// 网盘端已存在该元数据文件，跳过上传
-				return nil
-			}
-			st.mu.Lock()
-			if st.activeUploadPaths != nil && st.activeUploadPaths[path] {
-				st.mu.Unlock()
-				return nil
-			}
-			if st.activeUploadPaths != nil {
-				st.activeUploadPaths[path] = true
-			}
-			st.mu.Unlock()
-
-			task := &model.StrmUploadTask{
-				SyncPathID: st.p.ID,
-				AccountID:  st.p.AccountID,
-				Provider:   st.p.Provider,
-				FileName:   filepath.Base(rel),
-				LocalPath:  path,
-				RemotePath: st.remoteUploadPath(rel),
-				Size:       info.Size(),
-				Status:     model.StrmTaskPending,
-			}
-			st.mu.Lock()
-			st.pendingUploads = append(st.pendingUploads, task)
-			shouldFlush := len(st.pendingUploads) >= 100
-			st.rec.Uploaded++
-			st.mu.Unlock()
-
-			if shouldFlush {
-				st.flushPendingUploads()
-			}
-			return nil
-		})
 	}
+	localRoot := filepath.Clean(st.p.LocalPath)
+	return filepath.WalkDir(localRoot, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if path == localRoot {
+			return nil
+		}
+		select {
+		case <-st.ctx.Done():
+			return st.ctx.Err()
+		default:
+		}
+		if d.IsDir() {
+			return nil
+		}
+		rel, err := filepath.Rel(localRoot, path)
+		if err != nil {
+			return nil
+		}
+		rel = filepath.ToSlash(rel)
+		ext := strings.ToLower(filepath.Ext(rel))
+		if !st.isMetaExt(ext) {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return nil
+		}
+		st.mu.Lock()
+		_, exists := st.remoteMeta["m:"+rel]
+		st.mu.Unlock()
+		if exists {
+			// 网盘端已存在该元数据文件，跳过上传
+			return nil
+		}
+		st.mu.Lock()
+		if st.activeUploadPaths != nil && st.activeUploadPaths[path] {
+			st.mu.Unlock()
+			return nil
+		}
+		if st.activeUploadPaths != nil {
+			st.activeUploadPaths[path] = true
+		}
+		st.mu.Unlock()
+
+		task := &model.StrmUploadTask{
+			SyncPathID: st.p.ID,
+			AccountID:  st.p.AccountID,
+			Provider:   st.p.Provider,
+			FileName:   filepath.Base(rel),
+			LocalPath:  path,
+			RemotePath: st.uploadRemoteTarget(rel),
+			Size:       info.Size(),
+			Status:     model.StrmTaskPending,
+		}
+		st.mu.Lock()
+		st.pendingUploads = append(st.pendingUploads, task)
+		shouldFlush := len(st.pendingUploads) >= 100
+		st.rec.Uploaded++
+		st.mu.Unlock()
+
+		if shouldFlush {
+			st.flushPendingUploads()
+		}
+		return nil
+	})
+}
 
 // remoteUploadPath 远端元数据目标路径 = 同步目录远端根 + 相对路径。
 func (st *strmSyncState) remoteUploadPath(rel string) string {
@@ -1038,6 +1142,31 @@ func (st *strmSyncState) remoteUploadPath(rel string) string {
 	return root + "/" + rel
 }
 
+// uploadRemoteTarget 返回上传任务的目标远端描述。
+//   - 115：返回父目录 cid（供 PutFileNamed 定位），基于 dirPathToID 把父目录相对路径映射到 cid。
+//   - 网盘桥接（clouddrive2/openlist）：返回完整远端路径。
+func (st *strmSyncState) uploadRemoteTarget(rel string) string {
+	if st.p.Provider == model.StrmProvider115 {
+		dir := rel
+		if idx := strings.LastIndexByte(dir, '/'); idx >= 0 {
+			dir = dir[:idx]
+		} else {
+			dir = ""
+		}
+		if dir == "" {
+			// 文件在同步根目录下，父目录即 115 同步根目录 ID
+			return st.p.RemotePath
+		}
+		if cid, ok := st.dirPathToID[dir]; ok && cid != "" {
+			return cid
+		}
+		// 父目录未在缓存中（父目录可能本次未扫描到），降级为用户配置的同步根 cid，
+		// 由上传端尽力处理（可能失败记日志，不影响下载）。
+		return st.p.RemotePath
+	}
+	return st.remoteUploadPath(rel)
+}
+
 // taskExists 检查是否已有同目录、同目标的进行中/已完成任务（避免重复入队）。
 func (st *strmSyncState) taskExists(kind, syncPathID, localPath string) bool {
 	ctx := st.ctx
@@ -1053,6 +1182,14 @@ func (st *strmSyncState) taskExists(kind, syncPathID, localPath string) bool {
 
 // pruneLocal 清理本地多余 .strm 与元数据（远端已不存在），可选删除空目录。
 func (st *strmSyncState) pruneLocal() error {
+	// 增量同步保护：本次远端扫描不完整（目录详情解析失败 / 文件父路径降级）时，
+	// seenVideo/seenMeta 覆盖不全，按"远端不存在"清理会误删刚下载或已存在的本地文件，
+	// 进而触发"下次增量重新下载"的循环。此时跳过清理，仅做进度落库。
+	if st.syncType == model.StrmSyncTypeIncremental && st.scanIncomplete.Load() {
+		st.s.log.Warn("strm 增量同步跳过清理：本次远端扫描不完整，prune 已禁用",
+			zap.String("path_id", st.p.ID))
+		return nil
+	}
 	localRoot := filepath.Clean(st.p.LocalPath)
 	var dirs []string
 	err := filepath.WalkDir(localRoot, func(path string, d os.DirEntry, err error) error {
@@ -1138,6 +1275,18 @@ func (st *strmSyncState) flushProgress() {
 	}
 }
 
+// updateSyncMessage 实时更新同步阶段提示信息，让前端界面清晰了解当前进度。
+func (st *strmSyncState) updateSyncMessage(msg string) {
+	st.mu.Lock()
+	st.rec.Message = msg
+	st.p.LastSyncMessage = msg
+	rec := *st.rec
+	p := *st.p
+	st.mu.Unlock()
+	_ = st.s.repo.StrmSyncRecord.Update(st.ctx, &rec)
+	_ = st.s.repo.StrmSyncPath.Update(st.ctx, &p)
+}
+
 // ─── 定时同步巡检 ──────────────────────────────────────────────────────────────
 
 func (s *StrmService) cronLoop(ctx context.Context) {

internal/service/strm_sync_test.go

@@ -554,8 +554,82 @@ func TestWalkRemoteConcurrent(t *testing.T) {
 		}
 		wg.Wait()
 
-		if claimedCount != 200 {
-			t.Fatalf("expected all 200 tasks claimed, got %d", claimedCount)
+			if claimedCount != 200 {
+				t.Fatalf("expected all 200 tasks claimed, got %d", claimedCount)
+			}
+		}
+
+	// TestStrmDuplicateFileConflictResolution 测试远端存在多个同名不同大小文件时，本地确定性仲裁，避免增量死循环
+	func TestStrmDuplicateFileConflictResolution(t *testing.T) {
+		svc := testStrmService(t)
+		localDir := t.TempDir()
+
+		p := &model.StrmSyncPath{
+			Base:         model.Base{ID: "dup-test-path"},
+			Provider:     model.StrmProvider115,
+			RemotePath:   "root",
+			LocalPath:    localDir,
+			DownloadMeta: true,
+		}
+
+		st := &strmSyncState{
+			s:               svc,
+			ctx:             context.Background(),
+			p:               p,
+			cfg:             &strmPathConfig{DownloadMeta: true, MetaExt: []string{"nfo"}},
+			rec:             &model.StrmSyncRecord{},
+			seenMeta:        map[string]bool{},
+			remoteMeta:      map[string]int64{},
+			seenMetaTarget:  map[string]cloud.FileEntry{},
+			seenVideoTarget: map[string]cloud.FileEntry{},
+		}
+
+		// 模拟远端同目录下存在两个同名不同大小的 nfo 文件 (115 历史重复上传)
+		// entry1: 较早文件 (MTime: 1000, Size: 100)
+		entry1 := cloud.FileEntry{ID: "f1", Name: "test.nfo", Size: 100, MTime: 1000, PickCode: "p1"}
+		// entry2: 较新文件 (MTime: 2000, Size: 200)
+		entry2 := cloud.FileEntry{ID: "f2", Name: "test.nfo", Size: 200, MTime: 2000, PickCode: "p2"}
+
+		// 第一次全量处理：两者都在列表中
+		st.handleMeta(entry1, "test.nfo", ".nfo")
+		st.handleMeta(entry2, "test.nfo", ".nfo")
+		st.flushPendingDownloads()
+
+		// 验证仲裁结果：最终只产生 1 个下载任务，且使用的是首个匹配项 (Size 100/p1)
+		tasks, _, err := svc.repo.StrmDownload.List(context.Background(), "", 1, 10)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(tasks) != 1 {
+			t.Fatalf("expected 1 download task after conflict resolution, got %d", len(tasks))
+		}
+		if tasks[0].Size != 100 || tasks[0].RemoteRef != "p1" {
+			t.Fatalf("expected task with size 100/p1, got size=%d ref=%s", tasks[0].Size, tasks[0].RemoteRef)
+		}
+
+		// 模拟该任务下载落盘完成
+		writeFile(t, filepath.Join(localDir, "test.nfo"), strings.Repeat("x", 100))
+
+		// 第二次增量同步：两者再次依次扫描
+		st2 := &strmSyncState{
+			s:               svc,
+			ctx:             context.Background(),
+			p:               p,
+			cfg:             &strmPathConfig{DownloadMeta: true, MetaExt: []string{"nfo"}},
+			rec:             &model.StrmSyncRecord{},
+			seenMeta:        map[string]bool{},
+			remoteMeta:      map[string]int64{},
+			seenMetaTarget:  map[string]cloud.FileEntry{},
+			seenVideoTarget: map[string]cloud.FileEntry{},
+		}
+		st2.handleMeta(entry1, "test.nfo", ".nfo")
+		st2.handleMeta(entry2, "test.nfo", ".nfo")
+		st2.flushPendingDownloads()
+
+		// 验证：不会新增任何下载任务，NewMeta 为 0，增量跳过
+		if st2.rec.NewMeta != 0 {
+			t.Fatalf("expected 0 new meta on incremental sync, got %d", st2.rec.NewMeta)
 		}
 	}
 
+

test_rel.go

@@ -1,25 +0,0 @@
-package main
-import (
-	"context"
-	"fmt"
-	"github.com/ShukeBta/MMTL/internal/service"
-	"github.com/ShukeBta/MMTL/internal/service/cloud115"
-	"go.uber.org/zap"
-)
-func main() {
-	crypto := service.NewCryptoService("test-secret", zap.NewNop())
-	// Let's test with a mock RemoteFileDetail
-	d := &cloud115.RemoteFileDetail{
-		FileId: "3251154147730910635",
-		FileName: "出包王女",
-		Paths: []struct {
-			FileId string 
-			Name   string 
-		}{
-			{FileId: "0", Name: "根目录"},
-			{FileId: "3238787832374488117", Name: "影视库"},
-			{FileId: "3238787913223892116", Name: "动漫"},
-		},
-	}
-	fmt.Println("RelativePath when rootCID is 3238787832374488117:", d.RelativePath("3238787832374488117"))
-}

web/embed.go

@@ -0,0 +1,23 @@
+// Package webui embeds the built React SPA so a single binary can serve the
+// UI without requiring a separate web/dist directory on disk. The embed
+// happens at compile time, so `web/dist` must exist before `go build` runs
+// (the CI pipeline builds it via `npm run build` first).
+package webui
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:dist
+var distFS embed.FS
+
+// DistFS returns the embedded SPA build artifacts rooted at the directory
+// containing index.html (i.e. web/dist).
+func DistFS() fs.FS {
+	sub, err := fs.Sub(distFS, "dist")
+	if err != nil {
+		panic(err)
+	}
+	return sub
+}

web/src/api/library.ts

@@ -102,6 +102,9 @@ export const libraryAPI = {
   createWithRoots: (name: string, type: string, roots: LibraryRootInput[], coverURL = '') =>
     api.post<Library>('/libraries', { name, type, roots, cover_url: coverURL }).then((r) => r.data),
 
+  createPerSubfolder: (parentPath: string, type: string, coverURL = '') =>
+    api.post<{ libraries: Library[] }>('/libraries', { path: parentPath, type, cover_url: coverURL, create_per_subfolder: true }).then((r) => r.data),
+
   update: (id: string, payload: { cover_url: string }) =>
     api.patch<Library>(`/libraries/${id}`, payload).then((r) => r.data),
 

web/src/api/strm.ts

@@ -117,6 +117,13 @@ export const strmAPI = {
       .get<StrmSyncRecord[]>('/admin/strm/records', { params: pathId ? { path_id: pathId } : {} })
       .then((r) => r.data),
 
+  deleteRecord: (id: string) => api.delete(`/admin/strm/records/${id}`).then((r) => r.data),
+
+  clearRecords: (pathId?: string) =>
+    api
+      .delete<{ deleted: number }>('/admin/strm/records', { params: pathId ? { path_id: pathId } : {} })
+      .then((r) => r.data),
+
   // ── 本地目录浏览（同步目录选择器） ────────────────────────
   listLocalDirs: (path?: string) =>
     api
@@ -143,6 +150,9 @@ export const strmAPI = {
   clearFinishedDownloads: () =>
     api.post<{ deleted: number }>('/admin/strm/downloads/clear-finished').then((r) => r.data),
 
+  clearCanceledDownloads: () =>
+    api.post<{ deleted: number }>('/admin/strm/downloads/clear-canceled').then((r) => r.data),
+
   retryFailedDownloads: () =>
     api.post<{ retried: number }>('/admin/strm/downloads/retry-failed').then((r) => r.data),
 
@@ -162,6 +172,9 @@ export const strmAPI = {
   cancelPendingUploads: () =>
     api.post<{ canceled: number }>('/admin/strm/uploads/cancel-pending').then((r) => r.data),
 
+  clearCanceledUploads: () =>
+    api.post<{ deleted: number }>('/admin/strm/uploads/clear-canceled').then((r) => r.data),
+
   retryUpload: (id: string) =>
     api.post(`/admin/strm/uploads/${id}/retry`).then((r) => r.data),
 }

web/src/pages/AdminLibraryPanel.tsx

@@ -13,9 +13,11 @@ export function AdminLibraryPanel() {
         type={createForm.type}
         coverURL={createForm.coverURL}
         roots={createForm.roots}
+        createPerSubfolder={createForm.createPerSubfolder}
         onNameChange={createForm.setName}
         onTypeChange={createForm.setType}
         onCoverURLChange={createForm.setCoverURL}
+        onCreatePerSubfolderChange={createForm.setCreatePerSubfolder}
         onRootChange={createForm.updateRoot}
         onAddRoot={createForm.addRoot}
         onRemoveRoot={createForm.removeRoot}

web/src/pages/AdminLibraryPanelSections.tsx

@@ -9,9 +9,11 @@ type CreateFormProps = {
   type: string
   coverURL: string
   roots: RootDraft[]
+  createPerSubfolder: boolean
   onNameChange: (value: string) => void
   onTypeChange: (value: string) => void
   onCoverURLChange: (value: string) => void
+  onCreatePerSubfolderChange: (value: boolean) => void
   onRootChange: (index: number, patch: Partial<RootDraft>) => void
   onAddRoot: () => void
   onRemoveRoot: (index: number) => void
@@ -23,9 +25,11 @@ export function AdminLibraryCreateForm({
   type,
   coverURL,
   roots,
+  createPerSubfolder,
   onNameChange,
   onTypeChange,
   onCoverURLChange,
+  onCreatePerSubfolderChange,
   onRootChange,
   onAddRoot,
   onRemoveRoot,
@@ -50,9 +54,9 @@ export function AdminLibraryCreateForm({
     <>
       <form onSubmit={onSubmit} className="glass-panel grid gap-3 md:grid-cols-4">
         <input
-          required
+          required={!createPerSubfolder}
           className="input-base"
-          placeholder="名称"
+          placeholder={createPerSubfolder ? '父级媒体库名（批量模式忽略）' : '名称'}
           value={name}
           onChange={(e) => onNameChange(e.target.value)}
         />
@@ -81,15 +85,31 @@ export function AdminLibraryCreateForm({
               onRemove={onRemoveRoot}
             />
           ))}
-          <button type="button" className="inline-flex items-center gap-2 rounded-lg border px-3 py-2 text-sm" onClick={onAddRoot}>
-            <Plus size={16} /> 添加路径
-          </button>
+          {!createPerSubfolder && (
+            <button type="button" className="inline-flex items-center gap-2 rounded-lg border px-3 py-2 text-sm" onClick={onAddRoot}>
+              <Plus size={16} /> 添加路径
+            </button>
+          )}
         </div>
         <p className="md:col-span-4 -mt-2 text-xs text-sand-500">
           支持直接点选或手动输入；名称和类型与现有媒体库一致时，会自动把这里填写的路径追加到该媒体库。
         </p>
+        <label className="md:col-span-4 flex items-center gap-2 text-sm text-ink-100">
+          <input
+            type="checkbox"
+            className="h-4 w-4 accent-brand-400"
+            checked={createPerSubfolder}
+            onChange={(e) => onCreatePerSubfolderChange(e.target.checked)}
+          />
+          <span>按目录下每个子文件夹各建一个媒体库（媒体库名取子文件夹名）</span>
+        </label>
+        {createPerSubfolder && (
+          <p className="md:col-span-4 -mt-2 text-xs text-sand-500">
+            批处理模式：仅取上方第一个路径作为父级目录，会为其中每个子文件夹分别创建媒体库，可自选类型用于整体推断。
+          </p>
+        )}
         <button type="submit" className="neon-button md:col-span-4">
-          新建 / 追加路径
+          {createPerSubfolder ? '按目录批量创建' : '新建 / 追加路径'}
         </button>
       </form>
 

web/src/pages/StrmManagePage.tsx

@@ -211,7 +211,7 @@ export function StrmManagePage() {
             onCancel={cancelSync}
           />
 
-          <RecordSection records={records} />
+          <RecordSection records={records} onDeleted={refresh} />
         </>
       )}
 
@@ -453,13 +453,48 @@ function SyncPathSection({
 
 // ─── 同步记录 ────────────────────────────────────────────────────────────────
 
-function RecordSection({ records }: { records: StrmSyncRecord[] }) {
+function RecordSection({ records, onDeleted }: { records: StrmSyncRecord[]; onDeleted: () => void }) {
+  const [deletingId, setDeletingId] = useState<string | null>(null)
+
+  const deleteRecord = async (record: StrmSyncRecord) => {
+    const ok = await confirmAction({ message: '确定删除这条同步记录？', confirmText: '删除' })
+    if (!ok) return
+    setDeletingId(record.id)
+    try {
+      await strmAPI.deleteRecord(record.id)
+      toast.success('已删除同步记录')
+      onDeleted()
+    } catch (err) {
+      toast.error(apiErrorMessage(err))
+    } finally {
+      setDeletingId(null)
+    }
+  }
+
+  const clearRecords = async () => {
+    const ok = await confirmAction({ message: '确定清空全部同步记录？此操作不可恢复。', confirmText: '清空' })
+    if (!ok) return
+    try {
+      const res = await strmAPI.clearRecords()
+      toast.success(`已清空 ${res.deleted} 条同步记录`)
+      onDeleted()
+    } catch (err) {
+      toast.error(apiErrorMessage(err))
+    }
+  }
+
   return (
     <section className="glass-panel space-y-3 p-5">
       <div className="flex items-center gap-2">
         <History size={18} className="text-brand-500" />
         <h2 className="font-display text-lg font-semibold text-ink-600">同步记录</h2>
         <span className="rounded-full bg-gray-100 px-2 py-0.5 text-[11px] text-sand-500">{records.length}</span>
+        {records.length > 0 && (
+          <button type="button" onClick={clearRecords} className={iconButtonCls + ' ml-auto'}>
+            <Trash2 size={14} />
+            清空
+          </button>
+        )}
       </div>
       {records.length === 0 ? (
         <p className="rounded-xl bg-gray-50 px-4 py-6 text-center text-sm text-sand-500">还没有同步记录</p>
@@ -475,8 +510,10 @@ function RecordSection({ records }: { records: StrmSyncRecord[] }) {
                 <th className="px-3 py-2 text-right">新增/更新</th>
                 <th className="px-3 py-2 text-right">跳过</th>
                 <th className="px-3 py-2 text-right">下载元数据</th>
+                <th className="px-3 py-2 text-right">上传元数据</th>
                 <th className="px-3 py-2 text-right">清理</th>
                 <th className="px-3 py-2">说明</th>
+                <th className="px-3 py-2"></th>
               </tr>
             </thead>
             <tbody>
@@ -502,8 +539,20 @@ function RecordSection({ records }: { records: StrmSyncRecord[] }) {
                     <td className="px-3 py-2 text-right text-brand-500">{record.new_strm}</td>
                     <td className="px-3 py-2 text-right text-gray-500">{record.skipped}</td>
                     <td className="px-3 py-2 text-right">{record.new_meta}</td>
+                    <td className="px-3 py-2 text-right">{record.uploaded ?? 0}</td>
                     <td className="px-3 py-2 text-right">{record.pruned}</td>
                     <td className="max-w-[260px] truncate px-3 py-2 text-xs text-sand-500">{record.message}</td>
+                    <td className="px-3 py-2 text-right">
+                      <button
+                        type="button"
+                        onClick={() => deleteRecord(record)}
+                        disabled={deletingId === record.id}
+                        title="删除记录"
+                        className="rounded-md p-1 text-sand-400 transition hover:bg-rose-50 hover:text-rose-500 disabled:opacity-40"
+                      >
+                        <Trash2 size={15} />
+                      </button>
+                    </td>
                   </tr>
                 )
               })}

web/src/pages/StrmQueuePage.tsx

@@ -127,6 +127,19 @@ function StrmQueuePanel({ kind }: { kind: 'download' | 'upload' }) {
         'border-amber-200 text-amber-600 hover:bg-amber-50',
         cancelAllPendingAction,
       )
+    if (filter === 'canceled')
+      return batchBtn(
+        '清空已取消记录',
+        'trash',
+        'border-gray-200 text-rose-500 hover:bg-rose-50',
+        () =>
+          runBatch(
+            isDownload
+              ? () => strmAPI.clearCanceledDownloads()
+              : () => strmAPI.clearCanceledUploads(),
+            `确定清空所有已取消的${isDownload ? '下载' : '上传'}记录？`,
+          ),
+      )
     if (!isDownload) return null
     if (filter === 'done')
       return batchBtn(

web/src/pages/useAdminLibraryPanel.ts

@@ -32,20 +32,32 @@ function useCreateLibraryForm(refresh: () => Promise<void>) {
   const [roots, setRoots] = useState<RootDraft[]>([emptyRootDraft()])
   const [type, setType] = useState('movie')
   const [coverURL, setCoverURL] = useState('')
+  const [createPerSubfolder, setCreatePerSubfolder] = useState(false)
 
   const handleCreate = async (e: FormEvent) => {
     e.preventDefault()
     try {
-      const payload = createRootPayload(roots)
-      if (payload.length === 0) {
-        toast.error('请至少填写一个路径')
-        return
+      if (createPerSubfolder) {
+        const parentPath = roots[0]?.path?.trim()
+        if (!parentPath) {
+          toast.error('请先选择或填写父级目录')
+          return
+        }
+        const { libraries } = await libraryAPI.createPerSubfolder(parentPath, type, coverURL.trim())
+        toast.success(`已按目录创建 ${libraries.length} 个媒体库`)
+      } else {
+        const payload = createRootPayload(roots)
+        if (payload.length === 0) {
+          toast.error('请至少填写一个路径')
+          return
+        }
+        await libraryAPI.createWithRoots(name, type, payload, coverURL.trim())
+        toast.success('媒体库已保存')
       }
-      await libraryAPI.createWithRoots(name, type, payload, coverURL.trim())
-      toast.success('媒体库已保存')
       setName('')
       setRoots([emptyRootDraft()])
       setCoverURL('')
+      setCreatePerSubfolder(false)
       await refresh()
     } catch (err: unknown) {
       toast.error(apiErrorMessage(err, '创建失败'))
@@ -61,9 +73,11 @@ function useCreateLibraryForm(refresh: () => Promise<void>) {
     type,
     coverURL,
     roots,
+    createPerSubfolder,
     setName,
     setType,
     setCoverURL,
+    setCreatePerSubfolder,
     updateRoot,
     addRoot: () => setRoots((prev) => [...prev, emptyRootDraft()]),
     removeRoot: (index: number) => setRoots((prev) => (prev.length <= 1 ? prev : prev.filter((_, i) => i !== index))),