【ug-videokeeper】教联子保护播放、收藏数据，重刮削、移动文件夹再也不怕丢记录了

一、工具简介
项目地址：knifezred/ug-videokeeper

1.1 解决的核心痛点

使用绿联NAS自带「影视中心」的用户，普遍会遇到以下数据丢失问题：
· 手动修改的电影标题、简介、评分，点击「重新刮削」后全部被系统重置
· 全家人的播放进度、观看历史，在媒体库重建、更换硬盘后集体断链
· 标记的收藏、整理的合集，刮削后全部消失，手动整理的心血直接白费
· 视频文件改名、移动目录后，播放记录无法对应，数据直接丢失

ug-videokeeper 就是专门针对绿联影视中心的数据守护工具，全程后台静默运行，自动备份、自动恢复，彻底解决上述痛点。实现修改文件名/文件夹名、移动文件夹、重新刮削后不丢失播放记录、收藏状态。

1.2 工作原理

工具会在每部视频的目录下，自动生成一个隐藏文件.ugreen.json，完整备份影视中心数据库里的所有关键数据。当检测到数据库因刮削、重建被重置时，自动从备份文件中将数据原样恢复，实现「刮削前后，数据完全一致」。
· 不修改、不依赖任何NFO文件，不会和现有刮削工具产生冲突
· 备份文件跟随视频目录走，移盘、改名都不影响数据匹配
· 基于文件内容哈希匹配播放记录，路径、文件名变化都能精准对应

1.3 可保护的数据范围

数据类型	保护效果
手动编辑的标题、简介、评分	刮削后自动恢复，手动修改永久保留
播放进度、完整观看历史	多账号记录全部保存，永不丢失历史
收藏标记、合集归属	刮削、重建媒体库后自动恢复
电视剧剧集列表	全剧集信息完整备份
目录移动、文件改名	备份跟随文件走，数据自动匹配恢复

二、部署前准备

1. 硬件环境：绿联NAS
2. 软件环境：NAS已安装Docker（绿联自带Docker管理器即可）
3. 数据库信息：绿联影视中心默认使用PostgreSQL数据库，默认参数如下，无修改则无需调整：
· 默认端口：5433
· 默认数据库名：video
· 默认用户名：postgres
·   密码：若无设置则留空
4. 路径确认：提前记好你的影视媒体库所在的完整路径，例如/volume1/电影、/volume2/电视剧

三、Docker Compose 部署步骤（绿联NAS通用）

1. services:
   
2.   sync:
   
3.     image: knifez/ug-videokeeper:latest
   
4.     container_name: ug-videokeeper-sync
   
5.     restart: unless-stopped
   
6.     environment:
   
7.       - DB_HOST=127.0.0.1
   
8.       - DB_PORT=5433
   
9.       - DB_NAME=video
   
10.       - DB_USER=postgres
    
11.       - DB_PASSWORD=
    
12.       - SCAN_INTERVAL=3600
    
13.       - SYNC_MODE=bidirectional
    
14.       - DRY_RUN=false
    
15.       # - TARGET_PATH=/volume1/media/movie
    
16.       - LOG_LEVEL=INFO
    
17.     volumes:
    
18.       - 你的绿联媒体目录:/你的绿联媒体目录
    
19.       - ./data:/app/data
    
20.     network_mode: "host"          # 使用主机网络模式（保证服务发现正常）
    
21.     command: ["python", "main.py"]
    
22. 
    
23.   web:
    
24.     image: knifez/ug-videokeeper:latest
    
25.     container_name: ug-videokeeper-web
    
26.     restart: unless-stopped
    
27.     depends_on:
    
28.       - sync
    
29.     ports:
    
30.       - "8088:8088"
    
31.     volumes:
    
32.       - ./data:/app/data
    
33.     command: ["python", "main.py", "--serve"]
    

复制代码

步骤3：首次试运行（强烈建议必做）

为避免误操作影响数据库，首次启动请先开启试运行模式：
1. 在环境变量中添加一行：- DRY_RUN=true
2. 保存配置文件，启动容器
3. 打开容器日志，确认以下信息正常：
· 成功连接数据库
· 成功识别到媒体库中的视频文件
· 无报错、无异常警告
4. 确认一切正常后，将DRY_RUN=true修改为DRY_RUN=false，重启容器

步骤4：确认部署成功

容器正式运行后，进入你的视频目录，开启「显示隐藏文件」，如果能看到每部视频目录下都生成了.ugreen.json文件，说明备份已生效，部署成功。
四、关键配置参数说明

环境变量	必填	默认值	说明
DB_HOST	是	-	PostgreSQL数据库地址，本机部署填127.0.0.1
DB_PORT	否	5433	数据库端口，绿联影视中心默认为5433
DB_NAME	否	video	数据库名称，默认无需修改
DB_USER	否	postgres	数据库用户名，默认无需修改
DB_PASSWORD	否	空	数据库密码，无密码则留空
MEDIA_LIB_PATHS	否	空	Watchdog监控的媒体目录，多个用英文冒号分隔
WATCHDOG_ENABLED	否	true	是否开启NFO文件实时监控
SCAN_INTERVAL	否	3600	周期同步间隔，单位秒；设为0则仅运行一次后进入纯监控模式
DRY_RUN	否	false	试运行模式，仅扫描不写入数据库，首次部署建议开启
TARGET_PATH	否	空	限定同步路径范围，仅处理该前缀下的视频，用于小范围测试
LOG_LEVEL	否	INFO	日志级别，可选DEBUG/INFO/WARNING/ERROR

五、核心功能与使用说明

1. 定时周期同步


工具默认每1小时自动执行一次全量检查：
· 检测到数据库有新的播放、收藏、元数据编辑操作 → 自动将最新数据备份到.ugreen.json
· 检测到刮削导致数据被重置 → 自动从备份文件恢复数据到数据库全程无需手动操作，后台静默运行，资源占用极低。
2. NFO文件实时监控（Watchdog）


开启后，工具会实时监控媒体目录中的NFO文件变化。如果你手动编辑了movie.nfo并保存，工具会自动将修改的字段合并到备份文件，再同步回影视中心数据库，无需手动触发重新刮削。
3. 完整播放历史保护


绿联影视中心数据库默认仅保留最新一条播放记录，而.ugreen.json会保存全部播放历史，同步时自动合并去重，永久保留所有观看记录。
4. 目录移动与文件改名兼容

· 移动视频文件夹到其他硬盘/其他路径：备份文件跟随目录移动，工具自动匹配新的目录ID，全部数据恢复
· 重命名视频文件：基于文件内容哈希匹配，文件名变化不影响播放记录对应


六、常见问题 FAQ


Q：电视剧的数据也能保护吗？
A：可以。电视剧目录同样会生成.ugreen.json文件，包含元数据全字段、剧集列表、播放记录、收藏与合集信息。
Q：每次同步都会扫描所有文件吗？会不会很卡？
A：不会。首次运行建立数据基线后，后续仅通过时间戳和内容哈希对比，无变化的文件直接跳过，日常运行对NAS性能几乎无影响。
Q：不小心删掉了.ugreen.json文件怎么办？
A：无需担心，下一次周期同步时，工具会自动从数据库重新生成该备份文件。
Q：可以只保护部分目录吗？
A：可以。通过TARGET_PATH参数限定路径前缀，工具就只会处理该路径下的视频，适合小范围测试。
Q：工具会修改我的NFO文件吗？
A：绝对不会。工具仅读取NFO文件的字段进行合并，不会写入、修改任何NFO文件，所有数据都保存在独立的.ugreen.json中。


七、使用建议与注意事项

1. 首次部署务必先开启DRY_RUN=true试运行，确认数据库连接和路径配置无误后再正式运行
2. 媒体目录的挂载路径，容器内必须和宿主机完全一致，否则会导致文件识别失败
3. 日常使用建议将同步间隔设置为1-2小时，兼顾数据安全性与性能开销
4. 可定期查看容器日志，确认工具运行状态正常
5. 项目开源免费，觉得好用可以去GitHub给作者点个Star支持


八、致谢

感谢 wa3ytsm 对本项目的启发和指导

你又出山了

蓝小白 发表于 2026-7-6 21:24
你又出山了

这功能靠联子遥遥无期啊，后续准备加上年度报告

不爱思考 发表于 2026-7-7 08:12
这功能靠联子遥遥无期啊，后续准备加上年度报告

继续  我等稳定版  哈哈

已填坑
1.docker-compose添加如下内容,对齐调整下
  network_mode: "host"
      - MEDIA_LIB_PATHS=/volume4/disk4/library:/volume3/云盘下载
volumes:
      - /volume4/disk4/library:/volume4/disk4/library
      - /volume3/云盘下载:/volume3/云盘下载
      - ./app:/app
    working_dir: /app
    command: sh -c "pip install -r requirements.txt && python main.py"
变量介绍
MEDIA_LIB_PATHS        Watchdog 监控的媒体目录（多个用 : 分隔）
volumes:  映射媒体库目录
2.app目录下手动创建data目录

相册有么

同步失败:
duplicate key value violates unique constraint "idx_uid_once_ph"
[ERROR] 同步失败: duplicate key value violates unique constraint "idx_uid_once_ph"
DETAIL:  Key (uid, category_id, file_id)=(1000, afd79b8ef365a402380afe5224531662, 77020) already exists.
Traceback (most recent call last):
  File "/app/scheduler.py", line 57, in _do_sync
    run_sync()
  File "/app/sync/executor.py", line 48, in run_sync
    _process_tv(conn, fr, folder, cache, stats)
  File "/app/sync/executor.py", line 217, in _process_tv
    _restore_tv_from_ugreen(conn, ug, folder, cat_changed=cat_changed)
  File "/app/sync/executor.py", line 261, in _restore_tv_from_ugreen
    db_sync.upsert_play_history(conn, ug.play_history, folder, "")
  File "/app/db/sync.py", line 209, in upsert_play_history
    cur.execute(
psycopg2.errors.UniqueViolation: duplicate key value violates unique constraint "idx_uid_once_ph"
DETAIL:  Key (uid, category_id, file_id)=(1000, afd79b8ef365a402380afe5224531662, 77020) already exists.

大佬，碰到这个问题怎么解决呀？

CN_4248 发表于 2026-7-12 09:54
同步失败:
duplicate key value violates unique constraint "idx_uid_once_ph"
[ERROR] 同步失败: duplic ...

看着是数据库已有重复值,删掉这条数据看下

可见光 发表于 2026-7-12 08:18
相册有么

这个没看到有数据库

CN_4248 发表于 2026-7-12 09:54
同步失败:
duplicate key value violates unique constraint "idx_uid_once_ph"
[ERROR] 同步失败: duplic ...

已修复