<!-- canonical: https://docs.axelabs.ai/ops/runbook/cloudflared -->
<!-- source: content/ops/runbook/cloudflared.mdx -->

---
title: Cloudflared 재기동
description: cloudflared 가 죽었거나 config 변경 시 5초 다운타임 절차.
playbook: true
---

# Cloudflared 재기동

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/cloudflared 따라 axelabs-tunnel 재기동 진행해줘.

진행:
1. 현재 상태 진단 — `docker ps -a | grep axelabs-tunnel` + 외부 endpoint health (`curl -sI https://axe.axelabs.ai/frame/health`)
2. 페이지 시나리오 1 (죽음 감지) / 시나리오 2 (ingress config 변경) 중 분기 식별
3. 페이지의 각 명령 실행 + 검증, 매 step 결과 받고 다음. **절대 SIGHUP 금지** (cloudflared graceful reload 미지원) — docker restart 만 사용, 5초 다운타임 발생 사용자 사전 확인
4. 함정 — 본 runbook 은 axe-macmini 중앙 tunnel 만 다룸, customer 별 tunnel (`axelabs-{customer}`) 은 `axe onboard --apply` step 7 이 customer macmini 의 config 자동 push
5. 외부 endpoint 200 검증 + (선택) /ops/updates Ship Log
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

`axelabs-tunnel` (cloudflared) 가 죽거나 ingress config 변경이 필요할 때.

> **Tunnel layer 구분** (2026-05-23 정정): AXE 플랫폼은 **2 종류 cloudflared tunnel** 운용. 본 runbook 은 axe-macmini 의 **중앙 tunnel** (`axelabs-tunnel` 컨테이너 — `axe.axelabs.ai` / `docs.axelabs.ai` / `admin.axelabs.ai` 등 운영자 자기 서비스) 만 다룸. **customer 별 tunnel** (`axelabs-realchoice` 등 — `{customer}.axelabs.ai` 서빙) 은 `axe onboard` 가 customer macmini 의 launchd `com.axelabs.{customer}.cloudflared` 로 부팅하며 본 runbook 적용 안 됨. customer tunnel ingress 추가 시 `axe onboard --apply` 가 step 7 에서 자동 push.

## 절대 SIGHUP 금지

```
❌ docker kill -s HUP axelabs-tunnel
```

**검증된 사실 (2026-05-15)**: cloudflared 는 SIGHUP graceful reload **미지원**. SIGHUP 받으면 프로세스 종료.

→ docker restart 만 사용. 5초 다운타임 발생.

## 시나리오 1 — 죽음 감지

`com.axe.health-check` 또는 운영자 콘솔에서 cloudflared 죽음 감지:

```bash
# 상태 확인
docker ps -a | grep axelabs-tunnel
# Exited (1) 또는 Dead 표시

# 재시작
docker start axelabs-tunnel

# 5초 대기 후 검증
sleep 5
curl -sI https://axe.axelabs.ai/frame/health
# 200 OK
```

## 시나리오 2 — Ingress config 변경

신규 customer 추가 또는 path 추가 시:

```bash
# 1. config 편집
vim /Users/axe/.axe/tunnels/axelabs/config.yml

# 2. 검증
docker run --rm -v /Users/axe/.axe/tunnels/axelabs:/etc/cloudflared cloudflare/cloudflared:latest \
    tunnel --config /etc/cloudflared/config.yml ingress validate
# OK 면

# 3. 재시작 (다운타임 ~5s)
docker restart axelabs-tunnel

# 4. 새 ingress 동작 확인
sleep 5
curl -sI https://&lt;new-host&gt;/&lt;path&gt;
```

## 시나리오 3 — credentials 만료 / 회전

cloudflared 의 tunnel credentials (`d8efecdd-2c3f-42de-9925-501433e21394.json`) 는 일반적으로 만료 없음. 단, 의심 노출 시:

```bash
# 1. Cloudflare dashboard → Zero Trust → Networks → Tunnels → axelabs-tunnel → Configure → Rotate token

# 2. 새 credentials 파일 받아서 macmini 에 push
scp credentials.json axe-macmini:/Users/axe/.axe/tunnels/axelabs/

# 3. 재시작
docker restart axelabs-tunnel
```

## Ingress 변경 시 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| docker kill -s HUP | process 종료 | `docker restart` |
| frame upstream 을 cloudflared 에 직접 (host:port) | blue/green swap 불가 | axe-frame-proxy 경유 |
| path strip 기대 | 라우터에서 prefix 못 찾음 | 서비스에 `/frame` mount |
| catch-all (404) 라인 제거 | unhandled 호스트 가 임의 origin 으로 | 마지막 `service: http_status:404` 유지 |

## 다운타임 분산 운영

cloudflared 재시작 = **5초** 다운타임 (모든 customer 의 모든 서비스). 따라서:

- 가능한 한 **새벽 시간 (03:00 KST)** 에 수행
- 사전 알림 (customer admin 들에게 24h 전)
- 한 번에 여러 변경 묶어서 (재시작 1회 분량)

## 자동화 모니터링 (TBD)

현재는 운영자 콘솔 (`https://admin.axelabs.ai`, `com.axe.console.refresh` 매시 rebuild) 에서 health probe 결과 확인. 매분 단위 자동 알림 (`com.axe.health-check` launchd + `axe-health-monitor` script) 는 **향후 작업 항목**.

대안 (즉시 구현 가능):

```bash
# /Users/axe/.axe/bin/check-cloudflared.sh (TODO: 실제 launchd 등록)
if ! curl -sf https://axe.axelabs.ai/frame/health > /dev/null; then
    osascript -e 'display notification "cloudflared 또는 frame 죽음" with title "AXE Labs"'
fi
```

## 다른 cloudflared 인스턴스

축전된 다른 tunnel 들:

| Tunnel | 컨테이너 | ingress |
|---|---|---|
| axelabs-tunnel | `axelabs-tunnel` (Docker) | 플랫폼 (`*.axelabs.ai`) |
| cortex-tunnel | `com.cortex.cloudflared` (launchd) | cortex.axellc.com + mysrt.axellc.com |
| (기타 customer 측) | (각 customer macmini) | 각 customer 의 자체 |

각각 독립 운영. cortex-tunnel 죽음 ≠ axelabs-tunnel 죽음.