sam-docs/system/server-access-management.md

# SAM 서버 접근 권한 관리

## 개요

SAM 시스템의 서버 및 데이터베이스 접근 권한을 관리합니다.
서버 관리자는 1명이며, 서브 관리자에게는 필요 시 임시로 접근을 허용하고 작업 완료 후 잠금합니다.

**최종 업데이트:** 2026-03-11

---

## 운영 관리자

| 계정 | 이름 | 역할 |
|------|------|------|
| `hskwon` | 권혁성 | 서버 관리자 (배포, 운영, 인프라) |
| `pro` | 김보곤 | 서브 관리자 (임시 접근, 평상시 잠금) |

---

## 서버 정보

| 구분 | 호스트 | SSH alias | 용도 |
|------|--------|-----------|------|
| 운영 (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 | dev |
|------|------|-----|
| OS timezone | Asia/Seoul (KST, +0900) | Asia/Seoul (KST, +0900) |
| NTP 동기화 | 활성 | 활성 |
| 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로 설정할 것.

---

## OS 계정 현황

### sam-prod (운영서버)

| 계정 | 이름 | 용도 | 상태 |
|------|------|------|------|
| `hskwon` | 권혁성 | 서버 관리자 (배포, 운영) | 활성 |
| `pro` | 김보곤 | 서브 관리자 임시 접근용 | 평상시 **잠금** |

### sam-cicd (CI/CD 서버)

| 계정 | 이름 | 용도 | 상태 |
|------|------|------|------|
| `hskwon` | 권혁성 | 서버 관리자 | 활성 |
| `pro` | 김보곤 | 서브 관리자 임시 접근용 | 평상시 **잠금** |

### sam-dev (개발서버)

| 계정 | 이름 | 용도 | 상태 |
|------|------|------|------|
| `hskwon` | 권혁성 | 서버 관리자 | 활성 |
| `pro` | 김보곤 | 서브 관리자 | 활성 |

---

## OS 계정 잠금/해제

서브 관리자에게 서버 접근이 필요한 경우, 작업 시간 동안만 해제하고 완료 후 다시 잠금합니다.

```bash
# 계정 잠금
sudo usermod -L pro

# 계정 해제
sudo usermod -U pro

# 상태 확인 (비밀번호 필드 앞에 ! 있으면 잠금 상태)
sudo passwd -S pro
```

### 임시 접근 절차

1. 작업 요청 접수 및 범위 확인
2. `sudo usermod -U pro` 로 해제
3. 작업 완료 확인
4. `sudo usermod -L pro` 로 잠금
5. 작업 내용 기록

> **참고:** OS 계정 잠금 시 DB 접근도 자동 차단됨. `pro@localhost` DB 계정은 SSH 터널 경유로만 접근 가능하므로, SSH가 막히면 DB도 접속 불가.

---

## OS 그룹 현황

### 그룹 역할

| 그룹 | 용도 | 핵심 특징 |
|------|------|----------|
| `webservice` | 웹 서비스 운영 (배포 + 웹 프로세스) | `www-data` 포함 → PHP-FPM이 파일 쓰기 가능 |
| `develop` | 개발 환경 전용 | 개발서버에서만 사용, `www-data` 포함 |

> **원칙:** `webservice` = 운영/CICD 서버, `develop` = 개발서버. 동일한 역할이므로 서버별로 하나만 사용.

### 서버별 그룹 구성

| 서버 | 그룹명 | 멤버 |
|------|--------|------|
| sam-prod (운영) | `webservice` | hskwon, www-data, pro |
| sam-cicd (CI/CD) | `webservice` | hskwon, pro |
| sam-dev (개발) | `develop` | hskwon, pro, www-data, zomking |

> **변경 이력:** 2026-03-11 — 운영/CICD 서버에서 미사용 `develop` 그룹 삭제 (webservice 그룹과 역할 중복)

### Jenkinsfile 권한 설정

배포 시 `storage/`, `bootstrap/cache/` 등의 소유권을 `www-data:webservice`로 설정:
```bash
sudo chown -R www-data:webservice storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```
- `www-data`(소유자): PHP-FPM 프로세스가 읽기/쓰기
- `webservice`(그룹): 배포 유저(hskwon)가 접근 가능

---

## DB 계정 현황

### sam-prod (운영서버 MySQL 8.4)

| 계정 | 인증 플러그인 | 접근 DB | 용도 |
|------|-------------|---------|------|
| `codebridge@localhost` | caching_sha2_password | sam, sam_stage, sam_stat, codebridge | 애플리케이션 (.env) |
| `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 | 전역 관리자 | 서버 관리자 |

> **참고:** cicd 서버의 MySQL은 Gitea DB + 백업 저장 용도

### sam-dev (개발서버 MySQL 8.4)

| 계정 | 용도 |
|------|------|
| `pro@localhost` | 서브 관리자용 |

> **참고:** dev 서버는 `sudo mysql` 불가, root 비밀번호 인증 방식

---

## DB 계정 관리

### 계정 잠금/해제 (MySQL)

```sql
-- 계정 잠금
ALTER USER 'pro'@'localhost' ACCOUNT LOCK;

-- 계정 해제
ALTER USER 'pro'@'localhost' ACCOUNT UNLOCK;

-- 상태 확인
SELECT user, host, account_locked FROM mysql.user WHERE user = 'pro';
```

### 인증 플러그인 변경

MySQL 8.4에서는 `mysql_native_password`가 제거되었으므로 `caching_sha2_password`를 사용합니다.

```sql
ALTER USER 'username'@'localhost' IDENTIFIED WITH caching_sha2_password BY '비밀번호';
FLUSH PRIVILEGES;
```

### PhpStorm 접속 시 주의사항

- SSH 터널 필수 (MySQL이 localhost만 허용)
- Host: `localhost` (127.0.0.1 아님)
- `caching_sha2_password` 사용 시 Advanced 탭에서 `allowPublicKeyRetrieval = true` 설정 필요

---

## DB 백업

sam-cicd 서버에서 prod DB를 원격 mysqldump로 백업합니다.

### 백업 설정

| 항목 | 값 |
|------|---|
| 스크립트 | `/home/hskwon/scripts/backup-db.sh` |
| 백업 경로 | `/home/hskwon/backups/mysql/` |
| 실행 시간 | 매일 03:00 (cron, hskwon 사용자) |
| 보관 기간 | 14일 |

### 백업 대상

| DB | 방식 | 파일명 패턴 |
|----|------|------------|
| sam | 원격 (prod) | `sam_production_YYYYMMDD_HHMMSS.sql.gz` |
| sam_stat | 원격 (prod) | `sam_stat_production_YYYYMMDD_HHMMSS.sql.gz` |
| codebridge | 원격 (prod) | `codebridge_production_YYYYMMDD_HHMMSS.sql.gz` |
| gitea | 로컬 (cicd) | `gitea_YYYYMMDD_HHMMSS.sql.gz` |

### 백업 확인

```bash
# cicd 서버에서 확인
ssh sam-cicd

# 최근 백업 파일 확인
ls -lt ~/backups/mysql/ | head -10

# 백업 로그 확인
tail ~/backups/mysql/backup.log
```

---

## 배포 계정 관리

### Jenkins 배포 흐름

Jenkins는 sam-cicd(110.10.147.46)에서 운영됩니다.

| 프로젝트 | main | develop |
|----------|------|---------|
| **api** | Jenkins (Stage + Production) | post-update hook (Jenkins 미관여) |
| **react** | Jenkins (Stage + Production) | Jenkins (Development) |

- 배포 SSH 계정: `hskwon` (deploy-ssh-key 크레덴셜)
- Slack 알림: `#deploy_api`, `#deploy_react`
- Jenkins 웹 UI: https://ci.sam.it.kr

### Jenkins 롤백 기능

Jenkins 웹에서 "Build with Parameters"로 롤백 실행 가능:

| 파라미터 | 옵션 | 설명 |
|----------|------|------|
| `ACTION` | deploy / rollback | 배포 또는 롤백 선택 |
| `ROLLBACK_TARGET` | production / stage | 롤백 대상 환경 |
| `ROLLBACK_RELEASE` | (릴리스 ID) | 비워두면 직전 릴리스로 롤백 |

**롤백 동작:**
1. 릴리스 목록 조회 (현재 활성 + 사용 가능 목록 콘솔 출력)
2. symlink 전환 → 캐시 재생성 → 서비스 재시작
3. Slack 알림 (`#deploy_api` / `#deploy_react`)

**릴리스 보관:**
- Production: 6개
- Stage: 4개

> **변경 이력:** 2026-03-11 — api, react Jenkinsfile에 롤백 파라미터 추가

---

## 관리 정책

1. **서버 관리자 1명 원칙** -- 여러 명이 동시에 관리하지 않음
2. **임시 접근만 허용** -- 서브 관리자는 필요 시에만 OS/DB 계정 해제
3. **작업 완료 후 즉시 잠금** -- 해제 상태로 방치하지 않음
4. **DB 접근은 SSH 터널 경유** -- 외부에서 MySQL 직접 접근 불가 (localhost 바인딩)
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)
- Jenkins 설정: [../dev/guides/jenkins-setup-guide.md](../dev/guides/jenkins-setup-guide.md)

---

**작성일:** 2026-03-05
**버전:** 1.3
**담당자:** SAM Infrastructure Team