SFTPマウントでシンボリックリンクが機能しない問題を解決 — NetDrive

読了目安 6 分 troubleshooting sftp
Morgan
MorganStaff Engineer
SFTPマウントのNetDriveでシンボリックリンクが解決しない問題をトラブルシューティング。バージョン要件、リンク切れ、権限が原因となるケースを解説します。

SFTPサーバー上のデプロイディレクトリでは、稼働中のリリースフォルダを指す current シンボリックリンクを保持することがよくあります — current → releases/20260821-1。これはゼロダウンタイムデプロイの定番パターンですが、NetDriveでそのサーバーに接続した瞬間、静かに壊れる典型例でもあります。リンクは空ファイルとして表示されたり、壊れたショートカットになったり、そもそも表示されなかったりし、S:\current\config.yaml がそのまま使えることを前提にしたスクリプトが、突然動かなくなります。

NetDrive drive manager showing Google Drive, S3 and pCloud mounted as drive lettersMounted clouds appearing as native drives in Windows File Explorer

シンボリックリンクが機能するSFTPサーバーのマウント

NetDrive を使えば Google Drive、OneDrive、S3、SFTP、WebDAV などが Windows と macOS でネイティブドライブとして表示されます — 同期も、まるごとダウンロードも不要です。

  • バージョン3.17.817以降、SFTPマウントでシンボリックリンクが正しく解決
  • パスワードまたはSSH鍵による認証
  • Windows、macOS、実験的なLinuxビルドで利用可能
WindowsmacOS
NetDriveをダウンロード →

無料トライアル。永久ライセンスとサブスクリプションプランあり。

まずバージョンを確認する

NetDriveがSFTP接続でのシンボリックリンク対応を追加したのは、バージョン 3.17.817（2023-01-07）です。それより前のビルドでは、サーバー上のシンボリックリンクに対応するものがマウント側に存在しません — 表示されないか、リンク先を指す代わりにゼロバイトのファイルとして表示されます。これは「シンボリックリンクが動作しない」という報告の中で最も多い原因であり、サーバー側を触る前にまず除外しておく価値があります。

インストール済みのバージョンを確認するには、NetDriveのDrive Managerを開き、NetDriveアイコン（Windowsではシステムトレイ、macOSではメニューバー）をクリックして About NetDrive を開きます。バージョン文字列が3.17.817より古い場合は、続行する前にアップデートしてください — 現行リリースは3.19.7で、netdrive.net/download から入手できます。

他のマウント済みドライブと並んでSFTP接続を表示するNetDriveのドライブマネージャー

すでに3.17.817以降を使っている場合はリンク自体を確認する

バージョンが原因でない場合、通常はシンボリックリンク自体の設定に問題があります。通常のSSHセッションでサーバー側から次の点を順に確認してください。

  • 絶対パスと相対パスのターゲット。 相対シンボリックリンク（current → releases/20260821-1）は自身のディレクトリを基準に解決され、マウント越しでも概ね問題なく機能します。絶対パスのシンボリックリンク（current → /var/www/app/releases/20260821-1）は、その絶対パスがSFTPアカウントから見たファイルシステム上にも存在し、到達可能な場合にのみ正しく解決されます — アカウントがサブディレクトリにchroot（隔離）されている場合、これは保証されません。

    # Run this on the server to see how the link is defined
ls -la /var/www/app/current

  • SFTPアカウントのルート外にあるターゲット。 サーバーによっては、SFTPユーザーをホームディレクトリや特定のパスを起点としたchroot環境に制限しています。そのルートの外を指すシンボリックリンクは、使用しているNetDriveのバージョンに関わらず、SFTPセッション自体から見えず、したがってNetDriveからも見えません。ターゲットのパスがSFTPアカウントのスコープと同じルート内に収まっているか確認してください。

  • リンク先が存在しない（ダングリングターゲット）。 シンボリックリンクが指しているリリースディレクトリが削除またはリネームされた場合（デプロイの途中終了や、早すぎるクリーンアップスクリプトの実行など）、リンク自体は正常でも解決先がありません。サーバー上で ls -la を実行すると、シェルの設定によってはリンクが別の色で表示されたり、壊れているとフラグが立ったりします。

  • リンクだけでなくターゲットの権限。 シンボリックリンクのファイル自体は読み取り可能でも、そのリンク先のディレクトリの権限がSFTPアカウントをブロックしている場合があります。両方を確認してください。

セットアップ後、接続したSFTPドライブが正常にマウントされたことを確認する

マウント経由で修正を確認する

バージョンを除外し、リンクが相対パスで、ルート内にあり、実在するものを指していることを確認したら、NetDriveでドライブを再接続し（Drive Managerで接続を右クリックして Reconnect を選ぶか、切断して再接続する）、マウントされたパスを直接確認します。

# Windows PowerShell — replace S: with your assigned drive letter
dir S:\current
# macOS / Linux Terminal
ls -la /Volumes/sftp-mount/current

対象フォルダの中身が正しく一覧表示されるようになれば、シンボリックリンクは正しく解決されています。バージョンとリンク自体の妥当性の両方を確認したにもかかわらず、依然として空または表示されない場合、残る原因は通常サーバー側のSFTPサブシステムの設定です — 具体的には、サーバーの sftp-server プロセスでシンボリックリンクのトラバーサルが無効化されているかどうかであり、これはNetDriveの設定ではなくサーバー管理者に確認すべき事項です。

まとめ

SFTPマウントにおけるシンボリックリンクの扱いは、独立した2つの要素に帰着します。NetDriveのビルドがそもそも対応しているか（3.17.817以降）、そしてリンク自体がSFTPアカウントの視点から見て有効かどうかです。まずバージョンを確認してください — こちらの方が早く解決できます — その上で、NetDriveに問題があると決めつける前にリンクのターゲットを確認しましょう。より広範なSFTP接続の問題についてはFix SFTP Authentication Failures in NetDriveを、初期セットアップについてはMount an SFTP Server on Windowsをご覧ください。

— Morgan, NetDrive

← 記事一覧 フォーラムで議論する →