tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(broker): establish remote Docker deployment plan for nats-server with networking/security guides and add D-15~D-21 freshness guards

Browse Source
This commit is contained in:
Godopu
2026-08-22 23:47:29 +09:00
parent c6b6c77ce4
commit 3523b9b1ea
7 changed files with 1215 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
implementation_plan.md
+42 -22
View File
@@ -20,6 +20,7 @@
|---|---|---|---|
| **Track 0** | `B-14`, `B-15` (P1) | 브로커 다운 시 65분 정지(Hang) 및 오판정 방지 (로컬 디스크 내결함성) | `publish_event.py`, `job_subscriber.py`, `multi-agent-mux-delegate-job` |
| **Track 1** | `O-5` (P2) | `nats-server` MQTT 3.1.1 어댑터 호환성 및 Retained 메시지 실측 검증 | 격리 클론 (`$SCRATCH/nats-spike`) |
| **Track 1R** | 원격 프로덕션 (P1) | VPS/홈랩 `nats-server` Docker 상시 가동 및 MAM 원격 백플레인 전환 | `PRIVATE_SERVER.md` §9, 서버측 `docker-compose.yml`/`nats.conf`, `.mam.env` |
| **Track 2** | `A-2`, `B-16` (P2) | 워크스페이스 지문 토픽 격리 및 `auth_token` 무조건 발급 강제 | `mqtt_common.py`, `registry.py`, `reconcile.sh` |
| **Track 3** | 문서/설정 동기화 | 공식 가이드, 배포 스크립트, 환경변수 템플릿 일원화 | `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` |
@@ -30,15 +31,16 @@
각 마일스톤은 완료 정의(DoD)와 엄격한 게이트(Gate)를 가지며, 게이트 조건을 충족하지 못하면 다음 마일스톤으로 진입할 수 없습니다.
```
M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실증) ──> M3 (Track 2 보안) ──> M4 (Track 3 완결)
M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스파이크) ──> M2b (원격 배포) ──> M3 (Track 2 보안) ──> M4 (Track 3 완결)
```
| 마일스톤 | 이름 | 완료 정의 (Definition of Done) | 통과 게이트 (Gate Condition) |
|---|---|---|---|
| **M0** | 문서 정합성 확보 | `PRIVATE_SERVER.md` E-1~E-4 교정, 다능성 절 추가, 본 로드맵 작성 | **G-D1 ~ G-D4 가드 테스트 통과** (276 -> 280) |
| **M1** | 내결함성 확보 (Track 0) | `B-14`, `B-15` 코드 패치 완료 | **G-1 ~ G-10 가드 통과 + mutation 전건 FAIL 확인** (280 -> 290) |
| **M2** | 브로커 실증 (Track 1) | 격리 클론에서 S-1 ~ S-9 스파이크 완수 | **S-3(Retained Terminal Event) 통과** (실패 시 mosquitto로 분기) |
| **M3** | 보안 종결 (Track 2) | A-2 지문 토픽 전환, G-11 무조건 토큰 발급 | 지문 토픽 동작 확인 **후** legacy 구독 제거 (290 -> 291) |
| **M2a** | 로컬 스파이크 (Track 1) | 격리 클론에서 S-1 ~ S-9 스파이크 완수 | **S-3(Retained Terminal Event) 통과** (실패 시 mosquitto로 분기) |
| **M2b** | 원격 프로덕션 전환 (Track 1R) | D-1~D-5 교정 + §9 원격 배포 + §9.5 전환 | **R-3(노출0) · R-5(retained) · R-6(신원) · R-9(계정격리) 동시 통과** |
| **M3** | 보안 종결 (Track 2) | A-2 지문 토픽 전환, G-11 무조건 토큰 발급 | 지문 토픽 동작 확인 **후** legacy 구독 제거 |
| **M4** | 동기화 완료 (Track 3) | `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` 정합 | 전체 테스트 스위트 100% Green |
---
@@ -102,7 +104,27 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실
---
## 5. Track 2: A-2 보안 결함 및 워크스페이스 격리 해소 (`A-2`, `B-16`)
## 5. Track 1R: 원격 프로덕션 전환 로드맵 (M2b 상세)
```
[P0 교정] D-1~D-5 문서 교정 + §5.2 경계 명문화 + 신규 가드 7종
▼
[P1 서버 준비] VPS/홈랩 프로비저닝, Docker, Tailscale 가입
▼
[P2 배포] nats.conf + compose 기동, healthcheck healthy 확인
▼
[P3 잠금] 바인드 주소 한정 + UFW + ss/nmap 로 노출 면적 0 단언 (R-3)
▼
[P4 전환] 드레인 → 잔여 스캔 → .mam.env 교체 (§9.5)
▼
[P5 검증] R-1 ~ R-10. R-5(retained) / R-9(계정 경계) 를 최종 관문으로
▼
[P6 상시화] 로그 로테이션, JetStream 볼륨 백업, healthcheck 알림
```
---
## 6. Track 2: A-2 보안 결함 및 워크스페이스 격리 해소 (`A-2`, `B-16`)
1. **`auth_token` 무조건 발급 (`F-3` / `G-11`)**:
`registry.register_job()`에서 브로커 설정과 무관하게 항상 `secrets.token_urlsafe(32)` 기반 토큰을 발급하여 공개 브로커 환경에서도 HMAC 검증이 무력화되지 않도록 강제합니다.
@@ -113,12 +135,12 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실
---
## 6. Track 3: 문서 및 배포 설정 동기화
## 7. Track 3: 문서 및 배포 설정 동기화
| 대상 파일 | 갱신 내용 |
|---|---|
| [`MESSAGING.md`](MESSAGING.md) | 브로커 표준을 `nats-server`로 갱신, F-1/C1 해소 기록, F-5 영속 세션 서술 정정 |
| [`IMPROVEMENTS.md`](IMPROVEMENTS.md) | A-2 완료 전환, B-14/B-15/B-16/O-5 해결 상태 갱신 |
| [`IMPROVEMENTS.md`](IMPROVEMENTS.md) | A-2 완료 전환, B-14/B-15/B-16/O-5 해결 상태 갱신, B-17/B-18 신설 등록 |
| [`VERSIONS.md`](VERSIONS.md) | `v2.0.0` 릴리스 노트에 메시징 백플레인 고도화 및 내결함성 패치 기록 |
| [`PRIVATE_SERVER.md`](PRIVATE_SERVER.md) | 스파이크 결과 반영 및 최종 가이드 확정 |
| [`deploy/install.sh`](deploy/install.sh) | `requirements.txt` 확인 (paho 유지) 및 개인 브로커 안내 추가 |
@@ -126,21 +148,6 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실
---
## 7. 의존성 그래프 및 롤백 전략
```
[M0: 문서/가드] ────────────┐
│ │ (M0 A-1 환경변수 정렬 선행)
▼ ▼
[M1: Track 0 내결함성] ──> [M2: Track 1 스파이크] ──> [M3: Track 2 보안] ──> [M4: 동기화]
```
- **롤백 전략**:
- `nats-server` 스파이크(S-3) 실패 시: 클라이언트 코드 변경 없이 `.mam.env`의 브로커 주소만 `eclipse-mosquitto`로 전환합니다 (가역성 100%).
- Track 0 내결함성 패치는 브로커 제품과 무관하게 순수 이득이므로 롤백하지 않고 영구 유지합니다.
---
## 8. 진행 추적 체크리스트
### M0: 문서 정합성 확보
@@ -154,14 +161,27 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실
- [x] Step 3: `multi-agent-mux-delegate-job` 인프라 `rc=3` 에러 분리 (`F-4` / G-9~G-10)
- [x] M1 통합 검증 (브로커 다운 상태 위임 3초 완주)
### M2: Track 1 `nats-server` 실증 (`O-5`)
### M2a: Track 1 `nats-server` 로컬 실증 (`O-5`)
- [ ] 격리 클론 생성 (`$SCRATCH/nats-spike`)
- [ ] S-1 ~ S-9 스파이크 매트릭스 검증 수행
- [ ] S-3 Retained 메시지 게이트 통과 확인
### M2b: Track 1R 원격 프로덕션 전환
- [x] D-1 `store_dir` 절대경로 교정 + 비인용 heredoc (`PRIVATE_SERVER.md:73`, `:146`)
- [x] D-2 이미지 핀 `nats:2.12-alpine` + `/healthz` healthcheck
- [x] D-3 8222/8080 바인드 주소 한정
- [x] D-4 TLS 절의 IP 예시 제거 및 DNS/SAN 요건 명시
- [x] D-5 `.mam.env.example` 정합 (`MQTT_KEEPALIVE` 추가)
- [x] N-1 §5.2 에 retained=MQTT 전용 경계 명문화 + §9.1 `mam_observer` 추가
- [ ] 신규 가드 G-D5 ~ G-D9, G-R1, G-R2 구현 및 검증 (290 -> 297)
- [ ] 서버 배포 및 R-3 노출 면적 0 단언
- [ ] §9.5 드레인·잔여 스캔 후 `.mam.env` 전환
- [ ] R-1 ~ R-10 전건 통과 (R-5 / R-9 최종 관문)
### M3: Track 2 보안 및 토픽 격리 (`A-2`, `B-16`)
- [ ] G-11 무조건 `auth_token` 발급 적용
- [ ] 워크스페이스 지문 토픽 발행 전환 및 레거시 구독 제거
### M4: Track 3 문서 및 배포 동기화
- [ ] `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` 최종 갱신