문서 첨부 파일
모든 문서 페이지에 이미지와 파일을 직접 첨부할 수 있습니다. 스크린샷을 에디터에 끌어다 놓으면 본문에 인라인으로 삽입되고, PDF, 사양서, 압축 파일을 첨부하면 다운로드할 수 있는 카드로 표시됩니다. 파일은 오브젝트 스토리지에 저장되므로 데이터베이스가 비대해지지 않으며, 페이지를 어디서 보거나 공유하든 항상 함께 따라갑니다.
첨부 파일 추가
에디터에서 문서 페이지를 열고(새 문서 또는 편집) 가장 편한 방법으로 파일을 추가합니다:
- 하나 이상의 파일을 에디터에 드래그 앤 드롭
- 클립보드의 이미지를 바로 붙여넣기 (예: 스크린샷)
- 에디터 툴바에서 파일 첨부를 클릭하고 파일 선택
여러 파일을 한 번에 첨부할 수 있습니다. 새 문서는 처음 파일을 첨부할 때 자동으로 저장되므로 업로드한 파일을 잃어버릴 일이 없습니다.
이미지와 파일
Archyl은 두 경우를 예상하는 방식대로 처리합니다:
- 이미지는 추가한 위치에 Markdown으로 인라인 삽입되어 페이지에 바로 렌더링됩니다.
- 기타 파일(PDF, 문서, 압축 파일 등)은 텍스트에 삽입되지 않고 첨부 파일 패널에 다운로드할 수 있는 카드로 추가됩니다.
첨부 파일 보기
페이지를 읽을 때 첨부 파일은 제목 바로 아래, 문서 상단의 첨부 파일 패널에 표시되므로 독자는 스크롤하기 전에 어떤 파일이 있는지 알 수 있습니다. 각 파일에는 다음이 표시됩니다:
- 색상으로 구분된 유형 아이콘 또는 이미지 썸네일
- 파일 이름, 유형, 크기
- 클릭 한 번으로 실행되는 다운로드
이미지는 콘텐츠에서 배치한 위치에도 인라인으로 렌더링됩니다.
첨부 파일 관리
에디터의 첨부 파일 패널에서 다음 작업을 할 수 있습니다:
- 모든 파일 다운로드
- 파일 삭제 (인라인에서 간단히 확인) — 스토리지에서도 함께 삭제됩니다
문서를 삭제하면 첨부 파일도 함께 삭제됩니다.
지원 파일
모든 파일 유형을 첨부할 수 있습니다. 이미지는 인라인으로 삽입되고, 그 밖의 파일은 다운로드할 수 있는 카드로 표시됩니다. 일반적인 예:
- 이미지 — PNG, JPEG, GIF, WebP, SVG, AVIF
- 문서 — PDF, Word, Excel, PowerPoint, 일반 텍스트, Markdown, CSV
- 데이터 및 압축 파일 — JSON, YAML, ZIP, 로그
기본 최대 크기는 파일당 10 MB입니다 (셀프 호스팅 인스턴스에서 변경 가능).
팁: 브라우저가 인식하지 못하는 파일 유형도 허용되며, 다운로드 파일로 제공됩니다.
스토리지 및 개인정보 보호
첨부 파일은 애플리케이션 데이터베이스가 아닌 오브젝트 스토리지에 저장됩니다. Archyl Cloud에서는 이 스토리지가 Google Cloud Storage이며, Archyl이 관리하므로 따로 구성할 것이 없습니다. 셀프 호스팅 인스턴스에서는 원하는 S3 호환 제공자를 직접 선택합니다 (아래 참조).
어느 경우든:
- 버킷은 비공개입니다. 파일은 요청 시 생성되는 수명이 짧은 서명된 링크로 제공되며, 기반 객체는 절대 공개적으로 나열되지 않습니다.
- 페이지에 삽입된 링크는 바뀌지 않으므로, 공유 문서와 공개 문서는 버킷을 노출하지 않고도 계속 작동합니다.
- 저장 데이터 암호화가 기본으로 켜져 있습니다. Google Cloud Storage는 모든 객체를 자동으로 암호화하며, 셀프 호스팅 인스턴스에서는 자체 키를 제공할 수도 있습니다 (예: GCS의 Cloud KMS CMEK).
셀프 호스팅 인스턴스
Archyl Cloud에서는 첨부 파일이 별도 설정 없이 바로 작동합니다. 셀프 호스팅하는 경우에는 오브젝트 스토리지를 직접 준비해야 하며, S3 호환 제공자(Google Cloud Storage, Amazon S3, MinIO, Cloudflare R2 등)라면 어디든 Archyl에 연결할 수 있습니다.
스토리지를 구성하기 전까지는 파일 첨부 작업을 사용할 수 없으며, 업로드하면 *"File storage is not configured"*라는 명확한 메시지가 반환됩니다. 기능을 활성화하려면 백엔드에 STORAGE_* 환경 변수(엔드포인트, 버킷, 액세스 키, 시크릿 키)를 설정하세요. Google Cloud Storage의 경우 상호 운용성(HMAC) 엔드포인트를 사용합니다. 전체 옵션 목록은 배포 구성을 참조하세요.