jauderho/tftpd Docker镜像文档

镜像概述和主要用途

jauderho/tftpd 是一个基于 tftp-hpa 实现的轻量级 TFTP (Trivial File Transfer Protocol) 服务器 Docker 镜像。该镜像源自 kalaksi/docker-tftpd 项目，专注于提供最小化、易于部署的 TFTP 服务。

主要用途：
提供符合 TFTP 协议的文件传输服务，支持文件上传与下载，适用于需要简单、无认证机制的网络文件传输场景。

核心功能和特性

• 轻量级设计：基于最小化基础镜像构建，镜像体积小，资源占用低。
• 可靠实现：采用 tftp-hpa（高性能 TFTP 服务器实现）作为核心，兼容性强。
• 易于配置：通过环境变量即可灵活调整服务参数，无需手动修改配置文件。
• 持久化支持：支持挂载宿主机目录作为 TFTP 根目录，实现文件持久化存储。
• 标准兼容：完全遵循 TFTP 协议（RFC 1350），支持 UDP 传输与标准文件操作。

使用场景和适用范围

典型使用场景

• PXE 网络启动：为无盘工作站、服务器提供启动镜像（如 Linux 内核、初始化文件）。
• 网络设备管理：网络交换机、路由器等设备的固件升级、配置文件备份/恢复。
• 嵌入式系统开发：嵌入式设备的程序镜像烧录、日志文件上传。
• 教育与测试环境：搭建简单的文件传输服务用于协议测试或教学演示。

适用范围

适用于需要 无认证、轻量级、低复杂度 文件传输的场景，不建议用于传输敏感数据或高并发业务。

详细使用方法和配置说明

前提条件

• 已安装 Docker 引擎（20.10+ 推荐）。
• 宿主机需开放 UDP 69 端口（TFTP 默认端口），或自定义端口。

1. 镜像拉取

从 Docker Hub 拉取最新版本镜像：

docker pull jauderho/tftpd:latest

2. 基本运行示例（docker run）

最简启动（默认配置）

docker run -d \
  --name tftpd \
  -p 69:69/udp \
  -v /path/to/tftp/files:/tftpboot \
  jauderho/tftpd:latest

• -p 69:69/udp：映射容器 UDP 69 端口到宿主机（TFTP 协议默认端口）。
• -v /path/to/tftp/files:/tftpboot：挂载宿主机目录 /path/to/tftp/files 作为 TFTP 根目录（容器内路径为 /tftpboot）。

自定义配置示例

指定自定义端口、允许文件上传、启用详细日志：

docker run -d \
  --name tftpd \
  -p 6969:69/udp \  # 宿主机端口 6969 映射到容器 69
  -v /data/tftp:/tftpboot \
  -e TFTP_DIR="/tftpboot" \  # TFTP 根目录（容器内路径）
  -e TFTP_PORT="69" \        # 容器内监听端口（需与 -p 映射一致）
  -e TFTP_OPTIONS="--secure --create --verbose" \  # 允许上传（--create）、详细日志（--verbose）
  jauderho/tftpd:latest

3. Docker Compose 配置示例

创建 docker-compose.yml 文件：

version: "3.8"

services:
  tftpd:
    image: jauderho/tftpd:latest
    container_name: tftpd
    restart: unless-stopped  # 异常退出后自动重启
    ports:
      - "69:69/udp"  # UDP 端口映射
    volumes:
      - ./tftp-root:/tftpboot  # 当前目录下 tftp-root 作为宿主机挂载点
    environment:
      - TFTP_DIR="/tftpboot"          # TFTP 根目录（容器内）
      - TFTP_USER="tftp"              # 运行服务的用户
      - TFTP_OPTIONS="--secure --create"  # 允许创建文件（上传）、限制根目录访问
    networks:
      - tftp-network  # 自定义网络（可选）

networks:
  tftp-network:
    driver: bridge

启动服务：

docker-compose up -d

4. 配置参数与环境变量

通过环境变量自定义服务行为，支持以下参数：

5. 文件操作示例

从客户端下载文件

tftp <宿主机IP>
tftp> get example.txt  # 下载容器内 /tftpboot/example.txt 到本地

向服务器上传文件

需先启用 --create 选项（见上文配置）：

tftp <宿主机IP>
tftp> put local-file.txt  # 上传本地文件到容器内 /tftpboot/local-file.txt

注意事项

1. 权限问题：
   宿主机挂载目录（如 /path/to/tftp/files）需确保容器内用户（默认 tftp，UID/GID 为 100:101）有读写权限，否则可能导致文件上传失败。可通过 chmod 777 /path/to/tftp/files 临时测试，生产环境建议通过 --user 参数指定宿主机用户 ID。

2. 防火墙配置：
   宿主机防火墙需允许 UDP 69 端口（或自定义端口）的入站流量，否则客户端无法连接。

3. 日志查看：
   通过 docker logs tftpd 查看服务运行日志，启用 --verbose 选项可获取更详细的传输记录。

4. 安全性：
   TFTP 协议无认证机制，请勿用于传输敏感数据。建议通过网络隔离（如 VLAN）限制访问范围。