SeatOn 관리자 가이드

SeatOn v1.4.1 기준. 화면을 쓰는 사람을 위한 조작법은 사용자 가이드에 있으며, 이 문서는 그 화면을 띄워 놓고 지키는 사람을 위한 것입니다. API 세부는 API_AND_MCP.md, 내부 구조는 ARCHITECTURE.md를 봅니다.

1. 구성 요소

컨테이너는 read_only 루트, cap_drop: ALL, no-new-privileges, UID 10001로 돌며 /tmp만 tmpfs로 씁니다. 이미지 크기는 약 186MB이고 PDF 도면 변환용 poppler-utils가 들어 있습니다.

2. 설치

릴리즈 자산 SeatOn-v1.4.1.tar.gz(GitHub Release 첨부)와 이 저장소의 compose.yaml 하나면 됩니다. PostgreSQL은 외부 또는 사내 것을 준비합니다(빈 데이터베이스와 소유 계정만 있으면 스키마는 SeatOn이 만듭니다).

2.1 처음부터 끝까지

# 1. 이미지 적재 — seaton:v1.4.1 태그가 생긴다
docker load < SeatOn-v1.4.1.tar.gz

# 2. 필수 환경변수 3개 + Compose 이미지 태그
export POSTGRES_DSN='postgres://seaton:change-db-password@postgres.intra:5432/seaton?sslmode=require'
export BOOTSTRAP_ADMIN='admin'
export BOOTSTRAP_ADMIN_PASSWORD='change-this-strong-password'   # 12자 이상
export SEATON_IMAGE_TAG='v1.4.1'

# 3. 기동
docker compose up -d

# 4. 준비 확인 — {"status":"ready"} 가 나올 때까지
curl -s http://127.0.0.1:8080/readyz
curl -s http://127.0.0.1:8080/api/v1/version

SEATON_IMAGE_TAG는 Compose가 이미지를 고르는 셸 치환값이며 컨테이너 안으로 전달되지 않습니다.

2.2 최초 관리자 계정

BOOTSTRAP_ADMIN / BOOTSTRAP_ADMIN_PASSWORD로 시스템 관리자 계정이 첫 기동 때 만들어집니다. 같은 이름의 계정이 이미 있으면 환경변수 비밀번호로 덮어쓰지 않으므로, 화면에서 비밀번호를 바꾸거나 SSO로 전환한 뒤에도 안전합니다. 이 계정은 삭제할 수 없는 비상 복구용(break glass) 계정으로 두고, 평소 운영은 SSO 계정으로 합니다.

http://호스트:8080에 접속해 로그인합니다. 로그인 카드 아래에 빌드 버전이 보이면 UI가 정상적으로 내장된 것입니다.

로그인 뒤 시스템 설정 → 보안 · 키 탭의 내 로컬 관리자 비밀번호에서 부트스트랩 비밀번호를 바로 바꿉니다. 그다음은 도면 · 좌석에서 사업장·층·도면을 등록하는 순서이며, 이 부분은 사용자 가이드의 “새 층 도면을 올려서 게시하기”를 따릅니다.

3. 설정

3.1 환경 변수

애플리케이션이 읽는 환경 변수는 세 개뿐입니다(internal/platform/config.go). 나머지는 모두 DB의 설정 테이블에 있고 시스템 설정 화면에서 바꿉니다.

Compose 전용(컨테이너에 전달되지 않음):

셋 중 하나라도 비면 기동 로그에 configuration error ... missing required environment variables: ...가 찍히고 종료합니다.

3.2 시스템 설정 화면

주소 /admin/settings. 시스템 관리자만. 상단 칩이 현재 상태(Keycloak 비활성, 인사 동기화 비활성, 오프라인 CV 엔진)를 요약하고, 오른쪽 위에 저장 여부(모든 변경 저장됨 / 저장하지 않은 변경)가 표시됩니다. 비밀값은 저장 후 ********로만 보이고, 빈 값이나 ********로 다시 저장하면 기존 값을 유지합니다. 모든 저장은 감사 로그(settings.update)에 바뀐 키 이름과 함께 남습니다.

설정 키 전수(internal/database/migrations.sql 기본값). 화면 탭과 항목 이름을 함께 적었습니다.

일반

Keycloak SSO

보안 · 키

AI 분석

인사 연동

3.3 Keycloak 연결

1. Keycloak에 Client를 만들고 Client authentication을 켭니다. Valid Redirect URI에 화면 안내대로 https://<서비스 주소>/api/v1/auth/oidc/callback을 등록합니다. 안내 주소는 리버스 프록시가 넘겨준 X-Forwarded-Host·X-Forwarded-Proto로 만들어지므로 프록시 설정을 먼저 맞춥니다.
2. Group Membership mapper로 groups claim을 ID Token에 넣고, /seaton-admins·/seaton-seat-managers 그룹을 만듭니다(이름을 바꾸면 설정의 그룹 이름도 맞춥니다).
3. 시스템 설정 → Keycloak SSO에 Issuer URL·Client ID·Client Secret을 넣고 설정 저장, 이어서 저장 후 연결 테스트(POST /api/v1/settings/oidc/test)로 Discovery 문서와 콜백 주소를 확인합니다.
4. Keycloak SSO 사용을 켜고 저장합니다. 다른 브라우저에서 SSO 로그인이 되는 것을 확인한 뒤에야 로컬 관리자 로그인 허용을 끌지 결정합니다.

SSO 사용자는 첫 로그인 때 자동 생성되고 그룹으로 역할이 정해집니다. 이미 system_admin인 사용자는 그룹이 바뀌어도 강등되지 않습니다.

3.4 좌석 인식 엔진과 사내 비전 모델

기본값 cv는 외부 통신이 전혀 없습니다. vlm·hybrid를 쓰려면 사내 추론 서버 주소를 넣고 설정 저장 뒤 저장 후 VLM 연결 시험(POST /api/v1/settings/ai/vlm/test)으로 주소·인증·응답 형식·좌표계를 한 번에 확인합니다. 엔진별 동작·실측·실패 처리는 §8에 있습니다.

3.5 인사 연동

hr.api_url을 GET으로 호출하고 hr.api_token이 있으면 Authorization: Bearer를 붙입니다. 응답 JSON의 organizations[](externalId, name, parentExternalId, color)와 employees[](employeeNo, name, email, organizationExternalId, title, position, workplace, status)를 upsert합니다. 화면의 저장 후 지금 동기화(POST /api/v1/settings/hr/sync)로 즉시 돌려 볼 수 있고, 결과는 employee_sync_runs 테이블과 감사 로그(hr.sync)에 남습니다. status가 retired인 직원이 좌석을 갖고 있으면 처리필요의 퇴직자 항목이 됩니다.

4. 계정과 권한

권한 검사는 서버에서 합니다(requireSeatManager → 403 seat_manager_required, requireAdmin → 403 admin_required). API 키로 부르는 요청은 키 소유자의 역할에 키의 범위(read·write·mcp)가 교집합으로 걸립니다. 예를 들어 assign_seat MCP 도구는 소유자가 좌석 관리자 이상이고 키에 write·mcp가 모두 있어야 합니다.

사용자 권한(/admin/users)에서 역할을 바로 바꿉니다. 화면에는 계정 만들기가 없습니다 — 로컬 계정은 부트스트랩 관리자 하나뿐이고, 나머지 사용자는 SSO 첫 로그인 때 생깁니다. 계정을 막으려면 PATCH /api/v1/users/{id}에 {"active": false}를 보냅니다(비활성 사용자는 로그인·세션·API 키가 모두 거부됩니다).

로컬 관리자 비밀번호는 시스템 설정 → 보안 · 키에서 바꿉니다(12자 이상, POST /api/v1/auth/password, 브라우저 세션에서만 가능). 바꾸면 현재 세션을 제외한 다른 세션이 종료됩니다.

5. 운영

5.1 상태 점검

처리필요 화면의 운영 준비도와 연동 상태가 같은 정보를 사람이 보기 좋게 보여 줍니다.

5.2 로그

표준 출력에 JSON 한 줄씩(log/slog) 찍힙니다. docker compose logs -f seaton으로 봅니다. 요청마다 "msg":"request"에 메서드·경로·소요 시간·request_id가 남습니다.

{"time":"2026-09-11T11:41:57Z","level":"INFO","msg":"SeatOn started","address":":8080","version":"1.4.1","commit":"…"}
{"time":"…","level":"INFO","msg":"request","method":"GET","path":"/readyz","duration_ms":0,"request_id":"…"}
{"time":"…","level":"INFO","msg":"도면 분석 완료","jobId":"…","floorMapId":"…","engine":"cv","detected":30,"review":6}

업무 감사 로그는 별도로 DB audit_logs 테이블에 사용자·IP·대상과 함께 쌓입니다(auth.login, settings.update, floor_map.publish, assignment.create, api_key.revoke 등). 좌석 이동 이력은 변경 이력 화면에서 CSV로 내보낼 수 있습니다.

5.3 백업

한 세트로 같이 받습니다.

# PostgreSQL
pg_dump "$POSTGRES_DSN" -Fc -f seaton-$(date +%F).dump

# master.key (볼륨)
docker run --rm -v seaton-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/seaton-data-$(date +%F).tgz -C /data .

master.key를 잃으면 DB의 암호화된 Client Secret·VLM 키·인사 토큰을 복호화할 수 없고, 세션과 개인 API 키의 해시도 맞지 않게 되어 모두 새로 발급해야 합니다. 개인 API 키 원문은 어떤 경우에도 복구되지 않습니다.

5.4 복구

docker compose down
pg_restore -d "$POSTGRES_DSN" --clean --if-exists seaton-YYYY-MM-DD.dump
docker run --rm -v seaton-data:/data -v "$PWD":/backup alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/seaton-data-YYYY-MM-DD.tgz -C /data && chown -R 10001:10001 /data'
docker compose up -d && curl -s http://127.0.0.1:8080/readyz

5.5 백그라운드 작업

5.6 업그레이드와 되돌리기

스키마는 기동 때 자동으로 맞춰지므로(migrations.sql, 멱등) 별도 마이그레이션 명령이 없습니다. 대신 올리기 전에 §5.3 백업을 먼저 받습니다.

pg_dump "$POSTGRES_DSN" -Fc -f before-v1.5.0.dump
docker load < SeatOn-v1.5.0.tar.gz
export SEATON_IMAGE_TAG='v1.5.0'
docker compose up -d
curl -s http://127.0.0.1:8080/api/v1/version    # "version":"1.5.0"

되돌릴 때는 태그를 이전 값으로 바꿔 다시 올립니다. 새 버전이 스키마를 바꾼 뒤라면 이전 바이너리가 그 스키마를 이해한다는 보장이 없으므로, 백업한 덤프를 먼저 복원합니다.

export SEATON_IMAGE_TAG='v1.4.1'
docker compose up -d

분석이 진행 중일 때 재시작하면 그 잡은 실패로 정리되고 도면은 다시 분석할 수 있는 상태로 돌아옵니다. 릴리즈 자산은 SeatOn-v<버전>.tar.gz → seaton:v<버전> 이름 규칙을 따르고, 애플리케이션이 알리는 버전 문자열은 v 없는 1.4.1입니다.

6. 장애 대응

7. 보안

• 바꿔야 하는 기본값: BOOTSTRAP_ADMIN_PASSWORD는 설치 직후 화면에서 변경. POSTGRES_DSN은 sslmode=require 이상. 비밀값 예시(change-this-strong-password)를 그대로 두지 않습니다.
• 밖에 열면 안 되는 것: :8080은 리버스 프록시 뒤에만 둡니다. PostgreSQL 포트는 SeatOn 컨테이너에서만 닿게 합니다. /mcp와 /api/v1/*은 같은 포트이므로 프록시에서 따로 막을 필요는 없지만, 사내망 밖으로 열지 않습니다.
• 프록시에서 HTTPS 종료: X-Forwarded-Proto: https와 X-Forwarded-Host를 반드시 전달합니다. 이 값으로 세션 쿠키의 Secure 플래그와 OIDC 콜백 주소가 결정됩니다.
• 컨테이너 강화: compose.yaml의 read_only, cap_drop: ALL, no-new-privileges, 비루트 UID 10001을 그대로 둡니다. 응답에는 CSP default-src 'self', X-Frame-Options: DENY, nosniff가 항상 붙습니다.
• 비밀값 저장: 설정의 비밀값은 master.key로 AES-256-GCM 암호화, 세션 토큰과 API 키는 HMAC 해시만 저장. master.key는 백업 대상이자 유출 금지 대상입니다.
• 인증 연동: Keycloak Authorization Code + PKCE(S256) + nonce 검증. SSO를 검증한 뒤 auth.local_enabled를 끄면 부트스트랩 계정도 화면에서는 못 들어오므로, 비상시 되돌리는 SQL(§6)을 운영 문서에 적어 둡니다.
• API 키 정책: 기본 유효기간 90일, 회전 유예 24시간. 유출이 의심되면 소유자가 폐기하거나, 관리자가 그 사용자를 비활성화합니다(비활성 사용자의 키는 즉시 거부).
• 인터넷 통신: 기본 설정(ai.engine=cv, SSO·인사 연동 꺼짐)에서는 컨테이너가 밖으로 나가는 연결이 없습니다. 연결이 생기는 곳은 Keycloak Issuer, hr.api_url, ai.vlm_base_url 세 군데뿐이며 모두 사내 주소를 씁니다.

8. 좌석 인식 엔진 (CV · VLM · 하이브리드)

시스템 설정 → AI 분석에서 도면 판독 엔진을 선택합니다. 세 방식 모두 결과를 동일한 비율 좌표 좌석으로 저장하므로 이후 편집·배정 흐름은 같습니다.

기본값은 cv입니다. hybrid가 항상 더 낫지는 않으므로 8.2의 실측 비교를 먼저 확인하십시오.

8.1 VLM 엔드포인트 설정

OpenAI 호환 /chat/completions 인터페이스를 제공하는 사내 추론 서버를 지정합니다. vLLM, SGLang, Ollama 등으로 Qwen2.5-VL 계열을 서빙한 주소를 쓰며, 인터넷 구간으로 나가는 주소를 넣지 마십시오. 설정을 저장한 뒤 저장 후 VLM 연결 시험 버튼을 누르면 합성 도면 한 장을 왕복시켜 주소·인증·응답 형식·좌표계를 한 번에 검증합니다.

8.2 실측 결과 (Qwen2.5-VL 7B, Ollama, RTX 5090)

합성 사무실 도면(책상 30개, 1600×1100, 외벽·복도벽·회의실·의자·치수선 포함)으로 엔진별 정확도를 측정한 값입니다. 정답과 IoU 0.5 이상 겹치면 일치로 계산했습니다.

가로 도면에서 하이브리드가 유리한 이유는 정확도가 아니라 검토 부담입니다. CV 단독은 6건이 자동 승인선 아래로 남지만, VLM이 같은 자리를 지목해 교차 검증되면 신뢰도가 0.95 이상으로 올라가 관리자가 확인할 항목이 사라집니다.

도면별 결과는 다음과 같습니다. PDF는 A3 150 DPI 래스터(2481×1754) 기준입니다.

세로 도면에서는 하이브리드가 CV보다 나빴습니다. VLM이 책상 28개 중 4개만 CV와 합의하고 14개를 엉뚱한 곳에 보고해, 그 오검출이 좌석으로 추가되면서 정밀도가 1.000에서 0.667로 떨어졌습니다. 그래서 CV가 책상 격자를 복원한 도면에서는 격자를 벗어난 VLM 단독 상자를 제외하도록 했고(10건 제외), 정밀도가 0.875, F1 0.933으로 회복됐습니다. 남은 오검출 4건은 우연히 격자 근처에 놓인 것으로, 모두 검토 대상으로 표시되며 분석 완료 후 경고에 “VLM만 찾은 좌석이 교차 검증된 건수보다 많습니다”가 함께 뜹니다.

정리하면 도면 종류에 따라 하이브리드가 CV보다 나쁠 수 있습니다. 도입 시 대표 도면 몇 장으로 cv와 hybrid를 모두 돌려 비교하고, VLM 합의 건수(details.agreed)가 CV 검출 수에 근접하는지 확인하십시오. 합의 비율이 낮으면 cv를 쓰는 편이 낫습니다.

프롬프트 설계가 정확도를 좌우합니다. 같은 모델·같은 도면에서 프롬프트 형식만 바꿔 5회씩 측정한 결과입니다.

SeatOn은 마지막에서 두 번째 형식을 사용하며, 여기에 시스템 메시지를 더한 실제 구현이 위 표의 0.900입니다. 좌석 수 상한은 프롬프트가 아니라 서버에서 잘라냅니다.

타일 분할은 이 모델에서 역효과였습니다. 1×1 F1 0.30 → 2×2 0.04 → 3×3 0.00. 큰 도면에서 작은 객체를 키워 보려던 의도였지만, Qwen 계열의 grounding은 장면 전체를 볼 때 더 정확했습니다. 기본값 1을 유지하고, 다른 모델로 교체할 때만 실제 도면으로 재측정해 조정하십시오.

좌표계는 같은 모델도 입력에 따라 바꿉니다. 실측에서 Qwen2.5-VL은 1600×1100 도면에는 절대 픽셀 좌표로, 640×480 시험 도면에는 0~1000 좌표로 답했습니다. SeatOn은 후보 좌표계를 모두 적용해 자동 판별하며, 판별 결과를 분석 잡의 details.vlmCoordinates에 기록합니다. 연결 시험 결과에도 표시되므로 모델 교체 시 먼저 확인하십시오.

8.3 신뢰도 보정 원칙

비전 모델이 스스로 보고하는 확신도는 보정된 확률이 아닙니다. 그래서 VLM이 단독으로 찾은 좌석은 신뢰도를 0.88~0.94로 제한해 자동 승인선(기본 0.95)을 절대 넘지 못하게 하고 항상 관리자 검토 큐에 남깁니다. 하이브리드에서 CV와 VLM이 같은 자리를 지목한 좌석만 0.90 이상으로 올라가 자동 승인 대상이 됩니다. CV가 단독으로 찾은 좌석은 소폭 감점합니다. 좌석의 metadata.source 값(cv, vlm, cv+vlm, grid-fill)으로 근거를 추적할 수 있습니다.

8.4 분석은 비동기 잡입니다

VLM 판독은 도면 크기와 타일 수에 따라 수십 초에서 수 분이 걸립니다. POST /floor-maps/{id}/analyze는 즉시 202와 jobId를 돌려주고 실제 작업은 백그라운드에서 진행됩니다. 관리자 화면은 완료까지 진행 상태를 표시합니다. 같은 도면을 동시에 두 번 분석할 수 없으며(409 analysis_running), 서비스가 재시작되어 중단된 잡은 다음 기동 시 실패로 정리되고 도면 상태도 복구됩니다.

8.5 예상되는 실패와 동작

모든 경고는 분석 완료 후 도면 화면에 목록으로 표시되며 analysis_jobs.warnings에 함께 기록됩니다.