Node.js と ssh2-sftp-client による SFTP へのファイルエクスポート
put() でローカルファイルをアップロードし、get() でダウンロードして、バイト列を比較してから成功を報告します。このチュートリアルでは、ssh2-sftp-client、SSH 鍵認証、一時的なローカル OpenSSH サーバーを使います。既存の SFTP アカウントがなくても、転送の全手順を試せます。
ユーザーだけでなくサーバーも認証
SFTP は SSH 経由でファイルを転送します。クライアント鍵はサーバーに対してユーザーを識別し、サーバーのホスト鍵はユーザーに対してサーバーを識別します。内部で使われる ssh2 クライアントは、hostVerifier を指定しない限りホスト鍵を自動的に受け入れるため、この例ではホスト鍵を明示的に検証します。
既存のサーバーを使う場合は、信頼できる経路で管理者からホスト鍵のフィンガープリントを取得してください。hostHash: 'sha256' を指定すると、ssh2 は、SSH 公開鍵の生のバイト列から生成した小文字の 64 文字の16進ダイジェストを検証関数に渡します。これは OpenSSH ツールが出力する SHA256: の base64 フィンガープリントとは異なるエンコーディングです。未検証の初回接続から期待値を取得しないでください。
クライアントプロジェクトの作成
以下のコマンドは、Linux 上で Bash、Node.js 26.12.1、Yarn 4.12.0、ssh-keygen、Docker Engine 28 以降を使います。クライアントは ssh2-sftp-client 12.1.1 に固定しています。Node が TypeScript ファイルを直接実行するため、ビルドは不要です。この例ではファイルの両方のコピーをメモリに保持するので、RAM に余裕を持って収まる小さなファイルを使ってください。
node-sftp-demo がまだ存在しないディレクトリで実行してください。&& でコマンドを連結しているため、ディレクトリの作成または移動に失敗するとセットアップが停止します。空のロックファイルにより、親ディレクトリが別のプロジェクトであっても、独立した Yarn プロジェクトとして扱われます。
mkdir node-sftp-demo &&
cd node-sftp-demo &&
printf '{"private":true,"type":"module"}\n' > package.json &&
touch yarn.lock &&
yarn add --exact ssh2-sftp-client@12.1.1 &&
ssh-keygen -q -t ed25519 -N '' -f client_key &&
printf 'Hello over SFTP.\n' > example.txt
以降のコマンドも、このディレクトリで実行してください。client_key は、このローカル演習専用の使い捨ての暗号化されていない秘密鍵です。コンテナには公開鍵だけを配置します。実際に使う秘密鍵はバージョン管理に含めず、サーバーで承認された認証設定を使ってください。
ローカル SFTP サーバーの起動
最初のターミナルで以下を実行してください。Ubuntu 24.04 コンテナ内に OpenSSH をインストールし、demo ユーザーを作成して、そのユーザー専用の書き込み可能な /home/demo/incoming ディレクトリを用意します。ForceCommand internal-sftp はセッションを SFTP に制限します。パスワードログインとフォワーディングは無効です。
docker run --rm --name node-sftp-demo \
--publish 127.0.0.1::22 \
--mount "type=bind,src=$PWD/client_key.pub,dst=/client_key.pub,readonly" \
ubuntu:24.04 bash -euc '
if ! command -v sshd >/dev/null; then
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends openssh-server
fi
useradd -m -s /bin/sh demo
passwd -d demo
install -d -m 700 -o demo -g demo /home/demo/.ssh /home/demo/incoming
install -m 600 -o demo -g demo /client_key.pub /home/demo/.ssh/authorized_keys
mkdir -p /run/sshd
ssh-keygen -q -t ed25519 -N "" -f /etc/ssh/demo_host_key
exec /usr/sbin/sshd -D -e -f /dev/null \
-o HostKey=/etc/ssh/demo_host_key \
-o PasswordAuthentication=no \
-o KbdInteractiveAuthentication=no \
-o PermitRootLogin=no \
-o AllowUsers=demo \
-o DisableForwarding=yes \
-o "Subsystem=sftp internal-sftp" \
-o ForceCommand=internal-sftp
'
Server listening on で始まる行が出力されたら、そのまま実行を続けてください。それより前に終了した場合は、出力されたエラーを解決してから先に進んでください。Docker はホストの空きポートを選び、ループバックにバインドします。サーバーのファイルとホスト鍵はこのコンテナ内にのみ存在し、コンテナを削除すると消えます。
node-sftp-demo でもう一つのターミナルを開いてください。割り当てられたポートを確認し、ローカルの Docker 接続経由でホストの公開鍵をコピーします。この例では、この接続を信頼できる管理経路として使います。
docker port node-sftp-demo 22/tcp &&
docker cp node-sftp-demo:/etc/ssh/demo_host_key.pub server_host_key.pub
最初のコマンドは、127.0.0.1:32768 のようなアドレスを出力します。以下では、実際に出力されたポートを使ってください。公開鍵をコピーすると、このデモ用ディレクトリにある既存の server_host_key.pub は置き換えられます。新しいコンテナには新しいホスト鍵が生成されるため、再作成したときはこの手順を繰り返してください。
単一ファイルのアップロードと検証
以下を transfer.ts として保存してください。ローカルパスとリモートファイルのフルパスは、コマンドライン引数で指定します。リモートの親ディレクトリはあらかじめ存在し、使用するアカウントでファイルを読み書きできる必要があります。
import { readFile } from 'node:fs/promises'
import Client from 'ssh2-sftp-client'
let stage = 'configuration'
async function main(): Promise<void> {
const [localPath, remotePath] = process.argv.slice(2)
const { SFTP_HOST, SFTP_PORT, SFTP_USERNAME, SFTP_KEY_FILE, SFTP_HOST_SHA256 } = process.env
const port = Number(SFTP_PORT ?? '22')
if (
!localPath || !remotePath || !SFTP_HOST || !SFTP_USERNAME || !SFTP_KEY_FILE ||
!/^[a-f0-9]{64}$/.test(SFTP_HOST_SHA256 ?? '') ||
!Number.isInteger(port) || port < 1 || port > 65535
) {
throw new Error('Provide two paths, SFTP settings, and a verified SHA-256 hex fingerprint')
}
stage = 'reading local files'
const original = await readFile(localPath)
const privateKey = await readFile(SFTP_KEY_FILE)
const sftp = new Client()
try {
stage = 'connect'
await sftp.connect({
host: SFTP_HOST,
port,
username: SFTP_USERNAME,
privateKey,
hostHash: 'sha256',
hostVerifier: (fingerprint: string) => fingerprint === SFTP_HOST_SHA256,
readyTimeout: 10000,
})
stage = 'upload'
await sftp.put(original, remotePath)
stage = 'download verification'
// Version 12.1.1 can return an empty array for a zero-byte download.
const downloaded = Buffer.from(await sftp.get(remotePath))
if (!original.equals(downloaded)) {
throw new Error('Downloaded bytes differ from the uploaded bytes')
}
} finally {
await sftp.end()
}
console.log(`Verified ${original.length} bytes at ${remotePath}`)
}
main().catch(() => {
console.error(`SFTP transfer failed during ${stage}; check the settings and server logs`)
process.exitCode = 1
})
put() は、指定したパスに既存のリモートファイルがあると置き換えます。上書きしても問題のない転送先を使ってください。直接書き込むため、転送が中断されると、不完全なファイルや一部だけのファイルが残ることがあります。検証に失敗しても元には戻りません。ダウンロードしたコピーはメモリに保持され、スクリプトはローカルにダウンロード用ファイルを作成したり、上書きしたりしません。Buffer.from() は、通常のバイナリバッファーに加えて空のダウンロード結果も正規化するため、正しいゼロバイトのファイルも検証を通過します。
パッケージのドキュメントには、put() と get() の説明があります。ここでは、同じ接続で順番に実行します。finally ブロックは、成功時も失敗時も end() を呼び出し、失敗時にはプロセスがゼロ以外の終了ステータスで終了します。接続の readyTimeout が制限するのは SSH ハンドシェイクの時間であり、転送全体ではありません。無人で実行する場合は、ジョブ全体の期限を設定してください。
二つ目のターミナルで接続情報を設定してください。32768 は、Docker が出力したポートに置き換えます。このコマンドは、信頼できる公開鍵の base64 フィールドをデコードして、そのバイト列をハッシュ化します。.pub ファイルのテキストをハッシュ化するわけではありません。
export SFTP_HOST=127.0.0.1 SFTP_PORT=32768 SFTP_USERNAME=demo SFTP_KEY_FILE=client_key
SFTP_HOST_SHA256=$(node --input-type=module -e '
import { createHash } from "node:crypto"
import { readFileSync } from "node:fs"
const [, key] = readFileSync("server_host_key.pub", "utf8").trim().split(/\s+/)
console.log(createHash("sha256").update(Buffer.from(key, "base64")).digest("hex"))
') &&
export SFTP_HOST_SHA256 &&
yarn node transfer.ts example.txt /home/demo/incoming/example.txt
付属のファイルの場合、成功すると次のように出力されます。
Verified 17 bytes at /home/demo/incoming/example.txt
自分の小さなファイルを転送するには、二つのパス引数を置き換えてください。スペースを含むパスは引用符で囲みます。比較が成功すれば、その時点でサーバーがアップロードしたものと同じバイト列を返したことが確認できます。バックアップとしての永続性や、別のプロセスがそのファイルを処理済みであることを示すものではありません。
転送失敗の診断
| 失敗した段階 | 確認事項 |
|---|---|
configuration | 両方のパス、1 から 65535 までの整数のポート番号、16進形式のフィンガープリントを指定してください。 |
reading local files | 転送元ファイルと秘密鍵が存在し、読み取れることを確認してください。 |
connect | ポート、信頼できるホスト鍵、ユーザー名、承認済みクライアント鍵を確認してください。ホスト鍵が変わった場合は、管理者への確認が必要です。 |
upload | リモートの親ディレクトリと書き込み権限を確認してください。スクリプトはディレクトリを作成しません。 |
download verification | 読み取り権限と、別のプロセスがリモートファイルを移動または変更していないかを確認してください。 |
サーバーの切断により、どちらの転送処理も失敗する可能性があります。再試行する前にサーバーのターミナルを調べ、転送先に不完全なファイルが残っていないか確認してください。接続エラーを回避するためにホスト検証関数を削除しないでください。既存のサーバーでは、その SFTP アカウントから見えるパスを使います。chroot されたアカウントでは、管理者にはより長いファイルシステムパスが見えていても、/incoming/example.txt と見える場合があります。
ローカルサーバーの停止
完了したら、二つ目のターミナルで以下を実行してください。
docker stop node-sftp-demo
サーバーは --rm を指定して起動したため、停止するとコンテナとアップロードしたファイルが削除されます。ローカルプロジェクト、サンプルファイル、使い捨てのクライアント鍵は
node-sftp-demo に残ります。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
