SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Docker로 ntfy 자체 호스팅 서버 구축 및 알림 설정 방법

Docker Compose를 사용하여 VPS에 ntfy 서버를 직접 구축하는 방법을 설명합니다. TLS 설정부터 사용자 인증, ACL 적용, cron 및 systemd OnFailure를 통한 알림 자동화까지 실무에 필요한 핵심 구성 과정을 단계별로 안내합니다.

자체 호스팅 ntfy 서버의 역할

자체 호스팅 ntfy 서버는 HTTP POST 요청을 휴대폰의 푸시 알림으로 변환합니다. curl를 사용하여 메시지를 게시하면 Android 앱, iOS 앱, 브라우저 탭 또는 HTTP 연결을 유지할 수 있는 모든 곳으로 메시지가 전달됩니다. 별도의 클라이언트 라이브러리를 설치하거나 메시지 브로커를 실행할 필요가 없습니다.

ntfy는 토픽(topic)을 통해 메시지를 식별합니다. 토픽은 https://ntfy.example.com/alerts과 같이 URL 경로에 포함된 이름이며, 누군가 해당 토픽으로 메시지를 게시하는 순간 생성됩니다. 기본 설치 상태에서는 해당 이름을 아는 누구나 토픽을 읽고 쓸 수 있습니다. 이 때문에 프로젝트 공식 문서에서는 토픽 이름을 비밀번호에 비유합니다. 이러한 모델은 공개 ntfy.sh 서비스에는 적합하지만, 백업 실패 알림과 같은 중요한 정보를 다루는 서버에는 적합하지 않습니다. 따라서 이 가이드에서는 첫 메시지를 보내기 전에 인증 기능을 활성화합니다.

시작하기 전에 필요한 것

Ubuntu 24.04 또는 Debian 13이 설치된 VPS, Docker Engine 및 Compose 플러그인, 도메인 이름, 그리고 매우 적은 양의 RAM이 필요합니다. 도메인 이름 시스템(DNS) A 레코드를 생성하여 ntfy.example.com이 서버의 공인 IP 주소를 가리키도록 설정한 뒤, 다른 작업을 시작하기 전에 해당 도메인이 올바르게 해석되는지 확인하십시오.

dig +short ntfy.example.com
sudo ufw allow 80,443/tcp
sudo ufw status

dig 명령은 서버의 IP를 출력해야 합니다. 인증서 발급을 위해서는 호스트 이름이 A 또는 AAAA 레코드를 통해 서버로 공개적으로 해석되어야 합니다. Let's Encrypt의 기반 프로토콜인 ACME(Automatic Certificate Management Environment)가 HTTP 챌린지에 80번 포트를 사용하므로, 이 포트는 열려 있어야 합니다. ntfy 컨테이너 자체는 공인 포트를 직접 사용하지 않습니다.

ntfy 설정 파일 작성

Docker 이미지에는 설정 파일이 포함되어 있지 않으므로 직접 생성해야 합니다. 이 가이드의 이후 모든 명령어는 이 파일을 참조합니다. 먼저 컨테이너를 실행할 사용자 ID와 그룹 ID를 확인하십시오.

id -u
id -g
sudo install -d -o "$(id -u)" -g "$(id -g)" /etc/ntfy /var/cache/ntfy /var/lib/ntfy
sudo nano /etc/ntfy/server.yml
base-url: "https://ntfy.example.com"
listen-http: ":2586"
behind-proxy: true
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-login: true
enable-signup: false

이 중 4개의 줄이 핵심적인 역할을 합니다. base-url은 반드시 정확한 공개 HTTPS 주소여야 합니다. ntfy는 이 주소를 사용하여 첨부 파일 링크를 생성하고 자체 호스팅 iOS 푸시 알림을 발송하기 때문입니다. listen-http: ":2586"는 컨테이너 내부의 모든 인터페이스에 바인딩합니다. 이는 위험해 보일 수 있으나 올바른 설정입니다. 컨테이너는 고유한 네트워크 네임스페이스를 가지므로, 내부에서 127.0.0.1에만 바인딩하면 호스트에서 해당 포트에 접근할 수 없게 되어 Docker가 게시한 포트가 연결되지 않습니다. auth-default-access: "deny-all"은 전체 보안 정책을 결정합니다. 명시적인 권한 부여 없이는 누구에게도 읽기 및 쓰기 접근을 허용하지 않기 때문입니다. behind-proxy: true은 ntfy가 X-Forwarded-For 헤더에서 클라이언트 주소를 가져오도록 지시합니다. 이를 통해 리버스 프록시를 하나의 매우 바쁜 클라이언트로 간주하는 대신 실제 방문자 수를 기준으로 속도 제한(rate limit)을 적용할 수 있습니다.

enable-login: true를 설정하면 사용자가 웹 앱이나 API를 통해 로그인할 수 있습니다. enable-signup은 false로 유지하십시오. 개인 서버에서 누구나 계정을 생성할 수 있게 하는 것은 보안상 취약점을 만드는 행위이기 때문입니다.

sudo chown "$(id -u):$(id -g)" /etc/ntfy/server.yml
sudo chmod 600 /etc/ntfy/server.yml

Docker Compose로 ntfy 실행하기

이 내용을 /opt/ntfy/compose.yaml에 넣고, 1000:1000을 위에서 출력된 두 숫자 id -u 및 id -g로 바꿉니다.

services:
  ntfy:
    image: binwiederhier/ntfy:v2.36.0
    container_name: ntfy
    command: serve
    user: "1000:1000"
    environment:
      - TZ=UTC
    volumes:
      - /etc/ntfy:/etc/ntfy
      - /var/cache/ntfy:/var/cache/ntfy
      - /var/lib/ntfy:/var/lib/ntfy
    ports:
      - "127.0.0.1:2586:2586"
    restart: unless-stopped
cd /opt/ntfy
sudo docker compose up -d
sudo docker compose logs ntfy
curl -s http://127.0.0.1:2586/v1/health

정상적인 서버는 {"healthy":true,"role":"active"}으로 응답합니다. 해당 compose 파일에는 의도적인 두 가지 세부 사항이 있습니다. 이미지는 latest 대신 2026년 11월 1일 기준 최신 안정화 릴리스인 v2.36.0로 고정했습니다. latest을 사용하면 다음 docker compose pull가 현재 이미지를 다운로드하고, 이어지는 docker compose up -d가 해당 이미지로 컨테이너를 다시 생성하기 때문입니다. 단순히 pull만 해서는 실행 중인 서버 버전이 바뀌지 않습니다. 고정 태그는 여전히 업데이트가 필요합니다. 2026년 10월 한 달 동안만 10번의 릴리스가 있었습니다. 10월 7일 v2.29.0, 10월 12일 v2.30.0, 10월 16일 v2.31.0 및 v2.31.1, 10월 18일 v2.32.0, 10월 23일 v2.33.0 및 v2.33.1, 10월 24일 v2.34.0, 10월 30일 v2.35.0, 10월 31일 v2.36.0입니다. v2.31.0은 클라이언트가 메시지 캐시에 도달하기 전에 재연결할 때 메시지가 유실되던 문제를 수정했지만, since=<message ID>을 사용한 재연결 시 데이터베이스의 토픽 내 모든 메시지를 읽어오는 문제가 있어 ntfy.sh는 해당 버전을 롤백했습니다. v2.31.1은 새로운 인덱스로 해당 부하를 수정했고, v2.34.0은 취소되거나 삭제된 사용자가 일부 구독을 유지하던 문제를 수정했습니다. v2.35.0은 유효한 자격 증명을 익명으로 처리하는 동시 요청 문제와 SQLite에서의 Matrix 푸시 게이트웨이 권한 우회 문제를 수정했으므로, 이전 고정 버전은 v2.36.0로 옮기십시오. 포트는 127.0.0.1:2586:2586로 게시되므로 컨테이너는 호스트의 루프백 주소에서만 접근할 수 있습니다. 2586:2586라고 작성하면 Docker가 사용자의 규칙보다 앞서 자체 방화벽 규칙을 삽입하므로, ufw status에서 포트가 닫혀 있다고 표시되더라도 인터넷에서 포트가 응답하게 됩니다. 두 습관 모두 다음 컨테이너를 추가할 때도 이어집니다. 셀프 호스팅 RustDesk 릴레이도 같은 방식으로 이미지 태그를 고정하지만, 신호 및 릴레이 포트가 인터넷에서 응답해야 하므로 루프백 뒤에 숨을 수 없습니다.

curl이 Connection refused을 출력하면 컨테이너 로그를 읽어보십시오. /var/lib/ntfy/user.db에서 권한 오류가 발생한다면 user: 라인이 해당 디렉터리의 소유자와 일치하지 않는다는 의미이며, 이 경우 프로세스가 자체 데이터베이스를 생성하지 못하고 종료됩니다. VPS를 위한 Docker Compose 기초 가이드에서 볼륨 소유권과 재시작 정책을 더 자세히 다룹니다.

Caddy를 이용한 TLS 적용

Caddy는 인증서를 스스로 요청하고 갱신하므로, TLS(transport layer security)를 구현하는 가장 빠른 방법입니다.

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

/etc/caddy/Caddyfile의 내용을 다음 세 줄로 교체합니다.

ntfy.example.com {
    reverse_proxy 127.0.0.1:2586
}
sudo systemctl reload caddy
curl -s https://ntfy.example.com/v1/health

HTTPS를 통해 동일한 {"healthy":true,"role":"active"}에 접속하여 전체 경로가 정상 작동하는지 확인합니다. Caddy에서 502 오류가 발생한다면 보통 ntfy가 수신 대기 중이지 않은 상태이므로 sudo ss -lntp | grep 2586로 확인해야 합니다. ntfy가 정상적으로 수신 대기 중인데도 502이 지속된다면, Caddy 로그에서 연결 초기화와 같은 업스트림 오류를 확인하십시오. 인증서 오류는 대개 DNS 레코드가 잘못되었거나 인증 기관이 80번 또는 443번 포트로 서버에 접근할 수 없을 때 발생합니다. sudo journalctl -u caddy -n 50를 확인하여 검증 오류 내용을 파악하십시오. 나중에 다른 서비스를 추가하려면 동일한 Caddyfile에 호스트명 블록을 하나 더 작성하면 됩니다. 이러한 방식으로 Jellyfin 라이브러리를 위한 90년대 비디오 가게 스타일 프론트엔드, Halcyon과 같은 서비스를 동일 서버의 두 번째 서브도메인에서 운영할 수 있습니다.

이미 nginx를 사용 중이라면 ntfy 문서에 명시된 프록시 설정인 proxy_http_version 1.1, proxy_buffering off, proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for을 복사하고, 읽기 및 전송 타임아웃을 최소 3분 이상으로 설정하십시오. 구독자는 수신 대기하는 동안 하나의 HTTP 연결을 계속 열어둡니다. nginx의 기본 proxy_read_timeout은 60초이며 이는 두 읽기 작업 사이의 시간만을 계산합니다. ntfy는 중간 경로의 장비가 비활성 상태로 간주하여 연결을 끊지 않도록 기본적으로 45초마다 keepalive 메시지를 전송합니다(keepalive-interval). 따라서 조용한 구독자라도 기본 nginx 설정 뒤에서 연결이 유지됩니다. 더 긴 타임아웃 설정은 연결 유지를 위한 것이 아니라 여유 공간을 확보하기 위함입니다. keepalive-interval 값을 높일 경우, 반드시 프록시의 읽기 타임아웃 값보다 낮게 유지하십시오.

사용자 생성 및 토픽 권한 제한

인증 기능이 활성화되었으나 아직 아무도 접근할 수 없는 상태입니다. 이는 의도된 결과입니다. 관리자용 계정 하나와 스크립트용 머신 계정 하나를 생성하십시오. 이 명령어들은 컨테이너 내부에서 /etc/ntfy/server.yml을 읽어오므로, 설정 파일은 볼륨으로 마운트되어 있어야 합니다.

sudo docker compose exec ntfy ntfy user add --role=admin admin
sudo docker compose exec ntfy ntfy user add robot
sudo docker compose exec ntfy ntfy user list

각 user add 명령어는 비밀번호를 요구합니다. 관리자는 접근 제어 목록을 무시하며 모든 토픽을 읽고 쓸 수 있으므로, 해당 계정은 본인과 모바일 앱용으로만 사용하십시오. robot은 권한을 부여하기 전까지는 아무런 접근 권한이 없는 일반 사용자입니다.

sudo docker compose exec ntfy ntfy access robot alerts write
sudo docker compose exec ntfy ntfy access robot "alerts_*" write
sudo docker compose exec ntfy ntfy access

ACL(접근 제어 목록) 항목은 사용자, 토픽, 권한으로 구성됩니다. 토픽은 고정된 이름이거나 *를 포함한 패턴일 수 있습니다. 예를 들어 alerts_*는 alerts_backup과 alerts_db을 모두 포함하므로 호스트마다 명령어를 실행할 필요가 없습니다. write 권한은 게시(publish)만 가능함을 의미하며, 크론 작업에서 탈취된 토큰으로 구독(subscribe)하여 전송된 데이터를 읽어가는 것을 방지합니다. 특수 사용자명인 everyone는 인증되지 않은 방문자의 권한을 설정합니다. 기본값인 deny-all을 사용하면 ntfy access everyone status read과 같이 의도적으로 공개된 토픽을 운영할 때 주로 사용하며, 익명 방문자의 접근을 명시적으로 차단하는 규칙을 설정할 때 deny를 사용할 수도 있습니다.

스크립트는 비밀번호가 아닌 토큰을 사용해야 합니다.

sudo docker compose exec ntfy ntfy token add robot

이 명령어는 tk_으로 시작하는 토큰을 출력합니다. 토큰은 해당 사용자의 권한을 그대로 상속받으므로, 이 토큰은 alerts 토픽에 게시하는 작업만 수행할 수 있습니다. ntfy token list는 현재 존재하는 토큰 목록을 보여주며, ntfy token remove은 사용자의 비밀번호를 변경하지 않고 특정 토큰만 무효화합니다.

첫 메시지를 전송하여 잠금 기능이 작동하는지 확인하기

먼저 문이 닫혀 있는지 확인하는 것으로 시작합니다.

curl -s -o /dev/null -w '%{http_code}\n' -d "hello" https://ntfy.example.com/alerts

이 명령을 실행하면 403이 출력되며, 403이 올바른 응답입니다. auth-default-access: "deny-all"는 익명 게시를 거부하기 때문입니다. 이제 실제 메시지를 전송해 봅니다.

curl -H "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN" \
  -H "Title: Nightly backup finished" \
  -H "Priority: default" \
  -H "Tags: white_check_mark" \
  -d "42 GB copied in 11 minutes" \
  https://ntfy.example.com/alerts

서버는 저장된 메시지를 JSON 형식으로 응답하며, 이를 통해 메시지가 무시되지 않고 정상적으로 수락되었음을 알 수 있습니다. Title은 굵게 표시된 첫 번째 줄입니다. Priority은 1에서 5까지의 숫자나 min에서 urgent 사이의 이름으로 설정할 수 있으며, 휴대폰에서 알림음이 울릴지 여부를 결정합니다. Tags는 이름이 알려진 이모지 단축 코드와 일치할 경우 알림에서 이모지로 변환되며, 일치하지 않으면 일반 텍스트로 유지됩니다.

터미널에서 토픽을 모니터링하려면 스트림을 연결하십시오.

curl -s -u admin https://ntfy.example.com/alerts/raw

curl은 비밀번호를 요구합니다. 각 메시지는 한 줄씩 도착하며, 간헐적으로 나타나는 빈 줄은 연결 유지를 위한 신호입니다. 브라우저에서 https://ntfy.example.com를 열고 동일한 계정으로 로그인하면 웹 앱 버전의 동일한 스트림을 확인할 수 있습니다.

스크립트가 서버를 마비시키지 않도록 속도 제한 설정하기

기본적으로 각 방문자는 60개의 요청 버킷을 가지며, 5초마다 1개의 요청이 다시 채워집니다. 이는 개인 서버로서는 넉넉한 양이지만, 재시도 루프에 빠진 스크립트는 이를 모두 소진할 것입니다. server.yml에 제한을 추가하십시오.

visitor-request-limit-burst: 30
visitor-request-limit-replenish: "10s"
visitor-message-daily-limit: 500
sudo docker compose restart ntfy

제한을 초과한 방문자는 메시지를 전달받는 대신 HTTP 429를 받게 됩니다. 제한은 방문자 주소별로 계산되며, 이것이 behind-proxy: true이 매우 중요한 이유입니다. 이 설정이 없으면 ntfy는 Caddy의 주소만 보게 되어 모든 클라이언트가 동일한 방문자로 간주됩니다. 그러면 시끄러운 스크립트 하나가 휴대폰과 다른 서버들이 공유하는 버킷을 모두 소진하게 됩니다. v2.36.0부터는 일일 카운트가 사용자 데이터베이스에 저장되어 재시작 후에도 유지되며, 각 방문자의 허용량은 자정(UTC)이 아닌 개별적인 24시간 주기로 초기화됩니다.

실패한 cron 작업에 대한 알림

명령줄에 토큰을 노출하지 마십시오. ps aux는 시스템의 모든 사용자에게 실행 중인 모든 프로세스의 전체 명령줄을 보여주므로, -H으로 전달된 토큰은 curl이 실행되는 동안 모든 로컬 계정에서 읽을 수 있습니다. curl 설정 파일을 사용하면 이를 방지할 수 있습니다.

sudo install -d -m 700 /etc/ntfy-alert
printf 'header = "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN"\n' | sudo tee /etc/ntfy-alert/curlrc
sudo chmod 600 /etc/ntfy-alert/curlrc

이제 작업을 래핑하십시오. 이 내용을 /usr/local/bin/backup-with-alert.sh로 저장하고 chmod 750 권한을 부여하십시오.

#!/bin/bash
out=$(/usr/local/bin/backup.sh 2>&1)
code=$?
if [ "$code" -ne 0 ]; then
  printf '%s' "$out" | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
    -H "Title: backup.sh failed with exit $code" \
    -H "Priority: high" \
    -H "Tags: warning" \
    --data-binary @- \
    https://ntfy.example.com/alerts
fi
exit "$code"
17 3 * * * /usr/local/bin/backup-with-alert.sh >> /var/log/backup-alert.log 2>&1

$?은 명령 바로 다음 줄에서 캡처됩니다. 다음 명령이 실행되면 덮어쓰이기 때문입니다. ntfy는 최대 메시지 크기를 제한하며 알림은 로그 뷰어가 아니므로, 출력은 tail -c 1000를 거쳐야 합니다. 마지막의 exit "$code"는 원래의 상태 코드를 보존하므로, 이 작업을 감시하는 다른 프로세스도 여전히 실패를 인지할 수 있습니다. 스크립트가 /bin/false을 가리키도록 설정하여 한 번 실행해 보고 전체 과정을 테스트하십시오.

실행되지 않는 실패 분기는 아예 알림이 없는 것보다 나쁩니다. 침묵이 곧 성공을 의미한다고 오해할 수 있기 때문입니다. Cron은 작업에 거의 비어 있는 환경과 로그인 셸보다 훨씬 짧은 PATH을 제공합니다. 따라서 직접 실행할 때는 잘 작동하던 스크립트가 curl 줄에 도달하기도 전에 종료될 수 있습니다. cron 작업이 실행되지 않는 이유에 대한 가이드에서 이러한 환경적 함정을 다룹니다. 모든 경로를 절대 경로로 사용하고, 성공했다고 가정하기보다는 첫 번째 예약 실행 후 로그 파일을 직접 확인하십시오.

systemd 유닛 실패 시 알림 설정

Cron은 예약된 작업을 처리합니다. 장시간 실행되는 서비스에는 OnFailure=이 필요하며, 이는 유닛이 failed 상태가 될 때마다 systemd가 실행합니다. 템플릿 유닛 하나를 생성하여 서버의 모든 서비스에 재사용하십시오. 이 파일을 /etc/systemd/system/ntfy-unit-failed@.service로 저장합니다.

[Unit]
Description=Send an ntfy alert because %i failed

[Service]
Type=oneshot
ExecStart=/usr/local/bin/ntfy-unit-failed %i

그런 다음 /usr/local/bin/ntfy-unit-failed을 실행하고 모드를 750으로 설정합니다.

#!/bin/bash
unit="$1"
journalctl -u "$unit" -n 15 --no-pager -o cat | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
  -H "Title: $unit failed on $(hostname -s)" \
  -H "Priority: urgent" \
  -H "Tags: rotating_light" \
  --data-binary @- \
  https://ntfy.example.com/alerts

패키지 업그레이드로 인해 설정이 덮어쓰이지 않도록 드롭인(drop-in) 파일을 사용하여 서비스에 연결합니다.

sudo systemctl edit myapp.service
[Unit]
OnFailure=ntfy-unit-failed@%n.service

%n은 전체 유닛 이름으로 확장되므로, 인스턴스화된 유닛은 ntfy-unit-failed@myapp.service.service가 되며 템플릿 내부의 %i은 myapp.service를 스크립트의 첫 번째 인자로 전달합니다. 이 덕분에 하나의 템플릿으로 모든 유닛을 처리할 수 있습니다. 의도적으로 실패하도록 설정한 /etc/systemd/system/ntfy-selftest.service 유닛을 저장하여 작동 여부를 확인하십시오.

[Unit]
Description=Deliberately failing unit
OnFailure=ntfy-unit-failed@%n.service

[Service]
Type=oneshot
ExecStart=/bin/false
sudo systemctl daemon-reload
sudo systemctl start ntfy-selftest.service

시작 명령이 0이 아닌 값을 반환하며 종료되고 Job for ntfy-selftest.service failed because the control process exited with error code을 출력하면, 약 1초 후에 휴대폰으로 알림이 올 것입니다. 테스트가 끝나면 해당 테스트 유닛을 삭제하십시오.

주의해야 할 함정이 하나 있습니다. OnFailure=은 유닛이 failed 상태에 도달할 때만 실행되는데, RestartMode=direct는 자동 재시작 중에 해당 상태를 건너뛰므로 실패 핸들러도 실행되지 않습니다. 기본값인 RestartMode=normal을 사용하면 자동 재시작 시 실패 상태를 거치게 됩니다. StartLimitBurst과 StartLimitIntervalSec는 반복적인 시작 시도를 거부할 시점을 제어하므로, 충돌 루프가 결국 멈추도록 설정하십시오. 타이머는 위에서 언급한 cron 패턴을 대체하는 더 깔끔한 방법입니다. 타이머의 서비스 유닛도 동일한 OnFailure= 드롭인을 지원하기 때문이며, VPS에서 systemd 서비스와 타이머를 사용하는 방법 가이드에서 변환 과정을 상세히 다룹니다.

업타임 모니터를 동일한 토픽에 연결하기

Uptime Kuma, 셀프 호스팅 상태 모니터는 ntfy 알림 유형을 기본으로 제공합니다. Settings를 열고 Notifications, Setup Notification 순으로 이동한 뒤 Ntfy를 선택합니다. 서버 URL을 https://ntfy.example.com로, 토픽을 alerts로 설정하고 우선순위를 선택한 다음 robot 액세스 토큰을 붙여넣습니다. 잘못된 토픽 이름을 사용하면 해당 토픽을 포함하지 않는 write 권한에서 오류가 발생하므로, 저장하기 전에 테스트 알림을 먼저 발송하십시오.

이 구성의 현실적인 한계는 다음과 같습니다. 동일한 VPS에서 실행되는 모니터는 해당 VPS가 다운되었을 때 이를 알릴 수 없으며, ntfy는 ntfy 자체가 다운된 상황을 전달할 수 없습니다. 모니터는 다른 장비에서 실행하고, ntfy를 감시하는 모니터를 위해 이메일과 같은 두 번째 알림 채널을 추가하십시오. Uptime Kuma의 Push 모니터 유형은 다른 사각지대를 보완합니다. 크론 작업이 성공적으로 실행된 후 푸시 URL을 호출하도록 설정하면, 해당 호출이 중단될 때 Kuma가 경고를 보냅니다. 실패 분기는 작업이 실행될 때만 작동하므로, 시작조차 하지 못한 작업에 대해서는 아무런 정보를 제공하지 못합니다.

자체 호스팅한 ntfy는 Android와 iPhone에서 작동합니까?

Android에서는 아무런 제약 없이 작동합니다. Google Play나 F-Droid에서 앱을 설치한 뒤, 설정(Settings)을 열어 기본 서버를 https://ntfy.example.com로 지정하십시오. 사용자 관리 화면에서 계정을 추가하고 alerts를 구독하면 됩니다. 즉시 전송(Instant delivery) 기능은 포그라운드 서비스를 실행 상태로 유지하므로, 휴대폰이 절전 모드(doze mode)일 때도 메시지가 수신됩니다. 이때 표시되는 상시 알림은 버그가 아니라 포그라운드 서비스에 대한 Android의 요구 사항입니다. F-Droid 빌드에는 Firebase 코드가 전혀 포함되어 있지 않으므로, 모든 구독이 즉시 전송 방식을 사용합니다. ntfy는 Google 푸시 서비스의 개방형 대체제인 UnifiedPush 배포자 역할도 수행할 수 있어, UnifiedPush를 지원하는 다른 앱들도 귀하의 서버를 통해 메시지를 전달받을 수 있습니다.

공식 iOS 앱에서는 제거할 수 없는 한 가지 의존성이 존재합니다. iOS는 백그라운드 상태의 앱을 일시 중단시키며, Apple이 허용하는 백그라운드 모드(오디오 재생, 위치 업데이트 수신, 예약된 작업 처리 등)로는 앱이 서버의 메시지를 대기할 수 없습니다. 따라서 즉각적인 깨우기(wake-up)는 APNs(Apple push notification service)를 통해서만 가능합니다. 앱에 대해 인증된 자격 증명을 가진 제공자만이 메시지를 보낼 수 있으므로, 귀하의 서버가 공식 앱에 직접 도달할 방법은 없습니다. ntfy는 이를 릴레이 방식으로 해결합니다. 귀하의 서버가 메시지 ID를 포함한 poll_request을 ntfy.sh로 보내면, ntfy.sh가 이를 Firebase와 APNs를 통해 전달하여 앱을 깨우고, 이후 앱이 귀하의 서버에서 메시지 본문을 가져오는 방식입니다.

upstream-base-url: "https://ntfy.sh"

이 방식의 비용을 명확히 이해해야 합니다. 메시지 본문은 귀하의 서버에 남지만, 메시지가 도착했다는 사실과 해당 ID는 귀하가 운영하지 않는 인프라를 거쳐 전달됩니다. 이 설정을 사용하지 않으면 자체 호스팅 서버에서 iPhone으로 오는 알림이 결국 도착하기는 하지만, 앱을 즉시 깨울 방법이 없으므로 ntfy 문서에서는 지연 시간이 수 시간까지 발생할 수 있다고 경고합니다. ntfy.sh 릴레이 없이 네이티브 iOS 앱을 사용하려면, 귀하의 Apple 개발자 계정과 APNs 키를 사용하여 직접 앱을 빌드하고 배포해야 합니다. 이는 매년 비용이 발생하며 업데이트마다 앱을 다시 빌드해야 함을 의미합니다. 다른 방법으로는 iOS 16.4 이상에서 ntfy의 PWA를 사용하는 것입니다. 홈 화면에 추가하고 서버에서 Web Push를 구성하면 ntfy.sh 릴레이를 피할 수 있지만, 여전히 브라우저의 푸시 인프라를 사용하게 됩니다. 만약 릴레이 방식이 허용되지 않는다면, Android나 데스크톱 웹 앱에서 알림을 확인하십시오.

백업, 업그레이드 및 이미지 고정

재생성할 수 없는 두 경로는 /etc/ntfy/server.yml과 /var/lib/ntfy/user.db입니다. 두 번째 파일에는 모든 사용자, 비밀번호 해시, ACL 항목 및 토큰이 들어 있으므로 개인 키처럼 다루어야 합니다.

sudo tar czf ntfy-backup.tgz -C / etc/ntfy var/lib/ntfy
sudo chmod 600 ntfy-backup.tgz

해당 파일을 서버 밖으로 복사하십시오. cache.db에는 위에서 설정한 cache-duration에 따라 최근 12시간 분량의 메시지와, 추후 전달을 위해 예약된 메시지가 들어 있습니다. 예약된 메시지는 전달 후 12시간이 지나면 삭제됩니다. 메시지를 미리 예약하지 않는다면, 이 파일을 잃어버려도 보호할 가치가 있는 것은 없습니다. 업그레이드란 compose 파일의 태그를 수정하고, 이미지를 pull하고, 컨테이너를 다시 생성하는 것을 의미합니다.

sudo docker compose pull
sudo docker compose up -d
curl -s https://ntfy.example.com/v1/health

먼저 릴리스 노트를 읽어보십시오. SQLite 데이터베이스는 시작 시 마이그레이션되므로, 스키마 변경 후 이전 태그로 롤백하는 것은 안전하지 않습니다. 예를 들어 v2.31.1은 메시지 캐시를 스키마 버전 17로 옮겼으며, 업그레이드 노트에 따르면 v2.31.0 이하로 다운그레이드하려면 해당 버전을 수동으로 16으로 되돌려야 합니다. v2.36.0으로 업그레이드하면 모든 사용자의 기존 일일 카운트가 한 번 초기화됩니다. 새 버전이 하루 동안 정상 작동할 때까지 방금 만든 백업을 보관하십시오. 노트에는 동작 변경 사항도 표시되어 있습니다. v2.31.0부터는 since=<message ID>로 재연결하는 클라이언트도 같은 초에 게시된 메시지를 수신하므로 중복 메시지를 볼 수 있습니다. ntfy 앱과 웹 앱은 메시지 ID를 기준으로 중복을 제거하지만, 토픽을 재생하는 사용자 고유의 스크립트는 직접 중복 제거를 수행해야 합니다. 서버의 모든 서비스는 재생성할 수 없는 고유한 경로 목록을 가지고 있으며, PhotoPrism과 Immich 비교 문서에서 동일한 종류의 VPS에 있는 사진 라이브러리에 대한 해당 목록과 그에 따른 백업 명령을 확인할 수 있습니다.

Gotify 및 Apprise

Gotify는 더 가벼운 선택지입니다. 웹 UI와 Android 앱을 포함한 단일 바이너리로 구성되며, 애플리케이션별로 메시지를 정리합니다. Android만 대상으로 하는 개인용 서버에 적합합니다. Apprise는 Python 라이브러리이자 명령줄 도구이며, 별도의 Apprise API 서버도 제공합니다. 단일 메시지를 ntfy를 포함한 100개 이상의 서비스로 동시에 전송할 수 있어, 여러 곳에 알림을 보내야 하는 스크립트에 적합합니다. ntfy는 서버, HTTP API, 양대 모바일 플랫폼용 앱을 모두 제공합니다. 이러한 이유로 임대 서버에서 알림을 보낼 때 가장 일반적으로 선택되는 솔루션입니다.

FAQ

ntfy 서버에 게시할 때 403 오류가 발생하는 이유는 무엇입니까?

auth-default-access: "deny-all"가 server.yml에 설정되어 있으면 익명 게시가 거부되며, 이는 의도된 동작입니다. -u user:pass 또는 -H "Authorization: Bearer tk_..."을 사용하여 자격 증명을 전송하십시오. 이미 토큰을 전송하고 있는데도 403 오류가 발생한다면, 해당 사용자의 ACL 항목에 해당 토픽에 대한 쓰기 권한이 있는지 확인하십시오. 일치하는 항목이 없으면 read-only 또는 deny에 의해 게시가 거부됩니다. v2.34.0 버전에서는 동일한 IP에서 발생하는 동시 요청으로 인해 유효한 자격 증명이 익명으로 처리될 수 있습니다. v2.35.0 버전에서 이 버그가 수정되었으므로, 간헐적인 403 오류를 ACL 문제로 단정 짓기 전에 업그레이드하십시오. ntfy access을 실행하여 전체 목록을 출력할 수 있습니다. write 권한은 구독을 허용하지 않으므로, 게시 권한이 있는 계정이라도 동일한 토픽을 읽으려 하면 거부된다는 점을 유의하십시오.

자체 호스팅 ntfy 서버를 사용할 때 iPhone에서 알림이 작동합니까?

공식 iOS 앱을 사용하면 릴레이를 통해 알림이 작동합니다. 일시 중단된 iPhone 앱을 즉시 깨우려면 APNs(Apple push notification service)를 거쳐야 하며, 공식 앱으로 전송하려면 해당 게시자의 푸시 자격 증명이 필요합니다. 따라서 ntfy는 메시지 ID가 포함된 poll_request을 ntfy.sh로 전달하고, ntfy.sh가 이를 기기로 릴레이합니다. upstream-base-url: "https://ntfy.sh"을 server.yml에 설정하고 컨테이너를 재시작하십시오. 메시지 본문 자체는 여전히 귀하의 서버에서 가져옵니다. 이 설정을 하지 않으면 iOS 알림이 결국 도착하기는 하지만, ntfy 문서에 따르면 지연 시간이 몇 시간까지 길어질 수 있다고 경고합니다. 서버에 Web Push가 구성된 경우 iOS 16.4 이상에서는 PWA가 또 다른 대안이 될 수 있습니다.

cron 작업의 ntfy 알림이 도착하지 않는 이유는 무엇입니까?

먼저 curl 명령어를 단독으로 실행하여 토큰과 토픽이 올바른지 확인하십시오. 수동으로 실행할 때는 잘 작동하는데 cron에서만 실패한다면, 문제는 알림 이전 단계에 있습니다. cron은 최소한의 환경과 짧은 PATH으로 작업을 실행하므로, 명령어 이름을 그대로 사용하는 스크립트는 curl 라인에 도달하기 전에 종료될 수 있습니다. 절대 경로를 사용하고, 작업의 출력을 로그 파일로 리다이렉트한 뒤 다음 실행 후에 해당 파일을 확인하십시오. 배달 대신 429 응답이 온다면 제한으로 인해 요청이 거부된 것입니다. 보통 스크립트가 너무 빠르게 재시도하는 경우이지만, 위에서 설정한 메시지 제한과 같이 일일 할당량을 모두 소진한 방문자의 경우 단일 요청이라도 동일하게 거부됩니다.

ntfy를 공용 인터넷에 노출해야 합니까?

휴대전화 앱은 모바일 네트워크에서 서버에 도달해야 하므로, auth-default-access: "deny-all"와 토픽별 ACL을 갖춘 공용 HTTPS 엔드포인트가 일반적인 구성입니다. 어떤 토픽도 everyone에 의해 읽기 가능하지 않다면 안전합니다. 모든 구독자가 직접 관리하는 기기라면 VPN 전용 인스턴스도 합리적입니다. 하지만 휴대전화의 경우 터널이 연결되어 있을 때만 앱이 메시지를 수신하므로, 휴대전화가 다시 연결될 때까지 알림이 대기하게 되어 적합하지 않습니다.

이 글이 도움이 되었나요?