(storing_and_serving)=

# 저장 및 서빙

Wagtail은 [Django의 업로드된 파일 관리 규칙](inv:django#topics/files)을 따릅니다. `FileSystemStorage` 설정 및 사용자가 업로드한 파일 처리에 대한 자세한 내용은 [](user_uploaded_files)를 참조하세요.

## 파일 저장 위치

Wagtail은 [`STORAGES["default"]`](inv:django#STORAGES) 설정을 사용하여 사용자가 업로드한 파일의 저장 위치와 방법을 결정합니다. 기본적으로 Wagtail은 로컬 파일 시스템에 파일을 저장합니다.

## 문서 서빙

문서 서빙은 [WAGTAILDOCS_SERVE_METHOD](wagtaildocs_serve_method) 메서드로 제어됩니다. 이 설정은 문서 요청을 정상적으로 처리할 때 발생하는 권한 확인의 엄격함 일부를 성능과 맞바꾸는 여러 서빙 메서드를 제공합니다.

제공되는 서빙 메서드는 `direct`, `redirect`, `serve_view` 이며, `WAGTAILDOCS_SERVE_METHOD` 가 지정되지 않았거나 `None` 으로 설정된 경우 `redirect` 메서드가 기본값입니다. 예를 들면 다음과 같습니다:

```python
WAGTAILDOCS_SERVE_METHOD = "redirect"
```

(documents_security_considerations)=

### 보안 고려 사항

```{warning}
사용자가 업로드한 파일을 허용하는 모든 시스템은 잠재적인 보안 위험을 가집니다.
```

`FileSystemStorage` 를 사용할 때, 문서는 사이트의 `MEDIA_ROOT` 내 `documents` 하위 디렉터리에 저장됩니다. 이 경우 `WAGTAILDOCS_SERVE_METHOD` 는 기본적으로 `serve_view` 로 설정되며, Wagtail은 개인정보 보호 검사를 시행하는 Django 뷰를 통해 문서를 서빙합니다.

`serve_view` 메서드를 사용할 때:

-   웹 서버 설정에서 `MEDIA_ROOT` 의 `documents` 하위 디렉터리에 대한 직접 접근을 차단해야 합니다. 이를 통해 사용자가 직접 URL로 문서에 접근하여 [컬렉션 개인정보 보호 설정](https://guide.wagtail.org/en-latest/how-to-guides/manage-collections/#privacy-settings)을 우회하는 것을 방지할 수 있습니다.
-   문서는 브라우저에 표시되는 대신 다운로드로 제공됩니다([](wagtaildocs_inline_content_types)를 통해 명시적으로 지정하지 않는 한). 이는 문서가 스크립트(예: HTML 또는 SVG)를 포함할 수 있는 유형인 경우 브라우저가 이를 실행하는 것을 방지합니다.
-   그러나 문서는 Django 애플리케이션 서버를 통해 제공되므로 웹 서버에서 직접 문서를 제공하는 것보다 더 많은 서버 리소스를 소비할 수 있습니다.

대안적인 서빙 메서드인 `'direct'` 와 `'redirect'` 는 `MEDIA_ROOT` 에서 직접 문서를 서빙하는 방식으로 작동합니다. 이는 `documents` 하위 디렉터리에 대한 직접 접근을 차단할 수 없음을 의미하며, 따라서 사용자는 직접 URL에 접근하여 권한 확인을 우회할 수 있습니다. 또한, Wagtail 관리자에 접근할 수 있는 사용자를 완전히 신뢰할 수 없는 경우, 문서 내 스크립트 실행을 방지하기 위해 추가적인 조치를 취해야 합니다:

-   [](wagtaildocs_extensions) 설정을 사용하여 업로드된 문서를 안전한 유형의 "허용 목록"으로 제한할 수 있습니다.
-   웹 서버를 설정하여 `documents` 하위 디렉터리 내 파일에 대해 `Content-Security-Policy: default-src 'none'` 헤더를 반환하도록 할 수 있습니다. 이는 해당 파일 내의 스크립트 실행을 방지합니다.
-   웹 서버를 설정하여 `documents` 하위 디렉터리 내 파일에 대해 `Content-Disposition: attachment` 헤더를 반환하도록 할 수 있습니다. 이는 브라우저가 파일을 인라인으로 표시하는 대신 다운로드하도록 강제합니다.

원격("클라우드") 스토리지 백엔드를 사용하는 경우, 서빙 메서드는 기본적으로 `'redirect'` 로 설정되며 문서는 클라우드 스토리지 파일 URL에서 직접 제공됩니다. 이 경우('direct'와 마찬가지로) Wagtail은 파일이 제공되는 방식에 대한 제어력이 적으며, 사용자는 권한 확인을 우회할 수 있고 문서 내의 스크립트가 실행될 수 있습니다(클라우드 스토리지 서비스의 설정에 따라 다름). 그러나 교차 사이트 스크립팅 공격은 여전히 가능하지만, 문서는 일반적으로 메인 사이트와 다른 도메인에서 제공되므로 그 영향은 줄어듭니다.

이러한 제한 사항을 수용할 수 없는 경우, `WAGTAILDOCS_SERVE_METHOD` 를 `serve_view` 로 설정하고 클라우드 서비스의 파일 URL을 사용하여 문서에 공개적으로 접근할 수 없도록 해야 합니다.

특정 응답에 대해 헤더를 설정하는 데 필요한 단계는 Wagtail 애플리케이션이 배포된 방식과 사용되는 스토리지 백엔드에 따라 달라집니다. `serve_view` 메서드의 경우, 문서에 포함된 스크립트 실행을 방지하기 위해 `Content-Security-Policy` 헤더가 자동으로 설정됩니다([](wagtaildocs_block_embedded_content)를 통해 비활성화하지 않는 한).

## 콘텐츠 유형

Wagtail은 [WAGTAILDOCS_CONTENT_TYPES](wagtaildocs_content_types) 설정을 제공하여 업로드할 수 있는 문서 콘텐츠 유형을 지정할 수 있습니다. 예를 들면 다음과 같습니다:

```python
WAGTAILDOCS_CONTENT_TYPES = {
    'pdf': 'application/pdf',
    'txt': 'text/plain',
}
```

## 인라인 콘텐츠 유형

[WAGTAILDOCS_INLINE_CONTENT_TYPES](wagtaildocs_inline_content_types)를 사용하여 인라인 콘텐츠 유형을 지정할 수 있으며, 이는 리치 텍스트 편집기 내에 표시됩니다.

예를 들면 다음과 같습니다:

```python
WAGTAILDOCS_INLINE_CONTENT_TYPES = ['application/pdf', 'text/plain']
```

## 파일 확장자

Wagtail은 [WAGTAILDOCS_EXTENSIONS](wagtaildocs_extensions) 설정을 사용하여 문서 업로드에 허용되는 파일 확장자를 지정할 수 있습니다.

또한 Django의 {class}`~django.core.validators.FileExtensionValidator` 를 사용하여 확장자를 검증합니다. 예를 들면 다음과 같습니다:

```python
WAGTAILDOCS_EXTENSIONS = ['pdf', 'docx']
```

## 문서 비밀번호 필요 템플릿

Wagtail은 보호된 문서에 접근하기 위해 비밀번호가 필요한 경우 사용할 사용자 지정 템플릿을 위해 `WAGTAILDOCS_PASSWORD_REQUIRED_TEMPLATE` 설정을 제공합니다. [](private_pages)에서 자세한 내용을 읽어보세요.

다음은 예시입니다:

```python
WAGTAILDOCS_PASSWORD_REQUIRED_TEMPLATE = 'myapp/document_password_required.html'
```