홈문서API 참조
Documentation
Start typing to search…

Backup and Restore Guide

특히 프로덕션 환경에서 Sandfly를 사용하는 경우, 데이터와 구성 요소가 손실되지 않도록 대비하는 것이 중요합니다. 결과 데이터는 비교적 빠르게 생성·소멸하지만, 사용자 정의 sandfly, 스케줄, 구성된 호스트, 계정, 자격 증명 등과 같은 기타 애플리케이션 데이터는 정기적인 백업을 통해 반드시 보존해야 하는 대체 불가능한 데이터입니다.

이 가이드에서는 데이터베이스 지식 없이도 파일 시스템 수준에서 Sandfly 노드와 서버를 안전하게 백업하고 복원하는 방법을 설명합니다. 숙련된 데이터베이스 관리자는 이 문서의 정보를 활용해 더 고급 백업·복원 방법을 사용할 수 있지만, 해당 세부 절차는 이 일반 사용자용 가이드의 범위를 벗어납니다.

디렉터리 구조 개요

Sandfly 시스템은 본질적으로 두 가지 영역/디렉터리 구조로 구성됩니다:

  • Sandfly Application

    • 루트 디렉터리는 "sandfly-setup"이며, 애플리케이션에 필요한 스크립트와 구성 텍스트 파일이 주로 포함되어 있습니다.
    • 설치를 위한 기본 또는 필수 경로는 없습니다.
      • 환경에서 정의된 위치는 최초 설치자 또는 재설치를 수행할 시스템 관리자와 상의하세요.
      • 또는 다음 명령으로 위치를 확인할 수 있습니다:
        • find / -name sandfly-setup
      • 아래에 언급된 디렉터리를 제외하면 Sandfly 루트 내 다른 파일들은 다운로드한 패키지에서 그대로 제공되므로 별도로 백업할 필요가 없습니다.
    • 중요 디렉터리:
      • <SANDFLY_ROOT_DIR>/sandfly-setup/setup/setup_data/
        • 이 디렉터리와 하위 폴더에는 설치 환경에 고유한 파일 시스템 수준의 구성 텍스트 파일이 모두 포함되어 있습니다.
        • 이 재귀 경로의 전체 크기는 1M 미만이어야 합니다.
        • 이 디렉터리의 파일은 언제든지 안전하게 백업할 수 있으며 Sandfly 애플리케이션을 중지할 필요가 없습니다.

  • Docker Service

    • Docker 서비스 내에 포함된 Sandfly 관련 파일.
    • 기본 Docker 루트 경로:/var/lib/docker/
      • 이 경로는 환경에 따라 다를 수 있습니다.
      • Docker의 루트 경로는 다음 명령으로 확인할 수 있습니다:
        • docker info --format='{{.DockerRootDir}}'
    • 중요 디렉터리:
      • <DOCKER_ROOT_DIR>/volumes/sandfly-pg14-db-vol
        • 일반적으로 "volumes" 디렉터리는 Docker 컨테이너에서 사용하는 영구 데이터를 포함합니다.
        • 구체적으로 "sandfly-pg14-db-vol" 디렉터리에는 Sandfly가 직접 사용하는 전체 Postgres 데이터베이스가 포함됩니다.
          • 데이터베이스 폴더의 전체 경로는 다음 명령으로 체계적으로 확인할 수 있습니다: 
            docker inspect sandfly-pg14-db-vol --format='{{.Mountpoint}}'
        • volumes 하위의 다른 디렉터리는 자동으로 (재)생성되므로 백업할 필요가 없습니다.
        • 데이터베이스 파일의 "사람이 읽기 쉬운" 크기는 다음 명령으로 확인할 수 있습니다: 
          du -h --total `docker inspect sandfly-pg14-db-vol --format='{{.Mountpoint}}'` | tail -1
        • A database backup at the volumes level requires that the Sandfly application is first stopped, otherwise data corruption can occur from unfinished transactions.
      • <DOCKER_ROOT_DIR>/containers/
        • 일반적으로 "containers" 디렉터리는 활성 Docker 컨테이너의 파일을 보관합니다.
        • 이 기본 경로 아래의 로그 파일은 비즈니스 또는 기술적 이유로 필요하다면 백업할 수 있습니다. 다만 애플리케이션 운영에는 필수가 아니며, 해당 파일들은 영구 데이터가 아닙니다.
          • 사용 가능한 모든 컨테이너 로그 파일의 전체 경로 목록은 다음 명령으로 체계적으로 생성할 수 있습니다: 
            ls -1 `docker info --format='{{.DockerRootDir}}'`/containers/*/*-json.log*
        • 선택적 Docker 로그 파일의 "사람이 읽기 쉬운" 크기는 다음 명령으로 확인할 수 있습니다: 
          du -h --total `docker info --format='{{.DockerRootDir}}'`/containers/*/*-json.log* | tail -1
        • 이러한 로그 파일은 언제든지 안전하게 백업할 수 있으며 Sandfly 애플리케이션을 중지할 필요가 없습니다. 다만 일부 로그의 활동량이 많을 수 있어, 서버가 실행 중인 상태에서는 잘린 로그가 발생할 수 있습니다.

백업

백업 세부 내용은 아래에서 서버와 노드 섹션으로 구분하여 설명합니다.

Sandfly 서버

일반적인 서버 설치의 경우 server_ssl_cert 디렉터리 내에서 커스텀 SSL 인증서를 사용하는 상황을 제외하면 구성 텍스트 파일은 거의 변경되지 않습니다. 반면 데이터베이스에는 환경의 크기와 범위에 따라 정기적으로 변경되는 데이터가 포함됩니다.

파일 시스템 접근 방식 개요

이 백업 방식의 목표는 백업 시점 서버의 파일 시스템에 존재하는 모든 Sandfly 구성 텍스트 파일, 전체 데이터베이스(Docker 볼륨 수준), 그리고 선택적으로 Docker 컨테이너 로그 파일을 그대로 복사하는 것입니다. Sandfly 결과가 많다면 백업 크기는 매우 커질 수 있습니다.

이 방식을 사용할 때는 과정 중에 Sandfly 애플리케이션을 중지해야 합니다. 이는 데이터 손상을 방지하기 위해 데이터베이스를 비활성 상태로 두기 위함입니다.

서비스 중단 없이 Sandfly 데이터베이스를 백업해야 하는 경우, 지원되는 Postgres SQL 덤프 방식을 통해 가능합니다. 다만 해당 고급 절차는 이 일반 사용자용 가이드의 범위를 벗어납니다.

파일 시스템 단계

다음 단계들을 Sandfly 서버에서 수행하세요:

  1. 사용자 인터페이스(UI)에서 모든 Active 스케줄을 비활성화합니다.
    1. 바로가기: Deactivating and Deleting Schedule
    2. 경고: 이 단계는 매우 중요합니다. 활성 상태로 남아 있는 스케줄은 그대로 백업됩니다. 따라서 데이터베이스 복원 후 서버가 정상 운영으로 복귀하면 해당 스케줄이 즉시 실행됩니다.
  2. 모든 Task Queue가 비어질 때까지 기다립니다.
    1. Sandfly UI에서 상단 바의 버튼 또는 사이드바 Scanning > Task Queues로 Task Queues 페이지를 열고 다음 사항을 모두 확인합니다:
      1. Total Tasks와 Tasks 지표가 0(zero)으로 표시되어 Task Queue가 비어 있는지 확인합니다.
      2. 진행 중인 Trickle 스케줄이 없어야 합니다. "Queues" 아래에 "Trickle Schedule Progress" 위젯이 보이면 하나 이상이 활성 상태라는 의미입니다. 이 경우 먼저 1단계가 완료되었는지 재확인한 뒤, Trickle 스케줄은 수동으로도 시작될 수 있으므로 남아 있는 Trickle 스케줄을 빨간색 "X" 버튼으로 수동 취소하세요.
    2. 스캔 도중에 노드를 중지하면 원격 호스트에 고아 파일이 남을 수 있으므로 중지하지 않는 것이 중요합니다. 노드가 활성 작업을 마칠 시간을 주면 모든 것이 정상적으로 정리됩니다.
  3. 서버 호스트에서 Sandfly 컨테이너를 안전하게 종료합니다.
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/start_scripts/shutdown_sandfly.sh
  4. 선택한 백업 시스템으로 아래 항목을 복사했는지 확인합니다(디렉터리인 경우 재귀적으로):
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/setup/setup_data/
    2. <DOCKER_ROOT_DIR>/volumes/sandfly-pg14-db-vol/
    3. <DOCKER_ROOT_DIR>/containers/*/*-json.log* (Optional)
  5. Sandfly 서버를 시작합니다.
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/start_scripts/start_sandfly.sh
  6. 다음 명령으로 sandfly-server 및 sandfly-postgres 컨테이너가 실행 중인지 확인합니다:
    1. docker ps
  7. 1단계에서 비활성화한 모든 스케줄을 활성화합니다.

Sandfly 노드

The goal of this backup is to make a copy of all of the Sandfly configuration text files, and optionally the log files of the Docker container(s), as they exist on the file system of a node at the moment of the backup action.

For a typical node installation the configuration text files should rarely change, if at all. This file system level backup can be performed at any time and does not require the Sandfly application to be stopped.

File System Level Steps

다음 단계들을 각 Sandfly 노드에서 수행하세요:

  1. 선택한 백업 시스템으로 아래 항목을 복사했는지 확인합니다(디렉터리인 경우 재귀적으로):
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/setup/setup_data/
    2. <DOCKER_ROOT_DIR>/containers/*/*-json.log* (Optional)

복원

복원 세부 내용은 아래에서 서버와 노드 섹션으로 구분하여 설명합니다.

Sandfly 서버

상황에 따라 데이터를 전체 또는 부분적으로 복구할 수 있습니다. 각 상황에 따라 복원 과정에서 선택할 수 있는 옵션이 달라질 수 있습니다.

파일 시스템 접근 방식 개요

이 복원 방식의 목표는 파일 시스템 수준에서만 서버 파일을 재구성하는 것입니다. 즉, 데이터베이스 테이블 수준이 아닌 Docker 볼륨 폴더 내 데이터베이스 디렉터리 전체를 교체해야 합니다. 또한 과정 중에는 Sandfly 애플리케이션을 중지해야 합니다.

Sandfly 데이터베이스의 SQL 수준 또는 부분 복원이 필요하다면, 지원되는 Sandfly 및 Postgres 방법을 조합해 수행할 수 있습니다. 다만 해당 절차는 본 가이드에서 다루지 않습니다.

복구 상황에 따라 전체 파일 집합(서버 전체 재구성이 필요한 경우 등) 또는 선택적 비-데이터베이스 파일(텍스트 파일의 실수 삭제나 손상 등) 복원을 고려하고 허용합니다. 다시 강조하지만 데이터베이스 볼륨 내 파일은 부분적으로 복원하지 마십시오. 마지막으로 Docker 컨테이너 로그는 원래 위치로 복원해서는 안 됩니다.

파일 시스템 단계

다음 단계들을 Sandfly 서버에서 수행하세요:

  1. If the Sandfly server is NOT running, skip to Step 4.
  2. 사용자 인터페이스(UI)에서 모든 Active 스케줄을 비활성화합니다.
    1. 바로가기: Deactivating and Deleting Schedule
  3. 모든 Task Queue가 비어질 때까지 기다립니다.
    1. Sandfly UI에서 상단 바의 버튼 또는 사이드바 Scanning > Task Queues로 Task Queues 페이지를 열고 다음 사항을 모두 확인합니다:
      1. Total Tasks와 Tasks 지표가 0(zero)으로 표시되어 Task Queue가 비어 있는지 확인합니다.
      2. 진행 중인 Trickle 스케줄이 없어야 합니다. "Queues" 아래에 "Trickle Schedule Progress" 위젯이 보이면 하나 이상이 활성 상태라는 의미입니다. 이 경우 먼저 2단계가 완료되었는지 재확인한 뒤, Trickle 스케줄은 수동으로도 시작될 수 있으므로 남아 있는 Trickle 스케줄을 빨간색 "X" 버튼으로 수동 취소하세요.
    2. 스캔 도중에 노드를 중지하면 원격 호스트에 고아 파일이 남을 수 있으므로 중지하지 않는 것이 중요합니다. 노드가 활성 작업을 마칠 시간을 주면 모든 것이 정상적으로 정리됩니다.
  4. 서버 호스트에서 Sandfly 컨테이너를 안전하게 종료합니다.
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/start_scripts/shutdown_sandfly.sh
      1. "No such container" 오류는 무시해도 안전합니다.
  5. 백업 시스템에서 파일을 복사합니다.
    1. 참고: <DOCKER_ROOT_DIR> 하위의 기본 디렉터리가 누락되었거나 손상된 경우, 백업 파일 복원을 시도하기 전에 docker 서비스를 재시작하면 해당 디렉터리가 다시 생성됩니다.
    2. "setup_data" 디렉터리 내 특정 텍스트 파일만 복원하는 경우, 아래 디렉터리부터 해당 파일들을 복사하세요:
      1. <SANDFLY_ROOT_DIR>/sandfly-setup/setup/setup_data/
    3. 서버 전체 백업을 복원하는 경우, 아래 두 디렉터리의 모든 파일이 재귀적으로 복사되었는지 확인하세요:
      1. <SANDFLY_ROOT_DIR>/sandfly-setup/setup/setup_data/
      2. <DOCKER_ROOT_DIR>/volumes/sandfly-pg14-db-vol/
        1. 컨테이너 로그 파일이 저장되는 "containers" 경로는 절대 원래 위치로 복원하지 마세요. 로그 파일을 복원해야 하는 경우에는 별도의 위치로 복원하세요.
  6. Sandfly 서버 시작
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/start_scripts/start_sandfly.sh
  7. 다음 명령으로 sandfly-server 및 sandfly-postgres 컨테이너가 실행 중인지 확인합니다:
    1. docker ps
  8. 일부 또는 모든 노드를 복원해야 하는 경우, 다음 단계로 진행하기 전에 노드 복원 절차를 모두 완료합니다.
  9. (해당되는 경우) 2단계에서 비활성화한 모든 스케줄을 다시 활성화합니다.
    1. 참고: 활성화해야 할 스케줄이 많고, 특히 동일한 주기로 실행되거나 동일한 호스트 집합을 공유하는 경우, 일정 기간에 걸쳐 분산하여 스케줄을 순차적으로 활성화하는 것을 고려하세요.

Sandfly 노드

복구 상황에 따라 이 절차는 전체 파일 집합(노드 재구성에 필요할 수 있음) 또는 선택적 파일(실수로 인한 파일 삭제나 손상 등)의 복원을 고려하고 허용합니다.

"config.node.json" 파일은 노드의 실행 구성에 직접 영향을 주므로 해당 호스트의 모든 컨테이너를 중지해야 합니다. 노드가 하나뿐이라면 서비스로 복귀할 때까지 Sandfly 스캔 기능을 사용할 수 없습니다. 그러나 동일한 Queue를 담당하는 추가 노드가 동작 중이고 서버가 정상인 경우 스캔은 계속될 수 있습니다. 마지막으로, 아래 절차는 서버가 비활성 상태가 아닌 한 한 번에 하나의 노드만 복원한다고 가정합니다.

마지막으로 Docker 컨테이너 로그는 절대 원래 위치로 복원하지 마십시오.

파일 시스템 단계

필요에 따라 각 Sandfly 노드에서 다음 단계를 수행하세요:

  1. 어떠한 이유로든 Sandfly 서버가 중지되어 있거나, 동일한 Queue에 대해 동작 중인 노드가 둘 이상인 경우 4단계로 건너뜁니다.
  2. 사용자 인터페이스(UI)에서 모든 Active 스케줄을 비활성화합니다.
    1. 바로가기: Deactivating and Deleting Schedule
  3. 모든 Task Queue가 비어질 때까지 기다립니다.
    1. Sandfly UI에서 상단 바의 버튼 또는 사이드바 Scanning > Task Queues로 Task Queues 페이지를 열고 다음 사항을 모두 확인합니다:
      1. Total Tasks와 Tasks 지표가 0(zero)으로 표시되어 Task Queue가 비어 있는지 확인합니다.
      2. 진행 중인 Trickle 스케줄이 없어야 합니다. "Queues" 아래에 "Trickle Schedule Progress" 위젯이 보이면 하나 이상이 활성 상태라는 의미입니다. 이 경우 먼저 2단계가 완료되었는지 재확인한 뒤, Trickle 스케줄은 수동으로도 시작될 수 있으므로 남아 있는 Trickle 스케줄을 빨간색 "X" 버튼으로 수동 취소하세요.
    2. 스캔 도중에 노드를 중지하면 원격 호스트에 고아 파일이 남을 수 있으므로 중지하지 않는 것이 중요합니다. 노드가 활성 작업을 마칠 시간을 주면 모든 것이 정상적으로 정리됩니다.
  4. 노드 호스트에서 모든 Sandfly 컨테이너를 중지합니다.
    1. docker stop $(docker ps -a -q)
  5. 백업 시스템에서 대상 복원을 위해 특정 파일을 선택하거나(선택적 복원), 전체/재귀 복원을 위해 아래 디렉터리를 선택하여 해당 파일을 노드의 다음 위치로 복사합니다:
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/setup/setup_data/
  6. Sandfly 노드를 시작합니다.
    1. <SANDFLY_ROOT_DIR>/sandfly-setup/start_scripts/start_node.sh
      1. 이 호스트에서 실행될 예정인 각 노드 인스턴스에 대해 6단계를 반복합니다.
  7. 예상된 개수의 sandfly-node 컨테이너가 실행 중인지 확인합니다.
    1. docker ps
  8. Sandfly 노드로 동작하는 각 호스트에 대해 4–6단계를 반복합니다.
  9. (해당되는 경우) 2단계에서 비활성화한 모든 스케줄을 활성화합니다.

이로써 파일 시스템 방식의 백업 및 복원 가이드를 마칩니다. SQL 기반 백업이나 VM 스냅샷 등 다른 백업 방법도 가능합니다. 중요한 점은, 불완전한 트랜잭션으로 인해 오류가 발생하지 않도록 Sandfly가 백업 가능한 적절한 상태에 있도록 하는 것입니다.

Updated 7 days ago

이 페이지가 도움이 되었나요?