docker/.agents/rules/03-storage-media.md

03-storage-media.md

本文件定义媒体库架构标准、路径映射规范与用户权限控制。

1. 媒体库核心设计标准

媒体库严格遵循统一的英文根目录与规范分类结构，禁止创建未约定的中文一级目录（如废弃的 电视剧、电影），禁止混入已废弃的分类（如废弃的 anime）：

/vol3/1000/media/library/
├── movies/       # 电影库
│   ├── 华语电影/
│   ├── 外语电影/
│   └── 动画电影/
├── tv/           # 剧集库（所有电视剧、国漫、日番等剧集统一入库于此）
│   ├── 国漫/
│   ├── 日番/
│   ├── 国产剧/
│   └── 欧美剧/
├── music/        # 音乐库（供飞牛音乐直接扫描，由 Music-Tag-Web 刮削归档）
│   └── 歌手名/专辑名 (年份)/01. 歌曲名.flac
└── porn/         # 特定内容隔离目录

2. 存储空间绝对路径定义

环境变量标识	宿主机物理路径	容器内典型挂载点	说明
MEDIA_ROOT	/vol3/1000/media	/media	媒体总根目录
LIBRARY_ROOT	/vol3/1000/media/library	/media/library	媒体库根路径
DOWNLOAD_ROOT	/vol3/1000/media/downloads/pt	/media/downloads/pt	PT 下载目录
CLOUD_ROOT	/vol3/1000/media/cloud	/media/cloud / /downloads	网盘直链下载与缓存目录
MUSIC_ROOT	/vol3/1000/media/library/music	/media/library/music	规范音乐库目录
PORN_ROOT	/vol3/1000/media/downloads/porn	/media/downloads/porn	成人媒体缓存

3. 权限与所有权规范 (PUID / PGID)

• 标准账户：所有媒体与容器统一映射为 Linux 用户 1000:1000 (triplestone:triplestone / triplestone:Administrators)。
• 配置规则：所有涉及文件读写（下载、移动、重命名、生成封面和 nfo）的容器，必须在 compose 中显式传递：

  environment:
    - PUID=${PUID}
    - PGID=${PGID}
    - UMASK=022
  

• 权限修复原则：Agent 在执行目录迁移或文件整理后，必须主动确保目标路径所有权为 1000:1000，避免后续容器写入权限不足。

4. 自动化刮削与归档规则 (MoviePilot Directories)

• MoviePilot 目录同步规则原则：
  • 针对电影与电视剧分别配置规则；
  • 关闭 library_type_folder（避免在 tv 下重复生成中文 电视剧）；
  • 开启 library_category_folder（保留 国漫、国产剧、欧美剧 等二级分类）；
  • 电视剧目标目录：/media/library/tv；
  • 电影目标目录：/media/library/movies。