快速开始

先把服务启动、账号登录、网盘连上。其他设置可以等流程跑通后再补。

部署前准备

• Docker + Docker Compose —— 推荐部署方式。下面这一份 Compose 默认会同时启动 Redis、PostgreSQL 和 HyperMS；如果你本机已经有 Redis 或 PostgreSQL，看后面的精简方式
• 一个媒体目录 —— STRM 文件会写到宿主机目录，再映射给 Emby 扫描。建议一开始就定好路径
• 网络能出去 —— 如果需要刮削 TMDB、连接 Telegram 频道，确保容器能访问外网
• 不用克隆项目，也不用本地构建 —— 主服务直接使用 Docker Hub 上的 gravityle/hyperms:latest 镜像

复制 Compose 配置

新建一个目录，把下面内容保存为 docker-compose.yml。这就是完整部署文件，不需要再额外准备数据库 Compose。

# 根据实际情况调整挂载目录路径
services:
  # Redis 服务
  redis:
    image: redis:latest
    container_name: redis
    restart: unless-stopped
    networks:
      - hms_network
    volumes:
      - ./data/docker/redis/data:/data
    environment:
      TZ: Asia/Shanghai

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

  # HyperMS 主服务
  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
      # HMS_DISABLE_AUTH: "true" # 关闭登录认证，不建议公网使用
      # HMS_ADMIN_KEY: xxxxxxxx # 自定义字符串，用于重置管理员密码
    ports:
      - "8115:8115"
      - "8196:8196"
    volumes:
      - ./data/docker/hyperms/media:/media

networks:
  hms_network:
    name: hms_network

已有 Redis 或 PostgreSQL 怎么改

如果宿主机已经跑了 Redis 或 PostgreSQL，不需要再让 Compose 启动对应容器。保留 hms 服务，删掉你已有的服务块和对应的 depends_on，再把连接地址改成宿主机能访问的地址。

services:
  hms:
    image: gravityle/hyperms:latest
    container_name: HyperMS
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      TZ: Asia/Shanghai
      HMS_DB_URL: postgresql+asyncpg://hyperms:你的数据库密码@host.docker.internal:5432/hyperms
      # Redis 无密码：
      HMS_REDIS_URL: redis://host.docker.internal:6379/0
      # Redis 有密码时，把上一行换成：
      # HMS_REDIS_URL: redis://:你的Redis密码@host.docker.internal:6379/0
      HMS_REDIS_KEY_PREFIX: hyperms
    ports:
      - "8115:8115"
      - "8196:8196"
    volumes:
      - ./data/docker/hyperms/media:/media

Redis 连接串按你的认证方式选择：

启动服务

docker compose up -d

首次登录

1. 找初始密码 —— 首次启动时，系统会在容器日志里输出临时管理员账号和密码。执行 docker logs HyperMS 查看
2. 修改密码 —— 登录成功后，进设置页把管理员用户名和密码改成你自己的。临时密码留在日志里不安全
3. 忘了密码怎么办 —— 修改容器部署环境变量，添加 HMS_ADMIN_KEY，启动容器后在登录页走重置流程。

先填这些设置

现在设置页按使用场景分成总览、账号权限、网盘登录、资源搜索、媒体服务、功能开关和通知。先把下面几项跑通，再开启自动流程。

检查是否可用

1. 改完管理员密码，确认能正常登出再登入
2. 去设置页“网盘登录”看 115 或夸克的登录状态是不是“正常”
3. 回首页搜一部片，看看能不能搜到结果
4. 贴一个 115 分享链接，看能不能解析出文件列表
5. 去任务页看一眼，确认后台任务能创建、能执行、能看到进度

日常使用

日常操作集中在首页：搜内容、处理链接、加订阅。任务、索引和规则维护放在工具页。

搜索框支持哪些输入

常用场景

场景一：拿到了一个分享链接

把链接贴进首页搜索框，系统会校验它还有没有效。有效的话，你可以选择"转存到我网盘"或者"直接生成 STRM"（如果你只想播、不想占网盘空间）。

场景二：想把资源整理进家庭库

先转存或导入，然后让系统扫描、补全元数据、按电影/剧集分类，最后统一生成 STRM。Emby 扫一下新目录，海报和播放就都有了。

场景三：只有磁力或 ED2K 链接

直接贴到首页。如果网盘支持离线，系统会先把资源离线到网盘，然后再走整理流程。不支持离线的话，暂时只能先存着链接。

场景四：长期追一部剧

搜到这部剧后，点"添加订阅"。系统会定期检查有没有新集数。发现更新后自动转存、整理、通知你。稳定后再开自动生成 STRM。

场景五：维护一个索引库

在网盘浏览器里给常用目录建索引，后续去"索引管理"里同步、发布。适合你有大量存量资源，想批量生成 STRM 的情况。

场景六：旧的 STRM 链接失效了

进 STRM 转换工具，批量选中旧的 STRM 文件，预览新链接，确认没问题后一键改写。不用手动一个个改文本文件。

排查顺序

先看任务，再看操作记录，最后看日志。这样最容易定位问题发生在哪一步。

1. 任务页 —— 你点了一个操作，先看任务页里有没有出现对应任务。如果没出现，说明请求根本没发出去
2. 操作记录 —— 任务出现了但结果不对，看操作记录。这里记录了系统具体做了哪些动作，比如"尝试转存到 /电影/2024/"
3. 日志页 —— 操作记录里没有异常，但结果还是不对，去看日志。这里有原始报错、外部服务返回的异常信息

整理输出

资源导入后，整理、刮削和 STRM 会决定 Emby 里的显示和播放效果。这里按流程说明每一步。

资源怎么进你的网盘

从分享链接转存

在首页粘贴 115 或夸克分享链接，系统校验后会显示文件列表。选择"转存"，文件就会复制到你设定的默认目录里。转存是复制，不是移动，原分享不受影响。

从离线任务获取

粘贴磁力或 ED2K 链接，系统会调用网盘的离线下载功能。离线完成后，文件已经在你的网盘里，可以直接进入整理流程。

元数据补全

系统会根据文件名和目录结构匹配 TMDB，并补上海报、简介、年份、演员等信息。

1. 系统先猜 —— 根据文件名和目录结构，系统会调用 TMDB 搜索匹配的影片。如果文件名规范（比如"沙丘.2021.1080p"），命中率很高
2. 猜错了你纠正 —— 如果匹配错了（比如把电视剧匹配成了电影），去"手动整理"页里重新指定正确的 TMDB ID
3. 写规则让它以后自动猜对 —— 在"TMDB 规则"里可以写正则或关键词映射，比如凡是文件名带"S01E"的，一律按剧集处理

STRM 文件

STRM 是一个很小的文本文件，里面写着播放地址。Emby 扫描到它以后，会按这个地址拉流播放。

• 不占本地空间 —— 一部电影几十 GB，STRM 文件只有几百字节。本地磁盘只需要存这些索引文件，视频本身还在网盘里
• Emby 能直接识别 —— STRM 文件放在 Emby 的媒体库目录里，Emby 扫描时会把它当成普通视频文件显示。点播放时读取里面的直链地址，自动走网盘播放
• 链接失效可以批量换 —— 如果网盘直链格式变了，不用重新生成所有 STRM。用"STRM 转换"工具，批量改写文件里的链接地址即可

什么时候开启自动整理

播放器联动

Emby 插件用于将 HyperMS 的虚拟媒体库映射进 Emby。找资源、整理和生成 STRM 仍由 HyperMS 处理，Emby 负责扫描和播放。无需生成 STRM 文件。

两步装好插件

第 1 步：复制插件文件

下载项目提供的 HyperMSPlugin.dll，复制到 Emby 的插件目录，然后重启 Emby。

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

第 2 步：在 Emby 后台配置

1. 打开 Emby Dashboard
2. 进入 Plugins → HyperMS
3. 填写 Server URL —— 这是最关键的一项。注意：这里要填 Emby 容器内部能访问到的 HyperMS 地址，不是你在浏览器里访问的地址。举例：如果你用上面的 Compose，并让 Emby 加入同一个网络，可以填 http://hms:8115
4. 保存并重启 Emby

路径映射最容易出错

HyperMS 生成 STRM 文件时写的是容器内部路径，Emby 读取时也必须是同一个物理路径。两边对不上，Emby 就扫不到。

确认插件生效

• 插件列表能看到 —— 进 Emby 的插件列表，确认 HyperMS 插件出现在已安装列表里
• 配置能保存 —— 填完 Server URL 保存后，退出重进插件页，确认内容还在
• 搜索有结果 —— 在 Emby 客户端里搜索一部本地没有的片，看结果里有没有来自 HyperMS 的条目

插件常见问题

• 插件不显示：先重启 Emby，再确认 DLL 是否真的在 /config/plugins/ 目录下
• 搜索没结果：检查 Server URL 填的是不是 Emby 能访问的地址。在 Emby 容器里 curl 一下这个地址，看能不能通
• 配置不保存：检查 Emby 配置目录的权限，确保容器有写入权限
• 有结果但播不了：通常不是插件的问题，是 STRM 或网盘直链的问题，检查 STRM 地址和分享链接是否有效

后台管理

后台用于处理维护工作：任务、订阅、索引、权限、STRM 批量改写和日志排查。

设置页速览

设置页桌面端是左侧菜单，移动端是底部浮动标签。开关和选项通常选择即保存；右上角的 保存 主要提交输入框内容，返回 关闭设置页，退出 结束当前登录会话。

工具说明

子账号权限

给家人或朋友使用时，建议只开放必要权限。

• 只给搜索 —— 适合只想让别人查查看有什么资源，不开放任何修改操作。最安全
• 搜索 + 转存 —— 适合让家人或朋友帮忙把资源转存到统一目录。但要注意会消耗你的网盘空间
• 链接处理助手 —— 额外开放 STRM 生成权限，但仍然不给设置页和管理工具

浏览器插件

如果你经常在网页上收集 115/夸克分享链接，希望边浏览边入库，不用来回复制粘贴，那浏览器插件很适合你。

下载后先解压，再到 Chrome / Edge 的扩展管理页开启开发者模式，选择“加载已解压的扩展程序”。

最关键的四个设置：

1. HyperMS 地址 —— 按实际填写，比如 http://127.0.0.1:8115
2. 连接测试 —— 先确认插件能访问到你的 HyperMS
3. 自动入库 —— 熟悉效果后再开启，别一上来就全自动
4. 指定网站 —— 控制在哪些站点触发，避免误识别

开放接口

开放接口适合给第三方工具、桌面小程序或 AI 辅助整理工具使用。它的核心流程很简单：先读取索引文件列表，在外部补全片名、类型、海报等元数据，再把结果写回 HyperMS 媒体库。

使用流程

1. 在 HyperMS 后台完成网盘索引，记下索引根目录 ID。
2. 调用读取接口拿到文件列表，重点使用文件的 id、file_id、文件名和相对路径。
3. 在外部工具里补全媒体标题、媒体类型、海报、简介、演员等元数据。
4. 调用写入接口导入媒体库，成功后 HyperMS 会尝试同步 Emby 插件频道。

接口概览

必须填写的信息

• 索引根目录 ID：请求里的 root_pk，来自索引管理。
• 媒体标题：每条媒体的 title，为空会导入失败。
• 媒体类型：movie、tv 或 custom。自定义分类媒体使用 custom。
• 文件引用：推荐使用读取接口返回的 items[].id，写入到导入请求的 file_pks。
• 自定义分类：导入综艺等自定义频道时，使用 custom_category_id 或 custom_category_path，例如 综艺/真人秀。

最小请求示例

{
  "root_pk": 2,
  "source_key": "manual-test",
  "items": [
    {
      "title": "示例真人秀",
      "media_type": "custom",
      "custom_category_path": "综艺/真人秀",
      "file_pks": [12345]
    }
  ]
}

完整字段、分页方式、响应结构和面向 AI 开发模型的实现检查清单，请下载上方 Markdown 文档。

Authorization: Bearer hms_xxxxxxxxxxxxxxxxxxxxx

GET /api/v1/drive/index/roots/{root_pk}/export-files?video_only=true&include_dirs=false&limit=1000&offset=0

POST /api/v1/library/drive-index/import

{
  "root_pk": 2,
  "source_key": "manual-test",
  "items": [
    {
      "title": "示例真人秀",
      "media_type": "custom",
      "year": 2026,
      "custom_category_path": "综艺/真人秀",
      "file_pks": [12345]
    }
  ]
}

常见问题

多数问题可以从任务页、操作记录和日志定位。下面按常见症状整理。