Infra2026.09.11

VAPID 란?

collie의 VAPID 키와 subject를 설정하고 서비스를 재시작해 iPhone 푸시 수신까지 확인했다

• #VAPID
• #웹푸시
• #PWA
• #iOS
• #Tailscale

한 줄로

VAPID(Voluntary Application Server Identification)는 웹 푸시 규격이 요구하는 서버 신원 증명 키 쌍이다. 애플·구글 푸시 서버가 “이 알림을 보낸 게 정말 그 서버가 맞는지”를 검증하는 데 쓴다. collie에서는 이 키가 기본 생성되지 않아 직접 설정해야 했다.

왜 키가 자동으로 안 만들어지나

아이폰에서 회사 맥의 에이전트 세션을 원격 조작하려고 collie 라는 웹앱을 붙였는데, 푸시 알림 자리에 이 문구가 떴다.

서버에 VAPID 키가 구성되지 않아 푸시 알림이 비활성화되었습니다

원인은 단순하다. collie 가 VAPID 키를 기본 생성하지 않기 때문이다. 그리고 이건 빠뜨린 게 아니라 의도된 설계로 읽는 게 맞다.

VAPID는 애플·구글 푸시 서버가 발신자를 검증하는 데 쓰는 키 쌍이다. 이번 설정에서 확인한 것은 키 생성, subject 설정, 서비스 재시작 뒤의 발송 결과다.

설치만으로 알림 수신 설정이 끝나지는 않았다. VAPID 키 설정과 기기의 알림 허용을 각각 확인했다.

실제로 켜는 데 필요한 것

단계	결과
VAPID 키 쌍 생성	.config/collie/.env (권한 600)
subject(RFC 8292 필수)	mailto: 주소
서비스 재시작	키 로드 확인 ([push] enabled, pid 86580)
테스트 발송	collie push-test → ✓ sent "Collie 테스트" to 1 device(s)
구독 기기	iPhone, iOS 18.7, Safari 1대

여기서 걸리기 쉬운 건 subject 다. 노트에는 subject를 RFC 8292의 필수 항목으로 기록했고, 실제 설정에는 mailto: 주소를 넣었다. subject를 비웠을 때의 발송 결과는 확인하지 않았다.

키를 만든 뒤 서비스를 재시작해야 로드된다. 로그에 [push] enabled 가 뜨면 된 것이다. 그 전에 쌓인 [push] disabled 줄들은 키 생성 이전 기록이라 무시해도 된다 — 이걸 모르고 로그를 거꾸로 읽으면 여전히 안 켜진 줄 오해하기 쉽다.

--force 는 되돌릴 수 없다

⚠️ --force 로 키를 재생성하면 기존 구독이 전부 무효화된다. 모든 기기가 알림을 다시 켜야 한다.

키를 재생성한 뒤에는 모든 기기가 알림을 다시 켜야 한다는 점을 주의사항으로 남겼다. “뭔가 안 되니까 일단 키부터 다시 만들어 보자”는 흔한 대응인데, 여기서는 그게 문제를 키운다. 기기가 한 대라면 별일 아니지만 여러 대를 페어링해 뒀다면 전부 다시 붙여야 한다.

알림이 안 올 때 점검 순서

키를 제대로 넣었는데도 알림이 안 오면 이 순서로 본다.

1. iOS 설정 → 알림 → 해당 앱 허용 여부
2. 홈 화면 PWA 로 실행했는지 — iOS 는 사파리 탭에서 연 웹사이트에 푸시를 주지 않는다
3. 집중 모드

2번이 iOS 특유의 함정이다. 같은 URL 인데 사파리 탭에서 열면 푸시가 아예 안 오고, 홈 화면에 추가해 독립 앱처럼 실행하면 온다. 이번에는 collie push-test의 발송 로그와 iPhone 수신을 함께 확인했다. 발송 로그만으로 기기 수신까지 확인한 것으로 보지는 않는다.

이 푸시가 붙어 있는 구조

알림을 켠 이유는 원격 조작 때문이다. 구조는 이렇다.

아이폰 ──Tailscale──> 회사 맥 ──> 에이전트 세션 14개

tailnet only 라 공개 인터넷에 노출되는 지점이 없다. 이 도구를 고른 이유도 연결 방식이 컸다 — 후보 중 SSH 를 계속 붙들고 있어야 하는 쪽은 재연결 버그 이슈가 15건 올라와 있었고, 이쪽은 웹앱이라 끊길 연결이 애초에 없다. Tailscale 과 Bun 이 이미 깔려 있어 외부 서버를 경유하지 않는 것도 조건에 맞았다.

안전장치는 페어링 기기만 입력 가능(미페어링 기기는 읽기만), 모든 입력이 감사 로그에 기록, 텔레메트리 없음이다. 설치 스크립트 219줄을 전부 읽고 실행했고 sudo 가 필요 없었으며 체크섬을 이중으로 검증했다.

⚠️ 다만 폰에서 승인을 누르는 것은 회사 레포에 코드를 쓰도록 허가하는 것이다. 작은 화면에서는 diff 를 대충 넘기기 쉬우니, 급하지 않으면 데스크톱에서 확인하는 편이 낫다. 푸시 알림을 켠다는 건 이 승인 요청이 더 빨리 눈앞에 온다는 뜻이기도 하다.

정리

• collie는 VAPID 키를 기본 생성하지 않는다. 이번에는 직접 설정했다.
• subject는 RFC 8292의 필수 항목으로 기록했고, mailto: 주소로 설정했다.
• --force 재생성은 기존 구독을 전부 날린다. 마지막 수단으로만.
• 발송 로그와 함께 기기 수신도 확인한다. iOS 는 홈 화면 PWA 로 실행해야 푸시를 받는다.

자주 쓰는 명령은 이 정도다 (재부팅 시 launchd 로 자동 기동).

collie status      # 지금 상태
collie pair        # 기기 추가 (QR, 10분)
collie push-test   # 알림 테스트
collie logs        # 문제 생겼을 때
collie stop        # 잠시 끄기