가이드

작성자 Matt Connor 2026-08-14 · 업데이트됨 2026-08-15

LinkBreeze 직접 호스팅: Docker Compose 구축 가이드

Q: 어떤 LinkBreeze 이미지 태그를 실행해야 합니까?

ghcr.io/manak-hash/linkbreeze:1.2.7와 같은 버전 태그를 실행하고, 의도적으로 변경하십시오. 릴리스 워크플로는 latest과 버전 번호만 푸시하므로, v가 포함된 :v1.2.7은 존재하지 않으며 Docker는 manifest unknown 오류를 반환합니다. 이 이미지는 linux/amd64 전용으로 빌드되었으므로, arm64 VPS를 사용하는 경우 태그를 복제하여 로컬에서 직접 빌드해야 합니다.

Q: LinkBreeze 분석에서 국가별 통계가 비어 있는 이유는 무엇입니까?

LinkBreeze는 cf-ipcountry 또는 x-vercel-ip-country와 같은 프록시 헤더에서 방문자의 국가 정보를 읽어오며, 자체적인 GeoIP 데이터베이스를 포함하고 있지 않습니다. Caddy나 Nginx 뒤에 있는 VPS는 해당 헤더를 설정하지 않으므로 국가 정보가 null로 저장됩니다. 도메인 앞에 Cloudflare를 배치하거나, 리버스 프록시에서 로컬 GeoIP 조회를 통해 해당 헤더 중 하나를 설정하도록 구성하십시오.

Q: 정확히 무엇을 백업해야 하며, 어떻게 복원합니까?

데이터베이스 파일뿐만 아니라 linkbreeze-data 볼륨 전체를 백업하십시오. /app/data/linkbreeze.db에는 모든 링크, 페이지, 설정, 구독자 및 분석 데이터가 포함되어 있으며, /app/data/uploads에는 페이지에서 참조하는 아바타와 썸네일 이미지가 저장됩니다. 컨테이너를 중지하고 docker compose cp linkbreeze:/app/data ./backup-$(date +%F)를 실행한 뒤 다시 시작하십시오. 복원하려면 디렉터리를 중지된 컨테이너에 다시 복사하고 컨테이너를 시작하면 됩니다. 대시보드에서 내보낸 JSON 파일은 프로필, 링크, 설정 및 테마에 대한 구성 스냅샷일 뿐이며, 분석 데이터나 이미지는 포함되어 있지 않습니다.

LinkBreeze를 VPS에 배포하는 방법을 알아봅니다. Docker Compose와 Caddy를 활용한 설정, SQLite 데이터 관리, 그리고 안정적인 서비스 운영을 위한 이미지 태그 고정 및 트래킹 설정 등 실무적인 구축 과정을 상세히 설명합니다.

LinkBreeze란 무엇인가

LinkBreeze는 직접 호스팅하는 Linktree 대안 서비스입니다. 하나의 Docker 컨테이너로 공개용 링크 페이지와 관리자 대시보드를 제공하며, 모든 상태 정보는 단일 SQLite 파일에 저장됩니다. 이 프로젝트는 MIT 라이선스를 따르며 TypeScript와 Next.js로 작성되었고, ghcr.io/manak-hash/linkbreeze로 배포됩니다. 이를 실행하려면 VPS, 해당 VPS를 가리키는 A 레코드가 설정된 도메인, 80번 및 443번 포트 개방, 그리고 Compose 플러그인이 포함된 Docker Engine이 필요합니다.

이 가이드는 저장소에서 공식적으로 지원하는 배포 방식, 즉 자체 인증서를 가져오는 리버스 프록시 뒤에서 Docker Compose를 실행하는 방법을 다룹니다. 또한 무엇이 서비스 중단을 유발하는지도 설명합니다. 링크 페이지는 타인이 클릭하는 공개 URL이므로, 서비스가 중단되면 클릭을 유도할 수 없기 때문입니다.

본격적인 시작에 앞서, 이 프로젝트가 얼마나 초기 단계인지 명확히 인지하시기 바랍니다.

LinkBreeze는 공개 프로필 링크용으로 사용하기에 충분히 성숙했습니까?

2026년 8월 기준으로 해당 저장소는 178개의 별, 17개의 포크, 그리고 단 한 명의 관리자를 보유하고 있습니다. 첫 번째 태그된 릴리스인 v1.0.0은 2026년 7월 1일에 배포되었습니다. 이는 수년이 아닌, 불과 몇 주 된 프로젝트입니다.

ChartLinkBreeze tagged releases per week, v1.0.0 to v1.2.7

week

releases

cumulative

2026-06-29

2026-07-06

2026-07-13

2026-07-20

2026-07-27

2026-08-03

2026-08-10

The data behind this chart

[
  {
    "week": "2026-06-29",
    "releases": 3,
    "cumulative": 3
  },
  {
    "week": "2026-07-06",
    "releases": 3,
    "cumulative": 6
  },
  {
    "week": "2026-07-13",
    "releases": 1,
    "cumulative": 7
  },
  {
    "week": "2026-07-20",
    "releases": 2,
    "cumulative": 9
  },
  {
    "week": "2026-07-27",
    "releases": 3,
    "cumulative": 12
  },
  {
    "week": "2026-08-03",
    "releases": 2,
    "cumulative": 14
  },
  {
    "week": "2026-08-10",
    "releases": 3,
    "cumulative": 17
  }
]

v1.0.0 이후 이 프로젝트는 17개의 릴리스를 7주에 걸쳐 배포했습니다. 이 가이드를 작성하는 시점에도 마지막 주의 릴리스가 진행 중이었으며, 이미 3개의 릴리스가 포함되어 있었습니다.

이 내용을 두 가지 사실로 나누어 이해해야 합니다. 관리자는 활발히 활동 중이며 버그는 며칠 내로 수정됩니다. 하지만 스키마와 기본 설정값은 여전히 변경되고 있으므로, 배포 후 방치하는 인스턴스는 작성 중인 코드와 크게 달라질 것입니다.

라이선스는 최악의 상황으로부터 사용자를 보호합니다. MIT 라이선스, 컨테이너 이미지, 그리고 로컬 디스크의 SQLite 파일을 사용하므로 개발이 중단되더라도 현재 상태는 계속 유지됩니다. 그러나 보안 패치가 중단된 공개 웹 애플리케이션은 시간이 지남에 따라 위험 요소가 될 수 있으며, 라이선스가 이를 보호해주지는 않습니다. 지속적으로 업데이트할 계획을 세우고, 아래의 백업 루틴을 첫날부터 작동하도록 구성하십시오.

이미지 태그를 고정하고 latest를 사용하지 마십시오

릴리스 워크플로는 버전당 정확히 두 개의 태그를 푸시합니다. latest과 v이 제거된 버전 번호입니다. 따라서 v1.2.7 릴리스에 대한 고정 태그는 ghcr.io/manak-hash/linkbreeze:1.2.7입니다. :v1.2.7을 작성하면 아무것도 가져오지 않으며 Docker는 manifest unknown를 보고합니다. 해당 태그는 푸시된 적이 없기 때문입니다.

latest는 계속 변하므로 태그를 고정해야 합니다. 위 차트의 주기에 따라 latest에 대해 docker compose pull을 수행하면 사용자가 이용 중인 페이지에 대해 검토되지 않은 업그레이드가 발생합니다. 태그를 고정하면 파일을 수정할 때 업그레이드가 수행됩니다.

이미지에 관해 한 가지 더 말씀드릴 점이 있습니다. 릴리스 워크플로는 platforms: 설정 없이 빌드되므로 게시된 이미지는 linux/amd64 전용입니다. arm64 호스트에서 가져오기를 시도하면 no matching manifest for linux/arm64/v8 in the manifest list entries 오류와 함께 실패합니다. 만약 x86 대신 ARM VPS를 운영 중이라면, 해당 장비에서 직접 이미지를 빌드하십시오.

git clone --branch v1.2.7 --depth 1 https://github.com/Manak-hash/LinkBreeze.git
cd LinkBreeze
docker build -t linkbreeze:1.2.7 .

그런 다음 아래 compose 파일의 이미지 이름으로 linkbreeze:1.2.7을 사용하십시오.

Caddy 뒤에 LinkBreeze 배포 및 자동 TLS 설정

Caddy는 Let's Encrypt에서 인증서를 직접 요청하고 갱신하므로, TLS(Transport Layer Security)를 위해 별도의 인증서 작업이 필요하지 않습니다. 전체 배포는 한 디렉터리에 있는 세 개의 파일로 구성됩니다.

먼저 시크릿을 생성합니다:

mkdir -p ~/linkbreeze && cd ~/linkbreeze
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env

SECRET_KEY는 관리자 세션 쿠키에 서명하고 분석 방문자 해시를 솔팅(salting)하는 데 사용됩니다. 저장소에 게시된 compose 파일은 기본값을 ${SECRET_KEY:-changeme-in-production}으로 설정하므로, 이 단계를 건너뛰면 GitHub에 공개된 세션 서명 키로 인스턴스가 실행됩니다. 나중에 변경하면 로그아웃되고 분석 솔트가 초기화되므로, 첫 실행 전에 설정하십시오.

docker-compose.yml를 작성합니다:

services:
  linkbreeze:
    image: ghcr.io/manak-hash/linkbreeze:1.2.7
    restart: unless-stopped
    volumes:
      - linkbreeze-data:/app/data
    environment:
      - DATABASE_PATH=/app/data/linkbreeze.db
      - SECRET_KEY=${SECRET_KEY}
      - BASE_URL=https://links.example.com
    networks:
      - linkbreeze-net

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - linkbreeze-net

networks:
  linkbreeze-net:

volumes:
  linkbreeze-data:
  caddy-data:
  caddy-config:

BASE_URL는 선택 사항이지만 설정하는 것이 좋습니다. 애플리케이션에 실제 공개 주소를 알려주어, 위조된 Host 헤더로 요청이 들어와도 애플리케이션이 타인의 도메인으로 링크를 생성하지 못하도록 합니다.

그 옆에 본인의 도메인을 사용하여 Caddyfile을 작성합니다:

links.example.com {
    encode zstd gzip
    reverse_proxy linkbreeze:3000
}

Caddy는 프록시 요청 시 기본적으로 X-Forwarded-For 및 X-Forwarded-Proto를 설정하며, 분석 기능은 이에 의존합니다. 서비스를 시작합니다:

docker compose up -d
docker compose ps
docker compose logs -f caddy

docker compose ps을 실행하면 LinkBreeze 컨테이너가 healthy 상태로 표시되어야 합니다. 이미지는 자체 헬스체크인 wget --spider -q http://127.0.0.1:3000/api/health를 포함하고 있으므로 별도로 추가할 필요가 없습니다. 저장소의 Caddy 예제에 있는 헬스체크를 그대로 복사하지 마십시오. 해당 예제는 curl을 호출하는데, 이 이미지는 node:22-alpine 기반으로 빌드되어 busybox wget만 포함하고 curl은 없기 때문입니다. 해당 컨테이너는 페이지를 완벽하게 제공하면서도 unhealthy 상태를 보고할 수 있습니다.

브라우저에서 https://links.example.com을 엽니다. 첫 방문 시 /setup의 설정 마법사로 이동하며, 여기서 단일 관리자 계정을 생성합니다. 이후 대시보드는 /dashboard에, 로그인 폼은 /login에 위치합니다. 해당 계정은 이 인스턴스에 로컬로 존재하며 애플리케이션 내에 싱글 사인온(SSO) 훅이 없으므로, 호스팅 중인 다른 서비스와 동일한 계정으로 대시보드에 로그인하려면 자체 호스팅 Authentik과 같은 포워드 인증 프록시를 앞단에 두어야 합니다.

compose 파일이 수행하지 않는 작업에 유의하십시오. 포트 3000을 외부로 노출하지 않습니다. Caddy만이 공개 인터페이스에서 수신 대기합니다. Compose 파일 문법이 생소하다면 VPS를 위한 Docker Compose 기초에서 이 파일이 가정하는 내용을 다루고 있으며, 이미 다른 프록시를 사용 중이라면 Nginx, Caddy 및 Traefik 비교에서 변경 사항을 설명합니다. 저장소는 Certbot을 사용하는 Nginx, Traefik 및 Cloudflare 터널에 대한 작동 예제를 제공합니다.

데이터가 저장되는 위치와 백업에 포함되어야 할 항목

DATABASE_PATH는 /app/data/linkbreeze.db을 가리킵니다. 업로드된 아바타와 링크 썸네일은 /app/data/uploads 내부에 함께 저장됩니다. 두 항목 모두 linkbreeze-data라는 이름의 볼륨에 존재하므로, 백업 단위는 데이터베이스 파일 단독이 아닌 해당 볼륨 전체가 되어야 합니다. 업로드 디렉터리를 제외하고 파일만 복원하면 페이지의 모든 이미지가 404 오류를 반환하게 됩니다.

그 외의 모든 데이터는 해당 데이터베이스 내에 존재합니다. 여기에는 페이지, 링크, 설정, 테마, 이메일 구독자 및 분석 데이터 행이 포함됩니다.

컨테이너를 중지한 상태에서 복사본을 생성하십시오:

docker compose stop linkbreeze
docker compose cp linkbreeze:/app/data ./backup-$(date +%F)
docker compose start linkbreeze

SQLite 데이터베이스에 프로세스가 쓰기 작업을 수행하는 도중에 복사하면 트랜잭션이 완료되지 않은 상태로 캡처되어, 복사본이 손상된 파일로 열릴 수 있으므로 반드시 먼저 중지해야 합니다. 복사가 진행되는 동안 페이지는 오프라인 상태가 됩니다. 복원 작업은 이 과정을 역순으로 수행하면 됩니다:

docker compose stop linkbreeze
docker compose cp ./backup-2026-08-14/. linkbreeze:/app/data
docker compose start linkbreeze
docker compose logs -f linkbreeze

대시보드에서는 /api/backup을 통해 linkbreeze-backup-YYYY-MM-DD.json 형식으로 JSON 내보내기 기능을 제공합니다. 여기에는 프로필, 링크, 설정 및 저장된 테마가 포함됩니다. 분석 기록, 이메일 구독자 또는 업로드된 이미지는 포함되지 않으며, 이 파일을 복원하면 해당 4개 테이블의 현재 행을 삭제한 뒤 파일의 내용을 삽입합니다. 이 기능은 호스트를 이전하거나 편집 실수를 되돌리기 위한 설정 스냅샷으로 활용하십시오. 볼륨 복사본이 곧 백업입니다.

VPS에서 SQLite를 운영할 때와 마찬가지로 여기에도 두 가지 저장소 규칙이 적용됩니다. 데이터베이스는 반드시 로컬 디스크에 유지하십시오. 네트워크 파일 시스템에서는 SQLite의 잠금 기능이 불안정하여 페이지 손상으로 이어질 수 있기 때문입니다. 또한 이름이 지정된 볼륨 대신 호스트 바인드 마운트를 사용하는 경우, 먼저 호스트 디렉터리의 소유권을 변경(chown)하십시오. 컨테이너는 node:22-alpine 내 uid 1000인 비루트 사용자 node로 실행되므로, root가 생성한 디렉터리에 쓰기 권한이 없어 애플리케이션이 데이터베이스를 열지 못하고 컨테이너가 시작 시 종료됩니다. Compose에서 이름이 지정된 볼륨과 바인드 마운트 비교에서 해당 내용을 자세히 다룹니다.

분석 도구와 동의 배너가 필요 없는 이유

이 기능이야말로 다른 곳에서 무료로 얻을 수 있는 페이지를 굳이 직접 호스팅하는 이유를 정당화합니다.

분석 도구는 쿠키를 사용하지 않습니다. 방문자에게 쿠키가 설정되지 않으며, 공개 페이지에서 타사 스크립트가 로드되지 않습니다. 방문자는 IP 주소, 사용자 에이전트 문자열, 솔트(salt)를 SHA-256으로 해싱한 뒤 16자리 16진수로 자른 값으로 식별됩니다. 솔트 자체는 현재 UTC 날짜와 SECRET_KEY을 해싱한 값이므로 UTC 자정에 변경되며, 어제의 해시값으로 오늘의 방문자를 추적할 수 없습니다. 원본 IP 주소는 데이터베이스에 기록되지 않습니다.

클릭 수는 서버에서 집계됩니다. 공개 페이지의 모든 http 링크는 자신의 도메인에 있는 /go/<id>을 가리키며, 이 경로가 클릭을 기록한 뒤 실제 목적지로 302 리다이렉트 응답을 보냅니다. 따라서 JavaScript가 비활성화된 환경이나 백그라운드 요청을 차단하는 인앱 브라우저에서도 클릭 집계가 정상적으로 작동합니다. 페이지 뷰는 /api/track를 통해 기록됩니다.

두 가지 예외 사항을 알아두어야 합니다. 유효한 관리자 세션이 포함된 요청은 건너뛰므로, 페이지를 직접 편집할 때 조회수가 증가하지 않습니다. 알려진 크롤러 사용자 에이전트 또한 집계에서 제외됩니다.

동의 관련 사항: 독자의 기기에는 아무것도 저장되지 않으며, 쿠키 배너가 허가를 요구하는 대상은 독자의 기기에 저장되는 쿠키입니다. 독자가 거주하는 지역에 따라 법적 의무가 달라질 수 있으므로 확인이 필요하지만, 여기에는 공개해야 할 추적 쿠키가 없으며 데이터를 수신하는 제3자도 없습니다.

사용자들이 종종 놀라는 주의 사항이 하나 있습니다. SECRET_KEY을 교체하면 일일 솔트도 함께 변경되므로, 그 시점부터 모든 재방문자는 신규 방문자로 집계됩니다.

분석 데이터의 국가 열이 비어 있는 이유는 무엇입니까?

스택 내에서 국가 헤더를 설정하는 항목이 없기 때문입니다. LinkBreeze는 cf-ipcountry 및 x-vercel-ip-country와 같은 프록시 헤더를 통해 국가 정보를 확인합니다. Caddy나 Nginx 뒤에 있는 VPS 환경에서는 이러한 헤더가 존재하지 않으므로 국가 정보가 null로 기록되고 분석 결과가 비어 있게 됩니다. 컨테이너 내부에는 GeoIP 데이터베이스가 포함되어 있지 않습니다.

이 문제를 해결하는 방법은 두 가지입니다. 도메인 앞에 Cloudflare를 배치하면 프록시를 거치는 모든 요청에 cf-ipcountry이 추가됩니다. 또는 로컬 GeoIP 조회를 수행하여 직접 운영하는 리버스 프록시에서 해당 헤더 중 하나를 설정할 수 있습니다.

이와 관련된 더 심각한 함정이 있으니 확인이 필요합니다. 클릭 및 조회 핸들러는 클라이언트 주소를 읽을 때 먼저 X-Forwarded-For을 확인하고, 그다음 X-Real-IP을 확인하며, 두 헤더가 모두 없을 경우 0.0.0.0로 대체합니다. 프록시 없이 포트 3000을 인터넷에 직접 노출하면 모든 방문자가 동일한 값으로 해싱됩니다. 이 경우 고유 방문자 수는 항상 1로 표시되며, IP당 분당 60개 이벤트라는 속도 제한(rate limit)이 전체 방문자에게 한꺼번에 적용됩니다. 위에서 언급한 reverse_proxy 지시문을 사용하면 Caddy가 헤더를 자동으로 설정하므로 두 문제 모두 해결됩니다.

Linktree에서 가져오기 및 이전되지 않는 항목

대시보드의 마이그레이션 마법사는 공개 프로필 URL이나 내보낸 파일을 허용합니다. 이 마법사는 linktr.ee, bento.me, lnk.bio, tap.link, hopp.bio, beacons.ai, solo.to, linkfly, mssg.me, LittleLink 페이지와 일반적인 HTML 및 JSON 내보내기 형식을 인식합니다. Linktree나 Bento URL의 경우 해당 페이지에 포함된 __NEXT_DATA__ JSON을 읽어 들입니다. 정적 페이지의 경우 앵커 태그를 읽습니다.

이전되는 항목은 각 링크의 제목, URL, 설명, 이미지, 소셜 프로필 여부, 그리고 사용자의 표시 이름, 소개글, 아바타입니다. 데이터베이스에 기록하기 전에 발견된 링크 중 유지할 항목을 직접 선택할 수 있습니다.

이전되지 않는 항목은 분석 기록, 테마 및 레이아웃, 이메일 구독자, 게시 예약 날짜, 그리고 이전 플랫폼이 자체 로그인 뒤에 보관하는 모든 데이터입니다. 외관은 수동으로 다시 구성해야 하며, 기존 클릭 기록은 이전 서비스에 남는다는 점을 인지하십시오.

임포터는 브라우저가 아닌 서버에서 URL을 가져오므로 공개되지 않은 주소는 거부합니다. Private/local URLs are not allowed는 사용자가 내부 네트워크의 주소를 입력했음을 의미하며, 이러한 거부는 의도된 것입니다. 이 기능이 없다면 대시보드 접근 권한이 있는 누구나 사용자의 서버를 이용해 서버에서만 접근 가능한 내부 장비를 탐색할 수 있기 때문입니다. 그 외에 발생할 수 있는 메시지는 Only http and https URLs are allowed, Request timed out, Response too large입니다.

스크래핑은 타사의 마크업 구조에 의존합니다. 링크가 분명히 존재하는 페이지에서 마법사가 아무것도 찾지 못한다면, 해당 플랫폼이 파서 작성 이후 HTML 구조를 변경한 것입니다. 수정 사항을 기다리기보다 링크를 직접 추가하십시오. 프로필 페이지가 아닌 측정 가능한 단축 링크가 필요한 경우, Shlink와 같은 자체 호스팅 URL 단축기가 해당 역할을 수행하며 동일한 서버에서 원활하게 작동합니다.

고정된 배포 버전 업데이트하기

# edit the image tag in docker-compose.yml, then
docker compose pull
docker compose up -d
docker compose logs -f linkbreeze

컨테이너가 시작되면 스키마 마이그레이션이 자동으로 실행됩니다. 마이그레이션을 이전 상태로 되돌리는 공식적인 방법은 없으므로, 먼저 볼륨을 복사해 두어야 합니다. 되돌릴 수 없는 업그레이드는 이전 상태를 복구할 수 있을 때만 안전합니다.

새로운 릴리스가 존재하면 대시보드에 배너가 표시됩니다. 이 기능은 24시간마다 프로젝트의 GitHub 저장소에서 작은 버전 파일을 가져와 확인하며, 인스턴스에 관한 어떠한 정보도 전송하지 않습니다. 태그를 변경하기 전에 릴리스 노트를 읽어보십시오. 현재 프로젝트 단계에서는 마이너 버전 업데이트만으로도 의존하고 있는 기본 설정이 변경될 수 있기 때문입니다.

실패 유형과 표시되는 문자열

manifest unknown (pull 작업 시). 태그가 :v1.2.7로 작성되었습니다. 레지스트리 태그에는 v가 포함되지 않으므로 :1.2.7를 사용하십시오.

no matching manifest for linux/arm64/v8 in the manifest list entries. 게시된 이미지는 amd64 전용입니다. 태그가 지정된 소스에서 ARM 호스트용으로 빌드하십시오.

페이지는 정상적으로 로드되는데 컨테이너가 unhealthy를 보고합니다. compose 파일의 healthcheck가 curl를 호출하고 있으나, 해당 이미지는 이를 포함하고 있지 않습니다. 이를 삭제하고 이미지 자체의 wget healthcheck가 실행되도록 하십시오.

Caddy가 인증서 오류를 반환하거나 아무것도 응답하지 않습니다. docker compose logs caddy를 확인하십시오. 일반적인 원인은 A 레코드가 아직 이 VPS를 가리키지 않거나, 방화벽에서 80번 포트가 닫혀 있는 경우입니다. 80번 포트가 닫히면 Caddy가 도메인 소유권을 증명하기 위해 사용하는 ACME(automatic certificate management environment) HTTP 챌린지가 차단됩니다.

순 방문자 수가 1에서 멈춰 있습니다. 프록시가 X-Forwarded-For를 설정하지 않아 모든 방문자가 동일한 해시 값을 가집니다.

어제까지는 정상 작동하던 컨테이너가 시작 직후 종료됩니다. 명명된 볼륨(named volume)에서 호스트 바인드 마운트(host bind mount)로 변경했다면, 데이터 디렉터리의 소유권은 root에 있고 애플리케이션은 uid 1000으로 실행되므로 데이터베이스 파일을 열 수 없습니다. 호스트 디렉터리에 sudo chown -R 1000:1000를 수행하십시오.

추적 요청에 대해 HTTP 429 응답이 반환됩니다. /api/track 및 /go/<id>에 설정된 IP당 제한(throttle)에 도달했습니다. 방문자는 목적지로 정상적으로 리다이렉트되지만, 클릭 수가 집계되지 않을 뿐입니다.

FAQ

LinkBreeze는 공개용 링크 인 바이오(link in bio) 서비스로 사용할 준비가 되었습니까?

이 프로젝트는 초기 단계입니다. 2026년 8월 기준으로 저장소는 178개의 스타와 17개의 포크를 보유하고 있으며, 관리자는 1명입니다. 첫 번째 릴리스는 2026년 7월 1일에 배포되었습니다. 평균적으로 일주일에 두 번 이상 릴리스가 이루어지므로 버그는 빠르게 수정되지만, 동작 방식도 자주 변경됩니다. MIT 라이선스와 로컬 SQLite 파일을 사용하므로 개발이 중단되더라도 페이지는 계속 작동하지만, 보안 업데이트가 없는 공개 웹 애플리케이션은 위험 요소가 될 수 있습니다. 따라서 한 번 설치하고 끝나는 소프트웨어가 아니라 지속적으로 업데이트해야 하는 소프트웨어로 다루어야 합니다.

어떤 LinkBreeze 이미지 태그를 실행해야 합니까?

ghcr.io/manak-hash/linkbreeze:1.2.7와 같은 버전 태그를 실행하고, 의도적으로 변경하십시오. 릴리스 워크플로는 latest과 버전 번호만 푸시하므로, v가 포함된 :v1.2.7은 존재하지 않으며 Docker는 manifest unknown 오류를 반환합니다. 이 이미지는 linux/amd64 전용으로 빌드되었으므로, arm64 VPS를 사용하는 경우 태그를 복제하여 로컬에서 직접 빌드해야 합니다.

LinkBreeze 분석에서 국가별 통계가 비어 있는 이유는 무엇입니까?

LinkBreeze는 cf-ipcountry 또는 x-vercel-ip-country와 같은 프록시 헤더에서 방문자의 국가 정보를 읽어오며, 자체적인 GeoIP 데이터베이스를 포함하고 있지 않습니다. Caddy나 Nginx 뒤에 있는 VPS는 해당 헤더를 설정하지 않으므로 국가 정보가 null로 저장됩니다. 도메인 앞에 Cloudflare를 배치하거나, 리버스 프록시에서 로컬 GeoIP 조회를 통해 해당 헤더 중 하나를 설정하도록 구성하십시오.

정확히 무엇을 백업해야 하며, 어떻게 복원합니까?

데이터베이스 파일뿐만 아니라 linkbreeze-data 볼륨 전체를 백업하십시오. /app/data/linkbreeze.db에는 모든 링크, 페이지, 설정, 구독자 및 분석 데이터가 포함되어 있으며, /app/data/uploads에는 페이지에서 참조하는 아바타와 썸네일 이미지가 저장됩니다. 컨테이너를 중지하고 docker compose cp linkbreeze:/app/data ./backup-$(date +%F)를 실행한 뒤 다시 시작하십시오. 복원하려면 디렉터리를 중지된 컨테이너에 다시 복사하고 컨테이너를 시작하면 됩니다. 대시보드에서 내보낸 JSON 파일은 프로필, 링크, 설정 및 테마에 대한 구성 스냅샷일 뿐이며, 분석 데이터나 이미지는 포함되어 있지 않습니다.

Linktree에서 가져오기를 하면 분석 데이터와 테마도 함께 이전됩니까?

아니요. 마이그레이션 마법사는 이전 공개 프로필에서 링크 제목, URL, 설명, 이미지와 표시 이름, 소개글, 아바타 정보만 읽어옵니다. 분석 기록, 테마, 이메일 구독자 및 예약 게시 날짜는 이전되지 않습니다. 가져오기 후 테마 편집기에서 디자인을 다시 구성해야 하며, 클릭 기록은 이전 플랫폼에 그대로 남게 됩니다.

#linkbreeze#linktree-alternative#docker-compose #sqlite #self-hosting #analytics