HyperMS 部署与使用指南 — 网盘媒体资源管理利器

HyperMS 是什么

HyperMS（HMS）是一个开源的网盘媒体资源管理工具，核心功能是把散落在 115、夸克网盘里的影视资源，自动整理成 Emby/Jellyfin 可以扫描播放的媒体库。

核心流程：搜索资源 → 转存网盘 → 自动整理 → 元数据刮削 → 生成 STRM → Emby 播放

项目地址： https://hyperms.wiki

部署

环境要求

• Docker + Docker Compose（OrbStack / Docker Desktop / Linux 均可）
• 网络能访问外网（TMDB、Telegram 等需要）
• 一个持久化目录存放数据和 STRM 文件

Docker Compose

HMS 依赖三个服务：Redis（缓存）、PostgreSQL（数据库）、HMS 主服务。一份 compose 搞定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

services:
  # Redis
  redis:
    image: redis:latest
    container_name: redis
    restart: unless-stopped
    networks:
      - hms_network
    volumes:
      - ./redis/data:/data
    environment:
      TZ: Asia/Shanghai

  # PostgreSQL
  pgsql:
    image: postgres:17-alpine
    container_name: postgresql
    restart: unless-stopped
    networks:
      - hms_network
    volumes:
      - ./postgresql/data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: hyperms
      POSTGRES_USER: hyperms
      POSTGRES_PASSWORD: hyperms
      TZ: Asia/Shanghai

  # HMS 主服务
  hms:
    image: gravityle/hyperms:latest
    container_name: HyperMS
    restart: unless-stopped
    networks:
      - hms_network
    depends_on:
      - redis
      - pgsql
    environment:
      - TZ=Asia/Shanghai
      - HMS_DB_URL=postgresql+asyncpg://hyperms:hyperms@pgsql:5432/hyperms
      - HMS_REDIS_URL=redis://redis:6379/0
      - HMS_REDIS_KEY_PREFIX=hyperms
      # 如果需要代理访问外网，取消注释并修改地址
      # - HTTP_PROXY=http://你的代理地址:端口
      # - HTTPS_PROXY=http://你的代理地址:端口
    volumes:
      - ./media:/media    # STRM 输出目录，Emby 也需要挂载这个目录
    ports:
      - "8115:8115"       # HMS 主界面
      - "8196:8196"       # Emby 代理端口（可选）

networks:
  hms_network:
    name: hms_network

已有 Redis 或 PostgreSQL？ 可以删掉对应的服务块和 depends_on，把连接地址改为已有服务的地址。注意容器内不能用 127.0.0.1，要用 host.docker.internal（Docker Desktop / OrbStack）或实际 IP。

启动

1

docker compose up -d

获取初始密码

首次启动会在日志中生成临时管理员账号：

1

docker logs HyperMS

找到类似输出：

1
2
3
4

🔐 首次启动已生成默认管理员账号
🔐 账号: hms
🔐 密码: xxxxxxxxxx
🔐 请立即登录，并在设置-通用中修改管理员密码

访问 http://localhost:8115 登录，第一时间修改密码。

基础配置

登录后进入设置页，按以下顺序配置：

1. 账号权限

• 修改管理员用户名和密码
• 如需第三方工具调用 API，记录 API Token

2. 网盘登录

• 115 网盘：Cookie 或扫码登录，设置电影/剧集默认转存目录
• 夸克网盘：Cookie 登录，同样设置默认目录

3. 资源搜索

• 配置外网代理（如果容器需要代理才能访问 TMDB 等）
• 启用搜索源：PanSou（默认）、影巢、聚影
• Telegram 授权：扫码后可搜索已加入的 Telegram 频道

4. 媒体服务

• TMDB API Key：免费申请，用于元数据匹配和海报下载
• Emby 连接：填写 Emby 地址和 API Key

5. 功能开关

建议先全部关闭自动功能，手动跑通流程后再逐步开启：

日常使用

搜索

首页搜索框是主入口，支持多种输入：

转存与整理

1. 搜索到资源后点击「转存」，文件会复制到网盘默认目录
2. 系统自动扫描转存的文件，匹配 TMDB 元数据
3. 确认分类和元数据正确后，生成 STRM 文件

订阅追剧

在剧集详情页点击「添加订阅」，系统会定期检查更新：

• 发现新集 → 自动转存 → 自动整理 → 推送通知
• 适合长期追的连载剧

STRM 文件

STRM 是一个几百字节的文本文件，里面写着播放地址。特点：

• 不占空间：电影几十 GB，STRM 只有几百字节
• Emby 直读：放在媒体库目录里，Emby 扫描时自动识别
• 可批量改写：链接格式变了，用「STRM 转换」工具一键替换

Emby 联动

Emby 媒体库

HMS 生成的 STRM 文件被 Emby 扫描后，自动建立媒体库：

安装插件

1. 下载 HyperMSPlugin.dll（官方文档提供）
2. 复制到 Emby 插件目录：

1
2
3

# Docker 部署的 Emby
docker cp HyperMSPlugin.dll emby-server:/config/plugins/
docker restart emby-server

3. 在 Emby 后台 → Plugins → HyperMS 中填写 Server URL

关键： Server URL 要填 Emby 容器内部能访问的地址。如果 Emby 和 HMS 在同一个 Docker 网络中，用 http://hms:8115。

路径映射

最容易出问题的一步。HMS 和 Emby 必须看到同一个物理路径：

1
2

✓ 正确：宿主机 /mnt/media 映射给 HMS 的 /media 和 Emby 的 /media
✗ 错误：HMS 映射 /media，Emby 映射 /data/media（路径不一致）

验证方法：在 Emby 容器里 cat 一个 STRM 文件，能读到就说明映射正确。

通知配置

飞书机器人

1. 飞书开放平台 创建企业自建应用
2. 添加「机器人」能力
3. 权限管理中开通 im:message:send_as_bot
4. 创建版本并发布
5. 在 HMS 设置页 → 通知 → 飞书机器人，填入 App ID 和 App Secret
6. 启用并点击「验证连接」
7. 在飞书中主动给机器人发一条消息（激活会话，不发消息收不到推送）

其他渠道

• Telegram Bot：填 Bot Token 和 Chat ID
• 企业微信：填 CorpID、Secret、AgentID
• Server 酱：填 SendKey

排查问题

按这个顺序排查，最高效：

1. 任务页 → 操作有没有生成任务？任务状态是什么？
2. 操作记录 → 系统实际执行了什么动作？
3. 日志页 → 原始报错信息

常见问题：

开放接口

HMS 提供 REST API，支持第三方工具批量操作：

• 读取索引文件：GET /api/v1/drive/index/roots/{root_pk}/export-files
• 写入媒体库：POST /api/v1/library/drive-index/import

鉴权方式：Authorization: Bearer <API Token>

适合做自动化脚本、AI 辅助整理等场景。

总结

HMS 把「找资源 → 看上大屏幕」这个流程串联了起来，特别适合有 115/夸克网盘 + Emby 的家庭影音场景。部署简单（一个 compose），功能完善（搜索、转存、整理、STRM、通知全流程），推荐以下使用节奏：

1. 第一周：全部手动，熟悉系统判断逻辑
2. 第二周：开启自动整理 + 手动生成 STRM
3. 稳定后：全自动 — 订阅检查 + 自动转存 + 自动整理 + 自动 STRM + 通知推送