cashstory/pureftpd-api

Docker Pure-ftpd Server with API

基于 https://github.com/stilliard/docker-pure-ftpd 和 https://github.com/garywiz/chaperone 构建，提供带API的FTP服务器，支持虚拟用户管理。

镜像概述

本镜像扩展了stilliard的pure ftpd镜像，添加了API接口用于管理FTP虚拟用户，并优化了安全配置（如禁止***登录、限制并发连接等），同时支持数据持久化和TLS证书自动生成。

核心功能

1. API用户管理：通过API实现用户的添加、删除、更新、查询及列表获取；
2. 安全配置：包含禁止***登录、限制并发连接、禁用CHMOD命令、TLS加密等安全选项；
3. 数据持久化：支持通过卷挂载保存用户数据库和上传文件；
4. 自动TLS证书：满足条件时自动生成自签名TLS证书；
5. 性能优化：包含主机名解析禁用、带宽限制等性能相关配置。

使用场景

• 企业内部FTP服务，需动态管理用户权限；
• 开发者测试环境中的文件传输需求；
• 需要通过API集成FTP用户管理的业务系统；
• 对安全性和可扩展性有要求的FTP服务场景。

配置说明

环境变量

• X_API_KEY：API访问密钥，生产环境需手动指定（否则容器重启时会自动生成新密钥）；
• PUBLICHOST：PASV模式的IP/主机名；
• TLS_CN/TLS_ORG/TLS_C：自签名TLS证书的配置参数（需配合ADDED_FLAGS=--tls使用）。

卷挂载

• /home/ftpusers/：FTP上传数据存储目录；
• /etc/pure-ftpd：用户数据库文件存储目录（需挂载以持久化用户信息）；
• /etc/ssl/private/：TLS证书存储目录（需挂载以持久化证书）。

API操作示例

添加用户：

bash
curl -X POST --header "X-api-key:YOURAPIKEY" -F 'username=davidwalsh' -F 'password=toto' localhost:5000/user/add

获取用户列表：

bash
curl -X GET --header "X-api-key:YOURAPIKEY" localhost:5000/user/list

更新用户密码：

bash
curl -X PUT --header "X-api-key:YOURAPIKEY" -F 'username=davidwalsh' -F 'password=newpass' localhost:5000/user/password

部署示例

Docker Run命令

bash
docker run -d --name ftpd_server \
  -p 21:21 \
  -p 30000-30099:30000-30099 \
  -e "PUBLICHOST=localhost" \
  -e "X_API_KEY=your_secure_key" \
  -v my-db-volume:/etc/pure-ftpd \
  -v my-data-volume:/home/ftpusers \
  cashstory/pureftpd-api:hardened

Docker Compose配置

yaml
version: '3'
services:
  ftpd_server:
    image: cashstory/pureftpd-api:hardened
    ports:
      - "21:21"
      - "30000-30099:30000-30099"
    environment:
      - PUBLICHOST=localhost
      - X_API_KEY=your_secure_key
    volumes:
      - my-db-volume:/etc/pure-ftpd
      - my-data-volume:/home/ftpusers
volumes:
  my-db-volume:
  my-data-volume:

更多配置细节请参考 pure-ftpd官方文档 及镜像依赖项目的说明。