pixel_pop/UHD_Media_Tool
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c85b139ec469559b1a177b93b397e391e7b2e633
UHD_Media_Tool/README.md
T

7.4 KiB
Raw Blame History

UHD Media Tool

内部使用、Agent 自动化优先的媒体整理入库平台。需求基线见 media_automation_requirements_architecture_v0.7.md。

源码版本以根目录 package.json 为准，各版变化见 CHANGELOG.md。业务逻辑以 MoviePilot v3 为参考，逐项对照见 MoviePilot v3 对照。正在推进的计划与待办见 docs/plan，开发与发布约定见 CLAUDE.md。

功能

已实现(有自动化回归及部分真实环境 / 脱敏样本记录,四站与真实下载、媒体服务器的完整验收尚未完成):

  • 来源:多 RSS(条件请求、重叠窗口、多层去重、补漏)、站点中心(观众 / 馒头 / HHClub / CHD 等 23 个站点定义,凭证、账号数据、健康检查)、站点快照与实时补查、全局搜索。

  • 识别:MP 对齐的标题解析、TMDB + 本地别名召回、本地实体优先、临时季集单元、待识别池、人工纠错与字段锁。

  • 订阅与规则:单次 / 持续追更、多版本目标(Slot)、总集数账本、覆盖矩阵、日历;规则组(兼容 MP 规则字符串)、偏好标签与抑制记录;新作品 / 追更 / 升级三种收录模式。

  • 下载:多 qB、管理标签接管、缓存卷硬阈值与恢复水位、无进展只记录不换源、缓存清理(入库已验证 + 保留期 + H&R)。

  • 整理:Copy / Move(跨卷可恢复、fsproxy 看门狗)、路径绑定固定、命名模板、文件管理 v2 与统一整理弹窗、回收站、公开整理记录增量接口。

  • 刮削:任意视频 / 目录就地识别并写 NFO 与图片、候选选择、覆盖策略、入库后自动刮削、每次刮削一条记录。

  • Agent:Pi 内核、能力目录（当前源码 42 项）、服务端授权(持续授权 / 一次性审批)、步骤清单 / 方案选择 / 内联审批、子会话、后台自动调查与授权内恢复、42 个内置上游 provider 与订阅登录(未逐家联网实测)。

  • 接口:REST + OpenAPI、MCP 服务端(API Key 鉴权)、SSE 带序号补读。

  • 浏览器:camofox BrowserProvider、原站视图(截图 + 坐标输入)、接管租约、下载捕获走统一提交。

  • 运维:管理员登录(TOTP / Passkey)、API Key 分级、主密钥轮换、定时任务看板、统一任务页、运行状态页、审计、备份与只读对账恢复。

  • 集数映射:识别后按作品季表校验季集号(元数据滞后放行),绝对集号 / 播出日期确定性换算,识别词(全局识别词与 MoviePilot 自定义识别词同语法,作品识别词写季集换算,可视化 / 文本两种编辑、保存前试算),待确认按组显示原因,智能体兜底把一行写进作品识别词(写入前强制模拟)。

未做:综艺正片覆盖、双版本组合校验、旧库分范围接管、Agent 偏好选片、规则学习与回放、Emby 库存参与决策。

快速启动

需要 Bun 1.4.3(curl -fsSL https://bun.sh/install | bash -s "bun-v1.4.3")和 Docker。解析沙箱使用 Linux seccomp；本地构建还需要 C 编译器及 Node-API 头文件(Debian/Ubuntu: apt-get install build-essential libnode-dev)。

cp .env.example .env
bun install --frozen-lockfile # 按 bun.lock 安装依赖到 node_modules
bun run dev:up      # 开发库 postgres:18.6(端口 55433)+ 迁移到最新;拉代码后也跑一次
bun run dev         # API http://localhost:4390  控制台 http://localhost:5180

提交前:bun run ci(typecheck:tsc 7.0.2 → biome → test:all(逐包跑完汇总,要求测试库可连)→ check:tokens → check:copy → web 构建 + server 编译 → check:binary)。

前端冒烟(bun run test:web:smoke)

Playwright(playwright-core,用本机 Chromium)登录后逐个打开控制台全部路由(详情页从列表接口取第一条真实 ID),检查页面渲染出来、没有控制台报错 / 未捕获异常 / 4xx·5xx 的 API 请求,并逐页截图。不在 bun run ci 里,需要先起好后端与 web、并已初始化管理员:

bun run dev                                   # 或单容器部署后直接用 4380
SMOKE_BASE_URL=http://127.0.0.1:5180 SMOKE_USER=<管理员> SMOKE_PASSWORD=<密码> bun run test:web:smoke

可选:SMOKE_OUT(截图目录,缺省 apps/web/test/screenshots/smoke,已 gitignore)、SMOKE_CHROMIUM(浏览器路径,缺省 /usr/bin/chromium)、SMOKE_SCREENSHOTS=0。全部通过退出 0,有失败 1,前置条件不满足 2。

部署

核心应用在一个容器里(api + worker + worker:agent 三个进程 + web 静态,单端口 4380);compose 默认服务为 app + postgres + camofox,可选 tls profile 的 Caddy 提供 HTTPS。

首次部署默认浏览器前,先按 浏览器镜像构建说明 构建 camofox-browser:1.18.0 基础镜像,compose 再据此构建桌面镜像。

cp docker/compose.env.example .env.deploy    # 填 SECRET_MASTER_KEY=$(openssl rand -hex 32)、POSTGRES_PASSWORD
docker compose --env-file .env.deploy up -d --build
docker compose --env-file .env.deploy logs app | grep 'setup token'   # 首次初始化管理员
docker compose --env-file .env.deploy exec app umt backup             # 备份到 /data/backups/<时间戳>/
  • 应用数据卷 /data(Agent 会话、备份、导出);媒体库根与下载目录自行 bind mount,需对 PUID:PGID(缺省 10001)可读写。
  • SECRET_MASTER_KEY 不在备份里,和备份分开保管。
  • 详见 docs/runbook/deploy.md 与 docs/runbook/backup-restore.md。

更多见 docs/runbook/dev.md。

仓库结构

路径 职责
apps/web React Router 8 SPA 控制台,沿用 uhd_web 设计系统
apps/server Hono API(/api/v1)+ SSE + worker 入口;业务按 src/modules/<area>/ 分模块(见 apps/server/README.md)
packages/contracts zod schema:API/事件/能力的唯一定义
packages/db Kysely 客户端、表类型与迁移
packages/domain 纯业务逻辑,无 IO
packages/mapping domain ↔ contracts 取值与结构映射(只依赖 domain + contracts)
packages/adapters qB / RSS / 站点 / TMDB / Emby / 文件系统适配
packages/runtime Bun 运行时适配与共用子进程协议
packages/tasks 持久任务与 outbox
packages/agent Pi 接入与能力注册桥接
packages/testkit mock 服务与测试夹具
docs/adr 架构决策记录
docs/design 设计系统规范
docs/runbook 运行手册
config/ tsc 7 用的 tsconfig 基座(Node + Bun 类型)
docker/ 容器入口脚本、compose 环境变量示例
scripts/ 备份 / 恢复脚本(镜像内 /app/scripts/)
spikes/movieclaw-src/ MovieClaw 只读源码克隆(不进 git;scripts/mp-sync/movieclaw-import.mjs 导入站点定义用)

技术选型:Bun 1.4.3(锁定)+ TypeScript 7.0.2 strict,package.json workspace,npm 依赖由 bun.lock 锁定。前端 Vite 8 + React Router 8 由 Bun 执行。决策见 ADR-007(取代 ADR-004)。

解析沙箱预加载解析器和 WASM 后,通过 Node-API 原生模块安装 Linux seccomp 系统调用白名单,覆盖全部 Bun 线程。任务执行阶段禁止路径文件访问、网络、执行程序和创建子进程；隔离无法建立时直接失败。超时和 RSS 超限仍由父进程 SIGKILL。生产镜像同时安装编译二进制、沙箱策略模块与内置 skills。

Reference in new issue View Git Blame Copy Permalink