diff --git a/docs/deploy.md b/docs/deploy.md index 8dd1ff8..f75c134 100644 --- a/docs/deploy.md +++ b/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**을 본다. diff --git a/docs/nas-deploy-guide.md b/docs/nas-deploy-guide.md index 87f3dde..b0f9a39 100644 --- a/docs/nas-deploy-guide.md +++ b/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://:42917`처럼 **평문 HTTP**로 PocketBase에 넘기는 구조가 일반적이다. + +이 오류는 **브라우저↔443 구간**에서 TLS 협상이 깨질 때 난다. 앱·Compose 코드 문제라기보다 **프록시·인증서·포트** 쪽을 본다. + +1. **PocketBase 자체 확인** + 브라우저에서 `http://: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** 포트로 가는지 확인 | ---