658 lines
48 KiB
Markdown
658 lines
48 KiB
Markdown
# 📐 구현 계획서 Rev.2: `docker/` 프로덕션 배포 자산 정본화 (Job `2168e631`)
|
||
|
||
- **작성일**: 2026-08-23
|
||
- **역할**: Planner (`.agents/MULTI_AGENT_RULES.md` §1 — Planner 는 저장소 코드/문서를 **수정하지 않으며**, 산출물은 본 계획서입니다)
|
||
- **기준 커밋**: `3523b9b` (테스트 **297건 수집** 실측)
|
||
- **선행 리비전**: `810987f6` (Rev.1) ← 본 문서가 대체합니다
|
||
- **판정 대상 리뷰**: `2934740e` (agy, `[VERDICT: PASS WITH CHALLENGE]`) — WebSocket `same_origin` 기본값 이의제기
|
||
- **대상 산출물**: `docker/docker-compose.yaml`, `docker/nats.conf`, `docker/.env.example`, `docker/README.md`, `tests/test_deploy_freshness.py` (D-22 ~ **D-30**)
|
||
- **테스트 수 예상**: 297 → **306** (Rev.1 의 305 에서 D-30 추가)
|
||
|
||
---
|
||
|
||
## A. 리뷰 판정 (Adjudication of Challenge `2934740e`)
|
||
|
||
### A-1. 판정 요약
|
||
|
||
| 항목 | 판정 | 근거 |
|
||
|---|---|---|
|
||
| **전제**: "`websocket {}` 를 원점 설정 없이 정의하면 NATS 가 `same_origin: true` 로 기본 동작한다" | ❌ **기각 (사실과 반대)** | `SameOrigin` 은 평범한 `bool` 필드이고 **기본값을 `true` 로 설정하는 코드가 저장소 어디에도 없음**. `checkOrigin()` 은 `!checkSame && listEmpty` 일 때 **즉시 `nil` 반환** |
|
||
| **귀결**: "브라우저 대시보드가 403 Forbidden 으로 거부된다" | ❌ **기각** | 403 경로는 실재하나(`websocket.go:869`) 도달 조건이 성립하지 않음. 현 설정에서 교차 출처 브라우저 접속은 **그대로 성공** |
|
||
| **처방 1**: `same_origin: false` 추가 | ⚠️ **부분 수용 (무해하나 no-op)** | 유효한 키이나 기본값과 동일. "꺼야만 동작한다"는 잘못된 서사를 설정 파일에 새기게 됨 → **주석으로 사실을 기록**하는 형태로 변환 수용 |
|
||
| **처방 2**: `allowed_origins: ["*"]` | 🔴 **강력 기각 — 서버가 기동하지 못함** | `validateWebsocketOptions` 가 `"*"` 의 scheme 이 http/https 가 아니라며 **에러 반환**(`websocket.go:1142-1143`). 이 처방을 따르면 브로커가 **아예 뜨지 않음** |
|
||
| **처방 3**: Mixed Content(`https://` → `ws://`) 문서화 | ✅ **전면 수용** | NATS 와 무관한 브라우저 정책이며 실제로 홈랩에서 자주 발생. §3.4 트러블슈팅 표에 반영 |
|
||
| **부수 효과** | 🟢 **신규 발견 N-7** | 챌린지가 지목한 "Plane B 브라우저 대시보드" 영역을 파다가, **8080 이 `/mqtt` 경로로 MQTT-over-WebSocket 도 서빙**한다는 사실을 확인. Rev.2 이래 미해결이던 열린 질문이 이걸로 **해소**됨 |
|
||
|
||
### A-2. 전제가 왜 사실과 반대인가 — 실측
|
||
|
||
**(1) 구조체 필드 주석이 명시적으로 반대를 말합니다.** `server/opts.go:672-677`:
|
||
|
||
```go
|
||
// If true, the Origin header must match the request's host.
|
||
SameOrigin bool
|
||
|
||
// Only origins in this list will be accepted. If empty and
|
||
// SameOrigin is false, any origin is accepted.
|
||
AllowedOrigins []string
|
||
```
|
||
|
||
**(2) 기본값을 `true` 로 세우는 코드가 없습니다.** `SameOrigin = true` / `SameOrigin:` (구조체 리터럴) 로 grep 하면 `opts.go`·`websocket.go` 양쪽에서 **0건**입니다. 값은 오직 설정 파서에서만 대입됩니다(`opts.go:5545-5546`). 따라서 Go 제로값 `false` 가 그대로 유효 기본값입니다.
|
||
|
||
**(3) 검사 자체가 단락(short-circuit)됩니다.** `server/websocket.go:1034-1041`:
|
||
|
||
```go
|
||
func (w *srvWebsocket) checkOrigin(r *http.Request) error {
|
||
checkSame := w.sameOrigin
|
||
listEmpty := len(w.allowedOrigins) == 0
|
||
if !checkSame && listEmpty {
|
||
return nil // ← 우리 설정이 여기서 끝납니다
|
||
}
|
||
...
|
||
```
|
||
|
||
우리 `websocket { port: 8080, no_tls: true }` 는 `sameOrigin=false`, `allowedOrigins` 비어 있음 → 첫 조건에서 `nil` 반환. `Origin` 헤더를 읽지도 않습니다. **`http://localhost:3000` 에서 뜬 React 대시보드가 `ws://100.x.y.z:8080` 로 붙는 시나리오는 아무 변경 없이 성공합니다.**
|
||
|
||
챌린지가 인용한 403 경로는 실재합니다(`websocket.go:868-870`, `StatusForbidden`, `"origin not allowed: %v"`). 다만 그 문은 `checkSame || !listEmpty` 일 때만 열립니다. 즉 **문은 있으나 우리 설정에서는 그 앞까지 가지 않습니다.**
|
||
|
||
### A-3. 처방 2 를 따르면 브로커가 죽는다 — 실측
|
||
|
||
`allowed_origins: ["*"]` 는 단지 불필요한 게 아니라 **기동 차단** 설정입니다. `server/websocket.go:1136-1150` (`validateWebsocketOptions`):
|
||
|
||
```go
|
||
for _, ao := range wo.AllowedOrigins {
|
||
u, err := url.ParseRequestURI(ao)
|
||
if err != nil { return fmt.Errorf("unable to parse allowed origin: %v", err) }
|
||
if u.Scheme != "http" && u.Scheme != "https" {
|
||
return fmt.Errorf("unable to parse allowed origin %q: allowed origins must be "+
|
||
"absolute URLs with http or https scheme", ao)
|
||
}
|
||
if u.Host == _EMPTY_ { ... }
|
||
```
|
||
|
||
`"*"` 는 scheme 이 비어 있으므로 두 번째 분기에서 에러. 옵션 검증 실패는 기동 실패입니다. 게다가 논리적으로도 역효과입니다 — `AllowedOrigins` 를 비우지 않는 순간 `listEmpty` 가 `false` 가 되어 **원점 검사가 켜집니다**. "모두 허용"을 의도한 설정이 "검사 활성화"를 유발하는 구조입니다.
|
||
|
||
> [!IMPORTANT]
|
||
> 이 항목은 챌린지의 처방을 그대로 구현했다면 **프로덕션 브로커가 기동조차 못 했을** 사안입니다. 리뷰를 지시가 아니라 가설로 취급하고 측정한 결과이며, `MULTI_AGENT_RULES.md` §1 의 '[REBUT:]' 절차에 해당합니다.
|
||
|
||
### A-4. 그럼에도 챌린지가 옳게 짚은 것
|
||
|
||
1. **Mixed Content 는 100% 실재하는 제약**입니다. NATS 설정과 무관하게, `https://` 로 서빙된 페이지는 `ws://` 연결을 브라우저가 차단합니다. 홈랩에서 대시보드를 HTTPS 로 올리는 순간 8080 평문 WS 는 못 씁니다. §3.4 트러블슈팅에 반영합니다.
|
||
2. **운영자가 반드시 궁금해할 지점을 정확히 지목**했습니다. Rev.1 의 `websocket { port: 8080, no_tls: true }` 는 원점 정책에 대해 **아무 말도 하지 않았고**, 그래서 리뷰어가 정반대로 추정했습니다. 설정 파일이 침묵하면 독자가 최악을 가정한다는 증거입니다 — 주석으로 사실을 명문화합니다(§3.1).
|
||
3. **보안 방향은 오히려 반대로 열려 있습니다.** 기본값이 관대하므로, 8080 을 tailnet 밖으로 내보내는 순간 임의 웹 페이지가 핸드셰이크를 시도할 수 있습니다(인증은 별도로 막지만). 완화가 아니라 **강화** 처방(`allowed_origins` 에 실제 대시보드 URL)이 필요하며, 이를 주석 템플릿으로 제공하고 D-30 가드로 `"*"` 회귀를 봉인합니다.
|
||
|
||
### A-5. 신규 발견 N-7 — 8080 은 MQTT-over-WebSocket 도 서빙한다 (열린 질문 해소)
|
||
|
||
챌린지의 주제(Plane B 브라우저 대시보드)를 측정하다 확인한 사실입니다.
|
||
|
||
```go
|
||
// server/websocket.go:820-833
|
||
if r.URL != nil {
|
||
ep := r.URL.EscapedPath()
|
||
if strings.HasSuffix(ep, leafNodeWSPath) { kind = LEAF }
|
||
else if strings.HasSuffix(ep, mqttWSPath) { kind = MQTT } // mqttWSPath = "/mqtt"
|
||
}
|
||
// Reject MQTT-over-WebSocket upgrades unless MQTT is enabled.
|
||
if kind == MQTT && opts.MQTT.Port == 0 { ... 404 ... }
|
||
|
||
// server/websocket.go:1333-1335
|
||
case MQTT:
|
||
s.createMQTTClient(res.conn, res.ws) // ← 1883 리스너와 동일 함수
|
||
```
|
||
|
||
- `mqttWSPath = "/mqtt"` (`server/mqtt.go:193`).
|
||
- 게이트는 `opts.MQTT.Port != 0` 뿐이며, 우리 설정은 `mqtt { port: 1883 }` 이므로 **이미 충족**입니다.
|
||
- 생성 함수가 네이티브 1883 리스너와 **동일한 `createMQTTClient`** (`mqtt.go:552` vs `websocket.go:1335`) 이므로, 이 연결은 트랜스포트만 WebSocket 인 **완전한 MQTT 클라이언트**입니다.
|
||
|
||
**이것이 왜 중요한가**: Rev.2(`b11d499d`) 이래 남아 있던 열린 질문 — *"대시보드를 MQTT 로 붙일 것인가, 아니면 N-1(retained 는 MQTT 전용) 제약을 받아들이고 JetStream 리플레이 스트림을 만들 것인가"* — 가 **제3의 답으로 해소**됩니다.
|
||
|
||
> 브라우저 대시보드가 **MQTT.js 로 `ws://mam-hub:8080/mqtt` 에 접속하면**, 그것은 MQTT 클라이언트이므로 `mqttSendRetainedMsgsToNewSubs` 경로를 그대로 타고 **retained 종료 이벤트를 받습니다**. 별도 리플레이 스트림도, 디스크 관리 부담도 필요 없습니다.
|
||
|
||
반면 같은 8080 포트라도 **NATS 네이티브 WebSocket**(경로 없음 또는 `/`)으로 붙으면 N-1 이 그대로 적용되어 종료 이벤트를 못 받습니다. **같은 포트, 다른 경로, 다른 결과** — 이 함정은 반드시 문서화되어야 합니다.
|
||
|
||
부수 효과로 노출 모델 서술도 정정이 필요합니다: 8080 은 "Plane B 전용"이 아니라 **MQTT 프로토콜 표면을 함께 노출**합니다(인증은 계정 설정이 동일하게 강제).
|
||
|
||
---
|
||
|
||
## B. Rev.1 → Rev.2 변경 요약
|
||
|
||
| # | 변경 | 출처 |
|
||
|---|---|---|
|
||
| C-1 | `docker/nats.conf` `websocket {}` 블록에 **원점 정책 사실 주석 + `allowed_origins` 강화 템플릿(주석)** 추가. `same_origin: false` 는 **활성 라인으로 넣지 않음** | 챌린지 §2.3-1 변환 수용 |
|
||
| C-2 | `docker/nats.conf` `websocket {}` 에 **`/mqtt` 경로 = MQTT-over-WS** 사실 주석 추가 | N-7 |
|
||
| C-3 | `docker/README.md` 트러블슈팅에 **WS 403(정확한 발동 조건)** · **Mixed Content** · **`/mqtt` vs `/` 경로 차이** 3행 추가 | 챌린지 §2.3-2 + N-7 |
|
||
| C-4 | `docker/README.md` 6절(클라이언트 연결)에 **브라우저 대시보드 접속 레시피** 신설 | N-7 |
|
||
| C-5 | 신규 가드 **D-30**(WebSocket 원점 정책이 기동 가능한 형태인지) 추가 → 305 → **306** | A-3 |
|
||
| C-6 | 문서 동기화 작업에 **T-5** 신설: `PRIVATE_SERVER.md` §5.1/§5.2 의 '두 소비 평면' 서술에 세 번째 경로(MQTT-over-WS) 반영 | N-7 |
|
||
| C-7 | 실측 원장에 **M-19 ~ M-24** 추가 | A-2 / A-3 / N-7 |
|
||
| C-8 | 열린 질문에서 'Rev.2 이월 질문' **삭제(해소됨)**, 대신 Q-5(대시보드 프로토콜 선택 권고) 로 대체 | N-7 |
|
||
|
||
Rev.1 의 §2 설계 결정 D-1 ~ D-8, §3.2 compose, §3.3 `.env.example`, §4 가드 D-22 ~ D-29, §5 T-1 ~ T-4, §7 발견 N-2 ~ N-6 은 **리뷰에서 전부 승인**되었으며 변경 없이 유지합니다.
|
||
|
||
---
|
||
|
||
## 0. 요약 — 이 계획이 무엇을 확정하는가
|
||
|
||
`PRIVATE_SERVER.md` §9 는 지금까지 **문서 안의 코드 펜스**로만 존재했습니다. 펜스는 복사-붙여넣기 대상이지 배포 자산이 아니므로,
|
||
|
||
1. 서버에 실제로 올라간 설정이 문서와 갈라져도 아무도 알 수 없고,
|
||
2. `test_deploy_freshness.py` 의 D-15 ~ D-19 가드는 **문서만** 검사하므로 실제 배포물의 회귀를 잡지 못하며,
|
||
3. 시크릿을 어디에 두는지가 규약이 아니라 관습으로 남습니다.
|
||
|
||
본 계획은 §9 의 펜스를 `docker/` 하위의 **정본(canonical) 파일**로 승격시키고, 문서↔파일 드리프트를 9종의 신규 가드(D-22 ~ D-30)로 봉인합니다.
|
||
|
||
> [!IMPORTANT]
|
||
> 현재 저장소에는 **0 바이트짜리 `docker/docker-compose.yaml`** 이 untracked 상태로 존재합니다(`git status` = `?? docker/`). 신규 가드 D-22 는 이 상태에서 **즉시 FAIL** 하도록 설계되어 있습니다 — 즉 가드가 공허하게 통과하지 않음이 착수 시점에 자동으로 증명됩니다.
|
||
|
||
---
|
||
|
||
## 1. 실측 기반 (Measurement Ledger)
|
||
|
||
| # | 검증 항목 | 방법 | 실측 결과 |
|
||
|---|---|---|---|
|
||
| M-1 | 테스트 베이스라인 | `pytest tests/ -q --collect-only` | **297 collected** |
|
||
| M-2 | `nats:2.12-alpine` 태그 실재 | Docker Hub API `library/nats/tags?name=2.12` | 존재. 최신 패치 **2.12.15** (2026-08-12) |
|
||
| M-3 | alpine 이미지 베이스 | `nats-docker/main/2.12.x/alpine3.22/Dockerfile` | `FROM alpine:3.22` → **busybox `wget` 내장** |
|
||
| M-4 | 엔트리포인트 인자 처리 | 동 디렉터리 `docker-entrypoint.sh` | `[ "${1#-}" != "$1" ] && set -- nats-server "$@"` → `command: ["-c", …]` **동작** |
|
||
| M-5 | 이미지 HEALTHCHECK 유무 | 동 Dockerfile | **없음** → compose 가 반드시 정의 |
|
||
| M-6 | 미해결 `$VAR` 동작 | `conf/parse.go:390` | 파싱 에러 = **fail-closed** |
|
||
| M-7 | 환경변수 값 재파싱 | `conf/parse.go` `lookupVariable` → `parseEnv(...)` | 환경변수 값이 **NATS 렉서로 재파싱** (N-5) |
|
||
| M-8 | 비인용 문자열 종결자 | `conf/lex.go:958-960` | NL, EOF, `;`, `,`, `]`, `}`, 공백. `=` `+` `/` 는 **비종결자** |
|
||
| M-9 | `mqtt {}` 유효 키 | `server/opts.go` `parseMQTT` | `port`/`ack_wait`/`max_ack_pending` **전부 유효** |
|
||
| M-10 | `max_ack_pending` 상한 | `opts.go:5673-5679` | `[0..65535]`. **1024 유효** |
|
||
| M-11 | `jetstream {}` 유효 키 | `opts.go` `parseJetStream` | `store_dir`, `max_file`, `max_mem` **전부 유효** |
|
||
| M-12 | 크기 접미사 대소문자 | `opts.go:2507` `suffixMap` | `{"K","M","G","T"}` **대문자 전용** (N-6) |
|
||
| M-13 | `websocket {}` 유효 키 | `opts.go` `parseWebsocket` | `port`, `no_tls`, `same_origin`, `allowed_origins` 등 유효 |
|
||
| M-14 | `.gitignore` 거동 | `git check-ignore -v` | `docker/.env` **ignored**(`:21`), `docker/.env.example` **tracked**(`:23`) |
|
||
| M-15 | 비인용 `${VAR:?msg}` YAML | PyYAML 6.0.3 파싱 | 평문 스칼라 → **문서 원문 그대로 파일화 가능** |
|
||
| M-16 | PyYAML 선언 여부 | `requirements.txt`=1행, `tests/test_sanity.py:3`=`import yaml` | **미선언 하드 의존** (N-2) |
|
||
| M-17 | 설치 스크립트 배포 범위 | `deploy/install.sh:365-374` | `docker/`·`PRIVATE_SERVER.md` **미배포** |
|
||
| M-18 | `DEFAULT_TOPIC_ROOT` | `mqtt_common.py:119` | `"python/mqtt/jobs"` |
|
||
| **M-19** | **`SameOrigin` 기본값** | `opts.go` 전역 grep `SameOrigin = true` / `SameOrigin:` | **0건** → Go 제로값 `false`. 주석(`opts.go:676-677`)도 "empty and SameOrigin is false → any origin is accepted" 명시 |
|
||
| **M-20** | **`checkOrigin` 단락 조건** | `websocket.go:1034-1041` | `!checkSame && listEmpty` → **즉시 `nil`**. `Origin` 헤더를 읽지 않음 |
|
||
| **M-21** | **403 발동 지점** | `websocket.go:868-870` | `StatusForbidden "origin not allowed"` — `checkOrigin` 이 에러일 때만 |
|
||
| **M-22** | **`allowed_origins: ["*"]`** | `websocket.go:1136-1150` `validateWebsocketOptions` | scheme 이 http/https 가 아니라며 **옵션 검증 실패 → 기동 실패** |
|
||
| **M-23** | **`no_tls` 필요성** | `websocket.go:1132-1134` | `TLSConfig == nil && !NoTLS` → `websocket requires TLS configuration`. 현 설정의 `no_tls: true` 는 **필수** |
|
||
| **M-24** | **MQTT-over-WebSocket** | `mqtt.go:193` `mqttWSPath="/mqtt"`; `websocket.go:824,832,1334-1335` | 8080 의 `/mqtt` 경로가 `createMQTTClient` 로 분기. 게이트는 `MQTT.Port != 0` 뿐 → **이미 활성** (N-7) |
|
||
|
||
---
|
||
|
||
## 2. 설계 결정 (Design Decisions)
|
||
|
||
### D-1. 파일명은 `docker/docker-compose.yaml` + 문서 참조 정정
|
||
브리프는 `.yaml`, `PRIVATE_SERVER.md` §9.2 제목은 `.yml` 을 씁니다. Compose 는 둘 다 인식하므로 기능 차는 없습니다. **브리프를 정본으로 채택**하고 문서 참조를 정정합니다(T-3). 두 곳이 다른 채로 남으면 D-23 doc↔file 가드가 무엇을 비교하는지 모호해집니다.
|
||
|
||
### D-2. 계정 사용자명은 `mam_agent` / `mam_observer` 유지
|
||
브리프의 `MAM with mam/observer` 축약은 **계정 구조**를 가리킨 것으로 읽습니다. 식별자를 바꾸면 `PRIVATE_SERVER.md` §6 (`MQTT_USERNAME=mam_agent`) 과 §9.4 R-9 플레이북이 조용히 깨집니다.
|
||
|
||
### D-3. `version: '3.8'` 제거
|
||
Compose V2 는 매 `up` 마다 `the attribute 'version' is obsolete` 경고를 냅니다. 프로덕션 자산이 상시 경고를 뿜으면 운영자가 경고를 무시하는 습관을 들입니다. 기능 영향 0.
|
||
|
||
### D-4. `.env.example` 의 시크릿은 **빈 값**으로 출하 (fail-closed 의 핵심)
|
||
|
||
| 방식 | `cp .env.example .env` 후 결과 |
|
||
|---|---|
|
||
| `MAM_BROKER_PASS=changeme` | 브로커 **정상 기동**. 전 세계가 아는 암호로 프로덕션 가동 = **fail-open** |
|
||
| `MAM_BROKER_PASS=` (빈 값) ✅ | `${VAR:?…}` 는 콜론 형태라 **빈 값에서도 중단** → 컨테이너 생성 전 비영점 종료 |
|
||
|
||
방어는 이중입니다: Compose 보간 실패(1차) → 그래도 떴다면 `nats.conf` 미해결 `$VAR` 파싱 에러(M-6, 2차).
|
||
|
||
### D-5. `nats.conf` 는 시크릿을 한 글자도 담지 않는다
|
||
모든 `password:` 는 `$VAR` 참조. 따라서 `docker/nats.conf` 는 커밋 가능하고, 시크릿은 gitignore 된 `docker/.env` 에만 존재합니다(M-14). D-25(e) 가 봉인합니다.
|
||
|
||
### D-6. 암호 생성기는 `openssl rand -base64 32` 로 고정하고 이유를 문서화
|
||
파서 제약입니다(M-7/M-8). 암호에 `공백 ; , ] } # ' " $` 가 들어가면 설정이 깨지거나 조용히 다른 값이 됩니다. base64 알파벳(`A-Za-z0-9+/=`)은 이 집합과 교집합이 0입니다.
|
||
|
||
### D-7. healthcheck 는 `wget` 유지 — 이미지 계열과 **커플링**해서 봉인
|
||
`wget` 은 alpine 베이스에만 있습니다(M-3). D-28 은 healthcheck 존재와 이미지 alpine 여부를 **한 테스트 안에서** 단언합니다. 분리하면 이미지만 바꾸는 커밋이 통과합니다.
|
||
|
||
### D-8. `docker/` 는 하위 워크스페이스로 배포하지 않는다
|
||
`install.sh` 는 `PRIVATE_SERVER.md` 조차 배포하지 않습니다(M-17). `docker/` 는 **이 저장소가 운영하는 서버**의 자산이므로 동일하게 저장소 전용으로 둡니다. `install.sh` 를 건드리지 않는 것이 명시적 결정입니다(Q-3).
|
||
|
||
### D-9 (신규). WebSocket 원점 정책은 **활성 설정이 아니라 주석으로** 다룬다
|
||
|
||
세 가지 선택지를 검토했습니다.
|
||
|
||
| 선택 | 결과 |
|
||
|---|---|
|
||
| `same_origin: false` 활성 추가 (챌린지 처방 1) | 동작상 **no-op**(M-19). 그러나 설정 파일이 "이걸 꺼야 브라우저가 붙는다"는 **거짓 서사**를 후임자에게 전달 |
|
||
| `allowed_origins: ["*"]` (챌린지 처방 2) | 🔴 **기동 실패**(M-22) |
|
||
| **주석으로 기본 동작을 명문화 + 강화 템플릿을 주석 제공** ✅ | 동작 불변, 리뷰어가 실제로 겪은 정보 공백을 메움, 8080 을 tailnet 밖으로 낼 때 필요한 **강화** 경로를 즉시 제공 |
|
||
|
||
세 번째를 채택합니다. 리뷰어의 관찰(설정이 원점 정책에 침묵한다)은 타당했고, 처방(끄기)만 방향이 반대였습니다. 침묵을 메우되 사실대로 메웁니다.
|
||
|
||
---
|
||
|
||
## 3. 산출물 명세 (Creator 구현 사양)
|
||
|
||
### 3.1 `docker/nats.conf`
|
||
|
||
```conf
|
||
# ==============================================================================
|
||
# docker/nats.conf — MAM 원격 프로덕션 브로커 (Track 1R)
|
||
#
|
||
# 정본 문서: PRIVATE_SERVER.md §9.1
|
||
# 시크릿: 이 파일에는 없습니다. 모든 password 는 docker/.env → compose
|
||
# environment → 컨테이너 환경변수로 주입되는 $VAR 참조입니다.
|
||
#
|
||
# ⚠ 암호 문자 제약: NATS 는 환경변수 값을 자체 설정 렉서로 재파싱합니다.
|
||
# 암호에 [공백 ; , ] } # ' " $] 가 들어가면 설정이 깨지거나 다르게 해석됩니다.
|
||
# 반드시 `openssl rand -base64 32` (알파벳 A-Za-z0-9+/=) 를 사용하십시오.
|
||
# ==============================================================================
|
||
server_name: mam-hub
|
||
|
||
# ── JetStream: MQTT retained/QoS1 저장소. 종료 이벤트 재수신이 여기에 의존 ──
|
||
jetstream {
|
||
store_dir: "/data" # 절대경로 고정. '~' 도 인용된 "$HOME" 도 확장되지 않음
|
||
max_file: 10G # 접미사는 대문자만 유효 (K/M/G/T)
|
||
max_mem: 256M
|
||
}
|
||
|
||
http_port: 8222 # 무인증 모니터링 → 호스트 게시는 loopback 한정 (compose)
|
||
|
||
mqtt {
|
||
port: 1883
|
||
ack_wait: 60s # WAN RTT 흡수 (기본 30s)
|
||
max_ack_pending: 1024 # 다중 에이전트 동시 발행 여유 (상한 65535)
|
||
}
|
||
|
||
websocket {
|
||
port: 8080
|
||
no_tls: true # 사설망/tailnet 한정. 생략하면 TLS 설정 필수라 기동 실패
|
||
|
||
# ── 원점(Origin) 정책 ────────────────────────────────────────────────
|
||
# 기본값은 이미 '모든 출처 허용'입니다. same_origin 의 기본값은 false 이고
|
||
# allowed_origins 가 비어 있으면 checkOrigin() 이 Origin 헤더를 읽지도 않고
|
||
# 즉시 nil 을 반환합니다 (server/websocket.go:1039).
|
||
# → http://localhost:3000 의 브라우저 대시보드는 별도 설정 없이 접속됩니다.
|
||
# → `same_origin: false` 를 적는 것은 no-op 입니다.
|
||
#
|
||
# 8080 을 tailnet 밖으로 노출한다면 아래를 켜서 출처를 좁히십시오.
|
||
# 주의: allowed_origins 를 비우지 않는 순간 원점 검사가 '켜집니다'.
|
||
# "*" 는 절대 쓰지 마십시오 — 옵션 검증 실패로 서버가 기동하지 못합니다
|
||
# (websocket.go:1142 "must be absolute URLs with http or https scheme").
|
||
# allowed_origins: ["https://dashboard.example", "http://localhost:3000"]
|
||
|
||
# ── 이 포트는 MQTT-over-WebSocket 도 서빙합니다 ───────────────────────
|
||
# 경로 /mqtt 로 붙으면 완전한 MQTT 클라이언트가 됩니다 (mqtt.go:193,
|
||
# websocket.go:1335 → createMQTTClient, 1883 리스너와 동일 함수).
|
||
# ws://<host>:8080/mqtt → MQTT. retained 종료 이벤트를 받습니다.
|
||
# ws://<host>:8080/ → NATS 네이티브. retained 를 받지 못합니다 (N-1).
|
||
# 브라우저 대시보드는 MQTT.js 로 /mqtt 에 붙이는 것을 권장합니다.
|
||
}
|
||
|
||
# ── 인증 및 멀티테넌시 ────────────────────────────────────────────────────
|
||
accounts {
|
||
MAM: {
|
||
jetstream: enabled # MQTT 내부 스트림이 이 계정 안에 생성됨
|
||
users: [
|
||
# 발행자 겸 구독자 — MAM 에이전트 본체 (.mam.env 의 MQTT_USERNAME)
|
||
{ user: mam_agent, password: $MAM_BROKER_PASS }
|
||
|
||
# 관측자 — 대시보드/모니터링. 반드시 MAM 계정 안에 위치
|
||
{ user: mam_observer, password: $MAM_OBSERVER_PASS,
|
||
permissions: {
|
||
subscribe: { allow: ["python.mqtt.jobs.>"] } # M3 이후: "mam.<fp>.jobs.>"
|
||
publish: { deny: [">"] }
|
||
}
|
||
}
|
||
]
|
||
}
|
||
# MAM 과 무관한 홈랩 서비스 전용. MAM subject 는 보이지 않음(의도된 격리)
|
||
HOME: { jetstream: enabled, users: [ { user: home, password: $HOME_BROKER_PASS } ] }
|
||
SYS: { users: [ { user: sys, password: $SYS_BROKER_PASS } ] }
|
||
}
|
||
system_account: SYS
|
||
```
|
||
|
||
**계약 값** (가드 검사 대상): `store_dir` = `/data` · `mqtt.port` = `1883` · `websocket.port` = `8080` · `http_port` = `8222` · 계정 `MAM`/`HOME`/`SYS` · 사용자 `mam_agent`/`mam_observer`/`home`/`sys` · subject 접두 `python.mqtt.jobs` · 모든 `password:` 는 `$` 시작 · 활성 `allowed_origins` 에 `"*"` 없음(D-30).
|
||
|
||
> [!NOTE]
|
||
> `accounts {}` 를 정의하고 `no_auth_user` 를 두지 않았으므로 **익명 접속은 MQTT·NATS·WebSocket 전 경로에서 거부**됩니다. 이는 §9.4 R-3(노출 면적 0)과 독립된 두 번째 방어선이며, N-7 로 드러난 `/mqtt` 표면에도 동일하게 적용됩니다.
|
||
|
||
### 3.2 `docker/docker-compose.yaml`
|
||
|
||
```yaml
|
||
# ==============================================================================
|
||
# docker/docker-compose.yaml — MAM 원격 프로덕션 브로커 (Track 1R)
|
||
# 정본 문서: PRIVATE_SERVER.md §9.2
|
||
#
|
||
# 사용법: cd docker && cp .env.example .env && <시크릿 채우기> && docker compose up -d
|
||
# ==============================================================================
|
||
services:
|
||
nats:
|
||
image: nats:2.12-alpine # alpine 필수: healthcheck 의 wget 이 여기에만 있음
|
||
container_name: mam-nats
|
||
restart: unless-stopped
|
||
command: ["-c", "/etc/nats/nats.conf"]
|
||
environment:
|
||
# 미설정/빈 값이면 컨테이너 생성 전에 compose 가 중단 → fail-closed
|
||
MAM_BROKER_PASS: ${MAM_BROKER_PASS:?set MAM_BROKER_PASS in docker/.env}
|
||
MAM_OBSERVER_PASS: ${MAM_OBSERVER_PASS:?set MAM_OBSERVER_PASS in docker/.env}
|
||
HOME_BROKER_PASS: ${HOME_BROKER_PASS:?set HOME_BROKER_PASS in docker/.env}
|
||
SYS_BROKER_PASS: ${SYS_BROKER_PASS:?set SYS_BROKER_PASS in docker/.env}
|
||
ports:
|
||
# ⚠ Docker 의 published 포트는 UFW 를 우회합니다. 노출 통제는 방화벽이 아니라
|
||
# 여기의 바인드 주소가 담당합니다. 기본값은 전부 loopback.
|
||
- "${MQTT_BIND:-127.0.0.1}:1883:1883" # MQTT 3.1.1 (평면 A: MAM)
|
||
- "${NATS_BIND:-127.0.0.1}:4222:4222" # NATS 네이티브 (평면 B)
|
||
- "127.0.0.1:8222:8222" # 무인증 모니터링 — loopback 고정
|
||
- "${WS_BIND:-127.0.0.1}:8080:8080" # WebSocket (NATS + /mqtt 경로의 MQTT)
|
||
volumes:
|
||
- ./nats.conf:/etc/nats/nats.conf:ro
|
||
- nats-data:/data # nats.conf 의 store_dir 와 일치
|
||
healthcheck:
|
||
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8222/healthz"]
|
||
interval: 30s
|
||
timeout: 5s
|
||
retries: 3
|
||
start_period: 20s
|
||
logging:
|
||
driver: json-file
|
||
options: { max-size: "10m", max-file: "3" }
|
||
|
||
volumes:
|
||
nats-data:
|
||
```
|
||
|
||
**주의 사항**
|
||
- `8222` 만 바인드 주소가 하드코딩입니다. 나머지 3개는 `${*_BIND:-127.0.0.1}` 로 tailnet IP 주입을 허용하되 기본값이 loopback 입니다. D-24 가 이 비대칭을 검사합니다.
|
||
- `./nats.conf` 는 compose 프로젝트 디렉터리 기준 상대경로이므로 `docker/` 안에서 실행해야 합니다.
|
||
- 비인용 `${VAR:?msg}` 는 PyYAML 로 평문 스칼라 파싱됨을 실측(M-15). 인용부호 추가 불필요.
|
||
|
||
### 3.3 `docker/.env.example`
|
||
|
||
```bash
|
||
# ==============================================================================
|
||
# docker/.env.example — 원격 브로커 서버 측 환경변수 템플릿
|
||
#
|
||
# 이 파일은 git 에 커밋됩니다 (.gitignore:23 의 `!.env.example`).
|
||
# 복사본 docker/.env 는 git 에서 제외됩니다 (.gitignore:21 의 `.env`).
|
||
#
|
||
# cd docker && cp .env.example .env && chmod 600 .env
|
||
#
|
||
# ⚠ 아래 시크릿 4종은 의도적으로 **빈 값**입니다. 채우지 않고 그대로 복사하면
|
||
# `docker compose up` 이 컨테이너를 만들기 전에 실패합니다 (fail-closed).
|
||
# 플레이스홀더 문자열을 넣지 마십시오 — '알려진 암호로 가동'이 최악입니다.
|
||
# ==============================================================================
|
||
|
||
# ── 시크릿 (필수) ────────────────────────────────────────────────────────
|
||
# 생성: openssl rand -base64 32
|
||
#
|
||
# ⚠ 반드시 위 명령을 사용하십시오. NATS 는 환경변수 값을 설정 렉서로 재파싱하므로
|
||
# 암호에 [공백 ; , ] } # ' " $] 가 포함되면 설정이 깨지거나 다르게 해석됩니다.
|
||
# base64 알파벳(A-Za-z0-9+/=)은 이 문자들과 교집합이 없어 안전합니다.
|
||
|
||
# MAM 에이전트 발행/구독 계정 (.mam.env 의 MQTT_PASSWORD 와 동일 값)
|
||
MAM_BROKER_PASS=
|
||
|
||
# 관측 전용 계정 (구독 allow: python.mqtt.jobs.>, 발행 전면 deny)
|
||
MAM_OBSERVER_PASS=
|
||
|
||
# MAM 과 무관한 홈랩 서비스용 별도 계정
|
||
HOME_BROKER_PASS=
|
||
|
||
# 시스템 계정 ($SYS). 운영 이벤트/모니터링 전용
|
||
SYS_BROKER_PASS=
|
||
|
||
# ── 리스너 바인드 주소 (선택 — 미설정 시 전부 127.0.0.1) ──────────────────
|
||
# ⚠ Docker 의 published 포트는 UFW 를 우회합니다. 아래 값이 실질적인 노출 통제입니다.
|
||
# 모델 T(Tailscale) 권장 설정: MQTT_BIND=$(tailscale ip -4)
|
||
#
|
||
# MQTT 1883 리스너 바인드 주소
|
||
# MQTT_BIND=127.0.0.1
|
||
#
|
||
# NATS 4222 네이티브 리스너 바인드 주소
|
||
# NATS_BIND=127.0.0.1
|
||
#
|
||
# WebSocket 8080 바인드 주소.
|
||
# 참고: 이 포트는 NATS WebSocket 과 MQTT-over-WebSocket(/mqtt)을 함께 서빙합니다.
|
||
# WS_BIND=127.0.0.1
|
||
#
|
||
# HTTP 모니터 8222 는 무인증이므로 바인드 주소를 변수화하지 않습니다 (loopback 고정).
|
||
```
|
||
|
||
**설계 포인트**: 시크릿 4종은 **주석 해제 없이 빈 값으로 활성**, 바인드 주소 3종은 **주석 처리**. 이 비대칭이 "시크릿은 반드시 채워야 하고, 바인드는 안 채워도 안전한 기본값"이라는 의도를 파일 형태로 표현합니다.
|
||
|
||
### 3.4 `docker/README.md`
|
||
|
||
| 절 | 내용 | 정본 |
|
||
|---|---|---|
|
||
| 1. 무엇인가 | 이 디렉터리가 MAM 관측 백플레인 브로커의 정본임. `PRIVATE_SERVER.md` §9 링크 | §9 |
|
||
| 2. 사전 요구 | Docker Engine + Compose V2, (모델 T) Tailscale, 개방 포트 없음 | §9.3 |
|
||
| 3. 5분 배포 | `docker/` 복사 → `cp .env.example .env` → `openssl rand -base64 32` ×4 → `chmod 600 .env` → `docker compose up -d` → `docker compose ps` **healthy** | §9.2 |
|
||
| 4. 네트워크 잠금 | UFW 규칙 전문 + **published 포트가 UFW 를 우회**한다는 경고를 최상단에 | §9.3 |
|
||
| 5. 노출 검증 | 외부 망에서 `nmap -Pn -p 1883,4222,8222,8080 <공개IP>` → 전부 closed/filtered (R-3) | §9.4 |
|
||
| 6. 클라이언트 연결 | (a) MAM 저장소 `.mam.env` 기입 (b) **브라우저 대시보드 레시피** (아래) | §6 + N-7 |
|
||
| 7. 검증 플레이북 | R-1 ~ R-10 표 + 지연 측정 스니펫 링크 | §9.4 |
|
||
| 8. 운영 | 로그 로테이션(내장), JetStream 볼륨 백업, `docker compose pull && up -d`, `/varz`·`/jsz` 는 SSH 터널 경유 | §9 P6 |
|
||
| 9. 트러블슈팅 | 아래 표 | 신규 |
|
||
|
||
**6절 (b) 브라우저 대시보드 접속 레시피** — N-7 반영, 필수 신설:
|
||
|
||
```js
|
||
// MQTT.js — retained 종료 이벤트까지 받는 경로 (권장)
|
||
const client = mqtt.connect("ws://mam-hub.tailXXXX.ts.net:8080/mqtt", {
|
||
username: "mam_observer",
|
||
password: "<MAM_OBSERVER_PASS>",
|
||
protocolVersion: 4, // MQTT 3.1.1
|
||
});
|
||
client.subscribe("python/mqtt/jobs/+/events");
|
||
// 이 클라이언트는 서버에서 완전한 MQTT 클라이언트로 취급되므로
|
||
// 잡이 끝난 뒤에 접속해도 retained 최종 이벤트를 즉시 수신합니다.
|
||
|
||
// nats.ws — 경로 없이 붙으면 NATS 네이티브. 라이브 스트림만 수신하며
|
||
// 이미 끝난 잡의 종료 이벤트는 받지 못합니다 (N-1).
|
||
```
|
||
|
||
**9절 트러블슈팅 표(필수 항목)**
|
||
|
||
| 증상 | 원인 | 조치 |
|
||
|---|---|---|
|
||
| `required variable MAM_BROKER_PASS is missing` | `.env` 미생성 또는 빈 값 | 의도된 fail-closed. 시크릿을 채울 것 |
|
||
| `variable reference for 'MAM_BROKER_PASS' … can not be found` | compose 통과했으나 컨테이너에 변수 미주입 | `environment:` 블록 누락 확인 |
|
||
| 컨테이너는 뜨는데 계속 `unhealthy` | 이미지를 `latest`/`scratch`/non-alpine 로 변경 → `wget` 부재 | `nats:2.12-alpine` 로 복귀 |
|
||
| 설정이 알 수 없는 값으로 해석됨 | 암호에 렉서 종결자 포함 | `openssl rand -base64 32` 로 재발급 |
|
||
| `max_file` 에러 | `10g` 등 소문자 접미사 | 대문자 `10G` |
|
||
| 원격에서 접속 불가 | 바인드가 loopback 기본값 | `.env` 에 `MQTT_BIND=$(tailscale ip -4)` |
|
||
| `JetStream not enabled for account` | 계정에 `jetstream: enabled` 누락 | `MAM` 계정 블록 확인 |
|
||
| **WebSocket `403 origin not allowed`** | **기본 설정에서는 발생하지 않습니다.** `allowed_origins` 를 채웠거나 `same_origin: true` 를 켠 경우에만 발동 | 해당 설정을 지우거나, 대시보드 URL을 `allowed_origins` 에 추가 |
|
||
| **서버가 `allowed origins must be absolute URLs…` 로 기동 실패** | `allowed_origins` 에 `"*"` 또는 scheme 없는 값 | `["https://dashboard.example"]` 처럼 절대 URL 로 |
|
||
| **브라우저 콘솔의 Mixed Content 차단** | `https://` 페이지에서 `ws://` 연결 시도 | 대시보드를 tailnet 내부 `http://` 로 서빙하거나, 리버스 프록시로 `wss://` 종단 제공 |
|
||
| **대시보드가 종료 이벤트를 못 받음** | 8080 에 **경로 없이**(NATS 네이티브) 접속함. retained 는 MQTT 전용 (N-1) | `ws://host:8080/**mqtt**` 로 MQTT.js 접속 (N-7) |
|
||
|
||
---
|
||
|
||
## 4. 신규 회귀 가드 D-22 ~ D-30
|
||
|
||
`tests/test_deploy_freshness.py` 말미에 추가합니다. 기존 D-11 ~ D-21 스타일(모듈 상단 상수, 펜스 스코핑, 공허 통과 방지 단언)을 따릅니다.
|
||
|
||
### 4.1 공통 헬퍼
|
||
|
||
```python
|
||
DOCKER_DIR = os.path.join(REPO_ROOT, "docker")
|
||
COMPOSE_PATH = os.path.join(DOCKER_DIR, "docker-compose.yaml")
|
||
NATS_CONF_PATH = os.path.join(DOCKER_DIR, "nats.conf")
|
||
ENV_EXAMPLE_PATH = os.path.join(DOCKER_DIR, ".env.example")
|
||
DOCKER_README_PATH = os.path.join(DOCKER_DIR, "README.md")
|
||
|
||
SECRET_VARS = {"MAM_BROKER_PASS", "MAM_OBSERVER_PASS",
|
||
"HOME_BROKER_PASS", "SYS_BROKER_PASS"}
|
||
|
||
|
||
def _load_compose():
|
||
"""compose 파일을 dict 로. 파일이 비었거나 nats 서비스가 없으면 즉시 실패."""
|
||
import yaml
|
||
with open(COMPOSE_PATH, encoding="utf-8") as f:
|
||
doc = yaml.safe_load(f)
|
||
assert isinstance(doc, dict) and doc.get("services"), (
|
||
"docker/docker-compose.yaml is empty or has no services: — the docker/ "
|
||
"assets were never populated")
|
||
svc = doc["services"].get("nats")
|
||
assert svc, "compose file defines no 'nats' service"
|
||
return doc, svc
|
||
|
||
|
||
def _active_conf_lines():
|
||
"""nats.conf 에서 주석을 제외한 '활성' 라인만. 주석 템플릿을 오탐하지 않기 위함."""
|
||
with open(NATS_CONF_PATH, encoding="utf-8") as f:
|
||
lines = [ln.split("#", 1)[0].rstrip() for ln in f]
|
||
return [ln for ln in lines if ln.strip()]
|
||
```
|
||
|
||
> `_active_conf_lines()` 는 D-30 의 정확도를 위한 것입니다. §3.1 은 `allowed_origins` 를 **주석 템플릿**으로 제공하므로, 주석을 그대로 스캔하면 가드가 자기 문서를 오탐합니다.
|
||
|
||
### 4.2 가드 명세
|
||
|
||
| ID | 이름 | 단언 | 공허 통과 방지 | 잡아내는 회귀 |
|
||
|---|---|---|---|---|
|
||
| **D-22** | `docker_assets_exist_and_are_populated` | 4개 파일 존재 + 크기 > 0, compose 가 `nats` 서비스를 갖는 dict 로 파싱 | `_load_compose()` 가 `services` 비면 실패 | **현재의 0바이트 compose**, 자산 삭제 |
|
||
| **D-23** | `compose_image_matches_doc_and_is_alpine` | compose 의 `nats:<tag>` == `PRIVATE_SERVER.md` 펜스에서 추출한 태그, `tag != "latest"`, `"alpine" in tag` | 양쪽에서 태그 추출 실패 시 실패 | 한쪽만 업그레이드하는 드리프트, scratch 회귀 |
|
||
| **D-24** | `compose_port_exposure_contract` | 컨테이너 포트 집합 == `{1883,4222,8222,8080}`; 모든 게시가 3필드 → **bare `"1883:1883"` 금지**; `8222` 는 정확히 `127.0.0.1:8222:8222` | `ports` 비면 실패 | 바인드 누락으로 인터넷 노출, 포트 오타 |
|
||
| **D-25** | `secrets_are_fail_closed` | (a) `nats.conf` 의 모든 `$VAR` ⊆ compose `environment:` 키 (b) 값이 전부 `:?` 형태 (c) `SECRET_VARS` 전부 `.env.example` 에 존재 (d) `.env.example` 의 시크릿 4종 값이 **빈 문자열** (e) `nats.conf` 의 모든 `password:` 값이 `$` 시작 | `$VAR` 0건이면 실패 | 플레이스홀더 암호, 평문 시크릿, `:?`→`:-` 완화 |
|
||
| **D-26** | `nats_conf_jetstream_and_mqtt_contract` | `store_dir` 절대경로 + compose 볼륨 타깃과 **동일**; `max_file`/`max_mem` 이 `^\d+[KMGT]$`; `mqtt {` + `port: 1883`; `MAM` 계정 `jetstream: enabled` | 추출 실패 시 실패 | `store_dir`↔볼륨 불일치(데이터 유실), 소문자 접미사, 계정 JS 누락 |
|
||
| **D-27** | `observer_permissions_match_topic_root` | subject 리터럴이 `mqtt_common.DEFAULT_TOPIC_ROOT.replace("/",".")` 로 시작; `mam_observer` 에 `publish` `deny` 존재 | 리터럴 0건이면 실패 | M3 지문 토픽 전환 시 관측자 권한 고아화 |
|
||
| **D-28** | `healthcheck_contract_and_image_coupling` | healthcheck 존재 + `/healthz` + `127.0.0.1:8222` + `wget`; **동일 테스트에서** 이미지가 alpine 계열임을 단언 | healthcheck 키 없으면 실패 | healthcheck 삭제, wget 없는 이미지 |
|
||
| **D-29** | `env_secrets_never_tracked` | `git check-ignore docker/.env` rc == 0; `.env.example` 은 not-ignored; `git ls-files docker/.env` 빈 출력 | — | `.gitignore` 완화로 실제 시크릿 커밋 |
|
||
| **D-30** 🆕 | `websocket_origin_policy_is_startable` | **활성**(비주석) 라인 기준: (a) `websocket {` 블록에 `no_tls: true` 존재(M-23); (b) `allowed_origins` 가 활성이라면 그 항목이 전부 `http://` 또는 `https://` 로 시작 — 특히 **`"*"` 금지**(M-22); (c) `nats.conf` 가 `/mqtt` 경로 주석을 포함해 N-7 지식이 유실되지 않음 | `websocket {` 블록을 못 찾으면 실패 | **챌린지 처방 2를 그대로 구현했을 때의 기동 불능**, `no_tls` 누락으로 인한 TLS 요구 에러, N-7 문서 소실 |
|
||
|
||
### 4.3 뮤테이션 수용 기준 (구현 완료의 정의)
|
||
|
||
가드는 **깨져야 할 때 깨지는 것이 증명되어야** 통과로 인정합니다. Creator 는 아래를 각각 적용 → 해당 테스트 FAIL 확인 → 원복하고, 로그를 커밋 메시지 또는 리뷰 요청에 첨부합니다.
|
||
|
||
| 뮤테이션 | FAIL 해야 하는 가드 |
|
||
|---|---|
|
||
| `docker-compose.yaml` 을 0바이트로 되돌림 | D-22 |
|
||
| 이미지를 `nats:latest` 로 변경 | D-23, D-28 |
|
||
| `- "1883:1883"` (바인드 주소 제거) | D-24 |
|
||
| `8222` 를 `0.0.0.0:8222:8222` 로 변경 | D-24 |
|
||
| `.env.example` 의 `MAM_BROKER_PASS=` → `=changeme` | D-25 |
|
||
| compose 의 `:?` → `:-` 로 완화 | D-25 |
|
||
| `store_dir: "/data"` → `"/var/lib/nats"` (볼륨 유지) | D-26 |
|
||
| `subscribe.allow` 를 `"mam.>"` 로 변경 | D-27 |
|
||
| healthcheck 블록 삭제 | D-28 |
|
||
| `.gitignore` 에 `!docker/.env` 추가 | D-29 |
|
||
| **`allowed_origins: ["*"]` 를 활성 라인으로 추가** | **D-30** |
|
||
| **`websocket {}` 에서 `no_tls: true` 삭제** | **D-30** |
|
||
|
||
> [!IMPORTANT]
|
||
> **D-22 는 착수 시점에 이미 FAIL 합니다** (0바이트 compose 파일 때문). 가드를 먼저 커밋하고 자산을 채우는 **테스트 우선 순서**로 진행하면, 이 가드가 공허하게 통과하지 않는다는 사실이 별도 뮤테이션 없이 자동 증명됩니다.
|
||
|
||
### 4.4 예상 테스트 수
|
||
|
||
| 시점 | 수 |
|
||
|---|---|
|
||
| 현재 (`3523b9b`) — 실측 | **297** |
|
||
| D-22 ~ D-30 추가 후 | **306** |
|
||
|
||
---
|
||
|
||
## 5. 문서 동기화 작업 (Creator 범위)
|
||
|
||
`docker/` 만 만들고 문서를 두면 다음 리뷰에서 "무엇이 정본인가"가 다시 논쟁이 됩니다. 아래 5건을 **같은 커밋**에 포함합니다.
|
||
|
||
| ID | 파일 | 작업 |
|
||
|---|---|---|
|
||
| **T-1** | `PRIVATE_SERVER.md` §9 서두 | "본 절의 설정은 [`docker/`](docker/) 에 정본 파일로 존재하며 아래 펜스는 그 사본입니다. 어긋나면 `tests/test_deploy_freshness.py` 의 D-22~D-30 이 실패합니다." 1문단 추가 |
|
||
| **T-2** | `PRIVATE_SERVER.md` §9.1 / §9.2 | 펜스를 `docker/nats.conf`·`docker/docker-compose.yaml` 최종본과 **일치**시킴 (`version: '3.8'` 제거, **§3.1 의 websocket 주석 블록 포함**) |
|
||
| **T-3** | `PRIVATE_SERVER.md` §9.2 제목 · §9.3 `.env` 블록 | `docker-compose.yml` → `docker/docker-compose.yaml`; `.env` 생성 절차를 `docker/.env.example` 복사 방식으로 교체 |
|
||
| **T-4** | `implementation_plan.md` §5 / §8 | §5 로드맵에 **P0.5 `docker/` 자산 정본화** 삽입; §8 M2b 에서 이미 완료된 `G-D5~G-D9, G-R1, G-R2` 를 `[x]` 로 정정(N-4)하고 `docker/` 자산 + D-22~D-30 (297 → 306) 항목 신설 |
|
||
| **T-5** 🆕 | `PRIVATE_SERVER.md` §5.1 / §5.2 | '두 개의 소비 평면' 서술에 **세 번째 경로**를 명문화: 8080 은 NATS WebSocket 과 **MQTT-over-WebSocket(`/mqtt`)** 을 함께 서빙하며, 후자만 retained 종료 이벤트를 받는다(N-1 ↔ N-7 연결). §5.2 의 브리징 문단이 현재 이 구분 없이 서술되어 있어 정정 대상 |
|
||
|
||
T-2 수행 시 주의: §9.1/§9.2 펜스는 기존 D-15 ~ D-19 가드의 검사 대상이기도 하므로, 편집 후 **전체 스위트를 돌려** 기존 7종 가드의 회귀 없음을 확인해야 합니다.
|
||
|
||
---
|
||
|
||
## 6. 실행 순서 및 완료 정의
|
||
|
||
```
|
||
[1] 가드 선행 커밋 ──> [2] docker/ 자산 작성 ──> [3] 문서 동기화 ──> [4] 뮤테이션 검증 ──> [5] 서버 실배포
|
||
D-22~D-30 추가 3.1~3.4 (4개 파일) T-1~T-5 §4.3 12건 전건 R-1~R-10 (+R-11)
|
||
D-22 FAIL 확인 306 전건 GREEN 기존 D-15~D-19 각 FAIL→원복 (별도 잡)
|
||
회귀 없음
|
||
```
|
||
|
||
**DoD (본 잡의 완료 정의)**
|
||
1. `docker/` 4개 파일이 §3 사양대로 존재하고, `docker/.env` 는 존재하지 않는다.
|
||
2. `pytest tests/ -q` 가 **306건 전건 통과**.
|
||
3. §4.3 뮤테이션 12건이 각각 지정된 가드를 FAIL 시킴이 로그로 확인된다.
|
||
4. T-1 ~ T-5 문서 동기화가 동일 커밋에 포함된다.
|
||
5. `git status` 에 `docker/.env` 가 나타나지 않는다(D-29 로 자동 보증).
|
||
|
||
**게이트**: 3번(뮤테이션 전건 FAIL) 미충족 시 커밋 금지. 통과하지 않는 가드는 가드가 아니라 주석입니다.
|
||
|
||
**신규 원격 검증 항목** (서버 배포 잡으로 이월):
|
||
|
||
| ID | 검증 | 방법 | 통과 기준 |
|
||
|---|---|---|---|
|
||
| **R-11** | healthcheck 의 음성 대조 | 컨테이너 안에서 `wget -q -O /dev/null http://127.0.0.1:8222/healthzX` (404) | **비영점 종료** — 200 이 아닐 때 실제로 실패함을 증명 |
|
||
| **R-12** | 교차 출처 브라우저 접속 | 다른 오리진의 페이지에서 `new WebSocket("ws://<host>:8080/")` | **핸드셰이크 성공** (A-2 의 반증 가능 형태 — 403 이 나오면 M-19/M-20 판정이 틀린 것) |
|
||
| **R-13** | MQTT-over-WS retained | 잡 종료 **후** MQTT.js 로 `ws://<host>:8080/mqtt` 접속 → 구독 | **retained 최종 이벤트 수신** (N-7 확증. 0건이면 N-7 이 틀린 것) |
|
||
|
||
R-12 와 R-13 은 **의도적으로 반증 가능하게** 작성했습니다. 실측이 틀렸다면 이 두 항목에서 드러나며, 그 경우 §A-2 와 §A-5 를 폐기하고 챌린지의 처방 1을 재검토해야 합니다.
|
||
|
||
**본 잡 범위 밖**: 실제 서버 프로비저닝, Tailscale 가입, `.mam.env` 전환, R-1 ~ R-13 실행.
|
||
|
||
---
|
||
|
||
## 7. 발견 사항 (Findings)
|
||
|
||
### N-2 (P2) — `PyYAML` 이 선언되지 않은 하드 테스트 의존
|
||
`requirements.txt` 는 `pytest>=8.0` **단 한 줄**인데 `tests/test_sanity.py:3` 은 최상단에서 `import yaml` 합니다. 현재 venv 에는 설치되어 있어 드러나지 않지만, `requirements.txt` 만으로 새 venv 를 만들면 **수집 단계에서 다수 파일이 에러**납니다. D-22 ~ D-28 이 `yaml` 의존을 더 깊게 만듭니다.
|
||
**처방**: `requirements.txt` 에 `PyYAML>=6.0` 추가. (`pytest.importorskip` 은 부적절 — 스킵되면 배포 가드가 조용히 사라집니다.)
|
||
|
||
### N-3 (P2) — D-16 가드의 구멍: `nats:2.12` 가 통과한다
|
||
`tests/test_deploy_freshness.py:387` 의 `assert "-alpine" in tag or tag.startswith("2.")` 는 `or` 때문에 `nats:2.12`(non-alpine) 나 `nats:2.12-scratch` 를 통과시킵니다. 그런데 healthcheck 는 alpine 에만 있는 `wget` 을 씁니다(M-3). 즉 D-16 은 자신이 막으려던 실패 모드의 **인접 변종을 놓칩니다**.
|
||
**처방**: `assert "alpine" in tag` 로 단순화.
|
||
|
||
### N-4 (P3) — `implementation_plan.md` 체크리스트가 실제보다 뒤처짐
|
||
§8 M2b 의 `- [ ] 신규 가드 G-D5 ~ G-D9, G-R1, G-R2 …(290 -> 297)` 이 미체크이나 실측 수집 수는 **297** 이고 D-15 ~ D-21 이 이미 존재합니다. T-4 에서 정정합니다.
|
||
|
||
### N-5 (P2) — NATS 는 환경변수 값을 **설정 렉서로 재파싱**한다
|
||
`conf/parse.go` 의 `lookupVariable` 은 환경변수를 `parseEnv(fmt.Sprintf("%s=%s", pkey, vStr), p)` 로 **다시 파싱**합니다(M-7). 비인용 문자열 종결자는 NL·EOF·`;`·`,`·`]`·`}`·공백(M-8)이며 `#`·`$`·따옴표도 위험합니다. 문서는 `openssl rand -base64 32` 를 쓰면서 **왜 그래야 하는지**를 적지 않았습니다. §3.1/§3.3 주석과 README 트러블슈팅에 명문화합니다.
|
||
|
||
### N-6 (P3) — 크기 접미사는 대문자 전용
|
||
`opts.go:2507` `suffixMap` 은 `{"K","M","G","T"}` 뿐. `max_file: 10g` 는 기동 실패. D-26 이 `^\d+[KMGT]$` 로 봉인합니다.
|
||
|
||
### N-7 (P1, 신규) — 8080 은 `/mqtt` 경로로 MQTT-over-WebSocket 을 서빙한다
|
||
§A-5 참조. `mqttWSPath = "/mqtt"`(`mqtt.go:193`)이며 `websocket.go:1334-1335` 가 네이티브 1883 리스너와 **동일한 `createMQTTClient`** 로 분기합니다. 게이트는 `opts.MQTT.Port != 0` 뿐이라 우리 설정에서 **이미 활성**입니다. 세 가지 귀결:
|
||
1. 브라우저 대시보드가 MQTT.js 로 `/mqtt` 에 붙으면 **retained 종료 이벤트를 받습니다** → Rev.2 이래의 열린 질문 해소, JetStream 리플레이 스트림 불필요.
|
||
2. 같은 포트에 경로만 다르게 붙으면(NATS 네이티브) N-1 이 그대로 적용되어 종료 이벤트를 못 받습니다. **같은 포트, 다른 경로, 다른 결과** — 함정입니다.
|
||
3. 노출 모델 서술 정정 필요: 8080 은 'Plane B 전용'이 아니라 **MQTT 프로토콜 표면을 함께 노출**합니다(인증은 동일 계정 규칙으로 강제).
|
||
|
||
### N-1 재확인 (기존) — retained 는 MQTT 전용
|
||
`mqttSendRetainedMsgsToNewSubs` 가 `mqttPacketSub` 핸들러에서만 호출되고 MQTT 전용 필드 `sub.mqtt.prm` 를 순회한다는 Rev.2 실측은 유효합니다. 다만 N-7 로 **경계가 프로토콜이지 포트가 아님**이 분명해졌습니다 — MQTT-over-WS 도 MQTT 이므로 retained 를 받습니다.
|
||
|
||
---
|
||
|
||
## 8. 열린 질문 (비차단)
|
||
|
||
계획은 아래 답 없이 그대로 실행 가능합니다. 기본값을 명시했으므로 **응답이 없으면 기본값으로 진행**합니다.
|
||
|
||
| # | 질문 | 기본값(무응답 시) |
|
||
|---|---|---|
|
||
| **Q-1** | 이미지 핀을 `nats:2.12-alpine`(마이너 추종) 로 둘 것인가, `2.12.15-alpine`(패치 고정) 으로 조일 것인가? | `2.12-alpine` 유지 — 문서 §9.2 와 일치, 보안 패치 자동 수령 |
|
||
| **Q-2** | 컨테이너를 비루트(`user: "1000:1000"`) 로 돌릴 것인가? | 변경하지 않음 — `nats-data` 볼륨 소유권 초기화가 필요해 무증상 실패 위험. 별도 하드닝 잡으로 분리 |
|
||
| **Q-3** | `docker/` 를 `deploy/install.sh` 로 하위 워크스페이스에 배포할 것인가? | 배포하지 않음 (D-8) |
|
||
| **Q-4** | `.mam.env` 의 `MQTT_PASSWORD` ↔ 서버 `docker/.env` 의 `MAM_BROKER_PASS` 동기화를 스크립트화할 것인가? | 수동 — 두 파일이 다른 호스트에 있어 자동화는 시크릿 전송 경로를 새로 만드는 일. README 6절에 절차만 기술 |
|
||
| **Q-5** 🆕 | 대시보드 프로토콜: MQTT.js(`/mqtt`) 로 통일할 것인가, `nats.ws` 도 허용할 것인가? | **MQTT.js 단일 권장.** retained 를 무상으로 얻고 N-1 함정이 사라짐. `nats.ws` 는 KV/JetStream 같은 NATS 고유 기능이 필요할 때만 |
|
||
|
||
> Rev.2(`b11d499d`) 이래 이월되던 *"대시보드를 MQTT 로 붙일 것인가, JetStream 리플레이 스트림의 디스크 관리 부담을 수용할 것인가"* 는 **N-7 로 해소**되어 목록에서 제거했습니다. 브라우저에서도 MQTT 를 쓸 수 있으므로 리플레이 스트림은 불필요합니다.
|
||
|
||
---
|
||
|
||
## 9. 부록 — Creator 착수 체크리스트
|
||
|
||
- [ ] `tests/test_deploy_freshness.py` 에 §4.1 헬퍼(`_load_compose`, `_active_conf_lines`) + D-22 ~ D-30 추가 → `pytest -k d22` 가 **FAIL** 하는지 먼저 확인
|
||
- [ ] `requirements.txt` 에 `PyYAML>=6.0` 추가 (N-2)
|
||
- [ ] `docker/nats.conf` 작성 — **websocket 주석 블록 포함** (§3.1)
|
||
- [ ] `docker/docker-compose.yaml` 작성 — 기존 0바이트 파일 덮어쓰기 (§3.2)
|
||
- [ ] `docker/.env.example` 작성 — 시크릿 4종 **빈 값** 확인 (§3.3)
|
||
- [ ] `docker/README.md` 작성 — 브라우저 레시피 + 트러블슈팅 12행 (§3.4)
|
||
- [ ] `PRIVATE_SERVER.md` T-1 ~ T-3, **T-5** (§5)
|
||
- [ ] `implementation_plan.md` T-4 (§5)
|
||
- [ ] D-16 단언 정정 (N-3)
|
||
- [ ] `pytest tests/ -q` → **306 passed**
|
||
- [ ] §4.3 뮤테이션 **12건** 각각 FAIL 확인 후 원복, 로그 첨부
|
||
- [ ] `git status` 에 `docker/.env` 부재 확인
|
||
- [ ] ⚠️ **`allowed_origins: ["*"]` 를 활성 설정으로 넣지 말 것** — 브로커가 기동하지 못합니다 (§A-3, M-22)
|