태블로 맵 차트, 인터넷 없이 쓰는 법 — 온프라미스 오프라인 환경일 경우

태블로 맵 차트가 인터넷을 요구하는 이유

태블로에서 맵 차트를 처음 만들어보면 당연하게 지도가 뜨는 것 같다. 그런데 폐쇄망 환경에 배포하는 순간, 지도 타일이 싹 사라지고 점만 둥둥 떠 있는 황당한 상황을 맞닥뜨리게 된다.

왜 그럴까. 이유는 단순하다. 태블로의 기본 맵 데이터는 태블로 서버 내부에 없다. 지도를 렌더링하는 타일 이미지를 외부 서버에서 실시간으로 받아오는 구조다.

태블로는 맵 데이터를 외부에서 호스팅하고, 지도를 표시하려면 포트 443을 통해 외부 맵 서버(mapsconfig.tableau.com, api.mapbox.com)에 연결해야 한다.

좀 더 정확히 말하면 태블로 2019.2 버전부터는 Mapbox의 벡터 타일 기술 기반으로 맵이 렌더링된다. 벡터 맵은 더 부드럽고 세밀하며 커스터마이징이 가능하지만, mapbox.com에 인터넷으로 접속해야 정상 작동한다.

즉, 맵 타일 서버(Mapbox) → 태블로 서버/데스크탑 방향으로 이미지를 받아오는 것이 기본 동작이다. 폐쇄망에서는 이 연결 자체가 불가능하기 때문에 맵이 뜨지 않는다.

해결책: 맵 타일 파일을 로컬에 넣어주면 된다

발상은 간단하다. 태블로가 외부 서버에서 받아오는 맵 타일 이미지 파일을, 미리 다운로드해서 태블로가 설치된 PC나 서버 로컬 경로에 넣어두면 된다. 그러면 태블로는 인터넷 대신 로컬 파일을 읽는다.

구체적인 절차는 크게 4단계다.

맵 타일 파일을 다운로드한다 (또는 운영서버에서 복사한다)
태블로 Desktop/Server의 맵 경로에 파일을 배치한다
Desktop에서 배경 맵을 "오프라인"으로 설정한다
Server는 TSM 명령어로 오프라인 맵을 기본값으로 변경한다

하나씩 살펴보자.

STEP 1. 맵 타일 파일 확보

방법 A. VWorld API로 직접 다운로드 (시간이 많다면)

국내 공공 데이터 플랫폼인 VWorld는 타일맵 이미지를 API 형태로 제공한다. Python 코드로 API를 호출해서 타일 이미지를 폴더 구조 그대로 다운로드할 수 있다.

import os
import urllib.request

baseURL = 'http://xdworld.vworld.kr:8080/2d/Base/service/'
URLsuffix = '.png'

# 줌 레벨 범위 설정 (6~16이면 한국 시군구 수준까지 커버)
s_level = 6
e_level = 16

if not os.path.isdir('normal'):
    os.mkdir('normal')

for z in range(s_level, e_level + 1):
    if not os.path.isdir('normal\\%i' % (z)):
        os.mkdir('normal\\%i' % (z))

    # y 범위: 6레벨 기준 52~58 (한반도 위경도 범위)
    for y in range(52 * (2 ** (z - 6)), 58 * (2 ** (z - 6))):
        if not os.path.isdir('normal\\%i\\%i' % (z, y)):
            os.mkdir('normal\\%i\\%i' % (z, y))

        # x 범위: 6레벨 기준 22~28
        for x in range(22 * (2 ** (z - 6)), 28 * (2 ** (z - 6))):
            print("%i %i %i" % (z, y, x))
            URL = '%s%i/%i/%i%s' % (baseURL, z, y, x, URLsuffix)
            fo = '.\\normal\\%i\\%i\\%i.png' % (z, y, x)
            if not os.path.exists(fo):
                try:
                    urllib.request.urlretrieve(URL, fo)
                except:
                    pass

        # 타일이 하나도 없는 폴더는 삭제
        if len(os.listdir('normal\\%i\\%i' % (z, y))) == 0:
            os.rmdir('normal\\%i\\%i' % (z, y))

다운로드 시 반드시 알아야 할 것들:

줌 레벨과 파일 수의 관계를 이해해야 한다. 줌 레벨이 올라갈수록 타일 수는 4ⁿ 규칙으로 지수적으로 증가한다. 줌 레벨 0에서는 전 세계가 타일 1장에 들어가지만, 레벨이 오를수록 기하급수적으로 늘어난다.

실무에서는 레벨 13까지만 받는 것을 권장한다. 시군구 경계까지 확인하는 데 레벨 13이면 충분하다. 레벨 16까지 모두 받으면 파일 수가 폭발적으로 늘어나서, 실제로 반나절에서 하루 이상 소요될 수 있다. 자료에 따르면 경우에 따라 2~3일까지 걸리기도 한다.

핵심 주의사항

다운로드하는 동안 서버 전원을 절대 끄지 말 것

디스크 여유 공간을 넉넉히 확보한 상태에서 시작할 것

파이썬 스크립트 실행 전에 normal 폴더가 있는 드라이브의 여유 공간 확인 필수

방법 B. 운영서버에서 복사 (실무 최강 꿀팁)

이건 정말 머리를 한 대 맞은 것 같았다.

신규 프로젝트 개발 서버에 맵을 설정해야 하는 상황이었다. 방법 A대로 다운로드를 시도하려니 시간이 너무 오래 걸렸다. 그런데 가만히 생각해 보니, 이미 오래전부터 운영서버에서 맵이 잘 돌아가고 있었다. 즉, 운영서버의 normal 폴더에는 이미 완성된 타일 파일들이 전부 들어 있다는 뜻이다.

결론: 운영서버의 맵 파일을 개발서버로 복사하면 끝난다.

운영서버 담당자를 통해 파일을 압축해서 산출물 시스템(내부 파일 공유 서버)으로 이관받은 뒤, 개발서버에 그대로 배치했다. 다운로드 시간 0분, 설정 시간만 걸렸다.

환경에 같은 버전의 태블로 서버가 운영되고 있다면, 이 방법이 압도적으로 빠르다.

STEP 2. 파일 경로에 배치

다운로드 혹은 복사한 normal 폴더를 다음 경로에 넣는다.

Tableau Desktop (Windows)

C:\Program Files\Tableau\Tableau <버전>\Local\Maps\US\

→ US 폴더 안에 normal 폴더를 위치시킨다.

Tableau Server (구버전)

<Tableau Server 설치경로>\Tableau Server\10.4\vizqlserver\local\maps\US\

Tableau Server (신버전 패키지 경로)

<Tableau Server 설치경로>\Tableau Server\packages\vizqlserver.<버전>\local\maps\US\

ormal 폴더의 내부 구조는 다음과 같다.

normal/
├── 0/        ← 줌 레벨 0 (전세계 윤곽)
├── 1/
├── 2/
├── 3/
├── 4/
├── 5/        ← 기본 설치 시 여기까지만 포함 (국가 수준)
├── 6/        ← 이 이후는 별도 추가 필요
├── 7/
├── ...
├── 13/       ← 시군구 수준 (이 정도면 대부분의 BI 대시보드에 충분)
├── ...
└── 16/       ← 도로명 수준 (거의 불필요)

기존 normal 폴더에는 0~5 레벨만 들어있다. 여기에 6번 이상 레벨 폴더를 추가로 합치는 개념이다. 기존 0~5는 그대로 두고, 새로 받은 6~13(또는 16)을 normal 폴더 안에 복사해 넣으면 된다.

STEP 3. Tableau Desktop 오프라인 설정

Desktop에서는 메뉴에서 간단히 전환할 수 있다.

상단 메뉴 → 맵(M) → 배경 맵(K) → 오프라인

이 설정을 적용한 통합문서(.twb, .twbx)를 Tableau Server에 게시하면, 서버에서도 오프라인 맵 설정이 그대로 유지된다. 단, 서버에도 맵 파일이 동일하게 배치되어 있어야 한다.

⚠️ 절대주의: 오프라인 설정 안 하고 필드 더블클릭하면 5분 멈춤

Desktop에서 오프라인 설정을 하지 않은 상태에서 위경도 필드 혹은 지역 필드를 맵 뷰에 올리면, Desktop이 api.mapbox.com으로 연결을 시도한다. 폐쇄망이면 이 연결 요청이 타임아웃될 때까지 대기하기 때문에, 화면이 약 5분 정도 그냥 멈춘다.

처음 겪으면 프로그램이 죽은 줄 알고 강제 종료하게 된다. 오프라인 환경에서 작업한다면, Desktop을 열자마자 배경 맵을 오프라인으로 바꾸는 것을 습관으로 들이자.

STEP 4. Tableau Server TSM 명령어 설정

Tableau Server는 기본값이 온라인 맵이기 때문에, 별도 명령어로 오프라인을 바라보도록 바꿔줘야 한다.

서버 터미널에서 아래 명령을 순서대로 실행한다.

$ tsm configuration set -k vizqlserver.force_maps_to_offline -v true
$ tsm pending-changes apply

tsm pending-changes apply 실행 시 재시작 여부를 묻는 프롬프트가 뜬다. y + Enter를 입력하면 Tableau Server가 재시작되면서 설정이 적용된다.

재시작 이후부터는 Tableau Server에서 지도 차트를 조회할 때 기본값으로 로컬에 저장된 오프라인 맵을 바라보게 된다.

전체 흐름 정리

[맵 파일 확보]
  A. VWorld API → Python 스크립트로 다운로드 (레벨 6~13 권장)
  B. 운영서버 normal 폴더 → 개발/산출물 서버로 복사 (강추)

[파일 배치]
  Desktop → C:\Program Files\Tableau\Tableau <ver>\Local\Maps\US\normal\
  Server  → <설치경로>\packages\vizqlserver.<ver>\local\maps\US\normal\

[Desktop 설정]
  맵 → 배경 맵 → 오프라인
  ※ 오프라인 설정 전 필드 클릭 금지 (5분 멈춤 현상)

[Server 설정]
  $ tsm configuration set -k vizqlserver.force_maps_to_offline -v true
  $ tsm pending-changes apply → y 입력 후 재시작

마치며

태블로 온프라미스 프로젝트에서 맵 차트는 생각보다 자주 요청된다. 공공기관 특성상 보안망이 막혀 있는 경우가 많고, 그때마다 이 작업이 필요하다.

핵심을 정리하면 이렇다.

첫째, 원인을 알면 해결책이 보인다. 태블로 맵은 Mapbox 외부 서버에서 타일을 가져오는 구조라, 폐쇄망에서는 로컬 파일로 대체해줘야 한다.

둘째, 같은 환경의 운영서버가 있다면 파일 복사가 정답이다. 수십 시간짜리 다운로드를 기다릴 이유가 없다.

셋째, Desktop에서의 5분 멈춤 현상을 동료에게 미리 공유하자. 이걸 모르는 사람이 맵 뷰를 열었다가 프리징이 생기면 공황 상태가 된다.

레퍼런스: Planit Partners - Offline map 다운로드 및 적용 설정가이드 (2017)

Insight Data Lab