즐거운 개발 세상

SpeakSH: Claude 로 Linux 서버 작업

블체. — Wed, 18 Mar 2026 00:05:11 +0900

회사 업무 중 서버작업을 해야할 일이 생겼다.

직접 서버에 붙어서 작업을 해보니 여러가지 오류가 발생했다.
인증서 문제, 패키지 버전문제 등등.. 해결이 가능한 문제들이었다.
다만 문제는 시간이겠지.
마침 내가 전에 만들어둔 "서버 - Claude" 를 가능하게 해주는 미들웨어를 사용하기로 했다.
문제는 아주 빠르게 해결이 되었다. 로그도 따로 남겼고.

Claude 에서 작성하는 명령어와 서버의 콘솔로그도 모두 출력된다. 내가 직접 작업도 가능하고.

서버의 로그를 Claude 도 확인가능해서 이슈에 대해 대화가 가능하다.

서버에 명령어를 실행하고, 그에 대한 로그를 가지고 대화가 가능했다.

작업 내용을 내가 파악하면서도 빠르게 진행할 수 있었다.

GitLab → GitHub 미러링 연동 구축기

블체. — Tue, 17 Mar 2026 20:00:47 +0900

개요

자체 서비스 납품으로 인해 취약점 점검을 진행해야했다.

취약점 점검 서비스는 github 에 연동해서 검사가 가능했는데, 우리팀은 gitlab 을 사용하고 있었다.

gitlab의 프로젝트를 연동시키기 위해서 처음에 고려했던 건 Repository mirroring 이었다.

문제가 하나 있었는데, 특정 브랜치만 연동할 방법이 없다는 것이었다. 따라서 CI/CD 파이프라인을 선택할 수 밖에 없었다.

따라서 GitLab서버에 GitLab Runner를 설치하고 프로젝트 루트 디렉토리에 .gitlab-ci.yml을 작성해서 특정 브랜치에 push가 발생하면 GitHub으로 자동 미러링되도록 했다.

환경

항목 내용

GitLab 서버	Rocky Linux 9.6, dev.test.co.kr
GitLab Runner	v16.11.0 (shell executor)
동기화 대상 브랜치	v1_test
GitHub 레포지토리	test-lab/dev01

구성 목표

GitLab (dev.test.co.kr)
  └── push to v1_test
        └── CI/CD Pipeline 실행
              └── git push → GitHub (test-lab/dev01) main 브랜치

GitLab Runner 설치 및 등록

Runner 설치 확인

which gitlab-runner && gitlab-runner --version

Runner 등록 명령어

gitlab-runner register \
  --non-interactive \
  --url https://dev.test.co.kr \
  --token glrt-xxxxxxxxxxxxxx \
  --executor shell \
  --description git-runner

Runner 서비스 등록 및 시작

바이너리로 직접 설치한 경우 systemd 서비스 등록이 필요하다.

gitlab-runner install --user root --working-directory /root
gitlab-runner start

.gitlab-ci.yml 최종 구성

stages:
  - sync

github_sync:
  stage: sync
  only:
    - v1_test
  variables:
    GIT_DEPTH: 0
  script:
    - git push --force https://test-lab:${GITHUB_TOKEN}@github.com/test-lab/dev01.git HEAD:main

GitLab CI/CD 변수 설정

설정 → CI/CD → Variables에서 아래와 같이 등록한다.

Key Value 옵션

GITHUB_TOKEN

GitHub PAT 토큰

Masked ✅, Protected ❌, Expanded ❌

주의: Masked를 반드시 체크해야 로그에 토큰이 노출되지 않는다.

트러블슈팅

1. TLS 인증서 오류 — Legacy Common Name

오류 메시지

tls: failed to verify certificate: x509: certificate relies on legacy Common Name field, use SANs instead

원인

Go 1.15 이후부터 SAN(Subject Alternative Name)이 없는 Legacy Common Name 방식의 인증서를 거부한다. 내부망 자체 서명 인증서가 SAN 없이 발급되어 있었다.

조치

기존 인증서를 백업하고 SAN을 포함한 새 인증서를 재발급한다.

# 백업
mkdir -p /etc/gitlab/ssl/backup_$(date +%Y%m%d)
cp /etc/gitlab/ssl/dev.test.co.kr.crt /etc/gitlab/ssl/backup_$(date +%Y%m%d)/
cp /etc/gitlab/ssl/dev.test.co.kr.key /etc/gitlab/ssl/backup_$(date +%Y%m%d)/

# SAN 포함 인증서 재발급
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/gitlab/ssl/dev.test.co.kr.key \
  -out /etc/gitlab/ssl/dev.test.co.kr.crt \
  -subj '/C=KR/ST=seoul/L=seoul/O=test/OU=dev/CN=dev.test.co.kr' \
  -addext 'subjectAltName=DNS:dev.test.co.kr'

# nginx 재시작
gitlab-ctl restart nginx

2. TLS 인증서 오류 — Unknown Authority

오류 메시지

tls: failed to verify certificate: x509: certificate signed by unknown authority

원인

자체 서명 인증서가 시스템 CA 신뢰 저장소에 등록되어 있지 않다.

조치

Rocky Linux의 CA 신뢰 저장소에 인증서를 등록한다.

cp /etc/gitlab/ssl/dev.test.co.kr.crt /etc/pki/ca-trust/source/anchors/
update-ca-trust

3. apk 명령어를 찾을 수 없음

오류 메시지

bash: apk: 명령어를 찾을 수 없음

원인

.gitlab-ci.yml에 image: alpine:latest와 apk add 명령이 작성되어 있었다. image 키는 Docker executor 전용 설정이며, shell executor에서는 무시된다. 따라서 서버 OS인 Rocky Linux에서 Alpine 전용 패키지 매니저 apk를 실행하려 해서 실패한다.

조치

shell executor 환경에서는 서버에 이미 git이 설치되어 있으므로 image와 before_script를 제거한다.

# 변경 전
image: alpine:latest
before_script:
  - apk add --no-cache git

# 변경 후 — 불필요하므로 제거

4. GitHub 인증 실패

오류 메시지

remote: Invalid username or token. Password authentication is not supported for Git operations.

원인

GITHUB_TOKEN 변수에 Protected 옵션이 설정되어 있었다. Protected 변수는 Protected 브랜치에서만 주입되므로, 해당 브랜치가 Protected로 설정되지 않은 경우 변수 값이 빈 문자열로 전달된다.

조치

GITHUB_TOKEN 변수 편집 → Protected 체크 해제

5. 토큰 평문 노출

오류 메시지

error: 레퍼런스를 'https://test-lab:ghp_xxxxxxxxxxxx'에 푸시하는데 실패했습니다

원인

GITHUB_TOKEN 변수에 Expanded 옵션이 활성화되어 있어 URL 파싱이 깨지면서 토큰 값이 에러 메시지에 평문으로 출력됐다.

조치

GitHub에서 노출된 토큰을 즉시 폐기(revoke)하고 새 PAT를 발급한다.
GitLab CI/CD 변수를 아래 옵션으로 재등록한다.

옵션 설정

Masked	✅ 체크 (로그 마스킹)
Protected	❌ 해제
Expanded	❌ 해제

6. shallow clone으로 인한 push 실패

오류 메시지

remote: fatal: did not receive expected object
error: 리모트 묶음 풀기 실패: index-pack failed

원인

GitLab Runner의 기본 GIT_DEPTH가 20으로 설정되어 있어 커밋 히스토리를 20개만 가져온다. GitHub에 push할 때 참조하는 커밋 객체가 shallow clone 범위 밖에 있어 실패한다.

조치

.gitlab-ci.yml에 GIT_DEPTH: 0을 설정해 전체 히스토리를 clone한다.

variables:
  GIT_DEPTH: 0

정리

순서 트러블 원인 조치

1	TLS Legacy CN 오류	SAN 없는 자체 서명 인증서	SAN 포함 인증서 재발급
2	TLS Unknown Authority	CA 신뢰 저장소 미등록	update-ca-trust
3	apk 명령어 없음	shell executor에서 Alpine 명령 사용	image, before_script 제거
4	GitHub 인증 실패	변수 Protected 옵션 활성화	Protected 해제
5	토큰 평문 노출	변수 Expanded 옵션 활성화	토큰 폐기 후 재발급, Expanded 해제, Masked 체크
6	push 실패 (객체 누락)	shallow clone (depth=20)	GIT_DEPTH: 0 설정

GPL-2.0 라이선스 취약점 조치

블체. — Thu, 12 Mar 2026 19:00:18 +0900

: javax.mail → jakarta.mail 교체

개요

시스템 취약점 점검 과정에서 다음과 같은 라이선스 취약점이 검출되었다.

Package License Category Severity Target

javax.mail:mail

GPL-2.0-with-classpath-exception

restricted

HIGH

Java

GPL-2.0 라이선스란?

GPL-2.0(GNU General Public License v2.0)은 오픈소스 라이선스 중에서도 강력한 의무사항을 지닌 라이선스다. 핵심 의무사항은 다음과 같다.

소스 코드 공개 의무 : GPL 2.0 코드를 사용하여 개발된 결과물을 배포할 경우, 수정된 부분을 포함한 전체 소스 코드를 반드시 제공해야 한다.
라이선스 유지 : 파생된 프로그램은 반드시 GPL 2.0 라이선스를 유지해야 한다.
고지 의무 : 저작권 및 라이선스 고지사항을 원본 그대로 유지해야 한다.
배포 시 소스 제공 : 바이너리(실행 파일) 배포 시, 소스 코드 또는 소스 코드를 얻을 수 있는 정보를 함께 제공해야 한다.

GPL의 전염성

GPL 라이선스의 가장 중요한 특징은 전염성(Copyleft) 이다. GPL로 된 코드를 포함하거나 결합한 프로그램은 전체가 GPL로 공개되어야 한다.

즉, javax.mail:mail 라이브러리를 사용하는 솔루션은 전체 소스코드를 외부에 공개해야 하는 치명적인 리스크를 안게 된다.

문제 확인

build.gradle에서 다음 의존성이 확인되었다.

implementation 'javax.mail:mail:1.4.7'

이 라이브러리가 GPL-2.0 라이선스 취약점의 원인이었다.

조치 방법: jakarta.mail로 교체

아래와 같이 라이브러리를 교체한다.

// 기존
implementation 'javax.mail:mail:1.4.7'

// 변경
implementation 'org.eclipse.angus:jakarta.mail:2.0.5'

교체 이유

jakarta.mail 역시 GPL-2.0 라이선스를 포함하고 있다. 그러나 동시에 GNU General Public License version 2 + Classpath Exception 라이선스도 함께 보유하고 있다.

Classpath Exception이 핵심이다. 이 예외 조항은 GPL 코드를 클래스패스(classpath)로 연결하여 사용할 경우, GPL의 전염성이 적용되지 않도록 해준다. 즉, 해당 라이브러리를 사용하더라도 전체 소스코드를 공개하지 않아도 된다.

참조: Jakarta Mail License 공식 문서

정리

구분 javax.mail:mail:1.4.7 org.eclipse.angus:jakarta.mail:2.0.5

라이선스	GPL-2.0	GPL-2.0 + Classpath Exception
소스코드 공개 의무	있음	없음
상용 솔루션 사용	위험	안전

GPL 라이선스 계열 라이브러리를 도입할 때는 반드시 Classpath Exception 포함 여부를 확인해야 한다. 예외 조항 하나의 유무가 소스코드 전체 공개 여부를 결정짓는 만큼, 라이선스 검토는 개발 초기 단계부터 꼼꼼히 이루어져야 한다.

gemini-cli 사용하는 법

블체. — Wed, 11 Mar 2026 15:05:34 +0900

1. npm install -g @google/gemini-cli
2. 터미널에 "gemini" 입력
3. https://aistudio.google.com/ 의 api 키를 복사해서 로그인 혹은 구글 아이디로 로그인

Docker 환경에서 OpenClaw와 Ollama 연결

블체. — Tue, 24 Feb 2026 00:15:30 +0900

OpenClaw와 Ollama를 각각 Docker 컨테이너로 실행할 때, 두 컨테이너가 서로 통신하도록 네트워크를 연결하는 과정을 정리했다.

환경

OS: Windows 11 + WSL2 (Ubuntu)
Docker Desktop
OpenClaw: docker-compose로 실행 (/mnt/c/clawdbot)
Ollama: 별도 Docker 컨테이너로 실행

문제 상황

OpenClaw와 Ollama를 각각 독립된 Docker 컨테이너로 실행하면, 기본적으로 서로 다른 네트워크에 속하게 된다. 이 상태에서는 OpenClaw가 Ollama에 접근할 수 없어 연결 오류가 발생한다.

트러블슈팅 과정

1단계: 네트워크 확인

먼저 현재 Docker 네트워크 상태를 확인한다.

docker network ls

NETWORK ID     NAME                    DRIVER    SCOPE
b0b244886b91   bridge                  bridge    local
8eade16da4b1   clawdbot_default        bridge    local
2889821e834b   clawdbot_openclaw-net   bridge    local
8bc80a2e5471   host                    host      local
14980b8324ab   none                    null      local

OpenClaw는 clawdbot_openclaw-net 네트워크를 사용하고 있었다. Ollama 컨테이너가 이 네트워크에 포함되어 있는지 확인한다.

docker network inspect clawdbot_openclaw-net | grep -A 5 "Containers"

"Containers": {
    "0d103a074adf...": {
        "Name": "clawdbot-openclaw-gateway-1",
        ...
    }
}

OpenClaw 컨테이너만 있고 Ollama는 없었다. 이것이 연결 실패의 원인이었다.

2단계: Ollama를 OpenClaw 네트워크에 연결

docker network connect clawdbot_openclaw-net ollama

연결 후 OpenClaw 컨테이너 내부에서 Ollama에 접근 가능한지 테스트한다.

docker exec -it clawdbot-openclaw-gateway-1 curl http://ollama:11434/api/tags

{"models":[{"name":"llama3.2:latest","model":"llama3.2:latest",...}]}

네트워크 연결은 성공했다.

3단계: openclaw.json 설정

네트워크 연결 후에도 채팅이 작동하지 않았다. 원인은 openclaw.json 설정 문제였다.

시행착오 1: api 필드 누락

처음 설정:

"ollama": {
  "baseUrl": "http://ollama:11434/v1",
  "apiKey": "ollama-local"
}

오류:

Error: No API provider registered for api: undefined

api 필드가 없으면 OpenClaw가 어떤 API 방식을 사용할지 알 수 없어서 크래시가 발생한다.

시행착오 2: openai-responses API 타입 사용

"api": "openai-responses"

같은 오류가 반복됐다. OpenClaw의 Ollama 통합은 native Ollama API를 사용해야 한다.

최종 설정:

"models": {
  "providers": {
    "ollama": {
      "baseUrl": "http://ollama:11434",
      "apiKey": "ollama-local",
      "api": "ollama",
      "models": [
        {
          "id": "llama3.2:latest",
          "name": "Llama 3.2",
          "input": ["text"],
          "reasoning": false,
          "cost": {"input": 0, "output": 0},
          "contextWindow": 32000,
          "maxTokens": 4096
        }
      ]
    }
  }
},
"agents": {
  "defaults": {
    "model": {
      "primary": "ollama/llama3.2:latest"
    }
  }
}

핵심 포인트:

baseUrl에서 /v1 제거 → native Ollama API 사용
"api": "ollama" 명시 필수
models 배열 필수 (없으면 config validation 오류 발생)

4단계: docker-compose.yml에 ollama 추가 (영구 설정)

docker network connect 명령은 컨테이너 재시작 시 초기화된다. 영구적으로 같은 네트워크를 공유하려면 docker-compose.yml에 ollama를 추가한다.

services:
  openclaw-gateway:
    networks:
      - openclaw-net

  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    networks:
      - openclaw-net
    restart: unless-stopped

networks:
  openclaw-net:
    driver: bridge

volumes:
  ollama:
    external: true

그 다음 재시작:

docker compose down
docker compose up -d

최종 결과

OpenClaw 로그에서 다음과 같이 모델이 정상 인식됨을 확인:

[gateway] agent model: ollama/llama3.2:latest

채팅 시 Ollama 컨테이너 CPU가 약 400%까지 올라가며 추론이 실행되는 것을 확인할 수 있다.

요약

문제 원인 해결

curl: (6) Could not resolve host: ollama	컨테이너 간 네트워크 분리	docker network connect로 같은 네트워크 연결
No API provider registered for api: undefined	api 필드 누락	"api": "ollama" 명시
config validation 오류	models 배열 누락	models 배열 추가 필수
재시작 후 네트워크 끊김	임시 네트워크 연결	docker-compose.yml에 ollama 서비스 추가

Docker 환경에서 Ollama + OpenClaw(Clawdbot) 설치하기

블체. — Mon, 23 Feb 2026 00:01:26 +0900

개요

환경: Windows 10/11, Docker Desktop, WSL2(Ubuntu)
목표: Ollama 로컬 LLM 모델을 AI 백엔드로 사용하는 OpenClaw를 Docker로 구성
참고: Clawdbot → Moltbot → OpenClaw 순서로 이름이 변경됨 (2026년 기준 공식 명칭은 OpenClaw)

1. WSL2 설치

PowerShell을 관리자 권한으로 실행 후:

wsl --install

설치 완료 후 PC 재시작. 재시작 후 Ubuntu 터미널이 자동으로 열리면 사용자 이름과 비밀번호를 설정한다.

2. Docker Desktop 설치

https://www.docker.com/products/docker-desktop 에서 다운로드
설치 완료 후 PC 재시작

WSL2 연동 설정

Docker Desktop 실행 후:

⚙️ Settings → Resources → WSL Integration
Enable integration with my default WSL distro 체크
Ubuntu 토글 켜기
Apply & Restart

WSL2에서 Docker 권한 설정

Ubuntu 터미널에서 실행:

sudo usermod -aG docker $USER

PowerShell에서 WSL2 재시작:

wsl --shutdown

Ubuntu 터미널을 다시 열고 정상 동작 확인:

docker compose version

3. Ollama 설치 (Docker)

컨테이너 실행

docker run -d --name ollama -p 11434:11434 -v ollama:/root/.ollama ollama/ollama

모델 다운로드

docker exec -it ollama ollama pull llama3.2

동작 확인

브라우저에서 http://localhost:11434 접속 시 Ollama is running 이 출력되면 정상.

4. OpenClaw 설치 (Docker)

소스코드 클론

cd /mnt/c/
git clone https://github.com/openclaw/openclaw.git clawdbot
cd /mnt/c/clawdbot

주의: 이후 모든 명령어는 Git Bash가 아닌 Ubuntu 터미널(WSL2) 에서 실행해야 한다.
Git Bash는 화살표 키 등 인터랙티브 기능을 제대로 지원하지 않는다.

설치 스크립트 실행

./docker-setup.sh

설치 마법사 진행

단계 선택

보안 경고	y + Enter
Onboarding mode	QuickStart → Enter
모델 선택	목록에 Ollama 없음 → 아무거나 선택 후 진행 (나중에 설정 파일 수정)
Skills 설치	Skip for now

마법사 완료 후 터미널에 토큰이 출력되지만, 실제 사용할 토큰은 설정 파일에서 확인한다.

5. OpenClaw 대시보드 접속

실제 토큰 확인

cat ~/.openclaw/openclaw.json

출력 내용 중 gateway.auth.token 값을 복사한다.

"gateway": {
  "auth": {
    "mode": "token",
    "token": "여기가 실제 토큰"
  }
}

브라우저 접속

http://localhost:18789/?token=여기에토큰값

6. 트러블슈팅

device token mismatch

disconnected (1008): unauthorized: device token mismatch

터미널 출력 토큰과 설정 파일 토큰이 다른 경우 발생한다.
반드시 ~/.openclaw/openclaw.json 의 gateway.auth.token 값을 사용해야 한다.

pairing required

disconnected (1008): pairing required

브라우저 디바이스 인증 단계에서 막히는 경우다. 설정 파일에 dangerouslyDisableDeviceAuth 옵션을 추가하면 우회할 수 있다.

nano ~/.openclaw/openclaw.json

gateway 섹션을 아래와 같이 수정:

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "auth": {
    "mode": "token",
    "token": "여기에토큰값"
  },
  "controlUi": {
    "dangerouslyDisableDeviceAuth": true
  },
  "tailscale": {
    "mode": "off",
    "resetOnExit": false
  }
}

저장 후 컨테이너 재시작:

docker compose -f /mnt/c/clawdbot/docker-compose.yml restart openclaw-gateway

7. Ollama 모델 연결

설정 파일에 Ollama provider를 추가한다:

nano ~/.openclaw/openclaw.json

최상위 레벨에 models 항목 추가, agents.defaults.model 수정:

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://host.docker.internal:11434/v1",
        "apiKey": "ollama"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/llama3.2"
      }
    }
  }
}

핵심: Docker 컨테이너 내부에서 호스트 PC의 Ollama에 접근할 때는 localhost 대신 host.docker.internal 을 사용해야 한다.

재시작:

docker compose -f /mnt/c/clawdbot/docker-compose.yml restart openclaw-gateway

8. 최종 구성도

브라우저 (http://localhost:18789)
        ↓
OpenClaw Gateway (Docker 컨테이너)
        ↓
Ollama (Docker 컨테이너, 포트 11434)
        ↓
llama3.2 등 로컬 LLM 모델

자주 쓰는 명령어

# 컨테이너 상태 확인
docker ps

# OpenClaw 로그 확인
docker compose -f /mnt/c/clawdbot/docker-compose.yml logs -f openclaw-gateway

# OpenClaw 재시작
docker compose -f /mnt/c/clawdbot/docker-compose.yml restart openclaw-gateway

# OpenClaw 중지
docker compose -f /mnt/c/clawdbot/docker-compose.yml down

# OpenClaw 시작
docker compose -f /mnt/c/clawdbot/docker-compose.yml up -d

# Ollama 모델 목록 확인
docker exec -it ollama ollama list

# Ollama 모델 추가
docker exec -it ollama ollama pull 모델명

sQuiry: AI 서버와 통신하는 프론트엔드 개발

블체. — Tue, 10 Feb 2026 00:10:09 +0900

서론

이전글: https://egg-stone.tistory.com/43

이전 글에서는 sQuiry의 백엔드 구조와 RAG 기반 SQL 생성 엔진에 대해 다뤘다.

이번 글에서는 프론트엔드 아키텍처와 백엔드와의 통신 구조를 다룬다. 프레임워크 없이 구현한 이유와 전체적인 데이터 플로우를 중심으로 설명한다.

기술 스택과 선택 이유

바닐라 JavaScript

React나 Vue 같은 프레임워크를 사용하지 않고 바닐라 JavaScript를 선택했다.

선택 이유:

프로젝트 규모가 작음 (3개 페이지, 독립적인 기능)
빌드 도구 불필요, 즉시 배포 가능
빠른 초기 로딩 속도
복잡한 상태 관리가 필요 없음

프레임워크는 강력하지만 모든 프로젝트에 필요한 것은 아니다. sQuiry는 페이지별로 독립적인 기능을 제공하므로 단순한 구조가 적합했다.

FastAPI + Jinja2

서버 사이드 렌더링을 위해 FastAPI와 Jinja2 템플릿 엔진을 사용했다.

장점:

초기 페이지 로드가 빠름
SEO 친화적
FastAPI와 자연스럽게 통합

구조:

frontend/
├── routes.py           # 페이지 라우팅
├── templates/          # Jinja2 템플릿
│   ├── base.html      # 공통 레이아웃
│   ├── index.html     # 메인 페이지
│   ├── query.html     # 쿼리 생성 페이지
│   └── history.html   # 히스토리 페이지
└── static/            # 정적 파일
    ├── css/           # 스타일시트
    └── js/            # JavaScript

CSS 변수 기반 스타일링

CSS 변수로 디자인 토큰을 정의하여 일관된 디자인 시스템을 구축했다. 향후 다크 모드나 테마 변경이 쉽도록 설계했다.

전체 아키텍처

레이어 구조

사용자
  ↓
[프론트엔드 - HTML/CSS/JS]
  ↓ HTTP Request (JSON)
[FastAPI 라우터]
  ↓
[백엔드 API] (/api/v1/*)
  ↓
[Vanna Engine + DB]
  ↓ HTTP Response (JSON)
[프론트엔드 - JavaScript]
  ↓
DOM 업데이트 → 사용자에게 표시

프론트엔드와 백엔드를 명확하게 분리했다.

프론트엔드 라우트: /, /query, /history → HTML 응답
백엔드 API: /api/v1/* → JSON 응답

이렇게 분리하면 향후 모바일 앱이나 다른 클라이언트에서도 동일한 API를 사용할 수 있다.

페이지 구조

메인 페이지 (/):

서비스 소개
주요 기능 안내
쿼리 생성 페이지로 이동

쿼리 생성 페이지 (/query):

자연어 질문 입력
SQL 생성 및 편집
SQL 실행 및 결과 표시

히스토리 페이지 (/history):

실행한 쿼리 목록
질문, SQL, 실행 결과 표시

백엔드와의 데이터 통신

API 엔드포인트

프론트엔드는 다음 API 엔드포인트와 통신한다.

1. SQL 생성

POST /api/v1/generate-sql
요청: { "question": "지난 달 매출은?" }
응답: { "question": "...", "sql": "SELECT ...", "execution_time": 1.5 }

2. SQL 실행

POST /api/v1/execute-sql
요청: { "sql": "SELECT * FROM orders" }
응답: { "success": true, "data": [...], "row_count": 10 }

3. 히스토리 조회

GET /api/v1/query-history
응답: { "history": [ { "question": "...", "sql": "...", "timestamp": "..." } ] }

데이터 플로우

쿼리 생성 및 실행 플로우:

1. 사용자가 자연어 질문 입력
   ↓
2. JavaScript: POST /api/v1/generate-sql
   ↓
3. 백엔드: Vanna 엔진이 SQL 생성
   ↓
4. 프론트엔드: 생성된 SQL 화면에 표시
   ↓
5. 사용자가 "실행" 버튼 클릭 (또는 SQL 편집 후 실행)
   ↓
6. JavaScript: POST /api/v1/execute-sql
   ↓
7. 백엔드: MariaDB에서 쿼리 실행
   ↓
8. 프론트엔드: 결과를 테이블로 렌더링

JavaScript 구조

코드를 기능별로 모듈화했다.

common.js - 공통 유틸리티

API 호출 헬퍼 (fetch 래퍼)
알림 메시지 표시
테이블 생성 함수
SQL 포맷팅

query.js - 쿼리 페이지 로직

SQL 생성 요청
SQL 실행 요청
SQL 편집 기능
복사 기능

history.js - 히스토리 페이지 로직

히스토리 로드
히스토리 렌더링

비동기 통신 패턴

모든 API 호출은 async/await로 처리하여 UI 블록을 방지했다.

// API 호출 패턴
async function generateSQL(question) {
    try {
        // 로딩 표시
        showLoading();
        
        // API 호출
        const response = await fetch('/api/v1/generate-sql', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ question })
        });
        
        const data = await response.json();
        
        // 결과 표시
        displaySQL(data.sql);
        
    } catch (error) {
        // 에러 처리
        showError(error.message);
    } finally {
        // 로딩 숨김
        hideLoading();
    }
}

이 패턴을 모든 API 호출에 일관되게 적용했다.

상태 관리

프레임워크를 사용하지 않기 때문에 상태 관리는 단순하게 처리했다.

페이지 수준 상태:

각 페이지는 독립적으로 동작
전역 상태 없음
필요한 데이터는 API에서 다시 가져옴

쿼리 페이지 상태:

let currentSql = '';  // 현재 생성된 SQL

단일 변수로 현재 SQL을 관리한다. 사용자가 편집하면 이 변수를 업데이트하고, 실행 시 이 변수의 값을 API로 전송한다.

히스토리 페이지 상태:

상태를 별도로 유지하지 않음
페이지 로드 시마다 API에서 최신 데이터 가져옴
새로고침 버튼으로 수동 업데이트 가능

사용자 경험 설계

단계별 UI 표시

쿼리 생성 페이지는 사용자의 작업 단계에 따라 섹션을 순차적으로 표시한다.

1. 질문 입력 섹션 (항상 표시)
   ↓
2. SQL 생성 클릭
   ↓
3. 생성된 SQL 섹션 표시
   ↓
4-A. 실행 클릭 → 결과 섹션 표시
4-B. 편집 클릭 → 편집 섹션 표시

각 단계에서 사용자는 다음에 무엇을 해야 할지 명확하게 알 수 있다.

피드백 시스템

사용자 행동에 즉각적인 피드백을 제공한다.

로딩 상태:

API 호출 중 로딩 스피너 표시
버튼 비활성화로 중복 클릭 방지

성공/실패 알림:

작업 성공 시 녹색 알림 (3초 후 자동 사라짐)
에러 발생 시 빨간색 알림

시각적 피드백:

버튼 호버 시 색상 변경
복사 버튼 클릭 시 체크마크 아이콘으로 변경

에러 처리

모든 API 호출에서 에러를 캐치하고 사용자에게 명확한 메시지를 표시한다.

try {
    const response = await apiCall('/api/v1/generate-sql', ...);
} catch (error) {
    showAlert(error.message, 'error');
}

네트워크 에러, 서버 에러, 검증 에러 모두 일관된 방식으로 처리한다.

성능 고려사항

최소한의 JavaScript

JavaScript 파일 크기를 최소화했다.

common.js: 약 2KB
query.js: 약 5KB
history.js: 약 3KB

외부 라이브러리를 사용하지 않아 추가 로딩 시간이 없다.

DOM 조작 최적화

테이블이나 히스토리 목록처럼 여러 요소를 렌더링할 때, HTML 문자열을 한 번에 생성한 후 innerHTML로 삽입한다. 여러 번 DOM을 조작하는 것보다 훨씬 빠르다.

비동기 로딩

페이지 로드와 API 호출을 분리하여 초기 로딩 속도를 개선했다. 히스토리 페이지는 빈 페이지를 먼저 표시하고, JavaScript로 데이터를 비동기 로드한다.

개발 과정의 설계 결정

상태 관리

선택: 페이지별 독립 상태

이유:

페이지 간 공유 상태 없음
Redux나 Vuex 같은 상태 관리 라이브러리 불필요
각 페이지는 필요한 데이터를 API에서 직접 가져옴

페이지가 많아지거나 복잡한 상태 공유가 필요하면 재고려할 수 있다.

API 설계

선택: RESTful API

프론트엔드와 백엔드 API를 명확히 분리했다.

/api/v1/* - JSON API
그 외 - HTML 페이지

이렇게 분리하면 API 버전 관리가 쉽고, 다른 클라이언트 (모바일 앱 등)에서도 동일한 API를 사용할 수 있다.

배포 구조

FastAPI는 프론트엔드와 백엔드를 하나의 애플리케이션으로 서빙한다.

# main.py
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from frontend.routes import router as frontend_router
from backend.api.routes.query import router as api_router

app = FastAPI()

# API 라우트 등록
app.include_router(api_router)

# 프론트엔드 라우트 등록
app.include_router(frontend_router)

# 정적 파일 서빙
app.mount("/static", StaticFiles(directory="frontend/static"), name="static")

장점:

단일 서버로 배포 가능
CORS 문제 없음
배포 구조 단순

단점:

프론트엔드와 백엔드를 독립적으로 스케일링 불가능
하지만 sQuiry는 소규모 프로젝트라 문제없음

향후 개선 방향

프론트엔드 빌드 도구 도입

프로젝트가 커지면 다음을 고려할 수 있다.

Vite로 모듈 번들링
TypeScript 도입
CSS 전처리기 (Sass)

하지만 현재는 복잡도 대비 이점이 크지 않다.

WebSocket 지원

실시간 쿼리 실행 상태나 진행률을 표시하려면 WebSocket이 필요할 수 있다.

사용자 → 쿼리 실행 요청
서버 → WebSocket: "쿼리 파싱 중..."
서버 → WebSocket: "데이터베이스 연결 중..."
서버 → WebSocket: "쿼리 실행 중... (10%)"
서버 → WebSocket: "완료!"

하지만 현재는 쿼리 실행 시간이 짧아 불필요하다.

결론

나는 거의 백엔드개발자에 가깝다. 다행히 Claude 의 도움으로 썩 괜찮아 보이는 웹서비스를 만들 수 있었다.
개발하면서 구조에 대해 고민했고, 설계단계에서 많은 시간을 보냈다.

핵심 설계 원칙:

적절한 기술 선택 - 프로젝트 규모에 맞는 도구를 사용했다
명확한 레이어 분리 - 프론트엔드와 백엔드를 독립적으로 설계했다
일관된 API 통신 - 모든 API 호출에 동일한 패턴을 적용했다
사용자 중심 설계 - 단계별 UI와 명확한 피드백을 중점으로 개발했다.

프레임워크는 많은 문제를 해결해주지만, 모든 프로젝트에 필수는 아니라는 생각이든다.

프로젝트의 요구사항을 정확히 파악하고 적절한 수준의 기술을 선택하는 것이 중요할 듯 하다.

sQuiry: 오픈소스 LLM과 RAG 기반 자연어-SQL 변환 서비스

블체. — Mon, 9 Feb 2026 00:10:45 +0900

서론

자연어로 쿼리를 생성하자

데이터베이스를 다루다 보면 비개발자가 원하는 데이터를 조회하기 위해 개발자에게 요청하거나, SQL을 배워야 하는 상황이 발생한다. "지난 달 매출이 가장 높은 상위 10개 제품을 보여줘"라는 간단한 요청도 복잡한 SQL 쿼리로 변환해야 한다.

이런 문제를 해결하기 위해 자연어를 SQL로 변환하는 시스템 sQuiry를 개발했다.

특히 상용 API 대신 Huggingface의 오픈소스 모델을 로컬에서 실행하고, RAG 기법으로 데이터베이스 스키마와 예제를 학습시켜 정확도를 높이는 것이 핵심이다.

프로젝트 개요

sQuiry는 자연어 질문을 SQL 쿼리로 변환하고 실행하는 API 서비스다. 사용자는 "지난 주 주문 수는?"과 같이 자연어로 질문하면, 시스템이 이를 SQL로 변환하여 실행하고 결과를 반환한다.

핵심 특징

오픈소스 LLM을 로컬에서 실행 (비용 절감)
RAG 기반 스키마 학습 (정확도 향상)
Few-shot learning 지원
FastAPI 기반 RESTful API

기술 스택

Python 3.x
FastAPI - 웹 프레임워크
Vanna.ai - SQL 생성 프레임워크
Ollama - 로컬 LLM 실행 환경
ChromaDB - 벡터 데이터베이스
MariaDB - 타겟 데이터베이스
PyMySQL - DB 커넥터

아키텍처 설계

sQuiry의 전체 아키텍처는 다음과 같다.

사용자 질문 (자연어)
    ↓
FastAPI (엔드포인트)
    ↓
Vanna Engine (SQL 생성)
    ↓ (유사 예제 검색)
ChromaDB (RAG)
    ↓ (프롬프트 구성)
Ollama (LLM 추론)
    ↓
생성된 SQL
    ↓
MariaDB (실행)
    ↓
결과 반환 (JSON)

데이터 흐름

사용자가 자연어 질문을 API로 전송
ChromaDB에서 유사한 질문-SQL 쌍 검색 (RAG)
데이터베이스 스키마 정보 조회
검색된 예제와 스키마로 프롬프트 구성
Ollama를 통해 LLM에 전송
생성된 SQL을 MariaDB에서 실행
결과를 JSON으로 반환

핵심 구현 내용

1. Vanna.ai 커스터마이징

Vanna.ai는 SQL 생성을 위한 프레임워크다. 하지만 기본적으로 OpenAI API를 사용하기 때문에, Ollama를 사용하도록 커스터마이징했다.

class OllamaLLM:
    """Ollama LLM 래퍼"""
    
    def __init__(self, host: str, model: str):
        self.host = host
        self.model = model
    
    def generate(self, prompt: str) -> str:
        """Ollama API를 통해 텍스트 생성"""
        try:
            url = f"{self.host}/api/generate"
            payload = {
                "model": self.model,
                "prompt": prompt,
                "stream": False
            }
            
            response = requests.post(url, json=payload, timeout=120)
            response.raise_for_status()
            
            result = response.json()
            return result.get('response', '')
            
        except Exception as e:
            raise Exception(f"Ollama 생성 실패: {str(e)}")

Ollama는 HTTP API를 제공하므로 간단한 POST 요청으로 LLM을 호출할 수 있다. 타임아웃은 120초로 설정하여 대용량 쿼리 생성도 안정적으로 처리했다.

2. ChromaDB 기반 RAG 구현

ChromaDB는 벡터 데이터베이스로, 임베딩된 질문-SQL 쌍을 저장하고 유사도 검색을 수행한다.

class VannaGenerator(ChromaDB_VectorStore):
    """Vanna.ai 기반 SQL 생성기 (ChromaDB + Ollama)"""
    
    def __init__(self, config=None):
        ChromaDB_VectorStore.__init__(self, config=config)
        self.llm = OllamaLLM(
            host=config.get('ollama_host', 'http://localhost:11434'),
            model=config.get('ollama_model', 'llama3.1:8b')
        )
    
    def generate_sql(self, question: str, **kwargs) -> str:
        """자연어 질문으로부터 SQL 생성"""
        # 1. 관련 문서/스키마 검색 (RAG)
        similar_docs = self.get_similar_question_sql(question)
        
        # 2. 데이터베이스 스키마 정보 가져오기
        schemas = db_connection.get_table_schemas()
        
        # 3. 프롬프트 구성
        context = ""
        if similar_docs:
            context = "\n참고할 수 있는 유사한 예제:\n"
            for doc in similar_docs[:3]:
                context += f"Q: {doc.get('question', '')}\n"
                context += f"SQL: {doc.get('sql', '')}\n\n"

RAG의 핵심은 유사한 질문-SQL 쌍을 검색하여 프롬프트에 포함시키는 것이다. 이렇게 하면 LLM이 데이터베이스 구조와 쿼리 패턴을 더 잘 이해할 수 있다.

3. 프롬프트 엔지니어링

정확한 SQL을 생성하기 위해 프롬프트를 세밀하게 설계했다.

prompt = f"""당신은 SQL 전문가입니다. 사용자의 자연어 질문을 SQL 쿼리로 변환하세요.

{schema_text}
{context}

데이터베이스: MariaDB
질문: {question}

중요한 규칙:
1. 반드시 위에 명시된 테이블과 컬럼만 사용하세요
2. 존재하지 않는 테이블이나 컬럼을 절대 사용하지 마세요
3. 테이블명과 컬럼명을 정확히 확인하세요
4. SQL 쿼리만 반환하세요 (설명이나 다른 텍스트 없이)
5. 마크다운 코드 블록 없이 순수 SQL만 작성하세요
6. SELECT, INSERT, UPDATE, DELETE 등 표준 SQL을 사용하세요

SQL:"""

프롬프트에는 다음 정보를 포함시켰다.

스키마 정보 - 사용 가능한 테이블과 컬럼 목록
유사 예제 - RAG로 검색된 질문-SQL 쌍
명확한 규칙 - 환각을 방지하기 위한 제약사항

특히 "반드시 명시된 테이블만 사용"과 같은 규칙으로 LLM이 존재하지 않는 테이블을 생성하는 것을 방지했다.

4. 자동 스키마 학습

데이터베이스의 모든 테이블 스키마를 자동으로 학습시키는 기능을 구현했다.

def train_on_database_schema(self) -> bool:
    """데이터베이스 스키마를 자동으로 학습"""
    try:
        schemas = db_connection.get_table_schemas()
        
        for table_name, columns in schemas.items():
            # DDL 형식으로 변환
            ddl = f"CREATE TABLE {table_name} (\n"
            column_defs = []
            
            for col in columns:
                col_def = f"  {col['column_name']} {col['column_type']}"
                
                if col['is_nullable'] == 'NO':
                    col_def += " NOT NULL"
                
                if col['column_key'] == 'PRI':
                    col_def += " PRIMARY KEY"
                
                if col['extra']:
                    col_def += f" {col['extra']}"
                
                if col['comment']:
                    col_def += f" COMMENT '{col['comment']}'"
                
                column_defs.append(col_def)
            
            ddl += ",\n".join(column_defs)
            ddl += "\n);"
            
            self.train_on_ddl(ddl)
        
        return True

스키마 정보를 DDL 형식으로 변환하여 ChromaDB에 저장한다. 이를 통해 LLM이 테이블 구조를 정확히 파악할 수 있다.

5. Few-shot Learning

사용자가 질문-SQL 쌍을 직접 학습시킬 수 있는 기능을 제공했다.

def train_on_sql(self, question: str, sql: str) -> bool:
    """질문-SQL 쌍을 학습시킨 (Few-shot learning)"""
    try:
        self.vanna.train(question=question, sql=sql)
        return True
    except Exception as e:
        return False

자주 사용되는 복잡한 쿼리나 도메인 특화 쿼리를 학습시키면, 유사한 질문에 대해 더 정확한 SQL을 생성할 수 있다.

6. SQL 후처리

LLM이 생성한 응답에서 순수한 SQL만 추출하는 로직을 구현했다.

def _extract_sql(self, text: str) -> str:
    """응답에서 SQL 추출"""
    import re
    
    # 마크다운 코드 블록 제거
    text = re.sub(r'```sql\n?', '', text)
    text = re.sub(r'```\n?', '', text)
    
    # 앞뒤 공백 제거
    text = text.strip()
    
    # SQL 키워드로 시작하는 라인만 추출
    lines = text.split('\n')
    sql_lines = []
    for line in lines:
        line = line.strip()
        if any(line.upper().startswith(kw) for kw in ['SELECT', 'INSERT', 'UPDATE', 'DELETE']):
            sql_lines.append(line)
        elif sql_lines:
            sql_lines.append(line)
    
    if sql_lines:
        return ' '.join(sql_lines)
    
    return text

LLM이 종종 마크다운 코드 블록이나 설명 텍스트를 포함하여 응답하기 때문에, 이를 제거하고 순수한 SQL만 추출했다.

API 설계

RESTful API는 FastAPI로 구현했다. 주요 엔드포인트는 다음과 같다.

1. SQL 생성 (실행 없이)

@router.post("/generate-sql", response_model=SQLResponse)
async def generate_sql(request: QuestionRequest):
    """자연어 질문으로부터 SQL을 생성합니다."""
    try:
        start_time = time.time()
        sql = sql_generator.generate_sql(request.question)
        execution_time = time.time() - start_time
        
        return SQLResponse(
            question=request.question,
            sql=sql,
            execution_time=execution_time
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

사용자가 생성된 SQL을 검토한 후 직접 실행하고 싶을 때 사용한다.

2. SQL 생성 및 실행

@router.post("/execute", response_model=QueryResult)
async def execute_query(request: QuestionRequest):
    """자연어 질문으로부터 SQL을 생성하고 실행하여 결과를 반환합니다."""
    try:
        result = sql_generator.generate_and_execute(request.question)
        
        return QueryResult(
            question=result["question"],
            sql=result["sql"],
            data=result["data"],
            row_count=result["row_count"],
            execution_time=result["execution_time"]
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

SQL 생성과 실행을 한 번에 처리한다.

3. 스키마 학습

@router.post("/train/schema")
async def train_schema():
    """데이터베이스 스키마를 자동으로 학습합니다."""
    try:
        result = vanna_trainer.train_from_database()
        
        if result["status"] == "error":
            raise HTTPException(status_code=500, detail=result["message"])
        
        return result
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

4. 예제 학습

@router.post("/train/examples")
async def train_examples(request: TrainingRequest):
    """질문-SQL 쌍을 학습시켜 Few-shot learning을 수행합니다."""
    try:
        results = []
        for example in request.examples:
            success = vanna_trainer.train_question_sql(
                question=example.question,
                sql=example.sql
            )
            results.append({
                "question": example.question,
                "success": success
            })
        
        return {
            "status": "success",
            "trained_count": len([r for r in results if r["success"]]),
            "total_count": len(results),
            "details": results
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

개발 과정의 고민

1. 상용 API vs 오픈소스 모델

처음에는 OpenAI API를 사용하려 했다. 하지만 비용 문제와 데이터 프라이버시를 고려하여 오픈소스 모델을 선택했다.

장점:

비용 절감 (무제한 사용 가능)
데이터 외부 유출 없음
커스터마이징 가능

단점:

초기 설정 복잡도
하드웨어 요구사항 (GPU 권장)
모델 성능이 GPT-4보다 낮을 수 있음

Ollama를 사용함으로써 로컬에서 Llama 3.1, Mistral 등의 오픈소스 모델을 간편하게 실행할 수 있었다.

2. RAG의 중요성

처음에는 RAG 없이 스키마 정보만 프롬프트에 포함시켰다. 하지만 복잡한 조인이나 집계 쿼리에서 정확도가 떨어졌다.

RAG를 도입한 후:

유사한 예제를 참고하여 더 정확한 쿼리 생성
Few-shot learning으로 도메인 특화 쿼리 개선
컬럼명 오타나 존재하지 않는 테이블 사용 감소

ChromaDB는 벡터 검색이 빠르고 설정이 간단하여 RAG 구현에 적합했다.

3. 환각 방지

LLM은 종종 존재하지 않는 테이블이나 컬럼을 사용한다. 이를 방지하기 위해:

명시적 스키마 제공 - 사용 가능한 테이블과 컬럼을 명확히 나열
엄격한 규칙 - "명시된 테이블만 사용하라"는 지시
SQL 검증 - 생성된 SQL을 실행 전에 구문 검사
에러 피드백 - 실패한 쿼리를 학습 데이터로 활용

4. 프롬프트 최적화

프롬프트 설계가 SQL 품질에 가장 큰 영향을 미쳤다. 여러 번의 실험을 통해:

규칙의 명시성 - 애매한 표현 대신 구체적인 지시
예제 품질 - 잘못된 예제는 오히려 성능을 낮춤
적절한 컨텍스트 - 너무 많은 정보는 혼란을 초래

최종적으로 스키마 + 상위 3개 예제 조합이 최적이었다.

5. 모델 선택

여러 오픈소스 모델을 테스트했다.

모델 크기 속도 SQL 정확도 비고

llama3.1:8b	4.7GB	빠름	우수	추천
mistral:7b	4.1GB	매우 빠름	양호	간단한 쿼리용
llama3.1:70b	40GB	느림	매우 우수	GPU 필수
codellama:13b	7.4GB	보통	우수	코드 특화

llama3.1:8b가 속도와 정확도의 균형이 가장 좋아 기본 모델로 선택했다.

성능 최적화

1. 비동기 처리

FastAPI의 async/await를 활용하여 동시 요청 처리 성능을 개선했다.

2. 타임아웃 설정

Ollama 요청에 120초 타임아웃을 설정하여 무한 대기를 방지했다.

향후 개선 계획

쿼리 히스토리 관리

실행된 쿼리와 결과를 데이터베이스에 저장하여 재사용하고 분석할 수 있도록 개선할 예정이다.

결과 시각화

JSON 결과를 차트나 그래프로 자동 시각화하는 기능을 추가할 계획이다.

멀티 데이터베이스 지원

현재는 MariaDB만 지원하지만, PostgreSQL, MySQL, Oracle 등 다양한 데이터베이스를 지원하도록 확장할 예정이다.

보안 강화

SQL 인젝션 방지
읽기 전용 쿼리 제한
사용자 인증 및 권한 관리
쿼리 실행 로그 감사

Fine-tuning

도메인 특화 데이터로 오픈소스 모델을 Fine-tuning하여 정확도를 더 높일 수 있을 것 같다.

결론

sQuiry를 개발하면서 오픈소스 LLM과 RAG를 활용한 실용적인 서비스 구축의 가능성을 확인했다.

상용 API 대신 로컬 LLM을 사용함으로써 비용을 절감하고 데이터 프라이버시를 지킬 수 있었다.

특히 RAG를 통한 Few-shot learning이 SQL 생성 정확도에 큰 영향을 미친다는 것을 알게 되었다.

단순히 LLM을 호출하는 것이 아니라, 적절한 컨텍스트를 제공하는 것이 핵심이다.

프롬프트 엔지니어링에 대해서도 많이 배울 수 있었다. 단순히 페르소나를 부여하는 것 뿐만 아니라, AI가 데이터를 다루는 방식이나 속도에도 큰 영향을 끼친다는 것을 배웠다. 생각보다 훨씬 중요한 부분이었다.

앞으로도 지속적으로 기능을 개선하고, 다양한 도메인에 적용할 수 있는 범용적인 시스템으로 발전시킬 계획이다.

참고 자료

GitHub Repository:
Vanna.ai Documentation: https://vanna.ai/docs
Ollama: https://ollama.ai
ChromaDB: https://www.trychroma.com
FastAPI: https://fastapi.tiangolo.com
Huggingface: https://huggingface.co/models

SpeakSH: Claude AI로 서버 관리 (시나리오)

블체. — Sat, 7 Feb 2026 00:10:22 +0900

서론

이 글은 SpeakSH를 어떻게 사용할 수 있는지에 대한 몇 가지 시나리오를 만들어서 공유하는 것에 목적을 둔다.

테스트해 볼 시나리오는 다음과 같다.

개발환경 구축
보안상태 점검
서비스 제거
로그 확인

이전글: https://egg-stone.tistory.com/41

개발환경 구축

보안상태 점검

서비스 제거

로그확인

로그확인은 웃긴게, 로그를 보여달라니까 로그의 내용을 요약정리해서 보여줬다.

엉뚱한 답이긴한데, 실제 로그가 패키지 설치로그이기에 별 의미가 없다고 생각했는지 가독성 좋게 정리해서 출력하는 모습을 보여줬다.

SpeakSH: Claude Desktop 연동

블체. — Fri, 6 Feb 2026 00:10:56 +0900

서론

이 글은 SpeakSH를 실제로 Claude Desktop 에 연동하는 방법에 대해서 다룬다.

이전글: https://egg-stone.tistory.com/40

1. MCP 등록

좌측 하단 "설정" 아이콘을 클릭하면 연동 설정창이 뜨게된다.

"Claude Desktop 연동" 을 클릭하면 진행여부를 체크한다. 더 진행해보면..

claude_desktop_config.json 에 "speaksh" 가 성공적으로 등록된 것을 확인할 수 있다.

이제 claude desktop 에서도 확인을 해보자.

연결 성공!

2. 서버추가

SpeakSH의 서버 연결 테스트를 위해서 테스트서버를 만들어놨다.

이제 사이드바 하단에 있는 "서버 추가" 버튼을 클릭해서 해당 서버에 대한 정보를 입력 및 등록해보자.

이제 Claude Desktop 에서 서버가 추가되었는지 확인을 해보고 연결까지 진행해보겠다.

이렇게 MCP 등록 및 서버 등록/연결 과정까지 완료했다.

이제 실제로 Claude Desktop 을 통해서 서버에 대한 작업을 할 수 있게 되었다.

다음 글에서는 내가 정의해본 시나리오 몇 가지를 진행해보려고 한다.