현장 배포

한 현장에 TreeT를 세우는 큰 순서입니다. (설치 파일·상세 절차는 도입 시 제공되는 배포 패키지와 함께 안내됩니다.)

준비 사항 (역할별)

설치 전에 아래를 준비합니다. 역할별로 다른 기기를 쓰는 것이 기본이며, 규모에 따라 합칠 수도 있습니다.

역할	대수	준비할 것
CMS 서버	사이트당 1 (여러 사이트를 한 CMS로 운영 가능)	Ubuntu 26.04 LTS. Docker 는 설치 파일이 직접 설치합니다 → CMS 서버 설치
키오스크	사이트당 N (보통 10~30대)	Windows · Linux · Android 중 택일. 디스플레이와 유선 네트워크. 최저 사양: Windows 10 이상(64비트) · Linux 64비트(x86-64 · 라즈베리파이는 5 + 64비트 OS 에서 확인) · Android 7.0 이상
동기화 서버	멀티스크린 사용 시 1	Windows 10 이상(64비트) 또는 Linux 64비트(x86-64 · arm64). 별도 런타임 설치 불필요(단일 실행파일)
엣지 중계기	폐쇄망 현장만 1	Windows 11 22H2 이상, 내부망과 외부망 양쪽에 연결된 기기

폐쇄망 현장

키오스크가 외부망(CMS)에 직접 접속할 수 없는 현장에서는 엣지 중계기를 한 대 둡니다. 내부망과 외부망 양쪽에 연결된 이 기기만 외부와 통신하고, 키오스크는 이 기기만 바라봅니다. 엣지는 바깥으로 나가는 연결만 사용하므로 방화벽에 외부에서 들어오는 구멍을 뚫지 않아도 됩니다.

일반 현장(키오스크가 CMS에 직접 닿는 경우)에는 이 기기가 필요 없습니다.

CMS 서버 설치 위치

CMS는 OneDrive·Dropbox·Google Drive 같은 클라우드 동기 폴더에 설치하지 마세요. 설정 파일과 데이터베이스가 동기화 대상이 되어 충돌이나 파일 잠금이 발생할 수 있습니다. 고정된 로컬 경로 를 사용하세요 — 받은 꾸러미는 C:\treet 에 모으고, CMS 자체는 그 안의 설치 패키지를 Hyper-V 가상 머신(Ubuntu) 안으로 옮겨 설치합니다(CMS 서버 설치 참고).

열어야 하는 포트

방화벽·공유기를 설정할 때 쓰는 표입니다. 방향이 둘이라는 점을 먼저 보세요 — 대부분은 키오스크가 서버로 나가지만, 원격제어 하나만 반대로 들어옵니다.

키오스크 → 서버 (나가는 방향)

포트	무엇에 쓰나	붙는 상대	막히면
8443	CMS 보안 접속 — 등록·설정·편성·콘텐츠 다운로드	CMS(또는 MqttEdge)	화면이 새 편성으로 안 바뀝니다
8080	CMS 평문 접속 — https 를 안 쓰는 현장	CMS	〃
8883	MQTT(TLS) — 원격 명령·상태 보고	CMS 브로커(또는 MqttEdge)	원격제어·즉시 반영이 안 됩니다. 재생 자체는 계속됩니다
53000 부터	싱크 재생 — 싱크풀 하나마다 포트 하나	SyncServer	여러 화면의 재생이 어긋납니다

⚠️ https(8443)로 운영하는 현장은 8080 을 밖에 열지 않습니다 — 평문 입구라서입니다. 그러니 현장 밖(다른 망)에 있는 키오스크는 CMS 주소와 콘텐츠 주소를 둘 다 https://…:8443 으로 둡니다. 기기 설정에서 CMS 주소만 바꾸면 콘텐츠 주소는 CMS 가 따라 바꿔 줍니다 — 둘이 같은 입구였으면 https://…:8443/data 처럼 포트까지 옮깁니다.

⚠️ 안드로이드 7.0 이하 기기는 TreeTview Android 2026.9.135 이상이 필요합니다 — CMS 가 Let’s Encrypt 인증서를 쓰는 현장(https 8443)에서입니다. 그 기기들은 Let’s Encrypt 의 루트 인증서(ISRG Root X1)를 몰라서 CMS 를 믿지 못하고 접속하지 못합니다(실측: 갤럭시 노트4 · Android 6, 2026-09-22). 2026.9.135 부터는 앱이 그 루트를 직접 싣고 있어 붙습니다. 그보다 낮은 판이 깔린 기기는 CMS 에 붙지 못하므로 CMS 로는 업데이트할 수 없고, 새 판을 직접 설치해야 합니다.

⚠️ 53000 번대는 현장 안에서만 오갑니다 — 인터넷으로 나가지 않으므로 공유기에 구멍을 낼 필요가 없습니다. 풀을 추가하면 53001·53002… 로 하나씩 늘어납니다(CMS 가 빈 번호를 찾아 줍니다).

서버 → 키오스크 (들어오는 방향)

포트	무엇에 쓰나	막히면
5900	VNC 원격제어 — 그 화면을 직접 보고 조작합니다	원격제어 버튼이 안 열립니다

🔴 이 하나만 방향이 반대입니다. 다른 포트를 다 열어도 이걸 빠뜨리면 원격제어만 안 됩니다 — 그리고 나머지가 멀쩡하니 원인을 찾기 어렵습니다. 기기마다 다른 포트를 쓰면 기기관리 → 기기 페이지 머리의 기본 정보 고치기 → 원격접속 칸에 주소[:포트] 로 적습니다(관리자 이상).

관리자 쪽에서만 쓰는 포트 (키오스크와 무관)

포트	무엇
4822 · 8080	Guacamole 내부 통신
5500 · 5901	VNC 리피터(폐쇄망 구성에서 서버측·뷰어측)

🔵 데이터베이스 포트(3306)는 밖으로 열지 않습니다. 스택 안에서만 오갑니다.

MqttEdge 를 쓰는 현장

엣지가 있으면 키오스크는 엣지에만 붙고 CMS 에 직접 붙지 않습니다. 엣지가 현장 쪽으로 8883(MQTT)과 8443(콘텐츠 프록시)을 열고, 바깥으로는 엣지가 중앙으로 나가는 연결 하나만 있습니다.

⭐ 그래서 폐쇄망에서도 공유기에 들어오는 구멍을 낼 필요가 없습니다 — 엣지가 밖으로 나가는 방향이라서입니다.

순서

🔵 이 순서대로 하세요. 특히 2번과 3번을 바꾸면 안 됩니다 — CMS 주소는 재생기 화면에서 넣으므로, 재생기가 먼저 깔려 있어야 합니다.

1. CMS 설치 — CMS 호스트에 서버를 세우고 접속 주소(IP/도메인 + 포트)를 확정합니다. → CMS 서버 설치
2. 키오스크에 프로그램 설치 — 재생기(+ 감시자, 필요하면 동기화 서버)를 깝니다. → 아래 “키오스크 PC 에 설치하기”
3. CMS 주소 넣기 — 재생기 화면에서 F8. 감시자·동기화 서버는 설치할 때 넣거나(해당 판부터), 나중에 명령·파일로 넣습니다. → 아래 “CMS 주소 넣기” · “다른 프로그램도 CMS 주소가 필요합니다”
4. 🔴 들어갔는지 확인 — 재생기 로그의 [사이트설정] 확인 줄을 눈으로 봅니다. → 아래 “제대로 들어갔는지 확인하는 법”. 이 단계를 건너뛰면 뒤에서 원인을 못 찾습니다.
5. (HTTPS + IP 주소 현장만) 서버 인증서 신뢰 등록 — 아래 “주소를 IP로 쓰는 현장”.
6. 기기 등록 + 편성 — 주소가 맞으면 재생기가 스스로 CMS에 등록됩니다(기기 인증서도 자동으로 발급받습니다). CMS 관리 화면에서 콘텐츠·편성을 정합니다. 프로그램의 새 판은 CMS 의 업데이트 방식(자동 · 수동)에 따라 모든 기기가 같이 받습니다 (관리자 화면).

설치와 업데이트

프로그램마다 필요한 권한이 다릅니다. 설치 순서를 잡을 때 미리 알고 계셔야 합니다.

프로그램	설치 권한	설치 위치
TreeTview(재생기)	일반 사용자	그 사용자의 개인 폴더
🔴 SyncServer(동기화)	관리자	프로그램 폴더(공용)
🔴 Watchdog(감시)	관리자	프로그램 폴더(공용)
🔴 MqttEdge(폐쇄망 중계)	관리자	공용 폴더

Watchdog 이 관리자인 이유

화면보호기·절전 같은 그 기계 전체의 설정을 고쳐야 하기 때문입니다. 그래서 설치할 때 관리자 승인 창이 뜹니다 — 정상입니다.

🔵 설정 파일만은 운영자가 고칠 수 있는 자리(C:\ProgramData\TreeT\Watchdog)에 둡니다. 관리자 폴더에 두면 값을 바꿀 때마다 승인이 필요해집니다. ⚠️ C:\ProgramData 는 숨김 폴더라 탐색기에 안 보입니다 — 주소창에 C:\ProgramData\TreeT\Watchdog 를 그대로 입력해 엽니다.

🔵 SyncServer 도 관리자 설치입니다 — 로그인하기 전에도 떠 있어야 해서 부팅 때 시스템 계정으로 뜹니다. 설정 파일이 C:\Program Files\TreeT\SyncServer\SyncServer.json 이라 고칠 때는 메모장을 관리자로 엽니다.

일반 사용자로 설치하는 것은 재생기 하나이고, 계정마다 따로 설치됩니다 — 같은 PC를 여러 사람이 쓰면 그 사람 계정으로 로그인해서 설치해야 합니다.

업데이트 = 같은 설치 파일을 다시 실행

업데이트용 파일이 따로 있지 않습니다. 새 버전 설치 파일을 그대로 실행하면 기존 설치를 덮어씁니다.

이때 설정·인증서는 그대로 유지됩니다. 재설치 때문에 현장 설정을 다시 넣을 필요는 없습니다.

뷰어 화면에서 업데이트하기

설치 파일을 직접 실행하는 대신, 뷰어 화면에서 확인하고 설치할 수도 있습니다. CMS 가 그 기기에 내줄 새 판이 있으면(프로그램 판), 현장에서 이렇게 합니다:

1. 뷰어에서 F8 을 눌러 설정 화면을 엽니다.
2. 프로그램 업데이트 항목에서 [확인] 을 누릅니다 — 현재 버전과 상태가 보입니다.
3. 받을 것이 있으면 [지금 설치] 가 열립니다.

새 판은 운영시간 밖에 깔립니다 — 지금 깔려면 [지금 설치]

CMS 에 받을 판이 생겨도 기기는 곧바로 깔지 않습니다. 재생 중인 화면이 예고 없이 멈추지 않게 하기 위해서입니다. 그 기기 화면그룹의 운영시간이 끝날 때 스스로 깔고, 운영시간 밖이 없는 그룹(24시간 운영 등)은 CMS 설정 › 앱업데이트 의 업데이트 시각(기본 03:00)부터 60분 안에 깝니다.

기다리지 않고 지금 깔려면 [지금 설치] 를 누릅니다. 누르는 자리는 둘입니다:

어디서	어떻게
CMS 에서(여러 대 한꺼번에)	기기관리 → 기기를 고르고 → 선택한 기기에 명령 → 지금 설치
그 기기에서(한 대)	F8 → 프로그램 업데이트 → [확인] → [지금 설치]

설치가 시작되면 뷰어가 잠시 종료됐다가 새 버전으로 다시 뜹니다.

🔵 기다려도 되면 안 눌러도 됩니다. 위 때가 되면 그 기기가 스스로 깝니다. 실측으로 90초쯤 걸립니다. ⚠️ CMS 가 수동 업데이트로 돼 있으면 새 판이 먼저 승인돼야 합니다(CMS 의 [지금 업데이트]) — 승인 전에는 [지금 설치] 를 눌러도 깔 판이 없습니다.

⚠️ 누르고 나서 또 누르지 마세요. 한 번이면 됩니다 — 설치가 끝나면 기기가 스스로 다시 뜨면서 새 판을 보고합니다. 진행 중에 다시 눌러도 더 빨라지지 않습니다.

감시자·동기화 서버는 스스로 받아 깝니다

재생기와 달리 이 둘은 감시자가 CMS 에 물어보고 대신 깔아 줍니다. [지금 설치] 를 누르면 1분 안에 시작합니다.

⚠️ Watchdog 2026.9.43 보다 낮은 판이 깔린 PC 는 다릅니다 — 그 판 전에는 단추를 못 들어서 최대 6시간(감시자의 확인 주기)을 기다립니다. 급하면 그 PC 에서 감시자를 다시 시작하세요 (작업 스케줄러 → Watchdog → 끝내기 후 실행, 관리자). 시작할 때 바로 확인합니다.

⚠️ 설치 파일을 손으로 방금 돌렸다면 그 재시작이 안 먹습니다. 그때 도는 감시자는 설치 파일이 직접 띄운 것이라 작업 스케줄러가 관리하지 않습니다 — 끝내기가 “성공” 이라고 나와도 그대로 돌고 있습니다. PC 를 다시 켜면 정리됩니다.

출처가 다른 파일은 거부됩니다

받은 설치 파일은 서명과 체크섬을 확인한 뒤에만 설치합니다. 확인에 실패하면 그 파일을 버리고 설치하지 않습니다 — 설치가 거부되면 파일을 어디서 받았는지 먼저 확인하세요.

설치할 때 파란 경고 화면이 뜹니다 — 정상입니다

설치 파일을 실행하면 Windows 가 “Windows의 PC 보호” 라는 파란 화면을 띄우거나, 백신이 파일을 격리할 수 있습니다. 파일이 손상된 것이 아닙니다.

Windows 는 많은 사람이 설치해 본 파일을 신뢰하는데, 이 프로그램은 특정 현장에만 설치되는 소프트웨어라 그 횟수가 쌓이지 않습니다. 그래서 새 버전을 낼 때마다 다시 뜰 수 있습니다.

설치하려면: 파란 화면에서 추가 정보 → 실행을 누릅니다.

🔴 다만 아래를 먼저 확인하세요 — 경고를 그냥 넘기는 습관이 위험해지지 않도록:

• 파일을 저희가 안내한 경로에서 받았는지
• 파일 속성 → 디지털 서명 탭에 Jiseoan TreeT 가 있는지

⚠️ 백신이 파일을 지웠다면 담당자에게 알려 주세요 — 저희가 백신 제조사에 오탐 신고를 합니다. 그때까지는 예외 등록 대신 신고 결과를 기다리는 편이 안전합니다.

리눅스 기기의 업데이트 — 설치 프로그램이 없습니다

리눅스에는 윈도우 같은 설치 파일(.exe)이 없습니다. 설치본은 압축 파일 하나(.tar.gz)이고, 그 안에 파일마다의 검사값을 적은 목록과 그 목록의 서명이 함께 들어 있습니다. CMS 에서 새 판을 받는 방법(운영시간 밖 · [지금 설치])은 윈도우와 같습니다.

	윈도우	리눅스
받는 것	설치 파일(.exe)	압축 파일(.tar.gz) + 서명된 파일 목록
설치하는 방법	설치 파일을 조용히 실행	새 폴더에 풀고 폴더를 바꿔 끼움
확인하는 것	파일 서명	목록의 서명 + 파일마다 검사값
안 뜨면	사람이 봐야 합니다	스스로 옛 폴더로 되돌립니다

새 판이 안 뜨면 저절로 되돌아갑니다

재생기는 폴더를 바꿔 끼운 뒤 새 판이 실제로 떴는지를 봅니다. 화면이 살아 있으면 재생기가 10초마다 남기는 표시가 갱신되는데, 3분 안에 그 표시가 갱신되지 않으면 옛 폴더로 되돌리고 옛 판을 다시 띄웁니다. 실패한 폴더는 .failed 를 붙여 남겨 두므로 원인을 나중에 볼 수 있습니다.

되돌리기까지 실패하면 그때는 로그에 “사람이 봐야 합니다” 라고 남깁니다 — 그 줄이 보이면 현장에서 손으로 띄워야 합니다.

업데이트 도중 전원이 꺼져도 되살아납니다

폴더를 바꿔 끼우는 그 순간에 전원이 끊기면 설치 폴더가 비고 직전 판만 남을 수 있습니다. 감시자가 이 상태를 찾아 직전 판을 설치 자리로 되돌리고 재생기를 다시 띄웁니다. 그때 CMS 에 “바꿔 끼우는 도중 끊긴 뷰어 설치를 직전 판으로 되살렸습니다” 가 오류로 올라옵니다. 반쯤 남은 폴더는 .failed 를 붙여 남겨 둡니다.

설치 폴더도 직전 판도 없으면 감시자는 CMS 에 “사람이 봐야 합니다” 를 한 번 올립니다 — 그때는 현장에서 다시 깔아야 합니다.

라즈베리파이(arm64)는 파일이 따로 있습니다

같은 리눅스라도 일반 PC(x86-64)와 라즈베리파이(arm64)는 실행파일이 다릅니다. 파일 이름으로 구분합니다 — 이름에 -arm64 가 들어간 것이 라즈베리파이용입니다.

기기	받는 파일
리눅스 PC	TreeTview-linux-<판>.tar.gz · SyncServer-linux-<판>.tar.gz
라즈베리파이	TreeTview-linux-arm64-<판>.tar.gz · SyncServer-linux-arm64-<판>.tar.gz

⚠️ 다른 쪽 파일을 올리면 기기에서 뜨지 않습니다. 리눅스가 “실행 형식이 아닙니다” (Exec format error)라고만 말하고 끝나므로, 화면만 보고는 원인을 알기 어렵습니다. 설정 → 앱업데이트에 올릴 때 파일 이름을 한 번 확인하세요.

동기화 서버·감시자는 관리자(root) 로 돕니다

리눅스에서는 이 둘을 systemd 서비스로 깔기 때문에 업데이트도 감시자가 관리자 권한으로 합니다. 새 파일을 옆에 쓴 뒤 한 번에 바꿔 끼우고 서비스를 다시 시작합니다.

• 현장 설정 파일은 덮지 않습니다 — 주소 같은 값은 그대로 남습니다.
• 감시자가 자기 자신을 업데이트할 때는 스스로 끝내고, systemd 가 새 파일로 다시 띄웁니다.

키오스크 PC 에 설치하기

CMS 가 선 뒤, 화면을 띄울 키오스크 PC 마다 합니다.

설치 파일은 꾸러미의 설치파일\ 폴더에 있습니다(C:\treet\설치파일\) — CMS 설치 매뉴얼의 “시작하기 전에” 참고. 🔴 그 폴더를 통째로 키오스크 PC 로 옮겨 그 PC 에서 실행합니다 — 설치 파일은 자기가 있는 폴더를 기준으로 돕니다.

⚠️ 꾸러미의 TreeT_코드서명_공개인증서.cer 도 같이 가져가세요. 그것을 먼저 등록하지 않으면 자동 업데이트가 조용히 안 됩니다(위 “설치와 업데이트” 참고).

무엇을 설치하나요

순서	프로그램	꼭 필요한가
1	TreeTview — 화면을 띄우는 재생기	✅ 반드시
2	Watchdog — 재생기가 꺼지면 되살리고, 새 판을 대신 깔아 줍니다	✅ 권장 (무인 현장이면 사실상 필수)
3	SyncServer — 여러 화면을 한 박자로 넘길 때만	필요한 현장만
4	🔴 UltraVNC — CMS 에서 이 기기 화면을 들여다보려면	✅ 권장

SyncServer 는 CMS 가 몫을 나눠 줘야 화면을 받습니다

깔기만 해서는 안 됩니다. 몇 대의 화면을 함께 맞출 수 있는지(싱크 라이선스)는 CMS 가 정합니다 — 라이선스 총량 안에서 싱크서버마다 몫을 나눠 주고, 싱크서버는 그 수만큼만 화면을 받습니다.

순서 — 앞 단계가 끝나야 다음이 됩니다:

1. 그 PC 의 Watchdog 이 CMS 에 짝지어져 있어야 합니다(PC 당 한 번 승인 — 싱크서버는 따로 신청하지 않고 그 인증서를 같이 씁니다).
2. CMS 의 그 PC 기기 페이지 → SyncServer 탭 에서 이 싱크서버에 몫(동시 화면 수) 을 나눠 줍니다([싱크 라이선스 몫 바꾸기] — master 계정. 담당자에게 요청하세요).
3. 싱크서버가 몫을 받으면 기록에 싱크 라이선스: 동시 클라이언트 N대 가 남고, 그때부터 화면을 받습니다(보통 10초 안팎).

이런 줄이 보이면	뜻	할 일
[싱크 라이선스] CMS 에서 이 싱크서버에 배분된 싱크 라이선스가 0 입니다 — 기기관리에서 몫을 나눠 주세요	몫을 아직 못 받았습니다 — 화면을 하나도 받지 않습니다	2번을 합니다
클라이언트 접속차단! (싱크 라이선스 N대 초과 — CMS 에서 몫을 늘리세요)	몫보다 많은 화면이 붙었습니다 — 넘는 화면만 막힙니다	몫을 늘리거나 화면 수를 줄입니다
[싱크 라이선스] … 사이트 CA 가 없어 몫을 검증할 수 없습니다	몫이 정말 CMS 가 준 것인지 확인할 인증서를 못 찾았습니다 — 화면을 받지 않습니다	SyncServer 를 2026.9.52 이상으로 올리고, 그 PC 의 Watchdog 짝짓기(1번)가 끝났는지 봅니다

🔵 받은 몫은 그 PC 에 저장돼, CMS 가 잠시 안 닿아도 7일 동안은 그대로 돕니다. 🔴 세는 단위는 기기입니다 — 화면이 여럿인 기기(2분할 등)도 1대 입니다. 🔵 싱크를 안 쓰는 현장은 이 항목이 아예 필요 없습니다 — 위 표에서 “필요한 현장만” 인 이유가 그것입니다.

UltraVNC 는 우리 프로그램이 아닙니다

별도로 받아 설치하셔야 합니다. CMS 쪽 원격제어는 설치하면 바로 켜져 있지만, 보여 줄 화면을 내보내는 쪽은 이 기기에 있습니다 — 안 깔면 [원격 보기] 를 눌러도 화면이 안 나옵니다.

• 포트는 5900(기본값 그대로)
• 자동 시작되게 설정하세요(서비스로 설치)
• 비밀번호는 정하지 않아도 됩니다 — CMS 에서 단추를 누를 때마다 이 기기의 Watchdog 이 일회용으로 겁니다(Watchdog 2026.9.153 부터 · 그 판보다 오래된 Watchdog 은 사이트 공통 비밀번호를 쓰므로 Watchdog 을 새 판으로 올리세요)
• 주소 · 포트가 다를 때만 CMS 에 적습니다(기기관리 → 기기 페이지 → 기본 정보 고치기 → 원격접속 칸에 주소[:포트] — 관리자 이상)

Watchdog 은 관리자 승인 창이 뜹니다

설치 중 승인 창이 뜨는 것은 정상입니다(위 표 참고). 나머지 둘은 안 뜹니다.

TreeT 를 깐 PC 를 디스크 이미지로 복제하지 마세요

여러 대를 한 번에 준비하려고 TreeT 까지 깐 PC 의 디스크를 이미지로 떠서 다른 PC 에 붓지 마세요. 기기 신원 기록과 CMS 등록 정보까지 그대로 복사돼, 켜는 순간 원본 PC 의 등록을 빼앗을 수 있습니다.

• 이미지는 TreeT 를 깔기 전(윈도 · 드라이버 · UltraVNC 까지)에 뜨고, TreeT 는 PC 마다 따로 까세요.
• 이미 복제했다면 그 PC 를 켜 둔 채 두지 말고 TreeT 를 지운 뒤 다시 까세요. 기기 페이지에 [신원] 같은 PC 의 Watchdog 정본 신원과 다릅니다 가 보이면 이 경우일 수 있습니다.

Watchdog · SyncServer 는 설치 중에 CMS 주소를 묻습니다

설치 마법사에 CMS 주소 칸이 나옵니다. CMS 의 IP 나 이름을 적으세요(예: 192.168.0.10).

• 포트를 안 적으면 https://<적은 주소>:8443 으로 들어갑니다. CMS 를 http 로만 쓰는 현장은 이 칸을 비워 두고, 설치 뒤 아래 “다른 프로그램도 CMS 주소가 필요합니다” 의 명령에 --scheme=http 를 붙여 넣으세요.
• 비워 두면 기본값(127.0.0.1 — 이 PC 자신)이 남습니다. 그대로는 CMS 에 안 붙으니 설치 뒤 꼭 고칩니다.
• 다시 설치(업데이트)할 때는 묻지 않습니다 — 이미 넣은 주소를 지키기 위해서입니다.
• 🔴 이 주소는 CMS 화면에서 고칠 수 없습니다. 주소가 틀리면 CMS 와 연결이 끊겨, 고칠 통로가 사라지기 때문입니다.

무인 설치에서는 /CMSURL= 로 줍니다:

.\Watchdog_Setup_<판>.exe /VERYSILENT /CMSURL=192.168.0.10
.\SyncServer_Setup_<판>.exe /VERYSILENT /CMSURL=192.168.0.10

/CMSURL= 을 일부러 준 경우에만 업데이트 때도 주소가 바뀝니다.

작업표시줄 · 알림이 화면 위로 올라오지 않게

재생기가 전체화면(키오스크) 이면 작업표시줄보다 위에 떠 있습니다. 알림이나 다른 창이 잠깐 포커스를 가져가도 작업표시줄이 재생기 위로 올라오지 않습니다. 단축키로 전체화면을 빠져 창 모드가 되면 보통 창처럼 내려갑니다.

	윈도	리눅스(라즈베리파이)
재생기가 전체화면일 때	재생기가 작업표시줄 위를 덮습니다	화면 관리자(labwc)가 작업표시줄을 스스로 가립니다 — 재생기는 작업표시줄을 끄지 않습니다
알림	Watchdog 이 알림을 꺼 두고, 다시 켜지면 되돌립니다	—
터치 화면 가장자리 쓸기	키오스크 셋팅(Settings_All.cmd)이 끕니다 — 컴퓨터 전체 설정이라 Watchdog 은 어긋나면 보고만 합니다	—
켜진 직후	—	설치 때 돌리는 하드닝이 작업표시줄을 자동 시작에서 뺍니다
창 모드일 때	—	커서 숨김이 켜져 있으면 재생기가 작업표시줄을 끕니다(예비)

⚠️ 커서는 재생기 창 위에서만 숨겨집니다 — 재생기가 덮지 않는 화면(두 번째 모니터 등)에서는 보입니다(윈도 · 리눅스 같음).

🔵 재생기가 화면에 없으면 작업표시줄 · 커서가 보입니다 — 재생기를 끄거나(F4) 내리면(F11) 작업표시줄과 커서가 다시 나타나 그 PC 를 바로 쓸 수 있고, 재생기가 다시 나오면 사용자가 정한 대로(F9 · F10 으로 고른 것 — 정한 적이 없으면 둘 다 숨김) 돌아갑니다. 재생기가 갑자기 꺼진 경우에도 감시자(Watchdog)가 작업표시줄 · 커서를 되돌립니다.

설치한 뒤 확인할 것

재생기를 처음 켜면 스스로 CMS 를 찾아 등록합니다. 사람이 등록해 줄 필요가 없습니다.

CMS 관리 화면의 기기관리 목록에 그 기기가 나타나면 성공입니다.

안 나타나면 — 거의 항상 “주소” 입니다

재생기가 어느 CMS 를 볼지가 안 맞은 것입니다. 바로 아래 “CMS 주소 넣기” 를 하세요.

⚠️ 기기는 멀쩡히 켜져 있고 화면도 나옵니다. 안 되는 것은 CMS 와의 연결뿐이라, 겉만 보면 정상으로 보입니다.

설치 검사 돌리기 — check-install.ps1

꾸러미(C:\treet)에 설치가 제대로 됐는지 재는 스크립트가 같이 들어 있습니다. 화면에 그림이 나오는 것만으로는 안 보이는 것들을 봅니다.

설치는 “성공” 으로 끝나고도 틀릴 수 있습니다

“설치가 끝났습니다” 창을 보고 끝내지 마세요.

키오스크 PC 에서 PowerShell 을 열고 한 줄씩 돌립니다.

설치 전에 — 지금 값을 기준으로 남깁니다(이게 있어야 “설정이 보존됐나” 를 말할 수 있습니다):

powershell -ExecutionPolicy Bypass -File C:\treet\check-install.ps1 -Before

설치 후에 — 사후조건을 확인합니다:

powershell -ExecutionPolicy Bypass -File C:\treet\check-install.ps1 -After

-Before 를 안 남겼어도 -After 는 돌아갑니다. 다만 “지금 값이 이렇다” 까지만 말하고 무엇이 바뀌었는지는 못 말합니다.

이 도구는 고치지 않습니다 — 보고만 합니다

무엇을 봤는지가 현장 기록으로 남는 것이 목적입니다. 발견이 나오면 그 문구를 그대로 저희에게 전해 주세요.

CMS 주소 넣기 — 재생기 화면에서 (최초 1회)

재생기는 설치 직후엔 개발 기본값(127.0.0.1) 을 들고 있습니다. 그 PC 에서 한 번 넣어 주셔야 CMS 를 찾습니다. 손으로 하는 것은 이 한 번뿐이고, 그 뒤부터는 CMS 에서 바꿉니다.

키보드 단축키로 합니다 — 파일을 열 필요가 없습니다.

키	하는 일
F8	설정 화면을 엽니다 ← 여기서 CMS 주소를 넣습니다
F11	화면을 잠깐 내립니다(최소화)
F10	전체화면 켜기·끄기 — 고른 것을 기억합니다(다시 켜도 그대로)
F9	마우스 커서 · 작업표시줄 보이기·숨기기(리눅스 — 라즈베리파이 작업표시줄 포함) — 고른 것을 기억합니다
F4	재생기 종료

1. 재생기가 떠 있는 상태에서 F8 을 누릅니다.
2. CMS 주소 칸에 그 현장의 CMS 주소를 넣습니다 — 예: http://192.168.0.10:8080
3. 🔴 MQTT 사이트 칸도 같이 채웁니다 — CMS 설치 때 물어봤던 사이트 이름과 똑같이 (대소문자까지). ⚠️ 비워 두면 화면은 나오는데 원격 명령만 영영 안 옵니다 — 브로커가 토픽 권한으로 막고, 아무 오류도 안 뜹니다.
4. MQTT 주소 칸은 CMS 와 같은 기계면 CMS 주소의 호스트 부분만 (예: 192.168.0.10).
5. 저장하면 재생기가 그 주소로 CMS 를 찾아 스스로 등록합니다.

라즈베리파이 · 리눅스에 한글 글꼴이 없어도 설정 화면 · 부팅 화면의 한글 · 일본어 · 중국어가 보입니다 — 재생기가 글꼴을 함께 싣습니다. 폐쇄망에서도 인터넷에서 받지 않습니다.

단축키는 전체화면 중에도 먹습니다

키오스크로 전체화면이라도 F8·F11 은 동작합니다. 화면을 잠깐 치우고 다른 일을 하려면 F11, 다시 보려면 재생기 창을 고르면 됩니다.

파일을 직접 고치는 것은 마지막 수단입니다

설정 화면(F8)이 안 열릴 때만, 그 PC 의 %APPDATA%\TreeTview\config\setting.json 에서 path.baseUrl 한 칸을 고칩니다.

🔵 나머지 둘은 비워 두는 것이 정답입니다 — path.dataUrl 과 mqtt.host 는 비어 있으면 path.baseUrl 을 따라갑니다. 세 칸을 따로 적으면 나중에 CMS 주소를 옮길 때 한 칸만 고치고 나머지를 잊게 되고, 실제로 그 사고가 났습니다(기기가 브로커에 한 번도 안 붙었습니다).

언제 적나	무엇
path.dataUrl	파일서버를 따로 둘 때만
mqtt.host	폐쇄망에서 엣지 브로커를 쓸 때만

🔴 그 PC 에서, 그 사용자로 고쳐야 합니다. 공유 폴더·다른 계정·원격 도구로 고치면 파일은 바뀌었는데 재생기는 못 보는 일이 실제로 있었습니다. 그래서 아래 확인 절차를 반드시 하세요 — 고쳤다는 사실이 아니라 재생기가 그렇게 읽었다는 사실이 근거입니다.

제대로 들어갔는지 확인하는 법 (건너뛰지 마세요)

재생기를 껐다 켠 뒤, 그 PC 의

%APPDATA%\TreeTview\logs\main_<오늘날짜>.log

를 열어 맨 아래쪽 [사이트설정] 줄을 보세요.

보이는 줄	뜻
[사이트설정] 확인 — CMS 주소·MQTT·CA 설정에 걸리는 것 없음.	✅ 통과
✗ CMS 주소가 아직 개발 기본값입니다 (http://127.0.0.1)	❌ path.baseUrl 이 안 들어갔습니다
✗ mqtt.host 가 아직 개발 기본값입니다 (127.0.0.1)	❌ mqtt.host 에 개발 기본값이 남아 있습니다. 🔵 고치는 법은 값을 넣는 것이 아니라 비우는 것입니다(그러면 baseUrl 을 따라갑니다). 폐쇄망 엣지를 쓸 때만 그 주소를 적습니다
✗ mqtt.site 가 기본값 "site" 입니다	❌ MQTT 사이트 칸이 비었습니다 — 원격 명령이 안 옵니다
· 사이트 CA 가 아직 없습니다	최초 등록 전이면 정상입니다(오류 아님)

🔴 주소가 틀렸을 때의 증상은 “고장” 처럼 안 보입니다. 화면은 전체화면으로 잘 뜨고, Watchdog 이 몇 분마다 재생기를 되살리기를 반복합니다. 겉보기엔 “켜져 있는데 내용만 안 나온다” 입니다. 위 로그 줄이 유일하게 정확한 신호입니다.

기기 인증서는 사람이 넣지 않습니다

재생기는 CMS 에 처음 등록할 때 스스로 열쇠를 만들고 인증서를 발급받아 저장합니다. 준비하거나 복사할 것이 없습니다 — 주소만 맞으면 나머지는 저절로 됩니다.

다른 PC 의 인증서를 복사해 넣지 마세요

인증서의 개인키는 그 기계에 묶여 잠겨 있습니다. 복사해 온 것은 열리지 않고, 더 나쁜 것은 자동 발급이 안 되는 진짜 이유를 가려 버립니다 — 파일이 있으니 겉보기엔 정상이라, 왜 CMS 에 안 붙는지 아무도 못 찾게 됩니다.

사람이 넣어야 할 수 있는 것은 https 현장의 사이트 CA 하나뿐입니다 (아래 “주소를 IP로 쓰는 현장” 참고).

다른 프로그램도 CMS 주소가 필요합니다

재생기만 고치면 끝이 아닙니다. 같이 깐 프로그램들도 각자 CMS 를 봅니다.

프로그램	고칠 파일	고칠 칸
Watchdog	C:\ProgramData\TreeT\Watchdog\watchdog.json	appCheck.cmsUrl
SyncServer (쓰는 현장만)	C:\Program Files\TreeT\SyncServer\SyncServer.json	cms.url
MqttEdge (폐쇄망 현장만)	설치 폴더의 conf.d\site.conf	중앙 브로커 주소

Watchdog 주소가 틀리면 “조용히” 업데이트가 멈춥니다

재생기는 멀쩡히 돌고 화면도 정상입니다. 안 되는 것은 CMS 에서 새 판을 배포해도 안 깔리는 것 하나뿐이라, 몇 달 뒤에야 “왜 아직 옛 판이지” 로 발견됩니다.

명령으로 고치는 법 — 파일을 열지 않고 주소 한 줄만 바꿀 수 있습니다. 관리자 PowerShell 에서 한 줄씩:

& "C:\Program Files\TreeT\Watchdog\Watchdog.exe" --configure 192.168.0.10
& "C:\Program Files\TreeT\SyncServer\SyncServer.exe" --configure 192.168.0.10

• 주소만 적으면 https://192.168.0.10:8443 이 됩니다. http 현장은 뒤에 --scheme=http 를 붙입니다(http://192.168.0.10:8080).
• 먼저 보기만 하려면 --dry-run 을 붙입니다 — 몇 곳이 바뀌는지만 말하고 쓰지 않습니다.
• 바꾸기 전 원본은 같은 폴더에 .bak 으로 남습니다.
• 옛 판의 Watchdog 은 이 명령이 watchdog.json 을 못 찾았습니다 로 멈춥니다 — 그때는 아래처럼 메모장으로 고칩니다.
• 명령이든 메모장이든, 바꾼 뒤 다시 시작해야 반영됩니다(아래 표).

메모장으로 고치는 법 — 메모장을 관리자로 열어 그 파일의 주소만 바꿉니다.

설치 직후 Watchdog 주소는 이 PC 자신을 가리킵니다

설치본이 깔아 두는 값은 "cmsUrl": "https://127.0.0.1:8443" 입니다. 127.0.0.1 은 그 키오스크 자신이라 거기엔 CMS 가 없습니다 — 현장 CMS 주소로 바꿉니다. 🔴 주소 뒤에 경로(예: /treetweb)를 붙이지 않습니다 — 붙이면 등록되지 않습니다.

포트는 두 칸에 미리 적혀 있습니다 — httpPort(평문 입구, 기본 8080) · httpsPort(보안 입구, 기본 8443). CMS 가 다른 포트를 쓰는 현장만 고칩니다. https 로 붙을 때(예: https://192.168.0.10:8443) caFile 은 비워 둡니다 — Watchdog 이 httpPort 로 CMS 에서 사이트 CA 를 한 번 받아 저장하고, 그 지문을 로그에 남깁니다. CMS 설정 화면의 사이트 CA 지문과 같은지 한 번 대조하세요.

watchdog.json 은 [ 로 시작하는 목록이고, 주소는 맨 첫 번째 { … } 묶음 안의 appCheck 에 있습니다. 그 한 줄만 바꾸고 나머지 값은 그대로 둡니다 — 특히 signerThumbprints 를 비우면 자동 업데이트가 꺼집니다. 아래는 CMS 가 192.168.0.10:8080 인 현장의 파일 전체입니다.

[
  {
    "autoHide": true,
    "updateLock": {
      "file": "%APPDATA%\\TreeTview\\update.lock",
      "maxHoldMinutes": 10
    },
    "startupDelayMs": 30000,
    "appCheck": {
      "cmsUrl": "http://192.168.0.10:8080",
      "caFile": "",
      "httpPort": 8080,
      "httpsPort": 8443,
      "tokenFile": "%APPDATA%\\TreeTview\\data\\device-token.json",
      "intervalMs": 600000,
      "autoApply": true,
      "downloadDir": "%APPDATA%\\TreeTview\\data\\update",
      "signerThumbprints": [
        "1CAE827334F20023B720E10A3460FEA788F2DD8B"
      ],
      "nodeHeartbeatInterval": 60000
    }
  },
  {
    "processName": "TreeTview.exe",
    "execPath": "%LOCALAPPDATA%\\TreeT\\TreeTview\\TreeTview.exe",
    "execArgv": [],
    "heartbeatTimeout": 30000,
    "scheduledTask": "TreeTview"
  },
  {
    "processName": "SyncServer.exe",
    "execPath": "%ProgramFiles%\\TreeT\\SyncServer\\SyncServer.exe",
    "execArgv": [],
    "program": "SyncServer"
  },
  {
    "processName": "mosquitto.exe",
    "execPath": "C:\\ProgramData\\TreeT\\MqttEdge\\vendor\\win64\\mosquitto.exe",
    "execArgv": ["-c", "mosquitto.conf"],
    "workingDir": "C:\\ProgramData\\TreeT\\MqttEdge",
    "program": "MqttEdge",
    "logFile": "logs/mosquitto.log"
  }
]

• 경로의 \\ 는 JSON 문법이라 두 개 그대로 둡니다.
• mosquitto.exe 묶음은 MqttEdge 가 없는 PC 에서는 Watchdog 이 알아서 건너뜁니다 — 지우지 않아도 됩니다.
• 저장할 때 인코딩은 UTF-8 입니다.

SyncServer 는 cms 묶음의 한 줄입니다(여기엔 /treetweb 가 원래 없습니다):

"cms": {
    "url": "http://192.168.0.10:8080",

바꾼 뒤 그 프로그램을 다시 시작해야 반영됩니다.

프로그램	다시 시작하는 법
Watchdog	작업 스케줄러 → Watchdog 작업 → 끝내기 후 실행(관리자)
SyncServer	작업 스케줄러 → SyncServer 작업 → 같은 방법. 또는 로그오프 후 로그온
TreeTview(뷰어)	작업 스케줄러 → TreeTview 작업 → 끝내기 후 실행. 감시자가 10초 안에 알아서 되살리기도 합니다

제대로 들어갔는지 확인 — Watchdog 은 시작할 때 자기 로그에 주소를 찍습니다:

C:\Program Files\TreeT\Watchdog\logs\server_<오늘날짜>.log

보이는 줄	뜻
업데이트 확인 시작 (10분 주기, CMS http://192.168.0.10:8080)	✅ 그 주소로 보고 있습니다(주기 숫자는 intervalMs 에 따라 다릅니다)
업데이트 확인이 설정돼 있지 않습니다(watchdog.json 의 appCheck.cmsUrl)	❌ 칸이 비었습니다

CMS 에서 확인하는 것이 더 확실합니다 — 로그의 주소가 맞아도 경로(/treetweb)가 틀리면 등록은 안 됩니다. 기기관리 에서 그 PC 의 기기를 열면 기기 설정 탭의 이 PC 의 프로그램 에 Watchdog · SyncServer 가 1~2분 안에 올라오고, 마지막 응답이 방금 ~ 1분 전 이면 됐습니다(아직 PC 에 안 묶였으면 기기관리 목록 위 PC 미확인 프로그램 줄에 먼저 뜹니다). 안 올라오면 주소부터 다시 봅니다.

PowerShell(관리자)로 다시 시작할 때는 한 줄씩:

Stop-Process -Name Watchdog -Force

Start-ScheduledTask -TaskName Watchdog

Stop-Process -Name SyncServer -Force

SyncServer 는 Watchdog 이 곧 다시 띄웁니다 — 그래서 직후 대시보드에 “SyncServer.exe 이(가) 죽어 있어 다시 띄웠습니다” 가 한 줄 뜨는 것은 정상입니다.

재생기를 먼저 등록하세요

Watchdog 은 재생기가 등록 때 받아 둔 기기 토큰을 빌려 씁니다. 재생기가 아직 CMS 에 등록되지 않았으면 Watchdog 로그에 AUTH_TOKEN_REQUIRED 가 찍힙니다 — 이건 주소가 틀린 게 아니라 순서 문제입니다. 재생기부터 붙이면 저절로 풀립니다.

자동 시작

설치하면 그 PC 에 로그인할 때 자동으로 뜨도록 등록됩니다. 따로 하실 일이 없습니다.

무인 현장이라면 자동 로그인도 같이 보세요

재생기는 로그인한 뒤에 뜹니다. 정전 뒤 저절로 복구되려면 Windows 자동 로그인이 켜져 있어야 합니다 — 이건 OS 설정이라 우리 설치 파일이 건드리지 않습니다.

주소를 IP로 쓰는 현장 (HTTPS)

CMS 주소를 도메인으로 쓰면 공개 인증서를 쓸 수 있어 추가 작업이 없습니다. 반면 IP 주소로 접속하는 현장은 그 사이트 전용 인증서를 쓰기 때문에, 키오스크가 그것을 신뢰하도록 한 번 등록해 줘야 합니다.

등록할 때 지문을 눈으로 대조하세요

인증서를 받아 오는 통로 자체가 아직 보호되지 않은 상태라, 화면에 표시되는 지문(fingerprint)이 CMS 설정 화면에 적힌 값과 같은지 직접 확인한 뒤 수락해야 합니다. 이 대조를 건너뛰면 등록 절차의 보호 효과가 사라집니다.

등록은 도입 시 제공되는 도구로 처리하며, 현장 담당자는 지문 대조만 하면 됩니다.

개발 기본값 vs 현장 값

참고

방화벽/포트(웹 접속 포트, 실시간 제어·동기화 포트)와 멀티스크린 동기화용 라이선스는 현장 구성에 따라 추가로 확인합니다. 자세한 배포 상담은 TreeT 담당자에게 문의하세요.