Tencent Cloud COS 인증 오류 해결 — NetDrive

4분 읽기 troubleshooting tencent-cloud
Steve
SteveSenior Engineer
NetDrive가 Tencent Cloud COS 버킷에 연결되지 않나요? SecretId/SecretKey 쌍, CAM 권한, 리전 엔드포인트, 버킷 이름, 시스템 시계를 확인한 뒤 다시 연결하세요.

한 게임 스튜디오는 야간 빌드 산출물을 Tencent Cloud Object Storage(COS) 버킷에 보관하고, QA 리드의 Windows 워크스테이션은 NetDrive로 그 버킷을 마운트해 테스터들이 드라이브 문자에서 최신 빌드를 가져갑니다. 그런데 보안 점검에서 계정의 모든 API 키가 교체되자, 다음 날 아침 드라이브가 연결을 거부합니다. Tencent Cloud 인증 실패는 대부분 다섯 가지로 귀결됩니다. 키 쌍, 그 뒤의 CAM 권한, 리전 엔드포인트, 버킷 이름, 그리고 컴퓨터의 시계입니다. 이 가이드는 이 순서대로 점검합니다.

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

Tencent Cloud 드라이브를 되찾으세요

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

  • Windows 또는 macOS에서 COS 버킷을 드라이브로 마운트
  • Drive Manager에서 모든 드라이브의 상태 확인
  • 처음부터 다시 하지 않고 자격 증명 수정 후 재연결
WindowsmacOS
NetDrive 다운로드 →

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

오류 메시지로 원인 좁히기

NetDrive는 버전 3.17.799부터 Tencent Cloud를 지원하며, Tencent Cloud 드라이브를 저장할 때 연결을 확인합니다. 문제가 있으면 오류 메시지가 표시되고 동작하는 드라이브 카드는 생기지 않습니다. 필드를 바꾸기 전에 메시지를 먼저 읽으세요. COS 오류 코드마다 가리키는 문제가 다릅니다.

  • SignatureDoesNotMatch — SecretKey가 SecretId와 맞지 않거나, 값 중 하나에 불필요한 문자가 함께 붙여 넣어졌습니다.
  • InvalidAccessKeyId — Tencent Cloud가 해당 SecretId를 알지 못합니다. 삭제되었거나 비활성화되었거나 오타가 있습니다.
  • AccessDenied — 키는 유효하지만 키를 소유한 사용자가 이 버킷에 접근할 권한이 없습니다.
  • NoSuchBucket — 버킷 이름이나 리전이 실제로 존재하는 버킷과 일치하지 않습니다.
  • RequestTimeTooSkewed — 컴퓨터 시계가 Tencent Cloud 시간과 너무 많이 어긋나 서명된 요청이 거부되었습니다.

오류 코드를 적어 두세요. 한 번에 한 필드씩 고치고 매번 테스트하면 어떤 값이 원인이었는지 알 수 있습니다.

클라우드 드라이브와 연결 상태를 보여 주는 NetDrive Drive Manager

점검 1: SecretId와 SecretKey 쌍

Tencent Cloud API 키는 Tencent Cloud 콘솔의 CAM → API Keys에서 관리합니다. 키 교체 직후라면 NetDrive에 저장된 키 쌍이 가장 유력한 원인입니다.

  1. NetDrive가 사용하는 키의 소유 사용자에 대한 API 키 목록을 엽니다.
  2. NetDrive에 저장된 SecretId가 목록에 아직 있고 활성화되어 있는지 확인합니다.
  3. 삭제되었거나 비활성화되었다면 새 키를 만들고 SecretId와 SecretKey를 바로 복사합니다.
  4. 두 값을 NetDrive의 Tencent Cloud 드라이브 설정에 붙여 넣습니다. 앞뒤 공백에 주의하세요. 필드에서는 보이지 않지만 서명을 깨뜨립니다.

키 교체 과정에서 CAM 하위 사용자까지 삭제되었다면 키도 함께 사라집니다. 새 키를 만들기 전에 사용자가 아직 존재하는지 확인하세요.

점검 2: 버킷에 대한 CAM 권한

유효한 키로 AccessDenied 응답을 받는다면 문제는 키가 아니라 정책에 있습니다. 마운트에는 루트 계정의 키 대신 CAM 하위 사용자를 사용하고, 마운트할 버킷에 대한 접근 권한을 부여하세요. Tencent Cloud에는 QcloudCOSReadOnlyAccess, QcloudCOSFullAccess 같은 프리셋 정책이 있으며, 버킷 하나로 한정한 사용자 정의 정책을 작성할 수도 있습니다.

정책은 드라이브 사용 방식에 맞추세요. 읽기 전용 정책이면 테스터는 빌드를 탐색하고 복사할 수 있지만, 드라이브에 저장하는 작업은 모두 실패합니다. 의도한 동작이라면 NetDrive의 읽기 전용 드라이브 타입으로도 마운트하세요. 그러면 제한이 Explorer나 Finder에서 명확히 드러나고, 쓰기 실패로만 나타나지 않습니다. NetDrive의 읽기 전용 드라이브를 참고하세요.

점검 3: 리전 엔드포인트와 버킷 이름

COS 엔드포인트는 리전별이며 cos.<region>.myqcloud.com 형식을 따릅니다. 예를 들어 cos.ap-guangzhou.myqcloud.com 또는 cos.ap-singapore.myqcloud.com입니다. 광저우에서 만든 버킷은 싱가포르 엔드포인트에서 응답하지 않으며, 이때 나오는 오류는 자격 증명 실패처럼 보일 수 있습니다. 콘솔에서 버킷의 개요 페이지를 열고 리전을 그대로 복사하세요. 기억에 의존하지 마세요.

COS의 버킷 이름에는 항상 계정의 APPID가 접미사로 붙습니다. build-artifacts가 아니라 build-artifacts-1250000001입니다. 접미사를 빠뜨리는 것이 NoSuchBucket의 흔한 원인입니다. NetDrive의 이름과 콘솔의 이름을 한 글자씩 비교하세요.

설정을 수정한 뒤 NetDrive에서 드라이브의 마운트 상태 확인

점검 4: 시스템 시계

모든 COS 요청은 타임스탬프와 함께 서명됩니다. 컴퓨터 시계가 몇 분 이상 어긋나 있으면 키가 완벽해도 Tencent Cloud가 요청을 거부합니다. 오랫동안 오프라인이었던 컴퓨터나 오래된 스냅샷에서 복원한 VM에서 주로 발생합니다. Windows에서는 Settings → Time & language → Date & time을 열고 지금 동기화하세요. macOS에서는 System Settings → General → Date & Time에서 Set time and date automatically를 켜세요.

드라이브 다시 연결하기

잘못된 값을 수정했다면:

  1. Open NetDrive 후 Drive Manager에서 Tencent Cloud 드라이브를 찾습니다.
  2. 드라이브 설정을 열고 키 쌍, 엔드포인트 또는 버킷을 업데이트합니다.
  3. 저장하고 NetDrive가 연결을 다시 확인하도록 합니다.
  4. 드라이브 카드에서 연결하고 파일을 하나 열어 읽기가 되는지 확인합니다. 그런 다음 작은 테스트 파일을 저장해 쓰기가 되는지 확인합니다.

기존 항목을 수정해도 계속 실패하면 드라이브를 삭제하고 콘솔에서 방금 확인한 값으로 다시 추가하세요. 새 항목은 오래된 저장 설정의 영향을 배제합니다.

인증은 통과했는데 드라이브가 여전히 이상할 때

연결은 성공했는데 Windows에서 드라이브가 나타나지 않는다면 다른 장치가 이미 그 드라이브 문자를 쓰고 있을 수 있습니다. 드라이브 문자 사용 중 오류 해결을 참고하세요. 재연결 후에도 폴더에 어제 빌드가 보인다면 목록이 오래된 것입니다. 강제 폴더 갱신에서 새 목록을 가져오는 방법을 설명합니다.

마무리

Tencent Cloud COS 인증 오류는 체크리스트처럼 해결하세요. 키 쌍, CAM 정책, 리전 엔드포인트, APPID가 붙은 버킷 이름, 그리고 시계 순서입니다. 한 번에 하나씩 바꾸고 Drive Manager에서 다시 연결하세요. 처음 설정 전체는 NetDrive로 Windows에서 Tencent Cloud 마운트하기 또는 macOS 버전을 참고하세요. Alibaba Cloud도 함께 쓴다면 Alibaba Cloud 인증 오류 해결이 같은 흐름을 따릅니다.

— Steve, NetDrive