외향형 개발자 성장기

WebSocket 채팅 시스템

Red_Horse — Sun, 22 Mar 2026 19:19:35 +0900

기반 구성 사항 : https://red-horse.tistory.com/167

WebSocket(Chat System)

WebSocket?HTTP는 요청-응답 구조입니다.클라이언트가 요청하면 서버가 응답하고 연결을 닫습니다.서버가 먼저 데이터를 보낼 방법이 없는데 WebSocket은 이 문제를 핸드세이크로 해결합니다.클라이

red-horse.tistory.com

채팅 시스템 구조
WebSocket/Chat/
├── ChatMessage.cs           ← 메시지 프로토콜 (JSON)
├── ChatRoomManager.cs       ← 룸 멤버십 관리
└── ChatWebSocketHandler.cs  ← 채팅 이벤트 처리

Components/Pages/Chat/
├── ChatPage.razor           ← 채팅 UI
├── ChatPageBase.cs          ← JS interop + Blazor 상태 관리
└── ChatPage.razor.css       ← 스타일

wwwroot/js/
└── chat.js                  ← 브라우저 WebSocket 클라이언트

메시지 프로토콜 설계

서버와 클라이언트가 주고받는 모든 메시지는 JSON 형식으로 통일했습니다.

type 필드로 메시지 종류를 구분합니다.

ChatMessage 모델

public class ChatMessage
{
    [JsonPropertyName("type")]
    public string Type { get; set; } = string.Empty;

    [JsonPropertyName("roomId")]
    public string? RoomId { get; set; }

    [JsonPropertyName("userId")]
    public string? UserId { get; set; }

    [JsonPropertyName("userName")]
    public string? UserName { get; set; }

    [JsonPropertyName("content")]
    public string? Content { get; set; }

    [JsonPropertyName("timestamp")]
    public string Timestamp { get; set; } = DateTime.UtcNow.ToString("o");
}

전체 메시지 흐름

클라이언트 연결
  └─ 서버 → 클라이언트: { "type": "connected", "content": "<connectionId>" }
  └─ 클라이언트 → 서버: { "type": "join", "roomId": "general", "userId": "...", "userName": "홍길동" }
  └─ 서버 → 룸 전체:   { "type": "joined", "roomId": "general", "userId": "...", "userName": "홍길동" }

채팅
  └─ 클라이언트 → 서버: { "type": "message", "content": "안녕하세요!" }
  └─ 서버 → 룸 전체:   { "type": "message", "roomId": "general", "userId": "...", "userName": "홍길동", "content": "안녕하세요!", "timestamp": "..." }

퇴장
  └─ 클라이언트 → 서버: { "type": "leave" }
  └─ 서버 → 룸 전체:   { "type": "left", "roomId": "general", "userId": "...", "userName": "홍길동" }

연결 유지 (30초 주기)
  └─ 서버 → 클라이언트: { "type": "ping" }
  └─ 클라이언트 → 서버: { "type": "pong" }  ← Blazor가 자동 응답

type	방향	설명
connected	Server -> Client	연결 성공, content에 connectionId 포함
join	Client -> Server	룸 입장 요청
joined	Server -> Client	룸 전체에 입장 알림 브로드캐스트
message	양방향	채팅 메시지
leave	Client -> Server	퇴장 요청
left	Server -> Client	퇴장 알ㄹ미 브로드캐스트
ping / pong	Server -> Client	연결 유지 확인
error	Server -> Client	오류 메시지

public class ChatRoomManager
{
    // roomId → RoomEntry (멤버 집합 + lock 객체 묶음)
    private readonly ConcurrentDictionary<string, RoomEntry> _rooms = new();
    // connectionId → roomId (한 연결은 하나의 룸만 참여)
    private readonly ConcurrentDictionary<string, string> _connectionRoom = new();

    public void JoinRoom(string roomId, string connectionId)
    {
        var entry = _rooms.GetOrAdd(roomId, _ => new RoomEntry());
        lock (entry)
        {
            entry.Members.Add(connectionId);
        }
        _connectionRoom[connectionId] = roomId;
    }

    public string? LeaveRoom(string connectionId)
    {
        if (!_connectionRoom.TryRemove(connectionId, out var roomId)) return null;

        if (_rooms.TryGetValue(roomId, out var entry))
            lock (entry) { entry.Members.Remove(connectionId); }

        return roomId;
    }

    public IReadOnlyList<string> GetRoomMembers(string roomId)
    {
        if (_rooms.TryGetValue(roomId, out var entry))
            lock (entry) { return entry.Members.ToList(); }
        return [];
    }

    private sealed class RoomEntry
    {
        public HashSet<string> Members { get; } = [];
    }
}

Room 멤버십 관리

- Chat Room접속 관리에 대한 전반적인 프로세스를 관리합니다.

추후 개선 방향성

- 현재 User(1) : Room(1) 연결 방식 1:N으로 구성 변경

- DB 구성을 통한 과거 채팅 내역 관리 구조 적용

핵심 처리 로직

public class ChatWebSocketHandler : WebSocketHandlerBase
{
    private readonly ChatRoomManager _roomManager;
    private readonly ConcurrentDictionary<string, (int count, DateTime windowStart)> _rateLimit = new();

    private const int MaxContentLength = 1000;
    private const int MaxRoomIdLength = 50;
    private const int MaxUserNameLength = 30;
    private const int RateLimitPerSecond = 5;

    public override async Task ReceiveAsync(WebSocketConnection connection, string message)
    {
        // 1. Rate Limiting 체크
        if (IsRateLimited(connection.ConnectionId))
        {
            await SendErrorAsync(connection.ConnectionId, "Too many messages. Slow down.");
            return;
        }

        // 2. JSON 파싱
        var msg = JsonSerializer.Deserialize<ChatMessage>(message, JsonOptions);
        if (msg is null) return;

        // 3. 타입별 분기
        switch (msg.Type)
        {
            case "join":    await HandleJoinAsync(connection, msg);    break;
            case "message": await HandleMessageAsync(connection, msg); break;
            case "leave":   await HandleLeaveAsync(connection);        break;
        }
    }
}

WebSocketHandlerBase를 상속하고, 메시지 타입별로 처리합니다.

1. Join 처피 - UserId / UserName 서버 측 저장

private async Task HandleJoinAsync(WebSocketConnection connection, ChatMessage msg)
{
    // 입력 검증
    if (string.IsNullOrWhiteSpace(msg.RoomId) || msg.RoomId.Length > MaxRoomIdLength)
    {
        await SendErrorAsync(connection.ConnectionId, "Invalid roomId");
        return;
    }
    if (string.IsNullOrWhiteSpace(msg.UserName) || msg.UserName.Length > MaxUserNameLength)
    {
        await SendErrorAsync(connection.ConnectionId, "Invalid userName");
        return;
    }

    // 이미 다른 룸에 있으면 먼저 나가기
    if (_roomManager.GetUserRoom(connection.ConnectionId) is not null)
        await HandleLeaveAsync(connection);

    // UserId와 UserName을 서버(connection 객체)에 저장
    // 이후 메시지에서 클라이언트가 보내는 값은 무시
    connection.UserId = msg.UserId ?? connection.ConnectionId;
    connection.UserName = msg.UserName.Trim();

    _roomManager.JoinRoom(msg.RoomId, connection.ConnectionId);

    await BroadcastToRoomAsync(msg.RoomId, new ChatMessage
    {
        Type = "joined",
        RoomId = msg.RoomId,
        UserId = connection.UserId,
        UserName = connection.UserName  // 서버에 저장된 값 사용
    });
}

connection.UserName = msg.UserName에서 클라이언트 값을 서버에 저장하고, 이후 모든 메시지에서는 connection.UserName(서버 저장값)을 사용합니다. 클라이언트가 메시지마다 다른 이름을 보내도 무시됩니다.

2. Message 처리(브로드캐스트)

private async Task HandleMessageAsync(WebSocketConnection connection, ChatMessage msg)
{
    var roomId = _roomManager.GetUserRoom(connection.ConnectionId);
    if (roomId is null)
    {
        await SendErrorAsync(connection.ConnectionId, "Join a room first");
        return;
    }

    if (string.IsNullOrWhiteSpace(msg.Content)) return;
    if (msg.Content.Length > MaxContentLength)
    {
        await SendErrorAsync(connection.ConnectionId, $"Message too long (max {MaxContentLength})");
        return;
    }

    await BroadcastToRoomAsync(roomId, new ChatMessage
    {
        Type = "message",
        RoomId = roomId,
        UserId = connection.UserId,
        UserName = connection.UserName,  // 클라이언트 값 무시
        Content = msg.Content.Trim()
    });
}

private async Task BroadcastToRoomAsync(string roomId, ChatMessage msg, string? exclude = null)
{
    var json = JsonSerializer.Serialize(msg);
    var tasks = _roomManager.GetRoomMembers(roomId)
        .Where(id => id != exclude)
        .Select(id => ConnectionManager.SendAsync(id, json));

    await Task.WhenAll(tasks); // 룸 내 전체 전송을 병렬로
}

3. Rate Liniting(초당 메시지 제한)

private bool IsRateLimited(string connectionId)
{
    var now = DateTime.UtcNow;
    var state = _rateLimit.GetOrAdd(connectionId, _ => (0, now));

    int newCount;
    DateTime windowStart;

    if ((now - state.windowStart).TotalSeconds >= 1)
    {
        // 1초 창이 지나면 카운터 초기화
        newCount = 1;
        windowStart = now;
    }
    else
    {
        newCount = state.count + 1;
        windowStart = state.windowStart;
    }

    _rateLimit[connectionId] = (newCount, windowStart);
    return newCount > RateLimitPerSecond; // 초당 5개 초과 시 차단
}

슬라이딩 윈도우 대신 고정 윈도우 방식입니다. 구현이 단순하고 채팅같은 UX에서는 충분합니다. 초당 5개 초과 메시지를 보내면 오류 메시지를 받고 해당 메시지는 무시됩니다. 연결을 끊지 않기 때문에 정상 사용자가 실수로 빠르게 입력하는 경우에 친화적입니다.

프론트엔트 - Blazor + JavaScript

JavaScript를 사용해야 하는 이유?

Blazor Server는 이미 내부적으로 SignalR WebSocket을 사용해 서버와 통신합니다. C# 코드에서 두 번째 WebSocket 연결을 직접 열 수 없습니다. 브라우저에서 WebSocket을 다루는 것은 JavaScript의 영역입니다.

구조
Blazor(C#) ←── JS Interop ───→ chat.js ←── WebSocket ───→ 서버

Blazor에서 JS 함수를 호출하거, JS에서 서버로부터 메시지를 받으면 다시 Blazor 메서드를 호출합니다.

chat.js - 브라우저 WebSocket 클라이언트

window.ChatWs = (() => {
    let ws = null;
    let dotnetRef = null;
    let wsUrl = null;
    let reconnectTimer = null;
    let reconnectDelay = 1000;       // 초기 재연결 대기 1초
    const maxReconnectDelay = 30000; // 최대 30초
    let manualClose = false;

    function connect(dotnetObjRef, url) {
        if (ws && ws.readyState !== WebSocket.CLOSED) {
            manualClose = true;
            ws.close();
        }
        dotnetRef = dotnetObjRef;
        wsUrl = url;
        manualClose = false;
        _open();
    }

    function _open() {
        ws = new WebSocket(wsUrl);

        ws.onopen = () => {
            reconnectDelay = 1000; // 성공 시 딜레이 초기화
        };

        ws.onmessage = (event) => {
            if (dotnetRef) {
                dotnetRef.invokeMethodAsync('OnMessageReceived', event.data);
            }
        };

        ws.onclose = () => {
            dotnetRef?.invokeMethodAsync('OnMessageReceived',
                JSON.stringify({ type: 'disconnected' }));

            // 자동 재연결 (지수 백오프)
            if (!manualClose) {
                reconnectTimer = setTimeout(() => {
                    _open();
                    reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
                }, reconnectDelay);
            }
        };
    }

    function send(message) {
        if (ws && ws.readyState === WebSocket.OPEN) ws.send(message);
    }

    function disconnect() {
        manualClose = true;
        clearTimeout(reconnectTimer);
        if (ws) { ws.close(); ws = null; }
        dotnetRef = null;
    }

    return { connect, send, disconnect };
})();

지수 백오프(Exponential Backoff): 네트워크 일시 끊김 후 재연결을 시도할 때, 서버가 부하 상태라면 모든 클라이언트가 동시에 재연결을 시도해 부하를 더 키웁니다. 대기 시간을 1초 → 2초 → 4초 → ... → 30초로 늘려가면서 이를 방지합니다.

manualClose 플래그: 사용자가 "나가기" 버튼을 눌러 명시적으로 연결을 닫는 경우와, 네트워크 문제로 연결이 끊기는 경우를 구분합니다. 전자는 재연결하지 않고, 후자만 재연결합니다.

ChatPageBase.cs - Blazor 상태 관리

public class ChatPageBase : ComponentBase, IAsyncDisposable
{
    [Inject] private IJSRuntime JS { get; set; } = null!;
    [Inject] private NavigationManager Nav { get; set; } = null!;

    protected string UserName { get; set; } = string.Empty;
    protected string RoomId { get; set; } = "general";
    protected string InputText { get; set; } = string.Empty;
    protected string? ConnectionId { get; private set; }
    protected bool IsConnected { get; private set; }
    protected List<ChatDisplayMessage> Messages { get; } = [];

    private DotNetObjectReference<ChatPageBase>? _dotnetRef;

    protected async Task ConnectAsync()
    {
        _dotnetRef = DotNetObjectReference.Create(this);

        // http:// → ws://, https:// → wss:// 자동 변환
        var wsUrl = Nav.BaseUri
            .Replace("https://", "wss://")
            .Replace("http://", "ws://")
            .TrimEnd('/') + "/ws/chat";

        await JS.InvokeVoidAsync("ChatWs.connect", _dotnetRef, wsUrl);
    }

    // JS → C# 콜백 (JSInvokable)
    [JSInvokable]
    public async Task OnMessageReceived(string json)
    {
        var msg = JsonSerializer.Deserialize<ChatMessage>(json, ...);
        if (msg is null) return;

        switch (msg.Type)
        {
            case "connected":
                ConnectionId = msg.Content;
                IsConnected = true;
                // 연결 직후 자동으로 룸 입장 요청
                await SendWsAsync(new ChatMessage
                {
                    Type = "join",
                    RoomId = RoomId,
                    UserId = ConnectionId,
                    UserName = UserName
                });
                break;

            case "joined":
            case "left":
            case "message":
                Messages.Add(new ChatDisplayMessage(msg));
                await ScrollToBottomAsync();
                break;

            case "ping":
                await SendWsAsync(new ChatMessage { Type = "pong" });
                return; // UI 갱신 불필요

            case "pong":
                return; // 무시

            case "disconnected":
                IsConnected = false;
                ConnectionId = null;
                break;

            case "error":
                Messages.Add(new ChatDisplayMessage(new ChatMessage
                {
                    Type = "system",
                    Content = $"[오류] {msg.Content}"
                }));
                break;
        }

        await InvokeAsync(StateHasChanged); // Blazor UI 갱신
    }

    public async ValueTask DisposeAsync()
    {
        if (IsConnected) await DisconnectAsync(); // 페이지 벗어날 때 자동 정리
        _dotnetRef?.Dispose();
    }
}

DotNetObjectReference: JS에서 C# 메서드(OnMessageReceived)를 호출하기 위한 핸들입니다. Dispose를 반드시 호출해야 메모리 누수가 없습니다. DisposeAsync에서 처리했습니다.

InvokeAsync(StateHasChanged): WebSocket 메시지는 Blazor의 렌더링 스레드 외부에서 도착합니다. InvokeAsync로 렌더링 스레드에 UI 갱신을 예약해야 합니다.

WebSocket

Red_Horse — Sun, 22 Mar 2026 18:52:06 +0900

WebSocket?

HTTP는 요청-응답 구조입니다.

클라이언트가 요청하면 서버가 응답하고 연결을 닫습니다.

서버가 먼저 데이터를 보낼 방법이 없는데 WebSocket은 이 문제를 핸드세이크로 해결합니다.

클라이언트 -> 서버: HTTP Upgrade 요청
서버 -> 클라이언트: 101 Switching Protocols

이후: TCP 연결 위에서 양방향 통신(연결 유지)

한 번 연결되면 서버도 먼저 데이터를 보낼 수 있고, 연결은 명시적으로 닫을 때까지 유지됩니다. TCP 위의 애플리케이션 프로토콜이라는 게 핵심입니다.

아키텍처 설계

단순히 WebSocket을 열고 닫는 것이 아니라, 여러 기능에서 재사용 가능한 인프라를 목표로 설계했습니다. 채팅뿐 아니라 나중에 운동 세션 실시간 공유, 알림 들을 추가할 때도 같은 구조를 쓸 수 있게 됩니다.

레이어	역할
WebSocketConnection	소켓 래퍼. Send 동시성 보호, LastActivity 추적
WebSocketConnecionManager	전체 연결 풀. Send/Broadcast/연결 수 제한
IWebSocketHandler	연결 해제 수신 이벤트 인터페이스
WebSocketHanlerBase	공통 로직 (DisconnectedAsync 시 풀에서 제거)
WebSocketMiddleware	HTTP 업그레이드, 수신 루프, Ping/Pong, Origin 검증

public class WebSocketConnection : IDisposable
{
    public string ConnectionId { get; } = Guid.NewGuid().ToString();
    public System.Net.WebSockets.WebSocket Socket { get; init; } = null!;
    public string? UserId { get; set; }
    public string? UserName { get; set; }
    public DateTime ConnectedAt { get; } = DateTime.UtcNow;
    public DateTime LastActivity { get; private set; } = DateTime.UtcNow;

    public bool IsOpen => Socket.State == WebSocketState.Open;

    private readonly SemaphoreSlim _sendLock = new(1, 1);

    public void UpdateLastActivity() => LastActivity = DateTime.UtcNow;

    public async Task SendAsync(string message, CancellationToken ct = default)
    {
        if (!IsOpen) return;

        await _sendLock.WaitAsync(ct);
        try
        {
            if (!IsOpen) return;
            var buffer = Encoding.UTF8.GetBytes(message);
            await Socket.SendAsync(buffer, WebSocketMessageType.Text, true, ct);
        }
        finally
        {
            _sendLock.Release();
        }
    }

    public void Dispose() => _sendLock.Dispose();
}

SemaphoreSlim 필요성

WebSocket은 동시에 Send가 하나만 허용됩니다. 같은 소켓에 두 곳에서 동시에 SendAsync를 호출하면 런타임 예외가 납니다.

- PingLoop: 30초마다 Ping 전송(좀비 PC 체크용)

- BroadcastToRoom: 채팅 메시지를 룸 내 전체에 전송(관리자 전체 메시지 전송용)

SemaphoreSlim(1, 1)로 Socket당 Send를 직렬화해서 이 충돌을 막습니다.

※ SemaphoreSlim : 동시 접근제어를 위한 동시성 제어 기술(lock은 동기 코드로 비동기를 지원하는 SemaphoreSlim을 사용)

public class WebSocketConnectionManager
{
    private readonly ConcurrentDictionary<string, WebSocketConnection> _connections = new();
    private readonly int _maxConnections;

    public WebSocketConnectionManager(int maxConnections = 1000)
    {
        _maxConnections = maxConnections;
    }

    public WebSocketConnection? AddConnection(System.Net.WebSockets.WebSocket socket)
    {
        if (_connections.Count >= _maxConnections) return null; // 연결 수 제한
        var connection = new WebSocketConnection { Socket = socket };
        _connections[connection.ConnectionId] = connection;
        return connection;
    }

    public Task SendAsync(string connectionId, string message, CancellationToken ct = default)
    {
        if (_connections.TryGetValue(connectionId, out var connection))
            return connection.SendAsync(message, ct); // 내부 SemaphoreSlim으로 직렬화됨
        return Task.CompletedTask;
    }

    public Task BroadcastAsync(string message, string? excludeConnectionId = null, CancellationToken ct = default)
    {
        var tasks = _connections.Values
            .Where(c => c.IsOpen && c.ConnectionId != excludeConnectionId)
            .Select(c => c.SendAsync(message, ct));
        return Task.WhenAll(tasks);
    }
}

ConcurrentDictionary 사용 이유

- 연결은 다수의 스레드에서 동시에 추가/제거됩니다. 일반 Dictionary에 lock 없이 접근하면 데이터 손상이 발생합니다.

public interface IWebSocketHandler
{
    Task OnConnectedAsync(WebSocketConnection connection);
    Task OnDisconnectedAsync(WebSocketConnection connection, Exception? exception);
    Task ReceiveAsync(WebSocketConnection connection, string message);
}

public abstract class WebSocketHandlerBase : IWebSocketHandler
{
    protected readonly WebSocketConnectionManager ConnectionManager;

    protected WebSocketHandlerBase(WebSocketConnectionManager connectionManager)
    {
        ConnectionManager = connectionManager;
    }

    public virtual Task OnConnectedAsync(WebSocketConnection connection) => Task.CompletedTask;

    public virtual Task OnDisconnectedAsync(WebSocketConnection connection, Exception? exception)
    {
        ConnectionManager.RemoveConnection(connection.ConnectionId);
        return Task.CompletedTask;
    }

    public abstract Task ReceiveAsync(WebSocketConnection connection, string message);
}

추후 신규 기능을 추가할 시에 WebSocketHanlerBase을 상속하고 ReceiveAsync만 구현하여 사용

* 연결 풀 관리, Ping, 수신 루프 같은 인프라 코드는 손댈 필요가 없습니다.

★WebSocketMiddlewawre(핵심 루프)

1. HTTP -> WebSocket Upgreade + 보안 체크

public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvider)
{
    if (!context.WebSockets.IsWebSocketRequest)
    {
        await _next(context);
        return;
    }

    // Origin 검증: 허용된 도메인이 아니면 403 반환
    if (_options.AllowedOrigins.Count > 0)
    {
        var origin = context.Request.Headers.Origin.ToString();
        if (!_options.AllowedOrigins.Contains(origin))
        {
            context.Response.StatusCode = 403;
            return;
        }
    }

    // 연결 수 초과 거부
    var socket = await context.WebSockets.AcceptWebSocketAsync();
    var connection = connectionManager.AddConnection(socket);
    if (connection is null)
    {
        await socket.CloseAsync(WebSocketCloseStatus.NormalClosure, "Server full", CancellationToken.None);
        return;
    }
    // ...
}

2. 수신 루프 -> 멀티프레임 조합

private async Task ReceiveLoopAsync(WebSocketConnection connection, IWebSocketHandler handler, CancellationToken ct)
{
    var buffer = ArrayPool<byte>.Shared.Rent(_options.BufferSize); // GC 부담 감소
    using var messageBuilder = new MemoryStream();                  // 프레임 조합용

    try
    {
        while (!ct.IsCancellationRequested && connection.IsOpen)
        {
            // 수신 타임아웃 (기본 2분)
            using var timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
            timeoutCts.CancelAfter(_options.ReceiveTimeout);

            var result = await connection.Socket.ReceiveAsync(buffer, timeoutCts.Token);

            connection.UpdateLastActivity();

            if (result.MessageType == WebSocketMessageType.Close) break;
            if (result.MessageType != WebSocketMessageType.Text) continue;

            // 메시지 크기 제한 (기본 64KB)
            if (messageBuilder.Length + result.Count > _options.MaxMessageSize)
            {
                messageBuilder.SetLength(0);
                await connection.SendAsync("{\"type\":\"error\",\"content\":\"Message too large\"}", ct);
                continue;
            }

            messageBuilder.Write(buffer, 0, result.Count);

            // EndOfMessage가 true일 때만 처리 (멀티프레임 조합 완료)
            if (!result.EndOfMessage) continue;

            var message = Encoding.UTF8.GetString(messageBuilder.ToArray());
            messageBuilder.SetLength(0);

            await handler.ReceiveAsync(connection, message);
        }
    }
    finally
    {
        ArrayPool<byte>.Shared.Return(buffer); // 반드시 반환
    }
}

멀티 프레임을 신경 써야 하는 이유?

- 메시지가 버퍼 크기(4KB)를 초과하면 WebSocket은 자동으로 여러 프레임으로 나눠 보냅니다.

각 프레임을 독립적으로 처리하면 잘린 JSON이 파싱에 실패합니다. MemoryStream으로 프레임을 조합하다가 EndOfMessage = true인 마지막 프레임이 왔을 때 한 번에 처리합니다.

ArrayPool <byte>

- new byte [4096]은 연결마다 GC 힙에 새 객체를 할당합니다. 연결이 수천 개면 GC 압박이 생깁니다. ArrayPool은 사용이 끝난 배열을 풀에 반납하고 재사용합니다.

3. Ping 푸프 - 좀비 연결 감지

private async Task PingLoopAsync(WebSocketConnection connection, CancellationToken ct)
{
    while (!ct.IsCancellationRequested && connection.IsOpen)
    {
        await Task.Delay(_options.PingInterval, ct); // 30초 대기

        // 마지막 활동이 60초 이상 없으면 좀비로 판단하고 연결 종료
        if (DateTime.UtcNow - connection.LastActivity > _options.PingInterval * 2)
            break;

        await connection.SendPingAsync(ct); // SemaphoreSlim 보호 하에 전송
    }
}

좀비 연결?

- 클라이언트가 WI-FI를 끊거나 앱을 강제 종료하면 TCP FIN 패킷이 전달되지 않습니다. 서버는 연결이 살아있다고 착각하고 _connections에 영원히 남겨둡니다. Ping을 주기적으로 보내서 응답이 없는 연결을 탐지하고 정리합니다.

4. Task.WhenAny - 두 루프 동시 실행

var receiveTask = ReceiveLoopAsync(connection, handler, cts.Token);
var pingTask = PingLoopAsync(connection, cts.Token);

var completed = await Task.WhenAny(receiveTask, pingTask);
await completed; // 먼저 끝난 Task를 다시 await → 예외 전파 보장

수신 루프와 Ping 루프를 동시에 실행합니다. 둘 중 하나가 먼저 종료되면 (예: 클라이언트 연결 해제, Ping 타임아웃) finally 블록에서 나머지도 CancellationToken으로 종료시킵니다.

await completed의 중요성

- Task.WhenAny는 먼저 완료된 Task 객체를 반환할 뿐, 그 Task의 예외를 전파하지 않습니다. 반드시 다시 await 해야 예외가 올라옵니다.

Redis

Red_Horse — Mon, 2 Mar 2026 16:48:37 +0900

Redis는 In-Memory 데이터 구조 저장소로, 다양한 자료형을 지원합니다. 그 중에서도 String은 Redis에서 가장 기본적이면서도 널리 사용되는 자료형입니다. 실제로 Redis 사용 사례의 90% 이상이 String 자료형을 활용한다고 할 수 있을 정도로 중요하고 유용한 자료형입니다.

Redis String의 내부 구조: SDS (Simply Dynamic String)

SDS란?

Redis String은 내부적으로 SDS(Simply Dynamic String) 구조를 사용합니다. 이는 C언어의 전통적인 null-terminated string이 아닌, Redis가 자체적으로 구현한 동적 문자열 구조입니다.

SDS의 주요 장점

1. 빠른 문자열 길이 조회

시간 복잡도: O(1)
C의 strlen()은 O(n)이지만, SDS는 길이 정보를 미리 저장하여 즉시 반환

2. 버퍼 오버플로우 방지

문자열 추가 시 자동으로 메모리 재할당
안전한 메모리 관리로 시스템 크래시 방지

3. 바이너리 세이프 (Binary Safe)

null 바이트(\0)를 포함한 모든 바이너리 데이터 저장 가능
이미지, 직렬화된 객체 등도 String으로 저장 가능

4. 효율적인 APPEND 연산

미리 할당된 여유 공간을 활용하여 문자열 추가 최적화

Redis String의 3가지 인코딩 방식

Redis는 메모리 효율성을 위해 값의 특성에 따라 다른 인코딩 방식을 사용합니다:

1. 정수값 저장 (int encoding)

SET counter 123
# 내부적으로 정수로 저장하여 메모리 절약

2. embstr 인코딩 (≤ 44바이트)

SET short_text "Hello Redis"
# 44바이트 이하의 문자열은 연속된 메모리에 할당
# RedisObject와 SDS가 하나의 메모리 블록에 저장됨

3. raw 인코딩 (> 44바이트)

SET long_text "This is a very long string that exceeds 44 bytes limit..."
# 44바이트 초과 시 RedisObject와 SDS를 별도 메모리에 분리 할당

핵심 String 명령어들

기본 저장 및 조회

SET 명령어

Redis에서 90% 이상 사용되는 가장 기본적인 데이터 저장 명령어입니다.

# 기본 사용법
SET users:1000:name "Redhorse"
SET users:1000:email "redhorse@example.com"

# 키 네이밍 컨벤션: 콜론(:)을 사용한 계층적 구조
SET project:redis:version "7.0"

GET 명령어

저장된 데이터를 검색하는 명령어입니다.

GET users:1000:name
# 결과: "Redhorse"

GET nonexistent_key  
# 결과: (nil)

카운터 명령어들

Redis String의 강력한 기능 중 하나는 원자적(Atomic) 카운터 연산입니다.

INCR / DECR 명령어

# 방문 횟수 카운터
SET users:1000:visits 0
INCR users:1000:visits    # 1 증가 → 1
INCR users:1000:visits    # 1 증가 → 2

DECR users:1000:visits    # 1 감소 → 1

Race Condition 방지: INCR/DECR은 원자적 연산이므로 동시성 문제가 발생하지 않습니다.

INCRBY / DECRBY 명령어

# 특정 값만큼 증가/감소
INCRBY users:1000:visits 5    # 5 증가
DECRBY users:1000:visits 2    # 2 감소

# 점수 시스템 예제
SET game:player:1000:score 150
INCRBY game:player:1000:score 50   # 50점 추가 → 200

다중 작업 명령어

MSET (Multiple SET)

# 여러 키-값을 한 번에 설정
MSET users:1000:name "Redhorse" users:1000:email "redhorse@example.com" users:1000:country "Korea"

MGET (Multiple GET)

# 여러 키의 값을 한 번에 조회
MGET users:1000:name users:1000:email users:1000:age

# 결과 예시:
# 1) "Redhorse"
# 2) "redhorse@example.com"  
# 3) (nil)  # users:1000:age가 존재하지 않는 경우

RTT(Round-Trip Time) 감소: MGET/MSET을 사용하면 네트워크 왕복 시간을 크게 줄일 수 있습니다.

# 비효율적: 3번의 네트워크 통신
GET users:1000:name
GET users:1000:email  
GET users:1000:country

# 효율적: 1번의 네트워크 통신
MGET users:1000:name users:1000:email users:1000:country

SET 명령어의 고급 옵션들

만료 시간 설정

SETEX (SET with EXpire)

# 300초(5분) 후 자동 만료
SETEX session:abc123 300 "user_data"

# 캐시 구현 예제
SETEX cache:weather:seoul 3600 "22°C, Sunny"

PSETEX (밀리초 단위)

# 5000밀리초(5초) 후 만료
PSETEX temp:token:xyz789 5000 "temporary_token"

SET 명령어의 EX/PX 옵션

# EX: 초 단위 만료
SET cache:user:1000 "cached_data" EX 3600

# PX: 밀리초 단위 만료  
SET cache:user:1000 "cached_data" PX 3600000

# NX: 키가 존재하지 않을 때만 설정
SET users:1000:name "Redhorse" NX

# XX: 키가 이미 존재할 때만 설정  
SET users:1000:name "NewName" XX

조건부 설정

SETNX (SET if Not eXists)

# 분산 락(Distributed Lock) 구현
SETNX lock:resource:db1 "locked_by_server_A"

# 결과가 1이면 락 획득 성공, 0이면 실패
# 중복 처리 방지에 유용

실제 사용 사례들

1. 사용자 세션 관리

# 사용자 로그인 시
SET session:a1b2c3d4 "user:1000" EX 1800  # 30분 세션

# 세션 확인
GET session:a1b2c3d4

2. 캐시 구현

# API 응답 캐싱 (1시간)
SET cache:api:weather:seoul "22°C,Sunny,Humidity:65%" EX 3600

# 데이터베이스 쿼리 결과 캐싱
SET cache:db:user:1000:profile "{\"name\":\"Redhorse\",\"role\":\"developer\"}" EX 600

3. 카운터 시스템

# 일일 방문자 수
INCR stats:daily_visitors:2024-03-02

# API 호출 제한 (Rate Limiting)
SET rate_limit:api:user:1000 1 EX 60    # 1분간 1회
INCR rate_limit:api:user:1000

4. 분산 락

# 중복 처리 방지를 위한 락
SET lock:payment:order:12345 "processing" NX EX 30

# 처리 완료 후 락 해제
DEL lock:payment:order:12345

성능 최적화 팁

1. 키 네이밍 전략

# 좋은 예: 계층적이고 의미있는 구조
users:1000:profile
users:1000:settings:notification
orders:2024:03:02:summary

# 피해야 할 예: 너무 길거나 의미 불명확
this_is_a_very_long_key_name_that_wastes_memory
user_data_abcd1234

2. 메모리 효율성

# 작은 정수는 자동으로 정수 인코딩 사용
SET counter 42        # int 인코딩

# 44바이트 이하로 유지하면 embstr 인코딩
SET short_msg "Hello"  # embstr 인코딩

# 불필요하게 긴 문자열 피하기
SET data "very long string..."  # raw 인코딩 (메모리 사용량 증가)

3. 배치 연산 활용

# 여러 번의 GET 대신 MGET 사용
MGET users:1000:name users:1000:email users:1000:role

# 여러 번의 SET 대신 MSET 사용  
MSET cache:A "dataA" cache:B "dataB" cache:C "dataC"

주의사항 및 베스트 프랙티스

1. 메모리 사용량 고려

Redis는 In-Memory 데이터베이스이므로 메모리 사용량을 항상 모니터링해야 합니다
대용량 문자열 저장 시 메모리 부족 위험이 있습니다

2. 만료 시간 설정

# 캐시 데이터는 반드시 TTL 설정
SET cache:expensive_query "result" EX 3600

# 세션 데이터도 적절한 만료 시간 설정
SET session:token "user_data" EX 1800

3. 원자성 보장

# 카운터 연산 시 INCR/DECR 사용 (GET + SET 조합 피하기)
INCR page_views    # ✅ 원자적 연산

# 다음과 같은 방식은 Race Condition 위험
GET page_views     # ❌ 비원자적
SET page_views 101 # ❌ 중간에 다른 클라이언트가 수정할 수 있음

4. 키 존재 여부 확인

# 조건부 설정 활용
SET lock:resource "owner" NX    # 키가 없을 때만 설정
SET config:updated "yes" XX     # 키가 있을 때만 업데이트

Redis String은 단순해 보이지만 매우 강력하고 유연한 자료형입니다. SDS 구조의 장점과 다양한 인코딩 방식을 통해 메모리 효율성을 제공하며, 풍부한 명령어 세트를 통해 다양한 사용 사례를 지원합니다.

특히 캐싱, 세션 관리, 카운터, 분산 락 등의 시나리오에서 Redis String의 진가를 발휘할 수 있습니다. 원자적 연산과 RTT 최적화를 통해 높은 성능을 보장하므로, 현대적인 웹 애플리케이션에서 필수적인 도구라고 할 수 있습니다.

다음 포스트에서는 Redis의 다른 자료형들(List, Set, Hash, Sorted Set)에 대해서도 자세히 알아보겠습니다.

참고 자료:

웹 애플리케이션(.NET)

Red_Horse — Sun, 30 Nov 2025 23:11:19 +0900

1. ASP.NET MVC (Server-Side Rendering)

동작 방식:

전통적인 서버 사이드 렌더링 방식
클라이언트 요청 → 서버에서 HTML 생성 → 완성된 HTML 반환
각 페이지 이동마다 전체 페이지 새로고침

장점:

SEO 친화적 (검색엔진이 콘텐츠 쉽게 크롤링)
초기 로딩 빠름 (서버에서 완성된 HTML 전송)
서버 리소스 활용 (클라이언트 부담 적음)
.NET Framework 4.8 같은 레거시 환경에서도 안정적

단점:

페이지 전환시 깜빡임
서버 부하 높음 (매 요청마다 HTML 생성)
인터랙티브한 UX 구현 어려움
JavaScript로 추가 작업 필요

적합한 경우:

콘텐츠 중심 웹사이트
SEO가 중요한 경우
레거시 시스템 유지보수

// Controller
public class ProductController : Controller
{
    public ActionResult Index()
    {
        var products = _productService.GetAll();
        return View(products); // 서버에서 HTML 생성
    }
    
    public ActionResult Detail(int id)
    {
        var product = _productService.GetById(id);
        return View(product); // 페이지 전체 새로고침
    }
}
```

**플로우:**
```
사용자: /Product/Index 요청
    ↓
서버: DB 조회 → Razor 뷰 엔진으로 HTML 생성
    ↓
브라우저: 완성된 HTML 받아서 전체 렌더링
    ↓
사용자: 상세페이지 클릭 (/Product/Detail/1)
    ↓
서버: 다시 HTML 생성
    ↓
브라우저: 페이지 전체 새로고침 (깜빡임)

2. Blazor Server (SSR + SignalR)

동작 방식:

초기 HTML은 서버에서 렌더링
이후 SignalR로 실시간 양방향 통신
UI 이벤트 → SignalR → 서버 처리 → DOM 업데이트 전송

장점:

빠른 초기 로딩
작은 다운로드 크기 (클라이언트에 전체 앱 불필요)
서버에서 로직 실행 (보안에 유리)
C# 코드만으로 개발 가능

단점:

지속적인 서버 연결 필요 (동시 사용자 많으면 부담)
네트워크 지연 시 반응 느림
서버 종속적 (오프라인 불가)
SignalR 연결 관리 복잡도

적합한 경우:

기업 내부 시스템 (안정적 네트워크)
실시간 데이터 처리
보안이 중요한 애플리케이션

// Component (.razor)
@page "/products"
@inject ProductService ProductService

<h3>상품 목록</h3>
@foreach (var product in products)
{
    <div @onclick="() => ShowDetail(product.Id)">
        @product.Name
    </div>
}

@code {
    private List<Product> products;
    
    protected override async Task OnInitializedAsync()
    {
        products = await ProductService.GetAllAsync();
    }
    
    private async Task ShowDetail(int id)
    {
        // UI만 부분 업데이트 (페이지 새로고침 없음)
        selectedProduct = await ProductService.GetByIdAsync(id);
    }
}
```

**플로우:**
```
초기 로딩: 서버에서 HTML 생성 → 브라우저 렌더링
    ↓
SignalR 연결 수립 (WebSocket)
    ↓
사용자: 버튼 클릭
    ↓
SignalR로 이벤트를 서버에 전송
    ↓
서버: 처리 후 변경된 UI 정보만 전송
    ↓
브라우저: DOM만 부분 업데이트 (새로고침 없음)

3. Blazor WebAssembly (CSR)

동작 방식:

전체 앱을 WebAssembly로 클라이언트에 다운로드
브라우저에서 .NET 런타임 실행
SPA처럼 동작 (클라이언트에서 모든 렌더링)

장점:

SPA 경험 (빠른 페이지 전환, 부드러운 UX)
서버 부하 최소화
오프라인 작동 가능 (PWA)
API 서버와 분리 배포 가능

단점:

초기 로딩 느림 (전체 앱 다운로드 필요)
SEO 어려움 (초기 HTML 거의 비어있음)
브라우저 호환성 이슈 가능
클라이언트 성능에 의존

적합한 경우:

인터랙티브한 웹 앱
PWA 구축
API 기반 아키텍처

// Component (.razor)
@page "/products"
@inject HttpClient Http

<h3>상품 목록</h3>
@foreach (var product in products)
{
    <div @onclick="() => ShowDetail(product.Id)">
        @product.Name
    </div>
}

@code {
    private List<Product> products;
    
    protected override async Task OnInitializedAsync()
    {
        // 브라우저에서 직접 API 호출
        products = await Http.GetFromJsonAsync<List<Product>>("api/products");
    }
    
    private async Task ShowDetail(int id)
    {
        // 브라우저에서 모든 처리 실행
        selectedProduct = await Http.GetFromJsonAsync<Product>($"api/products/{id}");
    }
}
```

**플로우:**
```
첫 방문: 전체 앱 다운로드 (.dll, 런타임 등) → 느림
    ↓
브라우저에서 .NET 런타임 시작
    ↓
사용자: 페이지 이동 또는 버튼 클릭
    ↓
브라우저에서 C# 코드 직접 실행 (WebAssembly)
    ↓
필요시 API 서버에 데이터만 요청
    ↓
브라우저에서 UI 업데이트 (빠른 반응, SPA 경험)

Blazor 8+ (Auto/통합 렌더링)

.NET 8부터는 Static SSR, Interactive Server, Interactive WebAssembly, Interactive Auto 모드를 컴포넌트 단위로 선택 가능합니다.

렌더 모드 옵션:

@rendermode InteractiveServer: Blazor Server 방식
@rendermode InteractiveWebAssembly: WASM 방식
@rendermode InteractiveAuto: 초기 Server → 이후 WASM 전환
Static SSR (기본): MVC처럼 정적 HTML만

임시 파일 자동정리(.NET TimerQueue & .NET IHostedService)

Red_Horse — Thu, 27 Nov 2025 22:32:28 +0900

웹 어플리케이션 운영시 파일을 생성하고 다운로드 링크로 제공할시에 정상적인 플로우로 다운로드 및 임시파일 삭제가 이루어지면 문제가 없지만 간혹 프로세스 진행중에 브라우저를 닫거나 예기치 못한 오류로 종료가 되었을때 임시 파일이 서버에 쌓이는 문제가 있습니다.

이러한 문제를 해결하기 위해 .NET Timer Queue에 정리하는 프로세스를 예약해놓고 주기적으로 해당 동작이 수행되게 구성합니다.

서버 자동 삭제의 장점

브라우저 상태와 무관
확실한 정리 보장
관리 편의성
리소스 효율적 사용

Timer의 동작 원리

_timer = new Timer(callback, state, dueTime, period);
```
**내부 동작:**

1. Timer 생성 시 OS의 타이머 큐에 등록
2. 대기 중에는 CPU/쓰레드 사용 안 함 (리소스 0%)
3. 지정된 시간이 되면 OS가 하드웨어 인터럽트 발생
4. ThreadPool에서 쓰레드를 빌려 콜백 실행
5. 실행 완료 후 쓰레드 반납

**비유:**  
알람시계를 맞춰놓고 자는 것과 같습니다. 알람 시간까지 당신은 아무것도 하지 않고(CPU 사용 없음), 시간이 되면 알람이 울립니다.

### 리소스 사용량
```
Timer 1개당:
- 메모리: ~1KB
- CPU: 0% (대기 중)
- 쓰레드: 실행 시점에만 잠깐 사용

10개의 Timer를 돌려도:
- 메모리: ~10KB
- CPU: 여전히 0%
```

.NET Framework 4.8 MVC 구현

1. 서비스 클래스 생성

// Services/TempFileCleanupService.cs
using System;
using System.IO;
using System.Threading;
using System.Web;

public class TempFileCleanupService
{
    private static Timer _timer;
    
    public static void Start(params string[] folderPaths)
    {
        // 다음 정각까지 대기 시간 계산
        var now = DateTime.Now;
        var nextHour = now.Date.AddHours(now.Hour + 1);
        var delay = nextHour - now;
        
        _timer = new Timer(
            Cleanup,
            folderPaths,
            delay,                       // 첫 실행: 다음 정각
            TimeSpan.FromHours(1)        // 이후: 1시간마다
        );
    }
    
    private static void Cleanup(object state)
    {
        string[] folders = state as string[];
        
        foreach (var folder in folders)
        {
            CleanupFolder(folder);
        }
    }
    
    private static void CleanupFolder(string folderPath)
    {
        try
        {
            if (!Directory.Exists(folderPath))
                return;
            
            var files = Directory.GetFiles(folderPath);
            int deletedCount = 0;
            
            foreach (var file in files)
            {
                try
                {
                    var fileInfo = new FileInfo(file);
                    // 30분 이상 된 파일 삭제
                    if (DateTime.Now - fileInfo.CreationTime > TimeSpan.FromMinutes(30))
                    {
                        File.Delete(file);
                        deletedCount++;
                    }
                }
                catch (Exception ex)
                {
                    // 개별 파일 삭제 실패 시 로깅
                    System.Diagnostics.Debug.WriteLine($"파일 삭제 실패: {file}, {ex.Message}");
                }
            }
            
            if (deletedCount > 0)
            {
                System.Diagnostics.Debug.WriteLine($"{folderPath}: {deletedCount}개 파일 삭제됨");
            }
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine($"{folderPath} 정리 실패: {ex.Message}");
        }
    }
    
    // 선택사항: 명시적 종료
    public static void Stop()
    {
        _timer?.Dispose();
        _timer = null;
    }
}

2. Global.asax.cs에서 시작

public class MvcApplication : HttpApplication
{
    protected void Application_Start()
    {
        AreaRegistration.RegisterAllAreas();
        FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
        RouteConfig.RegisterRoutes(RouteTable.Routes);
        BundleConfig.RegisterBundles(BundleTable.Bundles);
        
        // 임시 파일 자동 정리 시작
        TempFileCleanupService.Start(
            Server.MapPath("~/Temp"),
            Server.MapPath("~/Content/Present"),
            Server.MapPath("~/Uploads/Temp")
        );
    }
    
    // 선택사항: 애플리케이션 종료 시 정리
    protected void Application_End()
    {
        TempFileCleanupService.Stop();
    }
}

.NET 8 Blazor Server 구현

Blazor에서는 IHostedService를 사용하는 것이 표준 방식입니다.

1. 서비스 클래스 생성

// Services/TempFileCleanupService.cs
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class TempFileCleanupService : IHostedService, IDisposable
{
    private Timer _timer;
    private readonly ILogger<TempFileCleanupService> _logger;
    private readonly IWebHostEnvironment _env;
    private readonly IConfiguration _config;
    
    public TempFileCleanupService(
        ILogger<TempFileCleanupService> logger,
        IWebHostEnvironment env,
        IConfiguration config)
    {
        _logger = logger;
        _env = env;
        _config = config;
    }
    
    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("임시 파일 정리 서비스 시작");
        
        // 다음 정각까지 대기
        var now = DateTime.Now;
        var nextHour = now.Date.AddHours(now.Hour + 1);
        var delay = nextHour - now;
        
        _timer = new Timer(
            Cleanup,
            null,
            delay,
            TimeSpan.FromHours(1)
        );
        
        return Task.CompletedTask;
    }
    
    private void Cleanup(object state)
    {
        try
        {
            // appsettings.json에서 설정 읽기
            var folders = _config.GetSection("TempFileCleaning:Folders").Get<string[]>();
            var maxAgeMinutes = _config.GetValue<int>("TempFileCleaning:MaxAgeMinutes");
            
            foreach (var folder in folders)
            {
                string fullPath = Path.Combine(_env.ContentRootPath, folder);
                CleanupFolder(fullPath, maxAgeMinutes);
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "파일 정리 중 오류 발생");
        }
    }
    
    private void CleanupFolder(string folderPath, int maxAgeMinutes)
    {
        try
        {
            if (!Directory.Exists(folderPath))
                return;
            
            var files = Directory.GetFiles(folderPath);
            int deletedCount = 0;
            
            foreach (var file in files)
            {
                try
                {
                    var fileInfo = new FileInfo(file);
                    if (DateTime.Now - fileInfo.CreationTime > TimeSpan.FromMinutes(maxAgeMinutes))
                    {
                        File.Delete(file);
                        deletedCount++;
                    }
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, $"파일 삭제 실패: {file}");
                }
            }
            
            if (deletedCount > 0)
            {
                _logger.LogInformation($"{folderPath}: {deletedCount}개 파일 삭제됨");
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, $"폴더 정리 실패: {folderPath}");
        }
    }
    
    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("임시 파일 정리 서비스 종료");
        _timer?.Change(Timeout.Infinite, 0);
        return Task.CompletedTask;
    }
    
    public void Dispose()
    {
        _timer?.Dispose();
    }
}

2. appsettings.json 설정

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "TempFileCleaning": {
    "Folders": [
      "wwwroot/Temp",
      "wwwroot/Uploads/Temp",
      "Content/Present"
    ],
    "MaxAgeMinutes": 30
  }
}

3. Program.cs에서 등록

var builder = WebApplication.CreateBuilder(args);

// Razor Pages, Blazor 등 기본 서비스 등록
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();

// 백그라운드 서비스 등록
builder.Services.AddHostedService<TempFileCleanupService>();

var app = builder.Build();

// 미들웨어 설정
app.UseStaticFiles();
app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();
```

## IHostedService 동작 원리

많은 분들이 `StartAsync`가 어떻게 호출되는지 궁금해하십니다.

### 호출 흐름
```
1. Program.cs에서 서비스 등록:
   builder.Services.AddHostedService<TempFileCleanupService>();
   → "이 서비스는 백그라운드 서비스입니다" 라고 표시
   
2. app.Run() 실행:
   → ASP.NET Core 런타임이 시작됨
   
3. 런타임이 자동으로:
   → 모든 IHostedService를 찾음
   → 각 서비스의 StartAsync() 호출
   
4. 애플리케이션 실행 중...
   
5. 애플리케이션 종료 시:
   → 모든 IHostedService의 StopAsync() 호출

MVC vs Blazor 비교

// MVC (.NET Framework 4.8)
// 수동으로 직접 호출
protected void Application_Start()
{
    TempFileCleanupService.Start(folders); // 개발자가 호출
}

// Blazor (.NET 8)
// 프레임워크가 자동 호출
builder.Services.AddHostedService<TempFileCleanupService>();
// app.Run() 시점에 자동으로 StartAsync() 실행

차이점

항목	.NET Framework MVC	.NET 8 Blazor
진입점	Global.asax.cs	Program.cs
시작 방식	수동 호출	자동 호출 (IHostedService)
설정 방식	코드에 직접	appsettings.json
로깅	Debug.WriteLine	ILogger (구조화된 로깅)
종료 처리	Application_End	StopAsync (자동)
DI 지원	제한적	완전 지원

주의사항

1. 폴더 권한 확인

IIS 애플리케이션 풀 계정이 해당 폴더에 대한 삭제 권한을 가지고 있어야 합니다.

2. 네트워크 드라이브 사용 시

네트워크 드라이브의 파일을 삭제할 때는 네트워크 지연을 고려해야 합니다.

Background tasks with hosted services in ASP.NET Core

Learn how to implement background tasks with hosted services in ASP.NET Core.

learn.microsoft.com

IIS(Internet Information Services)

Red_Horse — Thu, 27 Nov 2025 00:29:07 +0900

Microsoft가 만든 웹 서버 소프트웨어

식당으로 비유:
- ASP.NET MVC 앱 = 요리사가 만든 음식
- IIS = 식당 건물 + 웨이터 (손님에게 음식을 서빙)
- 브라우저 = 손님

// 역할
1. 브라우저 요청 받기
   사용자: "http://localhost/Home/Index 주세요!"
   
2. ASP.NET 앱에게 전달
   IIS: "야, ASP.NET! /Home/Index 처리해줘"
   
3. 결과를 브라우저에게 돌려주기
   IIS: "여기 HTML 페이지 나왔습니다~"

타 웹 서버들과 비교

웹	서버	주로 사용하는 언어운영체제
IIS	C# (ASP.NET)	Windows
Apache	PHP, Python	Linux/Windows
Nginx	모든 언어	Linux/Windows
Tomcat	Java	Linux/Windows

Visual Studio에서 개발할 시

개발 중 (F5 실행시)

IIS Express 사용
- IIS의 경량 버전
- 개발자 PC에서만 동작
- 자동으로 실행됨 (포트: 44300 같은 번호)

실제 서버 배포 시

IIS (full version) 사용
- Windows Server에 설치
- 실제 사용자들이 접속
- 포트 80 (HTTP) 또는 443 (HTTPS)

실제 사용 예시

당신의 개발 환경:
┌─────────────────────────────────┐
│  Visual Studio (F5 실행)         │
│         ↓                       │
│  IIS Express 자동 시작            │
│         ↓                       │
│  ASP.NET MVC 앱 실행              │
│         ↓                       │
│  브라우저 자동 열림:                 │
│  https://localhost:44300        │
└─────────────────────────────────┘

실제 서버 환경:
┌─────────────────────────────────┐
│  Windows Server                 │
│         ↓                       │
│  IIS 설치 및 설정                  │
│         ↓                       │
│  ASP.NET MVC 앱 배포              │
│         ↓                       │
│  사용자 접속:                      │
│  https://company.com            │
└─────────────────────────────────┘

IIS Manager (관리 도구)

Windows에서 IIS를 설정할 때 사용하는 GUI 프로그램:

할 수 있는 것들:
✅ 웹사이트 추가/삭제
✅ 포트 번호 변경 (80, 443, 8080 등)
✅ SSL 인증서 설정 (HTTPS)
✅ 애플리케이션 풀 관리 (메모리, CPU 제한)
✅ 가상 디렉토리 설정

IIS는 .net Framework 버전(.net core 이전버전)에서 Window만 지원되어 사용한 구조로서 .net core부터는 실행되는 서버의 운영체제 제한이 없어졌습니다.

파일 생성 및 다운로드 관리(물리 경로 vs 가상 경로)_Web

Red_Horse — Thu, 27 Nov 2025 00:18:06 +0900

물리 경로 (Physical Path)

// Server.MapPath()로 변환
string physicalPath = Server.MapPath("~/Content/Data");
// 결과: C:\Projects\MyApp\Content\Data

// 사용: 파일 시스템 작업
Directory.CreateDirectory(physicalPath);
File.WriteAllBytes(Path.Combine(physicalPath, "file.xlsx"), bytes);
File.Delete(Path.Combine(physicalPath, "file.xlsx"));

특징:

실제 디스크 경로
운영체제 파일 시스템이 이해하는 경로
C#의 File, Directory 클래스가 사용

가상 경로 (Virtual Path)

// 웹 URL 경로
string virtualPath = "/Content/Data/file.xlsx";

// 사용: 다운로드 링크
return Json(new { Data = virtualPath });

특징:

웹 서버가 이해하는 경로
브라우저가 접근하는 경로
도메인 + 가상 경로 = 완전한 URL

분리해서 사용하는 이유

1. 역할이 다름

// 물리 경로로 다운로드 링크 만들면?
string physicalPath = "C:\\Projects\\MyApp\\Content\\file.xlsx";
return Json(new { Data = physicalPath });

// JavaScript에서
window.location.href = "C:\\Projects\\MyApp\\Content\\file.xlsx";
// 브라우저는 이걸 이해 못 함!
// 로컬 파일 시스템 접근은 보안상 차단됨! (브라우저에서 PC로 접근하려는 모습)

// 가상 경로로 다운로드 링크
string virtualPath = "/Content/file.xlsx";
return Json(new { Data = virtualPath });

// JavaScript에서
window.location.href = "/Content/file.xlsx";
// 브라우저가 이해 할수 있는 경로!
// 실제 요청: http://localhost/Content/file.xlsx
// 실행되고 있는 프로젝트 경로로 접근

2. 서버 환경마다 물리 경로가 다름

개발 서버: C:\Projects\MyApp\Content\file.xlsx
스테이징: D:\WebApps\MyApp\Content\file.xlsx
운영 서버: E:\inetpub\wwwroot\MyApp\Content\file.xlsx

가상 경로는 모든 환경에서 동일: /Content/file.xlsx
물리 경로는 환경마다 다름

3. 보안

// 물리 경로 노출 위험
return Json(new { Data = "C:\\Projects\\MyApp\\Content\\file.xlsx" });
// 사용자가 서버 구조를 알게 됨!(PC 경로 구성을 외부에 보이게됨)

// 가상 경로는 안전
return Json(new { Data = "/Content/file.xlsx" });
// 서버 구조는 숨겨짐

동작 원리

1. 파일 저장 (물리 경로)

// Step 1: 물리 경로 얻기
string physicalPath = Server.MapPath("~/Content/Data");
// C:\Projects\MyApp\Content\Data

// Step 2: 파일 시스템에 저장
File.WriteAllBytes(Path.Combine(physicalPath, "file.xlsx"), bytes);
// C:\Projects\MyApp\Content\Data\file.xlsx 생성

물리 경로를 사용하는 이유

File.WriteAllBytes()는 운영체제 API 호출
운영체제는 물리 경로만 이해함
/Content/file.xlsx 같은 가상 경로는 이해 못 함(브라우저 접근용)

2. 다운로드 링크 (가상 경로)

// Step 1: 가상 경로 생성
string virtualPath = "/Content/Data/file.xlsx";

// Step 2: 클라이언트에 전달
return Json(new { Data = virtualPath });

window.location.href = "/Content/Data/file.xlsx";
// 브라우저가 요청: http://localhost/Content/Data/file.xlsx
//서버에서 (IIS/ASP.NET):**

1. 요청 받음: GET /Content/GoodsSelectJson/file.xlsx
2. 가상 경로를 물리 경로로 변환: C:\Projects\MyApp\Content\Data\file.xlsx
3. 파일 읽기
4. 응답 전송

예시

// Controllers/PresentController.cs
public ActionResult PresentInfomation(...)
{
    // 1. 물리 경로로 파일 저장
    string physicalFolder = Server.MapPath("~/Content/Present");
    // C:\Projects\MyApp\Content\Present
    
    if (!Directory.Exists(physicalFolder))
    {
        Directory.CreateDirectory(physicalFolder);
        // 물리 폴더 생성: C:\Projects\MyApp\Content\Present
    }
    
    string fileName = "items_20241126.xlsx";
    string physicalFilePath = Path.Combine(physicalFolder, fileName);
    // C:\Projects\MyApp\Content\Present\items_20241126.xlsx
    
    File.WriteAllBytes(physicalFilePath, excelBytes);
    // 운영체제 파일 시스템에 저장
    
    // 2. 가상 경로로 다운로드 링크 생성
    string virtualPath = $"/Content/Present/{fileName}";
    // /Content/Present/items_20241126.xlsx
    
    return Json(new
    {
        Success = true,
        Data = virtualPath  // 가상 경로 반환
    });
}

// JavaScript
$.ajax({
    success: function(result) {
        // result.Data = "/Content/Present/items_20241126.xlsx"
        
        // 3. 브라우저가 다운로드 요청
        window.location.href = result.Data;
        // 실제 요청: http://localhost/Content/Present/items_20241126.xlsx
    }
});
```
```
4. IIS/ASP.NET 처리(자동으로 됨)
요청: GET /Content/Present/items_20241126.xlsx

IIS:
- 가상 경로: /Content/Present/items_20241126.xlsx
- 물리 경로 변환: C:\Projects\MyApp\Content\Present\items_20241126.xlsx
- 파일 읽기
- 응답 전송 (파일 다운로드)

파일 삭제

// Controller
[HttpPost]
public ActionResult DeleteTemporaryFile(string fileUrl)
{
    // fileUrl = "/Content/Present/file.xlsx" (가상 경로)
    
    // 가상 경로를 물리 경로로 변환
    string physicalPath = Server.MapPath("~" + fileUrl);
    // C:\Projects\MyApp\Content\Present\file.xlsx
    
    // 물리 경로로 삭제
    if (File.Exists(physicalPath))
    {
        File.Delete(physicalPath);
    }
    
    return Json(new { Success = true });
}

만약 IIS가 없다면?

// 이렇게 직접 구현해야 함
public ActionResult DownloadFile(string fileName)
{
    // 가상 경로를 물리 경로로 변환
    string physicalPath = Server.MapPath($"~/Content/Present/{fileName}");
    
    if (!File.Exists(physicalPath))
    {
        return HttpNotFound();
    }
    
    // 파일 읽기
    byte[] fileBytes = File.ReadAllBytes(physicalPath);
    
    // 파일 전송
    return File(fileBytes, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", fileName);
}

// 사용
// window.location.href = "/Present/DownloadFile?fileName=file.xlsx";

비교표

항목	물리 경로	가상 경로
예시	C:\Projects\MyApp\Content\file.xlsx	/Content/file.xlsx
사용 대상	파일 시스템 (C#)	웹 서버 (브라우저)
사용 시점	파일 생성/삭제/읽기	다운로드 링크/URL
환경 의존성	환경마다 다름	모든 환경 동일
보안	서버 구조 노출	안전
브라우저 접근	불가능	가능
File.WriteAllBytes	가능	불가능
window.location	불가능	가능

Http -> Https Domain 변경

Red_Horse — Sat, 25 Oct 2025 01:06:50 +0900

환경 설정

서버: 리눅스 Ubuntu
웹서버: Nginx (리버스 프록시)
도메인: 가비아에서 구매한 도메인
네트워크: iptime 공유기 환경
SSL: Let's Encrypt 무료 인증서

목표

https://jenkins.[도메인] - 브라우저 경고 없는 안전한 접속
https://fitnesspt.[도메인] - 브라우저 경고 없는 안전한 접속

준비 단계: certbot 설치

sudo apt update 
sudo apt install certbot
sudo apt install python3-certbot-nginx # Nginx와 acme챌린지를 위한 플러그인
sudo apt install python3-certbot-apache # Apache와 acme챌린지를 위한 플러그인

1단계: 도메인 DNS 설정

가비아 관리콘솔 설정

호스트명: jenkins
레코드타입: A
값: [서버공인IP]

호스트명: fitnesspt  
레코드타입: A
값: [서버공인IP]

주요 이슈와 해결

문제: 도메인 접속 시 공유기 관리페이지로 리다이렉트

원인: 80포트 포트포워딩 누락

해결: iptime 포트 포워딩 규칙 추가

3단계: Nginx 리버스 프록시 설정

Jenkins 설정 (/etc/nginx/sites-available/jenkins)

server {
    listen 80;
    server_name jenkins.[도메인];

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host jenkins.[도메인];
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Jenkins 쿠키 도메인 수정 (중요!)
        proxy_cookie_domain 127.0.0.1 jenkins.[도메인];
        proxy_cookie_domain localhost jenkins.[도메인];
        
        proxy_redirect http://127.0.0.1:8080/ http://jenkins.[도메인]/;
        proxy_redirect http://localhost:8080/ http://jenkins.[도메인]/;
        
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

주요 이슈와 해결

문제: Jenkins 접속 시 /login/login.cgi로 리다이렉트, "Not Found" 오류

원인: Jenkins의 쿠키와 세션이 새 도메인에서 작동하지 않음

해결: proxy_cookie_domain 설정 추가

nginx 설정 활성화

sudo ln -s /etc/nginx/sites-available/jenkins /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

sites-available 위치에는 설정 파일만 있고 실제 실행되는건 sites-enable에서 연결되어 있는 파일을 읽어서 실행합니다.

4단계: Let's Encrypt SSL 인증서 발급

acme-challenge 경로 설정

nginx파일에 다음 내용 추가(jenkins, fitnesspt)

location ^~ /.well-known/acme-challenge/ {
    root /var/www/html;
    try_files $uri =404;
}

웹 루트 디렉토리 준비(SSL 인증서 발급시 도메인 소유권을 확인하기 위해 사용할 경로)

sudo mkdir -p /var/www/html/.well-known/acme-challenge
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html

주요 이슈와 해결

문제: SSL 인증서 발급 시 "Timeout during connect" 오류

원인: iptime에서 해외 IP 접근 차단 설정

해결: 인증서 발급 시에만 임시로 해외 IP 차단 해제

SSL 인증서 발급

# 해외 IP 차단 임시 해제 후
sudo certbot certonly --nginx --cert-name [저장될 이름] -w /var/www/html -d jenkins.[도메인] -d fitnesspt.[도메인]

5단계: HTTPS 최종 설정

Jenkins HTTPS 설정

# HTTP → HTTPS 리다이렉트
server {
    listen 80;
    server_name jenkins.[도메인];
    return 301 https://$server_name$request_uri;
}

# HTTPS 설정
server {
    listen 443 ssl http2;
    server_name jenkins.[도메인];

    ssl_certificate /etc/letsencrypt/live/[인증서이름]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[인증서이름]/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host jenkins.[도메인];
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Port 443;
        
        proxy_cookie_domain 127.0.0.1 jenkins.[도메인];
        proxy_cookie_domain localhost jenkins.[도메인];
        
        proxy_redirect http://127.0.0.1:8080/ https://jenkins.[도메인]/;
        proxy_redirect http://localhost:8080/ https://jenkins.[도메인]/;
    }
}

자동 갱신 설정

sudo systemctl status certbot.timer
sudo certbot renew --dry-run

CSS Position - 요소 배치의 모든 것

Red_Horse — Fri, 17 Oct 2025 23:44:57 +0900

Position은 HTML 요소를 원하는 위치에 배치하기 위한 CSS 속성입니다.

top, bottom, left, right 속성과 함께 사용하여 정확한 위치를 지정할 수 있습니다.

1. 부모-자식 관계 설정

기본 원칙

부모 요소: position: relative
자식 요소: position: absolute

→ 자식 요소는 부모를 기준으로 배치됨

CSS
.parent {
    position: relative;  /* 기준점 설정 */
    width: 600px;
    height: 300px;
    background-color: dodgerblue;
}

.child {
    position: absolute;  /* 부모 기준 절대 위치 */
    width: 200px;
    height: 100px;
    right: 0;    /* 부모의 우측에 붙음 */
    bottom: 0;   /* 부모의 하단에 붙음 */
    background-color: crimson;
}


HTML
    <div class="parent">
        <div class="child">
        </div>
    </div>

핵심 포인트:

position을 선언해야 top, bottom, left, right 속성 사용 가능
부모의 relative가 없으면 자식은 브라우저 전체를 기준으로 배치됨

2. 원하는 위치에 정렬

4가지 기본 정렬

CSS
.container{
	position: relative;
	width: 500px;
	height: 500px;
	border: 1px solid #000;
}

/* 좌측 상단 */
.box1{
	position: absolute;
	background-color: dodgerblue;
	width: 100px;
	height: 100px;
}

/* 우측 상단 */
.box2{
	position: absolute;
	background-color: gold;
	width: 100px;
	height: 100px;
	right: 0;
}

/* 좌측 하단 */
.box3{
	position: absolute;
	background-color: #cc4f4f;
	width: 100px;
	height: 100px;
	bottom: 0;
}

/* 우측 하단 */
.box4{
	position: absolute;
	background-color: purple;
	width: 100px;
	height: 100px;
	right: 0;
	bottom: 0;
}

HTML
    <div class="container">
        <div class="box1"></div>
        <div class="box2"></div>
        <div class="box3"></div>
        <div class="box4"></div>
    </div>

3. 중앙 정렬 (완벽한 중앙)

CSS
.center-container{
	position: relative;
	width: 500px;
	height: 500px;
	border: 1px solid #000;
}
        
.box-center{
	background-color: dodgerblue;
	width: 100px;
	height: 100px;
	position: absolute;

	/* 1단계: 좌측 상단을 중앙으로 */
	left: 50%;
	top: 50%;
    
	/* 2단계: 자신의 크기만큼 역방향 이동 */
	transform: translate(-50%, -50%);
}

HTML
    <div class="center-container">
        <div class="box-center"></div>
    </div>

핵심 포인트:

left: 50%, top: 50%: 요소의 좌측 상단을 중앙에 배치
transform: translate(-50%, -50%): 요소를 자신의 크기 절반만큼 역방향 이동
브라우저 크기와 관계없이 항상 중앙 유지

4. 부모 요소 밖으로 배치

위치 계산 방식

핵심: %는 부모(relative)의 크기를 기준으로 계산

부모 크기: 300px × 200px
top: 100% → 200px 아래
left: 100% → 300px 오른쪽

4가지 밖으로 배치

CSS
/* 하단 중앙 밖 */
.box-out1{
	background-color: dodgerblue;
	width: 100px;
	height: 100px;
	position: absolute;
	top: 100%;
	left: 50%;
	transform: translate(-50%, 0%);
}

/* 우측 하단 밖 */
.box-out2{
	background-color: gold;
	width: 100px;
	height: 100px;
	position: absolute;
	top: 100%;
	left: 100%;
	transform: translate(-100%, 0%);
}

/* 우측 상단 밖 */
.box-out3{
	background-color: purple;
	width: 100px;
	height: 100px;
	position: absolute;
	left: 100%;
}

HTML
    <div class="out-container">
        <div class="box-out1"></div>
        <div class="box-out2"></div>
        <div class="box-out3"></div>
    </div>

주의사항

자식 요소의 크기는 자동으로 고려되지 않습니다!

/* 잘못된 예 */
.box-out {
    top: 100%;
    left: 50%;
    /* transform 없음 → 박스가 중앙에서 벗어남 */
}

/* 올바른 예 */
.box-out {
    top: 100%;
    left: 50%;
    transform: translate(-50%, 0);  /* 필수! */
}

Transform의 매개변수 translate(X, Y)

transform: translate(-50%, -50%);
                     ↑      ↑
                   좌우    상하

값의 의미:

양수(+): 오른쪽, 아래로 이동
음수(-): 왼쪽, 위로 이동
%: 자신의 크기 기준

예시:

transform: translate(-50%, 0);    /* 왼쪽으로 절반, 상하 이동 없음 */
transform: translate(0, -100%);   /* 좌우 이동 없음, 위로 전체 */
transform: translate(-100%, -100%); /* 왼쪽 위로 완전히 이동 */

실전 활용 예시

1. 모달 창 중앙 배치

.modal {
    position: fixed;     /* 화면 기준 고정 */
    left: 50%;
    top: 50%;
    transform: translate(-50%, -50%);
    z-index: 1000;
}

2. 툴팁 하단 중앙 표시

.tooltip-container {
    position: relative;
}

.tooltip {
    position: absolute;
    top: 100%;
    left: 50%;
    transform: translate(-50%, 5px);  /* 5px 간격 */
}

3. 배지 우측 상단 배치

.avatar {
    position: relative;
}

.badge {
    position: absolute;
    top: 0;
    right: 0;
    transform: translate(50%, -50%);  /* 반만 삐져나오게 */
}

핵심 정리

속성	역할	기준점
relative	기준점 역할	원래 위치
absolute	절대 위치 지정	부모 relative
fixed	화면 고정	브라우저 화면

% 계산 기준

top, bottom, left, right의 % → 부모(relative) 크기 기준
transform: translate()의 % → 자신의 크기 기준

Transform이 필요한 이유

position만으로는 요소의 좌측 상단 모서리만 제어 가능 → transform으로 요소 자체를 이동시켜 정확한 위치 조정

Jenkins CI/CD 구축

Red_Horse — Fri, 17 Oct 2025 00:43:59 +0900

이 가이드는 Ubuntu 22.04 환경에서 Jenkins를 설치하고, .NET 프로젝트의 CI/CD 파이프라인을 구축하는 전 과정을 다룹니다.

1. 환경 준비 및 기본 설정

1.1 시스템 업데이트

sudo apt update && sudo apt upgrade -y

1.2 SSH 서버 설정 (원격 접속용)

# SSH 서버 설치
sudo apt install openssh-server -y

# SSH 서비스 시작 및 자동 시작 설정
sudo systemctl start ssh
sudo systemctl enable ssh

# SSH 서비스 상태 확인
sudo systemctl status ssh

1.3 방화벽 설정

# UFW 방화벽 활성화
sudo ufw enable

# SSH 포트 허용 (기본 22번 포트)
sudo ufw allow 22/tcp

# Jenkins 웹 포트 허용 (8080)
sudo ufw allow 8080/tcp

# 애플리케이션 포트 허용 (예: 5117)
sudo ufw allow 5117/tcp

# 방화벽 상태 확인
sudo ufw status

⋇iptime에서 지원하는 DDNS 기능을 사용할 경우 포트포워딩을 별도로 설정해 주어야합니다.

2. Jenkins 설치 및 초기 설정

2.1 Java 설치 (Jenkins 필수 요구사항)

# OpenJDK 17 설치
sudo apt install openjdk-17-jdk -y

# Java 버전 확인
java -version

# JAVA_HOME 환경변수 설정
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$PATH:$JAVA_HOME/bin' >> ~/.bashrc
source ~/.bashrc

2.2 Jenkins 저장소 추가 및 설치

단계 1: Jenkins GPG 키 다운로드 및 추가

# Jenkins 공식 보안 키를 다운로드하여 시스템에 추가
curl -fsSL https://pkg.jenkins.io/debian/jenkins.io-2023.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null

GPG 키? 패키지가 진짜 Jenkins에서 만든 것인지 확인하는 디지털 서명입니다. 가짜 패키지 설치를 방지하기 위함.

명령어 설명:

curl -fsSL: Jenkins 웹사이트에서 보안 키 파일을 다운로드
sudo tee: 다운로드한 키를 시스템 보안 키 저장소에 저장
/usr/share/keyrings/: Ubuntu에서 패키지 보안 키를 저장하는 표준 위치

단계 2: Jenkins 저장소를 시스템에 추가

# Jenkins 패키지 저장소를 APT 소스 목록에 추가
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

단계 3: 패키지 목록 업데이트

# 새로 추가된 Jenkins 저장소를 포함하여 패키지 목록 업데이트
sudo apt update

단계 4: Jenkins 설치

# Jenkins 패키지 설치
sudo apt install jenkins -y

단계 5: Jenkins 서비스 설정

# Jenkins 서비스 시작
sudo systemctl start jenkins

# 시스템 부팅 시 Jenkins 자동 시작 설정
sudo systemctl enable jenkins

# Jenkins 서비스 상태 확인
sudo systemctl status jenkins

설치 성공 확인:

sudo systemctl status jenkins 명령어 실행 시 Active: active (running) 상태여야 함
만약 실패했다면 sudo journalctl -u jenkins로 로그 확인

2.3 Jenkins 초기 설정

# Jenkins 초기 관리자 비밀번호 확인
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

웹 브라우저에서 http://[서버IP]:8080에 접속하여:

위에서 확인한 초기 비밀번호 입력
"Install suggested plugins" 선택 (권장)
관리자 계정 생성
Jenkins URL 설정

3. .NET 개발 환경 구축

3.1 .NET SDK 설치

# Microsoft 패키지 저장소 추가
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# .NET SDK 설치
sudo apt update
sudo apt install -y dotnet-sdk-8.0

# 설치 확인
dotnet --version

3.2 Git 설정

# Git 설치 (보통 이미 설치되어 있음)
sudo apt install git -y

# Git 사용자 정보 설정 (사용자)
sudo -u jenkins git config --global user.name "사용자 이름"
sudo -u jenkins git config --global user.email "이메일"

4. systemd 서비스 설정

4.1 애플리케이션용 systemd 서비스 생성

#.Net 서비스 파일 생성
sudo nano /etc/systemd/system/{프로젝트명}.service

서비스 파일 내용

[Unit]
Description="프로젝트명" Service
After=network.target

[Service]
Type=simple
User=jenkins
Group=jenkins
#WorkingDirectory=/var/lib/jenkins/deployments/프로젝트명
WorkingDirectory="프로젝트 빌드파일 위치"

# 환경변수
Environment=ASPNETCORE_ENVIRONMENT=Development
Environment=ASPNETCORE_URLS=http://0.0.0.0:5117

#ExecStart=/usr/bin/dotnet 프로젝트.dll
ExecStart="프로젝트 실행파일(.dll)"

Restart=always
RestartSec=5
KillMode=mixed
KillSignal=SIGINT

[Install]
WantedBy=multi-user.target

4.2 환경변수 파일 생성 (민감한 정보 보호)

# 환경변수 디렉토리 생성
sudo mkdir -p /etc/fitness-api

# 환경변수 파일 생성
sudo nano /etc/fitness-api/environment

환경변수 파일 내용 예시:

# 데이터베이스 연결 문자열
ConnectionStrings__DefaultConnection=Server=localhost;Database=FitnessDB;User=dbuser;Password=your_secure_password;

# JWT 설정
JwtSettings__SecretKey=your_jwt_secret_key_here
JwtSettings__Issuer=Issuer
JwtSettings__Audience=Audience
JwtSettings__ExpiryMinutes=1440

# API 키들
ExternalApi__GoogleMaps=your_google_maps_api_key
ExternalApi__Payment=your_payment_gateway_key

# 로깅 설정
Serilog__MinimumLevel=Information

4.3 서비스 권한 설정 및 등록

# 환경변수 파일 권한 설정 (보안 강화)
sudo chown root:jenkins /etc/프로젝트 경로/environment
sudo chmod 640 /etc/프로젝트 경로/environment

# 배포 디렉토리 생성 및 권한 설정
sudo mkdir -p /var/lib/jenkins/deployments/프로젝트 폴더
sudo chown -R jenkins:jenkins /var/lib/jenkins/deployments

# systemd 서비스 등록
sudo systemctl daemon-reload
sudo systemctl enable 프로젝트명.service

5. Jenkins Job 생성 및 배포 스크립트

5.1 Jenkins Job 생성

사전 준비: Git 인증 정보 설정

Private repository이거나 Push 권한이 필요한 경우 반드시 인증 정보를 설정해야 합니다.

GitHub Personal Access Token 사용 (권장)

GitHub에서 토큰 생성:
- GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
- "Generate new token" 클릭
- 권한 선택: repo (전체 저장소 접근) 체크
- 토큰 복사 (한 번만 보여줌으로 별도의 메모장에 작성해두고 사용하길 권장합니다.)
Jenkins에 인증 정보 추가:
- Jenkins 관리 → Manage Credentials → System → Global credentials
- "Add Credentials" 클릭
- Kind: "Username with password" 선택
- Username: GitHub 사용자명
- Password: 위에서 생성한 Personal Access Token 입력
- ID: github-credentials (기억하기 쉬운 이름)
- Description: GitHub Personal Access Token

Jenkins Job 생성 단계:

Jenkins 대시보드 → "새 항목"
항목 이름: FitnessPT_API_Deploy
"Freestyle project" 선택
"소스 코드 관리" → Git 선택
- Repository URL:
  - HTTPS 방식: 깃 레포주소
- Credentials: 위에서 생성한 인증 정보 선택
- Branch: */main

연결 테스트:

Repository URL과 Credentials 설정 후 "Test Connection" 버튼 클릭
성공 시: "Credentials verified for user [username], repository [repo-name]"
실패 시: 인증 정보나 URL 확인 필요

5.2 배포 스크립트 생성

Jenkins Execute Shell에 입력할 스크립트

#!/bin/bash

echo "  자동배포를 시작합니다..."

# ================================================================
#   프로젝트 설정
# ================================================================
PROJECT_NAME="프로젝트명"
SERVICE_NAME=".Service 이름"
APP_PORT="5117"
BUILD_CONFIG="Release"
DEPLOY_PATH="/var/lib/jenkins/deployments/$PROJECT_NAME"

# 색상 정의 (가독성 향상)
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m'

# ================================================================
#  ️ 배포 프로세스
# ================================================================

echo -e "${YELLOW}  배포 설정:${NC}"
echo "  • 프로젝트: $PROJECT_NAME"
echo "  • 서비스명: $SERVICE_NAME"
echo "  • 포트: $APP_PORT"
echo "  • 빌드 구성: $BUILD_CONFIG"
echo "  • 배포 경로: $DEPLOY_PATH"
echo ""

# 1. 기존 서비스 중지
echo -e "${YELLOW}  기존 서비스 중지 중...${NC}"
sudo systemctl stop $SERVICE_NAME || echo "서비스가 실행 중이 아닙니다."

# 2. 이전 배포 파일 백업 (선택사항)
if [ -d "$DEPLOY_PATH" ]; then
    echo -e "${YELLOW}  이전 배포 파일 백업 중...${NC}"
    sudo cp -r $DEPLOY_PATH ${DEPLOY_PATH}_backup_$(date +%Y%m%d_%H%M%S) || true
fi

# 3. 배포 디렉토리 생성/정리
echo -e "${YELLOW}  배포 디렉토리 준비 중...${NC}"
sudo mkdir -p $DEPLOY_PATH
sudo rm -rf $DEPLOY_PATH/*

# 4. .NET 프로젝트 빌드
echo -e "${YELLOW}  .NET 프로젝트 빌드 중...${NC}"
dotnet clean
dotnet restore
dotnet publish -c $BUILD_CONFIG -o $DEPLOY_PATH --no-restore

if [ $? -ne 0 ]; then
    echo -e "${RED}❌ 빌드 실패!${NC}"
    exit 1
fi

# 5. 파일 권한 설정
echo -e "${YELLOW}  파일 권한 설정 중...${NC}"
sudo chown -R jenkins:jenkins $DEPLOY_PATH
sudo chmod +x $DEPLOY_PATH/$PROJECT_NAME

# 6. 서비스 시작
echo -e "${YELLOW}  서비스 시작 중...${NC}"
sudo systemctl start $SERVICE_NAME

# 7. 서비스 상태 확인
sleep 5
SERVICE_STATUS=$(sudo systemctl is-active $SERVICE_NAME)

if [ "$SERVICE_STATUS" = "active" ]; then
    echo -e "${GREEN}✅ 서비스가 성공적으로 시작되었습니다!${NC}"
    
    # 헬스체크
    echo -e "${YELLOW}  헬스체크 진행 중...${NC}"
    sleep 10
    
    if curl -f http://localhost:$APP_PORT/health > /dev/null 2>&1; then
        echo -e "${GREEN}✅ 헬스체크 성공!${NC}"
    else
        echo -e "${YELLOW}⚠️  헬스체크 실패 (서비스는 실행 중)${NC}"
    fi
    
    # 최종 결과 출력
    echo ""
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo -e "${GREEN}  배포 완료!${NC}"
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo "프로젝트: $PROJECT_NAME"
    echo "포트: $APP_PORT"
    echo "URL: http://localhost:$APP_PORT"
    echo "배포 위치: $DEPLOY_PATH"
    echo "로그 확인: sudo journalctl -u $SERVICE_NAME -f"
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo ""
    
    # 실행 중인 프로세스 정보
    echo "실행 중인 프로세스:"
    ps aux | grep "$PROJECT_NAME" | grep -v grep || echo "프로세스 정보 조회 실패"
    
else
    echo -e "${RED}❌ 서비스 시작 실패!${NC}"
    echo "서비스 로그 확인:"
    sudo journalctl -u $SERVICE_NAME --no-pager -l
    exit 1
fi

echo -e "${GREEN}✅ 모든 작업 완료!${NC}"

빌드 스크립트의 경우 프로젝트의 설정마다 일부 차이가 있을 수 있습니다.
기본적인 .NET 프로젝트 기준으로 작성된 스크립트로서 빌드 오류가 발생시 프로젝트에 맞추어 수정이 필요할 수 있습니다.

6. 보안 설정 및 환경변수 관리

6.1 Jenkins 사용자 sudo 권한 설정

# Jenkins 사용자에게 특정 명령어만 sudo 권한 부여
sudo visudo

다음 내용 추가

# Jenkins가 서비스 관리만 할 수 있도록 제한
jenkins ALL=(ALL) NOPASSWD: /bin/systemctl start 프로젝트명, /bin/systemctl stop 프로젝트명, /bin/systemctl restart 프로젝트명, /bin/systemctl status 프로젝트명, /bin/journalctl -u 프로젝트명*

6.2 환경변수 보안 관리

# 환경변수 파일 암호화 (선택사항)
sudo apt install gpg -y

# 환경변수 파일 백업
sudo cp /etc/프로젝트명/environment /etc/프로젝트명/environment.backup

# 권한 재확인
sudo ls -la /etc/프로젝트명/

7. 트러블슈팅 및 모니터링

7.1 로그 모니터링

# Jenkins 로그 확인
sudo journalctl -u jenkins -f

# 애플리케이션 로그 확인
sudo journalctl -u 프로젝트명 -f

# 시스템 로그 확인
sudo tail -f /var/log/syslog

7.2 포트 및 프로세스 확인

# 포트 사용 현황 확인
sudo netstat -tulpn | grep :5117

# 실행 중인 프로세스 확인
ps aux | grep 프로젝트명

# 서비스 상태 확인
sudo systemctl status 프로젝트명

7.3 일반적인 문제 해결

문제 1: 빌드 실패

# .NET SDK 버전 확인
dotnet --version

# 프로젝트 의존성 복원
dotnet restore --force

# 캐시 정리
dotnet clean

문제 2: 서비스 시작 실패

# 서비스 로그 상세 확인
sudo journalctl -u 프로젝트명 -n 50

# 환경변수 파일 문법 검사
sudo systemd-analyze verify /etc/systemd/system/프로젝트명.service

# 권한 문제 해결
sudo chown -R jenkins:jenkins /var/lib/jenkins/deployments

문제 3: 포트 충돌

# 포트를 사용하는 프로세스 찾기
sudo lsof -i :{프로젝트 내부 포트}

# 해당 프로세스 종료
sudo kill -9 [PID]

마무리 및 추가 개선사항

완성된 CI/CD 파이프라인의 특징

자동화: Git 푸시 → 자동 빌드 → 자동 배포
보안: 환경변수로 민감 정보 보호
안정성: systemd 서비스로 프로세스 관리
모니터링: 상세한 로깅 및 헬스체크
확장성: 다른 프로젝트에도 쉽게 적용 가능

세팅 이후 내용을 정리한 가이드로서 진행중 이슈가 있을 수 있습니다.

도움이 필요한 부분은 댓글을 남겨주시면 내용 수정 및 추가 가이드 안내 드리겠습니다.