desstg/mypan repository overview

⁠MyPan 使用说明

MyPan 是一个自托管的网盘聚合面板。它把 115、夸克、百度、天翼等网盘挂到同一个界面里浏览和管理，并且围绕「影视库」这件事做了一整套自动化：扫描网盘 → 生成 STRM → 刮削海报和 NFO → 整理目录 → 通知 Emby/Jellyfin 刷新。生成的 STRM 文件可以被 Emby、Jellyfin、飞牛影视直接播放，播放时走网盘直链，不占服务器硬盘。

程序是一个单二进制 + 内嵌网页界面，全部配置和数据落在一个 SQLite 文件里，用 Docker 部署。

⁠目录

• 一、功能详解⁠
  • 1. 多网盘聚合⁠
  • 2. 文件管理⁠
  • 3. 在线预览⁠
  • 4. STRM 直连播放⁠
  • 5. STRM 刮削⁠
  • 6. 目录整理⁠
  • 7. 自动联动⁠
  • 8. 跨盘传输⁠
  • 9. 挂载：WebDAV 与 FUSE⁠
  • 10. 离线下载⁠
  • 11. 缓存保持⁠
  • 12. 媒体端反代⁠
  • 13. 任务、日志、备份、通知⁠
  • 14. 辅助工具⁠
• 二、部署⁠
• 三、已知限制⁠
• 四、常见问题⁠

⁠一、功能详解

⁠1. 多网盘聚合

一个界面管理所有网盘账号，支持多账号并存、切换、启用/禁用、设置默认账号。

各网盘能力并不一致，下面这些差异会直接影响你能用哪些功能：

⁠2. 文件管理

• 浏览：列表 / 网格两种视图，面包屑导航，会记住上次浏览的位置。
• 操作：新建文件夹、重命名、移动、复制、删除、下载。
• 上传：支持上传文件、上传整个文件夹，有独立的传输任务面板可以暂停 / 恢复 / 批量删除。
• 收藏夹：把常用目录收藏起来，支持重命名、排序、拖拽整理。
• 命名对齐：批量规范化影视文件名，先预览再应用。
• 拖拽移动：直接把文件拖到文件夹上完成移动（悬停约 0.6 秒才会触发，避免误操作）。
• 一键生成 STRM：在任意目录直接为当前目录生成 STRM，不用先去建任务。

⁠3. 在线预览

不用下载就能看。共 9 类预览：

视频预览还额外支持：

• 字幕：SRT / VTT / SUP（图形字幕），按文件名自动匹配中/英/日/韩多语言
• 剧集连播（自动跳下一集）、0.5–2 倍速、全屏
• 快捷键：←/→ 快退快进 10 秒、↑/↓ 音量、空格 播放暂停、N/P 切换剧集、M 静音

⁠4. STRM 直连播放

这是 MyPan 的核心。它扫描网盘目录，为每个视频文件生成一个 .strm 文本文件（内容是一行播放地址），Emby / Jellyfin / 飞牛影视扫描到这个文件后，播放时请求会打到 MyPan，由 MyPan 换取网盘直链并 302 跳转过去。

好处是：媒体服务器不占用本地硬盘，也不消耗服务器带宽（直链模式下流量直接从网盘到播放器）。

STRM 任务的配置项：

• 扫描模式：增量补缺（只补新增）/ 增量更新 / 全量同步
• 调度方式：时间窗口（在指定时段内跑）/ 手动
• 分组目录 + 输出目录：生成的 .strm 落到哪里
• 文件扩展名：决定哪些格式生成 STRM
• 排除目录 / 排除文件名关键字
• 分支：一个任务下可以建多条「入口分支」和「监控分支」，监控分支可设保留天数，适合临时追更某个剧集
• 元数据同步、冲突策略

配套工具：

• 播放地址替换：网盘直链的域名变了，批量改掉已有 .strm 里的地址
• 账号引用修复：账号重建后修复 .strm 里失效的账号引用
• 115 目录树清单增强：115 独有的全量列目录加速

⁠5. STRM 刮削

扫描 STRM 任务产出的目录，自动匹配 TMDB，写出 NFO（movie.nfo / tvshow.nfo / 分季分集 NFO）和 海报图，让 Emby / Jellyfin 直接就有海报墙。

• 界面上是一个海报墙，可以直接看到哪些匹配上了、哪些没匹配上
• 单条操作：重新匹配（换 TMDB ID）、重新刮削（同 ID 重跑）、标记为正常（清掉错误匹配）
• 写入模式：只补缺失 / 全部覆盖
• 支持电视剧的连载状态跟踪（已完结 / 连载中）
• 可以限定刮削范围（排除某些目录）

⁠6. 目录整理

TMDB 识别 → 生成计划 → 预览 → 应用。识别出的影片会被改名并移动到目标目录，命名规则可以对齐媒体标签（分辨率 / 编码 / 音轨 / 声道）。

计划在应用前完全可编辑 —— 可以逐条修改、删除，也可以批量删掉误识别的，确认无误再执行。

提供两套互相独立的识别方案：

• TMDB 方案：适合电影和电视剧
• 番号方案：基于规则匹配，带小文件删除、空目录清理、扫描目录限制

还有：

• 分类整理：自定义分类模板
• AI 辅助识别：对低置信度的匹配用 AI 再判一次（默认接 DeepSeek 兼容接口，需自行配置）

⁠7. 自动联动

把上面这些串成流水线。规则 = 触发器 + 一串动作。

触发器：每天定时 / 每隔 N 小时 / Webhook / 离线下载完成

动作（按顺序执行）：延迟 → 刷新目录缓存 → 目录整理 → 生成 STRM → 刮削 → 通知 Emby 刷新 → 补全 Emby 媒体信息

每个动作可以设执行条件：总是执行 / 上一步成功才执行 / 上一步失败才执行。目录整理还能设风险阈值（匹配风险超过阈值就停下等你人工确认）。

有运行记录可查。

Webhook 走 /api/open/automation/events，需要用 API 秘钥鉴权，可以按事件和路径前缀匹配。

⁠8. 跨盘传输

把文件从一个网盘搬到另一个网盘，两种模式：

• 跨盘秒传：先扫描源目录算出哈希，再探测目标盘能不能秒传，能就秒传（几乎是瞬间完成），不能就自动降级为「中转上传」（先下载到服务器再上传）。
• 跨盘普传：老老实实下载再上传，适合目标盘不支持秒传的情况。

冲突策略可选：跳过 / 重命名 / 覆盖。

⁠9. 挂载：WebDAV 与 FUSE

把网盘挂出去给自己用。注意：这是挂载，不是生成公开分享链接 —— MyPan 没有分享链接功能。

WebDAV

开启后通过 /dav/<账号>/... 访问，用管理员账号密码做 Basic 认证。支持列目录、下载、上传、重命名、移动、删除、新建目录。目录列表有缓存可加速。

FUSE 本地挂载

把网盘目录挂成本机文件系统路径，让其他程序（比如 Emby、qBittorrent、各种播放器）能像读本地文件一样读网盘。

• 支持读写 —— 往挂载点里写的文件会被暂存，然后自动转为上传任务传到网盘
• 每个挂载点可单独设 UID / GID、开机自动挂载
• 账号重新授权后会自动重新挂载
• FUSE 读缓存：把读过的数据块缓存在本地磁盘，明显加快重复读取。缓存大小、保留天数、淘汰策略（LRU / 大文件优先）都可配，建议把缓存目录放到更快的盘上

⁠10. 离线下载

有两条路：

网盘离线下载 —— 把链接或种子交给网盘，让网盘自己去下（不占服务器带宽）。支持情况见能力表⁠：115 最全（含磁力/种子），光鸭支持批量 URL，123 只支持单条 URL 且不能删除任务。

内置下载器 —— MyPan 自己下载，支持：

• HTTP / HTTPS：支持断点续传
• 磁力 / BitTorrent：基于 DHT，TCP/uTP 双协议

内置 BT 的默认监听端口是 42069（TCP + UDP），所以 Docker 里 EXPOSE 42069/tcp 42069/udp 就是它。用 host 网络时无需额外映射；用 bridge 网络记得把 TCP 和 UDP 都映射出去，否则 DHT 拿不到节点、速度会很差。

下载完成后会自动交接给上传任务传到目标网盘。可以设临时目录、全局限速、BT 端口。

⁠11. 缓存保持

网盘列目录是有成本的。缓存保持任务会在设定的时间窗口内主动遍历指定目录，把目录和元数据缓存焐热，这样你点进去浏览时是秒开，而不是转圈等网盘返回。

按账号设置扫描范围，支持立即运行、强制停止。它和 STRM / 目录整理任务在同一个账号上互斥，不会同时跑。

⁠12. 媒体端反代

给 Emby / Jellyfin / 飞牛影视用的代理层，把媒体服务器的 STRM 播放请求转成网盘 302 直链。

这样做的意义是降低直链直接暴露的风险，同时方便统一管理播放地址。

• Emby 反代：Emby/Jellyfin 配置、媒体库列表、触发刷新、补全媒体信息
• 飞牛影视反代：飞牛配置、端口、STRM 路径映射、直链客户端管理

⁠13. 任务、日志、备份、通知

任务系统：STRM、缓存保持、目录整理、自动联动、上传、离线下载全部落库，重启后自动恢复（会把上次异常中断的「运行中」状态纠正回来）。统一都有启用/禁用、立即运行、强制停止、进度查看。

日志：分级（debug/info/warn/error），按天落文件在 data/log。可设日志级别和保留天数，启动时自动清理过期日志。界面上可以查看、统计、确认错误、一键清理。

备份：生成 .lpb 备份文件（可选密码加密），支持完整备份和仅设置备份。恢复是在下次启动时应用的，失败会回滚。注意备份加密用的是 MyPan_SECRET_KEY。

通知与公告：站内通知中心（带未读数）+ 后台公告弹窗。

⁠14. 辅助工具

⁠二、部署

⁠环境要求

• 一台能跑 Docker 的机器（NAS、小主机、VPS 都行）
• 如果要使用 FUSE 挂载：宿主机需要 /dev/fuse，容器需要 privileged: true 和 pid: "host"
• 不需要额外装数据库，SQLite 是内嵌的
• 镜像基于 scratch，里面只有一个静态二进制和一份根证书，没有任何系统工具

⁠方式一：Docker Compose（推荐）

新建一个目录，比如 /volume1/docker/MyPan，在里面建 docker-compose.yml：

services:
  MyPan:
    image: desstg/mypan:latest
    container_name: MyPan
    restart: unless-stopped
    ports:
      - "5211:5211"
      # 内置磁力的 TCP/uTP/DHT 监听端口；在后台改过端口的话这里要同步改
      - "42069:42069/tcp"
      - "42069:42069/udp"
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/app/data
      - ./strm:/app/strm
      - ./mounts:/app/mounts:shared

      # 可选：把 FUSE 读缓存单独放到更快的盘上
      # - ./fuse_read_cache:/app/data/fuse_read_cache
    devices:
      - /dev/fuse:/dev/fuse
    pid: "host"
    privileged: true

然后：

docker compose up -d

打开 http://你的IP:5211。

⁠方式二：host 网络（省掉端口映射）

NAS 上常用，尤其配合媒体服务器反代时：

services:
  MyPan:
    image: desstg/mypan:latest
    container_name: MyPan
    restart: unless-stopped
    network_mode: host        # 用了 host 网络就不要写 ports:
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /vol1/1000/docker/MyPan/data:/app/data
      - /vol1/1000/docker/MyPan/strm:/app/strm
      - /vol1/1000/docker/MyPan/mounts:/app/mounts:shared
    devices:
      - /dev/fuse:/dev/fuse
    pid: "host"
    privileged: true

host 网络下端口直接监听在宿主机上，5211 和 42069 都自动可用。

⁠方式三：docker run

docker run -d \
  --name MyPan \
  --restart unless-stopped \
  --pid host \
  --privileged \
  --device /dev/fuse \
  -p 5211:5211 \
  -p 42069:42069/tcp \
  -p 42069:42069/udp \
  -e TZ=Asia/Shanghai \
  -v /volume1/docker/MyPan/data:/app/data \
  -v /volume1/docker/MyPan/strm:/app/strm \
  -v /volume1/docker/MyPan/mounts:/app/mounts:shared \
  desstg/mypan:latest

加 --network host 的话去掉所有 -p。

⁠首次启动

1. 打开 http://你的IP:5211
2. 用默认账号 admin / admin 登录
3. 系统会强制你先改密码 —— 在改掉默认密码之前，后台其他页面都是锁定的，只会显示一个「导入备份」的卡片。这是正常行为，不是出错了。
4. 改完密码后，进入「存储管理」添加你的第一个网盘账号
5. 建议紧接着去「仪表盘 → 系统日志」确认没有报错

⁠目录说明

data 目录是全部身家，备份它等于备份了整个 MyPan。注意复制时要把 MyPan.db-wal 和 MyPan.db-shm 一起复制，否则可能丢最近的数据。

⁠环境变量

绝大多数配置都在网页后台里改，不需要碰环境变量。 上面这些是给特殊部署场景用的。

⁠网络：TMDB 访问不了怎么办

刮削和目录整理都依赖 TMDB。如果服务器连不上 api.themoviedb.org，有两个办法，二选一：

办法一：在「目录整理 → 设置」里填 TMDB 反代域名（会自动补 /3 和 /t/p）。

办法二：给容器加 hosts。Compose 写 extra_hosts，docker run 用 --add-host：

    extra_hosts:
      - "api.themoviedb.org:对应的IP"
      - "image.tmdb.org:对应的IP"

⁠端口说明

用不到内置磁力下载的话，42069 可以不映射。但如果要映射，TCP 和 UDP 必须都给，只给 TCP 会导致 DHT 找不到节点、下载极慢。

⁠群晖 / 飞牛注意事项

• 群晖的 Container Manager 图形界面不能完全覆盖这里的配置（尤其是 privileged 和 pid: host），建议用 SSH 跑 docker compose，配置文件放在 /volume1/docker/MyPan。
• 群晖的 Docker 没有 buildx 组件。如果你要自己构建镜像而不是拉现成的，注意源码里的 Dockerfile 已经适配了这一点（不能用 RUN --mount=type=cache 这类 BuildKit 专属语法）。
• 飞牛用 /vol1/1000/ 作为数据根路径，其它一样。

⁠三、已知限制

• 没有公开分享链接功能。 「文件共享」页面实际提供的是 WebDAV 和 FUSE 挂载，是给自己用的，不能生成一个链接发给别人下载。
• 秒传不是通用能力，只在部分网盘作为目标时生效，详见能力表⁠。
• 夸克不支持 302 直链，只能走本机代理，播放会走服务器带宽。
• .doc / .ppt / .rar / .7z 不能在线预览，需要下载后用本地程序打开。压缩包只支持 zip / cbz。
• FUSE 是编译期开关（-tags fuse）。官方镜像已经打开；如果你自己从源码编译，忘了加这个 tag 会得到「未编译 FUSE 支持」的报错。
• AI 整理和分类整理默认关闭，需要在设置里手动开启并配置（AI 默认接 DeepSeek 兼容接口）。

⁠四、常见问题

登录进去只看到一个「导入备份」的卡片，别的页面都点不动？ 正常，你在用默认密码。先改密码，其他页面就会解锁。

打开首页就跳登录页，不能免登录浏览？ 默认如此。「系统设置 → 账号安全」里有「允许匿名访问文件列表」开关，打开后不登录也能看文件列表。

FUSE 挂载失败？ 依次检查四件事：宿主机 /dev/fuse 是否存在、容器是不是 privileged: true、pid 是不是 "host"、mounts 卷有没有写 :shared。这四项缺任何一个都会挂不上，绝大多数情况是漏了 :shared。

Emby 里 STRM 播放不了？ 先确认 STRM 里的播放地址能被 Emby 所在机器访问到，再检查「系统设置」里的 STRM 基础地址是不是填的内网地址。如果网盘直链域名变了，用「播放地址替换」工具批量更新已有 STRM。

刮削一直失败 / 目录整理匹配不上？ 基本都是 TMDB 网络问题，参见上面的网络章节⁠。

磁力下载没速度？ 先确认 42069 的 TCP 和 UDP 都映射了。这是 DHT 节点发现的前提，只映射 TCP 会非常慢。

容器日志在哪？ ./data/log 目录下按天分文件。也可以在网页「仪表盘 → 系统日志」里看。注意镜像是 scratch 基础、没有 shell，docker exec 进不去，排障请用日志。