본문으로 건너뛰기

MeshCentral 구축 가이드

등록일: 2026-11-02


1. 구성​

항목설정
호스트Xubuntu 24.04 (XFCE / X11)
MeshCentralDocker Compose, ghcr.io/ylianst/meshcentral:latest
외부 주소https://mc.sleepzz.xyz
외부 연결Cloudflare Tunnel (cloudflared)
Docker 네트워크serverzz-net (기존 외부 네트워크)
호스트 포트 공개없음
관리 대상Xubuntu 및 Windows PC (MeshAgent)

Cloudflare Tunnel과 MeshCentral은 동일한 Docker 네트워크를 사용한다. MeshCentral의 호스트 포트는 공개하지 않는다.

2. 디렉터리 준비​

설정·DB·인증서는 SSD에, 파일·백업은 HDD에 저장한다.

findmnt /ext001

docker network inspect serverzz-net --format '{{.Name}}'

sudo mkdir -p \
/data001/meshcentral/meshcentral-data \
/ext001/data001/meshcentral/meshcentral-files \
/ext001/data001/meshcentral/meshcentral-backups

/ext001이 정상 마운트된 상태에서 컨테이너를 시작한다.

3. Docker Compose​

작업 디렉터리에 compose.yaml을 작성한다.

services:
meshcentral:
image: ghcr.io/ylianst/meshcentral:latest
container_name: meshcentral
restart: unless-stopped

environment:
TZ: Asia/Seoul

volumes:
# SSD: 설정, DB, 인증서
- /data001/meshcentral/meshcentral-data:/opt/meshcentral/meshcentral-data
# HDD: 파일 저장소
- /ext001/data001/meshcentral/meshcentral-files:/opt/meshcentral/meshcentral-files
# HDD: 백업
- /ext001/data001/meshcentral/meshcentral-backups:/opt/meshcentral/meshcentral-backups
# 웹 UI 커스터마이징을 위한 meshcentral-web 디렉터리
- /data001/meshcentral/meshcentral-web:/opt/meshcentral/meshcentral-web

networks:
- serverzz-net

networks:
serverzz-net:
external: true

4. MeshCentral 설정​

호스트에서 다음 파일을 작성한다.

sudo micro /data001/meshcentral/meshcentral-data/config.json
{
"$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
"settings": {
"cert": "mc.sleepzz.xyz",
"port": 443,
"redirPort": 0,
"tlsOffload": true,
"agentPong": 120,
"selfUpdate": false,
"allowFraming": false,
"webRTC": false
},
"domains": {
"": {
"title": "serverzz mc",
"newAccounts": true,
"certUrl": "https://mc.sleepzz.xyz"
}
}
}
  • tlsOffload: true: Cloudflare에서 HTTPS를 종료하고, 컨테이너 내부의 MeshCentral은 HTTP로 통신한다.
  • certUrl: 외부 HTTPS 인증서를 참조하는 주소. 앞에 _를 붙이지 않는다. 에이전트 인증서 해시 검증에 중요하다.
  • newAccounts: true: 최초 관리자 계정 생성용 임시 설정. 관리자 생성 후 false로 변경한다.
  • JSON 키 앞에 _를 붙이면 MeshCentral의 예시/비활성 설정으로 취급될 수 있으므로 실제 적용할 키에는 붙이지 않는다.

설정 검증:

sudo python3 -m json.tool /data001/meshcentral/meshcentral-data/config.json > /dev/null

5. 컨테이너 실행​

compose.yaml이 있는 디렉터리에서:

docker compose config
docker compose up -d
docker logs --tail 80 meshcentral

정상 실행 시 MeshCentral의 HTTP 서버가 내부 포트 443에서 실행된다.

6. Cloudflare Tunnel 연결​

기존 Cloudflare Tunnel에 공개 호스트명을 추가한다.

항목값
호스트명mc.sleepzz.xyz
서비스 유형HTTP
서비스 주소meshcentral:443

cloudflared 컨테이너도 serverzz-net에 연결되어 있어야 한다. MeshCentral의 tlsOffload: true와 Tunnel의 HTTP 설정을 일치시킨다.

브라우저에서 다음 주소로 접속한다.

https://mc.sleepzz.xyz

별도의 URL 경로는 필요 없다.

7. 관리자 계정 및 장치 그룹​

  1. 웹페이지에서 최초 사용자 계정을 생성한다. 첫 계정은 관리자 계정으로 설정된다.
  2. 로그인 후 My Devices → Add Device Group으로 이동한다.
  3. 장치 그룹 이름을 지정하고 Manage using a software agent 유형으로 생성한다.

8. Xubuntu MeshAgent 설치​

  1. 생성한 장치 그룹에서 Add Agent를 선택한다.
  2. Linux/BSD에 해당하는 설치 명령어를 확인한다.
  3. 표시된 서버 주소가 mc.sleepzz.xyz인지 확인하고, Xubuntu에서 해당 명령어를 실행한다.

설치 명령어에는 서버 및 그룹별 정보가 포함되므로 MeshCentral 화면에 표시된 명령어를 그대로 사용한다.

서비스 상태 확인:

systemctl status meshagent --no-pager
systemctl list-units --type=service --all | grep -i mesh

연결이 정상이라면 My Devices에 Xubuntu 장치가 온라인으로 표시된다.

터미널 사용​

MeshAgent가 시스템 서비스로 실행되므로 Linux 웹 터미널은 root로 열릴 수 있다. 일반 사용자 환경이 필요하면:

su - sleepzz
whoami

원격 데스크톱​

장치의 Desktop → Connect에서 XFCE 화면을 확인한다. X11 세션이 여러 개라면 에이전트가 보여주는 화면이 xrdp 세션과 다를 수 있다.

9. Windows PC MeshAgent 설치​

  1. Windows 브라우저에서 https://mc.sleepzz.xyz에 로그인한다.
  2. 장치 그룹의 Add Agent를 선택한다.
  3. Windows 64비트 에이전트를 다운로드한다.
  4. 실행 후 Install / Update로 설치한다. 필요한 경우 관리자 권한을 승인한다.
  5. My Devices에서 Windows 장치가 온라인으로 표시되는지 확인한다.
  6. Desktop, Terminal, Files 기능을 테스트한다.

Windows에 별도의 SSH 또는 RDP 서버를 설치할 필요는 없다.

10. 관리자 계정 생성 후 보안 마무리​

신규 회원가입 차단​

sudo micro /data001/meshcentral/meshcentral-data/config.json

domains의 기본 도메인 설정에서 다음 값을 변경한다.

"newAccounts": false

변경 후:

sudo python3 -m json.tool /data001/meshcentral/meshcentral-data/config.json > /dev/null
docker restart meshcentral

시크릿 창으로 로그인 페이지를 열어 신규 가입 메뉴가 사라졌는지 확인한다. 기존 계정은 유지된다.

관리자 2단계 인증​

MeshCentral의 계정 설정에서 OTP 기반 2단계 인증을 활성화한다.

호스트 포트 비공개 확인​

Compose에 ports:가 없어야 한다.

sudo ss -lntp '( sport = :8087 )'
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep meshcentral

8087에 리스너가 없고 MeshCentral의 호스트 포트 매핑이 없다면 정상이다. Cloudflare Tunnel은 Docker 네트워크 내부에서 계속 접근할 수 있다.

11. 동작 검증​

  • https://mc.sleepzz.xyz 로그인 성공
  • Xubuntu 에이전트 온라인 표시
  • Linux 웹 터미널에서 한영 전환·한글 조합·붙여넣기 정상
  • XFCE Desktop 연결 및 키보드·마우스 조작 정상
  • Windows 에이전트 온라인 표시
  • Windows Desktop·Terminal·Files 정상
  • 원격 화면 장시간 사용 및 재연결 정상
  • 관리자 2단계 인증 활성화
  • 신규 계정 가입 차단
  • 호스트 포트 매핑 제거

12. 운영 명령어​

# 컨테이너 상태
docker ps --filter name=meshcentral

# 로그
docker logs --tail 100 meshcentral

# 설정 변경 반영
docker restart meshcentral

# Compose 변경 반영 (compose.yaml 위치에서)
docker compose up -d

# Xubuntu 에이전트 상태
systemctl status meshagent --no-pager

# 에이전트 재시작
sudo systemctl restart meshagent

# 에이전트 서비스 로그
sudo journalctl -u meshagent -n 50 --no-pager

인증서 관련 오류가 나타나면 config.json의 certUrl 활성화 여부와 Cloudflare Tunnel의 HTTPS 인증서 경로를 우선 확인한다. Agent bad web cert hash 오류는 인증서 해시가 일치하지 않아 연결이 보류된 상태를 뜻한다.