FTP в PowerShell: загрузка, SFTP и контроль прогресса

Иллюстрация: команды PowerShell для работы с FTP и SFTP

Быстрые ссылки

How To Use FTP in PowerShell
Advanced FTP Transfers with PowerShell
Sending SFTP Transfers with Posh-SSH
Sending Huge Files with a Progress Bar in PowerShell

Что такое FTP и SFTP

FTP — протокол передачи файлов поверх TCP. Прост в использовании, но не всегда защищён по умолчанию.
SFTP — передача файлов поверх SSH. Обеспечивает шифрование и часто предпочтительнее для защищённых каналов.

Определение: “FtpWebRequest” — .NET-класс для работы с FTP-запросами, поддерживает дополнительные параметры, такие как UsePassive и TLS.

Важно: никогда не храните пароли в открытом виде в скриптах. Используйте переменные окружения или менеджер секретов.

Как использовать FTP в PowerShell (простой способ)

Самый простой способ загрузить файл — использовать объект WebClient и его метод UploadFile. PowerShell даёт доступ к .NET-библиотекам через New-Object.

WebClient.UploadFile

Пример (сохраните пароли вне скрипта):

$client = New-Object System.Net.WebClient

$client.Credentials = New-Object System.Net.NetworkCredential("username", "password")

$client.UploadFile("ftp://example.com/path/archive.zip", "C:\archive.zip")

Пояснение: этот подход работает быстро и просто. Однако WebClient не всегда корректно работает с TLS/SSL и не даёт гибкого управления активным/пассивным режимом FTP.

Совет по безопасности: вместо явной строки “username” и “password” используйте переменные окружения, например $Env:FtpUsername и $Env:FtpPassword.

Пример функции с переменными окружения:

function uploadToFTPServer($remote, $local) {
$client = New-Object System.Net.WebClient
$client.Credentials = New-Object System.Net.NetworkCredential($Env:FtpUsername, $Env:FtpPassword)
$client.UploadFile($remote, $local)
}

uploadToFTPServer "ftp://example.com/path/archive.zip", "C:\archive.zip"

Плюсы: простота, удобство для коротких задач и одноразовых передач. Минусы: ограничена поддержка TLS и режимов соединения.

Расширённые FTP-передачи с FtpWebRequest

Когда нужен контроль над TLS и пассивным/активным режимом, используйте System.Net.FtpWebRequest. Этот подход работает с потоками и подходит для больших файлов.

function uploadToFTPServer($remote, $local) {
$request = [System.Net.FtpWebRequest]::Create($remote)
$request.Credentials = New-Object System.Net.NetworkCredential($Env:FtpUsername, $Env:FtpPassword)
$request.Method = [System.Net.WebRequestMethods+Ftp]::UploadFile
$request.UsePassive = $true
$fileStream = [System.IO.File]::OpenRead($local)
$ftpStream = $request.GetRequestStream()
$fileStream.CopyTo($ftpStream)
$ftpStream.Dispose()
$fileStream.Dispose()
}

uploadToFTPServer "ftp://example.com/archive.zip" "C:\archive.zip"

Почему это полезно:

Поддержка TLS/SSL при правильной настройке сервера.
Можно отключить пассивный режим (UsePassive = $false), если требуется активное соединение.
Копирование через потоки не загружает весь файл в память.

Примечание: если сервер требует явной настройки TLS (FTPS), дополнительно настраивают свойство EnableSsl и сертификаты.

Отправка SFTP через модуль Posh-SSH

SFTP работает поверх SSH. В Windows PowerShell нет нативной реализации SFTP, поэтому используют сторонние модули, например Posh-SSH.

Установка модуля:

Install-Module -Name Posh-SSH

Пример использования:

Import-Module Posh-SSH
$Password = ConvertTo-SecureString $Env:FtpPassword -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential ($Env:FtpUsername, $Password)
$FilePath = "C:\archive.zip"
$SftpPath = '/folder'
$ThisSession = New-SFTPSession -ComputerName '1.2.3.4' -Credential $Credential
Set-SFTPFile -SessionId ($ThisSession).SessionId -LocalFile $FilePath -RemotePath $SftpPath
Get-SFTPSession | % { Remove-SFTPSession -SessionId ($_.SessionId) }

Плюсы SFTP:

Шифрование по умолчанию.
Аутентификация ключами и паролями.
Подходит для безопасных корпоративных передач.

Минусы:

Требуется установка модуля.
Немного более сложная настройка по сравнению с WebClient.

Отправка больших файлов с индикатором прогресса

Для долгих передач удобно показывать прогресс. Простой CopyTo скрывает прогресс, поэтому читаем и пишем буферами вручную и используем Write-Progress.

$request = [Net.WebRequest]::Create("ftp://example.com/path/archive.zip")

$request.Credentials =
New-Object System.Net.NetworkCredential($Env:FtpUsername, $Env:FtpPassword)
$request.Method = [System.Net.WebRequestMethods+Ftp]::UploadFile
$fileStream = [System.IO.File]::OpenRead("C:\archive.zip")
$ftpStream = $request.GetRequestStream()
$buffer = New-Object Byte[] 10240
while (($read = $fileStream.Read($buffer, 0, $buffer.Length)) -gt 0)
{
$ftpStream.Write($buffer, 0, $read)
$pct = ($fileStream.Position / $fileStream.Length)
Write-Progress `
-Activity "Uploading" -Status ("{0:P0} complete:" -f $pct) `
-PercentComplete ($pct * 100)
}
$ftpStream.Dispose()
$fileStream.Dispose()

Совет: уменьшите или увеличьте размер $buffer для оптимизации скорости и использования памяти. Больший буфер даёт меньше обращений, но требует больше памяти.

Когда подход не сработает (контрпримеры)

WebClient не поддерживает FTPS/TLS в некоторых сценариях — используйте FtpWebRequest.
Если сервер использует SFTP (SSH), WebClient и FtpWebRequest не помогут — нужен Posh-SSH или сторонний клиент.
При нестабильной сети простая повторная отправка может привести к дублированию файлов; внедрите идемпотентность (уникальные имена или контрольные суммы).

Альтернативные подходы и элементы экосистемы

WinSCP: популярный GUI и .NET-API для автоматизации FTP/SFTP задач.
curl: современный инструмент командной строки, поддерживает FTP/SFTP, FTPS.
AzCopy/rsync: для специфичных сценариев синхронизации и облачных хранилищ.

Выбор зависит от окружения, политики безопасности и требований к автоматизации.

Модель мышления: потоки vs полностью в памяти

“Буферизированное” копирование (потоки) читается частями и подходит для больших файлов.
“В памяти” копирование (когда весь файл читается в массив байт) проще, но требует памяти, равной размеру файла.

Правило: если файл > нескольких сотен МБ — используйте потоки.

Чеклист перед деплоем (роль-ориентированный)

Для разработчика:
- Код читабельный и параметризуемый.
- Нет “жёстко” захардкоденных паролей.
- Логирование ошибок и возвратные коды.
Для оператора (Ops):
- Протестировано в тестовой сети с тем же режимом (пас/акт).
- Проверены сертификаты для FTPS.
Для безопасника/SecOps:
- Используйте ключи SSH или менеджер секретов.
- Логирование и аудит доступов.

Быстрый SOP: загрузка файла через FtpWebRequest

Настройте переменные окружения FtpUsername и FtpPassword.
В PowerShell запустите функцию uploadToFTPServer (пример выше).
Проверьте код возврата и лог сервера.
Если нужно, включите EnableSsl и проверьте сертификат.
Повторите с тестовым небольшим файлом.

Отладка и распространённые ошибки

Ошибка аутентификации — убедитесь в правильности учётных данных и что сервер принимает выбранный механизм (пароль/ключ).
Проблемы с TLS/FTPS — проверьте цепочку сертификатов, дату и совместимость протоколов (TLS1.2 и выше).
“425 Can’t open data connection” — обычно связано с пассивным/активным режимом; переключите $request.UsePassive.
Ошибки прав доступа — проверьте разрешения на целевой папке и квоты.

Технические примечания по безопасности и конфиденциальности

Не храните пароли в репозиториях. Используйте менеджеры секретов (Windows Credential Manager, Azure Key Vault, HashiCorp Vault и т. п.).
Логи не должны содержать секреты.
При работе с персональными данными соблюдайте требования локального законодательства и политики компании.

Критерии приёмки

Файл корректно загружается на сервер в тестовой среде.
Передача не требует хранения пароля в явном виде.
Время передачи и использование сети находятся в пределах допустимых лимитов.
Лог содержит успешную запись и, при ошибке, понятное сообщение.

Глоссарий (в одну строку)

FTP — File Transfer Protocol, передача файлов по TCP.
FTPS — FTP поверх TLS/SSL.
SFTP — SSH File Transfer Protocol, передача файлов по SSH.
WebClient — .NET-класс для простых загрузок.
FtpWebRequest — .NET-класс с расширенными возможностями FTP.

Краткая сводка

WebClient хорош для быстрых и простых задач. FtpWebRequest даёт контроль над режимом и TLS и лучше подходит для больших файлов. SFTP через Posh-SSH — безопасный выбор для шифрованных передач. Всегда храните секреты безопасно и тестируйте передачи в условиях, близких к боевым.

Важно: используйте потоки для больших файлов и включайте мониторинг прогресса для долгих операций.