배포

ASP.NET Core 앱은 Kestrel 웹 서버를 품은 일반 프로세스입니다. 배포는 컴파일된 결과물을 게시(publish)하고, 운영 설정으로 실행하며, 보통 리버스 프록시 뒤나 컨테이너 안에 두는 과정입니다.

dotnet publish

# 프레임워크 종속: 서버에 ASP.NET Core 런타임이 필요합니다
dotnet publish -c Release -o ./publish
dotnet ./publish/TodoApi.dll

# Linux x64용 자체 포함: 런타임이 함께 들어갑니다
dotnet publish -c Release -r linux-x64 --self-contained -o ./publish
./publish/TodoApi

최소 API 앱은 네이티브 AOT(<PublishAot>true</PublishAot> 또는 webapiaot 템플릿)로 게시해 시작 시간과 메모리 사용을 줄일 수도 있습니다. 다만 MVC 컨트롤러를 쓸 수 없는 등 제약이 있습니다.

운영 설정

환경은 기본적으로 Production입니다. 비밀 값과 연결 문자열은 환경 변수나 비밀 저장소로 넘기고, 수신 주소는 ASPNETCORE_URLS나 ASPNETCORE_HTTP_PORTS로 정합니다.

export ConnectionStrings__Default="Host=db;Database=todo;Username=app;Password=change-me"
export ASPNETCORE_URLS="http://127.0.0.1:5000"
dotnet ./publish/TodoApi.dll

리버스 프록시 뒤의 Kestrel

Kestrel은 운영 환경에서 그대로 쓸 수 있지만, Nginx, Apache, IIS, 클라우드 부하 분산기 같은 리버스 프록시가 TLS 종료, 한 IP에서 여러 사이트 운영, 요청 제한을 맡는 경우가 많습니다. 프록시는 Kestrel과 평문 HTTP로 통신하므로, 앱은 X-Forwarded-* 헤더에서 원래의 스킴과 클라이언트 IP를 읽어야 합니다.

using Microsoft.AspNetCore.HttpOverrides;

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

var app = builder.Build();
app.UseForwardedHeaders();   // 다른 미들웨어보다 먼저

기본값으로는 같은 컴퓨터의 프록시만 신뢰하므로, 프록시가 다른 곳에 있으면 그 주소를 KnownProxies에 추가합니다. 이에 맞는 Nginx 사이트 설정은 다음과 같습니다.

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass         http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header   Host $host;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Linux에서는 systemd 서비스로 앱을 계속 실행합니다.

[Unit]
Description=Todo API

[Service]
WorkingDirectory=/var/www/todoapi
ExecStart=/usr/bin/dotnet /var/www/todoapi/TodoApi.dll
Restart=always
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://127.0.0.1:5000

[Install]
WantedBy=multi-user.target

Windows에서는 .NET Hosting Bundle로 설치되는 ASP.NET Core Module을 통해 IIS가 앱을 호스팅합니다.

컨테이너

SDK는 Dockerfile 없이도 컨테이너 이미지를 만들 수 있습니다.

dotnet publish --os linux --arch x64 /t:PublishContainer -p:ContainerRepository=todoapi -p:ContainerImageTag=1.0
docker run --rm -p 8080:8080 todoapi:1.0

다단계 Dockerfile을 직접 쓸 수도 있습니다. 이미지 태그는 프로젝트의 TargetFramework에 맞춥니다.

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY *.csproj ./
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app --no-restore

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
USER $APP_UID
ENTRYPOINT ["dotnet", "TodoApi.dll"]

공식 .NET 이미지는 기본으로 8080 포트에서 수신하고 루트가 아닌 사용자(APP_UID)를 포함합니다. 오케스트레이터와 부하 분산기를 위해 builder.Services.AddHealthChecks()와 app.MapHealthChecks("/healthz")로 상태 확인 엔드포인트를 추가해 둡니다.

정리

• dotnet publish로 프레임워크 종속 또는 자체 포함 결과물을 만듭니다.
• 운영 설정은 환경 변수로 넘기고, 비밀 값을 appsettings.json에 넣어 배포하지 않습니다.
• 프록시 뒤에서는 전달 헤더(forwarded headers)를 켜고 Kestrel은 로컬 주소에서만 수신합니다.
• 컨테이너는 /t:PublishContainer나 다단계 Dockerfile로 만듭니다.

공식 문서

• Host and deploy ASP.NET Core
• Host ASP.NET Core on Linux with Nginx
• Configure ASP.NET Core to work with proxy servers and load balancers
• Containerize a .NET app with dotnet publish
• ASP.NET Core 문서