Files

PIN 기반 세션으로 관리자·발급기·표시판 3개 역할을 하나의 앱에서 운영.
Socket.IO 실시간 동기화, Podman Quadlet(10.89.0.25) 배포 구성 포함.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-26 10:56:15 +09:00

4.8 KiB

Raw Permalink Blame History

대기 번호표 시스템

실시간 대기 번호표 발급·관리·표시 웹앱입니다.
하나의 URL로 세 가지 역할(관리자 / 발급기 / 표시판)을 모두 운영합니다.

구조

관리자 디바이스   →  번호 호출 / 초기화
발급기 디바이스   →  고객이 번호표 수령
표시판 디바이스   →  호출 번호 대형 화면 표시

모든 디바이스는 PIN으로 같은 세션에 묶입니다.
같은 PIN이면 관리자 2대 + 표시판 2대처럼 여러 대를 동시에 운영할 수 있습니다.

시작하기

1. 첫 접속 (PIN 생성)

앱 URL에 접속하면 PIN 입력 화면이 나옵니다.

원하는 PIN을 자유롭게 입력합니다 (숫자 권장, 최소 4자리).
처음 입력하는 PIN은 자동으로 새 세션을 생성합니다.
접속 버튼을 누르거나 Enter를 치면 역할 선택 화면으로 이동합니다.

같은 PIN을 다른 디바이스에서 입력하면 동일한 세션에 합류합니다.

2. 역할 선택

역할	설명
⚙️ 관리자	번호 호출·초기화를 담당하는 직원용 화면
🎟️ 번호표 발급기	고객이 직접 번호를 뽑는 키오스크 화면
📺 번호 표시판	대기실에 띄워두는 대형 번호 화면

화면별 사용법

⚙️ 관리자 화면

![관리자 화면]

항목	설명
현재 호출 번호	지금 표시판에 표시 중인 번호
대기 중	아직 호출되지 않은 인원 수
발급 총계	지금까지 발급된 번호표 총 수

다음 호출 ▶ 버튼을 누르면

다음 번호가 호출됩니다.
표시판 화면이 즉시 업데이트됩니다.
대기 인원이 1 감소합니다.
대기자가 없으면 버튼이 비활성화됩니다.

번호 초기화 버튼을 누르면

확인 팝업이 뜨고 확인 시 모든 번호가 0으로 초기화됩니다.
발급기·표시판도 동시에 초기화됩니다.

역할 변경 버튼으로 역할 선택 화면으로 돌아갈 수 있습니다.

🎟️ 번호표 발급기 화면

고객이 직접 터치하는 키오스크 화면입니다.

화면 상단에 현재 대기 인원과 현재 호출 번호가 실시간으로 표시됩니다.
번호표 뽑기 버튼을 누르면 번호가 발급되고 초록색 박스로 표시됩니다.
발급 후에는 새 번호표 뽑기 버튼으로 다음 고객의 번호를 발급할 수 있습니다.
관리자가 번호를 호출하면 "앞에 N명 대기 중" 문구가 자동으로 업데이트됩니다.

📺 번호 표시판 화면

대기실 모니터에 띄워두는 화면입니다.

호출된 번호가 전체 화면 크기로 크게 표시됩니다.
새 번호가 호출될 때마다 노란색 플래시 애니메이션이 재생됩니다.
아직 호출된 번호가 없으면 -로 표시됩니다.
우측 하단의 역할 변경 버튼으로 돌아갈 수 있습니다.

다중 디바이스 운영

같은 PIN으로 접속하면 역할에 관계없이 몇 대든 연결 가능합니다.

예시: 2창구 운영

관리자 A (창구 1)  ─┐
관리자 B (창구 2)  ─┤  PIN: 1234  ─── 표시판 A (대기실 TV 1)
발급기             ─┤               ── 표시판 B (대기실 TV 2)

관리자 A, B 중 누가 "다음 호출"을 눌러도 표시판 A, B 모두 즉시 업데이트됩니다.
두 관리자가 동시에 누르지 않도록 운영 상 협의가 필요합니다.

배포 구성

항목	값
컨테이너 IP	`10.89.0.25`
내부 포트	`3000`
이미지	`localhost/queue-app:latest`
Quadlet	`/etc/containers/systemd/queue.container`
네트워크	`proxy.network`

빌드

cd /root/queue-app
npm install          # package-lock.json 생성
podman build -t queue-app:latest .

서비스 관리

# 시작
systemctl start queue.service

# 중지
systemctl stop queue.service

# 상태 확인
systemctl status queue.service

# 로그 확인
journalctl -u queue.service -f

업데이트 배포

cd /root/queue-app
podman build -t queue-app:latest .
systemctl restart queue.service

NPM(Nginx Proxy Manager) 설정

Proxy Host 추가 시 Websockets Support를 반드시 활성화해야 합니다.
Socket.IO 실시간 통신이 WebSocket 업그레이드를 사용하기 때문입니다.

Forward Hostname: 10.89.0.25
Forward Port: 3000
☑ Websockets Support

기술 스택

런타임: Node.js 20 (Alpine)
프레임워크: Express 4
실시간 통신: Socket.IO 4
상태 저장: 서버 메모리 (재시작 시 초기화)
컨테이너: Podman Quadlet (systemd 관리)

4.8 KiB Raw Permalink Blame History