feat: 화상회의 단계 1 — LiveKit 기반 인프라 토대

LiveKit(SFU)에 미디어 전송을 위임하고, 앱은 입장 토큰 발급 + 회의 화면만
담당하는 구조로 단계 1(기본 연결)을 구현한다.

백엔드
- meeting 모듈: POST /api/meetings/token (JWT 인증)
  livekit-server-sdk 로 입장 JWT 발급(identity=userId, name, grants:
  roomJoin/publish/subscribe/publishData, TTL 1h). 단계 2에서 역할별 분기 예정.

프론트
- useMeeting(토큰 발급), useLiveKitRoom(연결/참여자/컨트롤 상태)
- ParticipantTile(카메라/마이크 트랙 attach, 본인 거울·음소거, 이니셜 플레이스홀더)
- MeetingPage(로비 + 영상 그리드), 라우트 /meeting/:room?, 사이드바 네비 추가
- VITE_LIVEKIT_URL 주입(build arg + dev 런타임 env)

인프라/설정
- 개발 미디어 서버는 LiveKit Cloud 사용(로컬 self-host 는 WSL2/Docker Desktop
  WebRTC 네트워킹 제약으로 제외). env 만으로 운영 전환 가능.
- livekit/livekit.yaml 은 단계 6 셀프호스팅 참고용으로 보관.
- 화상회의_화면명세.md: 현재 화면 기능/구조/데이터 계약 문서(UI 개편 참고).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-23 17:40:18 +09:00
parent 145b4611d3
commit bf2321f2d5
22 changed files with 1299 additions and 61 deletions
@@ -0,0 +1,164 @@
<script setup lang="ts">
// 참여자 1명의 영상 타일 — 카메라 트랙을 <video>, (원격) 마이크 트랙을 <audio> 에 연결한다.
// 로컬 참여자 오디오는 에코 방지를 위해 재생하지 않는다.
import { onBeforeUnmount, onMounted, ref } from 'vue'
import { Track, ParticipantEvent, type Participant } from 'livekit-client'
const props = defineProps<{ participant: Participant; isLocal?: boolean }>()
const videoEl = ref<HTMLVideoElement | null>(null)
const audioEl = ref<HTMLAudioElement | null>(null)
const hasVideo = ref(false)
const micOn = ref(false)
// 표시 이름 — 토큰에 담은 name, 없으면 식별자
const displayName = ref(props.participant.name || props.participant.identity)
// 현재 트랙 상태를 DOM 에 반영
function sync() {
const p = props.participant
displayName.value = p.name || p.identity
micOn.value = p.isMicrophoneEnabled
const camPub = p.getTrackPublication(Track.Source.Camera)
if (camPub?.track && videoEl.value) {
camPub.track.attach(videoEl.value)
hasVideo.value = !camPub.isMuted
} else {
hasVideo.value = false
}
if (!props.isLocal) {
const micPub = p.getTrackPublication(Track.Source.Microphone)
if (micPub?.track && audioEl.value) micPub.track.attach(audioEl.value)
}
}
onMounted(() => {
sync()
const p = props.participant
p.on(ParticipantEvent.TrackSubscribed, sync)
p.on(ParticipantEvent.TrackUnsubscribed, sync)
p.on(ParticipantEvent.LocalTrackPublished, sync)
p.on(ParticipantEvent.LocalTrackUnpublished, sync)
p.on(ParticipantEvent.TrackMuted, sync)
p.on(ParticipantEvent.TrackUnmuted, sync)
})
onBeforeUnmount(() => {
const p = props.participant
p.off(ParticipantEvent.TrackSubscribed, sync)
p.off(ParticipantEvent.TrackUnsubscribed, sync)
p.off(ParticipantEvent.LocalTrackPublished, sync)
p.off(ParticipantEvent.LocalTrackUnpublished, sync)
p.off(ParticipantEvent.TrackMuted, sync)
p.off(ParticipantEvent.TrackUnmuted, sync)
})
</script>
<template>
<div class="tile">
<!-- 영상: 로컬은 좌우 반전(거울)으로 표시 -->
<video
ref="videoEl"
class="vid"
:class="{ mirror: props.isLocal, hidden: !hasVideo }"
autoplay
playsinline
:muted="props.isLocal"
/>
<!-- 영상이 없을 이름 이니셜 표시 -->
<div
v-if="!hasVideo"
class="placeholder"
>
<span class="initial">{{ displayName.charAt(0) }}</span>
</div>
<!-- 원격 오디오 -->
<audio
v-if="!props.isLocal"
ref="audioEl"
autoplay
/>
<!-- 하단 정보 -->
<div class="meta">
<span
class="mic"
:class="{ off: !micOn }"
:title="micOn ? '마이크 켜짐' : '마이크 꺼짐'"
>{{ micOn ? '🎙' : '🔇' }}</span>
<span class="name">{{ displayName }}{{ props.isLocal ? ' (나)' : '' }}</span>
</div>
</div>
</template>
<style scoped>
.tile {
position: relative;
aspect-ratio: 16 / 9;
background: #1b1d23;
border-radius: 0.625rem;
overflow: hidden;
border: 1px solid var(--border);
}
.vid {
width: 100%;
height: 100%;
object-fit: cover;
display: block;
}
.vid.mirror {
transform: scaleX(-1);
}
.vid.hidden {
display: none;
}
.placeholder {
position: absolute;
inset: 0;
display: flex;
align-items: center;
justify-content: center;
background: #1b1d23;
}
.initial {
width: 3.5rem;
height: 3.5rem;
border-radius: 50%;
background: var(--accent);
color: #fff;
display: flex;
align-items: center;
justify-content: center;
font-size: 1.5rem;
font-weight: 700;
text-transform: uppercase;
}
.meta {
position: absolute;
left: 0.5rem;
bottom: 0.5rem;
display: flex;
align-items: center;
gap: 0.375rem;
padding: 0.1875rem 0.5rem;
background: rgba(0, 0, 0, 0.55);
border-radius: 0.375rem;
max-width: calc(100% - 1rem);
}
.meta .name {
color: #fff;
font-size: 0.75rem;
font-weight: 600;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.meta .mic {
font-size: 0.75rem;
line-height: 1;
}
.meta .mic.off {
opacity: 0.6;
}
</style>
+114
View File
@@ -0,0 +1,114 @@
import { ref, shallowRef } from 'vue'
import { Room, RoomEvent, type Participant } from 'livekit-client'
// 브라우저가 접속할 LiveKit WebSocket URL (build arg/env 로 주입, 미설정 시 로컬 기본값)
const LIVEKIT_URL = import.meta.env.VITE_LIVEKIT_URL || 'ws://localhost:7880'
// LiveKit 방 연결/생명주기 관리 Composable
// 미디어 전송 자체는 LiveKit SDK 가 담당하고, 여기서는 연결 상태와 참여자 목록만 반응형으로 노출한다.
export function useLiveKitRoom() {
// Room 인스턴스는 깊은 반응형이 불필요(내부적으로 자체 이벤트 관리) → shallowRef
const room = shallowRef<Room | null>(null)
// 참여자 배열도 shallowRef — Participant 는 비공개 멤버가 있는 클래스라 깊은 언랩 시
// 구조적 타입으로 바뀌어 타입 불일치가 난다. 매번 배열을 통째로 교체하므로 shallow 로 충분.
const participants = shallowRef<Participant[]>([])
const connected = ref(false)
const connecting = ref(false)
const micEnabled = ref(false)
const camEnabled = ref(false)
const errorMsg = ref<string | null>(null)
// 로컬 + 원격 참여자 목록 갱신(진행자 화면 구성은 단계 3에서 고도화)
function refresh() {
const r = room.value
if (!r) {
participants.value = []
return
}
participants.value = [
r.localParticipant,
...Array.from(r.remoteParticipants.values()),
]
}
function onDisconnected() {
connected.value = false
participants.value = []
}
// 방 입장 — 토큰으로 연결 후 카메라/마이크 발행
async function connect(token: string): Promise<void> {
if (connecting.value || connected.value) return
connecting.value = true
errorMsg.value = null
try {
const r = new Room({ adaptiveStream: true, dynacast: true })
r.on(RoomEvent.ParticipantConnected, refresh)
.on(RoomEvent.ParticipantDisconnected, refresh)
.on(RoomEvent.TrackSubscribed, refresh)
.on(RoomEvent.TrackUnsubscribed, refresh)
.on(RoomEvent.LocalTrackPublished, refresh)
.on(RoomEvent.LocalTrackUnpublished, refresh)
.on(RoomEvent.Disconnected, onDisconnected)
await r.connect(LIVEKIT_URL, token)
room.value = r
connected.value = true
// 카메라/마이크 권한 요청 및 발행 (실패해도 연결은 유지)
try {
await r.localParticipant.enableCameraAndMicrophone()
camEnabled.value = true
micEnabled.value = true
} catch {
errorMsg.value =
'카메라/마이크를 사용할 수 없습니다. 권한을 확인해 주세요.'
}
refresh()
} catch (e) {
errorMsg.value = e instanceof Error ? e.message : '연결에 실패했습니다.'
await disconnect()
} finally {
connecting.value = false
}
}
// 방 나가기
async function disconnect(): Promise<void> {
const r = room.value
if (r) await r.disconnect()
room.value = null
connected.value = false
camEnabled.value = false
micEnabled.value = false
participants.value = []
}
async function toggleMic(): Promise<void> {
const r = room.value
if (!r) return
micEnabled.value = !micEnabled.value
await r.localParticipant.setMicrophoneEnabled(micEnabled.value)
}
async function toggleCam(): Promise<void> {
const r = room.value
if (!r) return
camEnabled.value = !camEnabled.value
await r.localParticipant.setCameraEnabled(camEnabled.value)
refresh()
}
return {
participants,
connected,
connecting,
micEnabled,
camEnabled,
errorMsg,
connect,
disconnect,
toggleMic,
toggleCam,
}
}
+22
View File
@@ -0,0 +1,22 @@
import { useApi } from './useApi'
// 화상회의 토큰 응답 — 백엔드 MeetingTokenResult 와 1:1
export interface MeetingToken {
token: string // LiveKit 입장 JWT
roomName: string
identity: string // 참여자 식별자(사용자 ID)
}
// 화상회의 도메인 API Composable — 인터셉터가 success/data 를 언래핑
export function useMeeting() {
const api = useApi()
// LiveKit 입장 토큰 발급
async function getToken(roomName: string): Promise<MeetingToken> {
return (await api.post('/meetings/token', {
roomName,
})) as unknown as MeetingToken
}
return { getToken }
}
+27 -1
View File
@@ -29,9 +29,10 @@ function toggleCollapse() {
const mobileOpen = ref(false)
// 현재 경로 기준으로 사이드바 네비 활성 항목을 판별
const activeNav = computed<'tasks' | 'projects' | 'schedule'>(() => {
const activeNav = computed<'tasks' | 'projects' | 'schedule' | 'meeting'>(() => {
if (route.path.startsWith('/projects')) return 'projects'
if (route.path.startsWith('/schedule')) return 'schedule'
if (route.path.startsWith('/meeting')) return 'meeting'
return 'tasks'
})
@@ -201,6 +202,31 @@ async function onLogout() {
</svg>
<span>프로젝트</span>
</RouterLink>
<RouterLink
to="/meeting"
class="nav-item"
title="화상회의"
:class="{ active: activeNav === 'meeting' }"
>
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
>
<path d="m22 8-6 4 6 4V8Z" />
<rect
x="2"
y="6"
width="14"
height="12"
rx="2"
/>
</svg>
<span>화상회의</span>
</RouterLink>
</nav>
<!-- 하단: 접기 토글 + 사용자 프로필 + 메뉴(위로 펼침) -->
+345
View File
@@ -0,0 +1,345 @@
<script setup lang="ts">
// 화상회의 (단계 1: 인프라 토대) — 방 입장 → LiveKit 연결 → 참여자 영상 그리드
// 진행자/일반 권한 분기(단계 2), 화면 승격/페이지네이션(단계 3)은 후속 단계에서 구현한다.
import { computed, onBeforeUnmount, ref } from 'vue'
import { useRoute, useRouter } from 'vue-router'
import AppShell from '@/layouts/AppShell.vue'
import ParticipantTile from '@/components/meeting/ParticipantTile.vue'
import { useMeeting } from '@/composables/useMeeting'
import { useLiveKitRoom } from '@/composables/useLiveKitRoom'
const route = useRoute()
const router = useRouter()
const meetingApi = useMeeting()
const {
participants,
connected,
connecting,
micEnabled,
camEnabled,
errorMsg,
connect,
disconnect,
toggleMic,
toggleCam,
} = useLiveKitRoom()
// 방 이름 — 공유 링크(/meeting/:room)에서 가져오거나 직접 입력
const roomName = ref(
typeof route.params.room === 'string' ? route.params.room : '',
)
const joinError = ref<string | null>(null)
const ROOM_PATTERN = /^[A-Za-z0-9_-]+$/
// 입장 — 토큰 발급 후 연결, 공유 가능한 URL 로 치환
async function onJoin() {
const name = roomName.value.trim()
if (!name) {
joinError.value = '방 이름을 입력해 주세요.'
return
}
if (!ROOM_PATTERN.test(name)) {
joinError.value = '방 이름은 영문, 숫자, 하이픈(-), 밑줄(_)만 사용할 수 있습니다.'
return
}
joinError.value = null
try {
const { token } = await meetingApi.getToken(name)
await connect(token)
// 주소창을 공유 가능한 형태로 갱신(히스토리 오염 방지 위해 replace)
if (route.params.room !== name) {
void router.replace(`/meeting/${name}`)
}
} catch {
// 토큰 발급 실패는 API 인터셉터에서 전역 처리
joinError.value = '입장에 실패했습니다. 잠시 후 다시 시도해 주세요.'
}
}
// 나가기 — 연결 해제 후 로비로
async function onLeave() {
await disconnect()
void router.replace('/meeting')
}
const participantCount = computed(() => participants.value.length)
// 화면 이탈 시 연결 정리
onBeforeUnmount(() => {
void disconnect()
})
</script>
<template>
<AppShell>
<!-- 로비 (미연결) -->
<div
v-if="!connected"
class="page"
>
<div class="pagehead">
<h1>화상회의</h1>
</div>
<p class="lede">
이름을 입력해 입장하세요. 같은 이름으로 들어온 사람끼리 연결됩니다.
</p>
<form
class="lobby card"
@submit.prevent="onJoin"
>
<div class="fblock">
<div class="flabel">
<span class="req">*</span> 이름
</div>
<div class="fhint">
영문·숫자·하이픈(-)·밑줄(_) 사용할 있습니다.
</div>
<input
v-model="roomName"
type="text"
class="tinput"
placeholder="예: team-standup"
maxlength="64"
:disabled="connecting"
>
<p
v-if="joinError"
class="err"
>
{{ joinError }}
</p>
</div>
<div class="form-footer">
<button
class="btn primary"
type="submit"
:disabled="connecting"
>
{{ connecting ? '입장 중…' : '입장하기' }}
</button>
</div>
</form>
</div>
<!-- 회의실 (연결됨) -->
<div
v-else
class="room"
>
<div class="room-bar">
<div class="room-info">
<span class="room-name">{{ roomName }}</span>
<span class="room-count">참여자 {{ participantCount }}</span>
</div>
<div class="controls">
<button
class="ctrl"
:class="{ off: !micEnabled }"
:title="micEnabled ? '마이크 끄기' : '마이크 켜기'"
@click="toggleMic"
>
{{ micEnabled ? '🎙 마이크' : '🔇 마이크' }}
</button>
<button
class="ctrl"
:class="{ off: !camEnabled }"
:title="camEnabled ? '카메라 끄기' : '카메라 켜기'"
@click="toggleCam"
>
{{ camEnabled ? '📹 카메라' : '🚫 카메라' }}
</button>
<button
class="ctrl leave"
@click="onLeave"
>
나가기
</button>
</div>
</div>
<p
v-if="errorMsg"
class="room-err"
>
{{ errorMsg }}
</p>
<div class="grid">
<ParticipantTile
v-for="(p, i) in participants"
:key="p.sid || p.identity"
:participant="p"
:is-local="i === 0"
/>
</div>
</div>
</AppShell>
</template>
<style scoped>
.page {
max-width: 36rem;
}
.pagehead {
padding: 1.125rem 0 0.375rem;
}
.pagehead h1 {
font-size: 1.375rem;
font-weight: 700;
letter-spacing: -0.025rem;
}
.lede {
color: var(--text-2);
font-size: 0.844rem;
margin-bottom: 1.25rem;
}
.card {
background: var(--panel);
border: 1px solid var(--border);
border-radius: 0.625rem;
}
.fblock {
padding: 1.375rem 1.5rem;
}
.flabel {
font-size: 0.8125rem;
font-weight: 600;
color: var(--text);
margin-bottom: 0.25rem;
display: flex;
align-items: center;
gap: 0.4375rem;
}
.flabel .req {
color: var(--accent);
font-weight: 700;
}
.fhint {
font-size: 0.781rem;
color: var(--text-3);
margin-bottom: 0.6875rem;
}
.tinput {
width: 100%;
height: 2.5rem;
border: 1px solid var(--border-strong);
border-radius: var(--radius);
padding: 0 0.75rem;
font-family: inherit;
font-size: 0.875rem;
color: var(--text);
background: #fff;
}
.tinput:focus {
outline: none;
border-color: var(--accent);
box-shadow: 0 0 0 3px var(--accent-weak);
}
.err {
margin-top: 0.5rem;
font-size: 0.781rem;
color: var(--red);
}
.form-footer {
display: flex;
justify-content: flex-end;
padding: 1rem 1.5rem;
border-top: 1px solid var(--border);
background: #fafbfc;
border-radius: 0 0 0.625rem 0.625rem;
}
.btn {
height: 2.25rem;
padding: 0 1.25rem;
border-radius: var(--radius);
font-size: 0.844rem;
font-weight: 600;
font-family: inherit;
cursor: pointer;
border: none;
}
.btn.primary {
background: var(--accent);
color: #fff;
}
.btn.primary:hover {
background: var(--accent-hover);
}
.btn.primary:disabled {
opacity: 0.6;
cursor: default;
}
/* 회의실 */
.room {
display: flex;
flex-direction: column;
gap: 0.875rem;
padding-top: 1rem;
}
.room-bar {
display: flex;
align-items: center;
justify-content: space-between;
flex-wrap: wrap;
gap: 0.5rem;
}
.room-info {
display: flex;
align-items: baseline;
gap: 0.625rem;
}
.room-name {
font-size: 1.125rem;
font-weight: 700;
}
.room-count {
font-size: 0.781rem;
color: var(--text-3);
}
.controls {
display: flex;
gap: 0.5rem;
}
.ctrl {
height: 2.25rem;
padding: 0 0.875rem;
border-radius: var(--radius);
border: 1px solid var(--border-strong);
background: #fff;
color: var(--text-2);
font-size: 0.8125rem;
font-weight: 600;
font-family: inherit;
cursor: pointer;
}
.ctrl:hover {
border-color: var(--accent);
color: var(--accent);
}
.ctrl.off {
background: var(--amber-weak);
border-color: var(--amber-border);
color: var(--amber);
}
.ctrl.leave {
background: var(--red);
border-color: var(--red);
color: #fff;
}
.ctrl.leave:hover {
opacity: 0.9;
color: #fff;
}
.room-err {
font-size: 0.781rem;
color: var(--amber);
}
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
gap: 0.75rem;
}
</style>
+7
View File
@@ -108,6 +108,13 @@ const routes: RouteRecordRaw[] = [
component: () => import('@/pages/relay/SchedulePage.vue'),
meta: { requiresAuth: true },
},
{
// 화상회의 — LiveKit 기반(단계 1: 방 입장/연결). :room 으로 공유 링크 가능
path: '/meeting/:room?',
name: 'meeting',
component: () => import('@/pages/relay/MeetingPage.vue'),
meta: { requiresAuth: true },
},
{
path: '/:pathMatch(.*)*',
name: 'not-found',