PHP网站从FTP迁移到SFTP的完整教程

本文详解如何将 PHP 中基于传统 FTP 的文件上传逻辑安全迁移至 SFTP，涵盖环境准备、SSH2 扩展安装、代码重构及关键注意事项，无需第三方框架即可实现无缝升级。

本文详解如何将 PHP 中基于传统 FTP 的文件上传逻辑安全迁移至 SFTP，涵盖环境准备、SSH2 扩展安装、代码重构及关键注意事项，无需第三方框架即可实现无缝升级。

SFTP（SSH File Transfer Protocol）并非 FTP 的简单“加密版”，而是构建在 SSH 协议之上的独立文件传输机制。它不依赖 FTP 端口（21）或明文认证，而是通过 SSH 加密通道（默认端口 22）完成身份验证与数据传输。因此，不能直接复用 ftp_connect() 等原生 FTP 函数——PHP 核心确实不提供原生 SFTP 支持，必须借助 ext-ssh2 扩展。

✅ 前置条件：确保 SFTP 服务与 PHP 扩展就绪

首先确认目标 Linux 服务器已启用 SFTP（绝大多数 SSH 服务如 OpenSSH 默认集成，无需额外安装）：

# 检查 SSH 服务状态（SFTP 随 SSH 启动）
sudo systemctl status sshd
# 验证端口监听
ss -tlnp | grep ':22'

接着为 PHP 安装并启用 ssh2 扩展（推荐系统包管理器安装，避免 PECL 手动编译）：

• Ubuntu/Debian：

  sudo apt update && sudo apt install php-ssh2
  sudo systemctl restart apache2  # 或 php-fpm

• CentOS/RHEL 8+：

  sudo dnf install php-pecl-ssh2
  sudo systemctl restart php-fpm

• 验证扩展是否生效：

? 重构代码：从 FTP 到 SFTP 的一对一迁移

以下为原 FTP 上传逻辑的等效 SFTP 实现，保留原有业务流程（用户上传 → 重命名 → 上传至远程路径），但使用 ssh2_sftp() 封装：

服务器地址（同原 FTP_SERVER）
$ssh_port = 22;             // 默认 SSH 端口，如自定义请修改
$ssh_user = FTP_USER;
$ssh_pass = FTP_PASS;
$sftp_remote_path = FTP_DESTINATION_PATH; // 远程目标目录，如 '/var/www/uploads/'
$url_path = "uploads/";

// 1. 建立 SSH 连接
$conn = @ssh2_connect($ssh_host, $ssh_port);
if (!$conn) {
    return 'error connecting to SFTP server';
}

// 2. 认证（支持密码或密钥，此处为密码认证）
if (!@ssh2_auth_password($conn, $ssh_user, $ssh_pass)) {
    return 'error authenticating with SFTP server';
}

// 3. 初始化 SFTP 子系统
$sftp = @ssh2_sftp($conn);
if (!$sftp) {
    return 'failed to initialize SFTP subsystem';
}

// 4. 处理文件名（保持原有逻辑）
$filename_fixed = str_replace(" ", "_", $file['name']);
$filename_fixed = str_replace("/", "-", $filename_fixed);
$remote_file = $sftp_remote_path . $filename_fixed;

// 5. 打开远程文件写入流，并上传本地临时文件
$sftp_stream = @fopen("ssh2.sftp://{$sftp}{$remote_file}", 'wb');
if (!$sftp_stream) {
    return "cannot open remote file for writing: {$remote_file}";
}

$local_stream = @fopen($file['tmp_name'], 'rb');
if (!$local_stream) {
    fclose($sftp_stream);
    return "cannot read local temporary file";
}

// 流式上传（适合大文件，避免内存溢出）
while ($buffer = fread($local_stream, 8192)) {
    if (fwrite($sftp_stream, $buffer) === false) {
        fclose($local_stream);
        fclose($sftp_stream);
        return "write error to remote file";
    }
}
fclose($local_stream);
fclose($sftp_stream);

// 6. 清理连接（注意：ssh2_connect 不需要显式关闭，但建议 unset 释放资源）
unset($sftp, $conn);
?>

⚠️ 关键注意事项与最佳实践

• 权限与路径：SFTP 路径是绝对路径，且需确保 $ssh_user 对 $sftp_remote_path 具有写权限（如 chown www-data:www-data /var/www/uploads/）；FTP 中相对路径行为在此不适用。
• 错误处理增强：@ 抑制符会掩盖关键错误。生产环境应启用 libssh2 日志或结合 ssh2_fetch_error() 进行调试。
• 安全性升级：
  • 强烈建议改用 SSH 密钥认证 替代密码（ssh2_auth_pubkey_file()），避免硬编码密码；
  • 禁用密码登录（PasswordAuthentication no in /etc/ssh/sshd_config）后，密钥成为唯一入口。
• 性能提示：对于高频小文件上传，可复用 $sftp 连接句柄（避免每次新建）；大文件务必采用流式读写，防止 memory_limit 触发。
• 兼容性提醒：ssh2_sftp() 返回的是资源句柄，不可直接用于 file_put_contents() —— 必须通过 fopen("ssh2.sftp://...") URL 封装访问。

迁移完成后，原有 FTP 用户凭据即失效，所有传输自动获得端到端加密与完整性校验。这不仅是协议升级，更是对网站运维安全基线的一次实质性加固。