Claude Code 클라우드 서버 배포 가이드

이 가이드는 클라우드 서버에 VitePress 프로젝트를 배포하고 PM2를 사용하여 프로세스를 관리하며, SSH 연결이 끊어진 후에도 서비스가 계속 실행되도록 하는 방법을 자세히 설명합니다.

🛠 환경 요구사항

운영 체제: Linux (Ubuntu/CentOS)
Node.js: v22.11.0 (/www/server/nodejs/v22.11.0/bin에 설치됨)
PM2: 프로세스 관리자
메모리: 최소 512MB
저장 공간: 최소 1GB 사용 가능한 공간

📋 배포 단계

1. 서버 환경 구성

1.1 Node.js 환경 변수 구성

bash

# ~/.bashrc 또는 ~/.profile에 추가
echo 'export PATH=$PATH:/www/server/nodejs/v22.11.0/bin' >> ~/.bashrc
source ~/.bashrc

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

1.2 프로젝트 디렉터리 생성

bash

# 프로젝트 디렉터리 생성
mkdir -p /www/wwwroot/claudecode
cd /www/wwwroot/claudecode

2. 프로젝트 파일 업로드

2.1 SCP를 사용한 업로드 (권장)

bash

# 로컬에서 실행 (your-server-ip를 실제 IP로 교체)
scp -r /c:/Users/PC/Desktop/claudecode.blueshirtmap.com_eN7Pt/* root@your-server-ip:/www/wwwroot/claudecode/

2.2 Git 클론 사용 (Git 저장소가 있는 경우)

bash

# 서버에서 실행
git clone https://github.com/your-username/claudecode.git .

3. 프로젝트 의존성 설치

bash

# 프로젝트 디렉터리로 이동
cd /www/wwwroot/claudecode

# 프로젝트 의존성 설치
npm install

# 권한 문제가 발생하는 경우, 다음 명령 사용
npm install --unsafe-perm

4. 프로덕션 버전 빌드

bash

# 프로젝트 빌드
npm run docs:build

# 빌드 결과 확인
ls -la .vitepress/dist/

5. PM2 설치 및 구성

5.1 PM2 전역 설치

bash

npm install -g pm2

# 설치 확인
pm2 --version

5.2 PM2 구성 파일 생성

bash

# PM2 구성 파일 생성
cat > ecosystem.config.js << 'EOF'
module.exports = {
  apps: [
    {
      name: 'claudecode-docs',
      script: 'npm',
      args: 'run docs:preview',
      cwd: '/www/wwwroot/claudecode',
      instances: 1,
      exec_mode: 'fork',
      env: {
        NODE_ENV: 'production',
        PORT: 4173
      },
      error_file: '/www/wwwroot/claudecode/logs/err.log',
      out_file: '/www/wwwroot/claudecode/logs/out.log',
      log_file: '/www/wwwroot/claudecode/logs/combined.log',
      time: true,
      restart_delay: 1000,
      max_restarts: 5,
      min_uptime: '10s',
      max_memory_restart: '1G',
      watch: false,
      ignore_watch: ['node_modules', 'logs', '.git']
    }
  ]
}
EOF

5.3 로그 디렉터리 생성

bash

mkdir -p /www/wwwroot/claudecode/logs

6. 서비스 시작

6.1 PM2를 사용하여 프로젝트 시작

bash

# 서비스 시작
pm2 start ecosystem.config.js

# 서비스 상태 확인
pm2 status

# 로그 확인
pm2 logs claudecode-docs

6.2 PM2 자동 시작 설정

bash

# PM2 구성 저장
pm2 save

# 자동 시작 설정
pm2 startup
# 위 명령의 출력 명령 실행 (일반적으로 sudo 명령)

7. 리버스 프록시 구성 (선택사항)

도메인을 사용하여 액세스해야 하는 경우 Nginx 리버스 프록시를 구성할 수 있습니다:

7.1 Nginx 구성 예제

nginx

server {
    listen 80;
    server_name claudecode.blueshirtmap.com;
    
    location / {
        proxy_pass http://localhost:4173;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 정적 파일 캐싱
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            proxy_pass http://localhost:4173;
        }
    }
}

8. 배포 검증

8.1 서비스 상태 확인

bash

# PM2 상태 확인
pm2 status

# 프로세스 세부 정보 확인
pm2 show claudecode-docs

# 실시간 로그 확인
pm2 logs claudecode-docs --lines 50

8.2 웹사이트 접근 테스트

bash

# 로컬 테스트
curl -I http://localhost:4173

# 원격 테스트 (실제 IP로 교체)
curl -I http://your-server-ip:4173

🔧 일반적인 PM2 관리 명령

기본 명령

bash

# 모든 프로세스 확인
pm2 list

# 서비스 재시작
pm2 restart claudecode-docs

# 서비스 중지
pm2 stop claudecode-docs

# 서비스 삭제
pm2 delete claudecode-docs

# 구성 다시 로드
pm2 reload claudecode-docs

로그 관리

bash

# 로그 확인
pm2 logs claudecode-docs

# 로그 지우기
pm2 flush claudecode-docs

# 실시간 로그
pm2 logs claudecode-docs --lines 100 -f

모니터링 명령

bash

# 실시간 모니터링
pm2 monit

# 메모리 사용량 확인
pm2 show claudecode-docs

🚀 성능 최적화 제안

1. 정적 파일 배포 (권장)

bash

# Nginx를 사용하는 경우 정적 파일을 직접 배포할 수 있음
cp -r .vitepress/dist/* /www/wwwroot/claudecode-static/

2. Gzip 압축 활성화

nginx

# Nginx 구성에 추가
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;

3. PM2 구성 조정

javascript

// 서버 성능에 따라 조정
instances: 'max',  // 모든 CPU 코어 사용
max_memory_restart: '500M',  // 사용 가능한 메모리에 따라 조정

🛡️ 보안 구성

1. 방화벽 구성

bash

# 필요한 포트 열기
ufw allow 22    # SSH
ufw allow 80    # HTTP
ufw allow 443   # HTTPS
ufw allow 4173  # VitePress (직접 액세스하는 경우)

2. 프로세스 권한

bash

# 전용 사용자 생성 (선택사항)
useradd -m -s /bin/bash claudecode
chown -R claudecode:claudecode /www/wwwroot/claudecode

📊 모니터링 및 유지보수

1. 정기 백업

bash

# 백업 스크립트 생성
cat > /root/backup-claudecode.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
tar -czf /backup/claudecode_$DATE.tar.gz /www/wwwroot/claudecode
find /backup -name "claudecode_*.tar.gz" -mtime +7 -delete
EOF

chmod +x /root/backup-claudecode.sh

# 예약 작업에 추가
crontab -e
# 추가: 0 2 * * * /root/backup-claudecode.sh

2. 로그 순환

bash

# logrotate 구성
cat > /etc/logrotate.d/claudecode << 'EOF'
/www/wwwroot/claudecode/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        pm2 reloadLogs
    endscript
}
EOF

🐛 일반적인 문제 해결

1. 포트 점유

bash

# 포트 점유 확인
netstat -tlnp | grep 4173
lsof -i :4173

# 점유 프로세스 종료
kill -9 <PID>

2. 권한 문제

bash

# 권한 수정
chown -R $USER:$USER /www/wwwroot/claudecode
chmod -R 755 /www/wwwroot/claudecode

3. 메모리 부족

bash

# 메모리 사용량 확인
free -h
pm2 show claudecode-docs

# 서비스 재시작으로 메모리 해제
pm2 restart claudecode-docs

4. 빌드 실패

bash

# 캐시 정리 후 재빌드
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run docs:build

📞 배포 후 확인 체크리스트

[ ] ✅ Node.js 환경이 올바르게 구성됨
[ ] ✅ 프로젝트 파일이 성공적으로 업로드됨
[ ] ✅ 의존성 설치 완료
[ ] ✅ 프로젝트 빌드 성공
[ ] ✅ PM2가 정상적으로 실행됨
[ ] ✅ 서비스에 정상적으로 액세스 가능
[ ] ✅ 로그 출력이 정상임
[ ] ✅ 자동 시작 설정 완료
[ ] ✅ 리버스 프록시 구성 (필요한 경우)
[ ] ✅ 방화벽 및 보안 구성

위 단계를 완료하면 Claude Code 문서 웹사이트가 클라우드 서버에서 안정적으로 실행되며, SSH 연결이 끊어져도 서비스에 영향을 주지 않습니다.

Claude Code 클라우드 서버 배포 가이드 ​

🛠 환경 요구사항 ​

📋 배포 단계 ​

1. 서버 환경 구성 ​

1.1 Node.js 환경 변수 구성 ​

1.2 프로젝트 디렉터리 생성 ​

2. 프로젝트 파일 업로드 ​

2.1 SCP를 사용한 업로드 (권장) ​

2.2 Git 클론 사용 (Git 저장소가 있는 경우) ​

3. 프로젝트 의존성 설치 ​

4. 프로덕션 버전 빌드 ​

5. PM2 설치 및 구성 ​

5.1 PM2 전역 설치 ​

5.2 PM2 구성 파일 생성 ​

5.3 로그 디렉터리 생성 ​

6. 서비스 시작 ​

6.1 PM2를 사용하여 프로젝트 시작 ​

6.2 PM2 자동 시작 설정 ​

7. 리버스 프록시 구성 (선택사항) ​

7.1 Nginx 구성 예제 ​

8. 배포 검증 ​

8.1 서비스 상태 확인 ​

8.2 웹사이트 접근 테스트 ​

🔧 일반적인 PM2 관리 명령 ​

기본 명령 ​

로그 관리 ​

모니터링 명령 ​

🚀 성능 최적화 제안 ​

1. 정적 파일 배포 (권장) ​

2. Gzip 압축 활성화 ​

3. PM2 구성 조정 ​

🛡️ 보안 구성 ​

1. 방화벽 구성 ​

2. 프로세스 권한 ​

📊 모니터링 및 유지보수 ​

1. 정기 백업 ​

2. 로그 순환 ​

🐛 일반적인 문제 해결 ​

1. 포트 점유 ​

2. 권한 문제 ​

3. 메모리 부족 ​

4. 빌드 실패 ​

📞 배포 후 확인 체크리스트 ​

Claude Code 클라우드 서버 배포 가이드

🛠 환경 요구사항

📋 배포 단계

1. 서버 환경 구성

1.1 Node.js 환경 변수 구성

1.2 프로젝트 디렉터리 생성

2. 프로젝트 파일 업로드

2.1 SCP를 사용한 업로드 (권장)

2.2 Git 클론 사용 (Git 저장소가 있는 경우)

3. 프로젝트 의존성 설치

4. 프로덕션 버전 빌드

5. PM2 설치 및 구성

5.1 PM2 전역 설치

5.2 PM2 구성 파일 생성

5.3 로그 디렉터리 생성

6. 서비스 시작

6.1 PM2를 사용하여 프로젝트 시작

6.2 PM2 자동 시작 설정

7. 리버스 프록시 구성 (선택사항)

7.1 Nginx 구성 예제

8. 배포 검증

8.1 서비스 상태 확인

8.2 웹사이트 접근 테스트

🔧 일반적인 PM2 관리 명령

기본 명령

로그 관리

모니터링 명령

🚀 성능 최적화 제안

1. 정적 파일 배포 (권장)

2. Gzip 압축 활성화

3. PM2 구성 조정

🛡️ 보안 구성

1. 방화벽 구성

2. 프로세스 권한

📊 모니터링 및 유지보수

1. 정기 백업

2. 로그 순환

🐛 일반적인 문제 해결

1. 포트 점유

2. 권한 문제

3. 메모리 부족

4. 빌드 실패

📞 배포 후 확인 체크리스트