# 현장 IP와 CA 연결 절차

## 작업 전에 준비할 값

- AI 내부 IPv4와 SSH port. SSH host key fingerprint는 주소 변경과 별개로 안전하게 대조합니다.
- Web 내부 IPv4, Manager의 HTTPS origin, Event API의 전체 URL. 두 API의 port가 같다고 가정하지 않습니다.
- AI control/WSS port, Redis port, 미디어 접근을 허용할 내부망 CIDR.
- Web 담당자가 전달한 공개 CA 파일과 별도 전달한 fingerprint. private CA key는 받지 않습니다.

현재 설정을 지우고 새로 등록하는 작업이 아닙니다. 카메라 URI/ROI/threshold, server ID, DB, 원장,
Redis 비밀번호, control/relay token, TLS private key와 원본 자료를 보존합니다.
`connectionConfigVersion`도 프로토콜 값으로 보존합니다.

## 1. 서비스 정지와 OS 주소

`ct stop`으로 정상 회수합니다. 물리 콘솔에서 기존 networkd/netplan 설정으로 실제 주소와 경로를 먼저 정합니다.
`ip -4 -br addr`로 확인하며 새 NetworkManager나 원격 desktop을 설치하지 않습니다.
SSH로 IP를 바꾸면 연결이 끊길 수 있으므로 물리 콘솔에서 수행합니다. ct는 OS NIC 주소를 자동 변경하지 않습니다.

## 2. 계획과 공개 CA 확인

```bash
ct connection check-ca /workspace/contextra/setup/inbox/manager-ca.crt
sha256sum /workspace/contextra/setup/inbox/manager-ca.crt
ct connection plan --ai-ip 실제AI주소 --web-ip 실제WEB주소 \
  --manager https://실제WEB주소:관리HTTPS포트 \
  --event-url https://실제WEB주소:이벤트HTTPS포트/api/v1/events \
  --control-port 38443 --redis-port 16379 --lan-cidr 실제허용망CIDR
```

Event API가 기존 승인된 HTTP 계약이면 실제 HTTP URL을 사용합니다. 새 주소로 인증 scheme을 임의 변경하지 않습니다.
`check-ca`의 certificate fingerprint와 `sha256sum`의 파일 hash는 다른 값입니다. 먼저 공개 CA의 fingerprint를
Web 담당자의 별도 전달값과 대조한 뒤 파일 hash를 다음 명령에 사용합니다.

## 3. 새 연결 자료 준비

```bash
ct connection prepare 출력된plan.json경로 \
  --ca /workspace/contextra/setup/inbox/manager-ca.crt --ca-sha256 확인한파일SHA256
```

새 private staging에 기존 내부 인증 정보를 보존하고, 새 AI IP/Redis 접속 정보와 새 CA를 반영합니다.
기존 TLS private key로 새 IP SAN용 CSR을 만들며 공개 CSR만 setup/outbox에 둡니다.
이 단계에서는 활성 Compose, firewall, 서비스, 기존 인증 세션을 바꾸지 않습니다.

## 4. 명시적 로그인과 인증서 발급

```bash
ct connection enroll 출력된stage경로
```

새 Manager에 로그인과 CSR 요청을 명시적으로 수행합니다. 새 session은 기존 session과 별도 경로에 저장합니다.
CA 일치, key/leaf 일치, 새 IP SAN을 검증합니다. timeout 등 결과가 불명확하면 같은 요청을 반복하지 말고
stage의 `enroll-intent.json`과 Web의 처리 상태를 확인합니다. 이 파일이나 token을 외부 문서에 붙이지 않습니다.

## 5. 승인 후 적용

```bash
ct connection apply 출력된stage경로 --yes
ct start
```

apply는 현재 active/설정 지문과 서비스 정지를 확인한 뒤 새 descendant transaction을 만듭니다.
기존 named volume/image를 유지하고 새 주소/인증 자료/미디어 CIDR/Redis 공개 binding을 적용합니다.
전용 `CTX-ICERTI-REDIS` 접근 규칙만 변경합니다. 다른 firewall rule, SSH port, OS 라우팅은 바꾸지 않습니다.
중간 오류가 나면 자동 rollback/Start하지 않으며, 불완전 transaction은 기동 guard가 차단합니다.

실제 새 주소의 Manager TLS, 로그인, WSS, Redis 수용과 브라우저 표시는 현장에서 확인해야 합니다.
오늘의 도구 검증을 내일의 새 IP/CA 실연동 성공이라고 간주하지 않습니다.

## 오류가 나면

- `ct status`: 서비스와 디스크/GPU 상태.
- `ct logs ai-control-sidecar`, `ct logs ai-gateway`: 최근 로그만 확인.
- 입력이 틀리면 서비스가 stopped인 상태에서 새 계획을 만듭니다. DB/인증을 지우지 않습니다.
- 적용 중 실패하면 `state/inflight.json`, 해당 transaction의 previous 파일과 실제 적용 상태를 확인합니다.
  과거 private 설정을 일괄 덮어쓰거나 이전 로그인 요청을 자동 재전송하지 않습니다.