LiteFS 설정 레퍼런스 (LiteFS Config Reference)

원문 보기 위키 갱신 2026.10.08

LiteFS의 대부분의 구성 옵션은 litefs.yml 설정 파일을 통해 설정돼요. FUSE 디렉토리, 내부 데이터 디렉토리, HTTP API/프록시 서버, 리스 매니지먼트(Consul/static) 등 LiteFS를 운영할 때 필요한 모든 설정 항목을 알려드려요.

출처: 문서

본문

LiteFS의 구성 옵션 대부분은 litefs.yml 구성 파일로 설정돼요. 완전히 주석이 달린 litefs.yml 버전은 LiteFS 리포지토리에서 찾을 수 있어요.

설정 파일 검색 경로 (Config file search path)

LiteFS는 다음 경로에서 설정 파일을 찾아요:

현재 디렉토리: ./litefs.yml
홈 디렉토리: ~/litefs.yml
시스템 구성 디렉토리: /etc/litefs.yml

명령줄 플래그로 설정 경로를 명시적으로 지정할 수도 있어요:

litefs mount -config /path/to/litefs.yml

litefs run -config /path/to/litefs.yml

환경 변수 (Environment Variables)

LiteFS는 구성 파일 내에서 환경 변수를 평가할 수 있어요. 변수는 $MY_VAR 구문이나 ${MY_VAR} 구문으로 참조할 수 있어요.

기본 문자열 동등·부등 표현식도 단일 또는 이중 따옴표로 평가할 수 있어요:

${MY_VAR == "xyz"}

${MY_VAR != "xyz"}

환경 변수 평가는 명령줄 인자에 -no-expand-env 플래그를 지정해 비활성화할 수 있어요.

FUSE 디렉토리 (FUSE directory)

LiteFS는 FUSE 디렉토리 마운트를 사용해 Linux 파일 시스템 호출을 가로채 SQLite 트랜잭션이 언제 시작되고 끝나는지 추적하여 복제할 수 있게 해요. 권장 경로는 /litefs이며, 애플리케이션이 데이터베이스와 상호작용할 때 사용해야 하는 디렉토리예요.

# The FUSE section handles settings on the FUSE file system. FUSE
# provides a layer for intercepting SQLite transactions on the
# primary node so they can be shipped to replica nodes
# transparently.
fuse:
  # Required. This is the mount directory that applications will
  # use to access their SQLite databases.
  dir: "/litefs"

  # Enable mounting of the file system by non-root users.
  # You must enable the 'user_allow_other' option in /etc/fuse.conf as well.
  allow-other: false

  # The debug flag enables debug logging of all FUSE API calls.
  # This will produce a lot of logging. Not for general use.
  debug: false

내부 데이터 디렉토리 (Internal data directory)

LiteFS는 패스스루(passthrough) 파일 시스템으로 동작하므로, 모든 데이터베이스 파일은 여전히 내부적으로 일반 파일 시스템에 저장돼야 해요. 이 내부 데이터 디렉토리는 재시작 사이에 데이터를 잃지 않도록 영구 볼륨에 저장해야 해요.

또한 LiteFS는 이 디렉토리에 트랜잭션 파일(LTX 파일이라고 함)을 저장해요. 이 파일들은 retention enforcement(보존 강제) 라는 내부 프로세스를 통해 주기적으로 제거돼요.

# The data section specifies where internal LiteFS data is stored
# and how long to retain the transaction files.
# 
# Transaction files are used to ship changes to replica nodes so
# they should persist long enough for replicas to retrieve them,
# even in the face of a short network interruption or a redeploy.
# Under high load, these files can grow large so it's not advised
# to extend retention too long.
data:
  # Path to internal data storage.
  dir: "/var/lib/litefs"

  # If true, compresses LTX files using LZ4 compression. Enabled by default.
  compress: true

  # Duration to keep LTX files. Latest LTX file is always kept.
  retention: "10m"

  # Frequency with which to check for LTX files to delete.
  retention-monitor-interval: "1m"

Supervisor / Exec

LiteFS는 다른 프로세스의 supervisor로 실행되는 옵션을 제공해요. 보통은 애플리케이션을 실행하는 명령이 될 거예요. 이렇게 하면 LiteFS가 애플리케이션을 시작하기 전에 스스로 마운트하고 클러스터에 연결할 수 있어서 유용해요. 앱에 신호를 전달하고, 앱이 종료되면 자동으로 함께 종료돼요.

# The exec field specifies a command to run as a subprocess of
# LiteFS. This command will be executed after LiteFS either
# becomes primary or is connected to the primary node. LiteFS
# will forward signals to the subprocess and LiteFS will
# automatically shut itself down when the subprocess stops.
#
# This can also be specified after a double-dash (--) on the
# command line invocation of the 'litefs mount' command.
exec: "myapp -addr :8080"

HTTP API 서버 (HTTP API Server)

LiteFS는 다른 노드의 API와 HTTP로 통신해요. 이는 구성의 http 섹션에서 설정할 수 있어요.

LiteFS의 기본 포트는 20202예요. 이 포트는 공개적으로 접근 가능하면 안 됩니다.

# This section defines settings for the LiteFS HTTP API server.
# This API server is how nodes communicate with each other.
http:
  # Specifies the bind address of the HTTP API server.
  addr: ":20202"

HTTP 프록시 서버 (HTTP Proxy Server)

LiteFS에는 대부분의 웹 애플리케이션을 위한 데이터 일관성과 요청 포워딩을 처리하는 내장 HTTP 프록시 서버가 포함돼 있어요. 기본적으로 비활성화되어 있지만, 바인드 주소와 타깃을 지정하면 활성화할 수 있어요.

# This section defines settings for the option HTTP proxy.
# This proxy can handle primary forwarding & replica consistency
# for applications that use a single SQLite database.
proxy:
  # Specifies the bind address of the proxy server.
  addr: ":8080"

  # The hostport of the target application. If blank, proxy is disabled.
  target: "localhost:8081"

  # The name of the database used for TXID tracking.
  db: "my.db"

  # If true, enables verbose logging of requests by the proxy.
  debug: false

  # List of paths that are ignored by the proxy. The asterisk is
  # the only available wildcard. These requests are passed
  # through to the target as-is.
  passthrough: ["/debug/*", "*.png"]

  # The duration to hold write requests when no primary is available.
  # This is helpful when a primary switches over and there is a small window
  # where the new primary is unknown to the replica.
  primary-redirect-timeout: "5s"

리스 매니지먼트 (Lease Management)

리더십은 외부 리스 시스템을 사용해 관리돼요. Consul을 사용하거나 단일 정적 primary 노드를 지정하는 방식으로 할 수 있어요.

# The lease section defines how LiteFS creates a cluster and
# implements leader election. For dynamic clusters, use the
# "consul". This allows the primary to change automatically when
# the current primary goes down. For a simpler setup, use
# "static" which assigns a single node to be the primary and does
# not failover.
lease:
  # Required. Must be either "consul" or "static".
  type: "consul"

  # Required. The URL for this node's LiteFS API.
  # Should match HTTP port.
  advertise-url: "http://$HOSTNAME:20202"

  # Sets the hostname that other nodes will use to reference this
  # node. Automatically assigned based on hostname(1) if not set.
  hostname: ""

  # Specifies whether the node can become the primary. If using
  # "static" leasing, this should be set to true on the primary
  # and false on the replicas.
  candidate: true

  # Filtered list of databases to replicate from the primary to this node.
  # If no databases are specified, all databases are replicated. You may only
  # filter databases on non-candidate nodes.
  databases: [ "my.db", "myother.db" ]

Consul 리스 (Consul Leasing)

Consul은 리더십이 primary 노드가 중지될 때 변경될 수 있게 해주는 권장 리스 백엔드예요. 노드가 Consul에 연결하고 자체 LiteFS API URL을 브로드캐스트할 수 있도록 url과 advertise-url이 필요해요.

lease:
  # A Consul server provides leader election and ensures that the
  # responsibility of the primary node can be moved in the event
  # of a deployment or a failure.
  consul:
    # Required. The base URL of the Consul server.
    url: "http://myhost:8500"

    # Required. The key used for obtaining a lease by the primary.
    # This must be unique for each cluster of LiteFS servers
    key: ""

    # Length of time before a lease expires. The primary will
    # automatically renew the lease while it is alive, however,
    # if it fails to renew in time then a new primary may be
    # elected after the TTL. This only occurs for unexpected loss
    # of the leader as normal operation will allow the leader to
    # handoff the lease to another replica without downtime.
    #
    # Consul does not allow a TTL of less than 10 seconds.
    ttl: "10s"

    # Length of time after the lease expires before a candidate
    # can become leader. This buffer is intended to prevent
    # overlap in leadership due to clock skew or in-flight calls.
    lock-delay: "1s"

정적 리스 (Static Leasing)

별도의 Consul 인스턴스를 실행하고 싶지 않고 primary 노드의 다운타임을 감수할 수 있다면, 정적 리스로 LiteFS를 실행할 수 있어요. 정적 리스는 단일 고정 노드만이 절대 primary가 된다는 뜻이에요.

정적 리스에는 추가 구성 섹션이 없어요. primary에는 lease.candidate 구성 필드를 true로, replicas에는 false로 설정하면 돼요. primary에 lease.hostname과 lease.advertise-url도 설정해야 해요.

기타 옵션 (Other options)

오류 시 종료 (Exit on error)

# If true, then LiteFS will not exit if there is a validation
# issue on startup. This can be useful for debugging issues as
# it avoids constantly restarting the node on ephemeral hosting.
exit-on-error: false

동기화 건너뛰기 (Skip sync)

# If true, then LiteFS will not wait until the node becomes the
# primary or connects to the primary before starting the subprocess.
skip-sync: false

트레이스 로그 (Trace Log)

트레이스 로그는 LiteFS 내부 이벤트에 대한 매우 저수준의 로그를 제공해요. 보통 문제 디버깅에만 사용되며 기본적으로 꺼져 있어요. 이 로그는 활성화하면 많은 디스크 I/O를 발생시킬 수 있어요.

# The tracing section enables a rolling, on-disk tracing log.
# This records every operation to the database so it can be
# verbose and it can degrade performance. This is for debugging
# only and should not typically be enabled in production.
tracing:
  # Toggles tracing if 'path' is also set. Defaults to true.
  enabled: true

  # Output path on disk.
  path: "/var/log/lifefs/trace.log"

  # Maximum size of a single trace log before rolling.
  # Specified in megabytes.
  max-size: 64

  # Maximum number of trace logs to retain.
  max-count: 10

  # If true, historical logs will be compressed using gzip.
  compress: true