stoffel2107/sftp

SFTP Docker镜像文档

支持的标签及对应Dockerfile链接

• https://github.com/atmoz/sftp/blob/master/Dockerfile !Docker Image Size (debian)
• https://github.com/atmoz/sftp/blob/master/Dockerfile-alpine !Docker Image Size (alpine)

镜像概述和主要用途

基于OpenSSH的SFTP（SSH文件传输协议）服务器镜像，旨在提供安全、易用的文件共享服务。支持通过多种方式定义用户，灵活挂载卷，适用于需要安全文件传输的场景，如开发环境文件交换、多用户隔离存储等。

核心功能和特性

• 灵活的用户管理：支持通过命令参数、SFTP_USERS环境变量或挂载配置文件（/etc/sftp/users.conf）定义用户
• 卷挂载支持：用户主目录支持卷挂载，可实现主机与容器间文件共享
• SSH密钥登录：支持通过挂载公钥实现无密码SSH密钥登录
• 自定义主机密钥：可挂载自定义SSH主机密钥，避免容器重建时的MITM警告
• 自定义脚本执行：支持在容器启动时执行/etc/sftp.d/目录下的自定义脚本
• 多版本支持：提供基于Debian（稳定）和Alpine（轻量）的两个版本

使用场景和适用范围

• 开发团队内部安全文件共享
• 服务器间文件传输服务
• 多用户隔离的文件存储服务
• 需要通过SFTP协议提供文件上传/下载的应用场景

使用方法和配置说明

用户定义语法

用户可通过以下三种方式定义，语法统一为：user:pass[:e][:uid[:gid[:dir1[,dir2]...]]]，各部分说明：

• user：用户名（必填）
• pass：密码（若使用SSH密钥登录可留空，格式为user::uid...）
• :e：可选，标记密码为加密格式
• uid：可选，用户UID（建议手动设置以匹配主机文件权限）
• gid：可选，用户GID
• dir1[,dir2]...：可选，在用户主目录下创建的子目录（自动赋予写权限）

卷挂载注意事项

• 用户被chroot到主目录，因此卷需挂载到用户主目录下的子目录（如/home/user/upload）或直接挂载/home目录
• 用户无法在主目录根目录直接创建文件，需确保至少有一个子目录用于文件上传

环境变量

• SFTP_USERS：用于定义用户，格式同用户定义语法，多个用户用空格分隔

详细使用示例

最简单的docker run示例

bash
docker run -p 22:22 -d atmoz/sftp foo:pass:::upload

创建用户“foo”，密码“pass”，可登录SFTP并上传文件到“upload”目录。无挂载目录或自定义UID/GID。

共享主机目录

挂载主机目录并设置UID：

bash
docker run \
    -v <主机目录>/upload:/home/foo/upload \
    -p 2222:22 -d atmoz/sftp \
    foo:pass:1001

使用Docker Compose：

yaml
sftp:
    image: atmoz/sftp
    volumes:
        - <主机目录>/upload:/home/foo/upload
    ports:
        - "2222:22"
    command: foo:pass:1001

登录方法

OpenSSH服务器默认运行在22端口，示例中容器22端口映射到主机2222端口。使用OpenSSH客户端登录：sftp -P 2222 foo@<主机IP>

通过配置文件存储用户

bash
docker run \
    -v <主机目录>/users.conf:/etc/sftp/users.conf:ro \
    -v mySftpVolume:/home \
    -p 2222:22 -d atmoz/sftp

<主机目录>/users.conf内容示例：

foo:123:1001:100
bar:abc:1002:100
baz:xyz:1003:100

使用加密密码

在密码后添加:e标记为加密密码（终端中使用需加单引号）：

bash
docker run \
    -v <主机目录>/share:/home/foo/share \
    -p 2222:22 -d atmoz/sftp \
    'foo:$1$0G2g0GSt$ewU0t6GXG15.0hWoOX8X9.:e:1001'

生成加密密码的Python命令：
docker run --rm python:alpine python -c "import crypt; print(crypt.crypt('你的密码'))"

使用SSH密钥登录

将公钥挂载到用户的.ssh/keys/目录，所有密钥会自动添加到.ssh/authorized_keys：

bash
docker run \
    -v <主机目录>/id_rsa.pub:/home/foo/.ssh/keys/id_rsa.pub:ro \
    -v <主机目录>/id_other.pub:/home/foo/.ssh/keys/id_other.pub:ro \
    -v <主机目录>/share:/home/foo/share \
    -p 2222:22 -d atmoz/sftp \
    foo::1001

提供自定义SSH主机密钥（推荐）

为避免容器重建时主机密钥变化导致MITM警告，可挂载自定义主机密钥：

bash
docker run \
    -v <主机目录>/ssh_host_ed25519_key:/etc/ssh/ssh_host_ed25519_key \
    -v <主机目录>/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
    -v <主机目录>/share:/home/foo/share \
    -p 2222:22 -d atmoz/sftp \
    foo::1001

生成主机密钥的命令：

bash
ssh-keygen -t ed25519 -f ssh_host_ed25519_key < /dev/null
ssh-keygen -t rsa -b 4096 -f ssh_host_rsa_key < /dev/null

执行自定义脚本或应用

将程序放入/etc/sftp.d/目录，容器启动时会自动运行。示例：绑定挂载其他位置的目录

bash
#!/bin/bash
# 挂载为: /etc/sftp.d/bindmount.sh

function bindmount() {
    if [ -d "$1" ]; then
        mkdir -p "$2"
    fi
    mount --bind $3 "$1" "$2"
}

# 注意权限，可能需要修复：
# chown -R :users /data/common

bindmount /data/admin-tools /home/admin/tools
bindmount /data/common /home/dave/common
bindmount /data/common /home/peter/common
bindmount /data/docs /home/peter/docs --read-only

注意：使用mount需要容器启用CAP_SYS_ADMIN capability，详情参见https://github.com/atmoz/sftp/issues/60#issuecomment-332909232%E3%80%82

Debian与Alpine版本的区别

主要区别在于大小和OpenSSH版本：

• 大小：Alpine版本比Debian小10倍
• OpenSSH版本：Alpine更新周期较短（约6个月），通常包含较新版本的OpenSSH；Debian更稳定，仅在发布后（约2年）提供bug修复和安全更新
• 推荐阅读：容器应用中Debian与Alpine的比较

OpenSSH版本说明

OpenSSH版本取决于所选的Linux发行版及版本，可通过以下链接查询：

• Alpine各版本openssh包列表
• Debian各版本openssh-server包列表

每日构建

镜像每日自动构建，以获取包管理器提供的最新OpenSSH版本。