기능 스포트라이트: 명령줄 인터페이스(CLI) 통합¶

나의 매우 중요한 친구 Lub에게 바칩니다.

새로운 FastAPI 기반 명령줄 인터페이스(CLI)는 모든 로컬 또는 원격 셸에서 실행 중인 핵심 텍스트 처리 서비스와 상호 작용할 수 있는 깔끔하고 동기적인 방법을 제공합니다. 이는 핵심 로직을 셸 환경에 통합하도록 설계된 강력한 솔루션입니다.

1. 아키텍처 및 동기식 CLI 개념¶

이 서비스는 Uvicorn/FastAPI 서버로 구동되며 사용자 정의 엔드포인트(/process_cli)를 사용하여 본질적으로 비동기식인 파일 기반 백그라운드 프로세스에서 동기식(차단) 결과를 제공합니다.

고유한 출력 재정의: API는 각 요청에 대해 고유한 임시 디렉터리를 생성합니다.
프로세스 시작: 비차단 스레드에서 핵심 로직을 실행하기 위해 process_text_in_Background를 호출하고 해당 고유 폴더 내의 tts_output_*.txt 파일에 결과를 씁니다.
동기 대기: 그런 다음 API 기능은 출력 파일이 생성되거나 시간 초과에 도달할 때까지 고유 폴더를 차단하고 폴링합니다.
결과 전달: API는 파일의 내용을 읽고 필요한 정리(파일 및 임시 디렉터리 삭제)를 수행한 다음 JSON 응답의 result_text 필드에 최종 처리된 텍스트를 반환합니다.

이렇게 하면 CLI 클라이언트가 텍스트 처리가 완료된 후에만 응답을 수신하여 안정적인 셸 경험을 보장할 수 있습니다.

Lub의 터미널과 같은 원격 클라이언트에서의 액세스를 허용하려면 제한된 외부 포트 가용성이라는 일반적인 제약 조건을 해결하기 위해 다음과 같은 네트워크 구성이 필요했습니다.

서비스는 내부적으로 포트 8000에서 실행되고 당사의 네트워크 환경은 외부 액세스를 특정 포트 범위(예: 88__-8831)로 제한하므로 라우터(Fritz!Box)에 포트 매핑을 구현했습니다.

엔드포인트	프로토콜	포트	설명
외부/공개	TCP	`88__` (예)	클라이언트(Lub)가 사용해야 하는 포트입니다.
내부/로컬	TCP	`8000`	FastAPI 서비스가 실제로 수신 대기하는 포트입니다(`--port 8000`).

라우터는 외부 포트(‘88__’)에서 들어오는 모든 연결을 호스트 시스템의 내부 포트(‘8000’)로 변환하여 코어 서버 구성을 변경하지 않고도 서비스에 전역적으로 액세스할 수 있도록 합니다.

클라이언트는 공용 IP 주소, 외부 포트 및 올바른 API 키로 구성되어야 합니다.

CODE_BLOCK_0