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>
2026-06-23 17:40:18 +09:00
parent 145b4611d3
commit bf2321f2d5
22 changed files with 1299 additions and 61 deletions
@@ -31,6 +31,7 @@
        "express-rate-limit": "^8.3.2",
        "helmet": "^8.1.0",
        "ioredis": "^5.11.1",
+        "livekit-server-sdk": "^2.15.5",
        "mammoth": "^1.12.0",
        "nest-winston": "^1.10.0",
        "passport": "^0.7.0",
@@ -798,6 +799,12 @@
        "url": "https://github.com/sponsors/Borewit"
      }
    },
+    "node_modules/@bufbuild/protobuf": {
+      "version": "1.10.1",
+      "resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-1.10.1.tgz",
+      "integrity": "sha512-wJ8ReQbHxsAfXhrf9ixl0aYbZorRuOWpBNzm8pL8ftmSxQx/wnJD5Eg861NwJU/czy2VXFIebCeZnZrI9rktIQ==",
+      "license": "(Apache-2.0 AND BSD-3-Clause)"
+    },
    "node_modules/@colors/colors": {
      "version": "1.5.0",
      "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.5.0.tgz",
@@ -2176,6 +2183,15 @@
      "integrity": "sha512-dXn3FZhPv0US+7dtJsIi2R+c7qWYiReoEh5zUntWCf4oSpMNib8FDhSoed6m3QyZdx5hK7iLFkYk3rNxwt8vTA==",
      "license": "MIT"
    },
+    "node_modules/@livekit/protocol": {
+      "version": "1.48.0",
+      "resolved": "https://registry.npmjs.org/@livekit/protocol/-/protocol-1.48.0.tgz",
+      "integrity": "sha512-fYHYgltH6YavAsokl3qsHLkBdQeKCl4UORVTub5crS3t8JtKFZ0uinHDFQ+XXdNKS6Ub9gcOjV+UHcDiqnWXoQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@bufbuild/protobuf": "^1.10.0"
+      }
+    },
    "node_modules/@lukeed/csprng": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/@lukeed/csprng/-/csprng-1.1.0.tgz",
@@ -6282,6 +6298,60 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/camelcase-keys": {
+      "version": "9.1.3",
+      "resolved": "https://registry.npmjs.org/camelcase-keys/-/camelcase-keys-9.1.3.tgz",
+      "integrity": "sha512-Rircqi9ch8AnZscQcsA1C47NFdaO3wukpmIRzYcDOrmvgt78hM/sj5pZhZNec2NM12uk5vTwRHZ4anGcrC4ZTg==",
+      "license": "MIT",
+      "dependencies": {
+        "camelcase": "^8.0.0",
+        "map-obj": "5.0.0",
+        "quick-lru": "^6.1.1",
+        "type-fest": "^4.3.2"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/camelcase-keys/node_modules/camelcase": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-8.0.0.tgz",
+      "integrity": "sha512-8WB3Jcas3swSvjIeA2yvCJ+Miyz5l1ZmB6HFb9R1317dt9LCQoswg/BGrmAmkWVEszSrrg4RwmO46qIm2OEnSA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/camelcase-keys/node_modules/quick-lru": {
+      "version": "6.1.2",
+      "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-6.1.2.tgz",
+      "integrity": "sha512-AAFUA5O1d83pIHEhJwWCq/RQcRukCkn/NSm2QsTEMle5f2hP0ChI2+3Xb051PZCkLryI/Ir1MVKviT2FIloaTQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/camelcase-keys/node_modules/type-fest": {
+      "version": "4.41.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.41.0.tgz",
+      "integrity": "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==",
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/caniuse-lite": {
      "version": "1.0.30001792",
      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001792.tgz",
@@ -9809,6 +9879,15 @@
        "url": "https://github.com/chalk/supports-color?sponsor=1"
      }
    },
+    "node_modules/jose": {
+      "version": "5.10.0",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-5.10.0.tgz",
+      "integrity": "sha512-s+3Al/p9g32Iq+oqXxkW//7jk2Vig6FF1CFqzVXoTUXt2qz89YWbL+OwS17NFYEvxC35n0FKeGO2LGYSxeM2Gg==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
    "node_modules/js-tokens": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -10064,6 +10143,21 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/livekit-server-sdk": {
+      "version": "2.15.5",
+      "resolved": "https://registry.npmjs.org/livekit-server-sdk/-/livekit-server-sdk-2.15.5.tgz",
+      "integrity": "sha512-Uzs4tVebvY4/+pO9pG1nMMVRDZPnOJolZIOWIiSEnUXFBywq+eNWHrR8mplKL8Qn13mSTQLjKVXfGCGTAMQeYg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@bufbuild/protobuf": "^1.10.1",
+        "@livekit/protocol": "^1.46.6",
+        "camelcase-keys": "^9.0.0",
+        "jose": "^5.1.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/load-esm": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/load-esm/-/load-esm-1.0.3.tgz",
@@ -10381,6 +10475,18 @@
        "sprintf-js": "~1.0.2"
      }
    },
+    "node_modules/map-obj": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/map-obj/-/map-obj-5.0.0.tgz",
+      "integrity": "sha512-2L3MIgJynYrZ3TYMriLDLWocz15okFakV6J12HXvMXDHui2x/zgChzg1u9mFFGbbGWE+GsLpQByt4POb9Or+uA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/math-intrinsics": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -47,6 +47,7 @@
    "express-rate-limit": "^8.3.2",
    "helmet": "^8.1.0",
    "ioredis": "^5.11.1",
+    "livekit-server-sdk": "^2.15.5",
    "mammoth": "^1.12.0",
    "nest-winston": "^1.10.0",
    "passport": "^0.7.0",
@@ -19,6 +19,7 @@ import { NotificationModule } from './modules/notification/notification.module';
 import { AiModule } from './modules/ai/ai.module';
 import { ProjectModule } from './modules/project/project.module';
 import { ScheduleModule } from './modules/schedule/schedule.module';
+import { MeetingModule } from './modules/meeting/meeting.module';

@Module({
  imports: [
@@ -100,6 +101,7 @@ import { ScheduleModule } from './modules/schedule/schedule.module';
    AiModule,
    ProjectModule,
    ScheduleModule,
+    MeetingModule,
  ],
  controllers: [AppController],
  providers: [
@@ -0,0 +1,16 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, Length, Matches } from 'class-validator';
+
+// 화상회의 입장 토큰 발급 요청 — 참여할 방 이름을 전달한다.
+export class CreateMeetingTokenDto {
+  @ApiProperty({
+    description: '참여할 회의 방 이름(영문/숫자/-/_ 만 허용)',
+    example: 'team-standup',
+  })
+  @IsString()
+  @Length(1, 64, { message: '방 이름은 1~64자여야 합니다.' })
+  @Matches(/^[A-Za-z0-9_-]+$/, {
+    message: '방 이름은 영문, 숫자, 하이픈(-), 밑줄(_)만 사용할 수 있습니다.',
+  })
+  roomName!: string;
+}
@@ -0,0 +1,26 @@
+import { Body, Controller, Post, UseGuards } from '@nestjs/common';
+import { ApiOperation, ApiResponse, ApiTags, ApiBearerAuth } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { CurrentUser } from '../auth/decorators/current-user.decorator';
+import type { PublicUser } from '../user/user.service';
+import { MeetingService, type MeetingTokenResult } from './meeting.service';
+import { CreateMeetingTokenDto } from './dto/create-meeting-token.dto';
+
+// 화상회의 컨트롤러 — 인증 사용자에게 LiveKit 입장 토큰을 발급한다.
+@ApiTags('화상회의')
+@ApiBearerAuth()
+@UseGuards(JwtAuthGuard)
+@Controller('meetings')
+export class MeetingController {
+  constructor(private readonly meetingService: MeetingService) {}
+
+  @Post('token')
+  @ApiOperation({ summary: 'LiveKit 입장 토큰 발급' })
+  @ApiResponse({ status: 201, description: '토큰 발급 성공' })
+  issueToken(
+    @CurrentUser() user: PublicUser,
+    @Body() dto: CreateMeetingTokenDto,
+  ): Promise<MeetingTokenResult> {
+    return this.meetingService.issueToken(user, dto.roomName);
+  }
+}
@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { MeetingController } from './meeting.controller';
+import { MeetingService } from './meeting.service';
+
+// 화상회의 모듈(단계 1) — LiveKit 입장 토큰 발급.
+// ConfigModule 은 전역(app.module)에서 등록되어 있어 별도 import 불필요.
+@Module({
+  controllers: [MeetingController],
+  providers: [MeetingService],
+  exports: [MeetingService],
+})
+export class MeetingModule {}
@@ -0,0 +1,67 @@
+import { HttpStatus, Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { AccessToken } from 'livekit-server-sdk';
+import { BusinessException } from '../../common/exceptions/business.exception';
+import type { PublicUser } from '../user/user.service';
+
+// 화상회의 토큰 발급 결과 — 브라우저는 자체 VITE_LIVEKIT_URL 로 접속하므로 URL 은 반환하지 않는다.
+export interface MeetingTokenResult {
+  token: string; // LiveKit 입장 JWT
+  roomName: string;
+  identity: string; // 참여자 식별자(사용자 ID)
+}
+
+// 화상회의 서비스(단계 1: 인프라 토대) — LiveKit 입장 토큰(JWT) 발급을 담당한다.
+// 미디어 전송은 LiveKit(SFU)에 위임하고, 여기서는 인증된 사용자에게 권한이 담긴 토큰만 만든다.
+@Injectable()
+export class MeetingService {
+  private readonly logger = new Logger(MeetingService.name);
+  private readonly apiKey: string;
+  private readonly apiSecret: string;
+
+  constructor(config: ConfigService) {
+    this.apiKey = (config.get<string>('LIVEKIT_API_KEY') ?? '').trim();
+    this.apiSecret = (config.get<string>('LIVEKIT_API_SECRET') ?? '').trim();
+    if (!this.enabled) {
+      this.logger.warn(
+        'LIVEKIT_API_KEY/LIVEKIT_API_SECRET 미설정 — 화상회의 토큰 발급 비활성화',
+      );
+    }
+  }
+
+  get enabled(): boolean {
+    return this.apiKey.length > 0 && this.apiSecret.length > 0;
+  }
+
+  // LiveKit 입장 토큰 발급
+  // 단계 1 에서는 모든 참여자에게 발행(publish)·구독(subscribe) 권한을 부여한다.
+  // (관리자/일반 사용자 역할에 따른 권한 분기는 단계 2에서 구현)
+  async issueToken(
+    user: PublicUser,
+    roomName: string,
+  ): Promise<MeetingTokenResult> {
+    if (!this.enabled) {
+      throw new BusinessException(
+        'SYS_001',
+        '화상회의 서비스가 아직 설정되지 않았습니다. 잠시 후 다시 시도해 주세요.',
+        HttpStatus.SERVICE_UNAVAILABLE,
+      );
+    }
+
+    const at = new AccessToken(this.apiKey, this.apiSecret, {
+      identity: user.id,
+      name: user.name,
+      ttl: '1h',
+    });
+    at.addGrant({
+      roomJoin: true,
+      room: roomName,
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: true,
+    });
+
+    const token = await at.toJwt();
+    return { token, roomName, identity: user.id };
+  }
+}