[Test] 독립 환경에서 로컬 시연 시작·검증·종료 재현

[Gimini-3]

목적

처음 접한 팀원이 개인 환경·기존 데이터 없이도 start → verify → stop을 재현할 수 있는지 실제 서비스로 검증합니다. 성공처럼 출력하기만 하는 시연을 피하기 위해 업로드·인덱싱·기대 검색·원본 해시·브라우저·종료를 각각 확인합니다. Closes #557.

테스트 환경

• GitHub hosted Ubuntu 24.04 임시 실행기, Java 17·Node 22·Python 3, PostgreSQL 17·pgvector 0.8.1, Valkey.
• 실제 BAAI/bge-m3 CPU 모델, Gradle 백엔드, Vinext 프런트엔드, Playwright 1.64.1·Chromium. Embedding CPU 상한 2.0, 메모리 상한 4 GiB.
• 예제 PDF 5·DOCX 5·HWPX 5, 고정 질문 3개. 정상 Chromium 컨텍스트 1개와 JavaScript 비활성 SSR 경계 컨텍스트 1개.
• 생성 모델을 제어 대체물로 성공시키지 않았습니다. 실제 Ollama 답변·인용, GCP OpenSQL·OpenProxy HA는 NOT_RUN입니다.
• 최초 컨테이너 0개·볼륨 0개·개인 환경 파일 0개를 확인했습니다. 미리 제공된 Docker 이미지 6개는 존재했으며, DB·모델 볼륨을 재사용한 첫 실행은 아닙니다.
• 전체 통과 회차의 소스 head dbf782c, 체크아웃된 PR 병합 미리보기 a62175ee3e4621c6411feb3af5f4ed3663802b6c. 후속 문서·컨텍스트 수 표기 변경은 최종 커밋 CI에서 다시 확인합니다.

테스트 방법

그림 1 — 실제 요청 경로

start → PostgreSQL·Valkey·BGE-M3 → Gradle 백엔드 → 프런트엔드
verify → 프런트엔드 /api/backend 프록시
           → 가입·15건 업로드 → Worker 실제 임베딩 → INDEXED
           → 질문 3개: 기대 문서 포함 → 원본 15건 SHA-256 대조
Chromium → 로그인 화면 → 질문 전송 → 근거 문서 클릭 → 원본 해시
stop → 소유 프로세스·컨테이너 종료 → 캐시 start → 이전 문서 ID 대조

1. python3 scripts/demo/reproduce_fresh.py로 독립 실행기 재현을 수행했습니다. 이 harness는 GitHub hosted 실행기에서만 허용합니다.
2. 첫 start 중 두 번째 start가 거부되는지 검사하고, 실제 listener·readiness·프록시·대상 DB를 대조했습니다.
3. verify로 INDEXED 15/15·기대 검색 3/3·원본 해시 15/15를 확인하고 같은 계정 재실행 원장과 문서 ID 15개를 비교했습니다.
4. JavaScript 비활성 화면에서는 인증 폼의 POST fallback·제출 비활성을 확인하고, 정상 Chromium에서는 실제 로그인·검색·다운로드를 수행했습니다.
5. stop 재실행, 잘못된 임베딩 주소, backend 기동 프로세스 등록 직후 SIGTERM, 캐시 재기동을 수행했습니다. 각 목적·회차 로그는 분리했습니다.

파일·구성요소	역할
.github/workflows/demo-reproducibility.yml	개인 컴퓨터와 분리된 실제 모델·브라우저 실행 환경
scripts/demo/reproduce_fresh.py	목적별 명령·시간·기대 종료 코드·정리·불변 원장 검사
scripts/demo/browser_smoke.cjs	SSR 인증 경계와 사용자 로그인·검색·원본 다운로드
scripts/demo.py	실제 Gradle 분리 JVM의 계보 등록·listener·종료 대조, IPv4 바인딩
AuthPage.tsx	클라이언트 준비 전 기본 GET 제출 방지
seed_demo_corpus.py·회귀	사전에 모르는 쿼리 비밀값도 저장 전에 제거
README·실행 기록	실측 수치·중단/진단 회차·검증 한계

관측 결과

전체 통과 실행 39105569049, 단계별 근거와 재시도 기록.

목적	실제 관측	판정
첫 start	의존성·이미지·모델 준비 포함 196.632초	코드 0
첫 verify	24.135초, 업로드·INDEXED 15/15·기대 검색 3/3·해시 15/15	통과
같은 계정 verify	3.072초, 문서 ID 15/15 재사용, 필수 단계 통과	통과
실제 Chromium	로그인·질문·다운로드 3.782초, 원본 52,683 bytes SHA-256 일치	통과
SSR 인증 경계	JavaScript 비활성 상태의 POST·제출 비활성	통과
동시 start	코드 1	기대한 거부
잘못된 임베딩 주소	코드 1, 정리 확인	기대한 준비 실패
기동 중 SIGTERM	코드 130, 정리 확인	기대한 취소
캐시 재기동·verify	start 26.061초, verify 3.626초, 기존 문서 ID·해시 유지	통과
stop·환경 보존	소유 컨테이너 3개 중지·포트 6개 해제, 환경 파일 2개 bytes·mtime 유지	통과
로컬 제어 회귀	최종 76/76, 9.168초	통과

전체 원장의 관측 항목은 24/24 PASS입니다. 독립 장애 시험을 24번 반복했다는 뜻은 아닙니다. 시간은 해당 개발 실행기의 명령 wall time이며 운영 RTO나 다른 팀 대비 성능 우위로 해석하지 않습니다.

검증 과정에서 확인된 사항

실제 프로세스와 제어 대체물의 차이

그림 2 — Gradle의 실제 자식 JVM

supervisor 전용 그룹 → Gradle launcher
                         └─ 별도 그룹의 단발성 JVM → Spring Boot·API 포트

그룹 ID만 비교 → 정상 JVM을 자신의 서버로 판정하지 못할 수 있음
보완: 살아 있는 부모 계보 → PID·시작 시각·명령 fingerprint 등록
      listener도 등록 PID와 대조 → 종료 직전 계보 재조회
      일치하는 자식만 개별 종료 → 그룹·포트 해제 확인

실제 Gradle 도움말 빌드 자체는 성공했지만 자식 그룹이 분리됐습니다. 제어 HTTP 검사만으로는 잡히지 않았던 가정을 보완했습니다. 분리 자식 종료 직후 부모도 자연 종료하는 경합은 회귀에서 추가 보완했고, 불통과 회차도 별도 로그로 보존했습니다.

실제 브라우저에서 발견한 인증 폼 경계

그림 3 — 로그인 SSR와 클라이언트 준비

기존: SSR 폼 표시·제출 버튼 활성 → React 이벤트 연결 전 클릭
        → 브라우저 기본 GET 제출 → login URL에 입력 필드 추가
        → 정상 로그인 API 흐름이 아니어서 search 이동 확인 불가

보완: SSR method=post + 제출 비활성
        → 클라이언트 이벤트 연결 뒤 활성화
        → onSubmit preventDefault → 로그인 API → 세션 → 검색 화면
검증: 실제 SSR HTML·무스크립트 Chromium 경계 + 정상 브라우저 E2E

• 이전 실제 API 단계는 통과했지만 Chromium 로그인은 시간 초과였습니다. 진단 회차에서 기본 GET 이동을 확인한 뒤 AuthPage를 보완했습니다. 브라우저 인증정보 입력을 생략하거나 토큰을 직접 주입해 통과시키지 않았습니다.
• 기존 수집 파일에서 원문 비밀번호 쿼리가 남은 파일은 0개였고, 진단 비밀번호는 저장 전에 제거됐습니다. 추가로 password/token/email 쿼리 일반 마스킹을 적용했습니다. 실패 화면은 입력 필드를 마스킹합니다.
• job 수준 runner 컨텍스트 위치 오류는 step env로 수정했습니다. 첫 두 실제 회차의 수동 중단, 첫 구성요소 로그 일부 미수집, 후속 진행 로그 보강을 문서에 명시했습니다. 중단 회차를 성공으로 세지 않습니다.
• 프런트엔드 localhost 기본값과 IPv4 검증 주소를 맞췄습니다. 원래 실제 소켓 주소를 수집하지 않았으므로 IPv6만이 유일한 원인이었다고 단정하지 않습니다.
• npm ci의 기존 감사 경고 30건(low 1·moderate 6·high 23)은 기록합니다. 프런트엔드 의존성 파일을 수정하지 않았으며 경고 해소는 검증 범위 밖입니다.
• 이 작업은 원래 개인 환경 파일에 쓰지 않았습니다. 중간 점검에서는 2개 해시가 같았으나, 최종 점검에서는 원래 .env에 15:30:29의 별도 변경이 감지됐습니다(변경 주체 미확인). 이를 원복하지 않고 현재 내용을 보존했습니다. frontend/.env.local의 해시와 미추적 작업 28개는 유지됐습니다. 공개 서비스·개인 Docker·GCP 설정은 변경하지 않았습니다.

게시된 최종 커밋 검사

86aaf7c3a972bc78725561f761b4e4fb86786e0c의 CI와 독립 환경 재검증이 모두 통과했습니다. 재검증도 24/24 PASS이며 최초 기동 207.745초·첫 verify 31.581초·캐시 기동 28.571초였습니다. 이 회차 원장은 해당 workflow artifact에 별도로 보존했습니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: DocGrid/docgrid/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7dfc6e56-6567-4da2-baff-969afed63938

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Gimini-3]

최종 구현자 수동 검토

대상 커밋: 86aaf7c3a972bc78725561f761b4e4fb86786e0c. 전체 diff와 목적별 원장, 마스킹된 Chromium 화면을 대조했습니다. 별도 팀원 승인으로 표현하지 않습니다. CodeRabbit의 SUCCESS는 이 저장소의 자동 리뷰 생략 표시입니다.

• 실제 모델 회차 39105569049에서 API·브라우저·종료·중단 정리·캐시 재기동의 24개 관측 항목이 모두 PASS였습니다. 필수 기능 15/15·3/3·15/15와 문서 ID 재사용, 브라우저 원본 해시를 원장 값으로 재확인했습니다.
• 브라우저 로그인은 토큰 주입 없이 입력·제출을 사용했습니다. SSR 단계의 기본 GET 제출을 막는 POST fallback과 클라이언트 준비 전 disabled 상태도 실제 무스크립트 화면에서 확인했습니다.
• Gradle의 분리 JVM을 실제 부모 계보에서 등록하고, 현재 PID·시작 시각·명령 fingerprint가 같은 자식만 종료합니다. 포트 점유 프로세스를 임의 종료하거나 Native Ollama를 중지하는 경로는 없습니다.
• Docker endpoint·Engine ID·컨테이너 ID·Compose 작업공간을 대조하며 이번 실행이 시작한 자원만 stop합니다. down -v나 데이터 삭제는 없습니다.
• 로그·원장은 공유 전 재검사했습니다. 텍스트 100여 파일에서 개인 경로·JWT·원문 비밀번호 쿼리 패턴이 없었고, 브라우저 입력 영역 마스킹도 확인했습니다.
• 이전 준비 오류·중단·브라우저 불통과·로컬 회귀 불통과는 최종 통과와 분리해 보존했습니다. 생성 답변·인용, 실제 OpenSQL·OpenProxy HA, macOS 전체 E2E는 검증했다고 주장하지 않습니다.
• 실제 전체 통과 뒤의 변경은 문서·브라우저 컨텍스트 수 표기입니다. 게시된 최종 커밋의 backend/frontend/demo-scripts와 독립 환경 workflow가 모두 통과한 뒤 병합합니다.

현재 확인 범위에서 병합을 막을 변경 문제는 없습니다. 기존 의존성 감사 경고는 별도 한계로 남기며, 이 PR에서 해결된 것으로 표시하지 않습니다.