Base64는 주로 어디에 쓰일까?

Base64는 바이너리 데이터를 텍스트(ASCII) 형태로 변환해야 할 때 사용한다. 텍스트만 허용되는 채널에서 바이너리를 안전하게 전송·저장하는 것이 핵심 목적이다.

대표적인 사용처

이메일 (MIME) — SMTP는 7-bit ASCII 기반 프로토콜이다. 이미지·첨부파일 같은 바이너리를 본문에 실으려면 base64로 인코딩해야 한다. Content-Transfer-Encoding: base64 헤더가 붙는 경우가 바로 이것이다.

웹/API 통신 — JSON이나 XML 같은 텍스트 포맷 안에 이미지·PDF 등 바이너리 파일을 넣을 때 활용된다. Anthropic API에 이미지를 보낼 때 source.type: "base64"로 넣는 패턴이 대표적이다. Data URI(data:image/png;base64,…)로 HTML/CSS에 이미지를 인라인 삽입할 때도 동일한 원리다.

인증 헤더 — HTTP Basic Authentication에서 username:password 문자열을 base64로 변환해 Authorization: Basic <encoded> 형태로 전송한다. 암호화가 아니라 단순 변환이므로 보안 목적은 아니다.

인증서·키 저장 — PEM 형식의 SSL/TLS 인증서, SSH 공개키 등이 base64로 표현되어 -----BEGIN CERTIFICATE----- 블록 안에 들어간다.

쿠키·토큰 — JWT의 header/payload 부분이 base64url로 처리되고, 쿠키에 구조화된 값을 담을 때도 종종 활용된다.

정리하면, base64 자체는 암호화나 압축이 아니라 "바이너리 → 텍스트 안전 변환"이 본질이며, 텍스트 전용 프로토콜·포맷과 바이너리 사이의 브릿지 역할을 한다. 다만 원본 대비 약 33% 크기가 늘어나는 오버헤드가 있어서, 대용량 파일에는 멀티파트 전송이 더 효율적이다.

Base64 말고 다른 종류들

문자 인코딩 (Character Encoding)

텍스트를 바이트로 표현하는 방식이다. ASCII가 영문 128자만 다루던 한계를 넘어 다국어를 지원하는 방향으로 발전해 왔다.

• ASCII — 7비트, 영문·숫자·기본 기호만 표현 (0~127)
• EUC-KR / CP949 — 한글 완성형. 과거 한국 웹에서 널리 쓰였고, 지금도 레거시 시스템에서 만난다
• UTF-8 — 가변 길이(1~4바이트) 유니코드 구현체. 현재 웹 표준이며 ASCII와 하위 호환된다
• UTF-16 — 2 또는 4바이트. JavaScript 내부 문자열, Windows API 등에서 채택
• UTF-32 — 고정 4바이트. 처리는 단순하지만 메모리 낭비가 커서 실무에선 드물다
• ISO-8859-1 (Latin-1) — 서유럽어 확장. HTTP 기본 charset으로 오래 활용되었다

바이너리→텍스트 (Binary-to-Text)

base64와 같은 계열로, 바이너리를 텍스트 안전 문자열로 바꾼다.

• Base32 — AZ + 27 사용. 대소문자 구분 없는 환경(DNS, OTP 시크릿)에 적합
• Base16 (Hex) — 09, AF. MAC 주소, 해시값, 색상 코드(#FF5733) 등에서 일상적으로 볼 수 있다
• Base85 (Ascii85) — base64보다 효율적(약 25% 오버헤드). PDF 내부, Git 바이너리 패치에 쓰인다
• Quoted-Printable — 이메일에서 대부분 ASCII인 텍스트에 간헐적 비ASCII 문자가 섞일 때 활용. =EC=9D=B4 같은 형태
• UUencode — Unix 시절 이메일 첨부 방식. base64/MIME에 거의 대체되었다

웹/URL

• Percent-encoding (URL encoding) — URL에 넣을 수 없는 문자를 %XX 형태로 변환. 예: 공백 → %20, 한글 → %ED%95%9C
• HTML Entity encoding — HTML 특수문자를 안전하게 표현. < → <, & → &, 숫자 참조 가 등

전송/압축 (Transfer Encoding)

전송 효율이나 스트리밍을 위한 방식이다.

• Chunked Transfer Encoding — HTTP/1.1에서 전체 크기를 모른 채 응답을 조각 단위로 전송
• gzip / deflate / br (Brotli) — HTTP Content-Encoding 헤더로 지정. 엄밀히는 압축이지만 전송 계층으로 분류되기도 한다

미디어 (Audio/Video/Image)

• 영상 — H.264, H.265(HEVC), VP9, AV1
• 음성 — AAC, Opus, MP3, FLAC
• 이미지 — JPEG, PNG, WebP, AVIF

이들은 "코덱"이라고도 부르며, 손실/무손실 압축과 디코딩 규격을 함께 정의한다.

보안 관련 변환

변환과 암호화는 다르지만, 실무에서 함께 언급되는 경우가 많다.

• 해싱 — SHA-256, MD5 등. 단방향 처리라 디코딩 불가. 무결성 검증·비밀번호 저장용
• 암호화 — AES, RSA, ChaCha20 등. 키가 있어야 복호화 가능. 파이프라인에서 인코딩과 결합되어 활용된다 (예: 암호화 → base64 → JSON 전송)

핵심 구분은 목적이다. 문자 표현이면 UTF-8 계열, 바이너리의 텍스트 안전 변환이면 base64 계열, 전송 효율이면 gzip/chunked, 미디어 압축이면 코덱.

바이너리→텍스트 인코딩, 실제로 어디서 쓰이나?

바이너리→텍스트 변환이 추상적으로 느껴지는 이유는, 대부분 "이미 변환된 결과물"을 매일 보면서도 그 사실을 의식하지 못하기 때문이다.

핵심 전제: 왜 필요한가?

세상에는 "텍스트만 통과시키는 통로"가 생각보다 많다. JSON, XML, HTTP 헤더, 이메일 본문, 환경변수, 설정 파일, 소스코드 — 이런 곳에 바이너리(이미지, 인증서, 암호화 결과물 등)를 넣으려면 텍스트로 바꿔야 한다. 그 변환기가 base64, hex 같은 바이너리→텍스트 기법이다.

1. SSH 키 / SSL 인증서 (Base64)

~/.ssh/id_rsa.pub를 열어보면 이런 형태다:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... user@host

가운데 긴 문자열이 base64이다. 공개키의 실체는 바이너리 숫자(큰 정수)인데, 이걸 텍스트 파일에 한 줄로 저장하고 터미널에 복사·붙여넣기 하려면 텍스트여야 한다. NHN Cloud 인스턴스에 SSH 키 등록할 때 콘솔에 붙여넣는 것도 같은 이유다.

SSL 인증서(*.pem)도 마찬가지다:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkq...
-----END CERTIFICATE-----

nginx 설정에서 ssl_certificate 경로를 지정하면 nginx가 이 base64를 디코딩해서 바이너리 인증서로 해석한다.

2. 이메일 첨부파일 (Base64)

이메일로 이미지를 보내면, 실제 전송되는 원문(raw message)은 이렇다:

Content-Type: image/png; name="photo.png"
Content-Transfer-Encoding: base64

iVBORw0KGgoAAAANSUhEUgAAAPAAAADwCAYAAAA+VemSAAA...

SMTP는 7-bit 텍스트 프로토콜이라 PNG 바이너리를 그대로 보낼 수 없다. 메일 클라이언트가 자동으로 base64 처리해서 전송하고, 수신 측에서 복원하는 것이다. 우리가 의식하지 못할 뿐 매일 일어나는 일이다.

3. API 요청 안에 파일 담기 (Base64)

Anthropic API에 이미지를 보내는 코드가 대표적이다:

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "/9j/4AAQSkZJRgABAQ..."
  }
}

JSON은 텍스트 포맷이라 바이너리 바이트를 직접 넣을 수 없다. multipart/form-data로 파일을 따로 보내는 방법도 있지만, JSON body 하나로 깔끔하게 처리하고 싶을 때 base64가 활용된다.

4. Data URI — HTML/CSS 안에 이미지 삽입 (Base64)

<img src="data:image/png;base64,iVBORw0KGgo..." />

별도 HTTP 요청 없이 HTML 자체에 이미지를 포함시킨다. 아이콘 같은 작은 이미지에 적용하면 네트워크 왕복을 줄일 수 있다. 이메일 HTML 템플릿에서 특히 많이 쓰인다 (외부 이미지 URL이 차단되는 메일 클라이언트 대응).

5. JWT 토큰 (Base64url)

로그인 후 받는 JWT를 .으로 쪼개면 세 파트다:

eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjN9.서명부분

앞 두 파트를 base64url 디코딩하면:

{"alg":"HS256"}
{"user_id":123}

JSON 객체를 HTTP 헤더(Authorization: Bearer ...)나 URL 파라미터에 넣어야 하는데, JSON을 그대로 넣으면 {, ", : 같은 특수문자가 문제를 일으킨다. base64url로 감싸면 알파벳·숫자·-·_만 남아서 어디에든 안전하게 들어간다.

6. Git 바이너리 diff (Base85)

Git에서 이미지 파일이 변경되면 diff에 이런 내용이 나타난다:

diff --git a/icon.png b/icon.png
GIT binary patch
literal 2345
zcmV+^3E7mhP)<h;3K|Lk000e1NJLTq...

텍스트 기반 diff/patch 포맷 안에 바이너리 변경분을 담기 위해 base85를 채택한다.

7. Hex (Base16) — 해시값, MAC 주소, 디버깅

매일 접하는 것들이다:

sha256sum file.tar.gz
# e3b0c44298fc1c149afbf4c8996fb924...  ← hex로 표현된 해시

ip link show
# link/ether 3a:2b:1c:4d:5e:6f  ← MAC 주소도 hex

hexdump -C /dev/urandom | head
# 바이너리 파일 내용을 사람이 읽을 수 있게 hex로 표시

해시 함수의 출력은 바이너리(32바이트 등)인데, 터미널에 표시하거나 로그에 기록하려면 hex 문자열로 변환한다.

정리하면 패턴은 하나다: "텍스트만 허용되는 곳에 바이너리를 넣어야 할 때." JSON, HTTP 헤더, 이메일, 설정 파일, 소스코드, 터미널 출력 — 이 모든 텍스트 전용 통로가 존재하는 한 바이너리→텍스트 기법은 계속 쓰인다. 눈에 잘 안 보이는 이유는 대부분 라이브러리나 프로토콜이 자동 처리해주기 때문이다.

바이너리는 0과 1인데 이게 이미지라고?

맞다. 바이너리는 0과 1의 나열이 맞고, 이미지도 음악도 영상도 결국 전부 0과 1이다. 핵심은 "해석 방식이 다르다"는 것이다.

컴퓨터에서 모든 것은 바이너리

텍스트 파일도 바이너리다. 예를 들어 A라는 글자는 내부적으로 01000001(65번)로 저장된다. 다만 텍스트 파일은 모든 바이트가 "사람이 읽을 수 있는 문자 범위(0~127)" 안에 있어서, 에디터로 열면 글자로 보이는 것이다.

반면 PNG 이미지 파일을 메모장으로 열어보면 ‰PNG\r\n... 뒤에 깨진 문자가 쏟아진다. 같은 0과 1인데 "문자로 해석할 수 없는 바이트"가 대부분이기 때문이다.

이미지가 바이너리인 구조

3×2 픽셀짜리 아주 작은 이미지가 있다고 하면, 각 픽셀은 RGB 값을 가진다:

픽셀(0,0) = 빨강 255, 초록 0, 파랑 0

이걸 바이너리로 쓰면:

11111111 00000000 00000000

이게 한 픽셀이고, 이런 바이트가 수십만~수백만 개 이어지면 사진 한 장이 된다. 거기에 파일 헤더(이미지 크기, 포맷 정보 등)가 앞에 붙고, 압축 알고리즘이 적용되면 PNG나 JPEG 파일이 되는 것이다.

"텍스트"와 "바이너리"의 실무적 구분

둘 다 0과 1인 건 같지만, 실무에서 말하는 구분은 이것이다:

텍스트 — 모든 바이트가 문자로 매핑되는 형태. JSON, HTML, 소스코드, 설정 파일 등. 에디터로 열면 사람이 읽을 수 있다.

바이너리 — 문자 범위 밖의 바이트가 포함된 형태. 이미지, 동영상, 실행파일, 압축 아카이브 등. 에디터로 열면 깨져 보인다.

그래서 base64가 필요한 이유

JSON 같은 텍스트 포맷은 "문자"만 담을 수 있게 설계되어 있다. 그런데 이미지 바이너리에는 0x00(null), 0x89, 0xFF 같은 바이트가 들어 있고, 이런 값들을 JSON 문자열 안에 그대로 넣으면 파싱이 깨진다.

base64가 하는 일:

원본 바이너리:  10001001 01010000 01001110 01000111 ...
                (0x89)    (P)      (N)      (G)

 ↓ base64 변환

텍스트 문자열:  "iVBORw0KGgo..."
                (A~Z, a~z, 0~9, +, / 만 사용)

0x89 같은 "텍스트로 표현 불가능한 바이트"까지 포함해서 전부 알파벳·숫자 조합으로 바꿔주는 것이다. 받는 쪽에서 다시 디코딩하면 원본이 그대로 복원된다.

바이너리→텍스트 변환은 "모든 바이트를 문자 안전 영역으로 옮기는 번역"이라고 생각하면 된다.

Django에서 base64를 만나는 경우

Django가 내부적으로 자동 처리하는 경우

CSRF 토큰 — {% csrf_token %}이 생성하는 토큰 값이 base64로 처리되어 있다. 내부적으로 랜덤 바이트를 생성한 뒤 변환해서 폼 hidden 필드나 쿠키에 넣는다. 바이너리 랜덤 값을 HTML과 쿠키(텍스트 통로)에 안전하게 담기 위해서다.

세션 — SESSION_ENGINE이 기본 DB 백엔드일 때, 세션 딕셔너리를 직렬화한 뒤 base64로 변환해서 저장한다. django_session 테이블의 session_data 컬럼을 직접 보면 base64 문자열이 들어 있는 것을 확인할 수 있다.

비밀번호 해싱 — PBKDF2로 해싱된 비밀번호가 DB에 저장될 때 형태가 이렇다:

pbkdf2_sha256$600000$salt$hash값

여기서 salt와 hash 부분이 base64로 표현된 바이너리다. 해시 함수 출력은 바이너리인데 DB varchar 컬럼(텍스트)에 저장해야 하기 때문이다.

Signed Cookie / signing 모듈 — django.core.signing이 HMAC 서명값을 base62/base64로 변환한다. 쿠키나 URL에 들어가야 하니까 텍스트 안전 형태가 필요하다.

API 개발할 때 직접 쓰는 경우

클라이언트에서 이미지를 JSON으로 받을 때 — 모바일 앱이나 프론트엔드가 파일을 multipart/form-data 대신 JSON body에 base64로 담아 보내는 경우:

import base64
from django.core.files.base import ContentFile

def upload_profile(request):
    data = json.loads(request.body)
    # "data:image/png;base64,iVBORw0KGgo..." 형태로 올 수 있음
    image_data = data['image'].split(',')[1]  # base64 부분만 추출
    binary = base64.b64decode(image_data)
    file = ContentFile(binary, name='profile.png')
    # 이후 모델에 저장하거나 Object Storage에 업로드

API 응답으로 작은 파일을 내려줄 때 — 별도 파일 다운로드 엔드포인트를 만들기 번거로울 때, 썸네일 같은 작은 이미지를 JSON 응답에 포함시키기도 한다:

import base64

def get_thumbnail(request, pk):
    obj = MyModel.objects.get(pk=pk)
    with obj.thumbnail.open('rb') as f:
        encoded = base64.b64encode(f.read()).decode('ascii')
    return JsonResponse({
        'thumbnail': f'data:image/jpeg;base64,{encoded}'
    })

외부 API 연동에서 Basic Auth — 외부 서비스를 호출할 때:

import base64
import requests

credentials = base64.b64encode(b'api_user:api_password').decode()
response = requests.get(url, headers={
    'Authorization': f'Basic {credentials}'
})

바이너리를 캐시에 저장할 때 — Redis 캐시에 바이너리를 넣어야 할 때 base64로 변환하면 직렬화 문제를 피할 수 있다.

공통 패턴

Django에서 base64가 등장하는 모든 경우를 관통하는 공통점은, DB 컬럼(텍스트), JSON 응답(텍스트), 쿠키(텍스트), HTTP 헤더(텍스트) 같은 텍스트 전용 통로에 바이너리 값(해시, 서명, 이미지, 랜덤 토큰)을 넣어야 하는 상황이라는 것이다. 프레임워크가 내부적으로 해주는 것과 개발자가 직접 하는 것의 차이만 있을 뿐, 원리는 동일하다.

Django + Gunicorn 환경에서 로그를 파일로 기록하고, logrotate로 자동 관리하며, 쌓인 데이터를 별도 블록 스토리지에 연/월 구조로 보관하는 전 과정을 다룬다.

목차

1. 블록 스토리지 연결 및 마운트
2. Gunicorn 로그 출력 설정
3. Logrotate 옵션 상세 정리
4. Logrotate 설정 작성
5. 아카이브 스크립트 설계
6. 디스크 사용량 계산
7. 기존 거대 로그 정리
8. 요약

1. 블록 스토리지 연결 및 마운트

1-1. 현재 디스크 상태 확인

lsblk

마운트 여부와 관계없이 연결된 블록 디바이스를 모두 트리 형태로 보여준다. 파일시스템 타입과 UUID까지 함께 확인하려면 -f 옵션을 붙인다.

lsblk -f

NHN Cloud 등 클라우드 환경에서 추가 볼륨을 attach하면 vdb와 같은 이름으로 나타난다.

1-2. 파티션 분리 여부 판단

클라우드 블록 스토리지를 단순 용량 확장 목적으로 쓴다면, 파티션 없이 디스크 전체를 그대로 사용하는 것이 깔끔하다. 파티션이 유용한 경우는 다음과 같다.

• 용도별(/data, /logs)로 용량을 강제 제한하고 싶을 때
• 한 영역이 꽉 차도 나머지에 영향이 없도록 격리하고 싶을 때

1-3. 포맷 및 마운트

# ext4로 포맷
sudo mkfs.ext4 /dev/vdb

# 마운트 포인트 생성
sudo mkdir -p /mnt/data

# 마운트
sudo mount /dev/vdb /mnt/data

# 확인
df -h

1-4. 재부팅 후 자동 마운트 (fstab 등록)

장치명(vdb)은 재부팅 시 바뀔 수 있어 UUID 기반으로 등록해야 안전하다.

# UUID 확인
sudo blkid /dev/vdb

출력 예시:

/dev/vdb: UUID="3de85581-2e2a-43f5-878e-b6a87d2fd905" BLOCK_SIZE="4096" TYPE="ext4"

# fstab에 추가
echo "UUID=3de85581-2e2a-43f5-878e-b6a87d2fd905  /mnt/data  ext4  defaults  0  2" | sudo tee -a /etc/fstab

# 재부팅 없이 검증
sudo mount -a

# 최종 확인
df -h

2. Gunicorn 로그 출력 설정

2-1. 문제: stdout으로 흘러가는 기본 구성

일반적인 gunicorn.service 파일은 이렇게 되어 있다.

ExecStart=/path/to/.venv/bin/gunicorn \
          --access-logfile - \
          --error-logfile - \
          ...

여기서 -는 stdout/stderr로 출력한다는 의미다. journald로만 데이터가 흘러가 별도 경로에 기록되지 않는다. journald는 용량 제한이 있고 검색도 불편하기 때문에, 운영 환경에서는 직접 경로를 지정하는 것이 일반적이다.

2-2. 로그 디렉토리 생성

sudo mkdir -p /var/log/mch_api
sudo chown ubuntu:www-data /var/log/mch_api
sudo chmod 755 /var/log/mch_api

• ubuntu:www-data: gunicorn이 ubuntu 계정으로 구동되므로 해당 소유자에게 쓰기 권한을 부여한다.
• 디렉토리명은 서비스에 맞게 자유롭게 지정(ssc_api, mch_api 등).

2-3. gunicorn.service 수정

[Unit]
Description=gunicorn daemon for MCH
Requires=gunicorn.socket
After=network.target

[Service]
User=ubuntu
Group=www-data
WorkingDirectory=/workspace/smart-silver-center/ssc-api

ExecStart=/workspace/smart-silver-center/ssc-api/.venv/bin/gunicorn \
          --access-logfile /var/log/mch_api/access.log \
          --error-logfile /var/log/mch_api/error.log \
          --workers 4 \
          --threads 2 \
          --worker-class gthread \
          --timeout 60 \
          --graceful-timeout 30 \
          --max-requests 1000 \
          --max-requests-jitter 100 \
          --keep-alive 5 \
          --bind unix:/run/gunicorn.sock \
          --preload \
          --capture-output \
          --enable-stdio-inheritance \
          --log-level info core.michuhol.wsgi:application

Environment="ENV_FILE=.env"
Restart=on-failure
RestartSec=5
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

변경점은 두 줄이다.

- --access-logfile - \
- --error-logfile - \
+ --access-logfile /var/log/mch_api/access.log \
+ --error-logfile /var/log/mch_api/error.log \

2-4. 적용 및 확인

sudo systemctl daemon-reload
sudo systemctl restart gunicorn

# 경로 생성 확인
ls -la /var/log/mch_api/

# 실시간 확인
tail -f /var/log/mch_api/access.log

기록이 안 된다면 아래 순서로 점검한다.

sudo systemctl status gunicorn.service
sudo journalctl -u gunicorn.service -n 30 --no-pager
ls -la /var/log/ | grep mch_api
cat /etc/systemd/system/gunicorn.service | grep logfile

3. Logrotate 옵션 상세 정리

3-1. 회전 주기

API 서버라면 daily가 일반적이다.

3-2. 보관 관련

3-3. 압축 관련

3-4. 파일 생성/처리

3-5. 예외 처리

3-6. 스크립트 실행

postrotate
    systemctl reload gunicorn 2>/dev/null || true
endscript

sharedscripts가 없으면 access.log 회전 후 한 번, error.log 회전 후 또 한 번 reload가 중복 호출된다.

2>/dev/null 이란?

리눅스의 모든 프로세스는 세 가지 기본 스트림을 가진다.

즉 2>/dev/null은 stderr(에러 메시지)를 /dev/null(쓰레기통)로 버리라는 의미다.

systemctl reload gunicorn 2>/dev/null || true
#                          ↑              ↑
#             에러 메시지 무시    실패해도 종료 코드 0으로 처리

gunicorn이 내려가 있거나 reload 자체가 실패해도, logrotate 전체가 오류로 처리되지 않도록 하는 방어 코드다.

3-7. 네이밍

4. Logrotate 설정 작성

4-1. 설정 파일 생성

/etc/logrotate.d/ 아래에 서비스명으로 생성한다. 파일 이름은 서비스명과 일치할 필요 없다. 중요한 건 안에 적는 경로다.

sudo nano /etc/logrotate.d/ssc_api

4-2. 내용

/var/log/ssc_api/*.log {
    daily
    missingok
    rotate 14
    maxsize 100M
    compress
    delaycompress
    notifempty
    create 0644 ubuntu www-data
    dateext
    sharedscripts
    postrotate
        systemctl reload gunicorn 2>/dev/null || true
        /usr/local/bin/archive_logs.sh >> /var/log/archive_logs.log 2>&1
    endscript
}

4-3. 검증 및 실행

# 문법 검증 (dry-run, 실제 동작 없음)
sudo logrotate -d /etc/logrotate.d/ssc_api

# 강제 실행 + verbose
sudo logrotate -vf /etc/logrotate.d/ssc_api

# 결과 확인
ls -lh /var/log/ssc_api/

logrotate는 데몬이 아니므로 설정 수정 후 별도 재시작이 필요 없다. cron이 매일 호출하는 구조이기 때문에, 저장 즉시 다음 실행부터 반영된다.

자주 보이는 메시지

glob finding logs to compress failed
glob finding old rotated logs failed

에러가 아니다. "이전에 회전된 항목을 찾으려 했는데 아직 없다"는 정보성 메시지로, 최초 실행 시 정상적으로 출력된다.

5. 아카이브 스크립트 설계

5-1. 전체 구조

/var/log/ssc_api/              ← 현재 활성 로그 (그대로 유지)
    gunicorn_access.log
    gunicorn_error.log
    gunicorn_error.log-20260304  ← delaycompress 대기 중 (미압축)

/mnt/data/logs/ssc_api/        ← 압축 완료된 항목 아카이브
    2026/
        03/
            gunicorn_access.log-20260301.gz
            gunicorn_error.log-20260304.gz
        04/
            ...

5-2. 디렉토리 준비

sudo mkdir -p /mnt/data/logs/ssc_api
sudo chown ubuntu:ubuntu /mnt/data/logs/ssc_api

5-3. 스크립트 작성

sudo nano /usr/local/bin/archive_logs.sh

#!/bin/bash

SRC="/var/log/ssc_api"
DEST="/mnt/data/logs/ssc_api"

# .gz 항목만 대상 (delaycompress로 압축 완료된 것만)
for f in "$SRC"/*.log-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]*.gz; do
    [ -f "$f" ] || continue

    filename=$(basename "$f")

    # 파일명에서 날짜 추출 (예: gunicorn_access.log-20260304.gz → 20260304)
    datestr=$(echo "$filename" | grep -oP '\d{8}')
    [ -z "$datestr" ] && continue

    year="${datestr:0:4}"
    month="${datestr:4:2}"

    target_dir="$DEST/$year/$month"
    mkdir -p "$target_dir"

    mv "$f" "$target_dir/"
    echo "[$(date)] Archived: $filename → $target_dir/"
done

sudo chmod +x /usr/local/bin/archive_logs.sh

5-4. ⚠️ delaycompress와의 충돌 주의

delaycompress는 직전 회전본을 하루 동안 압축하지 않은 채 둔다. glob 패턴을 .gz 없이 작성하면 미압축 항목도 매칭되어 /mnt/data로 이동해버린다. 다음 날 logrotate가 압축 대상을 찾지 못해 아카이브에 비압축 항목이 쌓이는 결과로 이어진다.

# ❌ 잘못된 패턴 (미압축도 매칭됨)
"$SRC"/*.log-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]*

# ✅ 올바른 패턴 (압축 완료본만 이동)
"$SRC"/*.log-[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]*.gz

5-5. 전체 동작 흐름 검증

Day 1 logrotate 실행:
  - access.log → access.log-20260303 (압축 안 됨, delaycompress)
  - postrotate: archive_logs.sh → .gz 없으므로 아무것도 안 함 ✅

Day 2 logrotate 실행:
  - access.log-20260303 → access.log-20260303.gz (압축 완료)
  - access.log → access.log-20260304 (새로 회전)
  - postrotate: archive_logs.sh → access.log-20260303.gz를 /mnt/data/2026/03/ 으로 이동 ✅

/var/log/ssc_api/ 에는:
  - gunicorn_access.log          (현재 활성)
  - gunicorn_access.log-20260304 (어제, 아직 압축 전)
  → 깔끔하게 유지 ✅

5-6. cron 등록 (보조 보험용)

수동 생성 항목 등 누락 케이스를 대비한 추가 트리거다.

sudo crontab -e

# 매일 새벽 2시 실행
0 2 * * * /usr/local/bin/archive_logs.sh >> /var/log/archive_logs.log 2>&1

이미 이동된 항목은 glob 매칭에서 걸리지 않으므로 중복 실행해도 무방하다.

6. 디스크 사용량 계산

6-1. 일일 생성량 파악

gunicorn_access.log   2.6GB / 5일 → 약 520MB/day
gunicorn_error.log    582MB / 5일 → 약 116MB/day

6-2. 회전 빈도 계산

maxsize 100M 적용 시:

• access: 520MB ÷ 100MB = 하루 약 5회 회전
• error: 116MB ÷ 100MB = 하루 약 1~2회 회전

6-3. 실제 보관 기간

rotate 14는 회전된 항목 14개를 유지한다는 뜻이다. 하루에 5회 회전한다면 14개는 약 2~3일치에 불과하다.

14일치 보장이 필요하다면:

rotate 70      # 하루 5회 × 14일 = 70개

6-4. 디스크 사용량 추정

gzip 압축 시 텍스트 로그는 원본의 약 10~15% 수준이 된다.

access.log 기준 (rotate 14 적용):

error.log도 동일 구조로 약 344MB. 총 합계: 약 700MB (기존 7GB 대비 1/10 수준)

rotate 70 적용 시 약 1.2GB 수준으로 여전히 기존 대비 대폭 절감된다.

7. 기존 거대 로그 정리

logrotate 도입 전 이미 쌓인 대용량 항목은 수동으로 처리한다.

# 압축 보관
sudo gzip /var/log/ssc_api/gunicorn_access.log
sudo gzip /var/log/ssc_api/gunicorn_error.log

# 불필요하다면 삭제
sudo rm /var/log/ssc_api/gunicorn_access.log

# 여유 공간 확인
df -h /var/log

8. 요약

libnginx-mod-rtmp + ffmpeg 기반 HLS 미디어 서버에 Prometheus와 Grafana를 붙여 생사 여부를 실시간으로 파악하는 대시보드를 구축한 과정을 기록한다.

아키텍처 개요

nginx-rtmp (/stat) ──→ Python Exporter (9101)  ─┐
node_exporter (9100)                              ├──→ Prometheus (9090) ──→ Grafana (3000)
ffmpeg 프로세스 상태                              ─┘

세 가지 수집 레이어로 구성된다.

• node_exporter : 서버 CPU/메모리/디스크/네트워크 등 시스템 지표
• 커스텀 Python exporter : nginx-rtmp /stat XML을 파싱해 스트림 상태를 Prometheus 포맷으로 변환
• Prometheus : 위 두 exporter를 주기적으로 스크랩해 시계열 DB에 저장
• Grafana : Prometheus를 데이터소스로 연결해 대시보드 시각화

1단계 — Prometheus 설치

사용자 및 디렉토리 준비

sudo useradd --no-create-home --shell /bin/false prometheus

sudo mkdir -p /etc/prometheus /var/lib/prometheus
sudo chown prometheus:prometheus /etc/prometheus /var/lib/prometheus

바이너리 다운로드

cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v3.4.1/prometheus-3.4.1.linux-amd64.tar.gz
tar xvf prometheus-3.4.1.linux-amd64.tar.gz
cd prometheus-3.4.1.linux-amd64

sudo cp prometheus promtool /usr/local/bin/
sudo chown prometheus:prometheus /usr/local/bin/prometheus /usr/local/bin/promtool

console 패키지는 3 버전에서 더이상 제공되지 않습니다. 왜냐하면 관리, 유지보수가 어렵고 그냥 모든 사람들도 grafana 와 같은 third-party library 와 함께 사용하는 게 국룰이 되어버렸기 때문에 tar 로 압축을 풀어봐도 console 패키지가 없으니 스킵!

prometheus.yml 작성

sudo nano /etc/prometheus/prometheus.yml

global:
  scrape_interval:     15s
  evaluation_interval: 15s
  scrape_timeout:      15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']

  - job_name: 'nginx_rtmp'
    static_configs:
      - targets: ['localhost:9101']
    scrape_interval: 10s

sudo chown prometheus:prometheus /etc/prometheus/prometheus.yml

systemd 서비스 등록

sudo nano /etc/systemd/system/prometheus.service

[Unit]
Description=Prometheus Monitoring
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
    --config.file=/etc/prometheus/prometheus.yml \
    --storage.tsdb.path=/var/lib/prometheus/ \
    --storage.tsdb.retention.time=30d \
    --web.console.templates=/etc/prometheus/consoles \
    --web.console.libraries=/etc/prometheus/console_libraries \
    --web.listen-address=0.0.0.0:9090 \
    --web.enable-lifecycle

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now prometheus

--web.enable-lifecycle 플래그를 추가해두면 재시작 없이 설정 리로드가 가능하다.

# 설정 변경 후 무중단 리로드
curl -X POST http://localhost:9090/-/reload

2단계 — node_exporter 설치

cd /tmp
wget https://github.com/prometheus/node_exporter/releases/download/v1.9.0/node_exporter-1.9.0.linux-amd64.tar.gz
tar xvf node_exporter-1.9.0.linux-amd64.tar.gz

sudo useradd --no-create-home --shell /bin/false node_exporter
sudo install -m 755 node_exporter-1.9.0.linux-amd64/node_exporter /usr/local/bin/node_exporter
sudo chown node_exporter:node_exporter /usr/local/bin/node_exporter

Tip. 기존에 node_exporter가 실행 중인 상태에서 cp로 덮어쓰려 하면 Text file busy 오류가 발생한다. 이때는 install 명령을 쓰거나 서비스를 먼저 중단한 뒤 복사한다.

# 방법 1: install 명령 (서비스 중단 불필요)
sudo install -m 755 node_exporter /usr/local/bin/node_exporter

# 방법 2: 서비스 중단 후 복사
sudo systemctl stop node_exporter
sudo cp node_exporter /usr/local/bin/
sudo systemctl start node_exporter

sudo nano /etc/systemd/system/node_exporter.service

[Unit]
Description=Node Exporter
Wants=network-online.target
After=network-online.target

[Service]
User=node_exporter
Group=node_exporter
Type=simple
ExecStart=/usr/local/bin/node_exporter \
    --collector.systemd \
    --collector.processes

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now node_exporter

3단계 — nginx-rtmp 커스텀 Exporter

nginx-rtmp의 /stat XML 엔드포인트를 파싱해 Prometheus 포맷으로 9101번 포트에 노출하는 Python 스크립트다.

패키지 설치

# apt로 시스템 전역 설치 (pip install은 systemd 서비스에서 인식 못함)
sudo apt install -y python3-lxml python3-requests
sudo apt install -y python3-prometheus-client
# apt에 없다면:
# sudo pip3 install prometheus_client --break-system-packages

pip3 install을 일반 사용자 권한으로 실행하면 시스템 Python에 반영되지 않는다. systemd 서비스는 시스템 Python을 바라보므로 반드시 apt 또는 sudo pip3로 설치해야 한다.

설치 후 한 번에 검증:

python3 -c "import prometheus_client, requests, lxml; print('모두 OK')"

exporter 스크립트

sudo mkdir -p /opt/nginx_rtmp_exporter
sudo nano /opt/nginx_rtmp_exporter/exporter.py

#!/usr/bin/env python3
"""
nginx-rtmp → Prometheus Exporter
포트 9101에서 메트릭 노출
"""

import time
import requests
import logging
from lxml import etree
from prometheus_client import start_http_server, Gauge

logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')

RTMP_STAT_URL  = "http://localhost:8888/stat"
SCRAPE_INTERVAL = 10

# ── 메트릭 정의 ────────────────────────────────────────────────────────────
rtmp_up = Gauge('nginx_rtmp_up', 'nginx-rtmp 서버 접근 가능 여부 (1=정상, 0=장애)')

rtmp_stream_count = Gauge('nginx_rtmp_stream_count', '현재 활성 스트림 수', ['app'])
rtmp_clients      = Gauge('nginx_rtmp_clients',      '스트림별 클라이언트 수', ['app', 'stream'])
rtmp_bw_in        = Gauge('nginx_rtmp_bw_in_bps',    '입력 대역폭 (bps)',     ['app', 'stream'])
rtmp_bw_out       = Gauge('nginx_rtmp_bw_out_bps',   '출력 대역폭 (bps)',     ['app', 'stream'])
rtmp_bytes_in     = Gauge('nginx_rtmp_bytes_in_total','누적 수신 바이트',      ['app', 'stream'])
rtmp_ffmpeg_count = Gauge('nginx_rtmp_ffmpeg_processes', '실행 중인 ffmpeg 프로세스 수')
hls_segment_count = Gauge('nginx_rtmp_hls_segment_count', 'HLS .ts 세그먼트 파일 수', ['stream'])

# ── 수집 함수 ──────────────────────────────────────────────────────────────
def count_ffmpeg_processes() -> int:
    import subprocess
    try:
        r = subprocess.run(['pgrep', '-c', 'ffmpeg'], capture_output=True, text=True)
        return int(r.stdout.strip()) if r.returncode == 0 else 0
    except Exception:
        return 0

def count_hls_segments(hls_root: str = '/var/hls') -> dict:
    import os
    counts = {}
    try:
        for entry in os.scandir(hls_root):
            if entry.is_dir():
                counts[entry.name] = len([f for f in os.listdir(entry.path) if f.endswith('.ts')])
    except FileNotFoundError:
        pass
    return counts

def collect():
    try:
        resp = requests.get(RTMP_STAT_URL, timeout=5)
        resp.raise_for_status()
        rtmp_up.set(1)
    except Exception as e:
        logging.warning(f"stat 엔드포인트 접근 실패: {e}")
        rtmp_up.set(0)
        return

    try:
        root = etree.fromstring(resp.content)
        for server in root.findall('.//server'):
            for app in server.findall('application'):
                app_name = app.findtext('name', default='unknown')
                live = app.find('live')
                if live is None:
                    continue
                streams = live.findall('stream')
                rtmp_stream_count.labels(app=app_name).set(len(streams))
                for stream in streams:
                    name   = stream.findtext('name', default='unknown')
                    rtmp_clients.labels(app=app_name, stream=name).set(len(stream.findall('.//client')))
                    rtmp_bw_in.labels(app=app_name,   stream=name).set(int(stream.findtext('bw_in',    '0')))
                    rtmp_bw_out.labels(app=app_name,  stream=name).set(int(stream.findtext('bw_out',   '0')))
                    rtmp_bytes_in.labels(app=app_name,stream=name).set(int(stream.findtext('bytes_in', '0')))
    except Exception as e:
        logging.error(f"XML 파싱 오류: {e}")

    rtmp_ffmpeg_count.set(count_ffmpeg_processes())
    for sname, cnt in count_hls_segments().items():
        hls_segment_count.labels(stream=sname).set(cnt)

if __name__ == '__main__':
    start_http_server(9101)
    logging.info("nginx-rtmp exporter 가동 — :9101")
    while True:
        collect()
        time.sleep(SCRAPE_INTERVAL)

systemd 서비스 등록

sudo nano /etc/systemd/system/nginx_rtmp_exporter.service

[Unit]
Description=nginx-rtmp Prometheus Exporter
After=network.target

[Service]
User=prometheus
ExecStart=/usr/bin/python3 /opt/nginx_rtmp_exporter/exporter.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now nginx_rtmp_exporter

# 정상 동작 확인
curl http://localhost:9101/metrics | grep nginx_rtmp

4단계 — 수집 타겟 확인

설정 변경 후에는 반드시 리로드하고 타겟 상태를 점검한다.

curl -X POST http://localhost:9090/-/reload

sleep 30 && curl -s http://localhost:9090/api/v1/targets \
  | python3 -m json.tool \
  | grep -E '"job"|"health"|"lastError"'

세 job 모두 "health": "up" 이어야 정상이다.

"job": "nginx_rtmp"  →  "health": "up"
"job": "node"        →  "health": "up"
"job": "prometheus"  →  "health": "up"

주의. Prometheus를 재시작하지 않고 prometheus.yml만 수정하면 변경 사항이 반영되지 않는다. --web.enable-lifecycle 플래그가 있다면 위처럼 reload API를 활용하면 되고, 없다면 sudo systemctl restart prometheus로 재시작해야 한다.

5단계 — Grafana 설치

sudo apt install -y apt-transport-https software-properties-common
wget -q -O - https://apt.grafana.com/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/grafana.gpg
echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://apt.grafana.com stable main" \
  | sudo tee /etc/apt/sources.list.d/grafana.list

sudo apt update && sudo apt install grafana -y
sudo systemctl enable --now grafana-server

6단계 — nginx 리버스 프록시 + 리다이렉트 루프 해결

서브경로(/grafana/)로 Grafana를 서빙하려면 nginx 설정과 grafana.ini 두 곳을 모두 올바르게 맞춰야 한다. 한쪽이라도 어긋나면 301 무한 루프가 발생한다.

자주 하는 실수들

nginx — 기존 서버 블록에 location 추가

별도 conf 파일을 만들지 말고, 해당 도메인의 기존 블록에 아래 location을 추가한다.

http {

        ##
        # Basic Settings
        ##

        ...

        server {
                listen 8888;
                allow 127.0.0.1;
                deny all;

                location /stat {
                        rtmp_stat all;
                        rtmp_stat_stylesheet stat.xsl;
                }
        }

}

location /grafana/ {
    proxy_pass            http://localhost:3000;   # 끝 슬래시 없음!
    proxy_set_header      Host $host;
    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 https;  # $scheme 대신 하드코딩
    proxy_redirect        off;
}

proxy_pass http://localhost:3000/ (슬래시 있음)으로 설정하면 /grafana/login 요청이 http://localhost:3000/login으로 전달된다. Grafana는 /login을 받으면 /grafana/login으로 301을 내리고, nginx가 다시 /login으로 벗겨서 보내는 무한 루프가 생긴다. 슬래시를 빼면 /grafana/login 그대로 http://localhost:3000/grafana/login으로 전달된다.

grafana.ini

sudo nano /etc/grafana/grafana.ini

[server]
protocol            = http
domain              = your-domain.com          # 실제 도메인
root_url            = https://your-domain.com/grafana/
serve_from_sub_path = true

주석 기호(;)를 반드시 제거해야 적용된다.

적용

sudo nginx -t && sudo systemctl reload nginx
sudo systemctl restart grafana-server

브라우저에서 https://your-domain.com/grafana/ 접속 후 초기 계정 admin / admin으로 로그인.

7단계 — Prometheus 데이터소스 연결

Grafana UI에서 Connections → Data Sources → Add → Prometheus 선택 후:

8단계 — 대시보드 주요 PromQL

# 서버 생존 여부
nginx_rtmp_up

# 활성 스트림 수
nginx_rtmp_stream_count{app="live"}

# 전체 시청자 합계
sum(nginx_rtmp_clients)

# 입력 비트레이트 (Mbps)
sum(nginx_rtmp_bw_in_bps) / 1000000

# ffmpeg 프로세스 수
nginx_rtmp_ffmpeg_processes

# CPU 사용률 (%)
100 - (avg by(instance)(rate(node_cpu_seconds_total{mode="idle"}[1m])) * 100)

# 메모리 사용률 (%)
(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100

# 네트워크 수신 (Mbps)
rate(node_network_receive_bytes_total{device!="lo"}[1m]) * 8 / 1000000

포트 정리 및 보안 그룹 권장 설정

Prometheus와 각 exporter는 외부에 노출할 이유가 없다. NHN Cloud 등 클라우드 보안 그룹에서 9090/9100/9101은 차단하고, Grafana는 nginx 리버스 프록시를 통해서만 접근하도록 구성하는 것을 권장한다.

트러블슈팅 요약

exporter가 9101에서 응답하지 않음

sudo journalctl -u nginx_rtmp_exporter -n 30

ModuleNotFoundError: No module named 'lxml' → sudo apt install -y python3-lxml python3-requests python3-prometheus-client

Prometheus 타겟이 1개뿐

설정 파일 수정 후 reload를 빠뜨린 경우.

curl -X POST http://localhost:9090/-/reload

Grafana 접속 시 500 에러

nginx 에러 로그와 curl -sIL 리다이렉트 체인을 먼저 확인한다.

sudo tail -50 /var/log/nginx/error.log
curl -sIL --max-redirs 5 https://your-domain.com/grafana/

301 무한 루프

• proxy_pass 끝 슬래시 제거 (http://localhost:3000 ← 슬래시 없음)
• grafana.ini의 domain, root_url, serve_from_sub_path 주석 해제 및 올바른 값 입력
• proxy_set_header X-Forwarded-Proto https 하드코딩 (변수 대신)

1. telegram 가입

현재로선 구글링한 어떤 방법으로도 2천원을 내지 않고 telegram 에 신규 가입할 수 있는 방법은 없습니다. 우선 2천원을 내고 신규 가입을 합니다.

그리고 오른쪽 위에 검색을 눌러 BotFather 를 누릅니다. 이때, 굉장히 다양한 가짜 계정이 있으니 반드시 blue check 을 확인합니다.

2. bot 생성

굉장히 다양한 메뉴가 있는데 /newbot 클릭

이름을 정해합니다. 처음 정하는 이름은 상태창에 뜨는 이름이고 두번째 정하는 이름은 bot 자체의 이름입니다. 이때, 만약 본인이 자비스를 만들고 싶다면

1. Javis
2. Jav13_bot 등 으로 지으면 됩니다. (뒤에는 bot 으로 끝나야하고 id 처럼 이미 선점된 bot 이름은 설정 불가)

이때, 나온 HTTP API 키를 잘 보관 형식은 숫자:문자열 형식.

3. clawd bot 연결

clawdbot 에 연결할 때 따로 json 에서 설정을 잡아줘도 되지만 clawdbot dashboard 로 간편하게 해당 부분만 설정해도 됩니다. 이때, 저장해준 숫자:문자열 형식의 token 을 입력 후 상단의 본인 bot 을 클릭하면 대화창이 뜨게 됩니다.

그리고 여기서 user id 를 저장! (Pairing code 아님) 이 부분을 web UI 에서 Allow From 부분을 추가하고 사용하면 됩니다.

그리고 말을 걸어보면 잘 연결 된 것을 확인할 수 있읍니다.

4. service 등록

window 에서 service 등록 방법엔 여러가지가 있는데 가장 편리한 것은 WinSW 가 편리할 듯 합니다. 예전에 window 서버에 .jar 말아서 올리던 기억이 있어서 저에게 가장 편한 WinSW 로 서비스화 하였습니다. 이제 pc 를 재부팅 해도 자연스럽게 telegram 으로 연결이 됩니다.

5. moltbot VS Claud desktop

Moltbot이 더 적합한 경우

1. local 에서 완전한 자동화 권한(shell, file, browser, cron)을 주고 AI가 “백그라운드에서 알아서 하게” 하고 싶을 때.
2. claude 외에 GPT, 로컬 모델을 섞어서 쓰고 싶거나, 자체 스킬/플러그인을 만들어 붙이고 싶은 경우.

Claude Desktop이 더 적합한 경우

1. claude 계정 기반 워크플로우(project, code, cowork)를 데스크톱에서 안정적으로 쓰고 싶은 경우.
2. 미친 장점 OAuth 방식이라 구독료 이외의 지출 X

사설

moltbot 에 claude 를 붙이기는 너무 사치고 qwen 같은 가성비 모델을 붙여서 막 굴리는 게 좋지 않을까 물론 정보는 중국에 넘어갈지도..?

window 에서는 현재까지 moltbot 이 아닌, clawdbot 으로 써야합니다.

disconnected (1008): unauthorized: gateway token missing (open a tokenized dashboard URL or paste token in Control UI settings)

web ui 에서 다음과 같이 뜬다면 아래 명령어를 입력하면 됨.

https://www.answeroverflow.com/m/1465993262190956688

clawdbot dashboard

claudebot onboard

위 help 의 wizard settup 에서 볼 수 있듯, 혹시 telegram 2천원 때문에 @clawdbot/line 으로 시도하려다 설치가 안 돼서 설정이 꼬인 분들은 clawd onboard 로 reset all 을 선택하시면 설정을 처음부터 다시 잡을 수 있습니다.

참고로 npm 에 들어가보니 베트남에서 많이 쓰이는 Zola 가 존재하고 line 은 없더라구요. 심지어 line 은 일본, 베트남 등 동남아에서 많이 쓰는 메신져 앱이라고 소개됨.

RDB 중 가장 버그가 안 나고 편리한 DB tool 중 Heidsql 을 사용하고 있다. 문제는 5Mb 가 넘는 대용량 sql 파일을 import 할 때 주로 에러가 나온다. 이때, CMD로 훨씬 빠르게 실행하는 방법이 있다.

1. 로컬 pc 에 mysql 서버 설치하기

본인 pc 환경에 맞는 MSI 를 설치한다. (링크)

2. DB 서버 세팅

1. DB 서버에 user 접속 권한이 전체 권한인지 확인

   # DB 접속 둘 중 하나
   sudo mysql -u root -p
   mysql -u SmartSilverAdmin -p

# 호스트 확인
SELECT user, host FROM mysql.user;

% 설정이 안 되어있다면

ALTER USER 'SmartSilverAdmin'@'localhost' IDENTIFIED BY '비밀번호';
CREATE USER 'SmartSilverAdmin'@'%' IDENTIFIED BY '비밀번호';
GRANT ALL PRIVILEGES ON SmartSilverCenter.* TO 'SmartSilverAdmin'@'%';
FLUSH PRIVILEGES;

2. DB 서버에 DB 포트가 뚫려있는지 확인 기본값: 3306

   sudo ufw status | grep 3306
   sudo ufw allow 3306/tcp
   sudo ufw reload

3. DB 서버에 원격으로 접속 가능한지 .conf 값 설정

   sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
   bind-address = 0.0.0.0

4. DB 서버가 설치된 인스턴스에 인그레스 방화벽 확인

3. 로컬 pc 에서 mysql 서버 접속하기

1. 이제 로컬 서버에서 mysql 서버의 DB 포트에 붙을 수 있는지 확인

   Test-NetConnection -ComputerName [DB서버IP주소] -Port 3306

2. 앞서 설치한 mysql server 위치에서 MySQL 콘솔 접속

   C:\Program Files\MySQL\MySQL Server 8.4\bin>mysql -h [DB서버IP주소] -P 3306 -u SmartSilverAdmin -p
   # 아래 문구가 뜨면 성공
   Enter password:

아니면 시스템 환경변수로 등록해줘도 됨.

3. 덤프 파일 바로 복원

   # exit 으로 나간 후
   C:\Program Files\MySQL\MySQL Server 8.4\bin>mysql -h [DB서버IP주소] -P 3306 -u SmartSilverAdmin -p [DB 명] < "C:\경로\대용량.sql"

📌 RTSP (Real Time Streaming Protocol)

🛠️ 용도

"컨트롤" 프로토콜에 가까움. → 영상/오디오 데이터를 직접 실어나르기보다는 재생, 일시정지, 중지 같은 명령 제어에 집중.

📦 데이터 전달

보통 RTP(Real-time Transport Protocol)랑 짝꿍으로 사용. 실제 영상 데이터는 RTP로 전달하고, RTSP는 그걸 관리.

⚙️ 사용처

CCTV, IP 카메라, 실시간 모니터링 시스템. (네트워크 카메라 주소가 rtsp://...인 경우가 많음.)

👍 특징

낮은 지연 시간(수백 ms 수준). 다만 방화벽이나 NAT 환경에서 잘 막히기도 함.

📌 RTMP (Real Time Messaging Protocol)

🛠️ 용도

원래 Adobe Flash Player 용으로 만든 "데이터 전송" 프로토콜. → 영상/오디오 데이터를 서버로 업로드하거나 내려받을 때 직접 씀.

📦 데이터 전달

TCP 기반, 자체 포맷으로 전송. 지금은 HLS/DASH 같은 표준 스트리밍으로 변환할 때 업로드(ingest) 프로토콜로 자주 사용.

⚙️ 사용처

유튜브 라이브, 트위치, 페이스북 라이브 등 방송 플랫폼 송출.

👍 특징

지연 시간은 RTSP보다 약간 크지만(1~5초), 범용 지원이 좋고 안정적임. 방화벽 우회도 상대적으로 쉬움.

ffmpeg 으로 미디어 스트림 hls 변환

0. libnginx-mod-rtmp 라이브러리

📜 정의

Debian/Ubuntu에서 제공하는 Nginx용 RTMP 동적 모듈 패키지다. 업스트림 오픈소스인 nginx-rtmp-module(일반적으로 arut/nginx-rtmp-module)을 배포판 포맷으로 묶어둔 것이라 보면 됨.

⚙️ 역할

1. Nginx에 rtmp {} 블록과 application {}/live on; 같은 RTMP 서버 기능을 추가
2. OBS 같은 퍼블리셔가 RTMP로 업로드(publish) 하면 이를 받아 중계(play/relay)
3. on_publish, on_play 등 이벤트 콜백(HTTP)로 인증/로깅을 붙일 수 있음. (관련 훅 링크)
4. exec로 FFmpeg를 자동 스폰하여 트랜스코딩/HLS 세그먼팅 파이프라인을 바로 붙일 수 있음.
5. (선택) 모듈 자체의 HLS/DASH 세그먼팅 기능도 있으나, 세밀한 제어·ABR 구성은 보통 FFmpeg가 더 유연함.

⚠️ 주의/제한

1. Nginx 공식 번들 모듈이 아닌 서드파티 모듈임. (배포판에서 편하게 쓰도록 패키징한 것)
2. RTMPS(SSL)를 네이티브로 직접 처리하지 않ㅓ는다. 필요하면 stunnel/Nginx stream 프록시 등으로 감싸 쓰는 패턴을 사용.
3. 무거운 실시간 트랜스코딩은 FFmpeg(또는 SRS 내장/외부 트랜스코드)로 처리하는 것이 일반적임.

1. RTMP Ingest 방식

패키지 설치

sudo apt update
sudo apt install -y nginx libnginx-mod-rtmp ffmpeg
sudo mkdir -p /var/www/hls
sudo chown -R www-data:www-data /var/www/hls

nginx.conf 작성

동적 모듈 로딩 + RTMP 인젯 + FFmpeg 자동 변환 + HLS 서빙

# 동적 RTMP 모듈 로드 (Ubuntu/Debian 표준 경로)
load_module modules/ngx_rtmp_module.so;

worker_processes auto;

events { worker_connections 1024; }

# ---------- RTMP(Ingest) 이 부분은 아예 새로 추가 ----------
rtmp {
    server {
        listen 1935;          # RTMP default 포트
        chunk_size 4096;

        application live {
            live on;          # publish/play 허용
            record off;

            # (선택) 퍼블리시 인증 HTTP 콜백 예시
            # on_publish http://127.0.0.1:8080/auth?name=$name&key=$arg_key;

            # 스트림이 들어오면 스트림 이름($name)별로 FFmpeg를 띄워 HLS를 생성
            # : ABR(1080/720/480) 3종, 2초 짜리 세그먼트, 오래된 세그먼트 삭제
            exec_kill_signal term;
            exec /usr/bin/ffmpeg -loglevel error -hide_banner \
                -reconnect 1 -reconnect_streamed 1 -reconnect_on_network_error 1 \
                -i rtmp://127.0.0.1/live/$name \
                -c:v libx264 -preset veryfast -profile:v high -level 4.1 -pix_fmt yuv420p \
                -sc_threshold 0 -g 60 -keyint_min 60 \
                -c:a aac -ar 48000 -ac 2 -b:a 128k \
                -filter:v:0 "scale=w=-2:h=1080" -b:v:0 6000k -maxrate:0 6420k -bufsize:0 12000k \
                -filter:v:1 "scale=w=-2:h=720"  -b:v:1 3500k -maxrate:1 3740k -bufsize:1 7000k  \
                -filter:v:2 "scale=w=-2:h=480"  -b:v:2 1200k -maxrate:2 1320k -bufsize:2 2400k  \
                -map 0:v:0 -map 0:a:0 -map 0:v:0 -map 0:a:0 -map 0:v:0 -map 0:a:0 \
                -hls_time 2 -hls_list_size 6 \
                -hls_flags delete_segments+program_date_time+independent_segments \
                -master_pl_name "$name/master.m3u8" \
                -var_stream_map "v:0,a:0 name:1080p v:1,a:1 name:720p v:2,a:2 name:480p" \
                -hls_segment_type mpegts \
                -hls_segment_filename "/var/www/hls/$name/v%v/seg_%06d.ts" \
                "/var/www/hls/$name/v%v/index.m3u8";
        }
    }
}

# ---------- HLS 서빙(HTTP) 일부 옵션 추가 ----------
http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    server {
        listen 80;
        server_name _;

        # HLS 정적 파일 제공
        location /hls/ {
            types {
                application/vnd.apple.mpegurl m3u8;
                video/mp2t ts;
            }
            alias /var/www/hls/;
            add_header Cache-Control no-cache;
            add_header Access-Control-Allow-Origin *;
            add_header Access-Control-Allow-Headers *;
        }
    }
}

적용:

sudo nginx -t && sudo systemctl reload nginx

OBS 설정

• 서버: rtmp://<서버IP 또는 도메인>/live
• 스트림 키: 예) mystream (인증을 붙였다면 mystream?key=YOURSECRET 식으로)

푸시가 성공하면 HLS는 다음 경로에 생긴다.

• 마스터 플레이리스트: http://<서버>/hls/mystream/master.m3u8
• 개별 레벨: /hls/mystream/v0/index.m3u8(1080p), v1(720p), v2(480p)

2. RTMP Ingress

exec를 쓰지 않고, 고정 스트림을 별도 서비스로 돌리는 방법 이게 훨씬 보기가 좋음. 대충 -p 옵션으로 /usr/local/bin/rtmp2hls.sh 작성

#!/usr/bin/env bash
set -Eeuo pipefail

IN="rtmp://127.0.0.1/live/mystream"   # OBS가 푸시하는 RTMP
OUTDIR="/var/www/hls/mystream"

mkdir -p "$OUTDIR"
exec /usr/bin/ffmpeg -loglevel error -hide_banner \
  -reconnect 1 -reconnect_streamed 1 -reconnect_on_network_error 1 \
  -i "$IN" \
  -c:v libx264 -preset veryfast -profile:v high -level 4.1 -pix_fmt yuv420p \
  -sc_threshold 0 -g 60 -keyint_min 60 \
  -c:a aac -ar 48000 -ac 2 -b:a 128k \
  -hls_time 2 -hls_list_size 6 \
  -hls_flags delete_segments+program_date_time+independent_segments \
  -f hls -hls_segment_filename "$OUTDIR/seg_%06d.ts" \
  "$OUTDIR/index.m3u8"

권한 추가

sudo chmod +x /usr/local/bin/rtmp2hls.sh

서비스 파일(.ini) 작성

# /etc/systemd/system/rtmp2hls.service
[Unit]
Description=RTMP -> HLS (FFmpeg)
After=network.target nginx.service

[Service]
User=www-data
Group=www-data
ExecStart=/usr/local/bin/rtmp2hls.sh
Restart=always
RestartSec=2
WorkingDirectory=/var/www/hls

[Install]
WantedBy=multi-user.target

데몬 로드 후 서비스 자동 등록 및 실행

sudo systemctl daemon-reload
sudo systemctl enable --now rtmp2hls

3. 체크리스트

권한: /var/www/hls에 www-data(또는 Nginx/FFmpeg가 도는 사용자) 쓰기 권한이 있어야 함.

경로: load_module modules/ngx_rtmp_module.so;가 실패하면 modules 경로(대개 /usr/lib/nginx/modules/)를 확인.

CORS: 웹 플레이어에서 크로스도메인 요청이면 /hls/에 CORS 헤더 추가(위 예시 포함).

키프레임 간격: 세그먼트 길이(예: 2초)의 정수배로 -g(GOP) 맞추는 것이 안정적.

성능: -preset veryfast부터 시작해서 여유되면 faster/fast로 올리기.

브라우저 RTMP: 불가. 웹은 HLS(또는 LL-HLS/WEBRTC)를 사용.

1. systemd 서비스 설정

yt-dlp 설치 및 경로 설정

yt-dlp 를 반드시 설치해야하는데, pipx로 설치하면 yt-dlp는 보통 ~/.local/bin/yt-dlp 또는 pipx venv 경로에 다 따라서 서비스에 PATH를 명시하고 스크립트에 절대경로를 없애거나 또는 정확한 절대경로로 수정 (/home/ubuntu/.local/bin/yt-dlp) 하면 된다.

서비스 파일(.ini) 작성 예시

[Unit]
Description=HLS live stream author.KJW
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/live-stream
Environment="PATH=/home/ubuntu/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/bin/bash -lc /opt/live-stream/live-stream.sh
Restart=always
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=false
ProtectSystem=full
ReadWritePaths=/var/www/videos/hls/live/720p /opt/live-stream
StandardOutput=journal
StandardError=inherit

[Install]
WantedBy=multi-user.target

권한/마운트 이슈를 우회하고 진단도 쉬운 형태로 설정.

ExecStart=/usr/bin/bash -lc /opt/live-stream/live-stream.sh

참고로 -l(login)은 /etc/profile 등을 읽어서 PATH가 더 풍부해지지만, 사용자 셸 설정(~/.bashrc)은 기본으론 안 읽힐 수 있다. 그래서 서비스 파일에서 Environment=PATH=...를 명시하는 것이다.

스크립트 파일 작성 예시

#!/usr/bin/env bash
set -Eeuo pipefail

VIDEO_URL="${VIDEO_URL:-https://www.youtube.com/watch?v=채널_id}"
COOKIES="${COOKIES:-/opt/live-stream/cookies.txt}"
OUTPUT_DIR="${OUTPUT_DIR:-/var/www/videos/hls/live/720p}"

YTDLP_BIN="${YTDLP_BIN:-$(command -v yt-dlp)}"
FFMPEG_BIN="${FFMPEG_BIN:-$(command -v ffmpeg)}"

if [[ -z "${YTDLP_BIN}" ]]; then
  echo "yt-dlp not found in PATH" >&2; exit 127
fi
if [[ -z "${FFMPEG_BIN}" ]]; then
  echo "ffmpeg not found in PATH" >&2; exit 127
fi

mkdir -p "$OUTPUT_DIR"

RESTART_DELAY=15
UA="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115 Safari/537.36"
REF="https://www.youtube.com/"

if [[ -s "$COOKIES" ]]; then
  COOKIES_ARG=(--cookies "$COOKIES")
  FFMPEG_COOKIE_ARG=()  # 필요 시 -headers "Cookie: ..." 방식으로 교체
else
  COOKIES_ARG=()
  FFMPEG_COOKIE_ARG=()
fi

while true; do
  echo "[$(date)] Fetching fresh HLS URL from YouTube..."
  if ! HLS_URL="$("$YTDLP_BIN" -g "${COOKIES_ARG[@]}" --no-warnings -f "bv*[height<=720]+ba/b" "$VIDEO_URL")"; then
    echo "[$(date)] yt-dlp failed. Retrying in $RESTART_DELAY sec..."
    sleep "$RESTART_DELAY"; continue
  fi

  if [[ -z "$HLS_URL" ]]; then
    echo "[$(date)] Empty HLS URL. Retrying in $RESTART_DELAY sec..."
    sleep "$RESTART_DELAY"; continue
  fi

  echo "[$(date)] Got HLS URL: $HLS_URL"
  echo "[$(date)] Starting ffmpeg HLS restream..."

  set +e
  "$FFMPEG_BIN" -hide_banner -loglevel warning \
    -user_agent "$UA" -referer "$REF" "${FFMPEG_COOKIE_ARG[@]}" \
    -re -reconnect 1 -reconnect_streamed 1 -reconnect_delay_max 15 \
    -rw_timeout 20000000 -timeout 20000000 -seekable 0 \
    -fflags +genpts+discardcorrupt -probesize 15M -analyzeduration 20M \
    -i "$HLS_URL" -c copy -bufsize 20M -max_delay 5000000 \
    -f hls -hls_time 10 -hls_list_size 20 \
    -hls_flags delete_segments+append_list+omit_endlist \
    "$OUTPUT_DIR/index.m3u8"
  CODE=$?
  set -e

  echo "[$(date)] ffmpeg exited with code $CODE. Waiting $RESTART_DELAY sec before restart..."
  sleep "$RESTART_DELAY"
done

쓰기 경로 권한부여

출력 경로(/var/www/videos/hls/live/720p)는 User=ubuntu가 쓰기 가능해야 한다.

sudo mkdir -p /var/www/videos/hls/live/720p
sudo chown -R ubuntu:www-data /var/www/videos
sudo chmod -R 775 /var/www/videos

혹은 서비스에 아래 줄을 넣어주면 되는데,

ReadWritePaths=/var/www/videos/hls/live/720p /opt/live-stream

이 코드는 systemd sandbox 가 쓰기를 허용하는 줄이다. 참고로 디렉터리 자체 권한, 소유권까지 제대로 맞춰줘야 한다.

쿠키/헤더 옵션

작동 후 품질 개선을 위해 쿠키 및 헤더 옵션을 넣어준다. ffmpeg의 -cookies 옵션은 name=value; name2=value2 형태가 일반적인데, -cookies "file=/path" 는 ffmpeg 표준 옵션은 아니니(빌드마다 다를 수 있음) 헤더로 넘기는 방법을 고려하였다.

쿠키 파일을 헤더로 붙이는 예 (Netscape cookies.txt라면 변환 필요)

FFMPEG_COOKIE_ARG=(-headers "Cookie: $(awk 'BEGIN{ORS="; "}$0 !~ /^#/ {print $6"="$7}' "$COOKIES")")

일단 지금처럼 yt-dlp -g로 m3u8을 받아서 -user_agent와 -referer만 맞춰도 동작하는 경우가 많으니, 우선 권한/경로부터 해결하고 필요 시 다듬자.

트러블 슈팅 방법

1. 스크립트와 경로 권한 확인

# 각 경로 구성요소의 권한을 한 눈에 보기
namei -l /opt/live-stream/live-stream.sh

# 퍼미션/소유자 확인
ls -l /opt/live-stream/live-stream.sh
ls -ld /opt/live-stream

조건: live-stream.sh에 실행 비트가 있어야 함 => -rwxr-xr-x(0755) 추천 /opt 와 /opt/live-stream 디렉터리에 실행 권한이 있어야 User=사용자명 가 경로를 탐색(traverse) 가능 (보통 755)

수정

sudo chown 사용자명:사용자명 /opt/live-stream/live-stream.sh /opt/live-stream
sudo chmod 0755 /opt/live-stream /opt/live-stream/live-stream.sh

참고: 디렉터리의 x 권한은 “들어갈 수 있음”이다. 따라서 아무리 파일을 755로 바꿔도, 디렉터리가 700이면 여전히 Permission denied가 뜰 수 있다.

2) CRLF(윈도우 개행) 및 shebang 확인

윈도우에서 만든 스크립트면 커널이 인터프리터를 못 찾아서 문제를 낼 수 있다.

head -n1 /opt/live-stream/live-stream.sh
file /opt/live-stream/live-stream.sh

첫번째 명령어는 쉬뱅인 #!/usr/bin/env bash 가, 두번째 명령어는 with CRLF line terminators 가 보이면 안 된다.

캐리지 리턴, 라인 피드 정리를 위해선 아래 명령어를 입력하면 된다.

sudo sed -i 's/\r$//' /opt/live-stream/live-stream.sh

3) noexec 마운트 여부 확인

참고로 그럴일은 없겠지만 opt가 noexec로 마운트 되어있으면 실행 자체가 막힌다. 따라서 아래 명령어를 실행한 뒤,

findmnt -no TARGET,OPTIONS /opt
# 또는
mount | grep ' /opt '

noexec 가 보이면 가급적 스크립트를 noexec 아닌 경로(예: /usr/local/bin)로 옮기거나, 서비스에서 인터프리터로 실행하면 된다. ExecStart=/usr/bin/bash /opt/live-stream/live-stream.sh 참고로 이 방식은 스크립트에 x 비트가 없어도 동작한다. 대신 보안상 최선은 아님.

정리.

# 1) 권한/소유/개행 정리
sudo chown ubuntu:ubuntu /opt/live-stream /opt/live-stream/live-stream.sh
sudo chmod 0755 /opt/live-stream /opt/live-stream/live-stream.sh
sudo sed -i 's/\r$//' /opt/live-stream/live-stream.sh

# 2) 출력 디렉터리 준비
sudo mkdir -p /var/www/videos/hls/live/720p
sudo chown -R ubuntu:www-data /var/www/videos
sudo chmod -R 775 /var/www/videos

혹은 서비스 파일에 명시

# 3) /opt noexec 여부 점검(필요 시만 보통은 필요 없을꺼임.)
findmnt -no TARGET,OPTIONS /opt

# 4) 서비스 파일 수정(예: /etc/systemd/system/live-stream.service)
#   - ExecStart=/usr/bin/bash -lc /opt/live-stream/live-stream.sh
#   - Environment="PATH=/home/ubuntu/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"

# 5) systemd 반영 및 재기동
sudo systemctl daemon-reload
sudo systemctl restart live-stream
sudo journalctl -u live-stream -e --no-pager

비록 정책 문제와 맞물려 채택되지 못한 아이디어이지만 굉장히 참신한 아디어라 소개해본다.

1. 아이디어

0. 특정 주소 접속해서 라이브 변환기 가 켜져있는지 확인.
1. 대상 채널 코드을 youtube api에 주고, 켜져 있는 라이브 방송이 있는지 알아본다. (100 가스 소요.)

--> response 라이브 방송 클립코드 2. 라이브 방송 클립코드가 live인지 체크한다. (1 가스 소요.) 3. 라이브 방송 채널 코드를 주고, yt-dlp로 돌린걸 ffmpeg으로 넘겨준다. 3.1 yt-dlp로 hls 주소를 확인한다. 3.2 방송을 ffmpeg으로 포장 -> response ffmpeg으로 넘겨준 master.m3u8 경로 4. nginx가 master.m3u8을 서빙 5. 2번, 3번을 서비스로 등록

2. Youtube API

1) youtube API 설정

1. gcp 콘솔에서 프로젝트를 하나 만들고 API 및 서비스에 접근한다.

2. 사용자 인증 정보 탭에 들어가서 API 키를 생성한다.

이때, API키 수정을 누른 다음

YouTube Data API v3 만 선택하여 사용하도록 하자.

2) youtube API 사용

Search: list 를 사용해야한다. (관련 문서)

요청 req url 예시

https://www.googleapis.com/youtube/v3/search?part=snippet&q=@CHANNEL_HANDLE&eventType=live&type=video&key=YOUR_KEY

4. 구현

1) HLS 패스스루

“라이트 리스팀” — YouTube Live → (내 서버) HLS 패스스루 유튜브의 라이브 HLS(m3u8)를 받아서, 내 도메인에서 HLS로 재공급하는 방식이다.

이 방식의 문제는 cookie, 정책 등의 문제로 아쉽게도 탈락 되었다. 일일이 수동으로 해야할 경우가 많고 문제를 일으킬 요소도 굉장히 많았기 때문이다.

장점은 Youtube Live Url 을 인코딩 없이 -c copy로 리패키징(패스스루) 하면 CPU 부담 거의 없고 Youtube Live Url은 만료 토큰이 있으므로 주기적으로 새 URL을 갱신하는 작은 스크립트만 추가하면 되기 때문에 굉장히 간단하다.

하지만 담점으로 약관/저작권 이슈를 스스로 관리해야 하고(특히 외부 공개 재배포 시), URL 만료 시 자동 재연결 로직이 필요하다.

2) 최소 구현 예시

0. 필수 lib 설치

pipx install yt-dlp
source ~/.bashrc
which yt-dlp

여기서 yt-dlp 가 잘 나오는 것을 확인.

1. 유튜브 라이브 스트리밍 HLS(m3u8) URL 얻기

유튜브에서 방송 중인 채널의 HLS 주소를 직접 얻기 위해 youtube download player 를 사용

yt-dlp --cookies 쿠키경로 -g "https://www.youtube.com/watch?v=스트리밍ID"

# ex)
yt-dlp --cookies /opt/yt-restream/cookies.txt -g "https://www.youtube.com/watch?v=스트리밍ID"

2. ffmpeg로 재인코딩 & HLS 세그먼트 생성

유튜브의 HLS 스트림을 ffmpeg가 받아서, 우리 서버에서 쓸 수 있는 HLS로 변환하는 작업이다.

ffmpeg \
    -i "$(yt-dlp -g https://www.youtube.com/watch?v=스트리밍ID)" \
    -c copy \
    -f hls \
    -hls_time 4 \
    -hls_list_size 5 \
    -hls_flags delete_segments \
    /var/www/html/stream/index.m3u8


# ex)
ffmpeg -i "$(yt-dlp --cookies /opt/yt-restream/cookies.txt -g https://www.youtube.com/watch?v=스트리밍ID)" \
    -c copy -f hls -hls_time 4 -hls_list_size 5 -hls_flags delete_segments \
    /var/www/html/stream/index.m3u8

설명: -c copy → 재인코딩 없이 원본 그대로 복사 (CPU 부담 ↓) -hls_time 4 → 세그먼트 길이 4초 -hls_list_size 5 → m3u8에 최신 5개 세그먼트만 유지 -hls_flags delete_segments → 오래된 ts 파일 삭제 /var/www/html/stream/index.m3u8 → Nginx 같은 웹서버에서 접근 가능한 경로

• 참고로 이때, 지정한 path 에 폴더가 있어야한다.

3. (옵션) 권한 설정하기

sudo mkdir -p /opt/yt-restream
sudo nano /opt/yt-restream/restream.sh
sudo chmod +x /opt/yt-restream/restream.sh

4. nginx 설정 해주고

이때, CORS 필요한 경우 nginx에 add_header Access-Control-Allow-Origin *; 등 옵션 추가

5. 이제 위 수동 테스트를 바탕으로 자동화 sh 파일 작성

#!/usr/bin/env bash
set -Eeuo pipefail

VIDEO_URL="https://www.youtube.com/watch?v=NJUjU9ALj4A"
COOKIES="/opt/yt-restream/cookies.txt"
OUTPUT_DIR="/var/www/html/stream"

mkdir -p "$OUTPUT_DIR"

while true; do
    echo "[$(date)] Fetching new m3u8 URL..."
    M3U8_URL=$(/home/ubuntu/.local/bin/yt-dlp --cookies "$COOKIES" -g "$VIDEO_URL")

    echo "[$(date)] Starting ffmpeg restream..."
    ffmpeg \
        -loglevel error \
        -i "$M3U8_URL" \
        -c copy \
        -f hls \
        -hls_time 4 \
        -hls_list_size 5 \
        -hls_flags delete_segments \
        "$OUTPUT_DIR/index.m3u8"

    echo "[$(date)] ffmpeg stopped. Restarting in 5 seconds..."
    sleep 5
done

이때, ffmpeg 옵션으로 -hls_time 2, -hls_list_size 6 이면 보통 6~12초. 더 낮추면 끊김 위험이 높다.

6. 서비스 등록

systemd 서비스 파일 작성

[Unit]
Description=YouTube to HLS Restream Service
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/opt/yt-restream/restream.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

7. 실행 및 로그

sudo systemctl daemon-reload
sudo systemctl enable 서비스이름
sudo systemctl start 서비스이름

로그 확인

journalctl -u 서비스이름 -f

결론. 이 아이디어가 채택이 안 된 이유.

트랜스코딩 없이 패스스루(-c copy)라 CPU는 가볍지만, 원본 코덱(보통 H.264/MP4 또는 VP9/WEBM)에 따라 일부 레거시 플레이어 호환성에 차이가 날 수 있다. 이때, 문제가 생기면 -c:v h264 -c:a aac 로 트랜스코딩을 고려하면 되는데 대신 CPU/GPU 코스트가 상승한다. 참고로 CDN을 앞단에 두면 대규모 시청자도 안정적으로 처리가 가능하다.

무튼 이 아이디어가 채택이 안 된 이유는 요청 빈도(yt-dlp & ffmpeg) 때문이다. 동작 과정이

1. yt-dlp yt-dlp -g 명령을 실행하는 순간, 유튜브 페이지를 12번 요청해서 실제 m3u8 주소를 뽑습는다. 평상시에 1초마다 계속 호출하는 건 아니고, 명령 실행할 때만 요청한다. m3u8 URL은 보통 몇 분몇 시간 유효하지만, 유튜브 라이브는 1시간 이내 만료되는 경우가 많다. → 그래서 주기적으로 새로 받아와야 함 (예: 30분~1시간마다)
2. ffmpeg 그리고 사실 여기가 문제인데 ffmpeg는 yt-dlp가 뽑아준 m3u8 URL을 읽어오는데, 이건 내부적으로 유튜브의 세그먼트(ts) 파일을 받아오는 HTTP 요청을 세그먼트 길이(내 경우 12초)마다 보낸다. 그럼 youtube 측에서는 요청을 너무 많이 보내서 429 too many req 에러를 보낸다.

마치 web-app 처럼 electron 을 사용해서 mini-pc 에 application 을 만들어볼 예정이다.

1. electron

electron 의 구성은 일단 index.html => splash 화면 package.json => 명세서 역할 main.js => landing-page 역할

여기에 추가적으로 본인이 원하는 파일을 목적에 만들면 된다.

preload.js => 해당 app 이 뜨기 전에 값을 가져오는 역할 updater.js => s3, object box 와 같이 자동으로 update 될 수 있도록 람다를 역할을 하는 곳.

그럼 이제 하나하나 천천히 살펴보자.

1. index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple Electron App</title>
    <style>
        body, html {
            margin: 0;
            padding: 0;
            height: 100%;
            overflow: hidden;
            display: flex;
            align-items: center;
            justify-content: center;
        }

        .background-image {
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            background-image: url('splash.jpg'); /* Replace with your image URL */
            background-size: cover;
            background-position: center;
            z-index: -1;
        }

        .text-container {
            position: absolute;
            top: 80%;
            color: white;
            font-family: Arial, sans-serif;
            font-size: 2rem;
            text-align: center;
            background: rgba(0, 0, 0, 0.5); /* Optional: Adds a translucent background */
            padding: 20px;
            border-radius: 10px;
        }
    </style>
</head>
<body>
<script type="text/javascript">
  var Request = function () {
    this.getParameter = function (name) {
      var rtnval = '';
      var nowAddress = unescape(location.href);
      var parameters = (nowAddress.slice(nowAddress.indexOf('?') + 1,
        nowAddress.length)).split('&');
      for (var i = 0; i < parameters.length; i++) {
        var varName = parameters[i].split('=')[0];
        if (varName.toUpperCase() == name.toUpperCase()) {
          rtnval = parameters[i].split('=')[1];
          break;
        }
      }
      return rtnval;
    }
  }
  var request = new Request();
</script>

<div class="background-image"></div>
<div class="text-container" id="did">device ID</div>

<script type="text/javascript">
  var deviceParam = request.getParameter('deviceID');
  var versionParam = request.getParameter('ver');
  document.getElementById('did').innerHTML = deviceParam + '<br>Ver.' + versionParam;
</script>

<script>
  var timer = setTimeout(function () {
    var webclient_url = 'http://localhost:3000';
    window.location.href = `${webclient_url}?deviceID=${deviceParam}`;
  }, 3000);
</script>

<script>
  document.addEventListener('keydown', (event) => {
    if (event.key === 'Enter') {
      console.log('✔ OK 버튼이 브라우저에서 감지됨!');
    }
  });
</script>

</body>
</html>

뭐 이런식으로 간단하게 작성해도 된다.

하지만 나는 electron work flow 가 package.json => main.js 로 실행되어 createWindow 에서 바로 react 서버를 요청했고 이를 가져와 표출하기로 했다. 참고로 react 에서 type 만 잘 잡아두고, electron 에서 ipc 를 사용하여 터널만 잘 뚫어 놓으면 OS 단의 정보를 react 에서도 받아볼 수 있다.

2. package.json

{
  "author": "kjw",
  "name": "레포 이름",
  "version": "1.0.0",
  "description": "레포 설명",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "dev": "electron . --enable-logging",
    "build": "electron-builder",
    "dist": "electron-builder --publish=never",
    "build:linux64": "electron-builder --linux --x64",
    "build:win64": "electron-builder --win --x64",
    "postinstall": "electron-builder install-app-deps"
    "build-publish": "electron-builder --publish=always",
    "deploy": "node deploy-to-gcs.js"
  },
  "author": "kjw",
  "license": "ISC",
  "devDependencies": {
    "electron-builder": "^26.0.12",
    "electron-log": "^5.4.2",
    "electron-updater": "^6.6.2"
  }
  "build": {
    "appId": "앱 아이디",
    "productName": "앱 이름",
    "asar": true,
    "asarUnpack": [
      "node_modules/node-hid/**"
    ],
    "protocols": {
      "name": "SmartSilverClient",
      "schemes": [
        "SmartSilverClient"
      ]
    },
    "files": [
      "**/*"
    ],
    "win": {
      "target": [
        "zip",
        "nsis"
      ],
      "icon": "./resources/installer/Icon.ico"
    },
    "linux": {
      "target": [
        "AppImage",
        "zip",
        "tar.gz"
      ],
      "icon": "./resources/linuxicon"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    },
    "directories": {
      "buildResources": "./resources/installer/",
      "output": "./dist/",
      "app": "."
    }
  },
  "type": "commonjs",
  "dependencies": {
    "@electron/rebuild": "^4.0.1",
    "electron": "^37.2.5",
    "node-hid": "^3.2.0"
  },

}

electron 에서 package.json 의 build 옵션은 굉장히 중요한 역할을 한다. AppImage 를 생성하는 옵션들을 여기서 설정하기 때문이다.

기본 설정

productName: 최종 사용자에게 표시될 애플리케이션 이름이다. 여기서 설정한 이름 + 버전.AppImage 로 빌드됨. appId: 애플리케이션의 고유 식별자로, 주로 도메인 역순 형식을 사용한다. asar: 애플리케이션 소스 코드를 asar 아카이브로 패키징한다. 성능 향상 + 코드 보호

build - 파일 설정

files: 최종 빌드에 포함될 파일들을 지정.

"files": [
  "index.html",
  "main.js",
  "splash.jpg",
  "node_modules/node-hid/**/*"
  // 아니면 그냥 프로젝트 내 모든 파일 설정
  "**/*"
]

build - asarUnpack

asar 아카이브로 패키징하지 않을 파일들을 지정하는 필드

"asarUnpack": [
  "node_modules/node-hid/**"
],

참고로 node-hid 모듈은 네이티브 모듈이므로 asar에서 풀어야 정상 작동한다.

build - protocols

프로토콜 설정 protocols: 커스텀 URL 스킴을 정의합니다.

"protocols": {
  "name": "앱 이름",
    "schemes": [
      "앱 이름"
    ]
},

이를 통해 앱 이름:// 형식의 URL로 애플리케이션을 실행할 수 있다.

build - Windows

electron-builder 설정의 일부

"win": {
  "target": [
    "zip",
    "nsis"
  ],
    "icon": "./resources/installer/Icon.ico"
},

zip: 압축 파일 형태로 배포 nsis: Windows 설치 프로그램으로 배포 win.icon: Windows 애플리케이션 아이콘

window 필드

1. NSIS 는 사용자가 window 에서 설치할 때 필요한 건가?

NSIS (Nullsoft Scriptable Install System)는 Windows 운영체제에서 소프트웨어 설치 파일을 만들 때 사용하는 도구이다. NSIS는 다양한 역할을 하는데, 1. Windows 설치 파일(exe) 생성 2. .nsi 확장자를 작성하여 설치 과정을 세밀하게 제어 가능 3. 다양한 기능제공 예를 들어 설치 경로 설정, 구성 요소 선택, 언인스톨러 생성, 프로그램 실행 여부 설정 등 그리고 무엇보다 무료 및 오픈 소스이다. 2. asar 아카이브란? asar(Atom Shell Archive Format) 아카이브는 Electron 애플리케이션을 위해 특별히 설계된 간단한 확장 아카이브 포맷이다. tar와 비슷한 방식으로 작동한다. 무슨 말이냐면 애플리케이션의 모든 소스 코드와 리소스 파일들을 압축 없이 하나의 파일로 묶어주는 역할을 한다. 파일 통합: 여러 파일을 하나로 묶어 관리가 용이 성능 최적화: asar 아카이브를 압축 해제 없이 임의로 접근하여 필요한 파일만 읽어들일 수 있음 경로 문제 해결: Windows에서 발생할 수 있는 긴 경로 이름 관련 문제를 완화 소스 코드 보호: 애플리케이션 배포 시 소스 코드를 직접 노출하지 않고 패키징할 수 있음 이러한 장점이 있어, win build 시 asar 아카이브로 패키징하도록 설정을 한다.

build - Linux

electron-builder 설정의 일부

"linux": {
  "target": [
    "AppImage",
    "zip",
    "tar.gz"
  ],
  "icon": "./resources/linuxicon",
  "category": "Utility"
},

AppImage: 설치 없이 실행 가능한 독립형 애플리케이션 파일 zip 및 tar.gz: 압축 파일 형태 linux.icon: 애플리케이션 아이콘

"build:linux64": "electron-builder --linux --x64", target 속성을 통해 Linux에서 어떤 배포 형식(어떤 형태의 패키지)으로 배포할지 지정한다. AppImage: 설치 없이 실행 가능한 독립형 애플리케이션 파일 deb: Debian 기반 리눅스(Ubuntu 등)에서 사용하는 패키지 형식 아키텍처 지정: arch 속성은 지원할 CPU 아키텍처를 지정한다. x64: 64비트 인텔/AMD 프로세서 arm64: 64비트 ARM 프로세서(라즈베리파이 등) 이렇게 설정하면 두 가지 배포 형식(AppImage, deb)과 두 가지 아키텍처(x64, arm64)에 대해 총 4개의 다른 빌드 파일이 생성된다.

• category 필드는 Linux 데스크톱 환경에서 애플리케이션의 분류를 지정한다. 메뉴 분류: Linux 데스크톱 환경(GNOME, KDE 등)의 애플리케이션 메뉴에서 어느 카테고리에 표시될지 결정합니다. "Utility"로 설정되어 있으므로 유틸리티 도구 섹션에 표시된다. 데스크톱 파일 정보: Linux에서는 .desktop 파일에 이 카테고리 정보가 포함되어, 시스템이 애플리케이션을 적절히 분류하고 표시할 수 있게 한다. 참고로 다른 카테고리로는 "Development", "Graphics", "Network", "Office", "System" 등이 있다.

build - NSIS 설치 프로그램 설정

nsis.oneClick: false - 원클릭 설치 대신 사용자 정의 설치 옵션을 제공하는 옵션 nsis.allowToChangeInstallationDirectory: true - 사용자가 설치 디렉토리를 변경할 수 있도록 도와주는 옵션

build - directory

"directories": {
  "buildResources": "./resources/installer/",
    "output": "./dist/",
      "app": "."
}

buildResources: 빌드에 필요한 리소스 파일 위치 output: 빌드된 파일이 저장될 폴더 명 app: 애플리케이션 소스 코드 위치 참고로 .는 현재 디렉토리를 사용한다는 의미임.

keywords

keywords 필드는 패키지를 설명하는 키워드 모음이다.

1. 검색 최적화: npm에 패키지를 등록했을 때, 다른 개발자들이 관련 키워드로 검색했을 때 발견될 수 있게 도와준다.
2. 패키지 설명: 패키지의 용도나 특성을 간략하게 표현한다. 예를 들어 "electron", "smartsilver", "webclient"라는 키워드를 통해 이 애플리케이션이 Electron 기반의 SmartSilver 웹 클라이언트임을 나타낸다.
3. 분류: npm 생태계에서 비슷한 용도의 패키지들과 함께 분류될 수 있도록 한다.

자동 실행 스크립트

이제 electron 의 기본 골조와 package.json 을 알아봤으면 linux 환경에서 자동으로 실행할 수 있도록 스크립트를 아래와 같이 작성해주면 된다.

/homr/user/.config/autostart/xxx.desktop 에 다음과 같이 작성해주고

[Desktop Entry]
Type=Application
Exec=/home/user/launch-settop.sh
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
Name[en_US]=settop
Name=settop
Comment[en_US]=
Comment=

해당 스크립트를 작성해준다.

#!/bin/bash
LATEST_APP=$(ls -t /home/user/본인앱이름-*.AppImage | head -1)
exec "$LATEST_APP"

그리고 아래 권한을 부여하면

chmod +x /home/user/launch-settop.sh

이제 pc 가 켜지면 자동으로 해당 app 이 실행된다.

npm run dev

우리가 테스트를 할 때 development 환경에서 실행할 때가 있다. 이를 위해 package.json 을 이렇게 바꿔주고,

"scripts": {
  "dev": "cross-env NODE_ENV=development electron . --enable-logging"
}

Electron 자체의 Linux SUID sandbox 문제를 해소하기 위해 다음과 같이 명령어를 입력해주면 된다.

sudo chown root:root /home/ubuntu/dev/node_modules/electron/dist/chrome-sandbox
sudo chmod 4755 /home/ubuntu/dev/node_modules/electron/dist/chrome-sandbox

이를 실행하는 이유는 Linux에서 Electron을 설치하면 sandbox 기능 때문에 일반 사용자로 바로 실행하면 오류가 발생할 수 있기 때문이다.

리모컨을 웹에서 동작하여 electron 을 사용하여 앱을 만들 수 있다. 그럼 마치 tvOS 처럼 동작하는데 이를 위해 web-client 에서 리모컨을 사용할 수있도록 도와주는 library 가 있다. 이에 Norigin-Spatial-Navigation 을 소개하고자 한다.

Norigin-Spatial-Navigation

Norigin-Spatial-Navigation 은 리모컨 또는 키보드 기반의 UI 탐색(특히 TV 앱)을 위한 React 중심의 spatial navigation 라이브러리이다. 넷플릭스나 유튜브 TV처럼 리모컨 방향키로 UI 요소 간 이동이 필요한 환경에서 매우 유용하다.

동작 방식

위 사진을 보면 이 library 가 어떻게 동작할지 궁금할텐데 이 library 는 기본적으로 DOM 기반으로 동작한다. 즉, 렌더링된 DOM 요소들의 위치와 크기를 계산하고, 어떤 요소가 포커스 가능한지(tabIndex, data-sn 속성 등)를 파악하여 공간적으로 다음 포커스 위치를 결정한다.

참고로 React key prop 과 focusable 의 key 는 전혀 관련이 없다.

useFocusable 훅을 통해 focusKey를 각 컴포넌트에 부여하고 trackChildren 속성을 설정함으로써, 라이브러리는 이 focusKey들을 사용하여 포커스 가능한 요소들을 관리하고, 포커스 이동 시 어떤 요소가 현재 활성화되어 있는지 등을 추적한다.

그리고 이 과정에서 CSS(DOM 요소의 레이아웃 정보)가 포커스 이동 방향을 결정하는 데 중요한 역할을 한다. 예를 들어, 왼쪽/오른쪽 화살표 키를 눌렀을 때, 현재 포커스된 요소의 DOM 위치를 기준으로 "오른쪽에 있는" 다음 포커스 가능한 요소를 찾는다.

install

npm i @noriginmedia/norigin-spatial-navigation --save

usage

init

useEffect(() => {
  init({
    // debug: true,
    // visualDebug: true,
  });

  setKeyMap({
    left: ['ArrowLeft', 37],
    up: ['ArrowUp', 38],
    right: ['ArrowRight', 39],
    down: ['ArrowDown', 40],
    enter: ['Enter', 13]
  });
}, []);

init 은 본인이 navigate 하고 싶은 모든 요소를 포함하는 부모 컴포넌트에 위치하면 된다.

useFocusable

이게 핵심 훅이다.

이때 대개 2가지 종류로 작성할 수 있다.

1. Provider

const {ref: busPageRef, focusKey: busInfoPageFocusKey, focusSelf: focusBusInfoPage} = useFocusable({
  focusKey: "bus-page",
  trackChildren: true,
});

    // 중략

return (
  <FocusContext.Provider value={busInfoPageFocusKey}>
  <Container ref={busPageRef}>
    <BusCard
direction="left"
stationName={busesInfo.station_1_info.name + " (상행)"}
highlightBusNumber={arrivalSoonBusL}
buses={station1Sorted}
/>
  <BusCard
direction="right"
stationName={busesInfo.station_2_info.name + " (하행)"}
highlightBusNumber={arrivalSoonBusR}
buses={station2Sorted}
/>
  </Container>
</FocusContext.Provider>
);

2. Consumer 아래는 위 Provider 의 BusCard 컴포넌트의 일부이다.

   const {ref: busCardRef, focused} = useFocusable({
   focusKey: `bus-card-${direction}`,
   onArrowPress: (direction) => {
    if (focused && scrollContainerRef.current) {
      const container = scrollContainerRef.current;
      const scrollAmount = 100;
   
      if (direction === 'up') {
        container.scrollTop = Math.max(0, container.scrollTop - scrollAmount);
        return false;
      } else if (direction === 'down') {
        container.scrollTop = Math.min(
          container.scrollHeight - container.clientHeight,
          container.scrollTop + scrollAmount
        );
        return false;
      } else if (direction === "left") {
        if (getCurrentFocusKey() === "bus-card-left") {
          setFocus("busArrived");
        }
      }
    }
    return true;
   }
   });
   

return ( <CardWrapper ref={busCardRef} $focused={focused} $direction={direction}> <Header $direction={direction}>

* 아래는 예시로 최대한 다양한 옵션을 적어보았다.

```ts
const {
  ref,
  focusSelf,
  focusKey,
} = useFocusable({
  focusable: true, // 컨테이너 자체는 포커스 불가
  saveLastFocusedChild: true,
  trackChildren: true,
  autoRestoreFocus: true,
  isFocusBoundary: true,
  focusBoundaryDirections: ["up", "down", "left"],
  focusKey: currentRemoteFocus,
  preferredChildFocusKey: undefined,
  extraProps: { foo: "bar" },
});

GCS 는 AWS 의 S3 포지션으로 static 파일을 서빙하는 역할을 한다. 그래서 나는 다음과 같이 pipe-line 을 구상해봤다.

자, 그럼 우선 코드부터 작성해보자.

0. package.json 수정

publish 설정은 빌드 시 업데이트 메타데이터 파일을 생성함.

latest.yml (Windows)
latest-mac.yml (macOS)
latest-linux.yml (Linux)

이 파일들에는 최신 버전 정보, 다운로드 URL, 파일 해시값 등이 포함됨.

{
  "name": "프로젝트 이름",
  "version": "프로젝트 버전",
  "description": "프로젝트 설명"
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "dev": "electron . --enable-logging",
    "build": "electron-builder",
    "dist": "electron-builder --publish=never",
    "build:linux64": "electron-builder --linux --x64",
    "postinstall": "electron-builder install-app-deps",
    "build-publish": "electron-builder --publish=always",
    "deploy": "node deploy-to-gcs.js"
  },
  "author": "kjw",
  "license": "ISC",
  "devDependencies": {
    "electron": "^37.2.5",
    "electron-builder": "^26.0.12",
    "electron-updater": "^6.6.2",
    "electron-log": "5.4.3"
  },
  "build": {
    "appId": "앱 id",
    "productName": "SmartSilverClient",
    "directories": {
      "output": "dist"
    },
    "files": [
      "**/*"
    ],
    "publish": {
      "provider": "generic",
      "url": "https://storage.cloud.google.com/tv-client-releases/"
    },
    "linux": {
      "target": [
        "AppImage"
      ],
      "category": "Utility"
    }
  },
  "type": "commonjs",
  "packageManager": "npm",
  "dependencies": {
    "@google-cloud/storage": "^7.17.0"
  }
}

provider와 url 옵션의 역할

provider: "generic": 커스텀 서버를 사용한다는 의미 (GitHub, S3 등이 아닌) url: 업데이트 파일들이 위치한 베이스 URL electron-updater는 이 URL에 /latest.yml을 붙여서 메타데이터를 가져옴. 참고로 파일 url 은 AppImage 가 들어있는 폴더까지 작성해주면 된다.

1. @google-cloud/storage 를 사용한 자동 deploy 로직 작성

@google-cloud/storage 에서 다운 받으면 되고 공식문서에서 upload 부분을 보면 된다.

const {Storage} = require("@google-cloud/storage");
const fs = require('fs');
const path = require('path');
const {log} = require("electron-log");

const storage = new Storage({
    keyFilename: '<본인 서비스 계정 .json>',
    projectId: '<본인 project id>'
});

const bucketName = '<본인 버킷 이름>';
const bucket = storage.bucket(bucketName);

async function uploadFiles() {
    const distPath = './dist'; // 본인 build 결과물 통상 ./dist
    const files = fs.readdirSync(distPath);

    // 본인은 linux 만 사용하여 AppImage 와 -linux.yml 만 등록
    const targetFiles = files.filter(file =>
        file.endsWith('.AppImage') || file.endsWith('-linux.yml')
    );

    for (const file of targetFiles) {
        const filePath = path.join(distPath, file);
        const destination = file;

        try {
            await bucket.upload(filePath, {
                destination: destination,
                metadata: {
                    cacheControl: 'no-cache',
                },
            });
            log(`✅ ${file} uploaded to ${bucketName}/${destination}`);
        } catch (error) {
            error(`❌ Failed to upload ${file}:`, error);
        }
    }
}

uploadFiles().catch(console.error);

참고로 electron 은 빌드하면 본인이 package.json 을 어떻게 꾸렸냐에 따라 빌드 결과물이 바뀐다. 만약 크로스 빌딩 등을 위해 모든 OS 에 대한 정보를 작성했다면 아래와 같은 결과물이 나온다.

버킷이름/
├── 폴더이름/
│   ├── latest.yml (Windows)
│   ├── latest-mac.yml (macOS)
│   ├── latest-linux.yml (Linux)
│   ├── your-app-1.0.0.exe
│   ├── your-app-1.0.0.dmg
│   └── your-app-1.0.0.AppImage

그리고 작성한 파일을 명령어로써 등록해주면 된다.

  // 윗줄 생략

  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "dev": "electron . --enable-logging",
    "build": "electron-builder",
    "dist": "electron-builder --publish=never",
    "build:linux64": "electron-builder --linux --x64",
    "postinstall": "electron-builder install-app-deps",
    "build-publish": "electron-builder --publish=always",
    "deploy": "node deploy-to-gcs.js"
  },
  "author": "kjw",
  "license": "ISC",

  // 아랫줄 생략

2. main.js 에 자동 update 기능 넣어주기

보통은 이제 해당 electron App 이 뜰 때, update 여부를 yml 로 검사하여 다르다면 이벤트에 따라 분기처리해주면 된다.

app.whenReady().then(() => {
    createWindow();

    // macOS에서 독 아이콘 클릭 시 윈도우 재생성
    app.on('activate', () => {
        if (BrowserWindow.getAllWindows().length === 0) {
            createWindow();
        }
    });

    // 디버깅 메뉴 생성
    createMenu();

    // 앱 실행 후 업데이트 확인
    if (!isDev) {
        setTimeout(() => {
            log.info('업데이트 확인을 시작합니다...');
            autoUpdater.checkForUpdatesAndNotify();
        }, 5000);
    }
});

업데이터 설정

autoUpdater.on('checking-for-update', () => {
    log.info('업데이트 확인 중...');
});

autoUpdater.on('update-available', (info) => {
    log.info(`새 업데이트가 있습니다: v${info.version}`);
    if (mainWindow) {
        mainWindow.webContents.send('update-available', info.version);
    }
});

autoUpdater.on('update-not-available', (info) => {
    log.info(`현재 최신 버전입니다: v${info.version}`);
});

autoUpdater.on('error', (err) => {
    log.error('업데이트 에러:', err);
});

autoUpdater.on('download-progress', (progressObj) => {
    const percent = Math.round(progressObj.percent);
    log.info(`업데이트 다운로드 중: ${percent}% (${progressObj.transferred}/${progressObj.total} bytes)`);

    if (mainWindow) {
        mainWindow.webContents.send('download-progress', percent);
    }
});

autoUpdater.on('update-downloaded', (info) => {
    log.info('업데이트 다운로드 완료. 5초 후 재시작합니다.');

    if (mainWindow) {
        mainWindow.webContents.send('update-ready');
    }

    setTimeout(() => {
        autoUpdater.quitAndInstall();
    }, 5000);
});

setFeedURL()로 동적 설정 (런타임에 설정) package.json의 publish 설정 (빌드타임에 설정) main.js에서 setFeedURL 제거하고, package.json만 사용 단, 동적으로 URL을 변경해야 하는 경우에만 setFeedURL 사용

(옵션.renderer.js 를 운용한다면) ㄱ. UI 업뎃

// renderer.js
const { ipcRenderer } = require('electron');

// 수동 업데이트 체크 버튼
document.getElementById('check-update').addEventListener('click', () => {
  ipcRenderer.send('check-for-updates');
});

// 업데이트 상태 수신
ipcRenderer.on('update-available', () => {
  document.getElementById('update-status').textContent = '새 업데이트가 있습니다. 다운로드 중...';
});

ipcRenderer.on('update-downloaded', () => {
  document.getElementById('update-status').textContent = '업데이트가 준비되었습니다. 재시작합니다.';
});

(옵션.renderer.js 를 운용한다면) ㄴ. Main 에서 핸들링

ipcMain.handle("check-for-updates", async () => {
    if (!isDev) {
        try {
            return await autoUpdater.checkForUpdatesAndNotify();
        } catch (error) {
            log('업데이트 체크 실패:', error);
            throw error;
        }
    }
    return null;
});

ipcMain.handle("quit-and-install", () => {
    if (!isDev) {
        autoUpdater.quitAndInstall();
    }
});

3. GCS 설정하기

여기서는 서비스 계정을 생성해줘야한다.

서비스 계정이란?

사람이 아닌 워크로드(앱, 배치, 컨테이너, VM)가 GCP 리소스에 안전하게 접근하기 위한 전용 신원이다. 개발자 개인 계정 대신, 애플리케이션 자체가 인증·권한 부여를 받을 수 있게 해주는 bot 이라고 생각하면 된다.

계정을 생성 후 json 을 다운 받으면 된다. 다음 원하는 버킷으로 가서 엑세스 권한 부여 를 누른 다음, 생성한 서비그 계정의 e-mail 입력해주면 된다.

그 후 오른쪽 상속 편집을 눌러 권한을 다음과 같이 지정해주면 된다.

4. build 및 deploy

그리고 다시 deploy 로직에서 본인의 프로젝트 id, 본인 서비스 계정의 .json 을 등록해준 후 build, deploy 를 해주면 성공적으로 static 파일이 올라간 것을 확인할 수 있다.

하지만 아니나 다를까 결국 문제가 생겼다.

이를 우회하는 방법은 다행이 굉장히 간단하다. Android Studio 는 Android\Sdk\ 를 사용하기 때문에 해당 directory 들을 미리 만들어 두고 symbolic link 만 만들면 된다.

mklink /D "C:\Android_Sdk" "C:\Users\강정우\AppData\Local\Android\Sdk"

• 옵션들 /D : 디렉토리 심볼릭 링크를 생성 (Directory symbolic link) /H : 하드 링크를 생성 (Hard link) /J : 디렉토리 정션을 생성 (Directory junction)

보통 기록들을 보면 instance 최초 생성 시 key 만을 등록한다. 하지만 집, 회사 굉장히 다양한 곳에서 접근할 수 있다. 그럴 땐 새로 키를 생성해서 그걸로 접근만 하면 되는 것이 아닌, 이를 새로 등록을 해줘야한다.

2. 공개키 등록의 원리

SSH 서버는 접속할 때 클라이언트의 비밀키로 만든 전자서명을 검증한다.

검증하려면 서버가 매칭되는 공개키를 알고 있어야 하는데, 그게 바로 ~/.ssh/authorized_keys 파일에 들어간다.

따라서 여기에 등록을 해주면 된다.

echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ...생략..." >> ~/.ssh/authorized_keys

>> 를 쓰는 이유는 기존 키들을 지우지 않고 새 키를 "추가"하기 위함이다. 만약 > 를 쓰면 기존 키들이 날아가니까 조심해야 한다.

3. 권한 확인

아마 AWS 는 필요없을 것 같긴 한데 SSH는 권한에 굉장히 민감하기 때문에 조치 후 아래 권한대로 맞추는 것을 권장한다.

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

무려 개발중인 버전도 2년 전이 마지막 업데이트다. 이때, 다른 대안이 없을까 서치하다가 완벽한 대안인 Object Box 에 대해 알게되었다.

1. ObjectBox 개념

ObjectBox는 순수 Dart 객체를 그대로 영속화하면서 SQLite 대비 최대 10배 빠른 성능을 제공하는 ACID 준수, 임베디드 NoSQL-DB 이다. 말은 SQL이 필요없지만 JPA 와 결이 비슷하다고 느낀 나로서는 아무래도 오히려 SQL 에 어느정도 지식이 있어야 사용이 용이하겠다고 판단하였다. 또 다른 장점은 필요 시 데이터 동기화·벡터검색까지 확장할 수 있다.

|구분|요약|비고|
|:---:|:---:|:--:|
|데이터 모델|    @Entity 클래스로 정의, @Id() 자동증가 기본값    |Null-safety 완전 지원|
|저장소(Store)|    Store 객체 1개가 DB 파일과 연동    |openStore() 헬퍼 함수 권장|
|Box|    store.box<T>()로 얻는 엔티티 단위 DAO    |CRUD·쿼리·트랜잭션 담당|
|쿼리|    타입 안전 QueryBuilder / 플러그식 조건 API|    findAsync()로 격리 Isolate 실행 가능|
|관계(Link)|    ToOne·ToMany 내장, LAZY 로딩 지원    |양방향은 Backlink 사용|
|반응형|    query.watch() 또는 box.watch() → Stream|    UI 자동 갱신에 용이|
|코드 생성|    build_runner로 objectbox.g.dart 생성|    변경 시마다 재실행 필요|

2. define entity

import 'package:objectbox/objectbox.dart';

@Entity()
class Person {
  @Id()
  int id = 0;
  String firstName;
  String lastName;

  Person({required this.firstName, required this.lastName});
}

이때, id가 0이면 put() 호출 시 자동 할당 JPA와 동일하게 @Entity()는 클래스, @Id()는 식별자이며, 이 둘은 필수이다. 원시 타입(Int, double, bool, String, DateTime, Uint8List) 및 조인을 위한 ToOne, ToMany 도 지원된다.

3. generate code

flutter pub run build_runner build --delete-conflicting-outputs

이제 entity 를 다 작성하였다면 위 명령어를 실행한다.

그러면 objectbox.g.dart, objectbox-model.json이 생성된다. analyzer 버전 불일치 등으로 78 오류가 나면 objectbox_generator 최신 버전으로 올리거나 캐시를 지운다.

4. init store

import 'objectbox.g.dart'; // 반드시 포함
import 'package:path_provider/path_provider.dart';
import 'package:path/path.dart' as p;

late final Store store;

Future<void> initStore() async {
    final dir = await getApplicationSupportDirectory(); // Android는 /files
    store = await openStore(directory: p.join(dir.path, 'person_db')); // 권장
}

5. CRUD

1. Box 가져오기

final personBox = store.box<Person>();

2. Create · Read · Update · Delete

// C
final id = personBox.put(Person(firstName: 'Jane', lastName: 'Doe')); 
// R
final jane = personBox.get(id);
// U
jane!.lastName = 'Black';
personBox.put(jane);
// D
personBox.remove(jane.id);

put()은 내부 트랜잭션 포함; 대량 삽입은 putMany(list) 사용해 속도 10배 이상 향상

3. QueryBuilder

이 부분이 바로 sql 을 몰라도 된다고 하는데 sql 을 알아야 query 를 작성할 수 있을 것으로 보인다. 물롱 sql 과 nosql 간의 괴리가 있을 수 있겠다.

final query = personBox
  .query(Person_.lastName.equals('Black') &
         Person_.firstName.startsWith('J'))
  .order(Person_.id, flags: Order.descending) // 정렬
  .build();

final results = query.find();  // List<Person>
query.close();                 // 리소스 해제

AND, OR 은 &, | 연산자로 표현한다. 참고로 pagenation 을 위한 오프셋, 제한은 query.offset = 40; query.limit = 20;

4. 비동기 쿼리

final people = await query.findAsync(); // Isolate에서 실행

6. Relations

1. ToOne

@Entity()
class Order {
  int id = 0;
  final customer = ToOne<Customer>(); // Target entity
}

@Entity()
class Customer {
  int id = 0;
  String name;
}

order.customer.target = customerObj;
box.put(order) 

하면 두 객체 모두 저장.

2. ToMany & Backlink

@Entity()
class Tag {
  int id = 0;
  String name;
  @Backlink('tags')
  final tasks = ToMany<Task>();
}

@Entity()
class Task {
  int id = 0;
  String title;
  final tags = ToMany<Tag>();
}

Backlink는 반대편에서 자동으로 역참조 컬렉션 생성.

3. Relation Query

final urgentTasks = taskBox
  .query(Task_.tags.contains(Tag_.name, 'urgent'))
  .build()
  .find();

7. 반응형 스트림

ObjectBox는 데이터 변경을 Stream으로 내보내 UI를 실시간으로 업데이트할 수 있다.

final query = personBox.query().build();
final subscription = query.watch(triggerImmediately: true)
  .listen((Query<Person> q) {
    final list = q.find();
    setState(() => persons = list);
  });

triggerImmediately 옵션으로 초기 데이터 전송. limit을 사용하려면 query.limit = 10 후 watch() 호출. subscription.cancel() 시 Query 자동 close.

8. 트랜잭션 및 동시성

store.runInTransaction(TxMode.write, () {
  for (final p in persons) personBox.put(p);
});

다트 Isolate 전송용 runInTransactionAsync()도 제공해 CPU 탐색 쿼리를 오프로드할 수 있다. CPU 집약적인 데이터베이스 작업을 메인(UI) 스레드에서 직접 실행하지 않고, 별도의 Isolate(백그라운드 스레드)에서 실행하도록 넘길 수 있다는 의미이다.

작업이 다른 Isolate에서 진행되는 동안, 메인 UI 스레드는 계속해서 사용자 인터페이스를 원활하게 갱신하고 사용자 입력을 처리할 수 있다. 그 후 무거운 작업이 완료되면, 그 결과만 메인 스레드로 다시 전달받게 된다.

9. 마이그레이션(스키마 업데이트)하는 법

1. 엔티티·필드 이름 변경: 원본에 @Id() 값 유지, 새 필드 추가 후 build_runner 재실행하면 자동 마이그레이션.
2. 삭제: 필드를 주석 처리 후 빌드 → 앱 배포 → 코드에서 제거 이렇게 귀찮지만 2-step 절차 권장. 바로 삭제하면 ID 재사용 충돌 가능.
3. 스키마 충돌 오류(예: last index ID 1 is higher than 0)는 모델 JSON·DB 파일 간 불일치로 발생한다. 사전 모델 동기화 후 배포해야 한다.

10. 성능 최적화

설정 중 DB 풀 설정, 로깅등은 제외하고 네트워크와 관련된 부분 알아보자.

1. 기본 및 핵심 설정

from .base import *
import os

DEBUG = False
ALLOWED_HOSTS = os.getenv('ALLOWED_HOSTS', '').split(',')
SWAGGER_ENABLED = False

ALLOWED_HOSTS = os.getenv('ALLOWED_HOSTS', '').split(','): Host header attacks 방어.

2. 보안 헤더 설정

# 보안 헤더 설정
SECURE_CROSS_ORIGIN_OPENER_POLICY = "same-origin"
SECURE_REFERRER_POLICY = 'strict-origin-when-cross-origin'
SECURE_CONTENT_TYPE_NOSNIFF = True
SECURE_BROWSER_XSS_FILTER = True

웹 애플리케이션의 기본적인 보안을 강화

SECURE_CROSS_ORIGIN_OPENER_POLICY = "same-origin": 다른 출처의 팝업 창이 현재 문서에 접근하는 것을 제한한다. Clickjacking과 같은 공격을 완화하는 데 도움이 된다.

SECURE_REFERRER_POLICY = 'strict-origin-when-cross-origin': Referrer 정보를 보낼 때의 정책을 정의한다. 다른 출처로 요청을 보낼 때만 오리진 정보를 포함하고, HTTPS에서 HTTP로 요청할 때는 보내지 않아 민감 정보 노출을 방지한다.

SECURE_CONTENT_TYPE_NOSNIFF = True: 브라우저가 MIME type sniffing을 통해 콘텐츠 타입을 유추하는 것을 방지한다. 이는 악의적인 콘텐츠가 잘못된 타입으로 해석되어 실행되는 것을 막는다.

SECURE_BROWSER_XSS_FILTER = True: 브라우저 내장 XSS(Cross-Site Scripting) 필터를 활성화하여 XSS 공격을 방어한다.

3. HTTPS 설정

# HTTPS 설정
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000  # 1년
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True

Nginx에서 이미 HTTPS 리다이렉션과 HSTS를 처리하고 있으면 필요없음 하지만 애플리케이션 레벨에서도 설정하여 혹시 모를 누락을 방지

SECURE_HSTS_SECONDS = 31536000 # (1년): HSTS(HTTP Strict Transport Security)를 활성화. 브라우저가 특정 기간(여기서는 1년) 동안 이 도메인에 대한 모든 요청을 HTTPS로만 보내도록 강제. 이는 중간자 공격(Man-in-the-Middle)을 통한 SSL 스트리핑 공격을 방지.

SECURE_HSTS_INCLUDE_SUBDOMAINS = True: HSTS 정책을 모든 서브도메인에도 적용한다.

SECURE_HSTS_PRELOAD = True: HSTS Preload List에 등록될 자격을 부여한다. Preload List에 등록되면, 사용자가 도메인에 최초 접속 시에도 HTTP 요청을 보내지 않고 바로 HTTPS로 연결을 시도하게 된다.

4. 세션 및 CSRF 보안

# 세션 보안
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = 'Strict'  # 최고 보안

# CSRF 보안
CSRF_COOKIE_SECURE = True
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SAMESITE = 'Strict'  # 최고 보안

쿠키를 통한 세션 및 CSRF 토큰 관리에 대한 보안 강화

SESSION_COOKIE_SECURE = True: 세션 쿠키가 HTTPS 연결을 통해서만 전송되도록

SESSION_COOKIE_HTTPONLY = True: 자바스크립트가 세션 쿠키에 접근하는 것을 방지. XSS 공격 시 쿠키 탈취를 어렵게 만듦

SESSION_COOKIE_SAMESITE = 'Strict': CSRF(Cross-Site Request Forgery) 공격을 방지하는 강력한 방법 'Strict' 모드는 동일 사이트 요청(Same-site request)에서만 쿠키가 전송되도록 한다. (예: 다른 사이트에서 링크를 통해 접속하더라도 해당 사이트의 쿠키는 전송되지 않음.) 이는 보안을 크게 강화하지만, 경우에 따라 Lax 모드가 더 적합할 수도 있음.

CSRF_COOKIE_SECURE = True, CSRF_COOKIE_HTTPONLY = True, CSRF_COOKIE_SAMESITE = 'Strict': CSRF 토큰 쿠키에도 세션 쿠키와 동일한 강력한 보안 설정이 적용

5. CORS 설정

# CORS 설정 (프로덕션 - 제한적)
CORS_ALLOW_ALL_ORIGINS = False
CORS_ALLOWED_ORIGINS = os.getenv('CORS_ALLOWED_ORIGINS', '').split(',')
CORS_ALLOW_CREDENTIALS = True
CORS_ALLOW_METHODS = ( ... )
CORS_ALLOW_HEADERS = ( ... )

CORS_ALLOW_ALL_ORIGINS = False: 모든 출처에서의 CORS 요청을 허용하지 않음.

2. nginx 설정

보통은 /api/ 로 경로를 나누어 요청하는 것이 일반적이지만 팀원의 요청으로 인하여 :8000 로 분기처리를 하였다.

server {
    listen 80;
    listen [::]:80;
    server_name cnn.parking.monster;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name cnn.parking.monster;

    # SSL 설정 (참고로 아래 경로들은 cerbot 를 사용했다면 기본 경로들)
    ssl_certificate /etc/letsencrypt/live/[도메인 네임]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[도메인 네임]/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # OCSP Stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # 보안 헤더 (옵션, 권장)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # 파일 업로드 크기 제한 (옵션)
    client_max_body_size 10M;

    # 타임아웃 설정 (옵션)
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # API 엔드포인트 (옵션 -> 여기선 8000 포트로 나눔.)
    location /api/ {
        proxy_pass http://unix:/run/gunicorn.sock;
        proxy_set_header Host $host;
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # WebSocket 지원 (옵션)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 버퍼링 설정 (옵션)
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }

    # 정적 파일 서빙
    location / {
        root [build 파일 위치];
        try_files $uri $uri/ /index.html;

        # 404 에러 처리
        error_page 404 /index.html;

        # HTML 파일 캐싱 방지
        location ~* \.html$ {
            expires -1;
            add_header Cache-Control "no-cache, no-store, must-revalidate, proxy-revalidate";
            add_header Pragma "no-cache";
            add_header Last-Modified $date_gmt;
            add_header ETag "";
            if_modified_since off;
        }

        # 정적 자원 캐싱
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|webp|woff|woff2|ttf|eot|map)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            add_header Vary "Accept-Encoding";

            # Gzip 압축 활성화 (옵션)
            gzip_static on;
        }
    }

    # 로그 설정
    access_log /var/log/nginx/cnn.parking.monster.access.log;
    error_log /var/log/nginx/cnn.parking.monster.error.log;
}

server {
    listen 8000 ssl http2;
    listen [::]:8000 ssl http2;
    server_name [도메인 네임];

    # SSL 설정
    ssl_certificate /etc/letsencrypt/live/[도메인 네임]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[도메인 네임]/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # 보안 헤더
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;

    # 파일 업로드 크기 제한 (옵션)
    client_max_body_size 10M;

    # 타임아웃 설정
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    location / {
        proxy_pass http://unix:/run/gunicorn.sock;
        proxy_set_header Host $host;
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # HTTP 버전 및 버퍼링 설정
        proxy_http_version 1.1;
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }

    # 로그 설정
    access_log /var/log/nginx/cnn.parking.monster.8000.access.log;
    error_log /var/log/nginx/cnn.parking.monster.8000.error.log;
}

사실 가장 간단한 방법은 bucket 을 사용하는 것이다.

로컬 → Cloud Storage 업로드

gsutil cp localfile.txt gs://your-bucket-name/

Cloud Storage → 로컬 다운로드

gsutil cp gs://your-bucket-name/file.txt .
gsutil은 Cloud SDK를 설치하면 함께 제공됩니다.

하지만 이는 무료가 아니다. 따라서 우리는 local PC 에서 파일을 WinSCP 를 사용하여 GCP 로 보내는 방법에 대알아보자.

2. WinSCP

1. key gen

보통 window 환경이니 putty 를 설치하자. 보통 intel 일테니 64bit installer 를 설치하고 putty 를 설치하면 putty Gen 도 함께 설치되는데 여기서 가장 많이 사용하는 RSA 방식으로 키를 생성하자.

그리고 key commnet 는 본인 gcp 계정 이름을 넣어줘야지 gcp 설정에서 key 를 넣고 이 comment 를 로그인한 gcp id 와 대조하여 로그인을 시켜준다.

참고로 위 public key 는 복사하지 않아도 그냥 private key 를 load 해도 다시 나오니 걱정 안 해도 된다.

2. gcp 등록

일단 위 public key 를 복사하고 gcp로 가서 수정에 들어간 다음

스크롤을 한참 내리면 기본적으로 2개의 key 가 들어있는데 이제 마지막에 방금 생성한 키를 넣어주면 된다.

3. WinSCP 로 접속

WinSCP 접속 후 고급 -> 개인키 파일 -> 로그인 순서대로 하면 된다.

필수 단어

1. WebRTC 란?

WebRTC(Web Real-Time Communication)는 브라우저나 앱이 직접 P2P로 오디오·비디오·데이터를 송수신하는 표준 기술을 뜻한다. 즉, WebRTC는 통신 프로토콜과 API의 집합이야. () WebRTC 자체에는 특정한 “라우팅 방식”(MCU, SFU 등)을 강제하지 않는다. 👉 WebRTC만으로도 A ↔ B 단순 P2P 통신이 가능하고, 여러명이면 메시에 가까운 연결도 가능.

WebRTC는 "클라이언트 ↔ 서버(또는 클라이언트 ↔ 클라이언트) 사이 미디어 전송에 항상 쓰이는 표준 프로토콜이다.

✅ ICE (Interactive Connectivity Establishment) WebRTC의 “네트워크 후보”를 찾고 연결을 시도하는 프레임워크. 예: 로컬 IP, 공인 IP, TURN 릴레이 IP 등 여러 경로를 테스트해서 최적의 경로를 찾음. 즉, ICE = 연결 성립 프로세스의 총칭.

✅ STUN (Session Traversal Utilities for NAT) NAT(Network Address Translation)를 통과하기 위한 서버. 브라우저가 “내 공인 IP를 알 수 있게” 도와줌. 아주 가볍고 빠름. P2P 통신 시 주로 사용.

✅ TURN (Traversal Using Relays around NAT) STUN으로 연결이 안 될 때 중계 서버를 통해 릴레이. 예: 방화벽이 너무 빡세서 직접 연결 불가할 때. TURN 서버는 대역폭도 많이 쓰고 비용도 큼.

ICE = 후보를 모아 연결 시도 └─ STUN = 내 공인 IP 알려주기 └─ TURN = 연결 안 되면 릴레이 중계

2. SFU (Selective Forwarding Unit) 란?

SFU는 다자간 화상회의의 미디어 라우팅 아키텍처를 말하는 거야.

보통 다자간 통화에서는 모든 참가자가 모든 다른 참가자에게 각각 스트림을 보내면 부담이 커지는데, SFU는 참가자가 서버에 하나만 업로드하고, 서버가 각 수신자에게 스트림을 “포워딩”해 줘.

SFU는 WebRTC 위에 구축될 수 있어. 즉, 미디어 전송은 WebRTC를 쓰고, 전송 방식(라우팅 아키텍처)으로 SFU를 적용하는 거지.

3. MCU (Multipoint Control Unit) 란?

다자간 화상회의의 미디어 서버 방식이야. 그런데 SFU랑 결정적으로 다른 점이 있어:

✅ MCU 간단 예시

1. 4명이 회의에 접속
2. 각자 서버에 스트림을 업로드
3. 서버가 모든 참가자의 비디오·오디오를 하나로 합성 (예: 화면에 4명 다 들어간 하나의 큰 비디오)
4. 서버가 합성된 하나의 비디오를 모든 참가자에게 전송
5. 클라이언트는 하나의 비디오만 디코딩하면 됨

✅ SFU 간단 예시

1. 4명이 회의에 접속
2. 각자 서버에 스트림을 업로드
3. 서버는 믹싱 없이 단순 포워딩 (예: A의 스트림은 B,C,D,E에게 개별 전달, B의 스트림도 마찬가지)
4. 클라이언트는 4개의 개별 스트림을 디코딩해서 갤러리 뷰 구성

4. Mesh 란?

Mesh(메시) 는 가장 단순한 다자간 통신 방식으로, 서버를 거치지 않고 모든 참가자가 서로 직접 P2P 연결을 맺는 모델이다. 🌟 Mesh 방식의 특징 각 참가자가 다른 모든 참가자에게 직접 스트림을 전송 예: 4명이면 각자가 3개의 스트림을 보냄

복사
편집
A ─────────▶ B
A ─────────▶ C
A ─────────▶ D
(B, C, D도 마찬가지)

별도의 서버에서 믹싱이나 포워딩을 하지 않음 순수 WebRTC P2P 이다.

장점. 구현이 가장 간단 지연(latency)이 가장 낮음 (직접 연결) 서버 비용이 거의 안 듦 (시그널링 서버만 있으면 됨)

단점. 참가자 수가 늘수록 트래픽 폭발 (연결 복잡도 O(n×(n−1)) ) CPU/대역폭 요구량이 급증 모바일/저사양 기기에서는 현실적으로 3~4명 이상 지원하기 어려움.

🧩 다시 요약 ✅ WebRTC = 스트림 송수신 프로토콜/기술 ✅ SFU/MCU/Mesh = 스트림을 어떻게 처리해 다자간으로 중계할지 결정하는 서버 아키텍처

대표 라이브러리 소개

우선 소개하기 앞서 현재 우리 상황에서 MCU 를 사용하면 아주 좋지 않을까? 생각할 수 있다. 나도 그랬다. 각 경로당 네트워크가 해당 현재 우리 회사 서비스 전용망이 아니기 때문에 화질이 매우 자주 깨진다. 그래서 하나의 비디오로 인코딩해서 내려보내면 좋을 것이라 생각했다.

그러나 이는 오산이었다.

1. ❌ 서버 CPU 부하가 엄청나게 큼 참여자 수 * 비디오 해상도 * FPS 만큼 인코딩해야 한다. (예) 10명 → 10개 스트림 믹싱 후 다시 10개로 인코딩) 이 때문에 50~100명 정도만 넘어가도 서버 증설 비용이 기하급수적으로 증가한다. 당연한 소리지만 이윤을 창출하는 기업에선 서버 비용도 고려해야할 매우 중요한 요소 중 하나다.

2. ❌ 지연(latency) 증가 믹싱과 인코딩 시간이 걸린다. SFU의 실시간성에 비해 딜레이 체감된다.

3. ❌ 대규모 회의에 부적합 결론적으로 CPU, 메모리 비용 때문에 요즘은 거의 SFU로 대체되는 추세이기 때문이다.

그러므로 우리는 SFU 라이브러리 위주로 살펴볼 것이다. 참고로 그나마 명맥을 유지중이던 Kurento가 그나마 오픈소스 중 유명했지만, 요즘은 Maintain 활동이 많이 줄어들었다.

그리고 아래 전반적인 표를 보고 가장 눈길을 끄는 Jitsi 와 Mediasoup 에 대해 알아보자.

1. Mediasoup

Node.js 기반의 서버 사이드 WebRTC SFU(Selective Forwarding Unit) 라이브러리로, 대규모 멀티파티 화상회의 및 실시간 스트리밍에 최적화되어 있음.

🧩 주요 구성

1. 아키텍처: Node.js 프로세스와 복수의 C++ 워커(worker)가 CPU 코어별로 분산 실행되어, 하나의 서버에서 수백~수천 명의 미디어 스트림을 효율적으로 처리 가능.
2. 확장성: router.pipeToRouter() 기능을 통해 여러 서버/워커 간에 트래픽을 분산시켜, 단일 서버 한계를 넘는 대규모 회의도 지원.
3. 코덱 지원: VP8, VP9, H.264, Opus 등 다양한 미디어 코덱을 유연하게 지원하며, 송출자별로 코덱을 다르게 설정하는 등 세밀한 제어 가능.
4. 커스터마이징: 신호 처리부터 미디어 라우팅, 외부 미디어 연동(FFmpeg, GStreamer 등)까지 거의 모든 부분을 개발자가 직접 설계·구현할 수 있음.
5. UI 미포함: Mediasoup 자체에는 사용자 인터페이스가 없으며, 모든 클라이언트·시그널링·UI를 직접 개발해야 함.

💪 장점

1. 최고 수준의 확장성: 수백~수천 명의 동시 접속자 처리에 강점. SFU 구조라 서버 부하 분산 및 네트워크 효율이 뛰어남.
2. 유연성/모듈성: 원하는 기능만 선택적으로 구현 가능. 다양한 비즈니스 요구에 맞는 맞춤형 플랫폼 구축에 적합.
3. 고급 미디어 처리: 시뮬캐스트, SVC, 다양한 코덱, 외부 미디어 연동 등 고급 기능 지원.
4. 낮은 레이턴시미디어 디코딩/인코딩이 없으므로 빠름.

❌ 단점

1. 높은 개발 난이도: 신호 처리, 미디어 라우팅, 클라이언트·UI 개발까지 모두 직접 구현해야 하므로, WebRTC 및 미디어 서버에 대한 깊은 이해 필요.
2. 커뮤니티/문서: Jitsi에 비해 커뮤니티와 문서가 적은 편.
3. 운영 난이도: 대규모 환경에서는 워커/라우터/로드밸런싱 등 인프라 설계가 복잡함.

🏗️ 대규모 회의 고려사항 300명이라면 "모두가 모두의 영상"은 불가능 (브라우저가 300개의 비디오 트랙을 처리 못 함) 적절한 "레이아웃 정책" 설계 필요 발표자 1~2명: 영상/음성 스트림 청취자: 오디오만 구독 상호간 채팅 + 제한적 마이크 권한 필요 시 여러 Worker를 띄워 부하 분산

2. Jitsi

완성형 오픈소스 화상회의 솔루션(Jitsi Meet)으로, 서버 및 클라이언트(웹/모바일)까지 모두 제공.

핵심 구성 요소:

1. Jitsi Videobridge: SFU 서버
2. Jicofo: 회의 관리 (시그널링 중심)
3. Prosody: XMPP 서버(시그널링)
4. Jitsi Meet: 웹 UI

🧩 주요 특징

1. 아키텍처: Jitsi Meet(프론트엔드), Jicofo(회의 관리), JVB(Jitsi Video Bridge, SFU), Prosody(XMPP 시그널링) 등으로 구성된 모듈형 구조.
2. 확장성: JVB(Videobridge)를 여러 대 추가하고, Octo(분산 처리) 및 로드밸런싱을 적용하면 200~250명 이상의 대규모 회의도 지원.
3. 기본 기능: 화면 공유, 채팅, 녹화, 브라우저 기반 UI, 모바일 앱 등 대부분의 화상회의 기능이 기본 제공.
4. 커스터마이징: 로고, UI, 기능 추가 등 커스터마이징 가능하지만, Mediasoup만큼의 자유도는 아님.

💪 장점

1. 빠른 구축: 별도 개발 없이 바로 사용 가능. 완성형 UI와 서버 제공.
2. 확장성: JVB 추가 및 서버 최적화, Octo 활용 시 200250명(기본), 최적화 시 수백수천 명까지 확장 가능.
3. 커뮤니티/문서: 대규모 커뮤니티와 풍부한 문서, 다양한 사례.
4. 보안: E2EE(1:1), 서버 자체 운영, 다양한 보안 옵션 지원.

❌ 단점

1. 커스터마이징 한계: UI/기능 커스터마이징은 가능하지만, 완전히 새로운 아키텍처나 신호 처리 로직 구현은 제한적.
2. 리소스 사용량: 대규모 회의 시 클라이언트(브라우저)와 서버 모두 높은 리소스 요구. 특히, 모든 참가자가 비디오를 켜면 브라우저 성능이 한계에 도달할 수 있음.
3. 기본 구조: Mediasoup에 비해 미디어 처리의 세밀한 제어(코덱, 라우팅 등)는 어려움.
4. XMPP 의존: 시그널링이 Prosody XMPP 기반이라 러닝커브 있음.

🏗️ 대규모 회의 고려사항

• Simulcast 필수 발표자 비디오 고화질 + 청취자 저화질
• Octo 모드 Videobridge 여러 대 연결하여 부하 분산
• Client 제한 UI에서 "타일뷰"를 제한하여 표시 수 축소
• 대규모 방에서는 청취자 전용 모드 권장

자~ Django 에서 mysqlclient 를 사용하여 다음과 같이 DB 를 잡는다고 가정하자.

# mysql 스크립트 연동하여 사용하는 방법
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'teakwondo',
        'USER': 'teakwondo',
        'PASSWORD': 'teakwondo123',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS':{
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
        }
    }
}

우선 서버에 DB 부터 설치해보자.

mysql-server 설치

sudo apt update
sudo apt install mysql-server
sudo mysql_secure_installation

그리고 mysql_secure_installation 를 설치하면 다음 몇개의 질문을 받는다.

1. VALIDATE PASSWORD COMPONENT? (비밀번호 유효성 검사 구성 요소를 사용하시겠습니까?) y 또는 n을 선택. 비밀번호 보안 수준을 높이는 기능인데, 개발 환경에서는 n을 선택해도 무방함.
2. New password: 및 Re-enter new password: MySQL root 사용자의 비밀번호를 설정.
3. Remove anonymous users? (익명 사용자 제거?) Y를 입력하는 것을 강권함.
4. Disallow root login remotely? (원격으로 루트 로그인 금지?) 보안을 위해 Y를 입력 후 다른 계정을 생성하는 것을 권하나 그냥 귀찮으면 N를 눌러도 됨.
5. Remove test database and access to it? (테스트 데이터베이스 및 접근 권한 제거?) Y를 입력하는 것이 좋음.
6. Reload privilege tables now? (권한 테이블 지금 다시 로드?) Y를 입력하여 변경 사항을 즉시 적용.

sudo systemctl status mysql

마지막으로 위 명령어로 잘 돌아가고 있는지 확인 후, 사용자를 만들어보자.

mysql 사용자 생성

sudo mysql -u root -p

아마 mysql_secure_installation 를 하지 않았으면 기본 비밀번호는 blank(아무것도 설정 X) 일것이다. 무튼 mysql 접속 후 위 Django 설정에 맞춰 유저를 생성하면

CREATE DATABASE IF NOT EXISTS teakwondo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'teakwondo'@'%' IDENTIFIED BY 'teakwondo123';
GRANT ALL PRIVILEGES ON teakwondo.* TO 'teakwondo'@'%';
FLUSH PRIVILEGES;
EXIT;

MySQL 5.7.6 버전 이상부터 validate_password 플러그인이 기본적으로 활성화되어 있어서, 설정된 비밀번호 정책에 맞지 않는 비밀번호는 사용할 수 없다. 즉, 대문자, 소문자, 숫자, 특수문자 조합으로 PW 를 만들어라는 것이다. 물론 비밀번호 정책 완화를 하면 된다.

teakwondo123 => Teakwondo!23

물론 이거에 맞춰서 Django 설정 파일도 바꿔줘야한다.

비밀번호 정책 완화

우선 mysql 접속 후 아래 명령어로 현재 비밀번호 정책상태를 파악 한다.

SHOW VARIABLES LIKE 'validate_password' 

그리고 비밀번호 정책 완화를 아래 명령어로 진행한다.

SET GLOBAL validate_password.special_char_count = 0;
SET GLOBAL validate_password.mixed_case_count = 0;
FLUSH PRIVILEGES;

후에 사용자의 비밀번호 변경 및 인증 플러그인을 설정한다. 여기서 인증 플러그인을 (mysql_native_password로) 설정하는 이유는 caching_sha2_password 문제로 인해 접속이 안 되었을 가능성을 해소하기 위함이다.

ALTER USER 'teakwondo'@'%' IDENTIFIED WITH mysql_native_password BY 'teakwondo123';
FLUSH PRIVILEGES;
EXIT;

그러고 mysql 을 재실행하면 된다.

sudo systemctl restart mysql

mysql 설정 파일 수정

bind-address 을 반드시 0.0.0.0 혹은 본인 공인 ip로 설정해줘야한다.

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
bind-address          = 0.0.0.0
mysqlx-bind-address   = 0.0.0.0

mysqlx-bind-address: MySQL 8.0 부터 도입된 X Protocol(mysqlx 프로토콜)에 대한 바인딩 주소이다. 일반적인 MySQL 클라이언트 연결(3306 포트)과는 직접적인 관련이 없다. 하지만 이 또한 127.0.0.1로 설정되어 있어서 외부 X Protocol 연결도 차단한다.

그리고 이를 적용하려면 mysql 을 재실행해줘야한다.

sudo systemctl restart mysql

포트 및 방화벽 확인 후 유효성 검사

Test-NetConnection -ComputerName [MySQL_서버_IP_주소] -Port 3306

# 예시
# ComputerName           : 203.0.113.45
# RemoteAddress          : 203.0.113.45
# RemotePort             : 3306
# InterfaceAlias         : Ethernet
# SourceAddress          : [내_PC_IP_주소]
# TcpTestSucceeded       : True

Django 에서 mySQL DB 접근에 필요한 library 들 설치하기

이때 mysqlclient는 파이썬에서 MySQL/MariaDB 데이터베이스와 통신하기 위한 C 언어 기반 라이브러리에 의존한다. 따라서 반드시 시스템 레벨의 개발 라이브러리를 먼저 설치해줘야 한다.

따라서 다음과 같이 필요한 library 들을 설치 후

# 가상환경 실행 중이라면 (deactivate)
sudo apt-get update
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config

python3-dev: 파이썬 개발 헤더 파일 및 라이브러리. C 확장 모듈을 컴파일하는 데 필요하다. default-libmysqlclient-dev: MySQL 클라이언트 라이브러리의 개발 파일이다. mysqlclient가 MySQL 서버와 통신할 수 있도록 해준다. build-essential: 컴파일에 필요한 기본적인 도구들 (gcc, g++ 등)을 포함한다. pkg-config: 패키지 정보를 질의하는 데 사용되는 도구이다.

(가상환경 실행 후)
pip install mysqlclient

자~ 그럼 다 설치가 되었으니 local 에서 돌려서 잘 실행되는지 확인하면 된다.

# (8000 은 기존 gunicorn 서비스가 사용중일 수도 있으니 8001)
gunicorn --workers 1 --bind 0.0.0.0:8001 tkd_api.wsgi:application

# 아래 명령어로 로그 확인
sudo journalctl -u gunicorn.service -f

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'teakwondo',
        'USER': 'teakwondo',
        'PASSWORD': 'teakwondo123',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS':{
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
        }
    }
}

'default': DB 연결 설정의 이름. Django 프로젝트 내에서 여러 데이터베이스를 사용할 경우, 각 데이터베이스에 고유한 이름을 부여하여 구별한다. 'default'는 Django가 기본적으로 사용하는 데이터베이스 연결을 의미한다.

'ENGINE': 어떤 종류의 데이터베이스를 사용할지 지정. 'django.db.backends.mysql'은 Django가 MySQL 데이터베이스와 통신하는 데 필요한 백엔드 모듈을 사용하겠다는 의미한다. 참고로 다른 데이터베이스 종류에 따라 postgresql_psycopg2 (PostgreSQL), sqlite3 (SQLite), oracle (Oracle) 등으로 변경될 수 있다.

'NAME': 연결할 데이터베이스의 이름. MySQL 서버 내에 'teakwondo'라는 이름의 데이터베이스가 존재해야 한다. Django는 이 데이터베이스에 테이블을 생성하고 데이터를 저장하게 된다.

'USER': 데이터베이스에 연결할 때 사용할 사용자 이름. MySQL 서버에 'teakwondo'라는 사용자 계정이 존재해야 하며, 해당 계정은 'teakwondo' 데이터베이스에 접근할 권한을 가지고 있어야 한다.

'PASSWORD': 데이터베이스 사용자 'teakwondo'의 비밀번호.

'HOST': 데이터베이스 서버가 실행 중인 호스트 이름 또는 IP 주소. 'localhost' 는 데이터베이스 서버가 Django 애플리케이션과 동일한 컴퓨터에서 실행되고 있음을 의미한다. 만약 데이터베이스가 원격 서버에 있다면 해당 서버의 IP 주소나 도메인 이름을 여기에 입력하면 된다.

'PORT': 데이터베이스 서버가 수신 대기하는 포트. '3306'은 MySQL의 기본 포트이다. 다른 데이터베이스 시스템은 다른 기본 포트를 사용하거나, MySQL이라도 관리자가 다른 포트를 사용하면 해당 포트를 적으면 된다.

'OPTIONS': 데이터베이스 연결이 이루어질 때 실행될 추가적인 옵션 또는 명령을 정의하는 부분. 'init_command'는 데이터베이스 연결이 성공적으로 수립된 직후에 실행될 SQL 명령을 지정한다. "SET sql_mode='STRICT_TRANS_TABLES'"는 MySQL의 sql_mode를 설정하는 SQL 명령이다.

STRICT_TRANS_TABLES: 해당 모드는 MySQL이 데이터 삽입 또는 업데이트 시 엄격한 규칙을 적용하도록 지시한다. 예를 들어, NOT NULL로 정의된 컬럼에 NULL 값을 삽입하려고 하거나, 정의된 컬럼의 최대 길이를 초과하는 문자열을 삽입하려고 할 경우, MySQL은 경고 대신 오류를 발생시키고 해당 작업을 거부한다. 이는 데이터 무결성을 강화하고, 예기치 않은 데이터 잘림이나 오류를 방지하는 데 도움이 된다.

그럼 짠~ 하고 붙는다.

참고

sqlite3 는 파일 기반의 경량 데이터베이스이다. 별도의 서버 프로세스가 필요하지 않으며, 모든 데이터는 단일 파일에 저장된다. 즉, 마치 flutter 의 SHARED_PREFERENCE 와 같다고 생각하면 된다.

# 장고 기본 db 사용하는 방법 (sqlite3)
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

네트워크 인터페이스 이름은 서버나 컴퓨터가 네트워크에 연결되기 위해 사용하는 하드웨어 및 소프트웨어 구성 요소의 식별자이다. 리눅스 시스템에서는 각 네트워크 카드나 인터페이스에 고유한 이름을 부여하여 구별하고 관리한다.

현대 네트워크 인터페이스 명명 규칙

Ubuntu 16.04 이후부터는 예측 가능한 네트워크 디바이스명(Predictable Network Interface Names) 규칙을 사용한다. 이전의 eth0, eth1 같은 단순한 명명 방식에서 벗어나 더 체계적인 이름을 사용한다. 그럼 이제 예를 들어 명명 규칙 구조를 알아보자.

앞 두 글자: 인터페이스 타입을 표시

en: 이더넷(Ethernet) wl: 무선 LAN ww: 무선 WAN

뒤 부분: 하드웨어 위치나 특성을 표시

o<숫자>: 온보드 디바이스 (예: eno1) s<숫자>: PCI Express 핫플러그 슬롯 인덱스 (예: ens33) p<버스>s<슬롯>: PCI 위치 (예: enp2s0) x<MAC주소>: MAC 주소 기반 (예: enxb23fd2asff)

systemd가 다음 우선순위에 따라 인터페이스 이름을 결정한다.

펌웨어/BIOS 정보 기반 온보드 디바이스 인덱스 (eno1) 펌웨어/BIOS 정보 기반 PCI Express 슬롯 인덱스 (ens1) 물리적 커넥터 위치 정보 (enp2s0) MAC 주소 기반 (선택적) 전통적인 예측 불가능한 이름 (eth0)

네트워크 인터페이스 이름 확인하는 방법

ls /sys/class/net

# 더 권장
ip link show

그럼 대충 아래 처럼 나온다. 여기서 알 수 있는 법은.

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN
2: ens33: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP

lo (Loopback Interface)

용도: 시스템 내부 통신용 가상 인터페이스 상태: UP, LOWER_UP (정상 작동) 특징: 모든 리눅스 시스템에 기본적으로 존재하는 루프백 인터페이스 사용 여부: SSH 접속용으로는 사용하지 않음

그리고 만약 docker 를 깔았다면 docker0 (Docker Bridge Interface) 도 있을 수 있다.