CMS 서버 설치

사이트에 CMS 서버를 세우는 순서입니다. 전문 지식 없이 따라 할 수 있게 썼습니다 — 설치 파일이 준비 상태를 스스로 점검하고, 필요한 것은 직접 설치합니다.

준비물

• Windows PC 라면 Hyper-V 가상 머신부터 만듭니다 — 0번부터 보세요.
• 이미 Ubuntu 26.04 LTS 가 깔린 PC·가상 머신이 있다면 1번부터 하시면 됩니다. (메모리 6GB · 디스크 120GB 이상 권장 — 디스크는 콘텐츠가 쌓이는 자리입니다)
• Ubuntu 설치 이미지: ubuntu-26.04.x-live-server-amd64.iso (Server 판입니다)
• 도입 시 전달받은 설치 패키지 폴더 (USB 등으로 옮겨 놓습니다)
• 이 PC 가 붙을 네트워크 (인터넷은 설치에 꼭 필요하지는 않습니다 — 아래 참고)

시작하기 전에 — 받은 것을 한곳에 모읍니다

Windows PC 의 C:\treet 에 받으신 것을 전부 넣어 두세요. 폴더가 없으면 만드시면 됩니다.

받으시는 꾸러미는 이렇게 생겼습니다 — 폴더째 통째로 옮기세요.

C:\treet\
  읽어주세요.md                      ← 🔴 **먼저 읽으세요.** 이 현장의 값이 적혀 있습니다
  목록.md                            ← 들어 있는 파일과 sha256
  TreeT_코드서명_공개인증서.cer      ← 🔴 키오스크마다 **설치 전에** 등록합니다
  check-install.ps1                  ← 설치가 제대로 됐는지 재는 스크립트
  설치파일\                          ← 키오스크용 설치 파일들(+ 안드로이드 APK)
  CMS\treet-cms-offline-<판>.tar.gz  ← CMS 설치 패키지
  매뉴얼\                            ← 이 문서의 오프라인 사본
  키오스크셋팅\                      ← 키오스크 PC 최적화 스크립트

여기에 하나를 더 받아 같이 두세요 — 저희가 드리지 않습니다:

  ubuntu-26.04.x-live-server-amd64.iso   ← 가상 머신에 깔 Ubuntu (ubuntu.com 에서 받습니다)

C:\treet 는 규칙이 아니라 약속입니다

설치 파일은 자기가 있는 폴더를 기준으로 돕니다 — 어디에 두셔도 동작합니다. 그래도 한곳으로 정해 두는 이유는 두 가지입니다.

• 나중에 누가 봐도 같은 자리에 있습니다. 현장이 여럿이 되면 이 차이가 큽니다.
• 전화로 안내할 때 “그 폴더” 가 서로 같은 곳을 가리킵니다.

여기만은 피하세요

OneDrive·Dropbox·바탕화면 안에 두지 마세요. 동기화 폴더는 설정 파일과 데이터가 계속 동기화되면서 충돌·잠금이 나고, 바탕화면은 사용자 계정 안이라 다른 계정으로 로그인하면 안 보입니다. C:\treet 는 둘 다 아닙니다.

CMS 설치는 이 폴더에서 하는 것이 아닙니다

C:\treet 는 모아 두는 자리입니다. CMS 는 가상 머신(Ubuntu) 안에서 설치하므로, treet-cms-offline 폴더는 나중에 VM 안으로 옮깁니다(1번). 설치파일 안의 것들은 각 키오스크 PC 로 옮겨 그 PC 에서 실행합니다.

전체 흐름 한눈에 보기

처음이시면 이 지도를 한 번 보고 시작하세요. 위에서 아래로 한 번만 가면 끝납니다.

	무엇을	얼마나	누가 합니까
준비	받은 것을 C:\treet 에 모으기 (바로 위)	5분	사람
0	가상 머신 만들고 Ubuntu 설치	30~60분	사람
0-e	🔴 디스크 넓히기 — Ubuntu 가 절반만 씁니다	1분	사람
1	설치 패키지를 VM 안으로	5~10분	사람
2	sudo bash install.sh 실행	1분	사람
3	준비 상태 점검	자동	설치 파일
4	질문 세 개에 답	1분	사람
5	관리자 비밀번호 받아 적기	1분	사람
6	실제로 뜨는지 확인	자동(몇 분)	설치 파일
7	백업 켜기 — 설치가 자동으로 · 확인만	1분	설치 파일
7-b	이 PC 에 Watchdog 깔기 — CMS VM 이 멈추면 다시 켭니다	5분	사람
8	원격 접속 준비	필요할 때	사람
9	인터넷 주소·인증서 + 관리자 입구	20분	사람(토큰·브라우저 승인) + 스크립트

끝나면 이렇게 됩니다

브라우저에서 http://<이 PC 주소>:8080 으로 관리 화면이 열리고, 관리자로 로그인할 수 있습니다. 거기서 기기를 등록하고 콘텐츠를 편성합니다.

설치 파일이 알아서 하는 것과 사람이 할 것

3번과 6번은 읽고 지나가는 절입니다 — 설치 파일이 하고, 뭔가 하실 일이 없습니다. 나머지(준비 · 0 · 0-e · 1 · 2 · 4 · 5 · 7)가 사람 몫입니다.

🔴 그중 잊기 쉬운 둘: 0-e 디스크 넓히기(안 하면 나중에 원인을 못 찾습니다)와 7 백업 켜기(이 사이트의 인증서는 다시 만들 수 없습니다).

중간에 멈췄다면

설치 파일은 되돌릴 수 없는 일을 하기 전에 점검하고, 막히면 무엇을 어떻게 해야 하는지 화면에 적어 줍니다. 그 문장을 그대로 따라가시면 됩니다 — 이 문서로 돌아와 찾으실 필요가 없습니다.

0. 가상 머신을 만듭니다 (Hyper-V)

CMS 는 Ubuntu 가상 머신 안에서 돕니다. Windows PC 라면 먼저 그 VM 을 만듭니다.

왜 가상 머신인가요

CMS 는 Docker 로 도는데, 그 Docker 는 Linux 에서 돌아야 안정적입니다.

0-a. Hyper-V 를 켜고 외부 스위치를 만듭니다

제어판 → 프로그램 → Windows 기능 켜기/끄기 에서 Hyper-V 를 체크하고 재부팅합니다.

Hyper-V 가 목록에 없으면

Windows Home 판에는 없습니다. Pro 이상이 필요합니다. 또 BIOS 에서 가상화 (Intel VT-x / AMD-V)가 꺼져 있으면 켜야 합니다.

재부팅한 뒤 VM 보다 먼저 외부 스위치를 만듭니다. 키오스크들이 이 VM 에 붙으려면 VM 이 이 PC 의 실제 랜카드에 연결돼 있어야 합니다.

화면으로: Hyper-V 관리자 → 가상 스위치 관리자 → 새 가상 네트워크 스위치 → 외부 → 이름 TreeT-External → 이 PC 가 실제로 쓰는 랜카드를 고릅니다. ⚠️ 화면으로 만들었다면, 만든 뒤 아래 명령의 ③ DNS 확인·채우기를 꼭 따로 하세요(고정 IP 면 DNS 가 빠집니다).

명령으로(관리자 PowerShell) — 빠진 DNS 까지 한 번에 처리합니다:

# ① 랜카드 이름 확인 — 키오스크와 같은 망에 연결된 것(보통 '이더넷')
Get-NetAdapter -Physical | Format-Table Name, InterfaceDescription, Status, LinkSpeed

# ② 위 목록의 Name 을 넣습니다
$Switch = "TreeT-External"
$Nic    = "이더넷"

# 만들기 전에 지금 설정을 기억해 둡니다 — 고정 IP 이면 스위치를 만들 때 DNS 만 사라집니다
$Static = (Get-NetIPInterface -InterfaceAlias $Nic -AddressFamily IPv4).Dhcp -eq "Disabled"
$Dns    = (Get-DnsClientServerAddress -InterfaceAlias $Nic -AddressFamily IPv4).ServerAddresses
"고정 IP: $Static · 지금 DNS: $($Dns -join ', ')"

# 스위치 만들기 — 이미 있으면 건너뜁니다 (⚠️ 몇 초 네트워크가 끊깁니다)
if (-not (Get-VMSwitch -Name $Switch -ErrorAction SilentlyContinue)) {
    New-VMSwitch -Name $Switch -NetAdapterName $Nic -AllowManagementOS $true | Out-Null
}

# ③ DNS 확인·채우기 — 새 어댑터에 DNS 가 비어 있으면 채웁니다
#    고정 IP 면 DNS 가 따라오지 않고, 자동 IP 여도 바로 못 받아오는 경우가 있습니다.
#    그래서 고정/자동과 상관없이 **비어 있으면** 채웁니다.
$vEth = "vEthernet ($Switch)"
for ($i = 0; $i -lt 10 -and -not (Get-DnsClientServerAddress -InterfaceAlias $vEth -AddressFamily IPv4).ServerAddresses; $i++) { Start-Sleep 2 }
if (-not (Get-DnsClientServerAddress -InterfaceAlias $vEth -AddressFamily IPv4).ServerAddresses) {
    if (-not $Dns) {
        # 원래도 DNS 가 비어 있었다면 공유기(게이트웨이)와 공용 DNS 를 넣습니다
        $Gw  = (Get-NetIPConfiguration -InterfaceAlias $vEth).IPv4DefaultGateway.NextHop
        $Dns = @($Gw, "8.8.8.8") | Where-Object { $_ }
    }
    Set-DnsClientServerAddress -InterfaceAlias $vEth -ServerAddresses $Dns
    Clear-DnsClientCache
}

# ④ 확인 — 둘 다 나와야 합니다
Get-VMSwitch $Switch | Format-Table Name, SwitchType, NetAdapterInterfaceDescription
Get-DnsClientServerAddress -InterfaceAlias $vEth -AddressFamily IPv4 | Format-Table InterfaceAlias, ServerAddresses
Resolve-DnsName ubuntu.com -Type A | Select-Object -First 1 Name, IPAddress

고정 IP PC 에서 스위치를 만든 뒤 인터넷 이름이 안 풀리면 — DNS 가 빠진 것입니다

증상: 랜선도 IP 도 멀쩡한데 사이트 이름으로 접속이 안 되고, ipconfig /all 의 DNS 서버에 fec0:0:0:ffff::1 만 보입니다. 그건 실제 서버가 아니라 Windows 가 DNS 설정이 없을 때 넣는 자리표시자입니다.

고치기 — 위 ③ 을 다시 하거나, 직접 넣습니다(공유기 주소는 현장에 맞게):

Set-DnsClientServerAddress -InterfaceAlias "vEthernet (TreeT-External)" -ServerAddresses 192.168.0.1, 8.8.8.8
Clear-DnsClientCache
Resolve-DnsName ubuntu.com

⚠️ ping 으로 확인하지 마세요 — 공유기가 ICMP 를 막는 현장이 많아 멀쩡해도 실패합니다. DNS 서버에 닿는지는 Test-NetConnection 192.168.0.1 -Port 53 으로 봅니다. 🔵 VM 안의 Ubuntu 도 같이 막힐 수 있습니다 — 호스트를 고친 뒤 VM 에서 resolvectl query ubuntu.com 으로 확인하세요. 🔵 DHCP(자동 IP) 현장은 보통 새 어댑터가 DNS 를 받아오지만, 바로 비어 있는 경우도 있습니다 — 위 ④ 에서 비어 있으면 같은 방법으로 채웁니다.

내부·개인용 스위치를 고르면 키오스크가 못 붙습니다

종류가 External(외부) 인지 확인하세요. ⚠️ 만드는 순간 이 PC 의 네트워크가 몇 초 끊깁니다 — 원격으로 접속해 작업 중이면 연결이 끊길 수 있습니다.

0-b. VM 을 만듭니다

Hyper-V 관리자 → 새로 만들기 → 가상 머신.

항목	값	왜 이 값인가
세대	2세대	UEFI 부팅. Ubuntu 26.04 는 2세대가 기본입니다
메모리	6 GB (동적 메모리 끄기)	실측은 유휴 214 MB 지만, 설치·DB 임포트와 영상 변환에 여유가 필요합니다
프로세서	4 코어	영상 변환이 CPU 를 씁니다 — 여기 투자하는 것이 가장 체감됩니다
하드 디스크	120 GB · 동적 확장	프로그램은 작지만(약 200 MB) 미디어와 이미지가 쌓입니다. 동적이라 처음부터 120 GB 를 먹지 않습니다
네트워크	TreeT-External(0-a 에서 만든 외부 스위치)	키오스크들이 이 VM 에 붙어야 합니다
보안 부팅 템플릿	Microsoft UEFI 인증 기관	기본값(Windows)으로 두면 Ubuntu 가 부팅하지 않습니다

디스크를 작게 잡지 마세요

콘텐츠가 쌓이는 자리입니다. 나중에 늘릴 수는 있지만 VM 을 끄고 파티션까지 손봐야 합니다. 동적 확장이라 120 GB 로 잡아도 실제로 쓰는 만큼만 차지합니다.

마법사 대신 명령 한 번이 더 정확합니다

값을 하나라도 빠뜨리면 나중에 고치기 번거롭습니다. 0-a 의 스위치를 만든 뒤, 관리자 PowerShell 에서 아래를 붙여 넣으세요. Ubuntu 설치 이미지는 준비 단계에서 C:\treet 에 받아 둔 것을 찾아 씁니다.

$VM     = "treet-cms"
$Root   = "C:\treet\HyperV"          # VM 디스크 자리 — 받은 것을 모아 둔 C:\treet 아래
$Switch = "TreeT-External"
# 준비 단계에서 C:\treet 에 받아 둔 Ubuntu 설치 이미지를 찾습니다
$Iso    = (Get-ChildItem "C:\treet\ubuntu-26.04*-live-server-amd64.iso" | Select-Object -First 1).FullName
if (-not $Iso) { throw "C:\treet 에 Ubuntu 설치 이미지(ubuntu-26.04.x-live-server-amd64.iso)가 없습니다 — 먼저 받아 두세요" }

# VM 만들기
New-Item -ItemType Directory -Force -Path "$Root\$VM" | Out-Null
New-VM -Name $VM -Generation 2 -MemoryStartupBytes 6GB -NewVHDPath "$Root\$VM\$VM.vhdx" -NewVHDSizeBytes 120GB -SwitchName $Switch | Out-Null
Set-VMMemory    $VM -DynamicMemoryEnabled $false
Set-VMProcessor $VM -Count 4
Set-VM          $VM -AutomaticStartAction Start -AutomaticStopAction ShutDown

# Ubuntu 가 부팅되게 — 보안 부팅 템플릿 · 설치 이미지 · 부팅 순서
Set-VMFirmware $VM -SecureBootTemplate MicrosoftUEFICertificateAuthority
Add-VMDvdDrive $VM -Path $Iso
Set-VMFirmware $VM -FirstBootDevice (Get-VMDvdDrive $VM)

# 켜고 화면 열기
Start-VM $VM
vmconnect.exe localhost $VM

🔵 VM 이름은 treet-cms 로 통일합니다. 🔵 AutomaticStartAction Start 는 호스트가 켜지면 VM 도 뜬다는 뜻입니다 — 정전이 나도 사람이 안 가도 됩니다.

자주 막히는 두 곳

• TreeT-External 스위치를 찾을 수 없다 — 0-a 의 스위치를 아직 안 만든 것입니다. 스위치는 VM 보다 먼저 있어야 합니다. 앞선 시도로 C:\treet\HyperV\treet-cms\treet-cms.vhdx 만 남았으면 그 파일을 지우고 다시 만드세요.
• VM 이 부팅하지 않고 멈춘다 — 보안 부팅 템플릿이 Windows 용으로 남은 것입니다. MicrosoftUEFICertificateAuthority 가 Ubuntu 용입니다.

0-c. 설치 이미지를 붙이고 켭니다

🔵 위 명령으로 만들었다면 이미 붙어 있고 켜져 있습니다 — 0-d 로 넘어가세요.

마법사로 만들었다면: 받아 둔 ubuntu-26.04.x-live-server-amd64.iso 를 VM 설정의 SCSI 컨트롤러 → DVD 드라이브에 붙이고 시작합니다.

부팅이 안 되면 — 보안 부팅

2세대 VM 의 보안 부팅 기본 템플릿은 Windows 전용이라 Ubuntu 가 부팅하지 않습니다. VM 설정 → 보안 에서 템플릿을 “Microsoft UEFI 인증 기관” 으로 바꾸세요(위 명령의 -SecureBootTemplate 줄이 이것입니다).

0-d. Ubuntu 를 설치합니다

기본값으로 넘어가도 되지만, 두 곳만 신경 씁니다 — 고정 IP(+DNS) 와 OpenSSH.

① 네트워크 — VM 에 고정 IP 를 줍니다

키오스크들이 이 주소로 CMS 에 붙고, CMS 설치 때 인증서에도 이 주소가 들어갑니다. 바뀌면 키오스크가 끊기므로 고정 IP 로 둡니다.

먼저 주소를 정합니다 — 호스트 PC 와 같은 대역에서 안 쓰는 주소, 그리고 공유기가 자동으로 나눠 주는 범위(DHCP) 밖이어야 합니다. 호스트에서 ipconfig 로 대역과 공유기(기본 게이트웨이)를 확인하세요.

예	값
호스트 PC	192.168.0.4
공유기(게이트웨이)	192.168.0.1
이 VM 에 줄 주소	192.168.0.10 (현장에 맞게)

설치 화면에서 — Network configuration → eth0 → Edit IPv4 → Manual:

칸	값
Subnet	192.168.0.0/24
Address	192.168.0.10
Gateway	192.168.0.1
Name servers	192.168.0.1, 8.8.8.8
Search domains	비워 둡니다

Name servers 를 비워 두지 마세요 — 현장에서 가장 자주 막히는 곳

비워 두면 랜선도 IP 도 멀쩡한데 이름 해석만 안 돼서 아무것도 안 되는 것처럼 보입니다 — 원인이 안 보여서 오래 헤맵니다. 공유기 주소와 8.8.8.8 을 넣으세요. (사내 DNS 가 있으면 그것을 먼저.)

설치를 이미 끝냈다면 — VM 안에서 설정합니다. 랜카드 이름(보통 eth0)을 먼저 확인하세요.

ip -br link

sudo tee /etc/netplan/60-treet-static.yaml > /dev/null <<'EOF'
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: false
      addresses: [192.168.0.10/24]
      routes:
        - to: default
          via: 192.168.0.1
      nameservers:
        addresses: [192.168.0.1, 8.8.8.8]
EOF
sudo chmod 600 /etc/netplan/60-treet-static.yaml
sudo netplan try

🔵 netplan try 는 적용한 뒤 120초 안에 Enter 를 누르지 않으면 원래대로 되돌립니다 — 잘못 넣어 연결이 끊겨도 안전합니다. Enter 를 누른 뒤 확인합니다:

ip -4 addr show eth0 | grep inet
resolvectl query ubuntu.com

② Install OpenSSH server 를 체크하세요

VM 화면에서 직접 타이핑하는 것보다, 다른 PC 에서 접속해 작업하는 편이 훨씬 편합니다. 설치 패키지를 옮길 때도 씁니다.

설치가 끝나면 재부팅하고, 로그인해서 아래로 정한 고정 IP 가 붙었는지 확인합니다.

ip -4 addr show | grep inet

0-e. 🔴 설치 직후 반드시 — 디스크 넓히기

Ubuntu 설치 관리자는 디스크를 절반만 씁니다. 120 GB 를 줘도 실제로 쓰는 자리는 약 58 GB 입니다.

sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv
df -h /

df -h / 가 100 GB 이상을 보이면 됐습니다.

안 하면 나중에 원인을 못 찾습니다

“120 GB 를 줬는데 왜 벌써 차지?” 로 헤매게 됩니다. 지금 30초면 되고, 나중에는 서비스를 멈추고 해야 합니다.

Docker 는 설치하지 않으셔도 됩니다

install.sh 가 시작할 때 점검하고, 없으면 직접 설치합니다. ⚠️ 단 인터넷이 있어야 자동 설치가 됩니다. 폐쇄망이면 Docker 를 미리 넣어 두세요 — 점검이 그 상황을 구분해 알려줍니다.

여기까지 되면 아래 1번으로 갑니다.

1. 설치 패키지를 VM 안으로 옮깁니다

꾸러미의 CMS\treet-cms-offline-<판>.tar.gz 파일 하나를 VM 안으로 옮기고, 거기서 풉니다. VM 안에서 둘 자리는 고정된 로컬 경로입니다. 예: /home/사용자/

어떻게 옮기나요

셋 중 편한 것으로 하시면 됩니다.

• SSH 로(0-d 에서 OpenSSH 를 켜셨다면) — Windows 에서 scp C:\treet\CMS\treet-cms-offline-<판>.tar.gz 사용자@<VM주소>:~/
• USB 로 — VM 설정에서 USB 를 붙이거나, 호스트 폴더를 공유
• 네트워크 공유로 — Windows 폴더를 공유하고 VM 에서 마운트

🔵 파일 하나(1.3 GB) 라 폴더를 통째로 옮기는 것보다 훨씬 빠릅니다. 몇 분 걸립니다.

옮겼으면 VM 안에서 풉니다.

cd ~
tar xzf treet-cms-offline-*.tar.gz
cd treet-cms-offline

클라우드 동기화 폴더에 두지 마세요

OneDrive·Dropbox 같은 동기화 폴더 안에 두면 설정 파일과 데이터가 계속 동기화되면서 충돌이나 잠금이 생깁니다. 설치 파일이 이 상황을 감지하면 경고합니다.

2. 설치를 시작합니다

폴더 안에서 아래를 실행합니다.

sudo bash install.sh

sudo 로 실행하는 이유는, 준비가 안 된 항목(예: Docker)을 설치 파일이 직접 설치하기 때문입니다.

3. 설치 파일이 먼저 점검합니다 (읽고 지나가세요)

🔵 여기서 하실 일은 없습니다. 설치 파일이 알아서 봅니다 — 아래는 무엇을 보는지 알려 드리는 것이고, 막혔을 때 돌아와 찾으시라고 적어 둔 것입니다.

부족한 것이 있으면 무엇을 어떻게 해야 하는지 화면에 알려줍니다.

점검 항목	문제가 있으면
운영체제	Ubuntu 26.04 LTS 가 아니면 알려줍니다(진행은 됩니다)
이름 해석(DNS)	안 되면 원인까지 알려줍니다 — 아래 참고
인터넷 연결	폐쇄망이면 정상입니다(Docker 가 이미 있어야 합니다)
Docker	없으면 자동으로 설치합니다
시계	시각이 크게 틀리면 알려줍니다
디스크 · 메모리	부족하면 막습니다
포트	이미 쓰는 프로그램이 있으면 막습니다
파일 권한	지켜지지 않는 곳이면 알려줍니다(진행은 됩니다) — 아래 참고

고정 IP 를 쓰는 현장에서 가장 자주 막히는 곳

고정 IP 로 설정하면서 DNS 서버를 안 넣으면 이름 해석이 안 됩니다. 인터넷 선은 꽂혀 있는데 아무것도 안 되는 것처럼 보입니다.

설치 파일이 이 경우를 구분해서 알려주고, 고치는 방법도 함께 보여줍니다. /etc/netplan/ 안의 설정 파일에 아래를 넣고 sudo netplan apply 하면 됩니다.

      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]

이 PC 가 Hyper-V 가상 머신이면 호스트(Windows) 쪽에도 같은 함정이 있습니다 — 가상 스위치를 만들면 IP 는 옮겨가는데 DNS 는 따라오지 않습니다. 고치는 법은 0-a 의 “DNS 가 빠진 것입니다” 를 보세요.

윈도 드라이브 위에 설치하면 개인키가 보호되지 않습니다

리눅스가 윈도 드라이브를 빌려 쓰는 자리(/mnt/c, /mnt/d 등)에 설치하면, 그 자리는 파일 권한을 흉내만 냅니다. 설치도 되고 CMS 도 정상 동작하지만, 사이트의 개인키가 그 PC 의 다른 사용자에게 열려 있습니다.

특히 사이트 인증서 발급용 키가 그렇습니다 — 그 키는 다시 만들 수 없습니다(다시 만들면 이미 등록된 재생기가 전부 끊깁니다).

권합니다: 리눅스가 자기 디스크로 쓰는 자리(예: /home/사용자/…)에 설치하세요. 설치 파일이 이 상황을 알려주지만 막지는 않습니다 — 알고 고르셔야 합니다.

4. 세 가지를 물어봅니다

점검을 통과하면 아래 세 가지만 묻습니다. 나머지는 알아서 설정됩니다.

① 이 사이트의 이름

1) 이 사이트의 이름 (영문 소문자·숫자·하이픈).
   추천: kjr7zbs  ← 지금 사용 가능한 이름입니다
   >

추천된 이름을 그대로 쓰셔도 됩니다(엔터). 이 이름은 기기와 주고받는 신호를 구분하는 데 쓰입니다.

왜 뜻이 없는 이름인가요

사이트 주소로 공개 인증서를 발급받으면 그 이름이 공개 기록에 영구히 남습니다. 회사명이나 지점명을 쓰면 고객사 목록이 그대로 드러나므로, 뜻이 없는 이름을 씁니다.

② 이 CMS 에 접속할 주소

2) 이 CMS 에 접속할 주소입니다 — 재생기가 이 주소로 붙습니다.
   여러 개면 쉼표로 나열하세요. [192.168.0.5]
   >

대괄호 안은 이 PC 의 주소를 자동으로 찾은 값입니다. 맞으면 엔터만 치세요.

③ 바깥 망에서 들어오는 주소

3) 바깥 망에서 이 CMS 로 들어오는 주소가 있으면 적으세요 — 공유기 포워딩 주소(여러 개면 쉼표).
   이름으로 붙는 것이 먼저입니다. 이름이 안 풀리는 망(폐쇄망 · 이중 NAT 바깥)에서 쓰는 IP 만 적으세요. 없으면 엔터.
   >

대부분은 엔터(비움)입니다. 공유기를 두 번 거치는 구성처럼, 바깥 망의 기기나 중계 장치가 공유기의 포워딩 주소(IP) 로 이 CMS 에 붙어야 할 때만 그 주소를 적습니다. 적은 주소는 CMS 인증서에 들어갑니다. 설치 뒤에 바꿔야 하면 다시 설치하지 않고 관리 화면에서 바꿉니다 — 담당자에게 문의하세요.

5. 관리자 비밀번호를 받아 적습니다

설치가 끝나면 관리자 초기 비밀번호가 한 번 표시됩니다.

이 값은 다시 볼 수 없습니다

화면에 한 번만 표시됩니다. 반드시 받아 적으세요. 로그인한 뒤에는 각자 다른 비밀번호로 바꾸시길 권합니다.

6. 설치가 스스로 확인합니다 (읽고 지나가세요)

🔵 마지막에 점검 한 화면이 나옵니다 — 이 기계를 맞춘 넷(시간대를 사이트 시각으로 · 도커가 부팅 때 자동으로 켜지게 · Hyper-V 면 KVP 데몬 · 백업 예약)의 결과와 CMS 상태 주소 · 다음 예약 시각 · 이 기계의 주소입니다. ⚠️ 가 붙은 줄은 그 줄이 보여 주는 명령을 그대로 실행하세요(못 했어도 설치는 성공입니다).

마지막으로 설치 파일이 실제로 화면이 뜨는지 확인합니다. 컨테이너가 떠 있어도 화면이 안 나오는 경우가 있어서, “명령이 끝났다” 가 아니라 “실제로 응답한다” 를 봅니다.

설치 검증 (실제로 응답하는지 — 최초 설치는 DB 초기화로 몇 분 걸립니다)...
  ✓ 컨테이너 web 동작
  ✓ 컨테이너 laravel 동작
  ✓ 컨테이너 db 동작
  ✓ 컨테이너 guacd 동작 (원격제어)
  ✓ 컨테이너 guacamole 동작 (원격제어)
  ✓ CMS 응답 확인 (HTTP 200)

여기까지 나오면 브라우저에서 http://<이 PC 주소>:8080 으로 접속할 수 있습니다.

원격제어 두 줄이 ⚠️ 로 나와도 설치는 정상입니다

화면은 멀쩡히 돌고 [원격 보기] · [조작 가능으로 열기] 단추만 못 씁니다. 고치려면 그 줄에 적힌 대로 docker compose up -d guacd guacamole 하시면 됩니다.

다시 설치할 때 이런 경고가 나오면

같은 PC 에 다시 설치하면, 설치 파일은 기존 설정을 그대로 둡니다(그래야 사이트 설정이 안 지워집니다). 그래서 .env 의 시크릿이 기본값 그대로 쓰이고 있으면 이런 줄이 나옵니다:

🔴 이 사이트가 **다른 사이트와 같은 시크릿**을 쓰고 있습니다: LARAVEL_APP_KEY

이건 그 사이트만의 비밀번호가 아직 만들어지지 않았다는 뜻입니다. 화면에 나오는 대로 .env 파일의 해당 값을 바꾸면 됩니다 — 새로 설치하는 곳에서는 나오지 않습니다.

⚠️ LARAVEL_APP_KEY 를 바꾸면 로그인이 한 번 풀립니다(다시 로그인하면 됩니다).

7. 백업을 켭니다 (꼭 하세요)

🔵 설치가 이 일을 스스로 합니다 — 매일 03:40(사이트 시각) · 14일 보관 · 설치 폴더의 backup/. 아래는 켜졌는지 확인하거나 저장 위치를 바꿀 때 씁니다(다시 깔아도 됩니다).

sudo bash docker/install-backup-timer.sh

매일 새벽에 설정·인증서·데이터베이스를 한 묶음으로 백업하고 14일간 보관합니다.

백업을 어디에 둘지 정하세요

기본 저장 위치는 설치 폴더 안의 backup/ 입니다. 편하지만, 나중에 설치 폴더를 통째로 옮기거나 지울 때 백업도 같이 사라집니다. 설치 폴더 밖을 권합니다.

sudo bash docker/install-backup-timer.sh '*-*-* 03:40:00' 14 /var/backups/treet

세 값은 차례대로 실행 시각 · 보관 일수 · 저장 위치입니다. 더 안전하게 하려면 이 폴더를 다른 디스크나 NAS 에 두세요.

백업이 없으면 복구가 불가능합니다

이 사이트에만 있는 인증서는 다시 만들 수 없습니다. 새로 만들면 이미 등록된 재생기들이 CMS 에 붙지 못합니다. 데이터베이스만 백업해서는 복구가 안 됩니다.

한 번은 손으로 돌려 실제로 파일이 생기는지 확인하세요.

sudo systemctl start treetweb-backup-site.service
ls -la backup/

7-b. 이 PC 에 Watchdog 을 깝니다 — CMS 가 멈추면 다시 켭니다

CMS 는 이 PC 의 가상 머신 안에서 돕니다. 그 VM 이 멈추면 현장의 화면 관리가 통째로 끊기는데, VM 은 스스로 그걸 알릴 수 없습니다. 그래서 바깥(이 윈도 PC)에서 Watchdog 이 지킵니다.

1. 재생기 PC 와 같은 방법으로 Watchdog 을 깝니다 — 현장 배포 의 Watchdog 설치를 보세요. 설치 중에 CMS 주소를 물으면 이 VM 의 주소(예: http://192.168.0.5:8080)를 넣습니다.

2. 따로 할 일은 없습니다. Watchdog 이 켜지면 CMS 주소와 같은 IP 의 VM 을 스스로 찾아 감시에 넣습니다.

3. ⚠️ 단, VM 안에 Hyper-V 연동 도구가 돌아야 Watchdog 이 그 VM 의 IP 를 봅니다(설치가 자동으로 깝니다 — 인터넷이 있어야 합니다). 이 윈도 PC(관리자 PowerShell)에서 확인합니다:

   Get-VMNetworkAdapter -VMName treet-cms | Select-Object -ExpandProperty IPAddresses

   VM 주소(예: 192.168.0.5)가 안 나오고 비어 있으면, VM 안에서 연동 도구를 깔고 켭니다(인터넷이 필요합니다):

   sudo apt install -y linux-cloud-tools-$(uname -r)
   sudo udevadm trigger --subsystem-match=misc --action=add
   sudo systemctl restart hv-kvp-daemon

   다시 위 명령으로 주소가 보이면 됩니다. 10분 안에 CMS 로그에 “이 PC 의 Hyper-V VM ‘treet-cms’ 을(를) CMS 로 알아보고 감시에 넣었습니다” 가 남습니다.

   🔵 Watchdog 은 이 상태를 스스로 알려 줍니다 — VM 이 켜져 있는데 IP 가 안 보이면 CMS 로그의 감시 줄에 ”… IP 가 Hyper-V 에 안 보입니다: VM 안에 hv-kvp-daemon … 이 돌아야 하고 …” 가 남습니다. 그 줄을 보면 위 세 줄을 실행하세요.

🔵 이미 Watchdog 이 깔린 PC 면 새로 깔지 않습니다 — 재생기와 CMS 가 한 PC 에 있는 현장이 그렇습니다. 그 Watchdog 이 CMS 도 같이 지킵니다.

켜 두면 이렇게 됩니다:

이런 일이 생기면	Watchdog 이
VM 이 꺼지거나 일시정지됨	다시 켭니다(3분 간격으로 봅니다)
CMS 가 3분 넘게 응답이 없음	CMS 로그에 남기고, 살아나면 “몇 시~몇 시 (N분) 응답이 없었다” 를 한 줄 남깁니다
VM 은 켜져 있는데 CMS 만 응답이 없음	보고만 합니다 — VM 안의 프로그램은 Watchdog 이 건드리지 못합니다

점검하려고 VM 을 일부러 꺼 둘 때

Watchdog 이 3분 안에 다시 켭니다. 오래 꺼 둘 일이 있으면 담당자에게 감시를 잠시 꺼 달라고 하세요.

가상 머신 없이 Ubuntu PC 에 바로 깔았다면 — 설치 파일이 Watchdog 도 깝니다

2번 설치(sudo bash install.sh)가 물리 PC 라는 것을 알아보면 Watchdog 을 함께 깔고 CMS 를 지키게 합니다. 따로 할 일은 없습니다 — 설치 화면에 “Watchdog(CMS 돌보기): …” 줄이 보입니다.

• 멈춘 CMS 프로그램은 원래 스스로 다시 뜹니다. Watchdog 은 그러지 못한 경우만 맡습니다 — 멈춘 채 남은 것은 그것만, 모두 사라졌으면 전체를 다시 올립니다(3분 간격).
• 상태 검사가 나쁘게 나오면 보고만 합니다 — 돌고 있는 데이터베이스를 내리지 않으려고입니다.
• CMS 가 3분 넘게 응답하지 않으면 기록하는 것은 위와 같습니다.

⚠️ 설치 화면에 “깔지 않았습니다” 가 보이면 그 줄이 시키는 대로 하세요(예: ps 가 없으면 apt-get install procps 뒤 다시).

점검하려고 CMS 를 일부러 멈춰 둘 때

docker compose stop 으로 멈춰 두어도 Watchdog 이 3분 안에 다시 올립니다(멈춘 채 남은 것을 되살리는 것이 위 규칙입니다). 오래 멈춰 둘 일이 있으면 그동안 감시를 꺼 두세요.

8. 원격으로 붙는 방법 (둘은 다른 이야기입니다)

자주 헷갈리는 자리라 갈라 적습니다.

8-a. 이 CMS PC 에 붙으려면 — SSH 입니다

설치 파일이 깔아 주지 않습니다. Ubuntu 를 설치할 때 Install OpenSSH server 를 체크한 것이 그 역할입니다(0-d 참고).

안 하셨다면 지금 깔면 됩니다.

sudo apt install -y openssh-server
systemctl status ssh

붙지 않으면 아래를 차례로 봅니다.

확인	명령 · 자리
SSH 가 도는가	systemctl status ssh
이 PC 의 주소	ip -4 addr show | grep inet
🔴 VM 이 외부 스위치인가	Hyper-V 관리자 → VM 설정 → 네트워크 어댑터. 내부/개인용이면 밖에서 못 붙습니다
방화벽	sudo ufw status (기본은 꺼져 있습니다)

8-b. 기기 화면을 보려면 — 원격제어 기능입니다

CMS 관리 화면에서 키오스크 화면을 브라우저로 들여다보는 기능입니다. 설치하면 바로 켜져 있습니다 — 따로 하실 일이 없습니다.

따로 접속하는 주소가 없습니다

원격제어 프로그램은 바깥으로 포트를 열지 않습니다. CMS 가 그 앞에서 대신 받아 넘기므로, CMS 에 로그인한 사람만 쓸 수 있습니다.

쓰는 법: 관리 화면 → 기기관리 → 기기를 눌러 기기 페이지 → 머리의 [원격 보기](또는 [조작 가능으로 열기]) 단추 → 새 탭이 열립니다. 주소는 평소 쓰시는 그 CMS 주소 하나뿐입니다.

🔴 기기마다 UltraVNC 를 깔아야 합니다

CMS 쪽은 준비돼 있지만, 보여 줄 화면을 내보내는 쪽은 기기에 있습니다. 키오스크 PC 마다 VNC 서버(UltraVNC) 를 설치·실행해 두세요.

기기에서	값
VNC 서버	UltraVNC (설치 후 자동 시작되게)
포트	5900 (기본값 그대로)
비밀번호	정하지 않아도 됩니다 — 단추를 누를 때마다 그 PC 의 Watchdog 이 일회용으로 겁니다(CMS 2026.9.725 · Watchdog 2026.9.153 부터)

CMS 쪽은 대부분 비워 두면 됩니다(기기가 보고한 IP · 5900). 주소나 포트가 다를 때만 관리 화면의 기기관리 → 기기 페이지 → 기본 정보 고치기 → “원격접속” 칸에 주소[:포트] 를 적습니다 — 비밀번호는 적지 않습니다.

오래된 Watchdog 기기는 사이트 공통 비밀번호를 씁니다

일회용 비밀번호를 아직 못 하는 Watchdog 판이 깔린 기기는 .env 의 GUACAMOLE_VNC_PASSWORD 로 붙습니다. 그 값이 기기의 UltraVNC 비밀번호와 다르면 탭은 열리는데 화면만 까맣게 뜹니다 — 연결 실패처럼 안 보입니다. 가장 쉬운 해결은 그 기기의 Watchdog 을 새 판으로 올리는 것입니다.

[원격 보기] 를 눌렀는데 안 되면

증상	원인
”원격제어가 구성되지 않았습니다”	.env 의 GUACAMOLE_JSON_SECRET_KEY 가 비었습니다(설치본이 만들어 주므로 보통 안 납니다)
새 탭이 뜨는데 502	원격제어 컨테이너가 안 떠 있습니다 → docker compose up -d
탭은 뜨는데 화면이 안 나옴	기기 쪽 UltraVNC 입니다 — 위 참고
Watchdog 응답 없음	그 PC 의 Watchdog 이 꺼졌거나 박동 간격이 깁니다 — 기기 페이지 Watchdog 탭의 마지막 응답
새 탭이 아예 안 뜸	브라우저 팝업 차단 — 이 CMS 주소를 허용하세요

끄는 설정은 없습니다

원격제어는 설치본에서 늘 켜져 있습니다 — 끄는 설정은 따로 없습니다. 잠깐 멈추려면 docker compose stop guacamole guacd 를 하세요. 그동안 원격접속 단추는 “원격제어 서비스가 실행 중이 아닙니다” 로 답합니다. 다시 켜려면 docker compose up -d guacd guacamole 입니다(그 문구 뒤에도 이 명령이 붙습니다). ⚠️ 업데이트나 재설치 때 다시 켜집니다(up -d 가 다시 띄웁니다) — 영구 스위치가 아닙니다.

9. 인터넷 주소와 인증서 — 두 입구를 함께 세웁니다

사이트에는 입구가 둘 있습니다. 기본 구성은 둘 다입니다.

주소	누가 씁니까	어떻게 들어옵니까
https://<사이트>.treetsites.com:8443	기기 · 큰 영상 업로드 · 평소 관리	공유기 → CMS 로 곧장(공개 인증서)
https://admin-<사이트>.treetsites.com	관리자만 — 공유기 포트가 막혔을 때의 비상 입구	Cloudflare 터널

관리자 입구는 기기에 넣지 마세요

기기(재생기·Watchdog·SyncServer)의 CMS 주소에는 첫 번째 주소만 넣습니다. 터널은 중간에서 암호화를 한 번 풀기 때문에 기기 인증서가 통하지 않습니다 — 증상이 “접속은 되는데 인증이 안 된다” 라서 원인을 찾기 어렵습니다. 관리자 입구로는 100MB 넘는 파일을 올릴 수 없습니다(Cloudflare 한도). 큰 영상은 첫 번째 주소로 올리세요.

두 입구를 세우는 일은 TreeT 담당자가 합니다

인증서와 관리자 입구는 TreeT 가 관리하는 treetsites.com 이름으로 만들어지므로, 그 작업은 TreeT 담당자가 설치 때 합니다. 사이트 쪽에서 준비할 것은 공유기 포트포워딩 하나입니다 — 바깥 8443 → CMS VM 8443. 끝나면 아래 9-e 로 두 주소가 열리는지 확인하세요.

9-e. 확인합니다

VM 에서:

sudo ./cert-check.sh            # 공개 인증서인지 · 만료까지 며칠인지
sudo ./install-tunnel.sh --check  # 터널 서비스 · 밖에서의 응답

그리고 Windows 브라우저에서 두 주소를 직접 엽니다 — 둘 다 자물쇠 아이콘이 떠야 하고 경고 화면이 나오면 안 됩니다. 🔵 사이트 안 네트워크에서 첫 번째 주소가 안 열리면 공유기가 자기 공인 IP 로 되돌아오는 접속(헤어핀)을 막는 경우입니다 — 휴대폰 데이터로 확인하거나, 관리자 입구를 쓰세요.

시간 서버 — CMS 가 기기에 시간을 내줍니다

CMS 를 설치하면 시간 서버(NTP) 가 함께 뜹니다. 끄는 스위치는 없습니다 — 기기가 시간 동기를 켜는 순간 받을 수 있어야 하기 때문입니다. 같은 내부망의 기기가 UDP 123 번으로 이 CMS 에서 시간을 받아 갑니다. 인터넷 쪽 시간 서버에 닿지 못하는 폐쇄망이어도, 기기끼리는 이 CMS 시계에 맞춰집니다.

할 일	왜
CMS VM 의 방화벽을 켰다면 내부망에서 들어오는 UDP 123 을 엽니다	막히면 기기가 시간을 못 받습니다
공유기에서 바깥으로는 열지 않습니다	공개된 시간 서버는 공격에 악용됩니다
CMS VM 에 다른 시간 서버 프로그램(chrony · ntpd)을 따로 깔지 않습니다	123 번을 서로 쓰려 해 CMS 의 시간 서버가 뜨지 못합니다 — 설치 전 점검이 그런 경우 막고 알려 줍니다. 우분투 기본 시간 맞춤(timesyncd)은 괜찮습니다

CMS 자신의 시계는 VM 이 맞춥니다(Hyper-V 통합 서비스의 시간 동기화 · 우분투 기본 시간 맞춤).

다 됐는지 확인하기

여기까지 오셨으면 아래가 모두 되어 있어야 합니다. 하나라도 안 되면 그 번호로 돌아가세요.

확인	어떻게	안 되면
관리 화면이 열린다	브라우저에서 http://<이 PC 주소>:8080	6번
관리자로 로그인된다	5번에서 받아 적은 비밀번호로	5번
백업이 켜져 있다	systemctl list-timers | grep treetweb	7번
백업 파일이 실제로 생긴다	ls -la backup/	7번
사이트 주소가 경고 없이 열린다	https://<사이트>.treetsites.com:8443	9번
관리자 입구가 열린다	https://admin-<사이트>.treetsites.com	9-d

백업 두 줄은 꼭 확인하세요

“켰다” 와 “파일이 생긴다” 는 다릅니다. 한 번은 손으로 돌려서 파일이 실제로 생기는 것까지 보세요. 이 사이트에만 있는 인증서는 다시 만들 수 없습니다.

다음은 무엇을 하나요

설치는 CMS 를 세우는 것까지입니다. 화면에 콘텐츠가 나오려면 세 가지가 더 필요합니다.

1. 재생기(TreeTview) 를 키오스크 PC 에 설치하고, 그 PC 에서 F8 로 이 CMS 주소를 넣습니다. 🔴 설치만으로는 안 붙습니다 — 재생기는 개발 기본값(127.0.0.1)을 들고 나옵니다. 주소를 넣으면 그때 스스로 등록되어 기기 목록에 나타납니다(기기 인증서도 자동으로 발급받습니다). → 현장 배포 ⚠️ 넣은 뒤 재생기 로그의 [사이트설정] 확인 줄을 눈으로 보세요. 목록에 뜨는 것만으로는 부족합니다 — 이 확인을 건너뛰면 뒤에서 원인을 못 찾습니다.
2. 콘텐츠를 올리고 편성합니다 — 어떤 화면에 무엇을 언제 틀지 정합니다.
3. 기기마다 UltraVNC 를 깝니다 — 원격제어는 CMS 쪽이 이미 켜져 있고, 보여 줄 화면을 내보내는 쪽만 기기에 있으면 됩니다(8-b).

쓰는 방법은 관리 화면 문서에 있습니다 — 기기 등록·편성·원격제어가 화면 순서대로 적혀 있습니다.

운영으로 넘길 때 — 업데이트 채널을 stable 로

설치를 막 마친 CMS 는 아직 운영 전(개발 단계) 으로 봅니다. 이때는 개발 판(시험 중인 앱·CMS 판)도 받습니다. 기기를 다 붙이고 편성까지 마쳐 모든 설정이 끝나면 운영으로 넘깁니다 — 그때부터는 시험을 마치고 정식으로 내보낸 판(stable)만 받습니다.

1. 설치 폴더의 .env 를 엽니다: sudo nano .env
2. #TREET_UPDATE_CHANNEL=stable 줄의 맨 앞 # 을 지웁니다. 그 줄이 없으면 맨 끝에 TREET_UPDATE_CHANNEL=stable 을 새로 적습니다.
3. 저장하고 CMS 를 다시 올립니다: sudo docker compose up -d

TREET_UPDATE_CHANNEL	이 CMS 는
(비어 있음 — 기본)	운영 전. 개발 판도 받습니다
stable	운영 중. 승격된(stable) 판만 받습니다 — 앱 업데이트 목록 · CMS 업데이트 꾸러미 · 손으로 올리는 설치본 모두

운영으로 넘긴 뒤에는 손으로 올리는 설치본도 승격된 판만 됩니다

관리 화면에서 앱 설치본을 직접 올릴 때도, 운영 중인 CMS 는 승격 증명서가 있는 판만 받습니다 (관리 화면 문서의 앱 설치본 올리기). CMS 자신을 올리는 업데이트 꾸러미도 마찬가지로, 운영 중인 CMS 는 승격된 CMS 판만 적용합니다. 시험 판을 현장에 올려야 하면 담당자에게 문의하세요.

모르는 값은 받지 않습니다

stable 이 아닌 값(예: beta)을 적으면 CMS 업데이트가 거절합니다. 오타가 없는지 보세요.

CMS 를 새 판으로 올릴 때

처음 설치와 같은 방법입니다 — 새 꾸러미를 받아 그 안에서 install.sh 를 다시 돌립니다. 따로 업데이트 절차가 있는 것이 아닙니다.

# VM 안에서, 새 꾸러미를 푼 폴더에서
sudo bash install.sh

사이트 값은 그대로 남습니다

.env(DB 비밀번호·사이트 주소)와 인증서는 이미 있으면 안 덮습니다. 관리자 비밀번호는 .env 가 아니라 DB 에 있어 그대로입니다. 그래서 다시 돌려도 현장 설정을 다시 넣을 필요가 없습니다. 콘텐츠와 DB 도 그대로입니다.

그래도 백업을 먼저 확인하세요

올리기 전에 백업 파일이 실제로 있는지 눈으로 보세요 — ls -la backup/. 이 사이트에만 있는 인증서는 다시 만들 수 없습니다.

무엇이 바뀌었는지는 꾸러미의 읽어주세요.md 와 판 번호로 확인합니다. 올린 뒤에는 위 “다 됐는지 확인하기” 의 넷을 다시 봅니다 — 특히 관리 화면이 열리는지.

기기는 따로입니다

CMS 를 올려도 키오스크의 재생기가 그 자리에서 바뀌지는 않습니다. 기기 쪽 새 판은 CMS 의 업데이트 방식(자동 · 수동)에 따라 각 기기의 운영시간 밖에 깔리고, 바로 깔려면 [지금 설치] 를 누릅니다 → 현장 배포

다시 설치해야 할 때 (복구)

같은 사이트를 다시 세우는 경우에는 백업 파일이 먼저 있어야 합니다.

bash docker/restore-site.sh <백업파일>            # 설정·인증서를 제자리에
sudo bash install.sh                              # 설치
bash docker/restore-site.sh <백업파일> --db-only  # 데이터 넣기

복원이 끝나면 기기 뷰어를 한 번 다시 시작하세요

배포 번호는 저절로 늘어나는 번호라 백업한 때의 번호부터 다시 셉니다. 그래서 복원 뒤에 새로 낸 배포도 기기가 이미 띄우고 있는 번호(백업 뒤에 나간 것)보다 낮을 수 있고, 기기는 받기는 해도 더 높은 번호만 적용해 화면이 안 바뀝니다. “편성을 다시 저장하면 되겠지” 는 이 경우 통하지 않을 수 있습니다.

• 기기 페이지의 명령 메뉴에서 [다시 시작] 을 누르면 받아 둔 편성을 그대로 띄웁니다.
• 다시 시작은 기기가 새 배포를 다 받은 뒤에 합니다 — 기기 로그(기기관리 → 로그)에 업데이트 완료: contents 가 찍힌 뒤입니다. 덜 받은 채 다시 시작하면 바로 전 편성으로 물러서고 새 것을 미룹니다.
• 복원 직후 편성을 비운 채 저장하지 마세요 — 비운 편성도 배포되어, 기기는 레이아웃(분할 · 배경)은 그대로 두고 빈 자리를 배경으로 채웁니다(콘텐츠가 사라진 것처럼 보입니다).

백업 없이 같은 이름으로 다시 설치하지 마세요

설치는 성공한 것처럼 끝나지만 인증서가 새로 만들어져 기존 재생기들이 CMS 에 붙지 못합니다. 설치 파일이 이 경우를 감지하면 멈추고 무엇이 필요한지 알려줍니다.

복원이 거부될 때 — 두 가지가 있습니다

복원은 넣기 전에 백업이 쓸 만한지 먼저 봅니다. 멈췄다면 둘 중 하나입니다.

• “끊어진 링크입니다” — latest.tar.gz 가 가리키던 파일이 보관 기간이 지나 지워졌습니다 (또는 그동안 백업이 안 돌았습니다). 같은 폴더의 다른 treetweb_site_*.tar.gz 를 직접 지정하세요.
• “덤프가 끝까지 나오지 않았습니다” — 그 백업이 만들어지다 중간에 끊겼습니다. 다른 날짜의 백업을 쓰세요.

🔴 억지로 넣지 마세요. 절반만 들어간 데이터베이스가 되고, 그 상태는 “복원 완료” 처럼 보입니다. 그때는 원본이 이미 덮인 뒤라 되돌리기가 훨씬 어렵습니다.

문제가 생기면

docker compose logs --tail 50 web laravel   # 최근 로그(예약 작업까지: laravel-scheduler media-worker 를 덧붙입니다)
docker compose ps                       # 무엇이 떠 있는지
sudo bash docker/preflight.sh           # 준비 상태 다시 점검