> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ones1ght.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SFTP 연결

> SFTP 서버에 있는 대용량 파일을 직접 읽도록 연결하세요

## SFTP 연결이란?

브라우저로 올리기 어려운 대용량 파일을 SFTP 서버에 두면, OneSight가 조회 시점에 해당 파일을 직접 읽습니다. 파일을 복사해 보관하지 않으므로 원본을 교체하면 다음 조회부터 바로 반영됩니다.

통신 구간은 SSH로 암호화됩니다. 암호화되지 않는 일반 FTP는 지원하지 않습니다.

<Note>
  데이터소스 등록은 **관리자(Admin)** 권한이 있는 사용자만 할 수 있습니다. 서버 계정 발급(1단계)은 해당 서버를 관리하는 담당자가 진행해야 합니다.
</Note>

## 준비물

* 서버 **주소**와 **포트** (기본 `22`)
* **읽기 전용** 계정과 그 계정의 **비밀번호** 또는 **SSH 개인키**
* 읽을 파일이 있는 **경로**

## 1단계: 읽기 전용 계정 준비 (서버)

OneSight는 파일 **목록 조회**와 **읽기**만 수행합니다. 파일을 올리거나 지우지 않으므로, 쓰기 권한이 없는 계정을 사용하세요.

<Steps>
  <Step title="전용 계정 만들기">
    OneSight 연결에만 쓰는 계정을 별도로 만듭니다. 다른 용도와 공유하지 않아야 나중에 접근을 회수하기 쉽습니다.
  </Step>

  <Step title="필요한 경로만 열기">
    데이터 파일이 있는 디렉터리에만 읽기 권한을 부여합니다. 가능하다면 해당 디렉터리 밖으로 나갈 수 없도록 제한(chroot 등)하는 것을 권장합니다.
  </Step>

  <Step title="인증 수단 정하기">
    비밀번호 또는 SSH 개인키 중 하나를 사용합니다. 보안상 **SSH 개인키 방식을 권장**합니다.
  </Step>
</Steps>

<Warning>
  SSH 개인키를 사용하는 경우 **패스프레이즈(암호)가 걸려 있지 않은 키**여야 합니다. 패스프레이즈가 있는 키는 연결되지 않으며, 원인이 표시되지 않고 인증 실패로만 보입니다.
</Warning>

## 2단계: OneSight에 연결

<Steps>
  <Step title="스토리지 선택">
    **데이터소스 → 추가 → 스토리지 → SFTP**를 선택합니다.
  </Step>

  <Step title="접속 정보 입력 후 연결">
    아래 항목을 입력하고 연결을 확인합니다.

    | 항목         | 설명                    |
    | ---------- | --------------------- |
    | 호스트        | 서버 주소                 |
    | 포트         | 기본 `22`               |
    | 사용자        | 1단계에서 만든 계정           |
    | 인증 방식      | 비밀번호 또는 SSH 개인키       |
    | 비밀번호 / 개인키 | 개인키는 파일 내용 전체를 붙여넣습니다 |

    입력한 비밀번호와 개인키는 등록 시 **AES-256-GCM 방식으로 암호화되어 저장**되며, 화면에 다시 표시되지 않습니다.
  </Step>

  <Step title="파일 선택">
    폴더를 눌러 이동하고, 사용할 파일을 선택합니다. SQLite(`.db`) 파일이라면 이어서 조회할 **테이블**을 고릅니다.
  </Step>

  <Step title="확인 후 등록">
    미리보기로 데이터를 확인하고, 자동으로 제안된 매핑을 검토한 뒤 이름을 지정해 등록합니다.
  </Step>
</Steps>

## 연결이 되지 않을 때

<Accordion title="사내망·VPN 안에 있는 서버입니다">
  서버는 **외부에서 접속할 수 있는 주소**여야 합니다. 사내망이나 VPN 안에서만 열리는 주소는 보안 정책에 따라 차단됩니다. 이 경우 담당자와 함께 외부 접속 경로를 마련해야 합니다.
</Accordion>

<Accordion title="방화벽에서 IP를 제한하고 있습니다">
  서버가 특정 IP만 허용하도록 설정되어 있다면, OneSight 서버의 주소를 허용 목록에 추가해야 합니다. 허용해야 할 IP는 [문의하기](/support/tickets)로 요청해 주세요.
</Accordion>

<Accordion title="개인키를 넣었는데 인증에 실패합니다">
  키에 패스프레이즈가 걸려 있는지 확인하세요. 패스프레이즈가 있는 키는 지원하지 않습니다. 또한 개인키는 앞뒤 머리글·꼬리글을 포함해 **파일 내용 전체**를 붙여넣어야 합니다.
</Accordion>

## 지원 파일 형식과 크기

| 형식                      | 크기 제한                     |
| ----------------------- | ------------------------- |
| CSV                     | 제한 없음 — 파일 앞부분 4MB까지 읽습니다 |
| Excel (`.xlsx`, `.xls`) | 32MB                      |
| JSON                    | 32MB                      |
| SQLite (`.db`)          | 256MB                     |

Excel·JSON·SQLite는 형식 특성상 파일 전체를 받아야 열 수 있어 크기 제한이 있습니다. 제한을 넘으면 등록 단계에서 안내 메시지가 표시됩니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="Amazon S3 연결" icon="database" href="/data-sources/s3">
    S3 및 S3 호환 스토리지를 연결합니다
  </Card>

  <Card title="문의하기" icon="message" href="/support/tickets">
    연결이 되지 않으면 문의해 주세요
  </Card>
</CardGroup>