Data Innovator

Serena Ubuntu

Wed, 15 Apr 2026 00:00:00 +0000

Serena MCP Server 설치 가이드 (Ubuntu)

사전 요구사항

Node.js 18 이상
Claude Code CLI 설치됨
uv 패키지 매니저

uv 설치 (없으면)

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

설치

npm 패키지가 없으므로 GitHub에서 직접 설치합니다.

uvx --from git+https://github.com/oraios/serena serena --help

위 명령으로 정상 동작 확인 후 MCP 등록으로 진행합니다.

Claude Code MCP 등록

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server

연결 확인

claude mcp list

아래처럼 ✓ Connected 가 표시되면 성공입니다:

serena: uvx --from git+https://github.com/oraios/serena serena start-mcp-server - ✓ Connected

제거

claude mcp remove serena

참고

GitHub: https://github.com/oraios/serena
MCP 서버 시작 커맨드는 serena start-mcp-server (단순 serena 또는 serena-mcp-server 는 동작 안 함)

Serena MCP 및 Claude 연동

Sat, 27 Dec 2025 00:00:00 +0000

Serena MCP 연동 가이드

Claude Code CLI 및 Claude Desktop에서 Serena를 MCP 서버로 연동하여 시맨틱 코드 분석 기능 활용하기

1. Serena 개요

Serena란?

Serena는 Language Server 통합을 통해 시맨틱 코드 이해와 지능적 편집 기능을 제공하는 오픈소스 AI 코딩 에이전트 툴킷입니다.

주요 기능

기능	설명
시맨틱 코드 분석	심볼 수준에서 코드 구조와 관계 이해
프로젝트 메모리	`.serena/memories/`에 프로젝트 정보 저장
토큰 절약	전체 파일 대신 필요한 부분만 분석
다국어 지원	TypeScript, JavaScript, Python, Java, C# 등

Claude Code에서 Serena가 필요한 이유

일반 AI는 응답 전에 모든 코드를 읽습니다. Serena는 인덱스를 먼저 생성하여 효율적으로 코드를 분석합니다.

┌─────────────────────────────────────────────────────────────────┐
│                      일반 AI 분석 방식                          │
│  "button.tsx 수정해줘" → button.tsx 파일만 확인                  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    Serena + AI 분석 방식                        │
│  "button.tsx 수정해줘" → 사용 위치, 스타일 정의, 관련 컴포넌트   │
│                         모두 확인 후 일관성 있게 수정            │
└─────────────────────────────────────────────────────────────────┘

2. 사전 요구사항

필수 항목

uv (Python 패키지 관리자)
Claude Code CLI 또는 Claude Desktop
Git (로컬 설치 시)

uv 설치

# macOS (Homebrew)
brew install uv

# 또는 공식 설치 스크립트
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 확인

uv --version

3. Serena 설치

방법 A: uvx로 직접 실행 (권장)

별도 설치 없이 바로 사용할 수 있습니다. 대부분의 사용자에게 권장합니다.

# 별도 설치 불필요, MCP 설정 시 자동 다운로드 및 캐시
uvx --from git+https://github.com/oraios/serena serena-mcp-server

장점:

설치 과정 불필요
자동 업데이트 (최신 버전 반영)
캐시되어 매번 다운로드하지 않음 (~/.cache/uv/)
관리 부담 없음

참고: Claude Code CLI나 Claude Desktop과 함께 MCP 모드로 사용할 경우, Serena는 도구만 제공하고 LLM 호출은 Claude가 담당합니다. 따라서 별도의 API 키 설정이 필요 없습니다.

방법 B: 로컬 설치

Serena를 단독 에이전트(Agno 모드)로 사용하거나, 설정 커스터마이징이 필요한 경우에만 권장합니다.

# 1. 원하는 위치에 클론
cd ~/workspace
git clone https://github.com/oraios/serena.git
cd serena

# 2. 설정 파일 복사 (선택)
cp src/serena/resources/serena_config.template.yml serena_config.yml

# 3. 환경 변수 설정 (Agno 모드 사용 시에만 필요)
# .env 파일에 API 키 설정

장점:

.env, 설정 파일 커스터마이징 가능
Agno 모드로 Serena 단독 에이전트 실행 가능
검증된 버전 유지 가능

언제 필요한가?

Serena를 단독 에이전트로 사용할 때 (API 키 필요)
serena_config.yml 커스터마이징이 필요할 때
특정 버전을 고정해서 사용해야 할 때

4. Claude Code CLI 연동

방법 A: uvx로 직접 실행 (권장)

claude mcp add serena --scope user -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd

방법 B: 로컬 설치 버전 사용

로컬에 Serena를 설치한 경우에만 사용:

claude mcp add serena --scope user -- uv run --directory ~/workspace/serena serena start-mcp-server --context=claude-code --project-from-cwd

설정 파일 직접 편집

~/.claude.json 파일:

uvx 직접 실행 (권장):

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--context=claude-code",
        "--project-from-cwd"
      ]
    }
  }
}

로컬 설치 버전:

{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/사용자명/workspace/serena",
        "serena",
        "start-mcp-server",
        "--context=claude-code",
        "--project-from-cwd"
      ]
    }
  }
}

연결 확인

claude mcp list

출력 예시:

serena: Scope: User
  Type: stdio
  Command: uv
  Args: run, --directory, /Users/사용자명/workspace/serena, serena, start-mcp-server, --context=claude-code, --project-from-cwd

5. Claude Desktop 연동

설정 파일 위치

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 파일 편집

uvx 직접 실행 (권장):

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server"
      ]
    }
  }
}

로컬 설치 버전:

{
  "mcpServers": {
    "serena": {
      "command": "/Users/사용자명/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/사용자명/workspace/serena",
        "serena",
        "start-mcp-server",
        "--context",
        "ide"
      ]
    }
  }
}

uv 경로 확인

Claude Desktop은 쉘 환경을 상속하지 않을 수 있으므로 절대 경로 사용 권장:

which uv
# 예: /Users/사용자명/.local/bin/uv 또는 /opt/homebrew/bin/uv

재시작

설정 저장 후 Claude Desktop 완전 종료 후 재시작 필요

6. 설정 옵션 상세

–context 옵션

값	용도	설명
`claude-code`	Claude Code CLI	CLI 전용 최적화
`ide`	IDE 통합 (Desktop, JetBrains 등)	도구 중복 방지
미지정	범용	모든 도구 활성화

–project 관련 옵션

옵션	설명
`--project-from-cwd`	현재 디렉토리를 프로젝트로 인식 (CLI 권장)
`--project /path/to/project`	특정 경로를 프로젝트로 지정

Scope 옵션 (Claude Code CLI)

Scope	저장 위치	용도
`user`	`~/.claude.json`	모든 프로젝트에서 사용
`project`	프로젝트/.mcp.json	해당 프로젝트만
(기본)	프로젝트/.claude/	해당 프로젝트만

7. 사용 예시

기본 사용

cd ~/workspace/my-project
claude

Claude에게:

이 프로젝트의 구조를 분석해줘

Serena가 자동으로:

프로젝트 인덱싱
.serena/memories/에 프로젝트 정보 저장
시맨틱 분석 결과 제공

시맨틱 코드 분석

# 심볼 찾기
UserService 클래스의 모든 메서드를 보여줘

# 참조 찾기
login 함수를 호출하는 모든 코드를 찾아줘

# 관계 분석
이 클래스들 간의 의존성을 설명해줘

리팩토링

# 컴포넌트 분리
UserProfile 컴포넌트가 너무 크니 적절히 분리해줘

# 일관성 있는 수정
다크 모드 기능을 추가하고 모든 컴포넌트에 일관되게 적용해줘

여러 프로젝트 연동 분석

# workspace 전체를 분석하려면 workspace에서 실행
cd ~/workspace
claude

# 특정 프로젝트만 분석하려면 해당 폴더에서 실행
cd ~/workspace/vpy-util
claude

8. 트러블슈팅

프로젝트에서 Serena가 인식되지 않음

증상: claude mcp list에서 serena가 보이지만, 특정 프로젝트에서 Serena 도구가 작동하지 않음

원인: ~/.claude.json에 프로젝트별 mcpServers 설정이 있으면, 해당 프로젝트에서는 프로젝트 설정이 우선되어 전역 mcpServers가 무시됩니다.

문제가 되는 구조:

{
  "mcpServers": {
    "serena": { ... }  // ← 전역 설정 (무시됨)
  },
  "projects": {
    "/Users/사용자명/workspace/my-project": {
      "mcpServers": {
        // ← 비어있거나 serena가 없으면 해당 프로젝트에서 serena 사용 불가
      }
    }
  }
}

해결 방법 1: 프로젝트별 mcpServers 섹션 제거 (권장)

프로젝트마다 다른 MCP 서버가 필요 없다면, projects 내의 mcpServers를 삭제:

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"]
    },
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--context=claude-code",
        "--project-from-cwd"
      ]
    }
  },
  "projects": {
    "/Users/사용자명/workspace/my-project": {
      // mcpServers 섹션 제거 → 전역 설정 사용
    }
  }
}

해결 방법 2: 각 프로젝트에 serena 추가

프로젝트별 설정을 유지해야 한다면, 각 프로젝트에 serena를 수동으로 추가:

{
  "mcpServers": {
    "serena": { ... }
  },
  "projects": {
    "/Users/사용자명/workspace/my-project": {
      "mcpServers": {
        "serena": {
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/oraios/serena",
            "serena",
            "start-mcp-server",
            "--context=claude-code",
            "--project-from-cwd"
          ]
        }
      }
    }
  }
}

참고: --scope user로 MCP를 추가해도 기존 프로젝트별 설정에는 자동으로 추가되지 않습니다. 새 프로젝트를 생성해도 마찬가지입니다.

MCP 서버 연결 실패

확인 사항:

# uv 설치 확인
uv --version

# 로컬 설치 경로 확인
ls ~/workspace/serena

# MCP 목록 확인
claude mcp list

해결:

# MCP 제거 후 재추가
claude mcp remove serena
claude mcp add serena --scope user -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd

Claude Desktop에서 Serena 인식 안 됨

원인: 환경 변수 미상속

해결: 설정 파일에서 uv 절대 경로 사용

{
  "mcpServers": {
    "serena": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/Users/사용자명/workspace/serena", "serena", "start-mcp-server"]
    }
  }
}

Language Server 관련 오류

일부 언어 서버는 추가 환경 변수가 필요할 수 있습니다:

{
  "mcpServers": {
    "serena": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/사용자명/workspace/serena", "serena", "start-mcp-server"],
      "env": {
        "DOTNET_ROOT": "/opt/homebrew/Cellar/dotnet/9.0.8/libexec"
      }
    }
  }
}

로컬 버전 업데이트

cd ~/workspace/serena
git pull

9. 참고 자료

공식 문서

설정 파일 위치 요약

앱	설정 파일 위치
Claude Code CLI	`~/.claude.json`
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`

JetBrains MCP와 함께 사용

Serena와 JetBrains MCP를 함께 사용하면 더욱 강력합니다:

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"]
    },
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--context=claude-code",
        "--project-from-cwd"
      ]
    }
  }
}

MCP 서버	역할
JetBrains	IDE 제어 (실행, 리팩토링, 디버깅)
Serena	시맨틱 코드 분석, 심볼 탐색, 프로젝트 이해

부록: 빠른 시작 체크리스트

# 1. uv 설치 확인
uv --version

# 2. Claude Code CLI에 MCP 추가 (uvx 방식)
claude mcp add serena --scope user -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd

# 3. 확인
claude mcp list

# 4. 테스트
cd ~/workspace/my-project
claude
# → "이 프로젝트 구조를 분석해줘"

문서 작성일: 2025년 12월 Serena MCP 연동 가이드 v1.0

Claude CLI 설치 및 MCP 서버 설정

Sat, 27 Dec 2025 00:00:00 +0000

Claude Code CLI + JetBrains IDE 연동 가이드

Claude Max 구독을 활용하여 JetBrains IDE(IntelliJ, PyCharm 등)를 제어하는 완벽 가이드

1. 개요

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                     Claude Code CLI                             │
│                   (MCP 클라이언트 역할)                          │
│                   Claude Max 구독 사용                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ MCP 프로토콜
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  JetBrains MCP Server                           │
│                   (MCP 서버 역할)                                │
│         PyCharm, IntelliJ IDEA, WebStorm 등 내장                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     IDE 기능 제어                                │
│  파일 편집, 리팩토링, 테스트 실행, 디버깅, Run Configuration 등  │
└─────────────────────────────────────────────────────────────────┘

이 조합의 장점

항목	장점
비용 효율	Claude Max 구독 직접 사용 (JetBrains AI 별도 비용 없음)
모델 선택	Claude Opus, Sonnet 등 원하는 모델 선택 가능
IDE 완전 제어	터미널에서 IDE의 모든 기능 사용 가능
터미널 친화적	개발 워크플로우에 자연스럽게 통합

2. 사전 요구사항

필수 항목

Claude Max 구독 (또는 Claude Pro / API 키)
Node.js 18+ 설치
JetBrains IDE 2025.2 버전 이상
- IntelliJ IDEA
- PyCharm
- WebStorm
- GoLand
- 기타 IntelliJ 기반 IDE

Node.js 설치 확인

node --version
# v18.0.0 이상이어야 함

npm --version

Node.js가 없다면:

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
sudo apt-get install nodejs npm

# Windows (Chocolatey)
choco install nodejs

3. Claude Code CLI 설치

3.1 전역 설치

npm install -g @anthropic-ai/claude-code

3.2 설치 확인

which claude
claude --version

3.3 첫 실행 및 인증

# 프로젝트 디렉토리로 이동
cd ~/your-project

# Claude Code 실행
claude

첫 실행 시 브라우저가 열리며 Claude 계정 인증을 요청합니다. Claude Max 계정으로 로그인하면 구독이 자동으로 연결됩니다.

3.4 인증 상태 확인

claude /status

4. JetBrains MCP 서버 활성화

JetBrains IDE 2025.2 버전부터 MCP 서버가 내장되어 있습니다.

4.1 IDE에서 MCP 서버 활성화

JetBrains IDE 실행 (PyCharm, IntelliJ 등)
Settings/Preferences 열기
- macOS: Cmd + ,
- Windows/Linux: Ctrl + Alt + S
Tools → MCP Server 이동
Enable MCP Server 체크박스 활성화
Apply 클릭

4.2 자동 설정 (권장)

Settings → Tools → MCP Server 화면에서:

Clients Auto-Configuration 섹션 확인
Claude Code 옆의 Auto-Configure 버튼 클릭
자동으로 Claude Code의 설정 파일이 업데이트됨

4.3 Brave Mode 설정 (선택)

매번 확인 없이 명령을 실행하려면:

Settings → Tools → MCP Server
Command execution 섹션에서
Run shell commands or run configurations without confirmation (brave mode) 활성화
Apply 클릭

⚠️ 주의: Brave Mode는 편리하지만, Claude가 확인 없이 명령을 실행할 수 있으므로 신중하게 사용하세요.

5. Claude Code CLI와 JetBrains 연결

5.1 MCP 서버 추가 (CLI 방식)

claude mcp add jetbrains -- npx -y @jetbrains/mcp-proxy

5.2 User Scope로 추가 (모든 프로젝트에서 사용)

claude mcp add jetbrains --scope user -- npx -y @jetbrains/mcp-proxy

5.3 설정 파일 직접 편집 (대안)

~/.claude.json 파일을 직접 편집:

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"]
    }
  }
}

5.4 특정 IDE 포트 지정 (여러 IDE 사용 시)

여러 JetBrains IDE를 동시에 사용하는 경우:

{
  "mcpServers": {
    "pycharm": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"],
      "env": {
        "IDE_PORT": "63342"
      }
    },
    "intellij": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"],
      "env": {
        "IDE_PORT": "63343"
      }
    }
  }
}

IDE 포트 확인: Settings → Build, Execution, Deployment → Debugger → Built-in Server Port

6. 연결 확인 및 테스트

6.1 MCP 서버 목록 확인

claude mcp list

출력 예시:

jetbrains: Scope: User
  Type: stdio
  Command: npx
  Args: -y, @jetbrains/mcp-proxy

6.2 연결 테스트

JetBrains IDE가 실행 중인지 확인
프로젝트 디렉토리에서 Claude Code 실행:

cd ~/your-project
claude

Claude에게 테스트 명령:

현재 IDE에서 열린 파일 목록을 보여줘

6.3 IDE 내 터미널에서 연결 (대안)

JetBrains IDE의 내장 터미널에서:

claude

터미널에서 /ide 명령으로 IDE와 연결:

/ide

7. 실제 사용 예시

7.1 파일 작업

# 파일 읽기
현재 열린 파일 내용을 보여줘

# 파일 수정
ByteConv 클래스의 docstring을 업데이트해줘

# 새 파일 생성
test_singleton.py 테스트 파일을 생성해줘

7.2 코드 실행 및 테스트

# 테스트 실행
PyCharm에서 test_byte_conv.py 실행해줘

# 특정 테스트 메서드 실행
TestByteConvSingle 클래스의 test_int_conversion 테스트만 실행해줘

# Run Configuration 실행
'Main' Run Configuration을 실행해줘

7.3 리팩토링

# 리팩토링 제안
이 클래스를 리팩토링하고 diff로 보여줘

# 변수명 변경
`data` 변수를 `byte_data`로 이름 변경해줘

# 메서드 추출
이 코드 블록을 별도 메서드로 추출해줘

7.4 디버깅 및 분석

# 린트 에러 확인
현재 파일의 lint 에러를 수정해줘

# 프로젝트 구조 분석
이 프로젝트의 구조를 설명해줘

# 의존성 확인
이 모듈의 의존성을 분석해줘

7.5 Git 작업

# 변경사항 확인
Git 변경사항을 요약해줘

# 커밋 메시지 생성
현재 변경사항에 대한 커밋 메시지를 작성해줘

8. 추가 MCP 서버 설정 (선택)

8.1 GitHub 연동

# 환경변수 설정 (.zshrc 또는 .bashrc에 추가)
export GITHUB_TOKEN=ghp_your_token_here

# MCP 서버 추가
claude mcp add github --scope user -- npx -y @modelcontextprotocol/server-github

8.2 Filesystem 접근 확장

claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/projects

8.3 Memory (대화 기억)

claude mcp add memory --scope user -- npx -y @modelcontextprotocol/server-memory

8.4 전체 설정 예시 (~/.claude.json)

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

9. 트러블슈팅

9.1 “Claude Code not found” 오류

원인: Claude Code CLI가 PATH에 없음

해결:

# npm 전역 경로 확인
npm config get prefix

# PATH에 추가 (.zshrc 또는 .bashrc)
export PATH="$PATH:$(npm config get prefix)/bin"

# 쉘 재시작
source ~/.zshrc

9.2 JetBrains MCP 서버 연결 실패

확인 사항:

JetBrains IDE가 실행 중인지 확인
MCP Server가 활성화되어 있는지 확인 (Settings → Tools → MCP Server)
IDE를 재시작

포트 충돌 시:

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"],
      "env": {
        "IDE_PORT": "63342",
        "HOST": "127.0.0.1"
      }
    }
  }
}

9.3 Node.js 버전 문제

오류: MCP Proxy가 작동하지 않음

해결:

# Node.js 버전 확인
node --version

# 18 미만이면 업그레이드
brew upgrade node
# 또는
nvm install 18
nvm use 18

9.4 WSL 환경 설정

WSL에서 사용 시 추가 설정:

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@jetbrains/mcp-proxy"],
      "env": {
        "IDE_PORT": "63342",
        "HOST": "호스트_Windows_IP"
      }
    }
  }
}

Windows IP 확인:

cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

9.5 MCP 서버 제거 및 재설정

# 서버 제거
claude mcp remove jetbrains

# 다시 추가
claude mcp add jetbrains --scope user -- npx -y @jetbrains/mcp-proxy

# 확인
claude mcp list

10. 참고 자료

공식 문서

MCP 서버 디렉토리

MCP.so - MCP 서버 검색
Smithery.ai - MCP 서버 디렉토리
GitHub MCP Servers - 공식 MCP 서버 레포

파일	위치	용도
Claude Code CLI 설정	`~/.claude.json`	CLI의 MCP 서버 설정
프로젝트별 MCP 설정	`프로젝트/.mcp.json`	프로젝트 특화 MCP 설정
Claude Desktop 설정	`~/Library/Application Support/Claude/claude_desktop_config.json`	Desktop 앱 MCP 설정 (별개)

부록: 빠른 시작 체크리스트

# 1. Node.js 확인
node --version  # 18+ 필요

# 2. Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code

# 3. 설치 확인
claude --version

# 4. JetBrains IDE에서 MCP 서버 활성화
# Settings → Tools → MCP Server → Enable MCP Server ✓

# 5. Claude Code에 JetBrains 연결
claude mcp add jetbrains --scope user -- npx -y @jetbrains/mcp-proxy

# 6. 연결 확인
claude mcp list

# 7. 테스트 (IDE 실행 상태에서)
cd ~/your-project
claude
# → "현재 IDE에서 열린 파일을 보여줘"

문서 작성일: 2025년 12월 Claude Code CLI + JetBrains MCP 연동 가이드 v1.0

AutoEncode 기반 시계열데이터 이상 진단

Sat, 29 Nov 2025 00:00:00 +0000

구조 설명 핵심 컴포넌트:

AnomalyDetectorConfig - 하이퍼파라미터 관리 (dataclass 활용) LSTMAutoEncoder - LSTM 기반 AutoEncoder

Encoder: 시퀀스 → 잠재 벡터 압축 Decoder: 잠재 벡터 → 시퀀스 재구성

AnomalyDetector - 이상 탐지기 래퍼 클래스

fit(): 정상 데이터로 학습 predict(): 재구성 오차 기반 이상 탐지 save()/load(): 모델 저장/로드

이상 탐지 원리:

정상 데이터로 학습된 AutoEncoder는 정상 패턴을 잘 재구성 이상 데이터는 재구성 오차가 높음 백분위 기반 임계값으로 이상 여부 판정

확장 포인트:

input_dim 조정으로 다변량 시계열 지원 Convolutional AutoEncoder로 변경 가능 Variational AutoEncoder (VAE)로 확장 가능 Attention 메커니즘 추가 가능

””” Time Series Anomaly Detection using AutoEncoder (PyTorch)

기본 구조:

AutoEncoder 모델 (LSTM 기반)
데이터 전처리 및 시퀀스 생성
학습 및 평가
이상 탐지 (재구성 오차 기반) “””

import numpy as np import torch import torch.nn as nn from torch.utils.data import Dataset, DataLoader from typing import Tuple, Optional from dataclasses import dataclass

@dataclass class AnomalyDetectorConfig: “"”AutoEncoder 설정””” input_dim: int = 1 # 입력 feature 수 hidden_dim: int = 64 # LSTM hidden 차원 latent_dim: int = 32 # 잠재 공간 차원 num_layers: int = 2 # LSTM 레이어 수 sequence_length: int = 50 # 시퀀스 길이 dropout: float = 0.2 # 드롭아웃 비율 threshold_percentile: float = 95.0 # 이상 탐지 임계값 백분위

class TimeSeriesDataset(Dataset): “"”시계열 데이터셋”””

def __init__(self, data: np.ndarray, sequence_length: int):
    self.data = torch.FloatTensor(data)
    self.sequence_length = sequence_length

def __len__(self) -> int:
    return len(self.data) - self.sequence_length + 1

def __getitem__(self, idx: int) -> torch.Tensor:
    return self.data[idx:idx + self.sequence_length]

class Encoder(nn.Module): “"”LSTM 기반 Encoder”””

def __init__(self, config: AnomalyDetectorConfig):
    super().__init__()
    self.lstm = nn.LSTM(
        input_size=config.input_dim,
        hidden_size=config.hidden_dim,
        num_layers=config.num_layers,
        batch_first=True,
        dropout=config.dropout if config.num_layers > 1 else 0
    )
    self.fc = nn.Linear(config.hidden_dim, config.latent_dim)

def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, Tuple]:
    # x: (batch, seq_len, input_dim)
    lstm_out, hidden = self.lstm(x)
    # 마지막 시점의 출력을 잠재 공간으로 매핑
    latent = self.fc(lstm_out[:, -1, :])
    return latent, hidden

class Decoder(nn.Module): “"”LSTM 기반 Decoder”””

def __init__(self, config: AnomalyDetectorConfig):
    super().__init__()
    self.sequence_length = config.sequence_length
    self.hidden_dim = config.hidden_dim
    
    self.fc = nn.Linear(config.latent_dim, config.hidden_dim)
    self.lstm = nn.LSTM(
        input_size=config.hidden_dim,
        hidden_size=config.hidden_dim,
        num_layers=config.num_layers,
        batch_first=True,
        dropout=config.dropout if config.num_layers > 1 else 0
    )
    self.output = nn.Linear(config.hidden_dim, config.input_dim)

def forward(self, latent: torch.Tensor) -> torch.Tensor:
    # latent: (batch, latent_dim)
    batch_size = latent.size(0)
    
    # 잠재 벡터를 시퀀스 길이만큼 반복
    hidden_init = self.fc(latent)
    decoder_input = hidden_init.unsqueeze(1).repeat(1, self.sequence_length, 1)
    
    lstm_out, _ = self.lstm(decoder_input)
    reconstructed = self.output(lstm_out)
    return reconstructed

class LSTMAutoEncoder(nn.Module): “"”LSTM AutoEncoder for Time Series Anomaly Detection”””

def __init__(self, config: AnomalyDetectorConfig):
    super().__init__()
    self.config = config
    self.encoder = Encoder(config)
    self.decoder = Decoder(config)

def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
    latent, _ = self.encoder(x)
    reconstructed = self.decoder(latent)
    return reconstructed, latent

def encode(self, x: torch.Tensor) -> torch.Tensor:
    latent, _ = self.encoder(x)
    return latent

def decode(self, latent: torch.Tensor) -> torch.Tensor:
    return self.decoder(latent)

class AnomalyDetector: “"”시계열 이상 탐지기”””

def __init__(
    self,
    config: Optional[AnomalyDetectorConfig] = None,
    device: Optional[str] = None
):
    self.config = config or AnomalyDetectorConfig()
    self.device = device or ('cuda' if torch.cuda.is_available() else 'cpu')
    self.model = LSTMAutoEncoder(self.config).to(self.device)
    self.threshold: Optional[float] = None
    self.train_losses: list = []

def _create_dataloader(
    self,
    data: np.ndarray,
    batch_size: int,
    shuffle: bool = True
) -> DataLoader:
    """데이터로더 생성"""
    # 데이터 정규화
    if data.ndim == 1:
        data = data.reshape(-1, 1)
    
    dataset = TimeSeriesDataset(data, self.config.sequence_length)
    return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle)

def fit(
    self,
    train_data: np.ndarray,
    epochs: int = 100,
    batch_size: int = 32,
    learning_rate: float = 1e-3,
    validation_data: Optional[np.ndarray] = None,
    verbose: bool = True
) -> 'AnomalyDetector':
    """모델 학습"""
    train_loader = self._create_dataloader(train_data, batch_size, shuffle=True)
    
    criterion = nn.MSELoss()
    optimizer = torch.optim.Adam(self.model.parameters(), lr=learning_rate)
    scheduler = torch.optim.lr_scheduler.ReduceLROnPlateau(
        optimizer, mode='min', factor=0.5, patience=10
    )
    
    self.model.train()
    self.train_losses = []
    
    for epoch in range(epochs):
        epoch_loss = 0.0
        
        for batch in train_loader:
            batch = batch.to(self.device)
            
            optimizer.zero_grad()
            reconstructed, _ = self.model(batch)
            loss = criterion(reconstructed, batch)
            loss.backward()
            optimizer.step()
            
            epoch_loss += loss.item()
        
        avg_loss = epoch_loss / len(train_loader)
        self.train_losses.append(avg_loss)
        scheduler.step(avg_loss)
        
        if verbose and (epoch + 1) % 10 == 0:
            print(f"Epoch [{epoch+1}/{epochs}], Loss: {avg_loss:.6f}")
    
    # 학습 데이터로 임계값 설정
    self._set_threshold(train_data)
    
    return self

def _set_threshold(self, data: np.ndarray) -> None:
    """재구성 오차 기반 임계값 설정"""
    reconstruction_errors = self._compute_reconstruction_error(data)
    self.threshold = np.percentile(
        reconstruction_errors,
        self.config.threshold_percentile
    )

def _compute_reconstruction_error(self, data: np.ndarray) -> np.ndarray:
    """재구성 오차 계산"""
    self.model.eval()
    
    if data.ndim == 1:
        data = data.reshape(-1, 1)
    
    loader = self._create_dataloader(data, batch_size=64, shuffle=False)
    errors = []
    
    with torch.no_grad():
        for batch in loader:
            batch = batch.to(self.device)
            reconstructed, _ = self.model(batch)
            
            # 시퀀스별 MSE 계산
            mse = torch.mean((batch - reconstructed) ** 2, dim=(1, 2))
            errors.extend(mse.cpu().numpy())
    
    return np.array(errors)

def predict(self, data: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
    """
    이상 탐지 수행
    
    Returns:
        anomalies: 이상 여부 (True/False)
        scores: 이상 점수 (재구성 오차)
    """
    if self.threshold is None:
        raise RuntimeError("모델이 학습되지 않았습니다. fit()을 먼저 호출하세요.")
    
    scores = self._compute_reconstruction_error(data)
    anomalies = scores > self.threshold
    
    return anomalies, scores

def save(self, path: str) -> None:
    """모델 저장"""
    torch.save({
        'model_state_dict': self.model.state_dict(),
        'config': self.config,
        'threshold': self.threshold,
    }, path)

def load(self, path: str) -> 'AnomalyDetector':
    """모델 로드"""
    checkpoint = torch.load(path, map_location=self.device)
    self.config = checkpoint['config']
    self.model = LSTMAutoEncoder(self.config).to(self.device)
    self.model.load_state_dict(checkpoint['model_state_dict'])
    self.threshold = checkpoint['threshold']
    return self

============================================================

사용 예제

============================================================

def generate_sample_data( n_samples: int = 1000, anomaly_ratio: float = 0.05 ) -> Tuple[np.ndarray, np.ndarray]: “"”샘플 데이터 생성 (정상 + 이상)””” np.random.seed(42)

# 정상 데이터: 사인파 + 노이즈
t = np.linspace(0, 10 * np.pi, n_samples)
normal_data = np.sin(t) + 0.1 * np.random.randn(n_samples)

# 이상 데이터 주입
n_anomalies = int(n_samples * anomaly_ratio)
anomaly_indices = np.random.choice(n_samples, n_anomalies, replace=False)

data = normal_data.copy()
data[anomaly_indices] += np.random.uniform(2, 4, n_anomalies) * np.sign(np.random.randn(n_anomalies))

# 실제 이상 레이블
labels = np.zeros(n_samples, dtype=bool)
labels[anomaly_indices] = True

return data, labels

def main(): “"”사용 예제””” print(“=” * 60) print(“Time Series Anomaly Detection - AutoEncoder Example”) print(“=” * 60)

# 1. 샘플 데이터 생성
print("\n[1] 샘플 데이터 생성...")
data, true_labels = generate_sample_data(n_samples=2000, anomaly_ratio=0.05)

# 학습/테스트 분할
split_idx = int(len(data) * 0.7)
train_data = data[:split_idx]
test_data = data[split_idx:]
test_labels = true_labels[split_idx:]

print(f"  - 학습 데이터: {len(train_data)} samples")
print(f"  - 테스트 데이터: {len(test_data)} samples")

# 2. 모델 설정 및 학습
print("\n[2] 모델 학습...")
config = AnomalyDetectorConfig(
    input_dim=1,
    hidden_dim=64,
    latent_dim=32,
    sequence_length=50,
    num_layers=2,
    threshold_percentile=95.0
)

detector = AnomalyDetector(config)
detector.fit(
    train_data,
    epochs=50,
    batch_size=32,
    learning_rate=1e-3,
    verbose=True
)

# 3. 이상 탐지
print("\n[3] 이상 탐지 수행...")
anomalies, scores = detector.predict(test_data)

# 시퀀스 길이로 인한 레이블 조정
adjusted_labels = test_labels[config.sequence_length - 1:]

# 4. 결과 출력
print("\n[4] 결과")
print(f"  - 탐지된 이상: {np.sum(anomalies)}")
print(f"  - 실제 이상: {np.sum(adjusted_labels)}")
print(f"  - 임계값: {detector.threshold:.6f}")
print(f"  - 평균 이상 점수: {np.mean(scores):.6f}")
print(f"  - 최대 이상 점수: {np.max(scores):.6f}")

# 5. 모델 저장
print("\n[5] 모델 저장...")
detector.save("anomaly_detector.pt")
print("  - 저장 완료: anomaly_detector.pt")

print("\n" + "=" * 60)
print("완료!")
print("=" * 60)

if name == “main”: main()

MongoDB 유저별 커넥션 전략

Tue, 04 Nov 2025 00:00:00 +0000

MongoDB: 유저별 독립 커넥션 전략 완벽 가이드

작성일: 2025-11-04
버전: 1.0
목적: 유저별 별도 데이터베이스 + 독립 커넥션으로 동시성 문제 해결

1. 문제 정의

1.1 시나리오

유저별로 별도의 데이터베이스 사용
- User A → user_a_db
- User B → user_b_db
- User C → user_c_db
...
- User N → user_n_db (N = 수천~수만)

1.2 단일 연결 방식의 문제점

# ❌ 단일 연결 + useDb() 방식
client = MongoClient("mongodb://localhost:27017/")

# 요청 1: User A
db_a = client['user_a_db']
db_a.posts.insert_one({...})  # 연결 점유

# 요청 2: User B (동시에 발생)
db_b = client['user_b_db']
db_b.posts.insert_one({...})  # 같은 연결 사용 → 대기!

# 요청 3, 4, 5... (동시 요청 증가)
# → 연결 풀이 고갈되고 병목 발생

문제점:

동시성 제한: 하나의 연결에 여러 DB 요청이 순차 처리
연결 풀 경쟁: 모든 유저가 같은 연결 풀 공유
성능 저하: 유저 수가 증가하면 대기 시간 증가
불공평한 리소스 배분: 특정 유저의 무거운 쿼리가 다른 유저 영향

1.3 해결 방안: 유저별 독립 커넥션

# ✅ 유저별 독립 연결 방식
connections = {
    'user_a': MongoClient("mongodb://localhost:27017/", maxPoolSize=10),
    'user_b': MongoClient("mongodb://localhost:27017/", maxPoolSize=10),
    'user_c': MongoClient("mongodb://localhost:27017/", maxPoolSize=10),
}

# 요청 1: User A
client_a = connections['user_a']
db_a = client_a['user_a_db']
db_a.posts.insert_one({...})  # 독립 연결 풀 사용

# 요청 2: User B (동시 발생)
client_b = connections['user_b']
db_b = client_b['user_b_db']
db_b.posts.insert_one({...})  # 독립 연결 풀 사용 → 대기 없음!

장점:

✅ 유저 간 완전한 격리
✅ 동시성 극대화
✅ 특정 유저의 부하가 다른 유저에게 영향 없음
✅ 유저별 연결 풀 크기 조정 가능

2. 연결 방식 비교

2.1 방식 1: 단일 연결 + useDb() ❌

"""
단일 MongoClient로 여러 DB 접근
"""

client = MongoClient("mongodb://localhost:27017/", maxPoolSize=100)

def get_user_db(user_id: str):
    return client[f'user_{user_id}_db']

# 모든 유저가 같은 연결 풀(100개) 공유
db_a = get_user_db('user_a')
db_b = get_user_db('user_b')

장점:

구현 간단
연결 수 적음 (1개 클라이언트)
메모리 사용 적음

단점:

❌ 동시성 제한 (연결 풀 100개를 모든 유저가 공유)
❌ 유저 간 간섭 (한 유저의 슬로우 쿼리가 전체 영향)
❌ 확장성 제한
❌ 유저별 QoS(Quality of Service) 불가능

적합한 경우:

유저 수 < 10
동시 접속 < 50
트래픽 예측 가능
단순한 애플리케이션

2.2 방식 2: 유저별 독립 연결 ✅

"""
유저별 독립 MongoClient 생성
"""

class UserConnectionManager:
    def __init__(self):
        self.connections = {}
        self.lock = threading.RLock()
    
    def get_client(self, user_id: str) -> MongoClient:
        """유저별 독립 클라이언트 반환"""
        with self.lock:
            if user_id not in self.connections:
                self.connections[user_id] = MongoClient(
                    "mongodb://localhost:27017/",
                    maxPoolSize=10  # 유저당 10개 연결
                )
        return self.connections[user_id]
    
    def get_database(self, user_id: str):
        """유저 DB 반환"""
        client = self.get_client(user_id)
        return client[f'user_{user_id}_db']

# 각 유저가 독립 연결 풀(10개) 사용
manager = UserConnectionManager()
db_a = manager.get_database('user_a')  # 독립 연결 풀
db_b = manager.get_database('user_b')  # 독립 연결 풀

장점:

✅ 유저 간 완전한 격리
✅ 동시성 극대화
✅ 유저별 QoS 가능 (Premium 유저는 더 큰 풀)
✅ 특정 유저 장애 격리
✅ 무한 확장 가능

단점:

⚠️ 연결 수 증가 (유저당 N개)
⚠️ 메모리 사용 증가
⚠️ 관리 복잡도 증가

적합한 경우:

유저 수 > 10
동시 접속 > 50
높은 동시성 요구
유저별 SLA 보장 필요

2.3 방식 3: 하이브리드 (그룹별 연결) 🔀

"""
유저를 그룹으로 묶어서 그룹별 연결
"""

def get_user_group(user_id: str) -> str:
    """해시로 유저 그룹 결정"""
    return f"group_{hash(user_id) % 10}"  # 10개 그룹

class GroupConnectionManager:
    def __init__(self):
        self.connections = {}
        # 10개 그룹 = 10개 클라이언트
        for i in range(10):
            self.connections[f'group_{i}'] = MongoClient(
                "mongodb://localhost:27017/",
                maxPoolSize=50  # 그룹당 50개
            )
    
    def get_database(self, user_id: str):
        group = get_user_group(user_id)
        client = self.connections[group]
        return client[f'user_{user_id}_db']

# 유저를 10개 그룹으로 분산
# 총 연결 수 = 10 * 50 = 500

장점:

✅ 적당한 격리 수준
✅ 연결 수 제한 (그룹 수로 제한)
✅ 관리 가능한 복잡도

단점:

⚠️ 같은 그룹 내 유저는 간섭 가능
⚠️ 그룹 불균형 시 문제

적합한 경우:

중간 규모 (100-1000 유저)
연결 수 제한 필요
완벽한 격리는 불필요

2.4 성능 비교

시나리오: 1000명 동시 접속, 각자 1초간 쿼리

┌─────────────────────┬──────────────┬──────────────┬──────────────┐
│      방식            │ 연결 수      │ 처리 시간    │ 격리 수준    │
├─────────────────────┼──────────────┼──────────────┼──────────────┤
│ 단일 연결            │ 100          │ ~10초        │ ⭐           │
│ (maxPoolSize=100)    │              │ (순차 처리)  │              │
├─────────────────────┼──────────────┼──────────────┼──────────────┤
│ 그룹별 연결          │ 500          │ ~2초         │ ⭐⭐⭐       │
│ (10 그룹 * 50)       │              │              │              │
├─────────────────────┼──────────────┼──────────────┼──────────────┤
│ 유저별 연결          │ 10,000       │ ~1초         │ ⭐⭐⭐⭐⭐   │
│ (1000 유저 * 10)     │              │ (병렬 처리)  │              │
└─────────────────────┴──────────────┴──────────────┴──────────────┘

3. 유저별 독립 커넥션 구현

3.1 기본 구현 (Python)

"""
유저별 독립 연결 관리자 - 프로덕션 수준

Copyright (c) 2024 VCANUS
"""

import threading
import weakref
import time
from typing import Dict, Optional
from pymongo import MongoClient
from pymongo.database import Database
import logging

logger = logging.getLogger(__name__)


class UserConnectionManager:
    """
    유저별 독립 MongoDB 연결 관리
    
    특징:
    - 유저별 독립 MongoClient 생성
    - 연결 풀 자동 관리
    - Thread-safe
    - 자동 정리 (idle timeout)
    - 메모리 효율적 (weak reference 옵션)
    """
    
    def __init__(
        self,
        connection_string: str,
        user_pool_size: int = 10,
        idle_timeout: int = 3600,  # 1시간
        use_weak_ref: bool = False,
        **mongo_options
    ):
        """
        Args:
            connection_string: MongoDB 연결 문자열
            user_pool_size: 유저당 연결 풀 크기
            idle_timeout: 유휴 연결 타임아웃 (초)
            use_weak_ref: WeakValueDictionary 사용 여부
            **mongo_options: MongoClient 추가 옵션
        """
        self.connection_string = connection_string
        self.user_pool_size = user_pool_size
        self.idle_timeout = idle_timeout
        
        # 연결 저장소
        if use_weak_ref:
            # 약한 참조 - 사용 안할 때 자동 GC
            self._clients: Dict[str, MongoClient] = weakref.WeakValueDictionary()
        else:
            # 강한 참조 - 명시적 제거 전까지 유지
            self._clients: Dict[str, MongoClient] = {}
        
        # 마지막 접근 시간 추적
        self._last_access: Dict[str, float] = {}
        
        # Thread-safe 락
        self._lock = threading.RLock()
        
        # 기본 MongoDB 옵션
        self.mongo_options = {
            'maxPoolSize': user_pool_size,
            'minPoolSize': 1,
            'maxIdleTimeMS': idle_timeout * 1000,
            'connectTimeoutMS': 5000,
            'serverSelectionTimeoutMS': 5000,
            **mongo_options
        }
        
        # 정리 스레드 시작
        self._cleanup_thread = threading.Thread(
            target=self._cleanup_idle_connections,
            daemon=True
        )
        self._cleanup_thread.start()
        
        logger.info(
            f"UserConnectionManager initialized: "
            f"pool_size={user_pool_size}, idle_timeout={idle_timeout}s"
        )
    
    def get_client(self, user_id: str) -> MongoClient:
        """
        유저의 독립 MongoClient 반환
        
        없으면 새로 생성, 있으면 재사용
        
        Args:
            user_id: 유저 ID
            
        Returns:
            MongoClient 인스턴스
        """
        with self._lock:
            # 접근 시간 업데이트
            self._last_access[user_id] = time.time()
            
            # 기존 클라이언트 확인
            if user_id in self._clients:
                client = self._clients[user_id]
                
                # 연결 상태 확인
                try:
                    client.admin.command('ping')
                    logger.debug(f"Reusing connection for user: {user_id}")
                    return client
                except Exception as e:
                    logger.warning(f"Dead connection for {user_id}, recreating: {e}")
                    # 죽은 연결 제거
                    del self._clients[user_id]
            
            # 새 클라이언트 생성
            logger.info(f"Creating new connection for user: {user_id}")
            client = MongoClient(
                self.connection_string,
                **self.mongo_options
            )
            
            self._clients[user_id] = client
            return client
    
    def get_database(self, user_id: str, db_name: Optional[str] = None) -> Database:
        """
        유저의 데이터베이스 반환
        
        Args:
            user_id: 유저 ID
            db_name: 데이터베이스 이름 (기본값: user_{user_id}_db)
            
        Returns:
            Database 인스턴스
        """
        client = self.get_client(user_id)
        
        if db_name is None:
            db_name = f"user_{user_id}_db"
        
        return client[db_name]
    
    def close_user_connection(self, user_id: str) -> bool:
        """
        특정 유저의 연결 종료
        
        Args:
            user_id: 유저 ID
            
        Returns:
            성공 여부
        """
        with self._lock:
            if user_id in self._clients:
                try:
                    self._clients[user_id].close()
                    del self._clients[user_id]
                    
                    if user_id in self._last_access:
                        del self._last_access[user_id]
                    
                    logger.info(f"Closed connection for user: {user_id}")
                    return True
                except Exception as e:
                    logger.error(f"Failed to close connection for {user_id}: {e}")
                    return False
            
            return False
    
    def _cleanup_idle_connections(self):
        """
        유휴 연결 자동 정리 (백그라운드 스레드)
        """
        while True:
            time.sleep(60)  # 1분마다 체크
            
            try:
                with self._lock:
                    now = time.time()
                    idle_users = []
                    
                    for user_id, last_access in self._last_access.items():
                        if now - last_access > self.idle_timeout:
                            idle_users.append(user_id)
                    
                    for user_id in idle_users:
                        logger.info(f"Closing idle connection for user: {user_id}")
                        self.close_user_connection(user_id)
            
            except Exception as e:
                logger.error(f"Error in cleanup thread: {e}")
    
    def get_stats(self) -> dict:
        """
        연결 통계 조회
        
        Returns:
            통계 정보
        """
        with self._lock:
            return {
                'total_connections': len(self._clients),
                'user_pool_size': self.user_pool_size,
                'idle_timeout': self.idle_timeout,
                'active_users': list(self._clients.keys()),
                'total_potential_connections': len(self._clients) * self.user_pool_size
            }
    
    def close_all(self):
        """모든 연결 종료"""
        with self._lock:
            logger.info(f"Closing all {len(self._clients)} connections...")
            
            for user_id, client in list(self._clients.items()):
                try:
                    client.close()
                except Exception as e:
                    logger.error(f"Error closing connection for {user_id}: {e}")
            
            self._clients.clear()
            self._last_access.clear()
            
            logger.info("All connections closed")
    
    def __enter__(self):
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        self.close_all()


# ============= 사용 예시 =============

if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    
    # 매니저 초기화
    manager = UserConnectionManager(
        connection_string="mongodb://localhost:27017/",
        user_pool_size=10,  # 유저당 10개 연결
        idle_timeout=3600   # 1시간 유휴 시 자동 종료
    )
    
    # User A - 독립 연결
    db_a = manager.get_database('user_a')
    db_a.posts.insert_one({
        'title': 'Hello from User A',
        'content': 'First post'
    })
    
    # User B - 독립 연결 (User A와 간섭 없음)
    db_b = manager.get_database('user_b')
    db_b.posts.insert_one({
        'title': 'Hello from User B',
        'content': 'First post'
    })
    
    # User C - 독립 연결
    db_c = manager.get_database('user_c')
    db_c.posts.insert_one({
        'title': 'Hello from User C',
        'content': 'First post'
    })
    
    # 통계 확인
    stats = manager.get_stats()
    print(f"\nConnection Stats:")
    print(f"  Total connections: {stats['total_connections']}")
    print(f"  Active users: {stats['active_users']}")
    print(f"  Potential connections: {stats['total_potential_connections']}")
    
    # 특정 유저 연결 종료
    manager.close_user_connection('user_a')
    
    # 모든 연결 종료
    manager.close_all()

3.2 Flask 통합

"""
Flask 애플리케이션과 통합
"""

from flask import Flask, g, request, jsonify
from functools import wraps

app = Flask(__name__)

# 전역 매니저
connection_manager = UserConnectionManager(
    connection_string="mongodb://localhost:27017/",
    user_pool_size=10,
    idle_timeout=3600
)


def get_user_id_from_request() -> str:
    """
    요청에서 유저 ID 추출
    
    우선순위:
    1. JWT 토큰
    2. X-User-ID 헤더
    3. 쿼리 파라미터
    """
    # 방법 1: JWT에서 추출
    auth_header = request.headers.get('Authorization')
    if auth_header and auth_header.startswith('Bearer '):
        token = auth_header[7:]
        # payload = decode_jwt(token)
        # return payload['user_id']
    
    # 방법 2: 헤더
    user_id = request.headers.get('X-User-ID')
    if user_id:
        return user_id
    
    # 방법 3: 쿼리 파라미터
    user_id = request.args.get('user_id')
    if user_id:
        return user_id
    
    raise ValueError("User ID not found in request")


def require_user_db(f):
    """
    유저 DB 주입 데코레이터
    
    각 유저마다 독립 연결 사용
    """
    @wraps(f)
    def decorated_function(*args, **kwargs):
        try:
            # 유저 ID 추출
            user_id = get_user_id_from_request()
            
            # 독립 연결로 DB 가져오기
            g.user_id = user_id
            g.db = connection_manager.get_database(user_id)
            
            return f(*args, **kwargs)
        
        except ValueError as e:
            return jsonify({'error': str(e)}), 400
        
        except Exception as e:
            logger.error(f"Database error: {e}", exc_info=True)
            return jsonify({'error': 'Internal server error'}), 500
    
    return decorated_function


# ============= API 엔드포인트 =============

@app.route('/api/posts', methods=['GET'])
@require_user_db
def get_posts():
    """포스트 목록 조회"""
    posts = list(g.db.posts.find({}, {'_id': 0}).limit(20))
    return jsonify({
        'user_id': g.user_id,
        'posts': posts
    })


@app.route('/api/posts', methods=['POST'])
@require_user_db
def create_post():
    """포스트 생성"""
    data = request.get_json()
    
    # 유저의 독립 DB에 저장
    result = g.db.posts.insert_one(data)
    
    return jsonify({
        'user_id': g.user_id,
        'post_id': str(result.inserted_id),
        'message': 'Post created successfully'
    }), 201


@app.route('/api/posts/<post_id>', methods=['GET'])
@require_user_db
def get_post(post_id):
    """포스트 조회"""
    from bson import ObjectId
    
    post = g.db.posts.find_one({'_id': ObjectId(post_id)})
    
    if not post:
        return jsonify({'error': 'Post not found'}), 404
    
    post['_id'] = str(post['_id'])
    return jsonify({
        'user_id': g.user_id,
        'post': post
    })


# ============= 관리자 엔드포인트 =============

@app.route('/admin/connections', methods=['GET'])
def get_connection_stats():
    """연결 통계"""
    stats = connection_manager.get_stats()
    return jsonify(stats)


@app.route('/admin/connections/<user_id>', methods=['DELETE'])
def close_user_connection(user_id):
    """특정 유저 연결 종료"""
    success = connection_manager.close_user_connection(user_id)
    
    if success:
        return jsonify({'message': f'Connection closed for {user_id}'})
    else:
        return jsonify({'error': f'No connection found for {user_id}'}), 404


if __name__ == '__main__':
    app.run(debug=True)

3.3 FastAPI 통합

"""
FastAPI 애플리케이션과 통합
"""

from fastapi import FastAPI, Depends, Header, HTTPException
from typing import Optional
from pydantic import BaseModel

app = FastAPI()

# 전역 매니저
connection_manager = UserConnectionManager(
    connection_string="mongodb://localhost:27017/",
    user_pool_size=10
)


# ============= Pydantic 모델 =============

class Post(BaseModel):
    title: str
    content: str
    tags: Optional[list] = []


# ============= Dependency =============

async def get_user_database(
    x_user_id: str = Header(..., description="User ID")
):
    """
    유저 독립 DB 의존성
    
    각 유저마다 독립 연결 사용
    """
    if not x_user_id:
        raise HTTPException(
            status_code=400,
            detail="X-User-ID header is required"
        )
    
    # 독립 연결로 DB 반환
    db = connection_manager.get_database(x_user_id)
    
    return {
        'user_id': x_user_id,
        'db': db
    }


# ============= API 엔드포인트 =============

@app.get("/api/posts")
async def get_posts(
    user_data = Depends(get_user_database),
    limit: int = 20
):
    """포스트 목록 조회"""
    posts = list(
        user_data['db'].posts
        .find({}, {'_id': 0})
        .limit(limit)
    )
    
    return {
        'user_id': user_data['user_id'],
        'posts': posts
    }


@app.post("/api/posts", status_code=201)
async def create_post(
    post: Post,
    user_data = Depends(get_user_database)
):
    """포스트 생성"""
    result = user_data['db'].posts.insert_one(post.dict())
    
    return {
        'user_id': user_data['user_id'],
        'post_id': str(result.inserted_id),
        'message': 'Post created successfully'
    }


@app.get("/api/posts/{post_id}")
async def get_post(
    post_id: str,
    user_data = Depends(get_user_database)
):
    """포스트 조회"""
    from bson import ObjectId
    
    post = user_data['db'].posts.find_one({'_id': ObjectId(post_id)})
    
    if not post:
        raise HTTPException(status_code=404, detail="Post not found")
    
    post['_id'] = str(post['_id'])
    return {
        'user_id': user_data['user_id'],
        'post': post
    }


# ============= 관리자 엔드포인트 =============

@app.get("/admin/connections")
async def get_connection_stats():
    """연결 통계"""
    return connection_manager.get_stats()


@app.delete("/admin/connections/{user_id}")
async def close_user_connection(user_id: str):
    """특정 유저 연결 종료"""
    success = connection_manager.close_user_connection(user_id)
    
    if success:
        return {'message': f'Connection closed for {user_id}'}
    else:
        raise HTTPException(
            status_code=404,
            detail=f'No connection found for {user_id}'
        )

4. 연결 풀 전략

4.1 풀 크기 결정

"""
유저별 연결 풀 크기 계산
"""

def calculate_pool_size(
    concurrent_users: int,
    requests_per_user: int = 5,
    available_connections: int = 10000
) -> tuple:
    """
    적절한 풀 크기 계산
    
    Args:
        concurrent_users: 동시 접속 유저 수
        requests_per_user: 유저당 동시 요청 수
        available_connections: 서버에서 허용하는 최대 연결 수
        
    Returns:
        (user_pool_size, max_users)
    """
    # 1. 이상적인 유저당 풀 크기
    ideal_pool_size = requests_per_user
    
    # 2. 서버 제약 고려
    max_users_with_ideal = available_connections // ideal_pool_size
    
    if max_users_with_ideal >= concurrent_users:
        # 충분한 연결 수
        return (ideal_pool_size, concurrent_users)
    else:
        # 연결 수 부족 - 풀 크기 줄임
        adjusted_pool_size = available_connections // concurrent_users
        return (adjusted_pool_size, concurrent_users)


# 예시
concurrent_users = 1000
pool_size, max_users = calculate_pool_size(
    concurrent_users=concurrent_users,
    requests_per_user=5,
    available_connections=10000
)

print(f"Recommended pool size: {pool_size}")
print(f"Max users supported: {max_users}")
print(f"Total connections: {pool_size * max_users}")

# 출력:
# Recommended pool size: 5
# Max users supported: 1000
# Total connections: 5000

4.2 동적 풀 크기 조정

"""
유저 등급별 다른 풀 크기
"""

class TieredUserConnectionManager(UserConnectionManager):
    """
    등급별 차등 연결 풀
    """
    
    def __init__(self, connection_string: str, **options):
        super().__init__(connection_string, **options)
        
        # 등급별 풀 크기
        self.tier_pool_sizes = {
            'free': 3,
            'basic': 5,
            'premium': 10,
            'enterprise': 20
        }
    
    def get_user_tier(self, user_id: str) -> str:
        """
        유저 등급 조회 (실제로는 DB에서 가져와야 함)
        """
        # TODO: 실제 구현에서는 DB 조회
        # 여기서는 예시로 user_id 기반 반환
        if user_id.startswith('ent_'):
            return 'enterprise'
        elif user_id.startswith('pre_'):
            return 'premium'
        elif user_id.startswith('bas_'):
            return 'basic'
        else:
            return 'free'
    
    def get_client(self, user_id: str) -> MongoClient:
        """등급에 맞는 풀 크기로 클라이언트 생성"""
        with self._lock:
            if user_id in self._clients:
                return self._clients[user_id]
            
            # 유저 등급 확인
            tier = self.get_user_tier(user_id)
            pool_size = self.tier_pool_sizes.get(tier, 5)
            
            logger.info(
                f"Creating connection for user {user_id} "
                f"(tier: {tier}, pool_size: {pool_size})"
            )
            
            # 등급별 풀 크기로 생성
            client = MongoClient(
                self.connection_string,
                maxPoolSize=pool_size,
                minPoolSize=1
            )
            
            self._clients[user_id] = client
            self._last_access[user_id] = time.time()
            
            return client


# 사용
manager = TieredUserConnectionManager(
    connection_string="mongodb://localhost:27017/"
)

# Free tier: 3개 연결
db_free = manager.get_database('user_123')

# Premium tier: 10개 연결
db_premium = manager.get_database('pre_user_456')

# Enterprise tier: 20개 연결
db_enterprise = manager.get_database('ent_user_789')

4.3 연결 풀 모니터링

"""
연결 풀 상태 모니터링
"""

class MonitoredUserConnectionManager(UserConnectionManager):
    """
    모니터링 기능 추가
    """
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        
        # 메트릭 저장
        self.metrics = {
            'total_connections_created': 0,
            'total_connections_closed': 0,
            'connection_errors': 0,
            'slow_queries': 0
        }
    
    def get_client(self, user_id: str) -> MongoClient:
        """연결 생성 추적"""
        with self._lock:
            if user_id not in self._clients:
                self.metrics['total_connections_created'] += 1
        
        return super().get_client(user_id)
    
    def close_user_connection(self, user_id: str) -> bool:
        """연결 종료 추적"""
        result = super().close_user_connection(user_id)
        
        if result:
            self.metrics['total_connections_closed'] += 1
        
        return result
    
    def get_pool_stats(self, user_id: str) -> dict:
        """
        특정 유저의 연결 풀 통계
        """
        try:
            client = self._clients.get(user_id)
            
            if not client:
                return {'error': 'No connection found'}
            
            # MongoDB 서버 상태 조회
            server_status = client.admin.command('serverStatus')
            
            return {
                'user_id': user_id,
                'connections': server_status.get('connections', {}),
                'pool_size': self.user_pool_size,
                'last_access': self._last_access.get(user_id, 0)
            }
        
        except Exception as e:
            logger.error(f"Failed to get pool stats: {e}")
            return {'error': str(e)}
    
    def get_all_metrics(self) -> dict:
        """전체 메트릭 조회"""
        stats = self.get_stats()
        
        return {
            **stats,
            **self.metrics,
            'avg_connections_per_user': (
                stats['total_potential_connections'] / stats['total_connections']
                if stats['total_connections'] > 0
                else 0
            )
        }

5. 동시성 처리

5.1 동시 요청 처리 테스트

"""
동시성 테스트: 단일 연결 vs 독립 연결
"""

import concurrent.futures
import time
from pymongo import MongoClient


# ============= 테스트 1: 단일 연결 =============

def test_single_connection():
    """단일 MongoClient로 여러 유저 처리"""
    client = MongoClient("mongodb://localhost:27017/", maxPoolSize=100)
    
    def process_user(user_id: int):
        db = client[f'user_{user_id}_db']
        start = time.time()
        
        # 시뮬레이션: 1초 걸리는 쿼리
        db.posts.insert_one({'user_id': user_id, 'timestamp': start})
        time.sleep(0.1)  # 쿼리 시뮬레이션
        
        return time.time() - start
    
    # 100명 동시 처리
    start_time = time.time()
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=100) as executor:
        futures = [executor.submit(process_user, i) for i in range(100)]
        results = [f.result() for f in concurrent.futures.as_completed(futures)]
    
    total_time = time.time() - start_time
    
    print(f"\n=== Single Connection ===")
    print(f"Total time: {total_time:.2f}s")
    print(f"Avg per user: {sum(results)/len(results):.2f}s")
    print(f"Max wait: {max(results):.2f}s")
    
    client.close()


# ============= 테스트 2: 독립 연결 =============

def test_independent_connections():
    """유저별 독립 MongoClient"""
    manager = UserConnectionManager(
        connection_string="mongodb://localhost:27017/",
        user_pool_size=10
    )
    
    def process_user(user_id: int):
        db = manager.get_database(f'user_{user_id}')
        start = time.time()
        
        # 시뮬레이션: 1초 걸리는 쿼리
        db.posts.insert_one({'user_id': user_id, 'timestamp': start})
        time.sleep(0.1)
        
        return time.time() - start
    
    # 100명 동시 처리
    start_time = time.time()
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=100) as executor:
        futures = [executor.submit(process_user, i) for i in range(100)]
        results = [f.result() for f in concurrent.futures.as_completed(futures)]
    
    total_time = time.time() - start_time
    
    print(f"\n=== Independent Connections ===")
    print(f"Total time: {total_time:.2f}s")
    print(f"Avg per user: {sum(results)/len(results):.2f}s")
    print(f"Max wait: {max(results):.2f}s")
    
    manager.close_all()


# 실행
if __name__ == "__main__":
    print("Running concurrency tests...")
    
    test_single_connection()
    test_independent_connections()
    
    # 예상 결과:
    # Single Connection - Total time: ~2-3s (병목 발생)
    # Independent Connections - Total time: ~1s (병렬 처리)

5.2 부하 테스트 시나리오

"""
실전 부하 테스트
"""

import asyncio
import aiohttp
import time


async def load_test(
    base_url: str,
    num_users: int,
    requests_per_user: int
):
    """
    부하 테스트
    
    Args:
        base_url: API 서버 URL
        num_users: 동시 유저 수
        requests_per_user: 유저당 요청 수
    """
    
    async def user_requests(session, user_id):
        """단일 유저의 요청들"""
        headers = {'X-User-ID': f'user_{user_id}'}
        timings = []
        
        for _ in range(requests_per_user):
            start = time.time()
            
            async with session.post(
                f'{base_url}/api/posts',
                json={'title': f'Post from user {user_id}'},
                headers=headers
            ) as response:
                await response.json()
            
            timings.append(time.time() - start)
        
        return timings
    
    # 모든 유저 동시 실행
    start_time = time.time()
    
    async with aiohttp.ClientSession() as session:
        tasks = [
            user_requests(session, user_id)
            for user_id in range(num_users)
        ]
        
        all_timings = await asyncio.gather(*tasks)
    
    total_time = time.time() - start_time
    
    # 통계
    flat_timings = [t for timings in all_timings for t in timings]
    
    print(f"\n=== Load Test Results ===")
    print(f"Total users: {num_users}")
    print(f"Requests per user: {requests_per_user}")
    print(f"Total requests: {len(flat_timings)}")
    print(f"Total time: {total_time:.2f}s")
    print(f"Requests/sec: {len(flat_timings)/total_time:.2f}")
    print(f"Avg response time: {sum(flat_timings)/len(flat_timings):.3f}s")
    print(f"Min response time: {min(flat_timings):.3f}s")
    print(f"Max response time: {max(flat_timings):.3f}s")
    
    # 백분위수
    sorted_timings = sorted(flat_timings)
    p50 = sorted_timings[len(sorted_timings) // 2]
    p95 = sorted_timings[int(len(sorted_timings) * 0.95)]
    p99 = sorted_timings[int(len(sorted_timings) * 0.99)]
    
    print(f"P50: {p50:.3f}s")
    print(f"P95: {p95:.3f}s")
    print(f"P99: {p99:.3f}s")


# 실행
if __name__ == "__main__":
    asyncio.run(load_test(
        base_url="http://localhost:5000",
        num_users=100,
        requests_per_user=10
    ))

6. 성능 최적화

6.1 연결 재사용 최대화

"""
연결 재사용 전략
"""

class OptimizedConnectionManager(UserConnectionManager):
    """
    최적화된 연결 관리
    """
    
    def __init__(self, *args, **kwargs):
        # 재사용 카운터
        self.reuse_count = {}
        super().__init__(*args, **kwargs)
    
    def get_client(self, user_id: str) -> MongoClient:
        """재사용 추적"""
        client = super().get_client(user_id)
        
        # 재사용 카운트
        with self._lock:
            if user_id not in self.reuse_count:
                self.reuse_count[user_id] = 0
            else:
                self.reuse_count[user_id] += 1
        
        return client
    
    def get_reuse_stats(self) -> dict:
        """재사용 통계"""
        with self._lock:
            total_reuses = sum(self.reuse_count.values())
            total_connections = len(self.reuse_count)
            
            return {
                'total_connections': total_connections,
                'total_reuses': total_reuses,
                'avg_reuses_per_connection': (
                    total_reuses / total_connections
                    if total_connections > 0
                    else 0
                ),
                'reuse_rate': (
                    total_reuses / (total_reuses + total_connections)
                    if (total_reuses + total_connections) > 0
                    else 0
                )
            }

6.2 메모리 최적화

"""
메모리 사용 최적화
"""

import sys
import gc


class MemoryEfficientConnectionManager(UserConnectionManager):
    """
    메모리 효율적인 연결 관리
    """
    
    def __init__(
        self,
        connection_string: str,
        max_connections: int = 100,  # 최대 연결 수 제한
        **kwargs
    ):
        self.max_connections = max_connections
        super().__init__(connection_string, **kwargs)
    
    def get_client(self, user_id: str) -> MongoClient:
        """최대 연결 수 제한"""
        with self._lock:
            # 연결 수 제한 체크
            if (user_id not in self._clients and 
                len(self._clients) >= self.max_connections):
                
                # LRU: 가장 오래 사용 안한 연결 제거
                oldest_user = min(
                    self._last_access.items(),
                    key=lambda x: x[1]
                )[0]
                
                logger.info(
                    f"Max connections reached. "
                    f"Closing LRU connection: {oldest_user}"
                )
                
                self.close_user_connection(oldest_user)
                
                # 강제 GC
                gc.collect()
        
        return super().get_client(user_id)
    
    def get_memory_usage(self) -> dict:
        """메모리 사용량 조회"""
        import psutil
        import os
        
        process = psutil.Process(os.getpid())
        mem_info = process.memory_info()
        
        return {
            'rss_mb': mem_info.rss / 1024 / 1024,
            'vms_mb': mem_info.vms / 1024 / 1024,
            'connections': len(self._clients),
            'avg_memory_per_connection': (
                mem_info.rss / len(self._clients) / 1024 / 1024
                if len(self._clients) > 0
                else 0
            )
        }

6.3 캐싱 전략

"""
쿼리 결과 캐싱
"""

from functools import lru_cache
from datetime import datetime, timedelta


class CachedDatabaseWrapper:
    """
    DB 래퍼 with 캐싱
    """
    
    def __init__(self, db, cache_ttl: int = 300):
        self.db = db
        self.cache_ttl = cache_ttl
        self._cache = {}
        self._cache_times = {}
    
    def find_one_cached(self, collection: str, query: dict):
        """캐시된 find_one"""
        cache_key = f"{collection}:{str(query)}"
        
        # 캐시 확인
        if cache_key in self._cache:
            cache_time = self._cache_times[cache_key]
            if datetime.now() - cache_time < timedelta(seconds=self.cache_ttl):
                return self._cache[cache_key]
        
        # 캐시 미스 - DB 조회
        result = self.db[collection].find_one(query)
        
        # 캐싱
        self._cache[cache_key] = result
        self._cache_times[cache_key] = datetime.now()
        
        return result
    
    def invalidate_cache(self, collection: str = None):
        """캐시 무효화"""
        if collection:
            # 특정 컬렉션만
            keys_to_remove = [
                k for k in self._cache.keys()
                if k.startswith(f"{collection}:")
            ]
            for key in keys_to_remove:
                del self._cache[key]
                del self._cache_times[key]
        else:
            # 전체 캐시
            self._cache.clear()
            self._cache_times.clear()

7. 실전 예제

7.1 블로그 플랫폼

"""
유저별 독립 블로그 DB
"""

class BlogPlatform:
    """
    멀티 유저 블로그 플랫폼
    
    각 유저마다 독립 DB 사용
    """
    
    def __init__(self):
        self.connection_manager = UserConnectionManager(
            connection_string="mongodb://localhost:27017/",
            user_pool_size=10,
            idle_timeout=3600
        )
    
    def create_post(self, user_id: str, title: str, content: str):
        """포스트 생성"""
        db = self.connection_manager.get_database(user_id)
        
        post = {
            'title': title,
            'content': content,
            'created_at': datetime.now(),
            'updated_at': datetime.now(),
            'views': 0,
            'likes': 0
        }
        
        result = db.posts.insert_one(post)
        return str(result.inserted_id)
    
    def get_user_posts(self, user_id: str, page: int = 1, page_size: int = 10):
        """유저의 포스트 목록"""
        db = self.connection_manager.get_database(user_id)
        
        skip = (page - 1) * page_size
        
        posts = list(
            db.posts
            .find({}, {'_id': 0})
            .sort('created_at', -1)
            .skip(skip)
            .limit(page_size)
        )
        
        return posts
    
    def increment_views(self, user_id: str, post_id: str):
        """조회수 증가"""
        from bson import ObjectId
        
        db = self.connection_manager.get_database(user_id)
        
        db.posts.update_one(
            {'_id': ObjectId(post_id)},
            {'$inc': {'views': 1}}
        )
    
    def get_stats(self, user_id: str):
        """유저 통계"""
        db = self.connection_manager.get_database(user_id)
        
        return {
            'total_posts': db.posts.count_documents({}),
            'total_views': list(db.posts.aggregate([
                {'$group': {'_id': None, 'total': {'$sum': '$views'}}}
            ]))[0]['total'] if db.posts.count_documents({}) > 0 else 0,
            'total_likes': list(db.posts.aggregate([
                {'$group': {'_id': None, 'total': {'$sum': '$likes'}}}
            ]))[0]['total'] if db.posts.count_documents({}) > 0 else 0
        }


# 사용
blog = BlogPlatform()

# User A
post_id_a = blog.create_post(
    'user_a',
    'First Post',
    'Hello World!'
)

# User B (독립 DB, User A와 간섭 없음)
post_id_b = blog.create_post(
    'user_b',
    'My First Post',
    'Welcome to my blog!'
)

# 통계
stats_a = blog.get_stats('user_a')
print(f"User A stats: {stats_a}")

7.2 SaaS 애플리케이션

"""
SaaS: 회사별 독립 DB
"""

class SaaSPlatform:
    """
    멀티 테넌트 SaaS 플랫폼
    
    각 회사마다 독립 DB
    """
    
    def __init__(self):
        self.connection_manager = TieredUserConnectionManager(
            connection_string="mongodb://localhost:27017/"
        )
    
    def onboard_company(self, company_id: str, plan: str = 'basic'):
        """회사 온보딩"""
        db = self.connection_manager.get_database(company_id)
        
        # 초기 컬렉션 생성
        db.create_collection('users')
        db.create_collection('projects')
        db.create_collection('tasks')
        
        # 인덱스 생성
        db.users.create_index([('email', 1)], unique=True)
        db.projects.create_index([('name', 1)])
        db.tasks.create_index([('project_id', 1), ('status', 1)])
        
        # 메타데이터
        db._metadata.insert_one({
            'company_id': company_id,
            'plan': plan,
            'onboarded_at': datetime.now(),
            'status': 'active'
        })
        
        logger.info(f"Company {company_id} onboarded with {plan} plan")
    
    def add_user(self, company_id: str, email: str, name: str, role: str):
        """유저 추가"""
        db = self.connection_manager.get_database(company_id)
        
        user = {
            'email': email,
            'name': name,
            'role': role,
            'created_at': datetime.now()
        }
        
        result = db.users.insert_one(user)
        return str(result.inserted_id)
    
    def create_project(self, company_id: str, name: str, description: str):
        """프로젝트 생성"""
        db = self.connection_manager.get_database(company_id)
        
        project = {
            'name': name,
            'description': description,
            'created_at': datetime.now(),
            'status': 'active'
        }
        
        result = db.projects.insert_one(project)
        return str(result.inserted_id)
    
    def get_company_analytics(self, company_id: str):
        """회사 분석 데이터"""
        db = self.connection_manager.get_database(company_id)
        
        return {
            'company_id': company_id,
            'total_users': db.users.count_documents({}),
            'total_projects': db.projects.count_documents({}),
            'total_tasks': db.tasks.count_documents({}),
            'active_projects': db.projects.count_documents({'status': 'active'}),
            'completed_tasks': db.tasks.count_documents({'status': 'completed'})
        }


# 사용
saas = SaaSPlatform()

# Company A 온보딩
saas.onboard_company('company_a', plan='premium')
saas.add_user('company_a', 'alice@company-a.com', 'Alice', 'admin')
saas.create_project('company_a', 'Project Alpha', 'First project')

# Company B 온보딩 (독립 DB)
saas.onboard_company('company_b', plan='enterprise')
saas.add_user('company_b', 'bob@company-b.com', 'Bob', 'admin')

# 분석
analytics_a = saas.get_company_analytics('company_a')
print(f"Company A analytics: {analytics_a}")

8. 요약

8.1 핵심 포인트

항목	단일 연결	유저별 연결
구현 복잡도	⭐ 낮음	⭐⭐⭐ 높음
동시성	⭐⭐ 제한적	⭐⭐⭐⭐⭐ 최대
격리 수준	⭐⭐ 낮음	⭐⭐⭐⭐⭐ 완벽
연결 수	적음 (100개)	많음 (유저*10)
메모리 사용	적음	많음
확장성	제한적	무한
QoS	불가능	가능

8.2 의사결정 트리

유저별 독립 DB 필요?
└─ YES
    │
    ├─ 동시 접속 < 50 → 단일 연결 + useDb()
    │   └─ 구현 간단, 비용 적음
    │
    ├─ 동시 접속 50-500 → 그룹별 연결
    │   └─ 균형잡힌 접근
    │
    └─ 동시 접속 > 500 → 유저별 독립 연결 ⭐
        └─ 최대 동시성, 완벽한 격리

8.3 최종 권장사항

소규모 (< 50 동시 접속)

# 단일 연결로 충분
client = MongoClient(uri, maxPoolSize=100)
db = client[f'user_{user_id}_db']

중규모 (50-500 동시 접속)

# 그룹별 연결
manager = GroupConnectionManager(groups=10)
db = manager.get_database(user_id)

대규모 (> 500 동시 접속)

# 유저별 독립 연결 ⭐
manager = UserConnectionManager(
    connection_string=uri,
    user_pool_size=10,
    idle_timeout=3600
)
db = manager.get_database(user_id)

9. 체크리스트

구현 전

동시 접속 유저 수 예측
유저당 평균 요청 수 분석
서버 연결 수 제한 확인
메모리 용량 확인
연결 방식 선택 (단일/그룹/유저별)

구현 중

운영

이 가이드가 도움이 되셨나요? 실전 경험과 피드백을 환영합니다!

Python Path Management

Tue, 04 Nov 2025 00:00:00 +0000

Python Package: 상대 경로 vs 절대 경로 완벽 가이드

작성일: 2025-11-04
Copyright: VCANUS
버전: 1.0

1. 개요

Python에서 모듈을 import하는 방식은 크게 두 가지입니다:

상대 경로 (Relative Imports): 현재 모듈의 위치를 기준으로 import
절대 경로 (Absolute Imports): 프로젝트 루트부터 전체 경로로 import

1.1 기본 문법

# 상대 경로
from .module import Class          # 같은 디렉토리
from ..module import Class         # 상위 디렉토리
from .subpackage.module import Class  # 하위 패키지

# 절대 경로
from mypackage.module import Class
from mypackage.subpackage.module import Class

1.2 예제 패키지 구조

이 가이드에서 사용할 예제 구조:

mypackage/
├── __init__.py
├── models/
│   ├── __init__.py
│   ├── user.py
│   └── product.py
├── services/
│   ├── __init__.py
│   ├── user_service.py
│   └── product_service.py
└── utils/
    ├── __init__.py
    ├── validators.py
    └── formatters.py

2. 상대 경로 (Relative Imports)

2.1 기본 개념

상대 경로는 점(.) 을 사용하여 현재 모듈의 위치를 기준으로 import합니다.

from .module import Class      # 현재 패키지의 module
from ..module import Class     # 상위 패키지의 module
from ...module import Class    # 상위의 상위 패키지의 module

2.2 상대 경로 패턴

패턴 1: 같은 디렉토리

# mypackage/models/user.py

from .product import Product  # 같은 models 디렉토리의 product.py

디렉토리 구조:

models/
├── user.py      ← 여기서
└── product.py   ← 이것을 import

패턴 2: 상위 디렉토리

# mypackage/services/user_service.py

from ..models import User  # 상위(mypackage)의 models 패키지

디렉토리 구조:

mypackage/
├── models/
│   └── user.py     ← 이것을 import
└── services/
    └── user_service.py  ← 여기서

패턴 3: 형제 패키지

# mypackage/services/user_service.py

from ..utils.validators import validate_email  # 형제 패키지

디렉토리 구조:

mypackage/
├── services/
│   └── user_service.py  ← 여기서
└── utils/
    └── validators.py    ← 이것을 import

패턴 4: 복잡한 경로

# mypackage/api/v1/endpoints/users.py

from ....models import User  # 4단계 상위의 models
from ...services import UserService  # 3단계 상위의 services
from ..auth import authenticate  # 1단계 상위의 auth

디렉토리 구조:

mypackage/
├── models/
│   └── user.py
├── services/
│   └── user_service.py
└── api/
    └── v1/
        ├── auth.py
        └── endpoints/
            └── users.py  ← 여기서

2.3 상대 경로의 장점 ✅

1. 패키지명 변경 용이

# mypackage/__init__.py → yourpackage/__init__.py
# 패키지명을 바꿔도 내부 import는 수정 불필요

# ✅ 상대 경로 (수정 불필요)
from .models import User
from .services import UserService

# ❌ 절대 경로 (모두 수정 필요)
from mypackage.models import User  # yourpackage로 변경 필요
from mypackage.services import UserService  # yourpackage로 변경 필요

2. 패키지 재사용 및 이식성

# other_project에 mypackage 폴더를 복사
# ✅ 상대 경로: 그대로 작동
# ❌ 절대 경로: 모든 import 수정 필요

3. 패키지 구조 명확성

# mypackage/services/user_service.py

from ..models import User  # ← 상위 패키지의 models라는 것이 명확
from .auth_service import AuthService  # ← 같은 services 패키지라는 것이 명확

4. 순환 참조 감지 용이

# 상대 경로는 순환 참조를 더 명확하게 보여줌
# mypackage/models/user.py
from ..services import UserService  # models → services

# mypackage/services/user_service.py
from ..models import User  # services → models
# ← 순환 참조 명확!

2.4 상대 경로의 단점 ⚠️

1. 스크립트로 직접 실행 불가

# mypackage/models/user.py
from .product import Product

# ❌ 직접 실행 시 에러
# python mypackage/models/user.py
# ValueError: attempted relative import beyond top-level package

해결방법:

# ✅ 모듈로 실행
python -m mypackage.models.user

2. 깊은 중첩 시 가독성 저하

# 너무 많은 점은 헷갈림
from ....models.user import User
from .....utils.validators import validate

3. IDE 자동완성 제한

일부 IDE에서는 상대 경로의 자동완성 지원이 약할 수 있습니다.

3. 절대 경로 (Absolute Imports)

3.1 기본 개념

절대 경로는 프로젝트 루트부터 전체 경로를 명시합니다.

from mypackage.models.user import User
from mypackage.services.user_service import UserService

3.2 절대 경로 패턴

패턴 1: 전체 경로 명시

# mypackage/services/user_service.py

from mypackage.models.user import User
from mypackage.utils.validators import validate_email

패턴 2: 패키지 레벨 import

# mypackage/services/user_service.py

from mypackage import models
from mypackage import utils

user = models.User()

패턴 3: 선택적 import

from mypackage.models import User, Product, Category
from mypackage.services import (
    UserService,
    ProductService,
    CategoryService,
)

3.3 절대 경로의 장점 ✅

1. 명확성

# 어느 패키지에서 가져오는지 명확
from mypackage.models.user import User
# ← mypackage의 models 패키지의 user 모듈이라는 것이 분명

2. IDE 지원 우수

# 대부분의 IDE에서 자동완성, 리팩토링, 코드 탐색 지원 우수
from mypackage.models.user import User  # ← Ctrl+Click으로 이동 가능

3. 스크립트 직접 실행 가능

# mypackage/services/user_service.py
from mypackage.models.user import User

# ✅ 직접 실행 가능
# python mypackage/services/user_service.py

4. 프로젝트 전체 구조 파악 용이

# import 문만 봐도 전체 프로젝트 구조 이해 가능
from mypackage.api.v1.endpoints.users import UserEndpoint
from mypackage.database.repositories.user_repository import UserRepository
from mypackage.services.auth.jwt_service import JWTService

3.4 절대 경로의 단점 ⚠️

1. 패키지명 의존성

# mypackage → yourpackage로 변경 시
# 모든 절대 경로 import를 수정해야 함

# ❌ 수정 전
from mypackage.models import User

# ✅ 수정 후
from yourpackage.models import User

2. 패키지 이식성 저하

# 다른 프로젝트에 복사 시 모든 import 수정 필요
from mypackage.models import User  # 패키지명이 hard-coded됨

3. 타이핑 양 증가

# 상대 경로
from .models import User

# 절대 경로 (더 김)
from mypackage.models.user import User

4. 비교표

4.1 종합 비교

측면	상대 경로	절대 경로
재사용성	✅ 우수 (패키지명 독립)	❌ 나쁨 (패키지명 의존)
이식성	✅ 우수 (복사만 하면 됨)	❌ 나쁨 (import 수정 필요)
명확성	⚠️ 상대적 위치 파악 필요	✅ 우수 (전체 경로 명시)
IDE 지원	⚠️ 제한적	✅ 우수 (자동완성, 탐색)
직접 실행	❌ 불가	✅ 가능
순환 참조 감지	✅ 명확	⚠️ 어려움
타이핑 양	✅ 짧음	⚠️ 김
유지보수	✅ 우수 (구조 변경 용이)	⚠️ 보통
가독성 (얕은 구조)	✅ 우수	✅ 우수
가독성 (깊은 구조)	⚠️ 나쁨 (`....`)	✅ 우수
프로젝트 구조 파악	⚠️ 어려움	✅ 쉬움
성능	동일	동일

4.2 사용 위치별 권장

위치	권장 방식	이유
`__init__.py`	⭐ 상대 경로	패키지 내부 구조, 재사용성
개별 모듈 (같은 패키지)	⚠️ 상대 경로	패키지 내부 응집도
개별 모듈 (다른 패키지)	⭐ 절대 경로	명확성, IDE 지원
테스트 코드	⭐ 절대 경로	명확성, 직접 실행
스크립트/CLI	⭐ 절대 경로	직접 실행 가능
라이브러리 내부	⭐ 상대 경로	재사용성, 이식성
애플리케이션 코드	⭐ 절대 경로	명확성, 유지보수

5. 사용 시나리오별 권장사항

5.1 시나리오 1: `init.py` 파일 ⭐

권장: 상대 경로

# mypackage/__init__.py

# ✅ 권장: 상대 경로
from .models import User, Product
from .services import UserService, ProductService
from .utils import format_date, validate_email

# ❌ 비권장: 절대 경로
from mypackage.models import User, Product
from mypackage.services import UserService, ProductService

이유:

패키지명 변경 시 수정 불필요
패키지 재사용 용이
내부 구조가 명확

5.2 시나리오 2: 같은 패키지 내 모듈

권장: 상대 경로 또는 절대 경로 (팀 컨벤션 따름)

# mypackage/models/user.py

# ✅ 옵션 1: 상대 경로 (짧고 간결)
from .product import Product
from .category import Category

# ✅ 옵션 2: 절대 경로 (명확함)
from mypackage.models.product import Product
from mypackage.models.category import Category

선택 기준:

라이브러리/패키지 개발: 상대 경로
애플리케이션 개발: 절대 경로
팀 컨벤션 따르기

5.3 시나리오 3: 다른 패키지의 모듈 ⭐

권장: 절대 경로

# mypackage/services/user_service.py

# ✅ 권장: 절대 경로
from mypackage.models.user import User
from mypackage.utils.validators import validate_email
from mypackage.database.repositories import UserRepository

# ⚠️ 비권장: 상대 경로 (헷갈림)
from ..models.user import User
from ..utils.validators import validate_email
from ..database.repositories import UserRepository

이유:

어느 패키지인지 명확
IDE 지원 우수
리팩토링 시 안전

5.4 시나리오 4: 테스트 코드 ⭐

권장: 절대 경로

# tests/test_user_service.py

# ✅ 권장: 절대 경로
from mypackage.services.user_service import UserService
from mypackage.models.user import User

def test_create_user():
    service = UserService()
    user = User("John")
    # ...

# ❌ 비권장: 상대 경로 (테스트는 패키지 외부)
from ..mypackage.services.user_service import UserService  # 에러!

이유:

테스트는 패키지 외부에 위치
직접 실행 가능해야 함
명확성 중요

5.5 시나리오 5: CLI/스크립트 ⭐

권장: 절대 경로

# scripts/migrate_data.py

# ✅ 권장: 절대 경로
from mypackage.database import Database
from mypackage.models import User, Product

def main():
    db = Database()
    # ...

if __name__ == "__main__":
    main()

이유:

스크립트는 직접 실행됨
상대 경로는 작동 안함

5.6 시나리오 6: 라이브러리 개발 ⭐

권장: 상대 경로 (내부), 절대 경로 (외부 의존성)

# mylib/core/processor.py

# ✅ 내부 모듈: 상대 경로
from .validator import Validator
from ..utils.helpers import format_output

# ✅ 외부 라이브러리: 절대 경로 (당연)
import pandas as pd
from typing import List

이유:

라이브러리는 다른 프로젝트에서 재사용
내부 구조는 독립적이어야 함

5.7 시나리오 7: Django/Flask 애플리케이션 ⭐

권장: 절대 경로

# myapp/views/user_views.py

# ✅ 권장: 절대 경로
from myapp.models import User
from myapp.services.user_service import UserService
from myapp.forms import UserForm

# ⚠️ 비권장: 상대 경로
from ..models import User
from ..services.user_service import UserService

이유:

애플리케이션은 명확성이 중요
프로젝트 구조를 한눈에 파악
팀 협업 시 이해 쉬움

6. 실전 예시

6.1 예시 1: 라이브러리 패키지 (상대 경로 중심)

# mathlib/
# ├── __init__.py
# ├── core/
# │   ├── __init__.py
# │   ├── algebra.py
# │   └── calculus.py
# └── utils/
#     ├── __init__.py
#     └── helpers.py

# ============= mathlib/__init__.py =============
"""MathLib - 재사용 가능한 수학 라이브러리"""

__version__ = "1.0.0"

# ✅ 상대 경로 (패키지 내부)
from .core import Algebra, Calculus
from .utils import format_result

__all__ = ["Algebra", "Calculus", "format_result"]


# ============= mathlib/core/__init__.py =============
# ✅ 상대 경로
from .algebra import Algebra
from .calculus import Calculus

__all__ = ["Algebra", "Calculus"]


# ============= mathlib/core/algebra.py =============
# ✅ 상대 경로 (같은 패키지)
from .calculus import derivative

# ✅ 상대 경로 (상위 패키지)
from ..utils.helpers import format_result


class Algebra:
    def solve(self, x):
        result = derivative(x)
        return format_result(result)

장점:

패키지명 mathlib → mathlib2로 변경해도 내부 수정 불필요
다른 프로젝트에 복사해도 그대로 작동
내부 구조 변경 용이

6.2 예시 2: 웹 애플리케이션 (절대 경로 중심)

# myapp/
# ├── __init__.py
# ├── models/
# │   ├── __init__.py
# │   └── user.py
# ├── views/
# │   ├── __init__.py
# │   └── user_views.py
# ├── services/
# │   ├── __init__.py
# │   └── user_service.py
# └── utils/
#     ├── __init__.py
#     └── validators.py

# ============= myapp/__init__.py =============
"""MyApp - 웹 애플리케이션"""

__version__ = "1.0.0"

# ✅ 상대 경로 (최상위 __init__.py)
from .models import User
from .views import UserView

__all__ = ["User", "UserView"]


# ============= myapp/views/user_views.py =============
# ✅ 절대 경로 (명확성 우선)
from myapp.models.user import User
from myapp.services.user_service import UserService
from myapp.utils.validators import validate_email


class UserView:
    def __init__(self):
        self.service = UserService()
    
    def create_user(self, name: str, email: str):
        if not validate_email(email):
            raise ValueError("Invalid email")
        
        user = User(name, email)
        return self.service.save(user)


# ============= myapp/services/user_service.py =============
# ✅ 절대 경로
from myapp.models.user import User
from myapp.database import Database


class UserService:
    def __init__(self):
        self.db = Database()
    
    def save(self, user: User):
        return self.db.save(user)

장점:

코드 한눈에 이해 가능
IDE 지원 우수
리팩토링 안전

6.3 예시 3: 하이브리드 접근 (실용적)

# myproject/
# ├── __init__.py
# ├── core/
# │   ├── __init__.py
# │   ├── base.py
# │   └── config.py
# ├── features/
# │   ├── __init__.py
# │   ├── auth/
# │   │   ├── __init__.py
# │   │   ├── models.py
# │   │   └── services.py
# │   └── users/
# │       ├── __init__.py
# │       ├── models.py
# │       └── services.py
# └── utils/
#     ├── __init__.py
#     └── helpers.py

# ============= myproject/__init__.py =============
# ✅ 상대 경로 (패키지 루트)
from .core import Config
from .utils import helpers

__all__ = ["Config", "helpers"]


# ============= myproject/features/auth/__init__.py =============
# ✅ 상대 경로 (피처 패키지 내부)
from .models import AuthUser
from .services import AuthService

__all__ = ["AuthUser", "AuthService"]


# ============= myproject/features/auth/services.py =============
# ✅ 상대 경로 (같은 피처)
from .models import AuthUser

# ✅ 절대 경로 (다른 피처/모듈)
from myproject.core.base import BaseService
from myproject.utils.helpers import hash_password
from myproject.features.users.models import User


class AuthService(BaseService):
    def authenticate(self, username: str, password: str):
        hashed = hash_password(password)
        # ...

규칙:

__init__.py: 상대 경로
같은 피처/모듈 내: 상대 경로
다른 피처/모듈: 절대 경로
공통 유틸리티: 절대 경로

7. 흔한 실수와 해결방법

7.1 실수 1: `init.py`에서 절대 경로 사용

❌ 나쁜 예

# mypackage/__init__.py

from mypackage.models import User  # ❌ 절대 경로
from mypackage.services import UserService

문제:

패키지명 변경 시 수정 필요
재사용성 저하

✅ 좋은 예

# mypackage/__init__.py

from .models import User  # ✅ 상대 경로
from .services import UserService

7.2 실수 2: 스크립트에서 상대 경로 사용

❌ 나쁜 예

# scripts/migrate.py

from ..mypackage.models import User  # ❌ 에러!

에러:

ValueError: attempted relative import beyond top-level package

✅ 좋은 예

# scripts/migrate.py

from mypackage.models import User  # ✅ 절대 경로

# 또는 sys.path 조정
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent))

from mypackage.models import User

7.3 실수 3: 너무 많은 점 사용

❌ 나쁜 예

# mypackage/api/v1/endpoints/users/create.py

from ......models.user import User  # ❌ 6개의 점!
from .....services.user_service import UserService

문제:

가독성 극악
유지보수 어려움

✅ 좋은 예

# mypackage/api/v1/endpoints/users/create.py

from mypackage.models.user import User  # ✅ 절대 경로로
from mypackage.services.user_service import UserService

규칙: 3개 이상의 점이면 절대 경로로 전환 고려

7.4 실수 4: 혼용으로 인한 혼란

❌ 나쁜 예

# 파일 내에서 일관성 없이 혼용
from .models import User  # 상대 경로
from mypackage.services import UserService  # 절대 경로
from ..utils import helpers  # 상대 경로

✅ 좋은 예

# 일관성 있게 사용
from mypackage.models import User
from mypackage.services import UserService
from mypackage.utils import helpers

7.5 실수 5: 순환 참조 미감지

❌ 나쁜 예

# mypackage/models.py
from mypackage.services import validate  # (1)

class User:
    pass

# mypackage/services.py
from mypackage.models import User  # (2)

def validate(user: User):
    pass

문제: ImportError: cannot import name ...

✅ 해결 방법 1: 지연 import

# mypackage/models.py
class User:
    def validate(self):
        from mypackage.services import validate  # 함수 내부로
        return validate(self)

✅ 해결 방법 2: TYPE_CHECKING

# mypackage/services.py
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mypackage.models import User  # 타입 체크용만

def validate(user: "User"):  # 문자열로 타입 힌트
    pass

✅ 해결 방법 3: 구조 개선

# 공통 인터페이스를 별도 모듈로
# mypackage/interfaces.py
from typing import Protocol

class UserProtocol(Protocol):
    name: str
    email: str

# mypackage/services.py
from mypackage.interfaces import UserProtocol

def validate(user: UserProtocol):
    pass

8. 베스트 프랙티스

8.1 Golden Rules (황금 규칙)

규칙 1: `init.py`는 항상 상대 경로 ⭐

# ✅ ALWAYS
from .module import Class

# ❌ NEVER
from package.module import Class

규칙 2: 같은 패키지 내는 상대 경로 또는 절대 경로 (팀 컨벤션)

# ✅ 옵션 1: 상대 경로
from .other_module import Class

# ✅ 옵션 2: 절대 경로
from package.subpackage.other_module import Class

규칙 3: 다른 패키지는 절대 경로 ⭐

# ✅ ALWAYS
from package.other_package.module import Class

# ⚠️ 가능하지만 비권장
from ..other_package.module import Class

규칙 4: 테스트/스크립트는 절대 경로 ⭐

# ✅ ALWAYS
from package.module import Class

규칙 5: 3개 이상의 점이면 절대 경로로

# ❌ 나쁜 예
from ....module import Class

# ✅ 좋은 예
from package.module import Class

8.2 팀 컨벤션 예시

컨벤션 A: 라이브러리 스타일

# 규칙:
# - __init__.py: 상대 경로
# - 모든 내부 모듈: 상대 경로
# - 외부 라이브러리만 절대 경로

# mylib/__init__.py
from .core import Engine
from .utils import helpers

# mylib/core/processor.py
from .validator import Validator
from ..utils.helpers import format_output

컨벤션 B: 애플리케이션 스타일

# 규칙:
# - __init__.py: 상대 경로
# - 모든 애플리케이션 코드: 절대 경로
# - 명확성 우선

# myapp/__init__.py
from .models import User

# myapp/views/user_views.py
from myapp.models.user import User
from myapp.services.user_service import UserService

컨벤션 C: 하이브리드 스타일 (추천)

# 규칙:
# - __init__.py: 상대 경로
# - 같은 서브패키지: 상대 경로
# - 다른 서브패키지: 절대 경로

# myapp/__init__.py
from .core import Config

# myapp/features/auth/services.py
from .models import AuthUser  # 같은 auth 패키지
from myapp.core.base import BaseService  # 다른 패키지
from myapp.utils.helpers import hash_password

8.3 체크리스트

새 패키지 작성 시

__init__.py에서 상대 경로 사용했는가?
__all__을 정의했는가?
import 스타일이 일관성 있는가?
순환 참조가 없는가?
테스트 코드에서 절대 경로를 사용했는가?

코드 리뷰 시

__init__.py에서 절대 경로 사용했는가? (❌)
3개 이상의 점을 사용했는가? (❌)
같은 파일에서 혼용했는가? (❌)
스크립트에서 상대 경로 사용했는가? (❌)

9. 요약

9.1 간단 요약

상황	사용 방식
`__init__.py`	⭐ 상대 경로
같은 패키지 내	상대 경로 또는 절대 경로
다른 패키지	⭐ 절대 경로
테스트/스크립트	⭐ 절대 경로
라이브러리 개발	상대 경로 중심
애플리케이션 개발	절대 경로 중심

9.2 핵심 원칙

__init__.py는 항상 상대 경로
외부로 나갈 때는 절대 경로
일관성 유지가 가장 중요
팀 컨벤션을 따르기
3개 이상 점이면 절대 경로로

9.3 최종 권장사항

라이브러리 개발:

# ✅ 상대 경로 중심 (재사용성)
from .module import Class

애플리케이션 개발:

# ✅ 절대 경로 중심 (명확성)
from myapp.module import Class

하이브리드 (실용적):

# __init__.py: 상대 경로
from .module import Class

# 개별 모듈: 절대 경로 (다른 패키지)
from myapp.other_package import Class

10. 참고 자료

공식 문서

Homepage Renewal

Mon, 08 Sep 2025 00:00:00 +0000

“Homepage Renewal”

VCANUS leverages real-time analytics, Edge AI, and digital twins to enable smarter decision-making, streamlined automation, and enhanced precision across industries.

Company History

Sat, 10 May 2025 00:00:00 +0000

History of Certifications and Designations

Date	Achievement
May 10, 2025	Renewal of Inno-Biz certification
Apr 09, 2025	Renewal of Venture Company designation
Dec 13, 2024	Certified as Performance-Sharing Company
Dec 11, 2023	Signed cooperation with SEOULTECH
Oct 01, 2023	Designated as Talent-Nurturing SME
Oct 21, 2022	Certified as Performance-Sharing Company
May 10, 2022	Designated as Inno-Biz
Jan 08, 2022	Joined Tomorrow’s Hope Savings program
Oct 06, 2021	Certified as Performance-Sharing Company
Jun 15, 2021	Registered as AI data analysis supplier
Jun 03, 2021	Registered as Startup Company
Mar 30, 2021	Registered as Smart Factory Provider
Dec 11, 2020	Issued Direct Production Certificate
Nov 25, 2020	Registered as Software Business
Sep 29, 2020	Participated in Youth Digital Job Program
Apr 20, 2020	Designated as Venture Company
Mar 31, 2020	Certified as Performance-Sharing Company
Mar 30, 2020	Certified as Future Performance-Sharing Co.
Mar 30, 2020	Relocated to Korea Robot Institute
Feb 10, 2020	Joined Youth Tomorrow Savings program
Sep 23, 2019	Established Corporate Research Institute
Jun 14, 2019	Registered for PPS Bidding Qualification
May 01, 2019	Established Research Department
Dec 03, 2018	VCANUS Co., Ltd. opened
Nov 19, 2018	VCANUS Co., Ltd. incorporated

비카누스 인증 및 등록 내용

날짜	내용
2025.05.10	기술혁신형 중소기업 연장 (Inno-Biz)
2025.04.09	벤처기업 연장
2024.12.13	성과공유도입기업 인증 (성과보상공제, 중소벤처기업부)
2023.12.11	산학협정 체결 (서울과학기술대학교)
2023.10.01	인재육성형 중소기업 지정 (중소벤처기업부)
2022.10.21	성과공유도입기업 인증 (성과급지급, 중소벤처기업부)
2022.05.10	기술혁신형 중소기업 지정 (Inno-Biz)
2022.01.08	내일채움공제 가입
2021.10.06	성과공유도입기업 인증 (성과급지급, 중소벤처기업부)
2021.06.15	AI기반 제조데이터 분석솔루션 공급기업 등록
2021.06.03	중소벤처기업부 창업기업 등록
2021.03.30	스마트 팩토리 공급기업 풀 등록
2020.12.11	직접생산확인증명서 발급
2020.11.25	SW 사업자 신고
2020.09.29	청년디지털 일자리사업 참여
2020.04.20	벤처기업 인정
2020.03.31	성과공유도입기업 인증 (성과급지급/성과보상공제, 중소벤처기업부)
2020.03.30	미래성과공유기업 인증 (중소벤처기업부)
2020.03.30	한국로봇산업진흥원 입주
2020.02.10	청년내일채움공제 가입
2019.09.23	기업부설연구소 설립
2019.06.14	나라장터 경쟁입찰참가자격 등록
2019.05.01	연구전담부서 설립
2018.12.03	주식회사 비카누스 개업
2018.11.19	주식회사 비카누스 설립 (법인등기)

Founded in November 2018

Mon, 19 Nov 2018 00:00:00 +0000

“Turning Data into Intelligence. One Byte at a Time.”

Founded in November 2018, VCANUS drives innovation through real-time analytics, Edge AI, and digital twins. Our solutions empower industries with smarter decisions, seamless automation, and unmatched precision.

Data Innovator

Serena Ubuntu

Serena MCP Server 설치 가이드 (Ubuntu)

사전 요구사항

uv 설치 (없으면)

설치

Claude Code MCP 등록

연결 확인

제거

참고

Serena MCP 및 Claude 연동

Serena MCP 연동 가이드

목차

1. Serena 개요

Serena란?

주요 기능

Claude Code에서 Serena가 필요한 이유

2. 사전 요구사항

필수 항목

uv 설치

설치 확인

3. Serena 설치

방법 A: uvx로 직접 실행 (권장)

방법 B: 로컬 설치

4. Claude Code CLI 연동

방법 A: uvx로 직접 실행 (권장)

방법 B: 로컬 설치 버전 사용

설정 파일 직접 편집

연결 확인

5. Claude Desktop 연동

설정 파일 위치

설정 파일 편집

uv 경로 확인

재시작

6. 설정 옵션 상세

–context 옵션

–project 관련 옵션

Scope 옵션 (Claude Code CLI)

7. 사용 예시

기본 사용

시맨틱 코드 분석

리팩토링

여러 프로젝트 연동 분석

8. 트러블슈팅

프로젝트에서 Serena가 인식되지 않음

MCP 서버 연결 실패

Claude Desktop에서 Serena 인식 안 됨

Language Server 관련 오류

로컬 버전 업데이트

9. 참고 자료

공식 문서

설정 파일 위치 요약

JetBrains MCP와 함께 사용

부록: 빠른 시작 체크리스트

Claude CLI 설치 및 MCP 서버 설정

Claude Code CLI + JetBrains IDE 연동 가이드

목차

1. 개요

아키텍처

이 조합의 장점

2. 사전 요구사항

필수 항목

Node.js 설치 확인

3. Claude Code CLI 설치

3.1 전역 설치

3.2 설치 확인

3.3 첫 실행 및 인증

3.4 인증 상태 확인

4. JetBrains MCP 서버 활성화

4.1 IDE에서 MCP 서버 활성화

4.2 자동 설정 (권장)

4.3 Brave Mode 설정 (선택)

5. Claude Code CLI와 JetBrains 연결

5.1 MCP 서버 추가 (CLI 방식)

5.2 User Scope로 추가 (모든 프로젝트에서 사용)

5.3 설정 파일 직접 편집 (대안)

5.4 특정 IDE 포트 지정 (여러 IDE 사용 시)

6. 연결 확인 및 테스트

6.1 MCP 서버 목록 확인

6.2 연결 테스트