GitHub Actions + Cloudflare Tunnel을 통한 Raspberry Pi CD 문제 해결

[Tae4an]

1. 개요

외부 포트가 차단된 Raspberry Pi 장비에 GitHub Actions를 통해 자동 배포를 구성하려 하였으며, 접속 경로로 Cloudflare Tunnel을 사용하였다. SSH 키와 호스트 도메인은 GitHub Secrets에 미리 등록해 두었음에도, 예상치 못한 인증 및 연결 오류가 발생하였다.

---

2. 증상

1. Cloudflared 실행 시 다음과 유사한 오류 발생:

   failed to start forwarding server: listen tcp: address [보안 식별자].access: missing port in address
   

2. 터널이 연결된 후에도 SSH 인증에서 다음 메시지가 출력되며 실패:

   Permission denied (publickey,password).
   

---

3. 원인 분석

✅ 문제 1. 잘못된 환경변수 매핑

• --hostname 인자에 **도메인 주소가 아닌 보안 식별자 (예: 클라이언트 ID)**가 들어감
• 결과적으로 Cloudflared가 잘못된 주소 형식(XXXXX.access)로 SSH 터널 연결을 시도하며 포트가 누락되었다는 오류 발생

🔧 해결

• CF_SSH_HOSTNAME → CLOUDFLARE_TUNNEL_HOSTNAME 등 명확한 이름으로 재구성
• 값은 반드시 ssh.example.com처럼 Cloudflare Access에 등록된 정식 도메인 주소로 설정해야 함

---

✅ 문제 2. SSH 키는 등록되어 있었으나, 참조 실패

• GitHub Secrets에는 개인 SSH 키(RASPBERRY_PI_SSH_KEY)가 정상 등록되어 있었음
• 그러나 워크플로우에서 SSH 키를 파일로 저장하거나, ~/.ssh/config 설정에 키 경로를 명시하는 과정이 누락 혹은 오류

🔧 해결

# SSH 키 저장 및 권한 설정
echo "${{ secrets.RASPBERRY_PI_SSH_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519

# SSH 설정 파일 생성
cat > ~/.ssh/config << EOF
Host raspberry-pi
  HostName 127.0.0.1
  Port 2222
  User ${{ secrets.RASPBERRY_PI_USER }}
  IdentityFile ~/.ssh/id_ed25519
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
EOF

---

4. 구조 변경: Cloudflare TCP 포워딩 방식 도입

항목	내용
cloudflared 실행	cloudflared access tcp --hostname ssh.example.com --url 127.0.0.1:22
SSH 연결 방식	ssh raspberry-pi → 실제로는 로컬 포트 2222에 연결
인증	등록된 개인 SSH 키로 수행 (~/.ssh/id_ed25519)

---

5. 교훈 요약

• 비밀 값은 변수 이름으로 명확히 구분하고, 유사한 값을 혼동하지 말 것
• 도메인 주소와 보안 식별자(클라이언트 ID, 터널 ID 등)를 혼동하면 SSH 터널 설정이 실패할 수 있음
• GitHub Actions에서 키 기반 인증을 사용할 때는 SSH 설정 파일 작성 및 키 파일 저장 경로를 명확히 지정해야 함
• Cloudflare Tunnel을 통한 SSH 연결에는 TCP 포워딩 방식이 더 안정적이며 디버깅이 수월함