<p>도메인, OpenAI API, 이미 운영 중이던 한 대의 VPS. 이 셋만으로 내가 쓴 글들이 검색되고, 시멘틱 검색이 작동하는 사이트를 만들었다. 도구는 <strong>Next.js · FastAPI · docconv</strong> 셋. 공식 문서대로 따라가다 막힌 지점들과 그걸 어떻게 풀었는지 기록한다.</p><h2>왜 자체 VPS인가</h2><p>처음엔 Vercel을 고민했다. Next.js의 본가이고, 무료 티어로 충분히 시작 가능. 그러나 두 가지 이유로 자체 호스팅을 택했다.</p><ul><li><p><strong>비용 통제</strong> — 트래픽 늘어나도 같은 VPS 안에서 끝남. Vercel은 이미지 최적화·serverless 호출 단위로 과금</p></li><li><p><strong>사이드카 자유도</strong> — Python ML 스택(docconv)을 같은 호스트에 띄워야 하는데, Vercel에선 별도 서비스로 분리해야 한다. 작은 사이트엔 과함</p></li></ul><p>이미 다른 서비스(<code>ai.sshsys.kr</code>)가 운영되고 있던 VPS라서, 그 위에 nginx 가상호스트만 추가하는 형태가 가장 단순했다.</p><h2>최종 토폴로지</h2><pre><code>VPS (Ubuntu 24.04)
├── nginx :80/:443
├── postgresql :5432 (localhost only)
│
├── ai.sshsys.kr   → :8001 hssagent (기존)
├── sshsys.kr      → :3000 portfolio web (Next.js)
├── api.sshsys.kr  → :8002 portfolio api (FastAPI)
└── docs.sshsys.kr → :8003 docconv (지식 플랫폼)
</code></pre><p>4개의 도메인, 3개의 새 서비스. 각각 격리된 venv·systemd 유닛·DB를 가진다.</p><h2>첫 함정: 공유 venv 충돌</h2><p>처음에 시간을 아끼려고 portfolio 백엔드와 docconv를 같은 venv에 깔았다. 곧장 깨졌다.</p><pre><code>fastapi.exceptions.FastAPIError: Invalid args for response field!
Hint: check that ForwardRef('UploadFile') is a valid Pydantic field type.</code></pre><p>portfolio가 FastAPI 0.115.0에 핀되어 있는데, docconv는 0.136.1을 기대해서 한 venv에 두 버전이 충돌. 결국 venv를 분리했다.</p><pre><code>/var/www/sshsys/
├── venv/                  ← portfolio 전용 (FastAPI 0.115.0)
└── docconv/venv/          ← docconv 전용 (FastAPI 0.136.1)
</code></pre><p>당연한 듯하지만 한 번 합쳐봐야 절실해진다. <strong>운영 환경에서 venv 공유는 절대 비추</strong>.</p><h2>Pydantic Settings의 까다로움</h2><p>portfolio 백엔드의 <code>config.py</code>는 pydantic-settings로 환경변수를 관리한다. 그런데 docconv 연동을 위해 <code>.env</code>에 <code>DOCCONV_URL</code>·<code>DOCCONV_INTERNAL_TOKEN</code>·<code>PUBLIC_SITE_URL</code>을 추가하니 시작도 못 했다.</p><pre><code>pydantic_core._pydantic_core.ValidationError: 4 validation errors for Settings
public_site_url
  Extra inputs are not permitted</code></pre><p>해결: <code>extra="ignore"</code> 옵션 추가. 이러면 라우터에서 <code>os.environ.get(...)</code>로 직접 읽는 변수들이 Settings에 등록되어 있지 않아도 거부되지 않는다.</p><pre><code class="language-python">model_config = SettingsConfigDict(
    env_file=".env",
    case_sensitive=False,
    extra="ignore",
)</code></pre><h2>빌드 시점에 SSL 미발급 도메인 호출하는 함정</h2><p>가장 까다로웠던 부분. 프론트엔드를 빌드할 때 Next.js가 <code>getStaticProps</code>를 실행하면서 <code>https://api.sshsys.kr</code>에 axios로 fetch한다. 그런데 그 시점엔 nginx에 <code>api.sshsys.kr</code> 가상호스트도, SSL 인증서도 없었다. 그래서 같은 IP의 다른 호스트의 인증서가 응답하면서 호스트 불일치 에러.</p><pre><code>Error: Hostname/IP does not match certificate's altnames:
  Host: api.sshsys.kr is not in the cert's altnames:
  DNS:ai.sshsys.kr, DNS:&lt;other-service&gt;
</code></pre><p>해결책은 <strong>서버사이드용 API URL과 브라우저용 API URL을 분리</strong>하는 것이다.</p><pre><code class="language-javascript">// src/lib/api.js
export const API_URL =
  (typeof window === "undefined"
    ? process.env.INTERNAL_API_URL || process.env.NEXT_PUBLIC_API_URL
    : process.env.NEXT_PUBLIC_API_URL) || "http://localhost:8000";</code></pre><p><code>.env.local</code>:</p><pre><code>NEXT_PUBLIC_API_URL=https://api.sshsys.kr      # 브라우저
INTERNAL_API_URL=http://127.0.0.1:8002          # 빌드/SSR
</code></pre><p>빌드 시점은 nginx 거치지 않고 백엔드 직접 호출. 브라우저는 공개 도메인. nginx 설정 순서에 빌드가 종속되지 않는다. 같은 정보가 두 경로로 흘러야 할 때 분리하는 패턴은 다른 곳에서도 쓸 수 있다.</p><h2>docconv 사이드카 — pgvector로 단순화</h2><p>이 사이트에는 시멘틱 검색·Q&amp;A·엔티티 자동 추출을 담당하는 별도 서비스가 떠 있다. docconv라는 지식 플랫폼인데, 처음엔 ChromaDB를 쓸 줄 알았다.</p><p>그런데 docconv의 store는 <strong>PostgreSQL + pgvector</strong> 백엔드를 지원한다. 이미 portfolio 백엔드용 Postgres가 있으므로, 같은 인스턴스에 <code>docconv</code> DB만 추가하면 끝. ChromaDB가 자체 SQLite + DuckDB 메모리를 따로 잡는 것 대비 메모리 풋프린트가 작다.</p><pre><code>{"status":"ok","backend":"postgresql+pgvector",
 "collections":{"chunks":0,"entities":0},
 "embedding_model":"text-embedding-3-small"}</code></pre><p>대기 메모리 <strong>140MB</strong>. ChromaDB 구성이었으면 250MB 이상 잡았을 것.</p><h2>portfolio ↔ docconv 연결</h2><p>두 서비스 사이엔 내부 토큰 한 줄로 끝낸다. portfolio가 글을 저장하면 background_task로 docconv의 <code>/wiki/ingest</code>를 호출. docconv가 본문을 청킹·임베딩·엔티티 추출 후 entity 슬러그를 반환하면, portfolio가 그걸 DB의 <code>entities</code> JSONB 컬럼에 저장한다.</p><pre><code class="language-python"># portfolio backend/app/routers/blogs.py
def _index_blog(blog_id: str, payload: dict) -&gt; None:
    entities = knowledge_client.ingest(
        kind="blog",
        doc_id=blog_id,
        title=payload.get("title") or "",
        content_html=payload.get("content") or "",
        url=f"{SITE_URL}/blog/{blog_id}",
        tags=payload.get("tags") or [],
        category=payload.get("category"),
    )
    if entities is None:
        return
    db = SessionLocal()
    try:
        b = db.query(Blog).filter(Blog.id == blog_id).first()
        if b:
            b.entities = entities or None
            db.commit()
    finally:
        db.close()</code></pre><p>nginx에선 <code>/wiki/ingest</code>·<code>/wiki/remove</code>·<code>/extract</code> 같은 인덱싱 엔드포인트는 <code>127.0.0.1</code>만 허용하고, 검색·Q&amp;A는 공개. 이중 격리.</p><h2>메모리 측정 결과</h2><p>4개 서비스가 동시에 떠 있는 정상 운영 시:</p><pre><code>sshsys-docs (docconv)        139.6 MB
sshsys-backend (hssagent)    202.7 MB
sshsys-api (portfolio)       215.5 MB
sshsys-web (Next.js)          70~150 MB
─────────────────────────────────────
                             약 700 MB</code></pre><p>2GB VPS에 충분히 들어간다. 빌드 시점만 잠깐 1GB 가까이 점유하는데, 그때만 docconv를 일시 중단하면 안전하다.</p><p></p><p>이 글이 사이트에 첫 콘텐츠로 올라가면, docconv가 자동으로 entity를 뽑아낸다. <code>/topics/fastapi</code>·<code>/topics/nginx</code>·<code>/topics/pgvector</code> 같은 페이지가 자동 생성될 것이다. </p><p></p>

My Archive

sshsys.kr 배포기 — Next.js · FastAPI · docconv를 단일 VPS에 띄우기