From 85dc30bfcd58a285305eb4ef6128ff6620a62dfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B6=8C=ED=98=81=EC=84=B1?= Date: Mon, 9 Mar 2026 13:22:53 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[infra]=20=EC=84=9C=EB=B2=84=20?= =?UTF-8?q?=EC=A0=95=EB=B3=B4=20=EC=98=A4=EB=A5=98=20=EC=88=98=EC=A0=95=20?= =?UTF-8?q?(ops-manual=20=EA=B8=B0=EC=A4=80=20=EC=A0=95=EB=A0=AC)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - server-access-management.md: sam-cicd IP 정정 (114.203.209.83 → 110.10.147.46), sam-dev 추가, DB 계정/백업 경로 갱신, 리플리케이션 섹션 제거 - CLAUDE.md: dev 서버에서 Jenkins 제거 (Jenkins는 cicd 서버), MySQL 8.0 → 8.4, Next.js 포트 수정 --- CLAUDE.md | 15 ++-- system/server-access-management.md | 110 ++++++++--------------------- 2 files changed, 36 insertions(+), 89 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 123e5e9..603aea0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -301,10 +301,10 @@ Claude가 **절대 직접 실행하지 않으며**, 사용자에게 명령어를 | 서버 | 호스트 | 계정 | SSH 접근 | 역할 | |------|--------|------|---------|------| -| 개발 서버 | `114.203.209.83` | `pro`, `hskwon` | **Claude 가능** | 개발/스테이징 + Jenkins CI/CD + Gitea | +| 개발 서버 (sam-dev) | `114.203.209.83` | `pro`, `hskwon` | **Claude 가능** | 개발/스테이징 + Gitea | | 운영 서버 | (비공개) | 별도 계정 | **Claude 불가** — 개발팀장만 접근 | 정식 서비스 | -> **참고**: Jenkins(`114.203.209.83:8080`)와 Gitea(`114.203.209.83:3000`)는 개발 서버에서 운영한다. +> **참고**: Jenkins는 CI/CD 서버(`110.10.147.46:8080`, ci.sam.it.kr)에서 운영한다. Gitea는 개발 서버(`114.203.209.83:3000`)와 CI/CD 서버(`110.10.147.46:3000`, git.sam.it.kr) 양쪽에 있다. > **운영 서버 정책**: Claude는 운영 서버에 SSH 접속할 수 없다. IP 접근이 제한되어 있으며 개발팀장만 접근 가능하다. 운영 배포는 `git push origin main` → Jenkins 자동 배포로만 이루어지며, 운영 서버 상태 확인이 필요하면 사용자(개발팀장)에게 요청한다. @@ -541,11 +541,11 @@ ssh <운영계정>@<운영서버IP> "cd /home/webservice/mng && php artisan tink |------|-----------|----------|----------| | **구성 방식** | Docker 컨테이너 | Bare-metal (네이티브) | Bare-metal (네이티브) | | **PHP** | 컨테이너 내부 (8.4) | 직접 설치 (8.4) | 직접 설치 (8.4) | -| **MySQL** | 컨테이너 (sam-mysql-1) | 직접 설치 (8.0) | 직접 설치 (8.0) | +| **MySQL** | 컨테이너 (sam-mysql-1) | 직접 설치 (8.4) | 직접 설치 (8.4) | | **Nginx** | 컨테이너 (sam-nginx-1) | 직접 설치 | 직접 설치 | | **명령 실행** | `docker exec` 필요 | 직접 실행 | 직접 실행 | | **서버 IP** | localhost | `114.203.209.83` | (신규, 미확정) | -| **추가 서비스** | — | Jenkins, Gitea | — | +| **추가 서비스** | — | Gitea | — | | **DB** | `samdb` | `samdb` | `sam_prod` | > **배경**: 서버는 Docker가 무거워서 PHP, Nginx, MySQL 등을 네이티브로 설치하여 운영한다. @@ -566,7 +566,7 @@ PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있다. ### 서버 환경 (Bare-metal — 개발/운영 동일 구조) -서버에는 Docker가 없다. PHP 8.4, Nginx, MySQL 8.0이 직접 설치되어 있다. +서버에는 Docker가 없다. PHP 8.4, Nginx, MySQL 8.4이 직접 설치되어 있다. ``` 개발 서버 (114.203.209.83) 운영 서버 (신규) @@ -575,13 +575,12 @@ PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있다. │ ├── api.sock │ ├── api.sock │ ├── mng.sock │ ├── mng.sock │ └── sales.sock │ └── sales.sock -├── MySQL 8.0 (samdb) ├── MySQL 8.0 (sam_prod) +├── MySQL 8.4 (samdb) ├── MySQL 8.4 (sam_prod) ├── Supervisor ├── Supervisor │ ├── sam-api-worker (x1) │ ├── sam-api-worker (x1) │ ├── sam-mng-worker (x2) │ ├── sam-mng-worker (x2) │ └── sam-api-scheduler │ └── sam-api-scheduler -├── Node.js (React SSR :3000) ├── Node.js (React SSR :3000) -├── Jenkins (:8080) │ +├── Node.js (React SSR :3001) ├── Node.js (React SSR :3000) ├── Gitea (:3000) │ ├── /home/webservice/api ├── /home/webservice/api ├── /home/webservice/mng ├── /home/webservice/mng diff --git a/system/server-access-management.md b/system/server-access-management.md index 67da35a..b32b531 100644 --- a/system/server-access-management.md +++ b/system/server-access-management.md @@ -5,7 +5,7 @@ SAM 시스템의 서버 및 데이터베이스 접근 권한을 관리합니다. 서버 관리자는 1명이며, 외부 인원에게는 임시로 접근을 허용하고 작업 완료 후 차단합니다. -**최종 업데이트:** 2026-03-07 +**최종 업데이트:** 2026-03-09 --- @@ -22,19 +22,21 @@ SAM 시스템의 서버 및 데이터베이스 접근 권한을 관리합니다. | 구분 | 호스트 | SSH alias | 용도 | |------|--------|-----------|------| -| 운영 (prod) | 211.117.60.189 | `sam-prod` | API + React 운영 배포 | -| 개발 (dev) | - | `sam-dev` | 개발 환경 | -| CI/CD | 114.203.209.83 | `sam-cicd` | Jenkins + React 개발 배포 + DB 백업 | +| 운영 (prod) | 211.117.60.189 | `sam-prod` | API + React + MNG 운영 배포 | +| CI/CD | 110.10.147.46 | `sam-cicd` | Jenkins + Gitea + Grafana + Prometheus | +| 개발 (dev) | 114.203.209.83 | `sam-dev` | API + React + MNG 개발 환경 + Gitea + MySQL | + +> **참고:** 상세 서버 구성은 `docs/dev/deploys/ops-manual/01-server-overview.md` 참조 ### 서버 시간대 -| 설정 | prod | cicd | -|------|------|------| +| 설정 | prod | dev | +|------|------|-----| | OS timezone | Asia/Seoul (KST, +0900) | Asia/Seoul (KST, +0900) | | NTP 동기화 | 활성 | 활성 | -| PHP CLI (`/etc/php/8.4/cli/php.ini`) | Asia/Seoul | PHP 미설치 | -| PHP FPM (`/etc/php/8.4/fpm/php.ini`) | Asia/Seoul | - | -| Laravel `app.timezone` | Asia/Seoul | - | +| PHP CLI (`/etc/php/8.4/cli/php.ini`) | Asia/Seoul | Asia/Seoul | +| PHP FPM (`/etc/php/8.4/fpm/php.ini`) | Asia/Seoul | Asia/Seoul | +| Laravel `app.timezone` | Asia/Seoul | Asia/Seoul | > **주의:** PHP timezone이 UTC면 스케줄러 실행 시간이 9시간 어긋남. 반드시 Asia/Seoul로 설정할 것. @@ -54,7 +56,6 @@ SAM 시스템의 서버 및 데이터베이스 접근 권한을 관리합니다. | 계정 | 이름 | 용도 | 상태 | |------|------|------|------| | `hskwon` | 권혁성 | 서버 관리자 | 활성 | -| `pro` | 김보곤 | 서브 관리자 임시 접근용 | 평상시 **잠금** | ### sam-dev (개발서버) @@ -90,39 +91,6 @@ sudo passwd -S pro --- -## 공동 관리 구조 (cicd 서버) - -인력 변동에 대비하여 cicd 서버는 공동 관리 구조로 운영합니다. - -### develop 그룹 - -```bash -# 그룹 구성원 -$ getent group develop -develop:x:1004:hskwon,pro - -# 디렉토리 구조 -/data/ -├── backups/mysql/ # DB 백업 파일 (14일 보관) -└── scripts/ # 운영 스크립트 + .sam_backup.cnf -``` - -### 권한 설정 - -- `/data/` 전체: `develop` 그룹 소유, **setgid** 적용 -- setgid(`chmod g+s`)로 하위에 생성되는 파일/폴더도 자동으로 `develop` 그룹 상속 -- 그룹 권한 = 소유자 권한 (`chmod g=u`) -- 누가 작업하든 다른 관리자가 접근/수정 가능 - -```bash -# 권한 재설정 필요 시 -sudo chown -R hskwon:develop /data -sudo chmod -R g=u /data -sudo chmod g+s /data /data/backups /data/backups/mysql /data/scripts -``` - ---- - ## DB 계정 현황 ### sam-prod (운영서버 MySQL 8.4) @@ -130,17 +98,17 @@ sudo chmod g+s /data /data/backups /data/backups/mysql /data/scripts | 계정 | 인증 플러그인 | 접근 DB | 용도 | |------|-------------|---------|------| | `codebridge@localhost` | caching_sha2_password | sam, sam_stage, sam_stat, codebridge | 애플리케이션 (.env) | -| `hskwon@localhost` | caching_sha2_password | 전역 관리자 + sam | 서버 관리자 | -| `pro@localhost` | caching_sha2_password | sam, sam_stage, sam_stat, codebridge | 서브 관리자용 | +| `hskwon@localhost` | auth_socket | 전역 관리자 (WITH GRANT OPTION) | 서버 관리자 | +| `root@localhost` | auth_socket | 전역 | 시스템 (sudo mysql) | +| `sam_backup@110.10.147.46` | caching_sha2_password | SELECT, LOCK TABLES (sam, sam_stat) | CI/CD 백업 | ### sam-cicd (CI/CD 서버 MySQL 8.4) | 계정 | 인증 플러그인 | 접근 DB | 용도 | |------|-------------|---------|------| | `hskwon@localhost` | caching_sha2_password | 전역 관리자 | 서버 관리자 | -| `pro@localhost` | caching_sha2_password | sam, sam_stage, sam_stat, codebridge, gitea | 서브 관리자용 | -> **참고:** cicd 서버에는 `codebridge` DB 계정이 없음 (애플리케이션이 다른 계정 사용) +> **참고:** cicd 서버의 MySQL은 Gitea DB + 백업 저장 용도 ### sam-dev (개발서버 MySQL 8.4) @@ -184,41 +152,16 @@ FLUSH PRIVILEGES; --- -## DB 리플리케이션 - -운영 DB(prod)에서 cicd 서버로 실시간 리플리케이션이 구성되어 있습니다. - -| 항목 | 값 | -|------|---| -| Source (마스터) | sam-prod (211.117.60.189) | -| Replica (슬레이브) | sam-cicd | -| 리플리케이션 사용자 | `sam_backup` | -| 대상 DB | **sam, sam_stat, codebridge** | -| 지연 | 0초 (실시간) | - -```sql --- cicd에서 리플리케이션 상태 확인 -SHOW REPLICA STATUS\G - --- 확인 항목 --- Replica_IO_Running: Yes --- Replica_SQL_Running: Yes --- Seconds_Behind_Source: 0 -``` - ---- - ## DB 백업 -리플리케이션과 별도로, cicd 서버에서 매일 03:00에 mysqldump 백업을 수행합니다. +sam-cicd 서버에서 prod DB를 원격 mysqldump로 백업합니다. ### 백업 설정 | 항목 | 값 | |------|---| -| 스크립트 | `/data/scripts/backup-db.sh` | -| 인증 파일 | `/data/scripts/.sam_backup.cnf` | -| 백업 경로 | `/data/backups/mysql/` | +| 스크립트 | `/home/hskwon/scripts/backup-db.sh` | +| 백업 경로 | `/home/hskwon/backups/mysql/` | | 실행 시간 | 매일 03:00 (cron, hskwon 사용자) | | 보관 기간 | 14일 | @@ -234,11 +177,14 @@ SHOW REPLICA STATUS\G ### 백업 확인 ```bash +# cicd 서버에서 확인 +ssh sam-cicd + # 최근 백업 파일 확인 -ls -lt /data/backups/mysql/ | head -10 +ls -lt ~/backups/mysql/ | head -10 # 백업 로그 확인 -tail /data/backups/mysql/backup.log +tail ~/backups/mysql/backup.log ``` --- @@ -247,6 +193,8 @@ tail /data/backups/mysql/backup.log ### Jenkins 배포 흐름 +Jenkins는 sam-cicd(110.10.147.46)에서 운영됩니다. + | 프로젝트 | main | develop | |----------|------|---------| | **api** | Jenkins (Stage + Production) | post-update hook (Jenkins 미관여) | @@ -254,6 +202,7 @@ tail /data/backups/mysql/backup.log - 배포 SSH 계정: `hskwon` (deploy-ssh-key 크레덴셜) - Slack 알림: `#deploy_api`, `#deploy_react` +- Jenkins 웹 UI: https://ci.sam.it.kr --- @@ -263,20 +212,19 @@ tail /data/backups/mysql/backup.log 2. **임시 접근만 허용** -- 서브 관리자는 필요 시에만 OS/DB 계정 해제 3. **작업 완료 후 즉시 잠금** -- 해제 상태로 방치하지 않음 4. **DB 접근은 SSH 터널 경유** -- 외부에서 MySQL 직접 접근 불가 (localhost 바인딩) -5. **공동 관리 대비** -- cicd `/data/`는 develop 그룹으로 관리, 인력 변동 대비 -6. **이중 백업** -- 리플리케이션(실시간) + mysqldump(매일 03:00) 병행 +5. **이중 백업** -- cicd에서 mysqldump(매일 03:00) 수행 --- ## 참고 +- 서버 운영 매뉴얼: [../dev/deploys/ops-manual/README.md](../dev/deploys/ops-manual/README.md) - API 보안 가이드: [security-policy.md](./security-policy.md) - Docker 설정: [docker-setup.md](./docker-setup.md) -- 원격 근무 설정: [remote-work-setup.md](./remote-work-setup.md) - Jenkins 설정: [../dev/guides/jenkins-setup-guide.md](../dev/guides/jenkins-setup-guide.md) --- **작성일:** 2026-03-05 -**버전:** 1.1 +**버전:** 1.2 **담당자:** SAM Infrastructure Team \ No newline at end of file