Reapply "간만의 공부.. 내용이 많은데 kui-veil 서버가 잘 처리해낼수 있을까?"

This reverts commit 7f3f250ed8.
2026-04-09 09:53:58 +09:00
parent 7f3f250ed8
commit fcfad44d51
5 changed files with 71 additions and 321 deletions
@@ -13,7 +13,6 @@ tags:
 GCE를 한대 빌려서 구축하였음
 ![[Pasted image 20260401150036.png]]
 원래는 퍼블릭하게 공개되면 안되는 자료들을 블러처리해주는 서버를 만들려고 (kui-veil) 확보한 서버였음
 <<<<<<< HEAD:content/01.Shelf/KUI/kui-vault.md
 ![[Pasted image 20260401163033.png]]
 ## 🖥️ Server Information: **kui-veil**
@@ -50,5 +49,3 @@ GCE를 한대 빌려서 구축하였음
 - **상태 요약:** 펌웨어 날짜가 2026년 2월인 것으로 보아, 시스템이 최근에 업데이트되었거나 생성된 아주 따끈따끈한 환경입니다!
 =======
 >>>>>>> parent of 96e0100 (간만의 공부.. 내용이 많은데 kui-veil 서버가 잘 처리해낼수 있을까?):01.Shelf/KUI/kui-vault.md
@@ -1,74 +0,0 @@
 ---
 id: "Gitea & Quartz 배포 자동화 트러블슈팅 20260401"
 created: "2026-04-01 13:23"
 tags:
 ---
 ## 🛠️ Gitea & Quartz 배포 자동화 트러블슈팅 기록
 ### 1. 문제의 발단: Gitea 경로 변경 (`/git/` 누락)
 기존에 설정된 Gitea의 접속 주소가 `/git/` 경로를 포함하고 있었으나, 서버 재설정 과정에서 이 경로가 빠지게 되었습니다. 이로 인해 연쇄적인 문제가 발생했습니다.
 - **현상:** Gitea 웹훅(Webhook)이 서버의 수신기(`webhook` 서비스)에 신호를 보내지 못함.
 - **원인:** Gitea 내부 리포지토리 설정과 외부 호출 URL이 일치하지 않아 404 에러 또는 연결 거부 발생.
 ---
 ### 2. 주요 장애 요인 및 해결 과정
 #### 📂 [Level 1] 서비스 실행 실패 (ConditionPathExists)
 - **에러:** `webhook.service was skipped because of an unmet condition check`.
 - **원인:** 기본 설치된 `webhook` 서비스가 `/etc/webhook.conf` 파일이 있어야만 작동하도록 설정됨.
 - **해결:** 서비스 파일(`systemd`)을 수정하여 해당 조건을 삭제하고, 우리가 직접 만든 `hooks.json`을 바라보도록 설정함.
 #### 🔑 [Level 2] 인증 에러 (no source for value retrieval)
 - **에러:** `500 | error evaluating hook: no source for value retrieval`.
 - **원인:** `hooks.json`에는 비밀번호(Secret) 검사 로직이 있는데, Gitea 웹훅 설정에는 비밀번호가 비어 있거나 헤더 이름이 일치하지 않음.
 - **해결:** 보안을 위해 Gitea와 서버 양쪽에 동일한 비밀번호를 설정하거나, 테스트를 위해 `trigger-rule`을 삭제하여 문턱을 낮춤.
 #### 🚀 [Level 3] 스크립트 실행 환경 문제 (npx & node)
 - **에러:** `npx: command not found` 또는 `node: No such file or directory`.
 - **원인:** `systemd` 서비스는 사용자 터미널 환경변수(`PATH`)를 읽지 못해 NVM에 설치된 Node.js를 찾지 못함.
 - **해결:** `deploy.sh` 상단에 Node.js 실행 파일이 있는 **절대 경로**를 `export PATH`로 직접 주입함.
 #### 📉 [Level 4] 자원 부족 및 서버 경직 (kswapd0)
 - **현상:** 빌드 시작 시 서버가 급격히 느려지며 접속이 끊김.
 - **원인:** Quartz 빌드는 CPU와 메모리를 많이 사용하는데, 512MB~1GB 수준의 낮은 메모리로 인해 스왑(Swap) 현상이 심화됨.
 - **해결:** 1. **Swap 확장:** 기존 스왑 파일을 **2GB**로 대폭 확장하여 물리 메모리 부족에 대비함.
    2. **우선순위 조정:** 빌드 명령어 앞에 **`nice -n 19`**를 붙여 다른 서비스(Nginx, Gitea)에 영향을 주지 않도록 최적화함.
 ---
 ### 3. 최종 자동화 아키텍처 (The "Tight" Setup)
 |**구성 요소**|**역할**|**최적화 포인트**|
 |---|---|---|
 |**Gitea**|소스 관리 및 트리거|`/git/` 경로를 제외한 클린 URL 적용|
 |**Webhook**|신호 수신기 (Port 29292)|전용 서비스 등록 및 자동 시작 설정|
 |**deploy.sh**|배포 스크립트|**절대 경로 사용**, **로그 파일 기록**, **우선순위 최저 설정**|
 |**Swap File**|가상 메모리 (2GB)|`/etc/fstab` 등록을 통한 영구 적용|
 ---
 ### 📝 교훈
 > **경로(Path)와 환경(Environment)은 언제나 명시적이어야 한다.** > 공짜 서버일수록 수동으로 자원을 배분하고 우선순위를 관리하는 **빡빡한 최적화**가 시스템의 생명줄이 된다.
@@ -1,239 +0,0 @@
 ---
 id: "gitea, qurtz 설치 20260331"
 created: "2026-03-31 10:41"
 tags:
 ---
 # 🌐 개인 서버(GCP) 기반 Gitea & HTTPS 구축 가이드
 본 문서는 Ubuntu 25.xx 환경에서 가벼운 Git 서비스인 **Gitea**를 설치하고, **Nginx**와 **DuckDNS**를 이용해 **HTTPS** 보안 접속을 구현한 과정을 정리합니다.
 ## 1. 서버 기본 환경 및 Gitea 설치
 가장 가벼운 바이너리 실행 방식으로 Gitea를 설치하고 전용 사용자를 생성했습니다.
 - **OS:** Ubuntu 25.xx (GCP Instance)
 - **사용자 생성:** `git` 시스템 사용자 생성 (`/home/git`)
 - **DB:** SQLite3 (경량화를 위해 선택)
 - **바이너리 경로:** `/usr/local/bin/gitea`
 - **데이터 경로:** `/var/lib/gitea`
 ---
 ## 2. 도메인 및 네트워크 설정
 외부 접속을 위해 무료 DDNS 주소를 확보하고 클라우드 방화벽을 조정했습니다.
 - **도메인:** `white-smith.duckdns.org` (GCP 외부 IP 연결 완료)
 - **포트 개방 (GCP & UFW):**
    - `22/tcp`: SSH 접속 (PuTTY, SFTP)
    - `80/tcp`: HTTP (인증서 발급 및 리다이렉트용)
    - `443/tcp`: HTTPS (실제 서비스용)
 - **보안 조치:** 불필요한 포트(20, 21, 3389 등) 차단 및 Gitea 직접 포트(3000)는 Nginx를 거치도록 외부 차단 권장.
 ---
 ## 3. HTTPS & Nginx 리버스 프록시
 Nginx를 앞단에 세워 보안을 강화하고 도메인 기반 접속을 구현했습니다.
 ### SSL 인증서 발급
 `Certbot`을 이용해 **Let's Encrypt** 무료 SSL 인증서를 발급받았습니다.
 Bash
 ```
 sudo certbot --nginx -d white-smith.duckdns.org
 ```
 ### Nginx 최종 설정 (`/etc/nginx/sites-available/gitea`)
 IP 접속 시 도메인으로 자동 전환되도록 설정했습니다.
 Nginx
 ```
 # 1. HTTP -> HTTPS 리다이렉트 (IP 포함)
 server {
    listen 80;
    server_name 34.19.79.94 white-smith.duckdns.org;
    return 301 https://white-smith.duckdns.org$request_uri;
 }
 # 2. HTTPS 서비스 블록
 server {
    listen 443 ssl;
    server_name white-smith.duckdns.org;
    # SSL 인증서 경로 (Certbot 관리)
    ssl_certificate /etc/letsencrypt/live/white-smith.duckdns.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/white-smith.duckdns.org/privkey.pem;
    location / {
        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 $scheme;
    }
 }
 ```
 ---
 ## 4. Gitea 내부 설정 업데이트
 HTTPS 환경에 맞춰 `/etc/gitea/app.ini` 파일을 `vi`로 수정했습니다.
 - **ROOT_URL:** `https://white-smith.duckdns.org/`
 - **DOMAIN:** `white-smith.duckdns.org`
 - **SSH_DOMAIN:** `white-smith.duckdns.org`
 ---
 ## 5. 현재 상태 요약
 1. **HTTPS 접속:** `https://white-smith.duckdns.org`로 안전하게 접속 가능.
 2. **IP 리다이렉트:** `34.19.79.94` 입력 시 자동으로 도메인 주소로 전환됨.
 3. **파일 전송:** 포트 22번을 통해 SFTP 방식으로 안전하게 파일 관리 중.
 # 🚀 Gitea & Quartz 도메인 통합 및 서버 설정 가이드
 본 가이드는 단일 메인 도메인(`white-smith.duckdns.org`)에서 **Quartz(블로그)**와 **Gitea(Git 서비스)**를 충돌 없이 운영하기 위한 설정법을 다룹니다.
 ---
 ## 1. 서비스 주소 설계
 동일 도메인 점유 문제를 해결하기 위해 **하위 경로(Path)** 방식으로 서비스를 분리했습니다.
 - **Quartz (메인 블로그):** `https://white-smith.duckdns.org/`
 - **Gitea (코드 저장소):** `https://white-smith.duckdns.org/git/`
 ---
 ## 2. Gitea 설정 수정 (`app.ini`)
 Gitea가 `/git/` 경로를 인식하도록 내부 설정을 변경해야 합니다.
 - **파일 위치:** `/var/lib/gitea/custom/conf/app.ini` (또는 설치 경로 내 `custom/conf/app.ini`)
 - **수정 내용:**
    Ini, TOML
    ```
    [server]
    ROOT_URL = https://white-smith.duckdns.org/git/
    LOCAL_ROOT_URL = http://127.0.0.1:3000/
    HTTP_ADDR = 127.0.0.1
    HTTP_PORT = 3000
    ```
    > **Tip:** `LOCAL_ROOT_URL`을 추가해야 내부 리다이렉션 시 404 오류를 방지할 수 있습니다.
 ---
 ## 3. Nginx 역방향 프록시 설정
 `/etc/nginx/sites-available/gitea` 파일을 수정하여 두 서비스를 통합합니다.
 Nginx
 ```
 server {
    listen 80;
    server_name 34.19.79.94 white-smith.duckdns.org;
    return 301 https://white-smith.duckdns.org$request_uri;
 }
 server {
    listen 443 ssl;
    server_name white-smith.duckdns.org;
    ssl_certificate /etc/letsencrypt/live/white-smith.duckdns.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/white-smith.duckdns.org/privkey.pem;
    # [우선순위 1] Gitea 설정
    location /git/ {
        proxy_pass http://127.0.0.1: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 $scheme;
    }
    # [우선순위 2] Quartz 설정 (메인)
    location / {
        proxy_pass http://127.0.0.1:8080; # Quartz 실행 포트
        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;
    }
 }
 ```
 ---
 ## 4. 권한 관리 및 접근 (etc 경로)
 시스템 설정 파일을 편리하게 수정하기 위해 권한을 조정하거나 도구를 활용합니다.
 1. **권한 변경 (추천):**
    Bash
    ```
    sudo chown -R root:$(whoami) /etc/nginx
    sudo chmod -R 775 /etc/nginx
    ```
 2. **포트 확인 명령어:**
    Bash
    ```
    sudo ss -tulpn | grep node  # Quartz 포트 확인
    ```
 3. **서비스 재시작:**
    Bash
    ```
    sudo nginx -t && sudo systemctl restart nginx
    sudo systemctl restart gitea
    ```
 ---
 ## 5. 핵심 주의사항
 - **Nginx 경로 슬래시:** `proxy_pass http://127.0.0.1:3000/;` 처럼 끝에 `/`가 있어야 `/git/` 경로가 중복되지 않고 올바르게 전달됩니다.
 - **Quartz 실행:** Quartz를 `npx quartz build --serve`로 띄운 경우 해당 포트(보통 8080)가 Nginx 설정과 일치해야 합니다.
 - **보안:** `/etc` 전체 권한을 `777`로 바꾸지 마세요. 필요한 폴더만 그룹 권한을 부여하는 것이 안전합니다.
@@ -1,5 +1,74 @@
 ---
-id: "유닉스 철학 (The Unix Philosophy) 20260330"
+id: 유닉스 철학 (The Unix Philosophy) 20260330
-created: "2026-03-30 15:20"
+created: 2026-03-30 15:20
 tags:
 ---
 # 개념
 [[유닉스(Unix)]] 개발자들 사이에서 내려오는 유명한 원칙이 있습니다. 바로 **작고 단순한 것이 아름답다**는 점입니다.
 1. **각 프로그램은 한 가지 일만 잘해야 한다.**
 2. **여러 프로그램을 조합해서 복잡한 문제를 해결한다.** (이때 사용하는 것이 **파이프(|)** 기능입니다.)
 3. **모든 것은 파일이다.** (텍스트 파일로 설정을 관리하고 데이터를 주고받습니다.)
 > [!note] 단순히 운영체제를 만드는 기술적 규칙이 아니라, 소프트웨어를 설계하고 문제를 해결하는 일종의 **미니멀리즘 예술**에 가깝습니다.
 : 1970년대 벨 연구소의 더글러스 매킬로이(Douglas McIlroy)가 정립한 이 철학의 핵심은 **작고 단순하며, 서로 협력하는 도구**를 만드는 것입니다.
 ## 1. 핵심 3원칙
 더글러스 매킬로이는 유닉스 철학을 다음 세 문장으로 요약했습니다.
 - **한 가지만 하되, 아주 잘하라 (Do One Thing and Do It Well):** 하나의 프로그램은 오직 하나의 기능에만 집중해야 합니다. 기능이 많아지면 복잡해지고 버그가 생기기 쉽기 때문입니다.
 - **함께 작동하도록 만들어라 (Expect the output of every program to become the input to another):** 프로그램은 서로 연결될 것을 예상하고 만들어야 합니다.
 - **텍스트 스트림을 표준 인터페이스로 사용하라:** 데이터는 가공하기 가장 쉬운 **텍스트** 형태로 주고받아야 합니다. 그래야 서로 다른 프로그램끼리 쉽게 대화할 수 있습니다.
 ## 2. 파이프(Pipe)와 필터
 유닉스 철학을 시각적으로 가장 잘 보여주는 것이 바로 **파이프(|)** 기호입니다. 작은 도구들을 파이프로 연결하여 복잡한 일을 수행하는 방식이죠.
 > **예시:** `ls | grep "test" | sort`
 > 
 > 1. `ls`: 파일 목록을 출력한다. (한 가지 일)
 >     
 > 2. `grep`: 그중 "test"가 포함된 것만 골라낸다. (한 가지 일)
 >     
 > 3. `sort`: 결과를 알파벳 순으로 정렬한다. (한 가지 일)
 >     
 각각은 단순한 도구일 뿐이지만, 연결하면 강력한 기능을 수행합니다. 이는 마치 레고 블록을 조립하는 것과 비슷합니다.
 ## 3. 에릭 레이먼드의 룰 (Rule of...)
 오픈소스 전도사인 에릭 레이먼드는 그의 저서에서 유닉스 철학을 더 구체적인 규칙으로 확장했습니다.
 - **단순함의 법칙 (Rule of Simplicity):** 복잡해지기 전까지 최대한 단순하게 설계하라.
 - **명확함의 법칙 (Rule of Clarity):** 코드는 컴퓨터가 읽기 쉬운 것보다 사람이 읽기 쉬운 것이 더 중요하다.
  위의 두 법칙을 지킴으로써 코드가 [[KISS (Keep It Simple, Stupid)]]해진다.
 - **조합의 법칙 (Rule of Composition):** 프로그램이 다른 프로그램과 쉽게 연결될 수 있도록 설계하라.
  조합의 법칙을 지키다 보면 코드가 [[DRY (Don't Repeat Yourself)]]해진다.
 - **침묵의 법칙 (Rule of Silence):** 프로그램이 정말로 할 말이 없을 때는 아무것도 출력하지 마라. (그래야 다른 프로그램이 출력을 가공하기 좋습니다.)
 유닉스 철학을 구체화 한 규칙들을 지킴으로써 [[클린코드의 기술]]들을 지키게 된다.
 ---
 ## 4. 왜 유닉스 철학이 중요한가요?
 오늘날 현대적인 소프트웨어 개발 방법론인 **마이크로서비스 아키텍처(MSA)** 나 **함수형 프로그래밍**의 뿌리도 이 유닉스 철학에 닿아 있습니다.
 - **유지보수 용이:** 작고 단순한 코드는 고치기 쉽습니다.
 - **재사용성:** 잘 만들어진 작은 도구는 여기저기서 다시 쓰일 수 있습니다.
 - **확장성:** 새로운 기능을 추가할 때 기존 프로그램을 수정하는 대신, 새로운 도구를 만들어 연결하면 됩니다.
@@ -1,3 +0,0 @@
 ---
 title: 2. 보관함
 ---