kalaksi/tftpd

Docker TFTP服务器镜像文档

注意事项

由于Docker Hub的自动构建功能已不可用，本README不会自动更新，但会保持最新状态。这也意味着GitHub仓库不再显示为源码来源。镜像现在通过GitLab CI推送，构建过程日志可在GitLab查看。镜像同时发布在GitLab，建议优先使用GitLab仓库的镜像，尤其是在可能触及Docker Hub新限制的情况下。

仓库信息

• GitLab仓库（镜像地址：registry.gitlab.com/kalaksi-containers/tftpd）
• https://hub.docker.com/r/kalaksi/tftpd/%EF%BC%88%E9%95%9C%E5%83%8F%E5%9C%B0%E5%9D%80%EF%BC%9A%60docker.io/kalaksi/tftpd%60%EF%BC%89
• https://github.com/kalaksi/docker-tftpd

一、镜像概述与主要用途

本容器运行TFTP服务器，其/tftpboot目录预填充了PXE启动所需的文件和配置，同时兼容U-Boot和Raspberry Pi 4设备。

二、核心功能与特性

设计理念

本容器的设计以简洁性和安全性为核心。许多社区容器默认以root权限运行，且未提供删除不必要权限能力的支持；此外，复杂的shell脚本和非官方基础镜像增加了源码验证和镜像更新的难度。为解决这些问题，本镜像在设计时重点关注安全性、简洁性和整体质量。

关键特性状态

三、使用场景与适用范围

适用于需要构建PXE网络启动环境的场景，包括但不限于：

• 企业或实验室网络中多设备的批量网络启动
• 嵌入式设备（如Raspberry Pi 4、U-Boot兼容设备）的网络启动
• 需要通过TFTP协议提供启动文件的PXE客户端环境

四、使用方法与配置说明

支持的标签

• latest：默认标签，包含最新更新
• 次要版本化标签（遵循语义化版本）：如1.1，对应GitHub的1.1.x分支

配置说明

用户需自行填充/tftpboot/boot目录中的启动镜像，并通常需要替换/tftpboot/pxelinux.cfg目录为自定义配置。具体示例可参考源码仓库中的docker-compose.yml。

目录结构

以下为/tftpboot目录结构示例，包含LibreELEC和RaspBian（Raspberry Pi）的启动文件：

/tftpboot
 ├── pxelinux.cfg           <- PXELINUX配置目录（需挂载自定义目录覆盖以定制）
 │   └── default            <- 默认配置文件
 ├── boot                   <- 存放启动文件的目录（需用户填充）
 │   ├── libreelec
 │   │   └── KERNEL         <- 示例：LibreELEC内核文件
 │   └── root               <- 可选特殊目录（内容会复制到TFTP根目录，适用于Raspberry Pi）
 │       ├── bootcode.bin   <- Raspberry Pi必需的根目录文件
 │       └── your-rpi4-serial  <- 按设备序列号的启动文件目录（详见RPi网络启动文档）
 │           ├── start.elf
 │           └── ...
 │
 └── syslinux               <- 预填充的Syslinux文件（无需修改）
     ├── pxelinux.0         <- BIOS启动加载器（传统PXE客户端使用，DHCP需指向"syslinux/pxelinux.0"）
     ├── efi64
     │   └── syslinux.efi   <- UEFI 64位启动加载器（客户端需指向"syslinux/efi64/syslinux.efi"，注意：UEFI+Syslinux可能存在传输速度慢等问题）
     ├── boot -> ../boot    <- 指向boot目录的符号链接
     ├── pxelinux.cfg -> ../pxelinux.cfg  <- 指向pxelinux.cfg目录的符号链接
     └── ...

自定义pxelinux.cfg配置示例

创建自定义pxelinux.cfg/default文件，示例内容如下：

DEFAULT menu.c32
PROMPT 0
TIMEOUT 100
ONTIMEOUT local

MENU TITLE 主菜单
LABEL libreelec
    MENU LABEL LibreELEC
    kernel boot/libreelec/KERNEL
    append <在此插入启动参数>

LABEL local
    MENU LABEL 从本地磁盘启动
    LOCALBOOT 0

使用HTTP替代TFTP传输文件

在部分场景中，TFTP可能速度缓慢或不稳定，此时可使用HTTP传输启动文件。需在kernel和append参数中指定HTTP服务器地址，示例：

    kernel http://HTTP服务器IP/boot/ubuntu/vmlinuz
    append initrd=http://HTTP服务器IP/boot/ubuntu/initrd.img <其他启动参数>

源码仓库的docker-compose.yml中包含一个注释掉的nginx服务示例，可用于通过HTTP提供启动文件。

五、Docker部署示例

docker-compose配置

建议参考源码仓库中的docker-compose.yml获取完整配置。典型配置需包含TFTP端口映射（UDP 69）、/tftpboot/boot和/tftpboot/pxelinux.cfg目录的挂载（用于自定义启动文件和配置），以及权限能力限制。

docker run命令示例

bash
docker run -d \
  --name tftpd \
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  -p 69:69/udp \
  -v /path/to/your/boot:/tftpboot/boot \
  -v /path/to/your/pxelinux.cfg:/tftpboot/pxelinux.cfg \
  registry.gitlab.com/kalaksi-containers/tftpd:latest

六、贡献

欢迎通过https://github.com/kalaksi/docker-tftpd%E6%8F%90%E4%BA%A4%E8%B4%A1%E7%8C%AE%EF%BC%8C%E5%8C%85%E6%8B%AC%E9%97%AE%E9%A2%98%E5%8F%8D%E9%A6%88%E3%80%81%E4%BB%A3%E7%A0%81%E6%94%B9%E8%BF%9B%E7%AD%89%E3%80%82

七、许可证

版权所有 (c) 2018 ***。许可证信息详见https://github.com/kalaksi/docker-airsonic/blob/master/LICENSE%E3%80%82

与所有Docker镜像一样，构建后的镜像可能包含其他软件，这些软件可能受其他许可证约束（如基础发行版的软件及依赖项）。使用预构建镜像时，用户有责任确保其使用符合所有包含软件的相关许可证要求。