file_server 지시문

원문 보기 위키 갱신 2026.10.03

file_server 지시문 (정적 파일 서버)

file_server 지시문은 실제 및 가상 파일 시스템을 지원하는 정적 파일 서버예요. 요청의 URI 경로를 사이트 루트 경로에 붙여 파일 경로를 만든다.

출처: Caddy 공식 문서

본문

실제 및 가상 파일 시스템을 지원하는 정적 파일 서버예요. 요청의 URI 경로를 사이트 루트 경로에 붙여 파일 경로를 만들어요.

기본적으로 정규 URI(canonical URI)를 강제해요. 즉 뒤에 슬래시가 없는 디렉터리 요청(슬래시를 추가하기 위해)이나 뒤에 슬래시가 있는 파일 요청(슬래시를 제거하기 위해)에 대해 HTTP 리다이렉트를 발행해요. 다만 내부 재작성이 경로의 마지막 요소(파일 이름)를 수정하면 리다이렉트를 발행하지 않아요.

대부분 file_server 지시문은 전체 사이트의 파일 루트를 설정하기 위해 root 지시문과 함께 쓰여요. 이 지시문에는 이 핸들러에만 루트를 설정하는 root 하위 지시문도 있어요(권장하지 않음). 사이트 루트는 샌드박스 보장을 하지 않는다는 점에 주의해요. 파일 서버는 경로 구성 요소로부터 디렉터리 트래버설을 막지만, 루트 안의 심볼릭 링크는 여전히 루트 밖 접근을 허용할 수 있어요.

에러가 발생하면(예: 파일 없음 404, 권한 거부 403) 에러 라우트가 호출돼요. handle_errors 지시문으로 에러 라우트를 정의하고 커스텀 에러 페이지를 표시해요.

browse를 사용할 때 기본 출력은 HTML 템플릿으로 생성돼요. 클라이언트는 각각 Accept: application/json 또는 Accept: text/plain 헤더를 사용해 디렉터리 목록을 JSON이나 평문으로 요청할 수 있어요. JSON 출력은 스크립팅에, 평문 출력은 터미널 사용에 유용해요.

문법 (Syntax)

file_server [<matcher>] [browse] {
	fs            <backend...>
	root          <path>
	hide          <files...>
	index         <filenames...>
	browse        [<template_file>] {
		reveal_symlinks
		sort <sort_field> [<direction>]
		file_limit <number>
	}
	precompressed [<formats...>]
	status        <status>
	disable_canonical_uris
	pass_thru
}

fs는 사용할 대체(아마도 가상) 파일 시스템을 지정해요. caddy.fs 네임스페이스의 모든 Caddy 모듈을 사용할 수 있어요. 모든 루트 경로/접두사는 대체 파일 시스템 모듈에도 여전히 적용돼요. 기본적으로 로컬 디스크를 사용해요.

xcaddy v0.4.0은 --embed 플래그를 도입해 파일 시스템 트리를 커스텀 Caddy 빌드에 임베드하고, embedded라는 fs 모듈을 등록해서 정적 사이트를 Caddy 실행 파일로 배포할 수 있게 해줘요.
root는 사이트 루트의 경로를 설정해요. root 지시문과 비슷하지만 이 파일 서버 인스턴스에만 적용되고, 정의된 다른 사이트 루트를 덮어써요. 기본값: {http.vars.root} 또는 현재 작업 디렉터리. 참고: 이 하위 지시문은 이 핸들러에만 루트를 바꿔요. 다른 지시문(try_files나 templates 등)이 같은 사이트 루트를 알게 하려면 root 지시문을 대신 사용해요.
hide는 숨길 파일 또는 폴더 목록이에요. 요청되면 파일 서버가 존재하지 않는 것처럼 처리해요. placeholder와 glob 패턴을 받아요. 참고로 이들은 파일 시스템 경로이지 요청 경로가 아니에요. 즉 상대 경로는 사이트 루트가 아닌 현재 작업 디렉터리를 기준으로 하고, 모든 경로는 비교 전에(가능하면) 절대 형태로 변환돼요. 경로 구분자 없이 파일 이름이나 패턴을 지정하면 위치와 무관하게 이름이 일치하는 모든 파일을 숨겨요. 그 외에는 경로 접두사 일치를 시도하고, 그다음 glob 일치를 시도해요. Caddyfile 설정이므로 활성 설정 파일이 기본으로 추가돼요. 하위 지시문은 여러 번 지정할 수 있어요. 각 사용은 목록을 대체하는 대신 추가해서, import된 스니펫이 사이트별 hide와 결합되는 공통 hide에 기여하게 해요. Hide 비교는 대소문자를 구분해요. 대소문자 구분 없는 파일 시스템에서는 대소문자가 다른 요청 경로가 같은 디스크 경로로 해석될 수 있으므로, 민감한 경로의 보안 경계로 hide를 취급해서는 안 돼요.
index는 인덱스 파일로 찾을 파일 이름 목록이에요. 기본값: index.html index.txt
browse는 인덱스 파일이 없는 디렉터리에 대한 요청에 파일 목록을 활성화해요.
**<template_file>**은 디렉터리 목록에 사용할 선택적 커스텀 템플릿 파일이에요. 기본값은 caddy file-server export-template 명령으로 추출할 수 있는 템플릿이며, 기본 템플릿을 stdout에 출력해요. 내장 템플릿은 소스 코드에서도 찾을 수 있어요. Browse 템플릿은 표준 템플릿 모듈의 액션도 사용할 수 있어요.
reveal_symlinks는 디렉터리 목록에서 심볼릭 링크의 대상을 드러내도록 해요. 기본적으로 링크 대상은 숨겨지고 링크 파일 자체만 표시돼요.
sort는 디렉터리 목록의 기본 정렬을 바꿔요. 첫 번째 매개변수는 정렬할 필드/열이에요: name, namedirfirst, size 또는 time. 두 번째 인자는 선택적 방향이에요: asc 또는 desc. 예를 들어 sort name desc는 이름을 내림차순으로 정렬해요.
file_limit은 디렉터리 목록에 표시할 최대 파일 수를 설정해요. 기본값: 10000. 파일 수가 이 한도를 초과하면 처음 N개 파일만 표시되며, N은 지정된 한도예요.
precompressed는 사전 압축된 사이드카 파일을 검색할 인코딩 형식 목록이에요. 인자들은 사전 압축된 사이드카 파일을 검색할 인코딩 형식의 정렬된 목록이에요. 지원되는 형식은 gzip(.gz), zstd(.zst), br(.br)예요. 형식을 생략하면 기본값은 br zstd gzip(이 순서)이에요.

모든 파일 조회는 먼저 압축되지 않은 파일의 존재를 확인해요. 찾으면 Caddy는 각 활성화 형식의 파일 확장자를 가진 사이드카 파일을 찾아요. 사전 압축된 사이드카 파일을 찾으면 Content-Encoding 응답 헤더를 적절히 설정한 채 사전 압축 파일로 응답해요. 그렇지 않으면 평소처럼 압축되지 않은 파일로 응답해요. encode 지시문이 활성화되어 있으면 사전 압축되지 않은 응답을 그때그때 압축할 수 있어요.
status는 응답을 쓸 때 사용할 선택적 상태 코드 덮어쓰기예요. 커스텀 에러 페이지로 요청에 응답할 때 특히 유용해요. 3자리 상태 코드일 수 있어요. 예: 404. Placeholder를 지원해요. 기본적으로 쓰는 상태 코드는 보통 200이고, 부분 콘텐츠면 206이에요.
disable_canonical_uris는 리다이렉트하는 기본 동작(요청 경로가 디렉터리면 뒤에 슬래시를 추가하고, 파일이면 뒤 슬래시를 제거)을 비활성화해요. 기본적으로 요청 경로의 마지막 요소(파일 이름)가 내부 재작성을 겪었으면 정규화가 일어나지 않아 암묵적 동작이 명시적 재작성을 덮어쓰지 않아요.
pass_thru는 통과 모드를 활성화해요. 요청한 파일을 찾지 못하면 404 에러를 트리거(handle_errors 라우트 호출)하는 대신 route의 다음 HTTP 핸들러로 계속 진행해요. 실질적으로 이 지시문이 순서상 마지막이기 때문에, file_server 뒤에 다른 핸들러 지시문이 있는 route 블록 안에서만 유용해요.

예시 (Examples)

현재 디렉터리에서 정적 파일 서버:

file_server

파일 목록을 활성화한 상태:

file_server browse

/static 폴더 안의 정적 파일만 서빙해요:

file_server /static/*

file_server 지시문은 보통 파일을 서빙할 루트 경로를 설정하기 위해 root 지시문과 함께 쓰여요:

example.com {
	root /srv
	file_server
}

Caddy를 systemd 서비스로 실행 중이라면 /home에서 파일을 읽는 것은 동작하지 않아요. caddy 사용자에게 /home 디렉터리에 대한 "실행(executable)" 권한이 없기 때문이에요(트래버설에 필요). 파일은 /srv나 /var/www/html에 두는 걸 권장해요.

모든 .git 폴더와 내용을 숨겨요:

file_server {
	hide .git
}

클라이언트가 지원하면(Accept-Encoding 헤더) 요청 파일 옆의 사전 압축 파일 존재를 확인해요. 그래서 /path/to/file이 요청되면 /path/to/file.br, /path/to/file.zst, /path/to/file.gz를 그 순서로 확인하고, 첫 번째 사용 가능한 파일을 해당 Content-Encoding과 함께 서빙해요:

file_server {
	precompressed
}

더 알아보기 (Learn more)

Caddy 공식 문서