Home

欢迎来到 openlist_strm_bridge Wiki

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

💡 项目核心定位

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

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

本中间件的目的就是：在 A区（引擎生成区）、B区（媒体库消费区） 与 云端真实文件 之间建立一条由 SQLite 持久化、OpenList Admin API 强绑定的自愈型桥梁，实现双向同步、血统校验、智能去重、字幕同步、熔断保护的完整闭环。

---

🏗️ 核心系统架构

graph TD
    subgraph Server [OpenList 服务端]
        Cloud[云端真实物理文件]
        AdminAPI[Admin API<br/>存储管理/索引刷新]
        WebDAV[WebDAV 接口<br/>文件操作/列目录]
        StrmEngine[STRM 引擎<br/>更新模式生成 STRM]
    end

    subgraph LocalFS [本地文件系统]
        AreaA[A区 - 引擎输出层<br/>OpenList STRM 自动生成]
        AreaB[B区 - 媒体库消费层<br/>用户整理/刮削/播放]
        AreaC[C区 - 幽灵收容层<br/>失效路径迁移/隔离]
        DB[(SQLite bridge.db<br/>10+ 表完整状态机)]
    end

    subgraph Core [核心控制中枢 openlist_strm_bridge]
        Config[配置系统<br/>TOML + 多 .txt + API动态映射]
        StorageMap[STRM存储映射表<br/>挂载点↔云端路径↔本地路径]
        Lineage[血统校验引擎<br/>Season层级/边界映射/单兵审判]
        Fingerprint[指纹系统<br/>SHA256规范化WebDAV路径]
        Scoring[命名打分机制<br/>标准命名>路径差异>长度>文件名]
        Ghost[幽灵保护<br/>防删除回灌/根目录快照]
        RefreshSvc[主动刷新服务<br/>交叉校验/只读模式/双阶段清理]
        SubtitleSvc[字幕同步服务<br/>电影/番剧双模式/语言标准化]
        Watchers[文件系统监控<br/>A/B/C三区独立事件处理]
    end

    %% 核心数据流
    StrmEngine -.更新模式同步.-> AreaA
    AreaA -->|1. 解析STRM提取WebDAV路径| Fingerprint
    Fingerprint -->|2. 逆向层级追溯+存储映射| Lineage
    Lineage -->|越界/单兵逃逸| 物理击毙[物理删除+A区恢复]
    Lineage -->|血统通过| Scoring
    Scoring -->|B区已有更优命名| 前置拦截[跳过劣质复制]
    Scoring -->|指纹不存在| DB
    DB -->|入库+复制| AreaB
    
    AreaB -->|用户改名/加深层级| Fingerprint
    AreaB -->|用户删除 STRM| WebDAV
    WebDAV -->|MOVE递归建目录+移动| Cloud
    AdminAPI -->|触发索引强制更新| StrmEngine
    StrmEngine -.同步联动删除.-> AreaA
    
    AdminAPI -->|探活存储状态| Ghost
    Ghost -->|掉线/异常| 熔断[保护B区不清理]
    Ghost -->|正常| RefreshSvc
    RefreshSvc -->|交叉校验路径| AreaB清理
    RefreshSvc -->|只读刷新| 非引擎路径
    RefreshSvc -->|Update模式| AreaA过期清理
    
    AreaB -->|字幕文件| SubtitleSvc
    SubtitleSvc -->|标准化命名+Season目录| AreaB
    
    Lineage -->|根目录失效| AreaC
    AreaC -->|人工核对| 手动恢复/清理

Loading

---

🚀 快速开始

目录结构

openlist_strm_bridge/
├── config.toml                 # 主配置文件 (TOML 格式)
├── a_folders.txt               # A区本地目录列表 (每行一个路径)
├── refresh_paths.txt           # WebDAV 主动刷新路径 (OpenList 路径)
├── strm_engine_paths.txt       # STRM 引擎入口路径 (OpenList 路径)
├── src/                        # 核心代码目录
│   ├── main.py                 # 程序入口
│   ├── app_service.py          # 核心服务逻辑 (~3200 行)
│   ├── config.py               # 配置加载 + API动态映射
│   ├── database.py             # SQLite 数据库 (WAL模式/线程安全)
│   ├── webdav_client.py        # WebDAV/OpenList Admin API 客户端
│   ├── utils.py                # 指纹/路径/文件操作工具
│   ├── area_watchers.py        # A/B/C三区文件系统事件处理
│   ├── refresh_service.py      # 主动刷新服务 (独立线程)
│   ├── media_renamer.py        # 媒体/字幕智能重命名
│   ├── logger_setup.py         # 日志配置 (轮转/级别)
│   ├── openlist_admin_api.py   # Admin API 封装
│   ├── test_openlist_admin_api.py
│   ├── requirements.txt        # Python 依赖
│   └── python_embed/           # 嵌入式 Python 3.14 环境
├── 环境变量启动.bat            # 系统 Python 启动脚本
├── 嵌入式启动.bat              # 嵌入式 Python 启动脚本 (推荐)
├── 启动aider.bat               # AI 助手启动脚本
├── stop_aider.bat              # 停止脚本
├── README.md
├── 工作流程.md
├── 设计思路.md
└── todo.md

配置文件说明

文件	用途	格式
config.toml	主配置：WebDAV、刷新、行为、日志、路径	TOML
a_folders.txt	A区本地监控目录 (OpenList STRM 输出目录)	每行一个绝对路径
refresh_paths.txt	主动刷新的 WebDAV 路径 (触发索引/清理)	每行一个 OpenList 路径
strm_engine_paths.txt	STRM 引擎入口路径 (用于访问引擎/检查状态)	每行一个 OpenList 路径

启动方式

1. 嵌入式 Python（推荐，无需安装 Python）：双击 嵌入式启动.bat
2. 系统 Python：双击 环境变量启动.bat（需系统 PATH 中有 Python 3.10+）

---

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

由于 OpenList STRM 引擎下发的直链包含了签名（?sign=）：

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

---

📚 Wiki 导航

文档	核心内容
📂 一、架构设计与 A/B/C 三区模型	三区定义、数据库 Schema (10+表)、8步启动自同步生命周期、存储映射系统
🛡️ 二、差异控制、动态 API 映射与探活断路器	主动刷新服务、交叉校验、只读刷新、Fail-Safe熔断、Update模式A区清理
🧬 三、严格血统校验与刮削整理边界约定	血统校验算法、Season层级处理、边界映射表、单兵30秒审判、群体改名检测
🧹 四、递归式回收站重建与 B区去重清理规则	MOVE递归建目录、三层校验清理、幽灵保护、命名打分机制、字幕同步
📝 五、字幕文件同步与标准化处理	电影/番剧双模式、语言检测标准化、从STRM推断季集、数据库记录去重
⚙️ 六、配置系统详解与存储映射	TOML配置结构、StrmStorageMapping三路映射、API动态加载、多存储分组
🔧 七、数据库设计完整参考	11张表完整Schema、索引设计、WAL模式、线程安全连接池