docs: [ops] .env 권한 장애 대응 문서 업데이트

- 08-troubleshooting: .env 권한 오류 → 500 에러 진단/조치 사례 추가
- 09-security: .env 권한 600→640 수정, vimrc backupcopy 설정 안내
- 02-daily-operations: .env 편집 시 주의사항 섹션 추가

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

deploys/ops-manual/02-daily-operations.md

@@ -30,6 +30,24 @@ sudo systemctl status gitea
 
 ---
 
+## [운영] .env 파일 편집 시 주의사항
+
+> **경고:** `vi`로 `.env`를 편집하면 권한이 `600`으로 변경되어 서비스 장애가 발생할 수 있습니다.
+
+```bash
+# 편집 전 권한 확인
+ls -la /home/webservice/api/shared/.env    # 640(-rw-r-----)이어야 함
+
+# 편집 후 반드시 권한 확인 및 복원
+chmod 640 /home/webservice/api/shared/.env
+chmod 640 /home/webservice/mng/shared/.env
+```
+
+이를 방지하려면 `~/.vimrc`에 `set backupcopy=yes`가 설정되어 있어야 합니다.
+자세한 내용: [09-security.md - .env 파일 보안](./09-security.md)
+
+---
+
 ## 시스템 리소스 모니터링
 
 양쪽 서버 공통 명령어:

deploys/ops-manual/08-troubleshooting.md

@@ -135,6 +135,58 @@ FLUSH PRIVILEGES;"
 
 ---
 
+### .env 권한 오류로 전체 500 에러 (API + MNG)
+
+**증상:** api.sam.it.kr, mng.sam.it.kr 모든 요청에서 500 에러. PHP-FPM, Redis, MySQL 모두 정상.
+
+**원인:** `.env` 파일 권한이 `600`(`-rw-------`)으로 변경되어 PHP-FPM(`www-data`)이 읽지 못함. 모든 환경변수가 null이 되면서 `DB_CONNECTION`, `CACHE_STORE` 등이 기본값(SQLite)로 fallback.
+
+**주요 발생 원인:**
+- `vi`로 `.env` 편집 시 파일이 재생성되면서 umask에 따라 `600`으로 변경됨
+- 배포 스크립트에서 권한 미설정
+
+**진단:**
+
+```bash
+# 1. .env 권한 확인 (640이어야 정상)
+ls -la /home/webservice/api/shared/.env
+ls -la /home/webservice/mng/shared/.env
+
+# 2. www-data로 읽기 테스트
+sudo -u www-data cat /home/webservice/api/shared/.env | head -1
+# "Permission denied" → 권한 문제 확인
+
+# 3. artisan으로 config 확인 (CLI는 sudo로 정상 작동)
+sudo php /home/webservice/api/current/artisan config:show cache
+# default가 database/file이면 .env 미반영 상태
+```
+
+**조치:**
+
+```bash
+sudo chmod 640 /home/webservice/api/shared/.env
+sudo chmod 640 /home/webservice/mng/shared/.env
+```
+
+**예방:**
+- 서버 계정 `~/.vimrc`에 `set backupcopy=yes` 추가 (vi 편집 시 권한 유지)
+- 배포 스크립트에 `chmod 640` 포함
+- 자세한 내용: 09-security.md "[운영] .env 파일 보안" 참조
+
+**실제 사례 (2026-03-03):**
+
+1. `.env`에서 `GEMINI_MODEL` 값을 `vi`로 변경
+2. `vi`가 파일을 재생성하면서 권한 `600`으로 변경
+3. PHP-FPM(`www-data`)이 `.env` 읽기 실패 → 모든 env 값 null
+4. `CACHE_STORE=null` → 기본값 `database` → SQLite 연결 시도 → 500 에러
+5. `chmod 640`으로 권한 복원하여 즉시 해결
+
+**진단 포인트:**
+- CLI(`artisan tinker`)에서는 정상인데 웹만 500 → **파일 권한 문제 의심**
+- Laravel 로그에 기록이 없으면 **로그 파일 쓰기 권한도 확인**
+
+---
+
 ### Redis 메모리 부족
 
 **증상:** "OOM command not allowed" 메시지.

deploys/ops-manual/09-security.md

@@ -168,18 +168,37 @@ sudo systemctl restart fail2ban
 
 ## [운영] .env 파일 보안
 
+> **주의:** `.env` 권한은 반드시 `640` (`-rw-r-----`)이어야 합니다.
+> PHP-FPM은 `www-data` 사용자(webservice 그룹)로 실행되므로 그룹 읽기 권한이 필요합니다.
+> `600`으로 설정하면 PHP-FPM이 .env를 읽지 못해 **전체 서비스 500 에러**가 발생합니다.
+> (실제 장애 사례: 2026-03-03, 08-troubleshooting.md 참조)
+
 ```bash
-# 권한 확인 (600이어야 함)
+# 권한 확인 (640이어야 함 — 소유자 rw + 그룹 r)
 ls -la /home/webservice/api/shared/.env
 ls -la /home/webservice/mng/shared/.env
 ls -la /home/webservice/sales/.env
 
 # 권한 수정
-chmod 600 /home/webservice/api/shared/.env
+chmod 640 /home/webservice/api/shared/.env
-chmod 600 /home/webservice/mng/shared/.env
+chmod 640 /home/webservice/mng/shared/.env
-chmod 600 /home/webservice/sales/.env
+chmod 640 /home/webservice/sales/.env
 ```
 
+### vi 편집 시 권한 변경 방지
+
+`vi`로 파일을 편집하면 새 파일로 교체되면서 권한이 `600`으로 초기화될 수 있습니다.
+이를 방지하기 위해 서버 계정의 `~/.vimrc`에 아래 설정을 추가합니다:
+
+```bash
+# 원본 파일에 직접 덮어쓰기 (권한 유지)
+echo "set backupcopy=yes" >> ~/.vimrc
+```
+
+**적용 현황 (2026-03-03):**
+- sam-prod: hskwon, pro 계정 적용 완료
+- sam-cicd: hskwon, pro 계정 적용 완료
+
 ---
 
 ## [운영] Redis 보안