🚀 使用 Docker Compose 部署 hlink（文件硬链接＆软链接管理工具）

🚀 使用 Docker Compose 部署 HLink

HLink 是一款专为 NAS 用户和影音爱好者设计的硬链接工具，它能够在不占用额外磁盘空间的前提下，让同一个文件在文件系统的多个位置同时出现。这对于需要同时维护下载做种和媒体库整理的场景尤为有用。

📝 项目简介

HLink 是一个基于 Node.js 开发的高效硬链接工具，它通过简单的配置，帮助用户实现文件的硬链接操作，特别适合用于影音文件的整理和归类。

核心特点：

可视化操作：提供直观的 Web 图形界面（WebUI），硬链接配置和管理变得简单易懂
灵活的任务配置：支持创建多个硬链接任务，每个任务可以使用不同的配置文件
自动化执行：支持定时任务和 API 触发，满足自动化需求
跨平台支持：通过 Docker 容器化部署，可以运行在各种操作系统和 NAS 设备上
智能过滤：支持通过包含（include）和排除（exclude）规则精确控制需要硬链接的文件类型

硬链接的价值：

对于 NAS 用户和影音爱好者，HLink 解决了这样一个痛点：当你想让下载中的影片既能继续做种，又能在媒体服务器（如 Jellyfin、Emby）中播放时，硬链接可以让文件同时存在于两个位置，却只占一份空间。HLink 则让这个过程变得简单高效。

🔧 部署前准备

系统环境要求

操作系统：支持 Linux、Windows、macOS 等主流操作系统，常见 NAS 系统（如群晖、威联通）也可运行
Docker 引擎：版本 20.10+
Docker Compose：版本 2.0+
硬件资源：
内存：至少 512MB
存储空间：至少 1GB 可用空间

环境检查

1.检查 Docker 服务状态

    systemctl status docker

确保 Docker 服务处于 `active (running)` 状态。

2.检查 Docker 版本

    docker --version

3.创建部署目录建议创建一个独立的目录来管理您的 HLink 部署文件和数据：

    mkdir -p /home/compose/hlink && cd /home/compose/hlink

⚙️ 配置 Docker Compose

根据您提供的配置，以下是一个优化后的 docker-compose.yml 文件示例和详细说明：

#version: '3'

services:
  docker:
    #stdin_open: true
    #tty: true

    # hlink 官方镜像（开发者 likun7981 维护，latest 为最新稳定版）
    image: likun7981/hlink:latest # docker镜像名称
    restart: on-failure  # 容器失败时自动重启（正常停止不重启，避免无效循环）
    container_name: hlink  # 容器名称，便于管理（如查看日志、重启）
    ports:
      # 端口映射：主机 9090 → 容器 9090（Web 管理界面访问端口）
      - 9090:9090
    volumes:
      # 这个表示存储空间映射
      #- ./share:/share

      # 1. hlink 配置/日志目录：本地 ./data → 容器 /share/data/hlinkDocker（与 HLINK_HOME 对应）
      - ./data:/share/data/hlinkDocker
      # 2. 源文件目录：本地 ./1 → 容器 /1（存放需要创建链接的原始文件）
      - ./1:/1

      #- /path/to/your/source:/source
      #- /path/to/your/destination:/destination

      ##- /mnt/media:/pt
      #- '/home/compose/obsidian/obdocker/Obsidian Vault:/1/ob'
      #- /home/compose/mkdocs/docs/my-project/docs:/1/mkdocs
      #- /home/compose/Docsify/docs:/1/Docsify
      #就这都会跨盘符不给硬链接，我不会使用，感觉没这玩意还更好。

    environment:
      # 核心环境变量：hlink 配置/日志存储根目录（需与 volumes 中 ./data 的容器路径一致）
      - HLINK_HOME=/share/data/hlinkDocker # 这个是环境变量

关键配置说明

镜像选择：使用官方 likun7981/hlink:latest 镜像。
端口映射：9090:9090 将容器内的 9090 端口映射到宿主机的 9090 端口，用于访问 WebUI。
数据持久化 (volumes)：
- ./data:/share/data/hlinkDocker：用于持久化 HLink 的配置文件、缓存和数据库。这里的 ./data 是相对于 docker-compose.yml 文件的目录。
- /path/to/your/source:/source：映射源文件目录。将宿主机的源目录（如下载目录）挂载到容器内。请替换 /path/to/your/source 为实际的源路径。
- /path/to/your/destination:/destination：映射目标文件目录。将宿主机的目标目录（如媒体库目录）挂载到容器内。请替换 /path/to/your/destination 为实际的目标路径。
  
  重要提醒：要成功创建硬链接，源目录和目标目录必须位于同一个物理磁盘（文件系统）分区上。硬链接不能跨文件系统创建。因此，请确保你挂载的源目录和目标目录在宿主机上位于同一磁盘分区。
环境变量：HLINK_HOME 定义了容器内 HLink 配置和数据的存储路径，应与卷挂载路径一致。
重启策略：on-failure 确保容器在异常退出时自动重启。

🚀 启动与验证

启动服务

在包含 docker-compose.yml 文件的目录下，执行：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

1.检查容器运行状态

    docker compose ps

应该看到名为 `hlink` 的容器状态为 `Up`。

2.查看服务日志

    docker compose logs -f

3.访问 Web 管理界面在浏览器中输入 http://你的服务器IP:9090，如果看到 HLink 的 WebUI 界面，说明服务已成功启动。

🔌 基础配置与使用

创建配置文件

1.在 HLink WebUI 中，点击 "新建配置文件"。 2.配置文件中，最重要的部分是 pathMapping，它定义了源路径和目标路径的映射关系。例如：

    "pathMapping": {
      "/source/Film": "/destination/Film",
      "/source/Episode": "/destination/Episode"
    }

**注意**：这里使用的是**容器内的路径**（即你在 `docker-compose.yml` 中通过 `volumes` 挂载时定义的容器内路径），而不是宿主机的路径。

3.你还可以根据需要配置 include 或 exclude 规则来过滤文件类型。

创建并执行任务

在 WebUI 的 "任务列表" 部分，点击 "创建任务"。
输入任务名称，选择任务类型（如 "硬链(hlink)"），并关联刚才创建的配置文件。
保存任务后，你可以在任务列表中找到它，点击"运行"按钮即可手动执行硬链接任务。

设置定时任务 (可选)

在任务列表中，点击任务的 "定时" 设置按钮。
HLink 提供了 "新手选项"（如每隔多少秒执行一次）和 "cron 表达式" 两种方式，你可以根据需求灵活设置。

配置文件的示例文档

// 重要说明路径地址都请填写 绝对路径！！！！
export default {
  /**
   * 源路径与目标路径的映射关系
   * 例子:
   *  pathsMapping: {
   *     '/path/to/exampleSource': '/path/to/exampleDest',
   *     '/path/to/exampleSource2': '/path/to/exampleDest2'
   *  }
   */
  pathsMapping: {
    '/1/1': '/1/2',

  },
  /**
   * 需要包含的后缀，如果与exclude同时配置，则取两者的交集
   * include 留空表示包含所有文件
   *
   * 后缀不够用? 高阶用法: https://hlink.likun.me/other/v2.html#%E6%96%B0%E5%A2%9E%E5%8A%9F%E8%83%BD
   */
  include: [
    'mp4',
    'flv',
    'f4v',
    'webm',
    'm4v',
    'mov',
    'cpk',
    'dirac',
    '3gp',
    '3g2',
    'rm',
    'rmvb',
    'wmv',
    'avi',
    'asf',
    'mpg',
    'mpeg',
    'mpe',
    'vob',
    'mkv',
    'ram',
    'qt',
    'fli',
    'flc',
    'mod',
    'iso',
  ],
  /**
   * 需要排除的后缀，如果与include同时配置，则取两者的交集
   *
   * 后缀不够用? 高阶用法: https://hlink.likun.me/other/v2.html#%E6%96%B0%E5%A2%9E%E5%8A%9F%E8%83%BD
   */
  exclude: [],
  /**
   * @scope 该配置项 hlink 专用
   * 是否保持原有目录结构，为false时则只保存一级目录结构
   * 可选值: true/false
   * 例子：
   *  - 源地址目录为：/a
   *  - 目标地址目录为: /d
   *  - 链接的文件地址为 /a/b/c/z/y/mv.mkv；
   *  如果设置为true  生成的硬链地址为: /d/b/c/z/y/mv.mkv
   *  如果设置为false 生成的硬链地址为：/d/y/mv.mkv
   */
  keepDirStruct: false, /*true,
  /**
   * @scope 该配置项 hlink 专用
   * 是否打开缓存，为true表示打开
   * 可选值: true/false
   * 打开后，每次硬链后会把对应文件存入缓存，就算下次删除硬链，也不会进行硬链
   */
  openCache: false,
  /**
   * @scope 该配置项 hlink 专用
   * 是否为独立文件创建同名文件夹，为true表示创建
   * 可选值: true/false
   */
  mkdirIfSingle: false, /*true,
  /**
   * @scope 该配置项为 hlink prune 命令专用
   * 是否删除文件及所在目录，为false只会删除文件
   * 可选值: true/false
   */
  deleteDir: false,
}

🛠️ 维护与管理

日常维护操作

服务启停：

  # 停止服务
  docker compose down
  # 启动服务
  docker compose up -d

数据备份：定期备份 HLink 的配置和数据是很好的习惯。

  # 备份 HLink 的配置和数据目录
  tar -czf hlink-backup-$(date +%Y%m%d).tar.gz ./data

服务更新：

  # 拉取最新镜像并重启服务
  docker compose pull
  docker compose down
  docker compose up -d

监控与日志

查看实时日志：除了启动时查看，日常排查问题也可使用 docker compose logs -f。
WebUI 日志查看：HLink 的 Web 界面通常也支持查看任务执行日志。

🐛 常见问题排查

无法访问 WebUI (http://IP:9090 无响应)
- 检查防火墙：确保服务器的 9090 端口访问已放行。
- 确认容器状态：通过 docker compose ps 检查容器是否正常运行。
- 查看日志：使用 docker compose logs 查看具体错误信息。
硬链接任务执行失败 (文件未创建)
- 检查路径映射：确认配置文件中 pathMapping 使用的是容器内路径，并且这些路径已通过 volumes 正确挂载。
- 检查文件系统：确认源目录和目标目录在宿主机上位于同一物理磁盘分区，因为硬链接不能跨文件系统创建。
- 检查权限：确保 HLink 容器对挂载的源目录和目标目录有读写权限。
硬链接成功，但媒体服务器无法识别文件
- 这通常是因为硬链接的文件虽然内容相同，但可能文件名、路径或元信息不符合媒体服务器的刮削规则。检查媒体服务器的扫描设置。
容器启动失败
- 检查端口占用：netstat -tulpn | grep 9090 查看 9090 端口是否被其他程序占用。
- 检查卷挂载路径：确认 docker-compose.yml 中指定的本地目录（如 ./data, /path/to/your/source 等）是否存在，或 Docker 是否有权限访问。

希望这篇教程能帮助你顺利部署和使用 HLink！如果在使用过程中遇到更复杂的问题，可以参考 HLink 的官方文档或在相关技术社区寻求帮助。

🐛 常见问题排查2

1. 硬链接创建失败（提示 “不支持的操作” 或 “跨设备链接”）

原因：源目录与目标目录不在同一文件系统（跨挂载点 / 跨盘符），硬链接仅支持同一文件系统。

解决： 1. 检查挂载点：df -h 源目录目标目录，确认「Mounted on」路径是否一致； 2. 方案 1：将源文件或目标目录迁移到同一磁盘 / 分区； 3. 方案 2：改用「软链接」（在任务配置中选择 “软链接” 类型，跨文件系统可用，但原文件删除后软链接失效）。

2. Web 界面无法访问（ERR_CONNECTION_REFUSED）

原因 1：9090 端口未开放或被占用。解决：
1. 检查端口占用：sudo lsof -i :9090，若占用则停止对应服务；
2. 重新开放端口：sudo ufw allow 9090/tcp，云服务器同步安全组；
3. 若端口冲突，修改 docker-compose.yml 中的主机端口（如 9091:9090），重启容器。
4. 原因 2：容器未正常启动（State 为 Exited）。解决：查看日志 docker compose logs -f docker，修复权限或路径错误后重启。

3. 链接任务执行后目标目录无文件（无报错）

原因 1：过滤规则设置过严，未匹配到任何文件（如仅筛选 .mp4 文件，但源目录只有 .mkv 文件）。解决：编辑任务，检查「过滤规则」，放宽格式或目录筛选条件，重新执行任务。
原因 2：源目录路径错误（容器内路径与配置不一致）。解决：确认任务的 “源目录” 是容器内的 /1（对应本地 ./1），而非本地路径（如 ./1），修改路径后重新执行。

4. 容器重启后任务丢失

原因：HLINK_HOME 环境变量与 ./data 的容器挂载路径不一致，hlink 无法找到配置文件。

解决：确保 HLINK_HOME=/share/data/hlinkDocker 与 volumes: ./data:/share/data/hlinkDocker 中的容器路径完全一致，修改后重启容器。

通过以上步骤，新手可快速搭建 hlink 并实现文件链接管理，解决 “重复文件占用空间” 的问题。hlink 尤其适合媒体库整理、PT 下载后分类场景，如需探索更多高级功能（如批量修改链接规则、API 集成），可参考 hlink 官方文档（通常在 Web 界面「帮助」或开发者 GitHub 仓库中获取）。

🚀 使用 Docker Compose 部署 hlink（文件硬链接 ＆软链接管理工具）