linuxserver/mods

Docker Mod 技术文档

一、镜像概述和主要用途

Docker Mod 是 Linuxserver.io 容器生态的扩展机制，旨在提供用户可消费的容器修改层。其核心是存储在 Docker Hub 或 GitHub Container Registry（GHCR）中的文件压缩包，容器启动时会自动下载并解压该压缩包，且在任何初始化逻辑执行前完成，从而实现对基础容器的自定义修改。

主要用途包括：

• 允许开发者和社区用户自定义基础容器功能，无需维护主仓库的分支
• 作为独立项目共享修改逻辑，拥有独立的支持渠道和开发理念
• 利用 GHCR 和 Docker Hub 提供零成本的托管和构建流水线
• 通过环境变量实现容器间的自定义配置管理和联动

二、核心功能和特性

核心功能

• 无分支维护需求：无需 fork 主容器仓库即可实现功能扩展
• 独立共享机制：Mod 可作为独立项目分发，与主容器解耦
• 多 Mod 组合：支持同时加载多个 Mod，通过分隔符实现组合使用
• 灵活的初始化逻辑：支持简单文件添加和复杂构建逻辑，满足多样化需求

关键特性

• 单镜像层限制：每个 Mod 仅包含单个镜像层，确保容器轻量化
• s6 v3 兼容：仅支持基于 s6 v3 初始化系统的 Linuxserver 容器（所有当前支持的基础镜像均已适配）
• 安全过滤机制：内置官方禁止的 Docker Hub 用户过滤，可通过环境变量绕过（不建议）
• 透明构建流程：推荐使用公开的构建流水线（如 GitHub Actions），确保修改逻辑可见

三、使用场景和适用范围

适用场景

• 为基础容器添加额外工具（如调试工具、命令行工具）
• 自定义容器初始化流程（如配置文件生成、服务依赖调整）
• 扩展容器功能（如添加插件、集成第三方服务）
• 统一环境配置（如跨容器的标准化修改）

适用范围

• 所有基于 s6 v3 初始化系统的 Linuxserver.io 容器（当前支持的官方镜像均适用）
• 需注意：旧版 s6 v2 容器、分支版本或第三方 fork 版本可能不兼容

四、使用方法和配置说明

环境变量说明

使用示例

1. Docker Run 命令

以下示例启动一个 NZBGet 容器，并加载 universal-tshoot Mod（包含 dig、netstat 等调试工具）：

bash
docker create \
  --name=nzbget \
  -e DOCKER_MODS=lscr.io/linuxserver/mods:universal-tshoot \  # 指定加载的 Mod
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -p 6789:6789 \
  -v /path/to/nzbget/data:/config \
  -v /path/to/downloads:/downloads \
  --restart unless-stopped \
  lscr.io/linuxserver/nzbget

2. Docker Compose 配置

yaml
---
services:
  nzbget:
    image: docker.xuanyuan.run/linuxserver/nzbget:latest
    container_name: nzbget
    environment:
      - DOCKER_MODS=lscr.io/linuxserver/mods:universal-tshoot  # 指定加载的 Mod
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
    volumes:
      - /path/to/nzbget/data:/config
      - /path/to/downloads:/downloads  # 可选挂载
    ports:
      - 6789:6789
    restart: unless-stopped

官方 Mod 列表

Linuxserver.io 官方托管的 Mod 可通过以下链接查看：
https://mods.linuxserver.io/

官方 Mod 镜像地址格式：
lscr.io/linuxserver/mods:<imagename>-<modname>（最新版本）
lscr.io/linuxserver/mods:<imagename>-<modname>-<commitsha>（特定版本）

五、Mod 的创建与维护

前提条件

• 需使用公开代码仓库（如 GitHub）存储 Mod 源码
• 推荐使用透明构建流水线（如 GitHub Actions），确保构建过程可审计
• 仅支持 s6 v3 初始化系统，不兼容 s6 v2 容器

Mod 类型与目录结构

核心原则

Mod 必须仅包含单个镜像层。所有文件需通过构建流程整合到单层中。

基础目录结构（以 Mod 名称 universal-mymod 为例）

text
.
└── root                  # 根目录，内容将被复制到容器的 / 路径下
  ├── defaults            # 存放默认配置文件（如需覆盖容器默认配置）
  └── etc
    └── s6-overlay
      └── s6-rc.d         # s6 服务管理目录
        ├── init-mods-end                 # 无依赖的初始化结束点
        │  └── dependencies.d
        │     └── init-mod-universal-mymod  # 无包安装需求时，依赖此文件（空文件）
        ├── init-mods-package-install      # 包安装初始化点
        │  └── dependencies.d
        │     └── init-mod-universal-mymod  # 有包安装需求时，依赖此文件（空文件）
        ├── init-mod-universal-mymod        # Mod 初始化服务
        │  ├── dependencies.d
        │  │  └── init-mods                 # 依赖基础 Mod 初始化（空文件）
        │  ├── run                          # 初始化脚本（需可执行权限）
        │  ├── type                         # 文件内容为 "oneshot"（单次执行）
        │  └── up                           # 脚本绝对路径，如 "/etc/s6-overlay/..."
        ├── svc-mod-universal-mymod         # Mod 持久服务（如需后台运行）
        │  ├── dependencies.d
        │  │  └── init-services             # 依赖容器主服务初始化（空文件）
        │  ├── run                          # 服务启动脚本（需可执行权限）
        │  └── type                         # 文件内容为 "longrun"（持续运行）
        └── user
          └── contents.d                    # 声明需加载的服务
            ├── init-mod-universal-mymod    # 声明初始化服务
            └── svc-mod-universal-mymod     # 声明持久服务

简单 Mod（仅添加文件/脚本）

适用于仅需添加文件或简单脚本的场景，通过基础 Dockerfile 实现：

Dockerfile
FROM docker.xuanyuan.run/scratch

# 复制本地文件到镜像层
COPY root/ /

操作步骤：

1. 在仓库根目录创建 root 文件夹，按上述目录结构组织文件
2. 初始化脚本（run 文件）需添加可执行权限：
   chmod +x root/etc/s6-overlay/s6-rc.d/init-mod-universal-mymod/run
3. 构建镜像，确保所有文件合并为单层

复杂 Mod（含构建逻辑）

适用于需动态下载文件、编译代码或多阶段构建的场景，通过多阶段 Dockerfile 实现：

Dockerfile
## 构建阶段 ##
FROM ***-ghcr.xuanyuan.run/linuxserver/baseimage-alpine:3.20 as buildstage

RUN \
  echo "* 安装依赖工具 *" && \
  apk add --no-cache curl && \
  echo "* 下载外部文件 *" && \
  mkdir -p /root-layer && \
  curl -o /root-layer/rclone.deb -L "https://downloads.rclone.org/v1.47.0/rclone-v1.47.0-linux-amd64.deb"

# 复制本地文件到构建层
COPY root/ /root-layer/

## 最终单层镜像 ##
FROM docker.xuanyuan.run/scratch

# 从构建层复制所有文件到单层
COPY --from=buildstage /root-layer/ /

包安装方法

如需在 Mod 中安装系统包，需通过 mod-repo-packages-to-install.list 或 mod-pip-packages-to-install.list 声明，由容器统一处理安装（支持 Ubuntu 和 Alpine）：

示例脚本（init-mod-universal-mymod/run）：

bash
#!/usr/bin/with-contenv bash

# Ubuntu 系统
if [ -f /usr/bin/apt ]; then
    echo "\
        dnsutils \
        net-tools \
        iputils-ping" >> /mod-repo-packages-to-install.list
fi

# Alpine 系统
if [ -f /sbin/apk ]; then
    echo "\
        bind-tools \
        net-tools" >> /mod-repo-packages-to-install.list
fi

包安装后操作：
如需在包安装后执行额外配置，需创建第二个初始化服务（如 init-mod-universal-mymod-postinstall），并依赖 init-mods-package-install。

发布 Mod 到 Docker Hub/GHCR

准备工作

• 需 GitHub 账号（用于代码托管和 Actions 构建）
• 需 Docker Hub 账号（用于镜像托管）

配置 GitHub Actions 构建

1. 复制模板仓库：https://github.com/linuxserver/docker-mods/tree/template
2. 修改 .github/workflows/BuildImage.yml，设置：

   yaml
   ENDPOINT: "user/endpoint"  # Docker Hub/GHCR 镜像路径（如 "myuser/mymod"）
   BRANCH: "master"           # 构建分支
   

3. 在 GitHub 仓库设置中添加密钥：
   • Docker Hub：DOCKERUSER（用户名）、DOCKERPASS（密码或令牌）
   • GHCR：CR_USER（GitHub 用户名）、CR_PAT（含 read:packages 和 write:packages 权限的令牌）
4. 提交代码后，Actions 自动构建并推送镜像到指定仓库

提交官方 Mod（PR 流程）

1. Fork 官方仓库 https://github.com/linuxserver/docker-mods
2. 基于 template 分支创建本地分支，命名格式：<基础镜像名>-<mod名>（如 nzbget-tshoot）
3. 编辑 Dockerfile（删除 Dockerfile.complex 示例文件）
4. 调整 root 目录内容，确保脚本权限正确（执行命令修复权限）：
   find ./ -path "./.git" -prune -o ( -name "run" -o -name "finish" -o -name "check" ) -not -perm -u=x,g=x,o=x -print -exec chmod +x {} +
5. 编辑 README 文档，添加 Mod 说明
6. 调整 .github/workflows/BuildImage.yml，设置 BASEIMAGE（基础镜像名）、MODNAME（Mod 名称）等参数
7. 提交 PR 到官方仓库的对应分支，确保提交信息格式为：<镜像名>: <mod名> <描述>（如 nzbget: tshoot add debug tools）

六、附录

文件编码要求

s6 初始化脚本（如 run、type 文件）必须使用 UTF-8 无 BOM 编码。若文件含 BOM，需通过编辑器去除（如 VS Code 中设置 "UTF-8" 编码）。

检查 Mod 内容

使用工具 dive 可查看 Mod 镜像层文件结构：

安装 dive

• 参考官方文档：https://github.com/wagoodman/dive

使用方法

带 Docker 环境：

bash
docker run --rm -it \
    -v /var/run/docker.sock:/var/run/docker.sock \
    docker.xuanyuan.run/wagoodman/dive:latest <镜像名> # 如 "lscr.io/linuxserver/mods:universal-tshoot"

本地安装 dive：

bash
dive <镜像名>  # 如 "lscr.io/linuxserver/mods:universal-tshoot"

安全注意事项

• 加载第三方 Mod 存在安全风险，需确保来源可信
• 官方技术支持将要求移除 DOCKER_MODS 环境变量以排查问题
• 禁用 RUN_BANNED_MODS 可能导致加载***镜像，谨慎使用