stilliard/pure-ftpd

Docker Pure-ftpd Server 镜像文档

镜像概述和主要用途

Docker Pure-ftpd Server是一个基于Debian系统构建的Pure-ftpd服务器镜像，提供轻量级、安全的FTP服务。该镜像支持虚拟用户管理、TLS加密传输、被动模式（PASV）配置、数据持久化及自定义服务器参数，适用于个人或企业快速部署可靠的文件传输服务。

核心功能和特性

• 虚拟用户管理：支持创建独立虚拟用户，隔离用户权限和目录
• TLS加密：可选TLS/SSL加密，支持自签名证书和Let's Encrypt证书
• 被动模式支持：可配置被动端口范围，适应防火墙和NAT环境
• 数据持久化：通过Docker卷挂载实现用户数据和配置持久化
• 自定义配置：支持通过环境变量和命令行参数调整服务器参数
• 多版本支持：提供基于不同Debian版本的镜像标签（Trixie、Bookworm、Bullseye等）
• 日志功能：支持详细传输日志和服务器日志，便于监控和调试

使用场景和适用范围

• 个人或团队需要快速搭建临时或长期FTP服务
• 企业内部文件共享和传输需求
• 开发/测试环境中的文件传输服务
• 需要安全加密传输的场景（如包含敏感数据的文件传输）
• 需要多用户隔离访问的文件存储服务

使用方法和配置说明

拉取镜像

bash
docker pull stilliard/pure-ftpd

若出现权限错误，可能需要将用户添加到docker组或使用sudo执行命令

基本运行命令

bash
docker run -d --name ftpd_server \
  -p 21:21 \
  -p 30000-30009:30000-30009 \
  -e "PUBLICHOST=localhost" \
  stilliard/pure-ftpd

创建运行时FTP用户

通过环境变量创建用户：

bash
docker run -d --name ftpd_server \
  -p 21:21 \
  -p 30000-30009:30000-30009 \
  -e "PUBLICHOST=localhost" \
  -e "FTP_USER_NAME=bob" \
  -e "FTP_USER_PASS=12345" \
  -e "FTP_USER_HOME=/home/bob" \
  stilliard/pure-ftpd

可通过FTP_USER_UID和FTP_USER_GID指定用户ID和组ID：

bash
-e "FTP_USER_UID=1000" -e "FTP_USER_GID=1000"

自定义被动端口范围

如需使用非默认被动端口（如***-***）：

bash
docker run -d --name ftpd_server \
  -p 21:21 \
  -p 10000-10009:10000-10009 \
  -e "PUBLICHOST=localhost" \
  -e "FTP_PASSIVE_PORTS=10000:10009" \
  --expose=10000-10009 \
  stilliard/pure-ftpd

进入容器操作

bash
docker exec -it ftpd_server /bin/bash

在容器内创建FTP用户

bash
pure-pw useradd bob -f /etc/pure-ftpd/passwd/pureftpd.passwd -m -u ftpuser -d /home/ftpusers/bob

-m选项会自动创建用户目录并更新用户数据库，无需重启服务

修改用户密码

bash
pure-pw passwd bob -f /etc/pure-ftpd/passwd/pureftpd.passwd -m

测试连接

从主机测试FTP连接：

bash
ftp -p localhost 21

Docker Compose配置示例

基础配置（docker-compose.yml）：

yaml
version: '3'
services:
  ftpd_server:
    image: stilliard/pure-ftpd
    container_name: ftpd_server
    ports:
      - "21:21"
      - "30000-30009:30000-30009"
    environment:
      - PUBLICHOST=localhost
      - FTP_USER_NAME=bob
      - FTP_USER_PASS=12345
      - FTP_USER_HOME=/home/bob
    volumes:
      - ftpdata:/home/ftpusers
      - ftppasswd:/etc/pure-ftpd/passwd
    restart: always

volumes:
  ftpdata:
  ftppasswd:

配置参数说明

环境变量

卷挂载

TLS配置

自签名证书生成

在容器内执行以下命令生成自签名证书：

bash
mkdir -p /etc/ssl/private
openssl dhparam -out /etc/ssl/private/pure-ftpd-dhparams.pem 2048
openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout \
    /etc/ssl/private/pure-ftpd.pem \
    -out /etc/ssl/private/pure-ftpd.pem
chmod 600 /etc/ssl/private/*.pem

自动生成TLS证书

当ADDED_FLAGS包含--tls（如--tls=1或--tls=2）且/etc/ssl/private/pure-ftpd.pem不存在时，可通过设置以下环境变量自动生成自签名证书：

bash
-e "ADDED_FLAGS=--tls=2" \
-e "TLS_CN=ftp.example.com" \
-e "TLS_ORG=MyOrg" \
-e "TLS_C=CN"

Let's Encrypt证书配置

将Let's Encrypt的证书和密钥文件合并为pure-ftpd.pem：

bash
cat /etc/letsencrypt/live/ftp.example.com/cert.pem /etc/letsencrypt/live/ftp.example.com/privkey.pem > /etc/ssl/private/pure-ftpd.pem

通过卷挂载该文件到容器：

bash
-v /path/to/letsencrypt/pure-ftpd.pem:/etc/ssl/private/pure-ftpd.pem

日志配置

启用详细日志

bash
docker run -d --name ftpd_server \
  -p 21:21 -p 30000-30009:30000-30009 \
  -e "PUBLICHOST=localhost" \
  -e "ADDED_FLAGS=-d -d" \
  stilliard/pure-ftpd

查看日志：

bash
docker logs -f ftpd_server

启用传输日志

bash
docker run -d --name ftpd_server \
  -p 21:21 -p 30000-30009:30000-30009 \
  -e "PUBLICHOST=localhost" \
  -e "ADDED_FLAGS=-O w3c:/var/log/pure-ftpd/transfer.log" \
  -v ftplogs:/var/log/pure-ftpd \
  stilliard/pure-ftpd

镜像标签说明

旧版本标签（不再更新）：buster-1.0.47、stretch-latest、jessie-latest、wheezy-1.0.36

默认配置选项说明

/usr/sbin/pure-ftpd          # pure-ftpd可执行文件路径
-c 5                         # 最大客户端数（同时5人）
-C 5                         # 每IP最大连接数（5个请求）
-l puredb:/etc/pure-ftpd/pureftpd.pdb  # 虚拟用户登录文件
-E                           # 禁用匿名用户
-j                           # 自动创建主目录（如不存在）
-R                           # 禁止使用CHMOD命令
-P $PUBLICHOST               # PASV支持的IP/主机名（来自PUBLICHOST环境变量）
-p 30000:30009               # PASV端口范围（10个端口对应5个最大客户端）
-tls 1                       # 启用可选TLS支持

更多配置选项可参考：pure-ftpd手册