docs: [CLAUDE.md] 로컬(Docker) vs 서버(네이티브) 환경 구분 명확화

- Docker 환경 섹션을 실행 환경 섹션으로 변경
- 서버는 Docker 없이 네이티브로 운영됨을 명시
- 로컬/서버 명령어 비교표 추가
- 서버 접근 정책에서 docker ps/logs 제거 (서버에 Docker 없음)
- 마이그레이션 실행, 공동 개발 워크플로우 등 관련 섹션 일괄 수정
This commit is contained in:
김보곤
2026-02-23 14:04:15 +09:00
parent b7d1fb97b4
commit 73d25b99ec

View File

@@ -151,7 +151,6 @@ fix: [auth] 로그인 시 세션 만료 오류 수정
✅ tail -f /var/log/*.log — 로그 조회
✅ systemctl status — 서비스 상태 조회
✅ crontab -l — 크론 작업 조회
✅ docker ps, docker logs — 컨테이너 상태 조회
```
### 🟡 Level 2: 경미한 변경 (확인 후 실행)
@@ -289,11 +288,13 @@ React 코드가 변경되었습니다. git push 후 서버에서 배포해주세
### 마이그레이션 실행
```bash
# 마이그레이션은 반드시 API 컨테이너에서 실행
# 로컬: 마이그레이션은 반드시 API 컨테이너에서 실행
docker exec sam-api-1 php artisan migrate
# MNG 컨테이너에서 마이그레이션 실행 금지
# docker exec sam-mng-1 php artisan migrate ← 사용하지 않음
# 서버: Docker 없음, 직접 실행
cd /home/webservice/api && php artisan migrate
# MNG에서 마이그레이션 실행 금지 (로컬/서버 모두)
```
### 이유
@@ -357,14 +358,26 @@ App\\Models\\Commons\\Menu::create([
---
## Docker 환경 (필수 인지)
## 실행 환경 (필수 인지)
> **중요: 로컬 개발 환경은 Docker 기반입니다!**
> **중요: 로컬과 서버의 환경이 다릅니다!**
### 왜 Docker를 통해 실행하나?
### 환경 비교
PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있습니다.
로컬 PC(WSL)에는 이런 도구들이 없으므로, 반드시 Docker 컨테이너를 통해 실행해야 합니다.
| 항목 | 로컬 (WSL) | 서버 (운영) |
|------|-----------|------------|
| **구성 방식** | Docker 컨테이너 | 네이티브 설치 (Docker 없음) |
| **PHP/Laravel** | 컨테이너 내부 | 서버에 직접 설치 |
| **MySQL** | 컨테이너 (sam-mysql-1) | 서버에 직접 설치 |
| **Nginx** | 컨테이너 (sam-nginx-1) | 서버에 직접 설치 |
| **명령 실행** | `docker exec` 필요 | 직접 실행 |
> **배경**: 서버는 Docker가 무거워서 PHP, Nginx, MySQL 등을 네이티브로 설치하여 운영한다.
### 로컬 환경 (Docker)
PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있다.
로컬 PC(WSL)에는 이런 도구들이 없으므로, 반드시 Docker 컨테이너를 통해 실행한다.
```
로컬 PC (WSL)
@@ -375,7 +388,29 @@ PHP, Laravel, Node.js 등이 **Docker 컨테이너 안에** 설치되어 있습
└── sam-nginx-1 ← Nginx 웹서버
```
### Docker 명령어 패턴
### 서버 환경 (네이티브)
서버에는 Docker가 없다. PHP, Nginx, MySQL이 직접 설치되어 있다.
```
운영 서버 (114.203.209.83)
├── Nginx ← 웹서버 (직접 설치)
├── PHP-FPM ← PHP 처리 (직접 설치)
├── MySQL ← DB (직접 설치)
├── /home/webservice/mng ← MNG 앱
└── /home/webservice/api ← API 앱
```
### 명령어 비교 (로컬 vs 서버)
| 작업 | 로컬 (Docker) | 서버 (네이티브) |
|------|--------------|----------------|
| artisan 실행 | `docker exec sam-api-1 php artisan <명령>` | `cd /home/webservice/api && php artisan <명령>` |
| composer 실행 | `docker exec sam-api-1 composer install` | `cd /home/webservice/api && composer install` |
| 마이그레이션 | `docker exec sam-api-1 php artisan migrate` | `cd /home/webservice/api && php artisan migrate` |
| 캐시 클리어 | `docker exec sam-mng-1 php artisan cache:clear` | `cd /home/webservice/mng && php artisan cache:clear` |
### 로컬 Docker 명령어 패턴
```bash
# MNG 앱에서 artisan 명령 실행
@@ -396,10 +431,10 @@ docker exec sam-mng-1 php artisan cache:clear
### 체크리스트 (명령 실행 시)
- [ ] `php artisan` 명령`docker exec sam-mng-1 php artisan` 또는 `sam-api-1` 사용
- [ ] `composer` 명령`docker exec sam-mng-1 composer` 또는 `sam-api-1` 사용
- [ ] DB 시더 실행 필요 시 → Docker를 통해 실행
- [ ] **마이그레이션은 반드시 API에서 실행** `docker exec sam-api-1 php artisan migrate`
- [ ] **로컬**: `php artisan``docker exec sam-mng-1 php artisan` 또는 `sam-api-1` 사용
- [ ] **로컬**: `composer``docker exec sam-mng-1 composer` 또는 `sam-api-1` 사용
- [ ] **서버**: `php artisan`, `composer` 직접 실행 (Docker 없음)
- [ ] **마이그레이션은 반드시 API에서 실행** (로컬: `docker exec sam-api-1`, 서버: 직접)
---
@@ -429,7 +464,9 @@ docker exec sam-api-1 php artisan config:clear
docker exec sam-mng-1 php artisan config:clear
```
### 서버 환경 업데이트
### 서버 환경 업데이트 (네이티브 — Docker 없음)
> 서버에는 Docker가 없다. PHP, Composer 등이 직접 설치되어 있으므로 명령어를 그대로 실행한다.
```bash
# API 프로젝트
@@ -448,12 +485,12 @@ php artisan config:clear
### 요약 표
| 작업 | 로컬 (Docker) | 서버 |
|------|--------------|------|
| 작업 | 로컬 (Docker) | 서버 (네이티브) |
|------|--------------|----------------|
| git pull | WSL에서 직접 | 서버에서 직접 |
| composer install | `docker exec sam-api-1 composer install` | `composer install` |
| migrate | `docker exec sam-api-1 php artisan migrate` | `php artisan migrate` |
| config:clear | `docker exec sam-api-1 php artisan config:clear` | `php artisan config:clear` |
| composer install | `docker exec sam-api-1 composer install` | `composer install` (직접) |
| migrate | `docker exec sam-api-1 php artisan migrate` | `php artisan migrate` (직접) |
| config:clear | `docker exec sam-api-1 php artisan config:clear` | `php artisan config:clear` (직접) |
### 체크리스트 (pull 후)