SFTP 마운트 심볼릭 링크 문제 해결 — NetDrive

SFTP 서버의 배포 디렉터리에는 현재 활성화된 릴리스 폴더를 가리키는 current 심볼릭 링크가 있는 경우가 많습니다 — current → releases/20260821-1. 무중단 배포에서 흔히 쓰는 패턴이지만, NetDrive를 그 서버에 연결하는 순간 조용히 문제를 일으키기 딱 좋은 요소이기도 합니다. 링크가 빈 파일로 보이거나, 깨진 바로가기로 표시되거나, 아예 나타나지 않기도 하며, S:\current\config.yaml이 그냥 작동하기를 기대하던 스크립트가 갑자기 실패합니다.

심볼릭 링크가 제대로 작동하는 SFTP 서버 마운트

NetDrive 는 Google Drive, OneDrive, S3, SFTP, WebDAV 등을 Windows 와 macOS 에서 일반 드라이브처럼 보이게 합니다 — 동기화도, 전체 다운로드도 없이.

• 3.17.817 버전 이상에서는 SFTP 마운트의 심볼릭 링크가 올바르게 풀립니다
• 비밀번호 또는 SSH 키 인증 지원
• Windows, macOS, 실험적 Linux 빌드에서 사용 가능

WindowsmacOS

NetDrive 다운로드 →

무료 체험. 평생 라이선스와 구독 플랜 제공.

먼저 버전을 확인하세요

NetDrive는 3.17.817 버전(2023-01-07)부터 SFTP 연결의 심볼릭 링크를 지원합니다. 그 이전 빌드에서는 서버의 심볼릭 링크에 대응하는 항목이 마운트된 쪽에 전혀 존재하지 않습니다 — 나타나지 않거나, 대상을 가리키는 대신 0바이트 파일로 표시될 수 있습니다. “심볼릭 링크가 작동하지 않는다”는 문의의 가장 흔한 원인이므로, 서버 쪽을 건드리기 전에 먼저 배제해야 할 항목입니다.

설치된 버전을 확인하려면 NetDrive의 Drive Manager를 열고 NetDrive 아이콘(Windows는 시스템 트레이, macOS는 메뉴 바)을 클릭한 뒤 About NetDrive를 엽니다. 버전 문자열이 3.17.817보다 오래된 것이면 계속 진행하기 전에 업데이트하세요 — 현재 릴리스는 3.19.7이며 netdrive.net/download에서 받을 수 있습니다.

이미 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 계정을 막고 있을 수 있습니다. 둘 다 확인하세요.

마운트를 통해 수정 여부 확인하기

버전 문제를 배제하고 링크가 상대 경로이며 루트 안에 있고 실제로 존재하는 대상을 가리키는 것을 확인했다면, 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 마운트에서의 심볼릭 링크 처리는 서로 독립된 두 가지로 귀결됩니다: NetDrive 빌드가 이를 지원하는지(3.17.817 이상) 여부와, SFTP 계정의 관점에서 링크 자체가 유효한지 여부입니다. 더 빠른 해결책이니 버전부터 확인한 다음, NetDrive를 탓하기 전에 링크의 대상을 점검하세요. 더 폭넓은 SFTP 연결 문제는 Fix SFTP Authentication Failures in NetDrive를, 초기 설정은 Mount an SFTP Server on Windows를 참고하세요.

— Morgan, NetDrive