fix(deps): pin numpy<2.2 for CPUs without x86_64_v2; docs Apache+503

- Avoid NumPy wheel baseline X86_V2 import crash on older VMs
- README: NumPy error remediation, Apache ProxyPass example, web UI note

Made-with: Cursor

README.md

@@ -156,22 +156,47 @@ uvicorn app.main:app --reload --host 127.0.0.1 --port 8025
 
 브라우저에서 `http://127.0.0.1:8025` 접속.
 
-웹 UI는 **faster-whisper** 전사만 수행합니다. 화자 구분이 필요하면 **`whisper_stt.py`**(로컬 CLI)를 사용하세요.
+웹 UI는 **faster-whisper** 전사와(옵션) **pyannote 화자 분리**를 지원합니다. OpenAI Whisper 기반 CLI는 **`whisper_stt.py`** 를 사용하세요.
 
 ### HTTPS 도메인(`https://ncue.net/stt/…`)에서 503 (Service Unavailable)
 
-브라우저가 **503**을 보여 줄 때, 대부분 **리버스 프록시(nginx 등)가 백엔드(uvicorn)에 붙지 못했다**는 뜻입니다. 이 저장소의 앱은 일반적으로 **503을 직접 내지 않습니다.**
+브라우저가 **503**을 보여 줄 때, 대부분 **리버스 프록시(nginx·Apache 등)가 백엔드(uvicorn)에 붙지 못했다**는 뜻입니다. 이 저장소의 앱은 일반적으로 **503을 직접 내지 않습니다.**
 
 **흔한 원인**
 
 1. **`run.sh`를 다른 머신에서만 실행한 경우**  
-   `run.sh`는 uvicorn을 **`127.0.0.1:8025`**에만 띄웁니다. **nginx가 돌아가는 서버와 같은 호스트**에서 프로세스가 떠 있어야 `https://도메인/stt/` 프록시가 연결됩니다. 노트북에서만 `./run.sh`를 켜 두면 공개 도메인 쪽 업스트림은 비어 있어 **503**이 납니다.
+   `run.sh`는 uvicorn을 **`127.0.0.1:8025`**에만 띄웁니다. **웹 서버(프록시)가 돌아가는 서버와 같은 호스트**에서 프로세스가 떠 있어야 `https://도메인/stt/` 프록시가 연결됩니다. 노트북에서만 `./run.sh`를 켜 두면 공개 도메인 쪽 업스트림은 비어 있어 **503**이 납니다.
 
 2. **프로세스가 곧바로 종료된 경우**  
-   DB 설정 오류, import 실패 등으로 uvicorn이 뜨자마자 죽으면 프록시도 503을 냅니다. **서버에서** `tail -n 100 server.log` 로 스택 트레이스를 확인하세요.
+   DB 설정 오류, **import 실패(NumPy·torch 등)** 로 uvicorn이 뜨자마자 죽으면 프록시도 503을 냅니다. **서버에서** `tail -n 100 server.log` 로 스택 트레이스를 확인하세요.
 
 3. **포트·프록시 설정 불일치**  
-   nginx `upstream` / `proxy_pass`가 가리키는 포트가 실제 uvicorn 포트(`PORT`, 기본 8025)와 같아야 합니다.
+   프록시가 가리키는 포트가 실제 uvicorn 포트(`PORT`, 기본 8025)와 같아야 합니다.
+
+#### 구형 CPU / NumPy `X86_V2` 오류 (`server.log`)
+
+다음처럼 **앱이 시작조차 못 하고** 죽는 경우가 있습니다.
+
+`RuntimeError: NumPy was built with baseline optimizations: (X86_V2) but your machine doesn't support: (X86_V2).`
+
+의미: 설치된 NumPy **바이너리**가 x86_64_v2(AVX2 등)를 요구하는데, 서버 CPU가 이를 지원하지 않습니다. (가상머신·오래된 Xeon 등에서 흔합니다.)
+
+**조치** (웹 서버에서, 사용 중인 conda env — 예: `ncue`):
+
+```bash
+conda activate ncue
+pip install "numpy>=1.26,<2.2" --force-reinstall
+pip install -r requirements.txt   # 나머지 의존성 유지
+./run.sh
+```
+
+pip만으로 안 되면 **conda-forge** NumPy가 해당 CPU에 맞는 빌드를 주는 경우가 많습니다.
+
+```bash
+conda install -n ncue "numpy<2.2" -c conda-forge
+```
+
+이 저장소 `requirements.txt`에는 위와 같이 **`numpy<2.2`** 를 명시해 두었습니다. 이미 깨진 환경은 위처럼 한 번 재설치하면 됩니다.
 
 **같은 서버에서 빠른 점검**
 
@@ -197,6 +222,15 @@ location /stt/ {
 
 `proxy_pass`에 **끝 슬래시(`/`)**가 있어야 `location /stt/`와 짝이 맞아 경로가 올바르게 넘어갑니다. 설정을 고친 뒤 **`nginx -t` 후 reload** 하세요.
 
+**Apache (`httpd`) 예시** (`mod_proxy`, `mod_proxy_http` 필요)
+
+```apache
+ProxyPass        "/stt/" "http://127.0.0.1:8025/"
+ProxyPassReverse "/stt/" "http://127.0.0.1:8025/"
+```
+
+설정 반영 후 `apachectl configtest` 및 재시작(또는 reload) 하세요.
+
 공개 URL은 가능하면 **`https://예시/stt/`** 처럼 **슬래시까지 포함**해 두면, UI의 상대 경로(`healthz`, `api/…`)가 같은 접두사 아래로 잘 붙습니다.
 
 ---

requirements.txt

@@ -2,6 +2,8 @@ fastapi
 uvicorn[standard]
 python-multipart
 pydantic
+# NumPy 2.2+ Linux wheel은 x86_64_v2(AVX2 등) 기준인 경우가 많아, 구형 CPU 서버에서 import 시 RuntimeError가 납니다.
+numpy>=1.26,<2.2
 faster-whisper
 imageio-ffmpeg
 psycopg[binary]