teraWeb/backend/STARTUP_TIMING.md

# 부팅 초기화 시간 확인

## 로그인 준비 상태

`GET /api/v1/auth/startup`은 인증 없이 준비 단계와 경과 시간을 제공합니다. 로그인 화면의 `/login/backend-status`는 이 상태가 `ready`인 경우에만 로그인 정책을 조회하고 로그인을 허용합니다. API의 로그인·CAPTCHA POST도 초기화 중에는 503으로 차단합니다.

설정 복원, 인증서, SNMP, 접속 설정, 시리얼 설정, 활성화된 포트 서비스 설정이 성공해야 합니다. 마지막으로 48개 시리얼 채널의 가용성과 운영 환경의 세션 서비스 정상 응답을 확인합니다. 부팅 알람 전송은 필수 성공 조건이 아닙니다.

게이지는 완료 단계 수/전체 단계 수이며 예상 남은 시간 비율이 아닙니다. 표시되는 경과 시간은 API 프로세스 시작 기준입니다. API가 응답하기 전에는 단계와 시간을 알 수 없어 대기 표시를 사용합니다. 준비 완료 후 시간은 고정됩니다.

필수 단계가 오류를 반환하면 3초 간격으로 실제 재시도합니다. 25초 이상 완료되지 않은 단계는 `delayed`로 표시하며 로그인은 차단됩니다. 응답하지 않는 호출과 새 시도를 중첩하지 않고, 해당 호출이 반환된 뒤에만 다음 시도를 진행합니다. 재시도가 성공하면 자동으로 다음 단계로 진행합니다. API 로그에는 상세 오류가 기록되지만 인증 전 화면에는 단계 이름만 표시합니다. 이 준비 확인은 전체 시리얼 송수신 시험이나 이후 발생하는 WCH 커널 장애의 방지를 의미하지 않습니다.

프론트엔드와 API를 함께 배포해야 합니다. 이전 API에 새 프론트엔드만 연결하면 명시적 준비 상태를 확인할 수 없어 로그인이 차단됩니다.

API는 시작 시 표준 오류 로그에 `tera-api startup stage=... elapsed_ms=...`를 출력합니다.

| 단계 | 측정 대상 |
| --- | --- |
| `config.load`, `config.persist` | 설정 읽기와 저장 |
| `auth.load`, `auth.bootstrap`, `auth.persist` | 계정 복원, 기본 계정 생성, 저장 |
| `sessions.*`, `login_failures.*`, `operations.*` | 세션, 로그인 실패, 작업 기록 복원과 저장 |
| `logs.retention`, `logs.journal.load` | 로그 보존 정책 적용, 기존 로그 읽기 |
| `store.total` | 저장소 초기화 전체 시간 (위 단계 포함) |
| `runtime.tls`, `runtime.snmp`, `runtime.port_services`, `runtime.management`, `runtime.serial`, `runtime.cold_start_alarm` | 각 서비스 초기 동기화 |

`runtime synchronization completed elapsed_ms=...`는 API 프로세스 시작부터 병렬 동기화 작업 종료까지의 시간입니다. OS 부팅 전체 시간이나 브라우저 렌더링 시간은 아닙니다. 각 runtime 단계는 병렬 실행되므로 시간을 합산하지 않습니다. 단계 종료는 성공을 보장하지 않으며, 기존 `degraded` 및 `error` 로그도 함께 확인합니다.

systemd 환경에서는 `journalctl -b -u tera-api.service`로 확인합니다. Buildroot의 `start-stop-daemon -b` 실행 경로에서는 표준 오류가 버려질 수 있으므로, 실제 장비의 서비스 실행 설정에서 표준 오류 수집을 먼저 구성해야 합니다. UI의 시스템 로그 목록에 자동 저장되는 항목은 아닙니다.

변경 후 실제 전원 부팅에서 로그를 수집하고, 동일한 설정·로그량으로 변경 전후의 첫 UI 요청 시간을 비교합니다. `auth.bootstrap`은 저장된 계정 목록이 있는 재시작에서는 나타나지 않아야 합니다. 공장 초기 상태에서는 나타날 수 있습니다.

이번 개선은 저장된 계정이 있을 때 불필요한 기본 계정 비밀번호 해시 생성을 생략하고, 계정·세션·로그인 실패 기록의 중복 저장을 제거합니다. 설정 마이그레이션, 로그 복원, 서비스 준비 상태 검사는 유지합니다. 실제 장비의 지연 원인과 개선 시간은 부팅 측정 후 판단합니다.

CAPTCHA는 준비 중에도 안내 영역을 표시합니다. 실제 이미지 발급은 준비 완료 및 활성화 정책 확인 후 수행하므로 초기화 대기 중 이미지가 만료되지 않습니다.

## 로그인 전 PC 시간 복원

장비 시각이 2000년 이전인 경우 로그인 준비 응답에 프로세스별 임의 토큰을 제공합니다. 로그인 페이지는 이 토큰과 현재 브라우저 UTC 시간을 `/login/bootstrap-time`으로 전송합니다. 프론트엔드는 JSON/전용 헤더와 Origin을 검사하고, API는 토큰·장비 시각·입력 범위를 검사합니다. 시간 변경은 기존 tera-timed 경계를 사용하며 설정된 시간대를 유지합니다.

성공 후 같은 API 프로세스에서는 다시 적용하지 않습니다. 장비 시간이 이미 정상 범위라면 이 비로그인 경로로 변경할 수 없습니다. 실패 요청은 3초 간격으로 제한하며 정상 시간을 변경하려면 기존 관리자 시간 설정 기능을 사용해야 합니다. 최초 복원 시 접속 PC의 시각을 신뢰하므로 PC 시간을 정확하게 유지해야 합니다. 이 기능은 NTP 또는 RTC를 설정하거나 하드웨어 시간을 영구 저장하는 기능이 아닙니다.

시간 복원 후에도 필수 설정 준비 확인이 끝나야 CAPTCHA 발급과 로그인이 허용됩니다. 케이블 연결만으로는 복원되지 않으며 브라우저로 로그인 페이지를 열어야 합니다.


## 전체 설정 준비 판정 (2026-09-09)

로그인은 다음 단계가 모두 성공한 뒤 허용한다. 시간 초과나 재시도 중인 단계는 완료로 계산하지 않는다.

- 저장소: 계정·권한·접근 제한 및 모든 running 설정 복원/검증.
- 시간: tera-timed가 시간대와 NTP 사용 여부/서버를 적용하고 NTP 프로세스 상태를 확인. 2000년 이전이면 로그인 화면의 기존 PC 시간 동기화 또는 NTP를 기다림. 이미 유효한 시각은 재설정하지 않음.
- 네트워크: tera-netd의 저장 설정과 실제 인터페이스/정적 IPv4 주소 비교. 불일치하면 running 설정 적용, 실제 주소 확인 후 트랜잭션 확정. pending 설정은 적용하지 않음.
- TLS·SNMP·관리 접속·포트 서비스: 각 담당 서비스의 설정 적용 성공 응답.
- 알림/인증 정책: 실행 중인 정책 검증, 활성 SMTP·SNMP trap·RADIUS/TACACS 자격 증명 참조 확인, 알림 데몬의 읽기 전용 health 응답. 검증을 위한 알림 전송이나 외부 로그인은 하지 않음.
- 로그: 저장된 로그 보존 정책 적용 응답.
- 시리얼: 48개 회선 설정 및 포트별 캡처/패키징/로깅 설정 적용. 마지막 서비스 검사에서 모든 채널의 available/profile_applied 확인.
- 초기 상태: 위 설정 적용이 끝난 뒤 새로 수집한 48개 CR 관측을 기다림. pending/confirming/error는 완료가 아님. no_response는 관측 완료로 인정하며 모든 포트에 연결 장비가 있을 것을 요구하지 않음.
- 마지막 서비스 검사: 시리얼과 세션 서비스 확인.

NTP 서버 응답, 외부 SMTP 수신, 외부 인증 서버 로그인 성공은 설정 적용과 별개의 외부 가용성이다. 인터넷이 없는 환경에서도 PC 시각으로 부팅할 수 있다. 네트워크의 DHCP 임대 획득 및 외부 DDNS 갱신 성공까지 보장하는 검사는 아니다.

배포 스크립트: `scripts/deploy-full-readiness.ps1`. API/web/timed/clone alarmd 네 파일을 SHA256 검증 후 교체하고, 120회 준비 상태 확인에서 성공하지 않으면 네 파일을 함께 복구한다. 하드웨어 커널/드라이버 코드는 변경하지 않는다.