b:eat 키오스크 · 실기 설치

실기 첫 설치 가이드

개발을 몰라도 따라 할 수 있도록, 처음 설치할 때 하는 일을 순서대로 정리했습니다. 단계마다 “이렇게 보이면 정상”이라는 확인 지점이 있습니다.

대상: 신규 실기 1대 관리자 PowerShell 필요 설치 버전: v1.2.12 권장 설치는 여러 번 실행해도 안전 갱신 2026-10-13 · v1.2.12 기준
★

먼저, 전체 그림

이 가이드는 “처음 한 번”만 다룹니다. 설치가 끝난 뒤의 업데이트는 실기가 알아서 합니다.

개발 PC

설치 파일(zip) 만들기

python-kiosk-vX.Y.Z.zip을 만듭니다.

사람이 함
CMS

업로드 + 매장 배치 등록

zip을 올리고, 어느 매장에 배포할지 등록합니다.

사람이 함
실기 (이 가이드)

처음 한 번 설치

bootstrap.ps1이 CMS에서 받아 설치합니다.

사람이 함
처음 한 번 — 위 7단계를 사람이 직접 합니다.
그 다음부터 — 매일 정기 재부팅 때 실기가 CMS를 확인해 자동으로 업데이트합니다. (아래 “설치 이후” 참고)
0

준비물 점검

설치 전에 아래를 확인하세요. 하나라도 빠지면 중간에 멈출 수 있습니다. 체크하면서 진행해도 됩니다.

0 / 10

사전에 받아 둘 것

실기에 이미 있어야 할 것

버전을 꼭 확인하세요. 자동 업데이트 기능은 v1.2.0부터 들어 있습니다. 그보다 낮은 zip을 설치하면 설치는 되지만 이후 자동 업데이트가 동작하지 않습니다. 또 메뉴 교환권 바코드(Code128)와 새 영수증 양식은 v1.2.12 이상이어야 제조 기기에서 읽힙니다.

설치 단계 보기

설치 명령과 다운로드 주소는 담당자에게 받은 접속 ID/비밀번호를 입력하면 나타납니다.

설치 중에 일어나는 일

4단계 명령을 실행하면 화면에 [1/4]부터 [4/4]까지 차례로 나옵니다.

1
버전 확인CMS에 이 매장의 최신 버전과 다운로드 주소를 묻습니다. (zip 방식이면 건너뜀)
2
Python 확인없으면 자동으로 내려받아 설치합니다. 있으면 그대로 씁니다.
3
앱 다운로드zip을 받고 SHA256으로 파일이 온전한지 검증합니다.
4
실기 세팅아래 5가지 작업을 하고 결과 표를 보여 줍니다.
[4/4] 실기 세팅 5가지
1기존 시작프로그램 정리 2원본 kiosk.exe 이름 변경 3보안 연결 환경변수 설정 4실행 환경 + 자동시작 등록 5키오스크 재시작
마지막 결과 표 읽는 법
OK이미 되어 있었습니다. 문제 없음.
변경됨이번에 새로 적용했습니다. 정상.
건너뜀할 필요가 없어서 넘어갔습니다. 정상.
실패그 줄의 설명을 캡처해 개발자에게 전달하세요.
설치는 멱등(여러 번 실행해도 같은 결과)입니다. 이미 된 단계는 건너뛰므로, 중간에 실패했다면 문제를 고친 뒤 같은 명령을 다시 실행하면 됩니다.

설치 이후: 알아서 업데이트됩니다

설치 뒤에는 사람이 할 일이 없습니다. 실기가 매일 정해진 시각(기본 새벽 2시)에 재부팅하면서 새 버전이 있는지 스스로 확인합니다.

재부팅 직후, 키오스크가 뜨기 전에
① CMS에 확인“지금 버전 v1.2.12인데 새 게 있나요?”
→
새 버전 없음바로 정상 시작
② 새 버전 있음“업데이트 중입니다” 화면이 1~3분 표시
→
받기 → 검증 → 교체이전 버전은 백업해 둠
→
새 버전이 뜨는지 시험
③ 성공새 버전으로 시작 + CMS에 성공 보고
③′ 실패이전 버전으로 되돌려 정상 시작 + CMS에 실패 보고
인터넷이 안 되면?

확인을 건너뛰고 지금 버전으로 그대로 시작합니다. 업데이트 때문에 키오스크가 못 뜨는 일은 없습니다.

동작 기록은 어디에?

C:\python-kiosk-real\kiosk_update.log 에 남습니다. 문제가 생기면 이 파일을 개발자에게 보내 주세요.

재부팅 시간을 바꾸려면?

관리자 화면(로고 7번 누르기) → 기본설정 탭의 정기 재부팅 시간에서 바꿉니다. 영업 시간과 겹치지 않는 시각을 쓰세요.

새 버전을 받은 날 영수증이 예전 모양이면?

바코드 글꼴이 새로 설치된 날은 재부팅 전까지 예전 양식입니다. 다음 정기 재부팅부터 새 양식으로 나옵니다.

막혔을 때

화면에 나온 문구를 눌러 해결 방법을 확인하세요.

2단계에서 로그인 창이 안 뜨거나 “401”, “권한이 없습니다”가 나와요
접속 ID/비밀번호가 틀렸습니다. 대소문자와 앞뒤 공백을 확인해 같은 명령을 다시 실행하세요. 계속 안 되면 담당자에게 새 ID/비밀번호를 요청하세요.
“스크립트 실행이 비활성화되어 있습니다” 오류가 나요
명령어에 -ExecutionPolicy Bypass가 들어 있는지 확인하세요. 위 “명령어 만들기”의 명령을 그대로 복사해서 쓰면 됩니다.
“매장코드를 알 수 없습니다”가 나와요
명령에 -StoreCode B0005(실제 매장코드)이 빠졌습니다.
“CMS 주소를 알 수 없습니다”가 나와요
C:\KIOSK.json 파일이 없는 실기입니다. 담당자에게 CMS 주소를 받아 명령 끝에 -BaseUrl 받은주소를 덧붙여 실행하세요.
“이 매장의 업데이트 배치가 없어…”가 나와요
CMS에 그 매장의 배치가 등록되지 않았습니다. CMS 운영자에게 배치 등록을 요청하거나, 개발자에게 zip을 받아 “받아 둔 zip으로 설치” 방식으로 하세요.
“sha256이 없어…”가 나와요
CMS에 올린 파일의 sha256 값이 비어 있습니다. CMS 담당자에게 등록을 요청하거나, zip으로 설치하세요.
C:\START.BAT 또는 kiosk.exe 단계가 “실패”로 나와요
효성 키오스크 환경이 아니거나 경로가 다른 실기입니다. 실제 경로를 -KioskExePath, -StartupBatPath로 지정해 다시 실행하세요. 시험용 PC라면 무시해도 됩니다.
Python 설치가 실패했어요
관리자 PowerShell인지, 인터넷이 되는지 확인한 뒤 같은 명령을 다시 실행하세요.
설치는 끝났는데 키오스크 화면이 안 떠요
C:\python-kiosk-real\kiosk_launcher.log 파일의 마지막 부분을 캡처해 개발자에게 전달하세요.
교환권 바코드 자리에 *1234* 같은 글자가 찍혀요 / 영수증이 예전 모양이에요
바코드 글꼴이 아직 프린터에 적용되지 않은 상태입니다. 먼저 재부팅을 한 번 하세요. 그래도 같으면 6단계의 셋째 명령(barcode font 로그 확인)을 실행해 not installed; skipped because this process is not elevated가 보이는지 보세요. 보이면 자동 시작 작업에 관리자 권한이 없는 상태이므로, 그 로그 줄을 캡처해 개발자에게 전달해 주세요.
업데이트 중 화면에서 멈춘 것 같아요
최대 몇 분 걸립니다. 20분이 지나면 자동으로 중단하고 지금 버전으로 시작합니다. 그래도 이상하면 kiosk_update.log를 개발자에게 보내 주세요.

되돌리고 싶을 때

설치는 파일을 지우지 않고 이동하거나 이름만 바꿨기 때문에 되돌릴 수 있습니다.

원본 화면 복구

kiosk.exe.orgi의 이름을 kiosk.exe로 되돌립니다.

자동시작 해제

C:\python-kiosk-real\deploy\device\register_autostart.ps1 -Unregister

원래 시작프로그램

시작프로그램 폴더 안 _disabled_by_python_kiosk_install 에 보관돼 있습니다.