본문으로 건너뛰기

서버 대시보드

9.14.0부터 dashboard 옵션을 켜면 서버가 실시간 상태 페이지를 함께 제공합니다. 게임처럼 서버 안의 게임 로직(호스트)을 쓰는 서버에서 특히 쓸모가 있지만, 호스트가 없는 서버에서도 서버와 트래픽 상태를 볼 수 있습니다.

import { Server } from 'iosignal' // 9.14.0 이상

const server = new Server({ port: 7777, dashboard: true })
// 브라우저에서 http://서버주소:7777/dashboard

기본은 꺼짐입니다. 페이지는 패키지 안에 들어 있어 인터넷이 없는 곳에서도 열립니다.

보여 주는 것​

패널내용
서버CPU, 이벤트 루프 지연(p99)과 사용률, 메모리 게이지, 5분 부하 그래프, 연결 수(WebSocket·TCP·로그인)
트래픽초당 받은·보낸 메시지와 바이트, 쿼터로 버린 메시지, 느린 연결과 밀린 송신량
호스트호스트마다 참가자 수, 초당 입력·방송·1:1 전송, 처리 시간, 위조 차단 수, 입력 그래프
게임 루프host.loop()의 목표 간격 대비 실제 틱 간격(p50·p99)과 처리 시간, host.report()로 보낸 값
참가자참가자별 입력 수, 로그인 여부, 참가 시간, 마지막 입력
이벤트입장·퇴장·위조 차단·오류 타임라인

보는 사람이 화면 위쪽에서 패널을 켜고 끌 수 있고, 선택은 그 브라우저에 기억됩니다. 그래프는 1초마다 갱신되며 라이트·다크 모드를 따릅니다.

설정​

new Server({
port: 7777,
dashboard: {
path: '/dashboard', // 페이지 주소. path + '/io.js'도 함께 씁니다
access: 'open', // 'open' | { token: '...' } | { login: { roles: ['admin'], cids: [] } }
panels: ['server', 'hosts'], // 처음 보여 줄 패널 (server, traffic, hosts, game, participants, events)
history: 300, // 그래프에 남길 초 (10~3600)
maxViewers: 20, // 동시에 보는 사람 수 (1~200)
showIdentities: false, // 참가자 CID·이름 보이기 (기본: access가 'open'이면 false)
},
})

보는 권한​

access동작쓰기 좋은 곳
'open' (기본)주소를 아는 누구나 봅니다. 참가자 CID는 앞 두 글자만 보입니다교실, 행사장, 같은 공유기 안
{ token: '…' }페이지에서 토큰을 입력해야 봅니다(8자 이상). 주소에 ?key=…를 붙여도 됩니다간단히 막고 싶을 때
{ login: { roles, cids } }이 서버의 인증으로 로그인한 연결 중, roles(기본 ['admin']) 이상의 역할이거나 cids에 있는 CID만 봅니다운영 서버

IP, 키, 메시지 내용은 어떤 방식에서도 보내지 않습니다. 대시보드는 읽기 전용이며 연결을 끊는 등의 조작은 없습니다.

직접 만든 HTTP 서버에 붙이기​

port 대신 httpServer를 넘기는 경우에는 요청 처리 맨 앞에서 server.dashboard.handle(req, res)를 부릅니다. 대시보드 주소면 응답하고 true를 돌려줍니다.

const http = createServer((req, res) => {
if (server.dashboard.handle(req, res)) return
// 나머지는 원래 처리
})
const server = new Server({ httpServer: http, dashboard: { path: '/ops/status' } })
http.listen(8080)

게임 상태 보내기​

호스트에 두 가지를 더하면 "게임 루프" 패널이 채워집니다.

const host = server.host('race', { inbound: ['race#in'], own: ['race#state'] })

// setInterval 대신: 33ms마다 실행하고, 틱 간격과 처리 시간을 자동으로 잽니다
host.loop(33, (now) => {
game.step(now)
host.publish('race#state', game.snapshot())
})

// 게임이 보여 주고 싶은 값 (숫자·짧은 글자·참거짓, 20개까지). null이면 지웁니다
host.report({ round: 3, players: game.players.size, leader: 'mina' })
  • host.loop()의 함수가 예외를 던지면 호스트의 'error'로 알리고 루프는 계속됩니다. 멈춤 함수를 돌려주며, host.close()가 모든 루프를 멈춥니다.
  • 호스트별 카운터는 host.counters에서 직접 읽을 수도 있습니다. 자세한 목록은 서버 API: 서버 호스트에 있습니다.

동작 방식​

  • 페이지는 IOSignal 클라이언트로 접속하고, 서버 안의 대시보드 전용 호스트(iosignal.dashboard)가 권한을 확인한 사람에게만 host.to()로 상태를 보냅니다. 채널을 구독해서 몰래 보거나 다른 클라이언트가 대시보드 화면을 위조할 수 없습니다.
  • 서버는 1초에 한 번 상태를 계산해 기록(history)을 남깁니다. 그래서 처음 열자마자 지난 그래프가 보입니다. 보는 사람이 없으면 보내지 않습니다.
  • 대시보드 연결도 연결 수와 트래픽에 포함됩니다. 페이지 위쪽에 지금 보는 사람 수가 나옵니다.
  • port로 서버를 열고 대시보드를 켜면, 서버가 HTTP 서버를 직접 만들어 웹소켓과 페이지를 같은 포트에서 제공합니다.