docs: HTTPS SSL 오류(api 도메인) 점검 안내

Made-with: Cursor

docs/deploy.md

@@ -64,3 +64,7 @@ docker build \
 ## PWA·HTTPS
 
 홈 화면 추가·서비스 워커 동작은 브라우저마다 다르며, **HTTPS**를 쓰는 것이 안정적이다. NAS 리버스 프록시에서 TLS를 종료하는 구성을 권장한다.
+
+### API 도메인에서 `ERR_SSL_VERSION_OR_CIPHER_MISMATCH`가 날 때
+
+PocketBase는 **자체 TLS 없이 HTTP**로 뜨는 경우가 많다. `https://api.todo.sori.studio`는 **프록시가 TLS를 처리**해야 한다. 443에 인증서가 없거나, 백엔드를 잘못된 프로토콜/포트로 넘기면 위 오류가 난다. 절차는 `docs/nas-deploy-guide.md` **11-1**을 본다.

docs/nas-deploy-guide.md

@@ -265,6 +265,29 @@ docker compose up -d --build
 다만 **PWA 설치·서비스 워커**는 브라우저·환경에 따라 HTTPS를 요구하는 경우가 많다.  
 공유기 뒤에서 도메인을 달거나, NAS 리버스 프록시로 **TLS 종료**하는 구성을 최종 목표로 두면 좋다. (구체 도메인·인증서 발급은 NAS/OS마다 다르다.)
 
+### 11-1. `ERR_SSL_VERSION_OR_CIPHER_MISMATCH`(api 서브도메인)
+
+PocketBase 컨테이너는 **기본적으로 HTTPS(TLS)를 제공하지 않는다.** `https://api.todo.sori.studio`는 **리버스 프록시가 443에서 TLS를 종료**하고, 뒤쪽은 `http://<NAS>:42917`처럼 **평문 HTTP**로 PocketBase에 넘기는 구조가 일반적이다.
+
+이 오류는 **브라우저↔443 구간**에서 TLS 협상이 깨질 때 난다. 앱·Compose 코드 문제라기보다 **프록시·인증서·포트** 쪽을 본다.
+
+1. **PocketBase 자체 확인**  
+   브라우저에서 `http://<NAS_LAN_IP>:42917/_/`(호스트 포트는 `docker-compose.yaml` 기준)로 관리자가 열리면 PB는 정상이다.
+
+2. **DNS**  
+   `api.todo.sori.studio`가 **지금 TLS를 설정한 그 NAS(또는 프록시)** IP를 가리키는지 확인한다.
+
+3. **리버스 프록시 443 설정**  
+   - `api`용 서버 블록에 **유효한 인증서**(Let’s Encrypt 등)가 붙어 있는지, 만료·체인 누락이 없는지.  
+   - `proxy_pass` 등 **업스트림은 `http://127.0.0.1:42917`** 처럼 PB의 **HTTP** 포트로 보내는지(HTTPS로 백엔드에 붙이면 PB는 응답하지 않는다).  
+   - 443에서 다른 서비스의 기본 인증서·잘못된 가상 호스트가 응답하고 있지 않은지.
+
+4. **Cloudflare 등 CDN을 쓰는 경우**  
+   SSL 모드가 **Full(strict)** 인데 오리진에 맞는 인증서가 없으면 비슷한 증상이 날 수 있다. 오리진은 HTTP만 둘 거면 **Flexible**(보안상 트레이드오프 있음) 또는 오리진에 정식 TLS를 올리고 **Full**에 맞추는 식으로 정책을 맞춘다.
+
+5. **터미널 확인(선택)**  
+   `curl -vI https://api.todo.sori.studio` 로 응답 헤더·인증서 이름이 기대와 같은지 본다.
+
 ---
 
 ## 12. NAS에 Git이 없을 때
@@ -285,6 +308,7 @@ docker compose up -d --build
 | 컨테이너 이름 충돌 | `todo-pocketbase`·`todo-web`이 이미 있으면 `docker-compose.yaml`의 `container_name`을 바꾼다. |
 | `fatal: not a git repository` | `apps`가 아니라 **`cd todo`(클론한 폴더)** 안에서 실행했는지 확인한다. |
 | `git pull`이 안 되거나 안 받아짐 | 10절 순서대로 `git status`·`fetch`·`checkout main`·`pull --ff-only`, 로컬 수정·비공개 저장소 자격 확인 |
+| `ERR_SSL_VERSION_OR_CIPHER_MISMATCH` (`https://api…`) | 11-1절. 프록시 443·인증서·`proxy_pass`가 PB **HTTP** 포트로 가는지 확인 |
 
 ---