Home

欢迎来到 openlist_strm_bridge Wiki

openlist_strm_bridge 是一个专为 OpenList STRM 引擎“同步模式” 打造的本地与云端智能防灾协调层。

💡 项目核心定位

OpenList STRM 引擎能够高效地生成 .strm 文件供本地媒体库刮削使用。但在真实的生产环境中，用户通常面临以下严峻的自愈与防灾挑战：

1. 删除意图不一致：在媒体库（Emby/Plex等）中删除 STRM 文件后，云盘上的真实视频文件不会同步被删。
2. 网盘掉线误删灾难：当云盘由于网络、到期或掉签而失效时，同步程序可能因读取到“空目录”而误将本地媒体库一并清空。
3. 整理重命名冲突：刮削器（如 TMM）整理媒体库后会导致文件名变更，普通同步程序会重新同步一份“烂原名”文件，导致媒体库混乱和重复刮削。
4. 单兵逃逸与污染：用户手滑跨库移动、或者将文件提取至根目录，会导致云端结构与数据库映射彻底失效。

本中间件的目的就是：在 A区（引擎生成区）、B区（媒体库扫描区） 与 云端真实文件 之间建立一条由 SQLite 持久化、OpenList API 强绑定的自愈型桥梁。

---

🎨 核心系统架构图

graph TD
    subgraph Server [OpenList / WebDAV 服务端]
        Cloud[云端真实物理文件]
        API[Admin API / WebDAV 接口]
        Hook[刷新搜索索引钩子]
    end

    subgraph AreaA [A区 - 引擎输出层]
        A_DIR[OpenList STRM 自动生成]
    end

    subgraph Core [核心控制中枢 openlist_strm_bridge]
        Config[API抓取存储配置表<br>解析 SaveStrmLocalPath]
        Auth{网盘可用性探活<br>Fail-Safe断路器}
        Lineage{严格血统校验<br>层级边界与逃逸拦截}
        Fingerprint[洗白内容<br>计算唯一指纹]
        Score{命名打分机制<br>防劣质原名回灌}
        DB[(SQLite 状态映射库)]
    end

    subgraph AreaB [B区 - 媒体库消费层]
        B_DIR[用户整理 / 媒体库消费区]
        B_DUP[后缀隔离区 .duplicate / .invalid]
    end

    subgraph AreaC [C区 - 幽灵收容层]
        C_DIR[根目录失效/挂载点丢失<br>整体迁移收容所]
    end

    %% 数据关系
    Cloud -. OpenList引擎同步 .-> A_DIR
    A_DIR -->|1. 提取真实云路径| Fingerprint
    Fingerprint -->|2. 逆向层级追溯| Lineage
    
    Lineage -->|越界逃逸/脱群单个改名| 物理击毙[物理抹除非血统文件]
    Lineage -->|血统通过| Score
    
    Score -->|B区已有更优重命名| 跳过[跳过A区劣质原名]
    Score -->|指纹不存在于B区| DB
    DB -->|状态入库并复制| B_DIR
    
    B_DIR -->|用户改名/加深层级| Fingerprint
    B_DIR -->|用户删除 STRM| API
    
    API -->|调用 FS Mkdir 递归树 + Move| Cloud
    API -->|触发索引强制更新| Hook
    Hook -->|同步联动删除| A_DIR
    
    Auth -->|云盘掉线/网络异常| 阻断[熔断清理 保护媒体库]
    Auth -->|探活成功| 清理[清理B区死链与空目录]
    清理 -->|大类路径从引擎移除| C_DIR

Loading

---

🚨 终极警示：OpenList 令牌与播放签名的强依赖关系

由于 OpenList STRM 引擎下发的直链包含了具有安全时效的数字签名（?sign=）：

• 不可恢复的重置灾难：该签名是在 OpenList 服务端使用其内部的 Token / Secret 算出来的。绝对不要在 OpenList 后台轻易重置 Token 或服务端密钥。一旦重置，即使你本地所有的 STRM 路径保存完好、云端文件没有任何变动，已生成的 STRM 里的直链全部会报“签名失效”导致彻底无法播放。
• 系统绑定约束：本项目对于特定的 OpenList 服务端是强绑定的。如果迁移到新的服务器，必须清理本地 bridge.db 数据库及 B区文件，让新服务器重新建立全量生成。