sam-docs/dev/deploys/ops-manual/11-server-setup.md

11. 서버 설치 가이드

목차로 돌아가기

---

[운영] 설치 순서

순서	항목	의존성
①	OS 기본 셋팅 (UFW, 스왑, 타임존)	-
②	MySQL 8.4	①
③	Redis 7.x	①
④	Nginx + Certbot	①
⑤	PHP 8.4 + Composer	①
⑥	Supervisor (Queue Worker)	⑤
⑦	Laravel API 배포 (api, api-stage, mng)	②③⑤
⑧	Sales 배포	⑤
⑨	Node.js 22 + PM2 (react, react-stage)	①
⑩	SSL 인증서 (Let's Encrypt)	④
⑪	node_exporter	①
⑫	fail2ban	①
⑬	최종 점검	전체

---

① OS 기본 셋팅

# 시스템 업데이트
sudo apt update && sudo apt upgrade -y

# 기본 패키지
sudo apt install -y curl wget git unzip vim htop net-tools

# 타임존
sudo timedatectl set-timezone Asia/Seoul

# 스왑 4GB 설정
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 스왑 최적화
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# UFW 방화벽
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow from 110.10.147.46 to any port 9100  # node_exporter (CI/CD만)
sudo ufw allow from 110.10.147.46 to any port 3306  # MySQL (CI/CD 백업용)
sudo ufw enable

# webservice 사용자 그룹 생성
sudo groupadd -f webservice
sudo usermod -aG webservice hskwon
sudo usermod -aG webservice www-data
sudo mkdir -p /home/webservice
sudo chown hskwon:webservice /home/webservice
sudo chmod 2775 /home/webservice  # setgid

② MySQL 8.4

# mysql-apt-config deb로 repo 등록
sudo wget https://dev.mysql.com/get/mysql-apt-config_0.8.33-1_all.deb
sudo DEBIAN_FRONTEND=noninteractive dpkg -i mysql-apt-config_0.8.33-1_all.deb

# GPG 키 만료 시 — Ubuntu keyserver에서 갱신
sudo gpg --keyserver keyserver.ubuntu.com --recv-keys B7B3B788A8D3785C
sudo gpg --export B7B3B788A8D3785C | sudo tee /usr/share/keyrings/mysql-apt-config.gpg > /dev/null

# 설치
sudo apt update
sudo apt install -y mysql-server

성능 튜닝 (/etc/mysql/mysql.conf.d/sam-tuning.cnf):

[mysqld]
innodb_buffer_pool_size = 2048M
innodb_log_file_size = 512M
innodb_flush_log_at_trx_commit = 2
max_connections = 100
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2
validate_password.policy = LOW

DB 및 사용자:

-- 데이터베이스 (4개)
CREATE DATABASE sam CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE sam_stage CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE sam_stat CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE codebridge CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 앱 사용자
CREATE USER 'codebridge'@'localhost' IDENTIFIED BY '<비밀번호>';
GRANT ALL PRIVILEGES ON sam.* TO 'codebridge'@'localhost';
GRANT ALL PRIVILEGES ON sam_stage.* TO 'codebridge'@'localhost';
GRANT ALL PRIVILEGES ON sam_stat.* TO 'codebridge'@'localhost';
GRANT ALL PRIVILEGES ON codebridge.* TO 'codebridge'@'localhost';

-- 관리자 (auth_socket)
CREATE USER 'hskwon'@'localhost' IDENTIFIED WITH auth_socket;
GRANT ALL PRIVILEGES ON *.* TO 'hskwon'@'localhost' WITH GRANT OPTION;

-- CI/CD 서버 백업용
CREATE USER 'sam_backup'@'110.10.147.46' IDENTIFIED BY '<백업용_비밀번호>';
GRANT SELECT, LOCK TABLES, SHOW VIEW, EVENT, TRIGGER ON sam.* TO 'sam_backup'@'110.10.147.46';
GRANT SELECT, LOCK TABLES, SHOW VIEW, EVENT, TRIGGER ON sam_stat.* TO 'sam_backup'@'110.10.147.46';

FLUSH PRIVILEGES;

③ Redis 7.x

sudo apt install -y redis-server

# /etc/redis/redis.conf 설정:
# bind 127.0.0.1 ::1
# maxmemory 512mb
# maxmemory-policy allkeys-lru
# supervised systemd

sudo systemctl enable redis-server
sudo systemctl restart redis-server
redis-cli ping  # → PONG

④ Nginx + Certbot

sudo apt install -y nginx certbot python3-certbot-nginx

보안 스니펫 (/etc/nginx/snippets/security.conf):

# 숨김 파일 차단 (.env, .git 등)
location ~ /\. {
    deny all;
    access_log off;
    log_not_found off;
}

# 환경설정/백업/로그 파일 차단
location ~* \.(env|ini|log|conf|bak|sql)$ {
    deny all;
    access_log off;
    log_not_found off;
}

# Composer, Node 패키지 등 민감 파일 차단
location ~* /(composer\.(json|lock)|package\.json|yarn\.lock|phpunit\.xml|artisan|server\.php)$ {
    deny all;
    access_log off;
    log_not_found off;
}

기본 설정 (/etc/nginx/nginx.conf):

worker_processes auto;
events {
    worker_connections 1024;
}
http {
    keepalive_timeout 65;
    client_max_body_size 50M;
    gzip on;
    gzip_types text/plain application/json application/javascript text/css;
}

⑤ PHP 8.4 + Composer

sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

sudo apt install -y \
  php8.4-fpm php8.4-mysql php8.4-mbstring php8.4-xml \
  php8.4-curl php8.4-zip php8.4-gd php8.4-bcmath \
  php8.4-intl php8.4-redis php8.4-opcache php8.4-soap

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

PHP-FPM Pool 설정 (4개):

Pool	설정 파일	소켓	max_children
api	/etc/php/8.4/fpm/pool.d/api.conf	php8.4-fpm-api.sock	10
admin	/etc/php/8.4/fpm/pool.d/admin.conf	php8.4-fpm-admin.sock	5
sales	/etc/php/8.4/fpm/pool.d/sales.conf	php8.4-fpm-sales.sock	3
api-stage	/etc/php/8.4/fpm/pool.d/api-stage.conf	php8.4-fpm-api-stage.sock	3

Pool 설정 템플릿 (api.conf 예시):

[api]
user = www-data
group = webservice
listen = /run/php/php8.4-fpm-api.sock
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 10
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
pm.max_requests = 500
php_admin_value[memory_limit] = 128M
php_admin_value[upload_max_filesize] = 50M
php_admin_value[post_max_size] = 50M
php_admin_value[display_errors] = Off

# 기본 pool 제거, 분리된 pool 사용
sudo rm /etc/php/8.4/fpm/pool.d/www.conf
sudo systemctl restart php8.4-fpm

⑥ Supervisor (Queue Worker)

sudo apt install -y supervisor

sudo tee /etc/supervisor/conf.d/sam-queue.conf > /dev/null << 'EOF'
[program:sam-queue-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/webservice/api/current/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/home/webservice/api/shared/storage/logs/queue-worker.log
stopwaitsecs=3600
EOF

sudo supervisorctl reread
sudo supervisorctl update

⑦ Laravel 배포 (API / API-Stage / MNG)

디렉토리 구조 생성:

# API 운영
sudo mkdir -p /home/webservice/api/{releases,shared/storage/{app/public,framework/{cache,sessions,views},logs}}
sudo chown -R hskwon:webservice /home/webservice/api
sudo chmod -R 2775 /home/webservice/api

# API Stage
sudo mkdir -p /home/webservice/api-stage/{releases,shared/storage/{app/public,framework/{cache,sessions,views},logs}}
sudo chown -R hskwon:webservice /home/webservice/api-stage
sudo chmod -R 2775 /home/webservice/api-stage

# MNG (Admin)
sudo mkdir -p /home/webservice/mng/{releases,shared/storage/{app/public,framework/{cache,sessions,views},logs}}
sudo chown -R hskwon:webservice /home/webservice/mng
sudo chmod -R 2775 /home/webservice/mng

초기 배포 절차:

# shared 심링크 연결
ln -sfn /home/webservice/api/shared/storage /home/webservice/api/current/storage
ln -sfn /home/webservice/api/shared/.env /home/webservice/api/current/.env

# 의존성 설치 + 최적화
cd /home/webservice/api/current
composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan migrate --force

⑧ Sales 배포

sudo mkdir -p /home/webservice/sales
sudo chown -R hskwon:webservice /home/webservice/sales

cd /home/webservice
git clone <repo_url> sales
cp /home/webservice/sales/.env.example /home/webservice/sales/.env
chmod 600 /home/webservice/sales/.env
chmod 775 /home/webservice/sales/uploads

⑨ Node.js 22 + PM2

# Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# PM2 설치
sudo npm install -g pm2

# 운영 + Stage 디렉토리
sudo mkdir -p /home/webservice/react/{releases,shared}
sudo mkdir -p /home/webservice/react-stage/{releases,shared}
sudo chown -R hskwon:webservice /home/webservice/react /home/webservice/react-stage

PM2 설정 (/home/webservice/ecosystem.config.js):

module.exports = {
  apps: [
    {
      name: 'sam-front',
      cwd: '/home/webservice/react/current',
      script: 'node_modules/next/dist/bin/next',
      args: 'start -p 3000',
      instances: 2,
      exec_mode: 'cluster',
      max_memory_restart: '300M',
      env: {
        NODE_ENV: 'production',
        NODE_OPTIONS: '--max-old-space-size=256'
      }
    },
    {
      name: 'sam-front-stage',
      cwd: '/home/webservice/react-stage/current',
      script: 'node_modules/next/dist/bin/next',
      args: 'start -p 3100',
      instances: 1,
      exec_mode: 'fork',
      max_memory_restart: '512M',
      env: {
        NODE_ENV: 'production',
        NODE_OPTIONS: '--max-old-space-size=384'
      }
    }
  ]
};

cd /home/webservice
pm2 start ecosystem.config.js
pm2 save
pm2 startup

⑩ SSL 인증서

# Nginx 사이트 활성화
sudo ln -s /etc/nginx/sites-available/sam.it.kr /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/api.sam.it.kr /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/mng.codebridge-x.com /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/sales.codebridge-x.com /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/codebridge-x.com /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/stage.sam.it.kr /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/stage-api.sam.it.kr /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# SSL 인증서 발급
sudo certbot --nginx -d sam.it.kr --email develop@codebridge-x.com
sudo certbot --nginx -d api.sam.it.kr --email develop@codebridge-x.com
sudo certbot --nginx -d stage.sam.it.kr --email develop@codebridge-x.com
sudo certbot --nginx -d stage-api.sam.it.kr --email develop@codebridge-x.com
sudo certbot --nginx -d mng.codebridge-x.com --email develop@codebridge-x.com
sudo certbot --nginx -d sales.codebridge-x.com --email develop@codebridge-x.com
sudo certbot --nginx -d codebridge-x.com -d www.codebridge-x.com --email develop@codebridge-x.com

# 자동 갱신 확인
sudo certbot renew --dry-run

⑪ node_exporter

cd /tmp
wget https://github.com/prometheus/node_exporter/releases/download/v1.8.2/node_exporter-1.8.2.linux-amd64.tar.gz
tar xzf node_exporter-1.8.2.linux-amd64.tar.gz
sudo mv node_exporter-1.8.2.linux-amd64/node_exporter /usr/local/bin/
rm -rf node_exporter-1.8.2*

sudo tee /etc/systemd/system/node_exporter.service > /dev/null << 'EOF'
[Unit]
Description=Node Exporter
After=network.target

[Service]
User=nobody
ExecStart=/usr/local/bin/node_exporter
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable node_exporter
sudo systemctl start node_exporter

⑫ fail2ban

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

---

Nginx 사이트 설정 템플릿

sam.it.kr (Next.js 운영)

upstream nextjs_prod {
    server 127.0.0.1:3000;
    keepalive 32;
}

server {
    listen 80;
    server_name sam.it.kr;

    access_log /var/log/nginx/sam.it.kr.access.log;
    error_log /var/log/nginx/sam.it.kr.error.log;

    location /_next/static/ {
        alias /home/webservice/react/current/.next/static/;
        expires 365d;
        add_header Cache-Control "public, immutable";
    }

    location / {
        proxy_pass http://nextjs_prod;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

api.sam.it.kr (Laravel API)

server {
    listen 80;
    server_name api.sam.it.kr;

    root /home/webservice/api/current/public;
    index index.php;

    access_log /var/log/nginx/api.sam.it.kr.access.log;
    error_log /var/log/nginx/api.sam.it.kr.error.log;

    include /etc/nginx/snippets/security.conf;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.4-fpm-api.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 60;
    }

    client_max_body_size 50M;
}

mng.codebridge-x.com (Laravel Admin)

server {
    listen 80;
    server_name mng.codebridge-x.com;

    root /home/webservice/mng/current/public;
    index index.php;

    access_log /var/log/nginx/mng.codebridge-x.com.access.log;
    error_log /var/log/nginx/mng.codebridge-x.com.error.log;

    include /etc/nginx/snippets/security.conf;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.4-fpm-admin.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 60;
    }

    client_max_body_size 50M;
}

sales.codebridge-x.com (Plain PHP)

server {
    listen 80;
    server_name sales.codebridge-x.com;

    root /home/webservice/sales;
    index index.php index.html;

    access_log /var/log/nginx/sales.codebridge-x.com.access.log;
    error_log /var/log/nginx/sales.codebridge-x.com.error.log;

    include /etc/nginx/snippets/security.conf;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.4-fpm-sales.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 60;
    }

    # uploads PHP 실행 차단 (보안)
    location ~* /uploads/.*\.php$ {
        deny all;
    }

    client_max_body_size 50M;
}

stage.sam.it.kr / stage-api.sam.it.kr

stage.sam.it.kr은 sam.it.kr과 동일 구조 (upstream 포트: 3100). stage-api.sam.it.kr은 api.sam.it.kr과 동일 구조 (소켓: php8.4-fpm-api-stage.sock, root: api-stage).

---

[CI/CD] 설치 순서

순서	항목	의존성
①	OS 기본 셋팅 (UFW, 스왑, 타임존)	-
②	MySQL 8.4	①
③	Java 21 (Jenkins 런타임)	①
④	Gitea	②
⑤	개발서버 post-receive hook 설정	④
⑥	Jenkins	③
⑦	Nginx + SSL	④⑥
⑧	Prometheus + node_exporter	①
⑨	Grafana	⑧
⑩	Jenkins 파이프라인 + Webhook	⑥⑦
⑪	백업 자동화 (운영 DB 원격 백업)	②
⑫	fail2ban + 최종 점검	전체

---

① OS 기본 셋팅

운영서버와 동일. 차이점:

• UFW: 22, 80, 443만 허용 (9100, 3306 불필요)
• webservice 그룹 생성 (배포 스크립트용)

② MySQL 8.4

운영서버와 동일한 설치 방법. 튜닝 차이:

[mysqld]
innodb_buffer_pool_size = 1536M       # 운영(2048M)보다 작음
innodb_redo_log_capacity = 536870912
innodb_flush_log_at_trx_commit = 2
max_connections = 50                   # 운영(100)보다 작음

DB 및 사용자:

-- Gitea DB
CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'gitea'@'localhost' IDENTIFIED BY '<gitea_비밀번호>';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';

-- 관리자
CREATE USER 'hskwon'@'localhost' IDENTIFIED WITH auth_socket;
GRANT ALL PRIVILEGES ON *.* TO 'hskwon'@'localhost' WITH GRANT OPTION;

FLUSH PRIVILEGES;

③ Java 21

sudo apt install -y openjdk-21-jre-headless
java -version
# openjdk version "21.0.x" 확인

# 여러 버전 설치 시 기본 Java 전환
sudo update-alternatives --set java /usr/lib/jvm/java-21-openjdk-amd64/bin/java

참고: Java 17은 2026-03-31 Jenkins 지원 종료. Java 21 사용 필수.

④ Gitea

GITEA_VERSION="1.22.6"
wget -O /tmp/gitea https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64
sudo mv /tmp/gitea /usr/local/bin/gitea
sudo chmod +x /usr/local/bin/gitea

sudo adduser --system --group --disabled-password --shell /bin/bash --home /home/git git

sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo mkdir -p /etc/gitea
sudo chown -R git:git /var/lib/gitea
sudo chown git:git /etc/gitea
sudo chmod 750 /etc/gitea

systemd 서비스:

# /etc/systemd/system/gitea.service
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target network.target mysql.service

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea
RestartSec=10

[Install]
WantedBy=multi-user.target

Gitea 설정 (/etc/gitea/app.ini):

[server]
DOMAIN           = git.sam.it.kr
HTTP_PORT        = 3000
ROOT_URL         = https://git.sam.it.kr/
DISABLE_SSH      = false
SSH_PORT         = 22
LFS_START_SERVER = true

[database]
DB_TYPE  = mysql
HOST     = 127.0.0.1:3306
NAME     = gitea
USER     = gitea
PASSWD   = <gitea_비밀번호>
CHARSET  = utf8mb4

[repository]
ROOT = /var/lib/gitea/data/repositories

[log]
ROOT_PATH = /var/lib/gitea/log
MODE      = file
LEVEL     = info

[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW  = true

초기 설정:

1. https://git.sam.it.kr 웹 설치 마법사 완료
2. 관리자 계정 생성 (hskwon)
3. Organization "SamProject" 생성
4. 저장소 생성: sam-api, sam-manage, sam-react-prod, sam-sales, sam-landing
5. Jenkins Webhook용 API 토큰 생성

⑤ 개발서버 post-receive hook (선택적 브랜치 동기화)

토큰 보안 파일 (개발서버):

# /data/GIT/.cicd-env (chmod 600, owner: git)
CICD_GITEA_TOKEN=<토큰>
CICD_GITEA_USER=hskwon
CICD_GITEA_HOST=git.sam.it.kr

hook 스크립트 (/data/GIT/samproject/<repo>.git/hooks/post-receive.d/push-to-cicd):

#!/bin/bash
source /data/GIT/.cicd-env
LOGFILE=/home/webservice/logs/cicd_push_<repo>.log
CICD_REMOTE="https://${CICD_GITEA_USER}:${CICD_GITEA_TOKEN}@${CICD_GITEA_HOST}/SamProject/<repo>.git"

mkdir -p /home/webservice/logs

while read oldrev newrev refname; do
    BRANCH=$(echo "$refname" | sed 's|refs/heads/||')
    if [ "$BRANCH" = "<target_branch>" ]; then
        echo "$(date '+%Y-%m-%d %H:%M:%S'): Pushing ${BRANCH} to CI/CD Gitea" >> $LOGFILE
        git push $CICD_REMOTE ${BRANCH}:${BRANCH} >> $LOGFILE 2>&1
        echo "$(date '+%Y-%m-%d %H:%M:%S'): Done (exit: $?)" >> $LOGFILE
    fi
done

동기화 요약:

저장소	hook 대상 브랜치	동작
sam-react-prod	main, develop	CI/CD Gitea에 push
sam-api	main	CI/CD Gitea에 push
sam-manage	main	CI/CD Gitea에 push (2026-02-24 추가)
sam-sales	main	CI/CD Gitea에 push
sam-landing	main	CI/CD Gitea에 push

⑥ Jenkins

# GPG 키 + APT Repository
sudo gpg --keyserver keyserver.ubuntu.com --recv-keys 7198F4B714ABFC68
sudo gpg --export 7198F4B714ABFC68 | sudo tee /usr/share/keyrings/jenkins-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.gpg]" \
  https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null

sudo apt update
sudo apt install -y jenkins

# JVM 메모리 제한
sudo mkdir -p /etc/systemd/system/jenkins.service.d
sudo tee /etc/systemd/system/jenkins.service.d/override.conf > /dev/null << 'EOF'
[Service]
Environment="JAVA_OPTS=-Xmx2048m -Xms512m -Djava.awt.headless=true"
EOF

sudo systemctl daemon-reload
sudo systemctl enable jenkins
sudo systemctl start jenkins

필요 도구 설치:

# Node.js 22 (react 빌드용)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# PHP 8.4 + Composer (선택 — Laravel 테스트용)
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y php8.4-cli php8.4-mbstring php8.4-xml php8.4-curl php8.4-zip php8.4-mysql php8.4-bcmath
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

SSH 키 설정:

sudo -u jenkins ssh-keygen -t ed25519 -C "jenkins@sam-cicd" -f /var/lib/jenkins/.ssh/id_ed25519 -N ""

# 운영/개발 서버에 공개키 등록
ssh sam-prod "echo '$(cat /var/lib/jenkins/.ssh/id_ed25519.pub)' >> /home/hskwon/.ssh/authorized_keys"
ssh sam-dev "echo '$(cat /var/lib/jenkins/.ssh/id_ed25519.pub)' >> /home/hskwon/.ssh/authorized_keys"

# known_hosts 등록
sudo -u jenkins ssh-keyscan -H 211.117.60.189 >> /var/lib/jenkins/.ssh/known_hosts
sudo -u jenkins ssh-keyscan -H 114.203.209.83 >> /var/lib/jenkins/.ssh/known_hosts

Jenkins Credentials:

• deploy-ssh-key: SSH 키 (hskwon@운영/개발 서버 공용)
• gitea-api-token: Gitea API 토큰

분산 빌드 설정 (Built-in Node 보안 격리):

# 1. Built-in Node executor를 0으로 변경 (Jenkins 정지 상태에서)
sudo systemctl stop jenkins
sudo sed -i 's|<numExecutors>2</numExecutors>|<numExecutors>0</numExecutors>|' /var/lib/jenkins/config.xml
# Agent 포트 활성화 (0 = 랜덤 포트)
sudo sed -i 's|<slaveAgentPort>-1</slaveAgentPort>|<slaveAgentPort>0</slaveAgentPort>|' /var/lib/jenkins/config.xml

# 2. Agent workspace 디렉토리
sudo mkdir -p /var/lib/jenkins-agent/workspace
sudo chown -R jenkins:jenkins /var/lib/jenkins-agent

# 3. Agent 노드 설정
sudo mkdir -p /var/lib/jenkins/nodes/local-agent
# config.xml 생성 (JNLP WebSocket, executor 2, label: build)
sudo chown -R jenkins:jenkins /var/lib/jenkins/nodes/local-agent

# 4. Jenkins 시작 → Agent secret 확인 (UI 또는 Groovy 스크립트)
sudo systemctl start jenkins

# 5. Agent jar 다운로드
sudo curl -sL http://localhost:8080/jnlpJars/agent.jar -o /var/lib/jenkins-agent/agent.jar
sudo chown jenkins:jenkins /var/lib/jenkins-agent/agent.jar

# 6. Agent systemd 서비스
sudo tee /etc/systemd/system/jenkins-agent.service > /dev/null << 'AGENTEOF'
[Unit]
Description=Jenkins Build Agent
After=network.target jenkins.service
Wants=jenkins.service

[Service]
Type=simple
User=jenkins
Group=jenkins
WorkingDirectory=/var/lib/jenkins-agent
ExecStart=/usr/bin/java -jar /var/lib/jenkins-agent/agent.jar \
  -url http://localhost:8080/ \
  -secret <AGENT_SECRET> \
  -name local-agent \
  -workDir /var/lib/jenkins-agent \
  -webSocket
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
AGENTEOF

sudo systemctl daemon-reload
sudo systemctl enable jenkins-agent
sudo systemctl start jenkins-agent

참고: Agent secret은 Jenkins UI > Manage Jenkins > Nodes > local-agent에서 확인하거나, init.groovy.d 스크립트로 추출 가능.

⑦ Nginx + SSL (CI/CD)

리버스 프록시 설정:

# /etc/nginx/sites-available/git.sam.it.kr
server {
    listen 80;
    server_name git.sam.it.kr;
    client_max_body_size 500M;
    proxy_request_buffering off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# /etc/nginx/sites-available/ci.sam.it.kr
server {
    listen 80;
    server_name ci.sam.it.kr;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 90;
        proxy_buffering off;
    }
}

# /etc/nginx/sites-available/monitor.sam.it.kr
server {
    listen 80;
    server_name monitor.sam.it.kr;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

sudo ln -s /etc/nginx/sites-available/git.sam.it.kr /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/ci.sam.it.kr /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/monitor.sam.it.kr /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

sudo certbot --nginx -d git.sam.it.kr
sudo certbot --nginx -d ci.sam.it.kr
sudo certbot --nginx -d monitor.sam.it.kr

⑧ Prometheus + node_exporter

# Prometheus
PROM_VERSION="2.51.0"
cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v${PROM_VERSION}/prometheus-${PROM_VERSION}.linux-amd64.tar.gz
tar xzf prometheus-${PROM_VERSION}.linux-amd64.tar.gz
sudo mv prometheus-${PROM_VERSION}.linux-amd64/prometheus /usr/local/bin/
sudo mv prometheus-${PROM_VERSION}.linux-amd64/promtool /usr/local/bin/
sudo mkdir -p /etc/prometheus /var/lib/prometheus
sudo mv prometheus-${PROM_VERSION}.linux-amd64/consoles /etc/prometheus/
sudo mv prometheus-${PROM_VERSION}.linux-amd64/console_libraries /etc/prometheus/
rm -rf prometheus-${PROM_VERSION}*
sudo useradd --no-create-home --shell /bin/false prometheus
sudo chown -R prometheus:prometheus /etc/prometheus /var/lib/prometheus

systemd 서비스:

# /etc/systemd/system/prometheus.service
[Unit]
Description=Prometheus
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus/ \
  --storage.tsdb.retention.time=30d \
  --web.listen-address=127.0.0.1:9090
Restart=always

[Install]
WantedBy=multi-user.target

node_exporter: 운영서버 설치와 동일.

sudo systemctl daemon-reload
sudo systemctl enable prometheus node_exporter
sudo systemctl start prometheus node_exporter

⑨ Grafana

sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install -y grafana

설정 (/etc/grafana/grafana.ini):

[server]
http_port = 3100
domain = monitor.sam.it.kr
root_url = https://monitor.sam.it.kr/

[security]
admin_password = <grafana_비밀번호>

[users]
allow_sign_up = false

sudo systemctl enable grafana-server
sudo systemctl start grafana-server

초기 설정: Data Source: Prometheus (http://localhost:9090) → 대시보드 임포트: Node Exporter Full (ID: 1860)

⑪ 백업 자동화 (운영 DB 원격 백업)

CI/CD 서버에서 운영 서버의 MySQL DB를 매일 자동 백업합니다.

1. 운영 서버 — 백업 사용자 생성 (운영 MySQL에서 실행):

CREATE USER 'sam_backup'@'110.10.147.46' IDENTIFIED BY '<백업용_비밀번호>';
GRANT SELECT, LOCK TABLES, SHOW VIEW, EVENT, TRIGGER ON sam.* TO 'sam_backup'@'110.10.147.46';
GRANT SELECT, LOCK TABLES, SHOW VIEW, EVENT, TRIGGER ON sam_stat.* TO 'sam_backup'@'110.10.147.46';
FLUSH PRIVILEGES;

2. CI/CD 서버 — MySQL 인증 파일:

cat > /home/hskwon/.sam_backup.cnf << 'EOF'
[client]
user=sam_backup
password=<백업용_비밀번호>
EOF
chmod 600 /home/hskwon/.sam_backup.cnf

3. CI/CD 서버 — 백업 스크립트:

mkdir -p /home/hskwon/scripts /home/hskwon/backups/mysql

cat > /home/hskwon/scripts/backup-db.sh << 'SCRIPT'
#!/bin/bash
set -e

BACKUP_DIR="/home/hskwon/backups/mysql"
BACKUP_CNF="/home/hskwon/.sam_backup.cnf"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=14

mkdir -p $BACKUP_DIR

# Gitea DB 백업 (로컬, auth_socket)
mysqldump --single-transaction --routines --triggers gitea | gzip > $BACKUP_DIR/gitea_$DATE.sql.gz

# 운영 DB 원격 백업 (sam_backup 사용자)
if [ -f "$BACKUP_CNF" ]; then
    mysqldump --defaults-extra-file=$BACKUP_CNF -h 211.117.60.189 --single-transaction --routines --triggers --no-tablespaces sam | gzip > $BACKUP_DIR/sam_production_$DATE.sql.gz
    mysqldump --defaults-extra-file=$BACKUP_CNF -h 211.117.60.189 --single-transaction --routines --triggers --no-tablespaces sam_stat | gzip > $BACKUP_DIR/sam_stat_production_$DATE.sql.gz
    echo "$(date '+%Y-%m-%d %H:%M:%S'): Backup completed (gitea + sam + sam_stat)" >> $BACKUP_DIR/backup.log
else
    echo "$(date '+%Y-%m-%d %H:%M:%S'): Backup completed (gitea only - $BACKUP_CNF not found)" >> $BACKUP_DIR/backup.log
fi

# 오래된 백업 삭제
find $BACKUP_DIR -name '*.sql.gz' -mtime +$RETENTION_DAYS -delete
SCRIPT

chmod +x /home/hskwon/scripts/backup-db.sh

4. CI/CD 서버 — 크론탭 등록:

# hskwon이 crontab 사용 가능해야 함
sudo sh -c "echo hskwon > /etc/cron.allow"
sudo chmod 644 /etc/cron.allow

# 크론 등록 (매일 새벽 3시)
(crontab -l 2>/dev/null; echo "# SAM DB 백업 (매일 새벽 3시)"; echo "0 3 * * * /home/hskwon/scripts/backup-db.sh >> /home/hskwon/backups/mysql/backup.log 2>&1") | crontab -

# 등록 확인
crontab -l

5. 테스트:

# 수동 실행
/home/hskwon/scripts/backup-db.sh

# 결과 확인
ls -lht /home/hskwon/backups/mysql/ | head -5
tail -3 /home/hskwon/backups/mysql/backup.log

상세 복원 절차 및 sam→sam_stage 동기화는 백업/복구/재부팅 참조.

⑫ fail2ban + 최종 점검

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

최종 점검:

# 전체 서비스 상태
sudo systemctl status nginx jenkins jenkins-agent gitea mysql prometheus grafana-server node_exporter fail2ban

# 포트 확인
sudo ss -tlnp | grep -E '(80|443|3000|3100|8080|9090|9100|3306)'

# 웹 서비스
curl -sI https://ci.sam.it.kr | head -3
curl -sI https://git.sam.it.kr | head -3
curl -sI https://monitor.sam.it.kr | head -3

# 백업 크론 확인
crontab -l

# 자동 시작 등록 확인
for svc in nginx jenkins jenkins-agent gitea mysql prometheus grafana-server node_exporter fail2ban; do
  echo -n "$svc: "; systemctl is-enabled $svc 2>/dev/null || echo "NOT FOUND"
done

---

보안 체크리스트

[운영]

• SSH 키 인증만 허용 (비밀번호 로그인 비활성화)
• root SSH 로그인 비활성화
• UFW 방화벽 활성화
• MySQL root 원격 접근 차단 (auth_socket)
• MySQL 앱 사용자 최소 권한 (codebridge)
• .env 파일 권한 600 (api, admin, sales)
• storage/ 디렉토리 권한 775
• Nginx security.conf 스니펫 적용
• PHP display_errors = Off (모든 pool)
• Laravel APP_DEBUG=false, APP_ENV=production
• Sales uploads/ PHP 실행 차단
• Certbot 자동 갱신 (7/7 dry-run success)
• fail2ban (SSH 브루트포스 방지)
• Redis bind 127.0.0.1 (외부 접근 차단)
• node_exporter CI/CD IP만 허용 (UFW)

[CI/CD]

• SSH 키 인증만 허용 (PasswordAuthentication no)
• root SSH 로그인 비활성화 (PermitRootLogin no)
• UFW 방화벽 활성화 (22, 80, 443만)
• Jenkins 관리자 계정 변경 (hskwon)
• Gitea 회원가입 비활성화 (DISABLE_REGISTRATION = true)
• Grafana 익명 접근 비활성화 (allow_sign_up = false)
• Prometheus 외부 접근 차단 (127.0.0.1:9090)
• MySQL root 원격 접근 차단 (auth_socket)
• fail2ban (sshd jail)
• Certbot 자동 갱신
• Jenkins SSH 키 ed25519 + Credential 등록
• Webhook Secret 설정 (Gitea → Jenkins)
• post-receive hook 토큰 보안 (600 권한)

---

개발서버 비교 (참고)

항목	개발서버	운영서버
OS	Ubuntu 24.04.2	Ubuntu 24.04 (kernel 6.8.0-100)
CPU/RAM	2C / 3.8GB (스왑 없음)	2C / 8GB + 스왑 4GB
PHP	8.4.15 (+ 5.6, 7.3)	8.4.18
MySQL	8.4.8	8.4.8
Node.js	22.17.1	22.17.1
Nginx	1.24.0	1.24.0
Redis	-	7.0.15 (512mb)
PHP-FPM	단일 www pool	4개 분리 (api/admin/sales/stage)
PM2	fork ×1 (:3001)	cluster ×2 (:3000) + fork ×1 (:3100)
Supervisor	-	queue worker ×2
UFW	비활성	활성
fail2ban	-	✅

---

[개발] PM2 설정

개발서버는 ecosystem.config.js 없이 PM2 CLI로 직접 관리합니다.

# 실행 (포트 3001, Gitea가 3000 사용)
cd /home/webservice/react && pm2 start npm --name sam-react -- start -- -p 3001

# 재부팅 자동 시작 등록
pm2 save
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u hskwon --hp /home/hskwon

이름	모드	포트	비고
sam-react	fork	3001	Gitea가 3000 사용, Jenkins 배포 시 자동 restart

---

[개발] MySQL 8.0 → 8.4 업그레이드 절차

Ubuntu 24.04 APT 기본은 MySQL 8.0입니다. 8.4로 업그레이드하는 절차:

사전 준비

# 1. DB 백업
DB_PASS=$(grep DB_PASSWORD /home/webservice/mng/.env | head -1 | cut -d= -f2)
for db in sam chandj sam_stat; do
  mysqldump -ucodebridge -p$DB_PASS --no-tablespaces --skip-triggers --skip-routines $db | gzip > /tmp/${db}_backup.sql.gz
done

# 2. 인증 방식 변환 (mysql_native_password → caching_sha2_password)
# 8.4에서 mysql_native_password가 deprecated
mysql -u debian-sys-maint -p'<debian-sys-maint_비밀번호>' -e "
  ALTER USER 'codebridge'@'localhost' IDENTIFIED WITH caching_sha2_password BY '<비밀번호>';
  ALTER USER 'chandj'@'localhost' IDENTIFIED WITH caching_sha2_password BY '<비밀번호>';
  FLUSH PRIVILEGES;"

debian-sys-maint 비밀번호: /etc/mysql/debian.cnf 참조

업그레이드 실행

# 3. MySQL 중지
sudo systemctl stop mysql

# 4. MySQL APT 레포 추가
wget -q https://dev.mysql.com/get/mysql-apt-config_0.8.33-1_all.deb -O /tmp/mysql-apt-config.deb
sudo DEBIAN_FRONTEND=noninteractive dpkg -i /tmp/mysql-apt-config.deb

# 5. 레포를 8.4-lts로 변경
sudo sed -i 's/mysql-8.0/mysql-8.4-lts/g' /etc/apt/sources.list.d/mysql.list
sudo apt-get update

# 6. 업그레이드 (기존 설정 유지)
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::="--force-confold" mysql-server mysql-client

# 7. 시작 및 확인
sudo systemctl start mysql
mysql --version   # → 8.4.x 확인

GPG 키 만료 시

MySQL APT 레포의 GPG 키가 만료된 경우:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B7B3B788A8D3785C
# 또는 allow-insecure 임시 허용 후 설치