TL;DR

  • ResolveHQ는 소규모 지원팀을 대상으로 Cloudflare Workers에서 실행되는 셀프 호스팅 헬프데스크이며, D1·R2·Queues·Email Routing·Resend를 조합해 티켓과 메일을 처리함
  • 테넌트 격리 고객, 티켓 배정·상태·우선순위·태그·전문 검색, 조직 간 워크스페이스 전환과 Owner/Admin/Agent 역할 관리를 제공함
  • RFC 5322 기반 메일 스레딩, 멱등 웹훅, 재시도·배달 상태·데드레터 큐, 검증된 R2 첨부파일 업로드로 메일과 파일 처리를 안정화함
  • 지식 베이스 기반 공개 헬프 센터, 리포트·CSV 내보내기, 규칙 기반 자동화, 저장 답변·내부 메모·옵트인 OpenAI 응답 초안 기능을 제공함
  • 소규모 배포는 사용량이 현재 Cloudflare Free 플랜 한도 내에 머무는 조건에서 실행 가능하며, 인증·메일 파싱의 CPU 사용량에 따라 Workers Paid가 필요할 수 있음

ResolveHQ

  • ResolveHQ는 소규모 지원팀을 위한 Cloudflare 네이티브 셀프 호스팅 헬프데스크임.

제공 기능

  • 테넌트가 격리된 고객 관리, 티켓 관리, 배정, 상태, 우선순위, 태그, 전문 검색을 지원하는 공유 받은편지함을 제공함.
  • 소유자로 가입하고 팀원을 초대하며, 조직 간 워크스페이스 전환기를 통해 Owner/Admin/Agent 역할을 관리함.
  • RFC 5322에 맞춰 메일을 정확하게 스레딩하며, 티켓 간 제목 위조에 대응함.
  • Cloudflare Email Routing으로 메일을 수신하고 Resend로 발송하며, 배달 상태·재시도·멱등 웹훅을 제공함.
  • 발신 답장에 연결된 첨부파일을 포함함.
  • 데드레터 큐를 내구성 있고 복구 가능한 레코드로 소진함.
  • 검증되고 권한이 부여된 R2 업로드를 통해 티켓에 파일을 첨부함.
  • 저장 답변, 내부 메모, 옵트인 방식의 인공지능 응답 초안, 낙관적 버전 충돌 처리를 지원하는 반응형 3열 받은편지함을 제공함.
  • 티켓 메일과 동일한 제공업체 연결을 통해 시스템 메일을 발송하고 비밀번호 재설정과 초대 수락을 처리함.
  • 지식 베이스 문서로 공개 헬프 센터를 게시하며, 초안은 팀에만 비공개로 유지함.
  • 리포트에서 처리량과 응답 속도를 추적하고, 임의 기간을 CSV로 내보내며, 규칙 기반 자동화로 분류를 자동화함.
  • 인앱에서 에이전트에게 배정과 고객 답장을 알리고, 라이트 모드와 다크 모드를 지원함.
  • 고객에 대해 저장된 모든 정보를 JSON으로 내보내거나, 대기 중인 메일을 취소하는 내구성 있고 재개 가능한 워크플로로 삭제함.
  • 5분마다 실행되는 크론 작업이 정체된 메일 작업을 재시도하고 스테이징 데이터와 고아 데이터를 정리해 자동 복구함.
  • 워크스페이스별 인공지능 지원을 제어함.
  • 관리자가 설정에서 활성화하기 전까지 기능이 꺼진 상태임.
  • 활성화한 뒤에만 티켓 대화가 OpenAI로 전송됨.
  • TICKET_RETENTION_DAYS를 설정하면 예약된 정리 작업이 해당 기간보다 오래된 해결·종료 티켓과 첨부파일을 영구 삭제함. 예시는 365일임.

인터페이스

  • 워크스페이스는 Slack에서 영감을 받은 가지색 사이드바, 셀프 호스팅 Lato 서체, Lucide 아이콘, Radix UI 프리미티브로 구성됨.
  • 테마 인식 컨트롤과 상태 색상이 라이트·다크 워크스페이스를 지원함.
  • 모바일에서는 하단 내비게이션과 키보드 접근이 가능한 워크스페이스 서랍으로 모든 목적지에 접근하며, 티켓 열 너비가 제목 가독성을 유지하도록 조정됨.
  • Cmd/Ctrl+K로 페이지 사이를 이동함.
  • 사이드바 도크에서 알림, 테마 전환, 계정 작업을 제공함.

작동 방식

  • ResolveHQ는 자체 계정의 단일 Cloudflare Worker로 실행됨.
  • Hono가 REST API와 빌드된 React 애플리케이션을 함께 제공함.
  • Cloudflare D1이 티켓과 고객을 저장하고, Cloudflare R2가 첨부파일을 저장하며, Cloudflare Queues가 수신·발신 메일 작업을 전달함.
  • Cloudflare Email Routing이 수신 메일을 Worker로 전달하고, Resend가 발신 메일을 전송함.
  • 티켓과 첨부파일은 자체 Cloudflare 계정에 저장되며, 발신 이메일 콘텐츠는 Resend를 통과함.

비용

  • 소규모 배포에서는 Workers, D1, R2, Queues, Cron Triggers, Email Routing의 현재 한도 내에서 사용량이 유지되는 조건으로 Cloudflare Free 플랜에서 실행 가능함.
  • CPU를 많이 사용하는 인증 또는 메일 파싱에는 Workers Paid가 필요할 수 있으므로 배포 환경의 벤치마크가 필요함.
  • Queues는 Workers Free에서 사용 가능함.
  • R2는 별도의 계정 활성화와 결제 설정이 필요함.
  • Resend는 자체 한도에 따라 발신 메일을 처리함.
  • 자세한 내용은 Free-plan audit에서 확인 가능함.

배포

  • 가장 쉬운 시작 방법은 위의 Cloudflare 배포 버튼을 사용하는 방식임.
  • 다음 항목이 필요함.
  • Cloudflare 계정이 필요하며, Workers Free에서 Queues를 지원함. R2는 별도로 활성화함.
  • Email Routing 설정을 위한 Cloudflare 도메인이 필요함.
  • 발신 메일을 보내려면 검증된 발신 도메인을 보유한 Resend 계정이 선택적으로 필요함.
  • 배포 후 ResolveHQ URL을 열고 소유자로 가입하며, 기본 받은편지함이 될 지원 이메일을 선택적으로 입력함.
  • Cloudflare 대시보드에서 해당 주소를 배포된 Worker로 전달하는 Email Routing 규칙을 추가한 뒤, 테스트 메일을 보내 받은편지함 도착 여부를 확인함.
  • 배포 흐름에서 프로비저닝하는 항목, 필수 설정, 최초 실행 설정, 수동 배포 방법은 배포 가이드에서 확인 가능함.

로컬 개발

  • npm install로 의존성을 설치함.
  • cp .dev.vars.local.example .dev.vars로 로컬 환경 변수 파일을 생성함.
  • npm run db:migrate:local로 로컬 데이터베이스 마이그레이션을 실행함.
  • npm run db:seed:local로 로컬 시드 데이터를 입력함.
  • npm run dev로 개발 서버를 실행함.
  • Vite 애플리케이션은 http://localhost:5173에서 실행되며, /api 요청을 http://localhost:8787의 Wrangler로 프록시함.

문서

  • 배포 및 설정
  • 아키텍처
  • 보안

선택적 설정

  • 인공지능 지원은 Worker 시크릿으로 OPENAI_API_KEY를 설정하면 사용할 수 있으며, OPENAI_MODEL은 선택 항목이고 기본값은 gpt-4o-mini임.
  • 각 워크스페이스는 설정에서 별도로 옵트인함.
  • 키가 없으면 기능이 숨겨지고 인공지능 호출이 발생하지 않음.
  • 보존 기간은 Worker 변수로 TICKET_RETENTION_DAYS를 설정해 해당 일수가 지난 해결·종료 티켓과 첨부파일을 자동 삭제함.
  • 값을 설정하지 않으면 자동 삭제가 발생하지 않음.

아직 구현되지 않은 기능

  • 다국어 인터페이스 및 앱 외부 알림인 이메일 다이제스트

라이선스

  • 자세한 내용은 LICENSE에서 확인 가능함.