From da81d69712097d24fa810e4b4ad15dac8f0a8a74 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Mar 2026 11:57:47 +0900
Subject: [PATCH] docs: add server-specific mount runbook and ufw dependency
 guardrails

---
 ...��사고_복구_및_의존포트_점검.md | 30 +++++++++++++++++--
 ...51123_ufw_외부포트_차단_하드닝.md | 21 +++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/journey/troubleshooting/2026-03-03_51123_DB5432_차단사고_복구_및_의존포트_점검.md b/journey/troubleshooting/2026-03-03_51123_DB5432_차단사고_복구_및_의존포트_점검.md
index 037f8e7..362946b 100644
--- a/journey/troubleshooting/2026-03-03_51123_DB5432_차단사고_복구_및_의존포트_점검.md
+++ b/journey/troubleshooting/2026-03-03_51123_DB5432_차단사고_복구_및_의존포트_점검.md
@@ -98,8 +98,34 @@ sudo ufw allow from 172.16.0.0/12 to any port 5432 proto tcp
 - `완료 전`: 핵심 서비스 헬스 + 최근 오류로그 교차 확인
 
 3. UFW 정책 원칙
-- 전면 허용(`Anywhere`) 대신 서버 단위 허용으로 운영
-- 예: `5432`는 `192.168.219.52`만 허용
+- 전면 허용(`Anywhere`) 대신 **의존 출발지 단위 최소 허용**으로 운영
+- `5432`는 최소 `192.168.219.52` + Docker 브리지 `172.16.0.0/12`를 포함해야 함
+
+## 운영 보강: 서버별 마운트 아키텍처 분기
+NAS 관련 장애 점검은 51123/51124가 서로 다른 구조임을 전제로 수행해야 함.
+
+- 51123: NAS/fallback 구조
+  - `/mnt/nas`, `/mnt/hdd/nas-fallback`
+  - `/etc/fstab`에 CIFS 항목(`//192.168.219.51/home /mnt/nas cifs ...`)
+- 51124: sshfs 연계 구조
+  - `/mnt/51123data`, `/mnt/51123logs` (sshfs)
+  - NAS CIFS/fallback 항목 없음
+
+즉, 같은 NAS 불통이어도 "경로가 다르다"는 사실 자체는 장애가 아니라 서버별 아키텍처 차이임.
+
+### NAS 실패 판정 규칙
+- `No route to host`와 `Timeout`은 둘 다 **연결 실패**로 동일 분류한다.
+- 에러 문구 차이는 시점/라우팅 상태에 따라 달라질 수 있으므로, 원인 분류 키로 사용하지 않는다.
+
+### 완료 전 필수 게이트 (고정)
+1. 컨테이너 env 기반 의존성 스캔
+2. 51124 -> 51123 포트 매트릭스 (`5432/9000/8100/7687`)
+3. 핵심 API 실호출
+   - `auth-server /auth/naverworks/passport/refresh`
+   - `skill-email /messages*`
+4. 서버별 스토리지 분기 점검
+   - 51123: NAS/fallback 경로
+   - 51124: sshfs 경로
 
 ## 명령어 체크리스트
 ```bash
diff --git a/journey/troubleshooting/2026-03-03_51123_ufw_외부포트_차단_하드닝.md b/journey/troubleshooting/2026-03-03_51123_ufw_외부포트_차단_하드닝.md
index ac5b3b1..651d825 100644
--- a/journey/troubleshooting/2026-03-03_51123_ufw_외부포트_차단_하드닝.md
+++ b/journey/troubleshooting/2026-03-03_51123_ufw_외부포트_차단_하드닝.md
@@ -47,3 +47,24 @@ sudo ufw --force delete allow 7474/tcp
 ## 후속 권장
 - Docker 퍼블리시 포트(`8000/8100/8200/9000/9200/9600`)의 외부 노출 축소(가능한 `127.0.0.1` 또는 내부 네트워크만 사용)
 - PostgreSQL `listen_addresses`, `pg_hba.conf`를 내부 대역 기반으로 추가 제한
+
+## 사후 정정 (2026-03-03 11:40 KST)
+초기 차단 조치만으로는 충분하지 않았고, 실제 운영 의존 경로를 일부 누락한 상태였다.
+
+- 누락된 의존 경로:
+  - 51124 직접 경로: `192.168.219.52 -> 51123:5432`
+  - Docker 브리지 경로: `172.16.0.0/12 -> 51123:5432` (예: auth-server `host.docker.internal:5432`)
+- 결과:
+  - `auth-server /auth/naverworks/passport/refresh` 타임아웃
+  - `skill-email /messages*` 연쇄 500
+
+복구 시 최종 반영한 규칙:
+
+```bash
+sudo ufw allow from 192.168.219.52 to any port 5432 proto tcp
+sudo ufw allow from 172.16.0.0/12 to any port 5432 proto tcp
+```
+
+최종 정책(정정):
+- "5432는 무조건 전체 차단"이 아니라, **실제 의존 출발지 단위 최소 허용**이 원칙.
+- 하드닝 변경 시 반드시 컨테이너 env 기반 의존성 스캔 + 변경 직후 연계 API 실호출을 완료해야 한다.