SFTP

![GitHub Workflow Status]([] !GitHub stars !Docker Stars ![Docker Pulls]([]

!OpenSSH logo

支持的标签及对应Dockerfile链接

• debian, latest (Dockerfile) !Docker Image Size (debian)
• alpine (Dockerfile) !Docker Image Size (alpine)

镜像概述和主要用途

基于OpenSSH的SFTP（SSH文件传输协议）服务器镜像，提供安全的文件传输服务。支持通过多种方式定义用户，可灵活配置权限、挂载存储卷，并支持完整的rsyslog日志功能。适用于需要安全文件共享、权限控制及持久化存储的场景。提供Debian（稳定）和Alpine（轻量）两种基础镜像供选择。

核心功能和特性

• 多用户管理：支持通过命令参数、环境变量（SFTP_USERS）或配置文件（/etc/sftp/users.conf）定义用户
• 灵活权限控制：可自定义用户UID/GID，确保挂载卷权限与主机文件系统一致
• 安全认证：支持密码（明文/加密）和SSH密钥两种认证方式
• 持久化存储：支持挂载主机目录或数据卷，实现文件持久化
• 主机密钥管理：可挂载自定义SSH主机密钥，避免容器重建导致的MITM警告
• 自动目录创建：用户配置中指定的目录会自动创建并赋予写权限
• 自定义脚本支持：可在/etc/sftp.d/目录挂载脚本，容器启动时自动执行
• 完整日志：集成rsyslog，提供详细的服务日志

使用场景和适用范围

• 个人或团队的安全文件共享服务
• 需要严格权限控制的文件传输场景
• 容器化环境中的SFTP服务部署
• 多用户隔离的文件存储需求
• 需要持久化存储和日志审计的SFTP服务

使用方法和配置说明

用户定义格式

用户配置遵循以下语法：
user:pass[:e][:uid[:gid[:dir1[,dir2]...]]]

• user: 用户名（必填）
• pass: 密码（为空时仅支持密钥登录）
• :e: 标记密码为加密格式（可选）
• uid: 用户ID（可选，默认自动分配）
• gid: 用户组ID（可选，默认与UID相同）
• dir1[,dir2]: 自动创建的子目录（可选，多个目录用逗号分隔）

卷挂载注意事项

• 用户被限制在其主目录（chroot），需将卷挂载到用户主目录的子目录（如/home/user/upload）
• 若直接挂载/home目录，需确保用户主目录下至少有一个可写子目录（用户无法直接在主目录创建文件）
• 挂载自定义主机密钥时，需提供/etc/ssh/ssh_host_*文件（如ssh_host_rsa_key、ssh_host_ed25519_key）

环境变量

• SFTP_USERS: 定义用户的环境变量，格式与配置文件相同（如"foo:pass:1001:100:upload,docs"）

使用示例

1. 最简单部署

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

• 创建用户foo，密码pass
• 自动创建upload目录（位于/home/foo/upload）
• 映射容器22端口到主机22端口，通过sftp foo@<host-ip>登录

2. 共享主机目录（指定UID）

docker run \
  -v /host/path/upload:/home/foo/upload \
  -p 2222:22 -d corilus/sftp \
  foo:pass:1001

• 将主机/host/path/upload目录挂载到用户foo的upload目录
• 指定用户UID为1001，确保与主机目录权限匹配
• 映射容器22端口到主机2222端口，通过sftp -P 2222 foo@<host-ip>登录

3. 使用Docker Compose部署

sftp:
  image: corilus/sftp
  volumes:
    - /host/path/upload:/home/foo/upload
  ports:
    - "2222:22"
  command: foo:pass:1001:100:upload,docs

4. 通过配置文件定义多用户

1. 创建用户配置文件users.conf：

foo:123:1001:100:upload
bar:456:1002:100:docs,backup

2. 启动容器：

docker run \
  -v /host/path/users.conf:/etc/sftp/users.conf:ro \
  -v sftp_data:/home \
  -p 2222:22 -d corilus/sftp

• sftp_data为数据卷，持久化存储用户主目录

5. 使用加密密码

1. 生成加密密码（以Python为例）：

docker run --rm python:alpine python -c "import crypt; print(crypt.crypt('YOUR_PASSWORD'))"

2. 启动容器（注意使用单引号包裹加密密码）：

docker run \
  -v /host/path/share:/home/foo/share \
  -p 2222:22 -d corilus/sftp \
  'foo:$1$0G2g0GSt$ewU0t6GXG15.0hWoOX8X9.:e:1001'

6. SSH密钥认证登录

docker run \
  -v /host/path/id_rsa.pub:/home/foo/.ssh/keys/id_rsa.pub:ro \
  -v /host/path/share:/home/foo/share \
  -p 2222:22 -d corilus/sftp \
  foo::1001

• 将公钥文件挂载到用户.ssh/keys/目录（所有.pub文件会自动追加到authorized_keys）
• 密码为空，仅允许密钥登录

7. 使用自定义SSH主机密钥

1. 生成主机密钥：

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

2. 启动容器：

docker run \
  -v /host/path/ssh_host_ed25519_key:/etc/ssh/ssh_host_ed25519_key \
  -v /host/path/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
  -v /host/path/share:/home/foo/share \
  -p 2222:22 -d corilus/sftp \
  foo::1001

8. 执行自定义脚本

1. 创建绑定挂载脚本bindmount.sh：

#!/bin/bash
# 挂载共享目录到多用户 home
mount --bind /data/common /home/dave/common
mount --bind /data/common /home/peter/common --read-only

2. 启动容器（需添加CAP_SYS_ADMIN权限）：

docker run \
  --cap-add=SYS_ADMIN \
  -v /host/path/bindmount.sh:/etc/sftp.d/bindmount.sh \
  -v /host/data:/data \
  -p 2222:22 -d corilus/sftp \
  dave::1001 peter::1002

Debian与Alpine版本区别

OpenSSH版本查询

• Alpine版本：Alpine packages - openssh
• Debian版本：Debian packages - openssh-server

注：镜像构建时间可能延迟OpenSSH官方更新，建议通过官方仓库确认具体版本，或自行克隆源码构建。