전원 On부터 정상 종료까지

이 서버에 이미 설치된 도구와 모델을 사용합니다. 같은 장비의 현장 운영을 위해 인터넷 다운로드나 설치 USB가 필수인 상태는 아닙니다.

현장에서 먼저 할 일

1. 전원과 데이터 디스크를 연결하고 si 계정으로 로그인합니다.
2. AI와 Web의 현장 IP가 달라졌다면 카메라 Start 전에 3~5쪽을 진행합니다.
3. 주소가 그대로라면 상태 확인 후 필요한 경우에만 서비스를 시작합니다.

ct status
ct start
ct auth status

안전하게 서버를 끄는 순서

ct stop
ct-llm stop
ct observe stop
ct status
sudo systemctl poweroff

각 명령이 끝난 뒤 다음 명령을 실행합니다. LLM·관측을 켜지 않았다면 해당 Stop은 생략해도 됩니다. 정상 정지에 실패하면 전원을 바로 뽑지 말고 9쪽을 확인합니다.

이번 종료 교차 확인

사용자가 서버 종료를 알린 뒤 외부 SSH를 1회 확인했고, 6초 연결 timeout이 발생했습니다. 종료 보고와 일치하는 원격 접속 불가 상태입니다. 이 확인에서 재기동이나 서비스 조작은 하지 않았습니다.

어디를 열고, 어디에 저장되나

평상시 탐색은 /workspace/contextra 아래에서 합니다. 데이터는 별도 디스크의 실제 저장소를 bind mount로 보여 줍니다.

TB·GB는 10진입니다. Event와 학습은 독립 상한이며, filesystem 최소 여유 100GB를 보호합니다. 작성·전송 중 자료는 보호하고 각 기능 소유의 정리 가능한 완료 자료만 삭제합니다.

VSCode에서 폴더가 안 보이거나 쓰기가 안 될 때

ct access

sudo 비밀번호를 입력하고 완료되면 VSCode 탐색기를 새로고침합니다. 필요하면 창을 다시 엽니다. 이 명령은 소유자·내용을 바꾸지 않고 si ACL을 재적용합니다. 카메라·컨테이너는 재시작하지 않습니다.

검색은 소스 폴더에서만

/workspace/contextra/setup/contextra.code-workspace 또는 편집 소스 폴더를 엽니다. 전체 / 또는 대용량 data를 검색 대상으로 열면 모델·영상 검색이 CPU를 많이 사용할 수 있습니다.

재부팅 후와 임시 GUI

CLI 부팅, 디스크 mount, 서비스 기동 순서와 ACL은 지속 설정입니다. LLM·GUI·관측은 기본 Off입니다. 물리 콘솔의 si 세션에서만 ct-gui를 실행하고, 종료는 GUI 로그아웃을 사용합니다. 실제 GUI 화면은 현장 확인 대상입니다.

현장 값부터 적으세요

오늘의 외부 IP·NAT 포트를 내일의 내부망 주소로 사용하지 않습니다. Web 담당자와 아래 실제 값을 맞춘 뒤 진행합니다.

1. 정상 정지 후 실제 OS 주소 확인

ct stop
ip -4 -br addr
ip route
timedatectl status
findmnt /backup
findmnt /training

NIC IP 변경은 물리 콘솔에서 기존 netplan/networkd 설정에 맞춰 진행합니다. ct는 OS IP를 변경하지 않습니다. 주소·prefix·Gateway는 담당자가 확정한 값만 사용합니다. 원격 SSH에서 무작정 IP를 바꾸지 않습니다.

2. 공개 CA를 준비

Web에서 공개 CA 인증서 1개를 받아 아래 경로에 둡니다. private CA key는 받지 않습니다. 서버 날짜·시간도 인증서 유효기간 판단에 영향을 줍니다.

ct connection check-ca /workspace/contextra/setup/inbox/manager-ca.crt
sha256sum /workspace/contextra/setup/inbox/manager-ca.crt

check-ca의 인증서 fingerprint는 별도 전달받은 값과 대조합니다. sha256sum의 파일 SHA256은 다음 prepare에 씁니다. 두 값은 서로 다른 값입니다.

계획 → 준비 → 발급 → 적용

아래 한글 자리표시는 현장 실제 값으로 바꿉니다. 단계가 출력한 plan.json 경로와 stage 경로를 기록해 다음 명령에 그대로 사용합니다.

1. 변경 계획 만들기

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

Manager와 Event의 포트가 같다고 가정하지 않습니다. Event가 기존 승인된 HTTP 계약이면 실제 HTTP URL을 사용합니다. plan은 실행 설정·방화벽·인증을 아직 바꾸지 않습니다.

2. 새 CA와 연결 자료 준비

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

기존 인증 정보를 보존한 private stage를 만들고 새 IP용 CSR을 준비합니다. 공개 CSR은 setup/outbox에 있습니다.

3. 계정·CA·주소 확인 후 발급 요청 1회

ct connection enroll 출력된stage경로

Web PC가 켜져 있어야 합니다. 실패·timeout이면 같은 요청을 반복하지 말고 오류와 Web 처리 상태를 확인합니다. 성공 확인 전 apply하지 않습니다.

4. 확인된 stage 적용 후 기동

ct connection apply 출력된stage경로 --yes
ct start
ct auth status

카메라 설정·DB·모델·기존 image를 유지합니다. 전용 Redis 접근 규칙만 갱신하며 SSH 포트·OS 라우팅은 바꾸지 않습니다. 실제 WSS·Redis·브라우저 표시는 현장에서 확인합니다.

계정 변경·재연결·오류 구분

주소와 CA가 이미 맞는 활성 연결에서 사용하는 절차입니다. 로그인 성공과 Web의 실제 WSS 연결은 서로 다른 확인 항목입니다.

AI 연결용 ID·비밀번호가 바뀐 경우

1. Web PC와 API가 켜져 있고 현장 주소·CA가 맞는지 확인합니다.
2. Web에서 카메라를 모두 Stop합니다. Contextra 서비스는 실행 상태로 둡니다.
3. 다음 명령에서 ID와 비밀번호를 입력하고 LOGIN을 입력해 1회 요청합니다.

ct auth status
ct auth update
ct auth status

비밀번호 입력은 화면에 보이지 않습니다. 비밀번호를 명령줄·공유 문서·LLM 질문에 넣지 않습니다. actorType=AI 및 기존 serverId가 맞는 정상 세션만 적용합니다.

진행 중 작업을 다루는 명령

상태 확인: ct logs ai-control-sidecar, ct logs ai-gateway. 로그를 외부에 전달하기 전에 비밀번호/token 포함 여부를 검토합니다.

인터넷 없이 한글 질답·코드 분석

LLM과 Contextra는 같은 GPU를 번갈아 사용합니다. LLM 실행 전에 Contextra를 정상 정지합니다. 새 다운로드나 외부 API는 사용하지 않습니다.

터미널에서 바로 질문

ct stop
ct-llm status
ct-llm chat

si 계정으로 실행하며 LLM에는 sudo가 필요 없습니다. 한국어로 질문합니다. 코드 파일을 직접 읽는 작업은 아래 ct-agent를 사용하거나 비밀정보를 제거한 코드 일부를 질문에 넣습니다.

코드 파일을 읽고 수정 제안을 받을 때

터미널 A: API를 실행한 채 둡니다.

ct-llm serve

터미널 B: 승인된 소스 폴더에서 작업 기록을 시작하고 agent를 엽니다.

cd /workspace/contextra/source/crowd-0f172d94
ct work begin /workspace/contextra/source/crowd-0f172d94
ct-agent

모델은 로컬 icerti-qwen입니다. 내부 API는 127.0.0.1:18080, 기본 동시 처리 1개입니다. 두 사람이 함께 질문하면 기다릴 수 있습니다. 관리 명령·삭제·운영 변경은 개별 확인 후 진행합니다.

끝낸 뒤 Contextra로 돌아오기

ct-llm stop
ct-llm status
ct start

LLM 정상 종료와 GPU 반환을 확인합니다. 실행 중인 다른 GPU 작업을 임의로 종료하지 않습니다. GPU 경로가 실패하면 Contextra가 정지한 상태에서 ct-llm cpu를 사용할 수 있으나 훨씬 느릴 수 있습니다.

일반 질답은 ct-llm chat, 파일 읽기·수정은 ct-agent입니다. 작업 기록은 자동으로 모든 터미널 명령을 녹화하지 않습니다.

소스 수정 → 기록 → APP image 적용

편집 폴더를 Runtime에 직접 bind하지 않습니다. ct apply가 현재 image 위에 Python 변경을 담은 작은 오프라인 APP image를 만듭니다.

1. 기록을 시작하고 수정

ct stop
ct work begin /workspace/contextra/source/crowd-0f172d94
ct work note '문제 증상과 수정 목적'

VSCode 또는 ct edit /workspace/contextra/source/crowd-0f172d94/app/수정파일.py로 수정합니다. 이미 work begin을 했다면 중복 실행하지 않습니다. 같은 파일을 여러 사람이 동시에 고치지 않습니다.

2. 변경과 검증을 기록하고 닫기

ct work note '변경 파일, 실행한 검사, 성공 또는 오류 결과'
ct work end

출력된 기록 폴더의 changes.diff, SUMMARY.ko.md를 확인합니다. 요약에는 문제·수정 이유·실제 검증·미확인을 적습니다. 수정되지 않은 기능까지 성공으로 쓰지 않습니다.

3. 적용하고 최소 확인

ct-llm stop
ct apply /workspace/contextra/source/crowd-0f172d94
ct start
ct status
ct auth status

ct apply가 표시한 소스·현재 지문을 확인하고 APPLY를 입력합니다. 성공 후에만 ct start를 실행합니다. 모델·SDK·native 코드·의존성을 변경하는 작업은 이 Python APP 경로의 범위가 아닙니다.

4. 작업 기록 반출

ct work export 출력된기록폴더이름 --reviewed

~/.local/state/contextra-work/ 아래 출력된 .tar.gz와 SHA256을 가져옵니다. 명령 실행 내역과 후속 Start 확인 결과는 SUMMARY에 보완한 뒤 export합니다. 별도 OpenCode 대화는 검토 후 필요할 때만 첨부합니다.

필요하면 9쪽 진단 결과와 작업 기록을 함께 남깁니다. 전체 서버 복원용 USB와 작은 작업 기록 반출은 다른 용도입니다.

새 내부 IP로 SSH와 LLM 연결

Windows에서 AI 서버의 모델만 사용할 수도 있고, Remote-SSH로 Linux 소스를 편집할 수도 있습니다. 어느 컴퓨터의 파일을 고치는지 구분합니다.

PowerShell에서 AI 서버로 접속

ssh -V
ssh -p 실제SSH포트 si@실제AI주소

내부 SSH port는 기존 외부 NAT port와 다를 수 있습니다. host key fingerprint를 AI 담당자와 대조합니다. 경고가 나면 known_hosts를 무작정 지우거나 검사 비활성 옵션을 사용하지 않습니다.

브라우저로 LLM 사용

1. AI 서버 담당자가 ct stop 뒤 ct-llm serve를 실행합니다.
2. Windows의 별도 PowerShell에서 아래 터널을 실행하고 창을 유지합니다.

PowerShell 명령입니다. 첫째·둘째 줄 끝의 backtick (`)은 다음 줄로 이어 쓰는 표시입니다.

ssh -N -T -p 실제SSH포트 `
  -L 127.0.0.1:18081:127.0.0.1:18080 `
  -o ExitOnForwardFailure=yes si@실제AI주소

브라우저: http://127.0.0.1:18081
API: http://127.0.0.1:18081/v1, 모델 alias: icerti-qwen.
API key는 별도 안전한 전달 경로를 사용합니다. 터널을 닫으면 접속만 종료되며 서버 LLM은 자동 종료되지 않습니다.

코드를 수정할 때 선택

Remote-SSH 터미널은 Linux입니다. Windows용 명령을 그 안에서 실행하지 않습니다. AI 서버 전체 / 또는 data 대신 소스 폴더만 작업 범위로 엽니다.

추가 설치 없이 AI 물리 콘솔·SSH CLI로 LLM 질답은 가능합니다. 보조 GUI는 AI 물리 콘솔에서 ct-gui를 사용합니다.

문제가 생기면 이 순서로

짧은 상태와 최근 로그부터 확인합니다. 운영 DB·인증·모델·기존 자료를 삭제해 문제를 우회하지 않습니다.

필요할 때만 관측 도구 켜기

ct observe start
ct observe status

수집 간격 15초, 보관 7일 또는 retained blocks 10GiB 중 먼저 도달하는 조건입니다. WAL 등은 추가 공간을 사용합니다. analytics 컨테이너를 재생성했다면 observe stop/start로 target 주소를 갱신합니다.

Windows에서 Grafana 터널을 연 뒤 http://127.0.0.1:33000으로 접속합니다.

ssh -N -T -p 실제SSH포트 -L 127.0.0.1:33000:127.0.0.1:33000 si@실제AI주소

Grafana admin 비밀번호는 root 전용 설정에서 별도 확인합니다. PDF에는 넣지 않았습니다. 외부망 전체에 관측 포트를 공개하지 않습니다. 사용 후 ct observe stop.

root 여유 15GiB 보호를 유지합니다. cleanup/prune, 모델 재변환, SDK 설치, 방화벽 전체 해제는 이 안내의 복구 절차가 아닙니다.

현장 확인 및 기록

이 문서는 2026년 9월 28일 설치·검증 기록과 실제 도구 소스를 바탕으로 만든 인쇄용 snapshot입니다. 현장 값과 실제 실행 결과를 아래에 적습니다.

현장 확인표

출발 전 확인된 것 / 현장에서 확인할 것

기존 확인: 정상 Stop/reap, 컨테이너 5개·모델 4개, offline APP image 적용, LLM 한국어 CLI, 관측 target, si 읽기·쓰기 ACL, mount·기동 unit 정합성.

현장 확인: 실제 전원 재기동, 변경된 IP·CA·AI 계정 수용, Web WSS·화면, Windows PC 연결, GUI 화면. 새 IP와 계정 동시 변경의 도구 경계는 4쪽을 먼저 확인합니다.

데이터와 USB

기존 Event·학습 미디어와 해당 관리 기록은 요청에 따라 초기화했습니다. 카메라·모델·설정·인증은 보존했습니다. 삭제한 미디어의 백업은 없습니다. 같은 AI 장비에서 기존 설치를 사용하는 데 설치 USB는 필수가 아닙니다. PDF는 휴대폰/태블릿에, 작업 기록은 작업 후 별도 매체에 보관하면 됩니다.

서버에 있는 원본 안내

/workspace/contextra/setup/guides/OFFLINE_OPERATIONS.ko.md
/workspace/contextra/setup/guides/NETWORK_TRANSITION.ko.md
/workspace/contextra/setup/guides/WINDOWS_PREP.ko.md

문서 근거: tools/icerti_offline의 위 가이드, maintenance/ct.py·connection.py·network_prepare.py·auth_control.py·work_record.py, ct_llm.py 및 배포 운영·검증 기록. source 기준 Git bbfbd13. Markdown 원본을 대체하지 않습니다.

현장 메모

날짜 / 담당: ___________________________________________________
발생 시각 / 증상: ________________________________________________
처리 / 확인 결과: ________________________________________________
남은 항목 / 반출 기록: ____________________________________________