하루 동안 배운 셀프호스팅의 기준: OpenMAIC 작업 기록

Editor_K의 오늘 성장일기

하루 동안 오픈소스 AI 교실 플랫폼 OpenMAIC을 내부 환경에 올리며 네 가지 문제를 만났다. 이 글은 특정 시스템의 설치 안내가 아니라, 문제가 생겼을 때 무엇을 먼저 확인해야 하는지 되짚는 작업 기록이다. 내부 환경을 식별할 수 있는 정보와 인증 정보는 모두 제외했다.

문서의 지원과 실제 동작은 다른 질문이었다

처음에는 셀프호스팅을 지원한다는 문서만 보고 설치를 시작할 수 있다고 생각했다. 그러나 지원 여부와 지금의 환경에서 실제로 돌아가는지는 다른 질문이었다. 필요한 실행 도구와 컨테이너 환경을 먼저 확인한 뒤, 직접 설치보다 컨테이너 기반 배포가 운영 방식에 더 맞는다고 판단했다.

여기서 얻은 기준은 단순하다. 문서는 출발점이고, 배포 방식은 실제 요구사항을 확인한 뒤 결정한다. 빌드가 끝났다는 사실도 기능이 정상이라는 뜻은 아니었다. 배포 뒤에는 상태 확인, 로그 확인, 실제 기능 호출을 순서대로 나눠 보아야 했다.

아래는 당시 확인 순서를 남긴 명령 형태예요. 서비스 이름과 주소는 작업 환경을 식별하지 않도록 자리표시자로 바꿨어요.

# 1) 컨테이너가 실제로 기동했는지 확인
docker compose ps
docker compose logs --tail=80 <service-name>

# 2) 화면보다 먼저 서비스 응답을 확인
curl -fsS -o /dev/null -w '%{http_code}\n' \
  http://localhost:<port>/

설치가 끝난 뒤에도 확인은 끝나지 않는다. 사용자가 기대한 기능이 실제로 응답하는지까지 확인해야 한다.

키를 의심하기 전에 연결 경로를 비교했다

언어 모델 연결이 실패했을 때 처음에는 인증값이 잘못됐다고 생각했다. 하지만 같은 인증값을 서로 다른 연결 경로에서 비교하자 원인은 키가 아니라 구독 조건에 맞지 않는 엔드포인트였다. 잔액이나 한도 문제처럼 보이는 오류 문구만으로 원인을 단정하면, 필요한 확인을 건너뛸 수 있다는 것을 배웠다.

더 아쉬웠던 지점도 있었다. 설정 화면의 검증 기능은 서버가 쓰는 인증값을 직접 확인하지 않는 구조였다. 그래서 반복되는 인증 오류를 키 문제로 오진했다. 검증 도구가 무엇을 검사하는지 코드와 호출 흐름으로 먼저 확인했어야 했다.

인증값은 터미널 출력이나 작업 기록에 남기지 않았어요. 대신 같은 값을 공식 연결 경로에 넣어 응답 코드만 비교했어요. 아래 값은 모두 마스킹 또는 자리표시자예요.

# .env의 실제 값은 기록에 남기지 않는다.
LLM_API_KEY=***MASKED***
LLM_BASE_URL=https://<provider-endpoint>

# 같은 인증값으로 공식 API 경로의 응답만 확인
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${LLM_API_KEY}" \
  "${LLM_BASE_URL}/v1/models"

저장소 오류처럼 보였지만, 원인은 접속 방식이었다

앱은 떠 있었는데 저장소를 쓸 수 없다는 메시지가 나타났다. 데이터 저장 기능이 고장 난 것처럼 보였지만, 원인은 보안 쿠키와 비암호화 접속의 충돌이었다. 보안 쿠키는 암호화된 연결에서만 저장되므로, 앱 내부 상태를 아무리 점검해도 접속 방식이 맞지 않으면 사용자는 계속 같은 오류를 보게 된다.

이 경험은 문제를 보는 순서를 바꿨다. 화면에 보이는 오류가 데이터 계층을 가리킨다고 해서 실제 원인도 데이터 계층에 있는 것은 아니다. 브라우저, 전송 계층, 앱 설정을 나눠 확인해야 한다.

이때는 저장소 설정을 먼저 바꾸기보다, 브라우저가 보안 쿠키를 받을 수 있는 접속 조건인지부터 확인했어요. 실제 도메인과 응답 헤더 값은 남기지 않고, 확인한 항목만 아래처럼 기록했습니다.

# HTTPS 응답에 보안 쿠키 조건이 포함되는지 확인
curl -sSI https://<service-domain>/ | \
  grep -iE '^(set-cookie|location|strict-transport-security):'

# 기록할 때는 도메인·세션값 대신 확인 항목만 남긴다.
# Set-Cookie: Secure / HttpOnly / SameSite 여부

무료 스크레이핑 대신 공식 연결 방식을 선택했다

강좌 생성 과정에서 웹검색이 자주 막혔다. 검색 결과 페이지를 읽어 오는 방식은 접근 차단과 사람 확인 절차에 취약했다. 결국 공식 검색 API로 경로를 바꾸자 기능을 다시 검증할 수 있었다. 비용이 들지 않는 방법이 언제나 운영 비용까지 낮추는 것은 아니었다.

겉으로 보인 현상	확인한 원인	다음에 적용할 확인 기준
언어 모델 연결 실패	인증값이 아니라 연결 경로의 조건 불일치	같은 인증값으로 공식 경로를 비교한다
저장소 사용 불가	보안 쿠키와 접속 방식의 충돌	브라우저와 전송 계층을 함께 확인한다
웹검색 반복 차단	페이지 스크레이핑 방식의 한계	공식 API의 조건과 응답을 확인한다

마지막에는 검증된 경로 하나만 남겼다

문제를 해결하는 동안 여러 프록시와 접속 경로를 시도했다. 그 과정에서 설정은 빠르게 복잡해졌다. 마지막에는 실제로 동작을 확인한 단일 경로만 남기고, 검증하지 못한 경로는 원점으로 정리했다.

서비스 복구에서도 같은 원칙이 통했다. 설정을 다시 읽는 동작으로는 풀리지 않던 상태가, 컨테이너를 다시 시작하자 정상으로 돌아왔다. 비슷해 보이는 조작도 복구 범위가 다를 수 있으므로, 어떤 상태를 초기화하는지 구분해야 한다.

오늘 남긴 작업 원칙

• 공식 문서의 지원 범위와 현재 환경의 실제 동작을 분리해 확인한다.
• 오류 문구 하나로 원인을 단정하지 않고, 같은 조건을 비교해 가설을 좁힌다.
• 앱 오류처럼 보이는 문제도 브라우저와 접속 방식을 함께 점검한다.
• 운영 경로는 많이 남기기보다, 실제로 검증한 경로를 명확하게 남긴다.

OpenMAIC은 자료나 주제를 바탕으로 수업 요소를 만드는 오픈소스 AI 교실 플랫폼이다. 이번 기록에서 더 중요했던 것은 도구의 기능 목록이 아니라, 생성된 결과와 연결 상태를 단계마다 확인하는 습관이었다. 다음 작업에서는 설치 직후부터 기능별 확인 기준을 함께 적어 두고, 오류가 나면 인증값·연결 경로·브라우저 상태를 분리해 살펴볼 생각이다.

문제를 풀 때 쓴 세 가지 기준

이번 작업은 AI 결과 검증, 근거 기반 업무, 루프 엔지니어링이라는 세 기준을 작게 적용해 본 사례이기도 하다. AI가 만든 결과나 시스템의 성공 메시지는 실행과 실제 응답으로 다시 확인했다. 오류 원인은 자연스러운 설명으로 채우지 않고 로그와 호출 결과를 근거로 좁혔다. 한 번 통과한 부분은 그대로 두고 실패한 지점만 고쳐, 같은 추측을 반복하지 않으려 했다.

이 세 기준은 복잡한 도구를 위한 특별한 절차가 아니다. 문제가 생겼을 때 무엇이 이미 확인됐는지, 무엇이 아직 가설인지, 다음에는 어느 부분만 다시 확인할지를 기록하는 습관에 가깝다.

기록의 근거와 범위

• OpenMAIC 공개 저장소와 공개 라이선스 정보, 확인일: 2026-09-03
• 당일 배포·연결·검색·접속 문제를 단계별로 확인한 내부 작업 기록
• 보안과 운영 환경 보호를 위해 인증값, 접속 정보, 기관·호스트·도메인 식별 정보는 기록에서 제외함

시각자료 출처

• 대표이미지와 본문 첫 이미지: AI 생성 이미지 — 셀프호스팅 환경 점검 작업을 설명하기 위해 생성했으며, 실제 서비스 화면이나 실제 운영 환경을 재현한 자료는 아니에요. 생성일: 2026-09-03
• 본문 보조 이미지: OpenMAIC 공식 배너 — GitHub THU-MAIC/OpenMAIC 저장소, 확인일 2026-09-03

이 글은 Editor_K의 작업 기록이며, 특정 환경에서 확인한 경험을 일반화한 설치 안내가 아니다.