Skip to content

스크립트 개발 / 시스템 패치

8.0.11 버전에서 추가됨

시스템 패치는 DataFlux Func 버전별로 실행 파일을 교체하는 메커니즘입니다. 패치 파일과 구성을 현재 버전에 해당하는 디렉터리에 넣으면 Server, Worker, Beat가 각각 시작될 때 패치 파일을 지정된 위치로 복사합니다.

시스템 패치는 당분간 이미지를 교체할 수 없을 때 검증된 수정 파일을 적용하는 데 적합하며, 일반적인 코드 확장이나 리소스 배포 방식으로는 적합하지 않습니다. 시스템 의존성이나 Python 패키지를 설치해야 하는 경우 스크립트 개발 / 사전 실행 스크립트 등 해당 메커니즘을 사용하세요.

시스템 패치는 DataFlux Func의 실행 파일을 덮어씁니다

패치를 적용하기 전에 패치 출처, 적용 버전, 대상 경로를 확인하고 교체될 파일을 백업하세요. 잘못된 패치는 Server, Worker 또는 Beat가 정상적으로 실행되지 않게 할 수 있습니다.

1. 시스템 패치 준비

1.1 현재 버전 확인

'관리 / 정보'에서 현재 DataFlux Func 버전을 확인합니다. 시스템은 현재 버전 이름과 정확히 일치하는 패치 디렉터리만 읽으며, 다른 버전의 패치는 읽지 않습니다.

시스템 패치 디렉터리는 다음과 같습니다.

환경 위치
컨테이너 내 /data/resources/system-patches/{현재 버전}/
호스트 내 {설치 디렉터리}/data/resources/system-patches/{현재 버전}/

예를 들어, 현재 버전이 8.0.19인 경우 호스트 내 패치 디렉터리는 다음과 같습니다.

Text Only
1
{설치 디렉터리}/data/resources/system-patches/8.0.19/

1.2 패치 파일 준비

각 버전의 패치 디렉터리에는 patch.yaml이 포함되어야 합니다. 패치 파일은 현재 버전 디렉터리에 바로 나열할 수 있으며, 실제 대상 위치는 patch.yaml에서 올바르게 지정하기만 하면 됩니다. 예를 들어:

Text Only
1
2
3
4
5
system-patches/
└── 8.0.19/
    ├── patch.yaml
    ├── example.json
    └── example.py

여기서 patch.yaml의 files 구성은 '패치 파일 이름 → 대상 경로' 매핑입니다:

patch.yaml
1
2
3
files:
  example.py  : '@/worker/utils/example.py'
  example.json: /data/resources/example.json

구성의 경로 규칙은 다음과 같습니다.

  • files의 키는 현재 버전 패치 디렉터리 안의 파일 이름입니다. 파일은 현재 버전 디렉터리에 반드시 존재해야 합니다.
  • @/로 시작하는 대상 경로는 DataFlux Func 애플리케이션 루트 디렉터리를 기준으로 합니다. 예를 들어 @/worker/utils/example.py는 애플리케이션 디렉터리의 worker/utils/example.py를 의미합니다.
  • @/로 시작하지 않는 대상 경로는 절대 경로 사용을 권장합니다. 상대 경로는 실행 디렉터리가 다르면 모호해질 수 있기 때문입니다.
  • 대상 디렉터리가 없으면 자동으로 생성됩니다. 대상 파일이 이미 있으면 바로 덮어쓰며 자동 백업은 수행되지 않습니다.

동일한 files 구성은 Server, Worker, Beat에 각각 적용되며, 서비스별로 패치를 필터링하는 것은 지원되지 않습니다. 패치를 준비할 때 모든 대상 경로가 이러한 서비스의 실행 컨테이너에 적용 가능한지 확인해야 합니다.

1.3 패치 업로드

호스트에 접근 권한이 있는 경우 patch.yaml과 패치 파일을 현재 버전에 해당하는 호스트 디렉터리에 직접 넣을 수 있습니다.

'파일 관리'를 사용하여 업로드할 수도 있습니다:

  1. '관리 / 실험적 기능'에서 파일 관리자 모듈을 활성화합니다.
  2. '관리 / 파일 관리 / system-patches'로 이동합니다.
  3. '현재 버전(x.y.z)의 패치 디렉터리 생성'을 클릭하고 새로 생성된 버전 디렉터리로 이동합니다.
  4. patch.yaml과 패치 파일을 현재 버전 디렉터리에 직접 업로드하고, files의 파일 이름과 대상 경로가 올바른지 확인합니다.

2. 시스템 패치 적용 및 확인

2.1 DataFlux Func 재시작

준비가 완료되면 시스템 유지보수 / 업그레이드 및 재시작에 따라 DataFlux Func를 재시작하여 Server, Worker 및 Beat가 다시 생성되고 패치가 적용되도록 합니다.

각 서비스는 시작될 때 다음 처리를 순서대로 수행합니다.

  1. 현재 DataFlux Func 버전을 읽습니다.
  2. system-patches/{현재 버전}/patch.yaml을 찾습니다.
  3. files 구성에 따라 각 패치 파일을 복사합니다.
  4. 현재 호스트, 서비스, 버전, 적용 시간 및 각 파일의 적용 결과를 기록합니다.

현재 버전 디렉터리나 patch.yaml이 없으면 서비스는 시스템 패치를 건너뜁니다. patch.yaml이 유효한 YAML 매핑이 아니거나 유효한 files 매핑이 없으면 패치 처리가 오류를 보고하고 해당 서비스의 시작이 중단됩니다.

개별 패치 파일이 없거나 경로가 유효하지 않거나 복사에 실패하면 시스템은 해당 파일을 실패로 기록하고 다른 파일을 계속 처리한 후 서비스 시작을 계속합니다. 따라서 서비스가 성공적으로 시작되었다고 해서 모든 패치가 성공적으로 적용된 것은 아닙니다.

2.2 적용 결과 확인

'관리 / 정보 / 시스템 도구'로 이동하여 '시스템 패치 로그 보기'를 클릭합니다.

로그는 버전과 유사한 적용 시간을 기준으로 그룹화되며 다음 정보를 표시합니다.

  • 서비스 및 호스트 이름
  • DataFlux Func 버전
  • 적용 시간
  • 패치 총 개수, 성공 수 및 실패 수
  • 각 패치 파일, 대상 경로, 적용 결과 및 오류 정보

각 Server, Worker 및 Beat 노드에 해당 기록이 있고 모든 패치 파일이 성공으로 표시되는지 확인해야 합니다. 컨테이너 로그에도 [SYSTEM PATCH]로 시작하는 각 파일의 적용 결과가 출력됩니다.

3. 시스템 패치 업데이트 또는 제거

시스템은 서비스가 시작될 때마다 현재 버전의 패치를 다시 적용합니다. 따라서 패치 파일이나 patch.yaml을 수정한 후에는 DataFlux Func를 재시작해야 변경 사항이 적용됩니다.

패치 구성을 삭제해도 현재 실행 중인 컨테이너에서 이미 덮어쓴 파일이 즉시 복원되지는 않습니다. @/ 대상 경로의 경우 해당 구성을 삭제하고 관련 서비스를 다시 생성하여 원래 이미지 파일에서 시작하도록 해야 합니다. 지속형 디렉터리 안의 절대 대상 경로의 경우에는 작업 전 백업을 사용하여 파일을 복원해야 합니다.

DataFlux Func를 업그레이드한 후에는 이전 버전 디렉터리의 패치가 새 버전에 적용되지 않습니다. 새 버전 코드를 기준으로 패치가 여전히 필요한지, 호환되는지 다시 확인하고, 새 버전에 적용 가능한 패치를 확보한 경우에만 새 버전 디렉터리를 생성하세요. 이전 버전 패치를 새 버전 디렉터리에 직접 복사하지 마세요.