Appearance

온프레미스 파일 스토리지 ​

IntelliDesk는 사내 S3 호환 스토리지에 문서, 이미지, 노트북 첨부파일과 테스트 스크린샷을 저장할 수 있습니다. AI 연결 설정과 파일 저장소 설정은 별개입니다. 이 문서는 서버 설치·운영 담당자를 위한 파일 스토리지 준비 절차입니다.

설정 범위 ​

스토리지 연결은 설치 환경 전체의 서버 환경변수로 관리합니다. 관리자 화면의 테넌트 환경 설정을 변경해도 이 연결에는 반영되지 않습니다. 같은 설치 환경의 모든 테넌트와 작업 워커가 같은 버킷을 사용하며, 기존 테넌트별 객체 키 경로를 유지합니다. 키 경로 구분 자체가 스토리지 차원의 접근 권한 분리를 제공하지는 않습니다.

테넌트마다 다른 저장소를 운영해야 하는 계약이나 물리적 분리 요구가 없다면 테넌트별 endpoint는 필요하지 않습니다. 현재 테넌트별 endpoint 전환은 지원하지 않습니다.

1. 사내 저장소 준비 ​

  1. 고객사에 S3 호환 스토리지가 있으면 해당 서비스의 endpoint, 리전, 버킷과 서비스 계정을 발급받습니다. 없다면 SeaweedFS 설치 안내 또는 Ceph Object Gateway 안내를 기준으로 사내에 구축합니다. 제품과 버전을 고정하고 해당 버전의 설치 절차를 따릅니다.
  2. 스토리지 데이터와 메타데이터를 영속 볼륨에 저장합니다. 컨테이너 재생성 후에도 보존되어야 합니다. 운영 환경은 용량, 복제 구성, 백업 주기와 복구 목표를 정하고 복원 시험을 수행합니다.
  3. IntelliDesk 전용 버킷을 미리 생성합니다. 앱은 버킷을 자동 생성하지 않습니다.
  4. 전용 계정에 해당 버킷의 객체 쓰기·읽기·삭제, 객체 메타데이터 조회, 멀티파트 업로드 및 중단 권한을 부여합니다. 현재 업로드는 객체 ACL도 전송하므로 private와 public-read ACL 및 필요한 ACL 설정 권한을 지원해야 합니다.
  5. 사내 DNS와 TLS 인증서를 준비하고 앱 서버 및 작업 워커에서 endpoint에 연결할 수 있도록 방화벽을 설정합니다. 사설 CA를 사용하면 Node.js 프로세스에 NODE_EXTRA_CA_CERTS로 CA 파일을 제공하며 인증서 검증을 끄지 않습니다.

공개 파일과 네트워크 범위

현재 에디터 이미지와 테스트 스크린샷 일부는 public-read로 업로드합니다. 특히 테스트 보고서는 저장소 직접 URL을 사용하므로 사용자 브라우저에서도 endpoint에 접근할 수 있어야 합니다. 공개 객체는 저장소에 접근 가능한 사용자가 URL로 읽을 수 있습니다. 버킷 전체를 공개하지 말고, 저장소의 네트워크 접근을 사내 범위로 제한하세요. ACL을 지원하지 않거나 공개 객체를 금지하는 환경은 endpoint 변경만으로 모든 기존 기능을 지원할 수 없습니다.

2. 서버 연결 설정 ​

운영 서버의 server/.env.production에 다음 값을 설정합니다. 개발 실행은 server/.env를 사용합니다. 실제 키는 배포 환경의 비밀정보 관리 방식으로 주입하고 저장소에 커밋하지 않습니다.

dotenv
AWS_S3_ENDPOINT=https://storage.company.internal:9443
AWS_S3_FORCE_PATH_STYLE=true
AWS_S3_BUCKET=intellidesk
AWS_S3_REGION=us-east-1
AWS_S3_ACCESS_KEY=발급받은-access-key
AWS_S3_SECRET_KEY=발급받은-secret-key
설정의미
AWS_S3_ENDPOINTS3 API의 기본 주소입니다. 관리 콘솔 주소나 버킷·객체 경로가 아닌 주소를 넣습니다. URL에 인증정보, 쿼리 또는 해시를 넣지 않습니다. 비우면 기존 AWS S3 연결을 사용합니다.
AWS_S3_FORCE_PATH_STYLEtrue이면 https://호스트/버킷/객체 방식입니다. 기본값은 false이며 https://버킷.호스트/객체 방식을 사용합니다. 소문자 true 또는 false를 사용합니다.
AWS_S3_BUCKET미리 생성한 버킷 이름입니다.
AWS_S3_REGION저장소에서 요구하는 서명 리전입니다. 예시의 us-east-1은 운영 제품의 설정에 맞게 변경합니다.
AWS_S3_ACCESS_KEY, AWS_S3_SECRET_KEY해당 사내 저장소에서 발급한 서비스 계정 자격증명입니다. AWS 계정 키일 필요는 없습니다.

사내 저장소는 보통 path style로 시작하면 버킷별 DNS와 인증서를 추가할 필요가 없습니다. false로 사용할 때에는 버킷을 붙인 호스트의 DNS와 TLS 인증서도 준비합니다. AWS SDK의 endpoint 설정 문서를 참고할 수 있습니다.

환경변수 변경 후 모든 앱 서버와 백그라운드 작업 워커를 재시작합니다. 연결 클라이언트와 버킷은 프로세스에서 캐시되므로 화면 새로고침만으로 반영되지 않습니다. 모든 인스턴스에 같은 설정을 적용합니다.

AWS S3로 되돌릴 때는 AWS_S3_ENDPOINT를 비우고 AWS_S3_FORCE_PATH_STYLE=false로 설정한 뒤 AWS 버킷·리전·자격증명을 복원하고 재시작합니다. 설정 전환은 파일을 자동으로 이동하지 않습니다.

3. 설치 후 검증 ​

실제 운영에 사용할 계정으로 다음 항목을 확인합니다.

  • 문서 에디터에 이미지를 업로드하고 저장한 뒤 다시 열어 표시되는지 확인합니다.
  • 노트북에 파일을 첨부하고 내용 추출과 조회·삭제를 확인합니다.
  • 회사 로고 업로드와 조회를 확인합니다.
  • 자동 테스트를 사용하는 환경은 스크린샷 업로드와 보고서에서의 이미지 표시를 확인합니다. 직접 URL이 AWS 주소가 아닌 사내 주소인지 확인합니다.
  • 한글·공백이 포함된 파일명도 확인합니다.
  • 다른 테넌트로 전환해 기존 파일 접근 권한이 유지되는지 확인합니다.
  • 스토리지 재시작 후 파일이 유지되는지, 백업으로 파일과 메타데이터를 복원할 수 있는지 확인합니다.

SignatureDoesNotMatch는 리전·키·서버 시간과 프록시의 호스트/경로 변경 여부를 확인합니다. AccessDenied는 버킷 및 객체 ACL 권한을, AccessControlListNotSupported는 제품의 ACL 지원 여부를 확인합니다. 서버에서 조회되지만 보고서 이미지가 보이지 않으면 사용자 PC의 DNS·방화벽·TLS와 공개 객체 정책을 확인합니다.

4. 기존 AWS 파일 이전 ​

  1. DB와 기존 버킷을 백업하고 업로드·삭제 및 관련 작업 워커를 일시 중지합니다.
  2. 기존 객체 키를 그대로 유지해 새 버킷에 복사합니다. Content-Type과 공개/비공개 접근 정책도 유지합니다.
  3. 객체 수·크기와 표본 파일 내용을 검증합니다. DB에 저장된 키를 임의로 변경하지 않습니다.
  4. 문서와 테스트 보고서 등에 저장된 AWS 직접 URL을 조사합니다. endpoint 설정은 이미 저장된 URL을 바꾸지 않으므로 해당 데이터의 URL 이전도 별도로 수행해야 합니다. 앱 프록시 URL은 객체 키를 유지하면 같은 경로를 사용할 수 있습니다.
  5. 연결 설정을 변경하고 서버·워커를 재시작한 뒤 위 검증 절차를 수행합니다. 검증 후 쓰기를 재개합니다.
  6. 이전 저장소는 검증 및 복구 기간 동안 보존합니다. 전환 후 새 파일이 생겼다면 이전 저장소로 되돌리기 전에 새 데이터도 동기화해야 합니다.

Intellidesk

Copyright © 2026