Drive Sync 아키텍처: URL, 범위, 감사

개발자용 Drive Sync 참조입니다. REST API 또는 MCP server와 동기화 접근을 통합하거나 TrekMail Drive 기반 도구를 만들거나 WebDAV 권한 적용을 감사할 때 사용합니다.

rclone 또는 Finder 연결만 필요하면 Drive Sync 개요부터 확인하세요.

Drive Sync란

Drive Sync는 TrekMail Drive의 WebDAV 인터페이스입니다. 호환 동기화 앱이 별도 기기 비밀번호와 선택한 권한으로 대시보드 및 웹메일과 같은 파일에 접근합니다.

고정 접두사에서 표준 WebDAV 메서드를 사용합니다. 클라이언트 지원이 다르므로 운영 마이그레이션이나 백업 전에 임시 폴더에서 필요한 작업을 시험하세요.

URL 구조

Drive URL은 배포별로 생성되어 Sync devices에 표시됩니다. 대시보드 도메인으로 만들지 말고 복사하세요. 경로는 /dav/files/로 시작합니다.

https://YOUR-DRIVE-HOST/dav/files/

루트 아래에는 계정 트리와 사서함 트리가 있습니다. 비밀번호가 열 수 있는 범위는 사서함 연결과 선택 권한 모두에 따라 달라집니다.

계정 전체 트리

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

대시보드의 Account Drive입니다. 한 사서함으로 제한되지 않은 비밀번호는 Account Drive 권한이 있으면 이 트리를 볼 수 있습니다.

사서함 범위 트리

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

한 사서함으로 제한된 비밀번호는 해당 개인 트리만 봅니다. 개인 Drive 접근 권한과 계정 공유 폴더가 있으면 Shared/에 모든 사서함과 공유된 계정 폴더가 표시됩니다.

제한된 비밀번호는 Account Drive나 다른 사서함을 볼 수 없습니다. 제한 없는 비밀번호는 계정 Drive 공간을 나열할 수 있지만 각 경로에는 대응하는 계정 또는 사서함 권한이 필요합니다.

기기 비밀번호 만들기

대시보드 Sync devices 또는 현재 사서함의 웹메일에서 만듭니다. 대시보드는 계정 전체 또는 한 사서함 제한 비밀번호를 만들며 웹메일은 로그인한 사서함 전용입니다.

명확한 라벨, 필요한 권한만 선택하고 임시 연결에는 만료를 정하세요. 비밀 값은 한 번만 표시되므로 확인 화면을 닫기 전에 앱이나 비밀번호 관리자에 저장하세요.

일반 TrekMail 비밀번호를 바꾸지 않고 언제든 취소할 수 있습니다. 취소되거나 만료된 비밀번호는 즉시 작동을 멈춥니다.

기기 비밀번호로 로그인

동기화는 HTTPS를 통한 HTTP Basic을 사용합니다. Sync devices의 사용자 이름과 생성 비밀번호를 입력하고 대시보드 비밀번호는 사용하지 마세요.

취소 또는 만료되면 앱이 보통 자격 증명을 다시 요청합니다. 계정 상태, 사서함과 Drive 접근, 선택 권한은 요청마다 확인됩니다.

범위 모델

REST API와 같은 drive:{family}:{action} 형식을 사용합니다. 기기 비밀번호에는 다음 여덟 가지가 적용됩니다.

읽기에는 :read, 생성, 변경, 이동, 복사, 삭제에는 :write가 필요합니다. 경로가 계정 또는 사서함 접근을 결정하므로 제한 비밀번호는 Account Drive나 다른 사서함에 접근할 수 없습니다.

Sync devices는 동기화 앱에 적합한 권한만 제공합니다. Billing permissions는 포함되지 않습니다.

Share 및 purge 권한

계정 자격이 있으면 :share와 :purge가 표시됩니다. 현재 WebDAV route guard는 파일 작업을 :read와 :write에만 매핑하므로 선택해도 WebDAV 링크 또는 영구 삭제 명령이 추가되지 않습니다.

일반 WebDAV DELETE에는 :write가 필요하며 파일을 Trash로 옮깁니다. WebDAV는 제자리 파일 교체나 영구 purge를 제공하지 않으므로 Drive 인터페이스를 사용하세요.

파일 이름 안전

이름은 여러 운영 체제에서 안전해야 합니다. 빈 이름, 경로 구분자, 제어 문자, 오해를 부르는 문자, Windows 또는 Unicode 정규화 후 충돌하는 이름은 거부됩니다. 최대 255개 표시 문자입니다.

검증 오류가 발생하면 앱에서 이름을 바꾸고 다시 시도하세요. 파일 이름에 경로를 넣어 우회하지 마세요.

청크 업로드

작은 파일은 일반 PUT을 사용합니다. Nextcloud chunked-upload v2 클라이언트는 /dav/uploads/{session-uuid}/ 아래에 세션을 만들고 번호 청크를 올린 뒤 MOVE로 최종 위치에 조립합니다.

제한은 배포와 클라이언트에 따라 다릅니다. 실패 또는 만료 세션은 새 시도로 처리하세요. 다른 클라이언트가 목적지를 먼저 만들었다면 충돌 응답으로 새 이름을 선택하거나 폴더를 새로 고치세요.

감사 기록

Sync의 성공한 변경은 Drive 활동 기록에 표시됩니다. 대상, 작업, 시간, 사용한 기기 비밀번호가 기록되어 관리자가 조사하고 비밀번호를 취소할 수 있습니다.

Drive change feed 클라이언트는 WebDAV 변경도 봅니다. 전체 재동기화를 요구하면 저장 cursor를 계속하기 전에 새 snapshot에서 로컬 보기를 다시 구성하세요.

속도 제한

Drive Sync 요청은 제한됩니다. 429를 받으면 concurrency를 낮추고 제공된 Retry-After를 따르며 작은 작업을 재시도한 뒤 작업을 재개하세요.

제공 상태

Drive Sync는 production에서 제공됩니다. Drive 접근이 필요하며 권한은 계정, 사서함, 요금제와 생성자에 따라 달라집니다. White Label도 같은 서비스를 사용합니다. URL은 항상 Sync devices에서 복사하세요.

다음 단계

• 사용자 설정은 Drive Sync 개요.
• 기기 비밀번호 발급 UI는 Sync devices.
• REST API와 MCP 대응 작업은 Drive API 개요 및 Drive API 범위와 권한.
• 저장소 및 할당량 모델은 공유 저장소 할당량 설명.