AriWeb-Suite/modules/webmaker/docs/SSL-WILDCARD.md

# 플랫폼 도메인 와일드카드 인증서 (Let's Encrypt)

AI Webmaker v1.4.14 · 2026-10-10 · 대상: 운영자

## 1. 두 종류의 인증서

| 대상 | 인증서 | 발급 방법 | 누가·언제 |
|---|---|---|---|
| 서브 도메인 사이트 `이름.ibit.kr` (플랫폼 도메인 아래 한 단계) | **와일드카드** `*.ibit.kr` — 이름 `wh-wild-ibit.kr`, 하나로 전체 | DNS 인증(TXT `_acme-challenge.ibit.kr`) | 운영자가 관리자 콘솔에서 한 번 (갱신 60~90일마다) |
| 고객 도메인 `example.com`, `www.example.com` | **사이트별** `wh-<사이트ID>` | HTTP 인증(webroot) | 발행(배포) 때 자동 (DNS 가 이 서버를 가리키는 도메인만) |

- 분리하는 이유: 서브 도메인은 수가 늘어도 인증서 하나(발급 한도 문제 없음), 고객 도메인은 사이트 폐기 때 그 인증서만 지운다.
- nginx 설정은 도메인 묶음마다 server 블록을 만든다. 와일드카드가 없으면 서브 도메인은 HTTP 로 열리고, 와일드카드를 발급하면 배포된 서브 도메인 사이트들의 설정을 **재배포 없이** 다시 써 HTTPS 가 된다.
- `a.b.ibit.kr` 처럼 두 단계 아래 이름과 `ibit.kr` 자신은 와일드카드로 덮이지 않는다(서브 도메인 등록은 한 단계만 허용하므로 해당 없음).

## 2. 조건

| 조건 | 확인 |
|---|---|
| 플랫폼 도메인 | 관리자 콘솔 › 설정 › 도메인 서비스 › 플랫폼 도메인 (webmaker 는 `ibit.kr`) |
| 기본 배포 서버가 서비스 서버 자신(종류 local)·sudo 허용·certbot 설치 | webmaker: "서비스 서버 (bear, webmaker.ibit.kr)" ✅ |
| 원격(ssh) 배포 서버 | 지원하지 않음 — 훅이 그 서버에서 실행되어 이 서비스의 DNS 접속 정보를 쓸 수 없다. 그 서버의 서브 도메인은 사이트별 인증서로 발급된다 |
| 와일드카드 DNS `*.ibit.kr A 121.152.149.45` | 인증서와 별개로 사이트가 열리려면 필요 ([DOMAIN-SETUP.md](DOMAIN-SETUP.md) 5장). 인증서 발급 자체에는 필요 없다 |
| Let's Encrypt 알림 이메일 | 설정 › SSL (비워도 발급됨) |

## 3. 발급 절차

관리자 콘솔 › 설정 › **SSL (Let's Encrypt)** › 플랫폼 도메인 와일드카드 인증서

### DNS 방식이 수동 (ibit.kr — hosting.co.kr DNS, 지금 상태)
1. **와일드카드 인증서 발급·갱신** 을 누른다.
2. 몇 초 뒤 화면에 **DNS 에 넣을 TXT 레코드** 가 뜬다.
   | 이름 | 종류 | 값 |
   |---|---|---|
   | `_acme-challenge.ibit.kr` (hosting.co.kr 화면에서는 호스트 `_acme-challenge`) | TXT | 화면의 값 (43자) |
3. hosting.co.kr 도메인 관리 › ibit.kr › DNS 레코드에 위 TXT 를 추가한다.
4. 서비스가 공용 DNS(1.1.1.1·8.8.8.8)에서 그 값을 확인하면 자동으로 인증이 이어진다(최대 40분 대기, 보통 수 분). 끝나면 상태 줄에 "인증서 있음 — *.ibit.kr, 만료 …" 가 보이고, 서브 도메인 사이트들의 nginx 설정이 HTTPS 로 바뀐다.
5. TXT 는 지워도 된다. **갱신 때(만료 30일 전부터 certbot 이 시도, 화면은 20일 전 경고)** 새 값이 다시 필요하다 — 같은 절차를 반복한다. 갱신 전에는 기존 인증서가 그대로 쓰인다.

### DNS 방식이 자동 (플랫폼 도메인 DNS 를 Openprovider 로 옮긴 뒤)
- 발급·갱신을 누르면 훅이 Openprovider API 로 TXT 를 넣고 인증 뒤 지운다. certbot 타이머의 자동 갱신도 같은 훅으로 사람 손 없이 된다.
- 조건: 설정 › 도메인 서비스 › DNS 방식 "자동(Openprovider)", 외부 연동 접속 정보에 Openprovider 등록.

## 4. 동작 원리 (코드)

- `lib/ssl.js`: 상태(`GET /api/admin/ssl`)·발급 시작(`POST /api/admin/ssl/wildcard`, 비동기)·취소. certbot 을 `--manual --preferred-challenges dns` 와 훅으로 실행한다:
  `certbot certonly --manual --manual-auth-hook "node scripts/acme-dns-hook.js auth" --manual-cleanup-hook "… cleanup" --cert-name wh-wild-<도메인> -d "*.<도메인>" --keep-until-expiring --deploy-hook "systemctl reload nginx"`
- `scripts/acme-dns-hook.js`: certbot 이 넘기는 `CERTBOT_DOMAIN`·`CERTBOT_VALIDATION` 으로 TXT 를 넣거나(Openprovider) 대기 파일(`/var/tmp/webmaker-acme/<도메인>.json`)에 적고 공용 DNS 에 보일 때까지 기다린다. 서비스는 그 파일을 읽어 화면에 보인다.
- 발급이 끝나면 `lib/ssl.js reconfigureSites` 가 그 플랫폼의 서브 도메인이 연결된 배포 사이트들의 vhost 를 다시 쓴다(`deploy.configureVhost` — 묶음별 인증서).
- 결과는 `data/ssl-wildcard.json` 에 남고, certbot 로그는 `/var/log/letsencrypt/letsencrypt.log`.

## 5. 자주 나는 메시지

| 메시지 | 원인 | 해결 |
|---|---|---|
| 플랫폼 도메인이 없습니다 | 설정 › 도메인 서비스 › 플랫폼 도메인 비어 있음 | 도메인 입력 (예: ibit.kr) |
| 와일드카드 인증서는 서비스 서버가 배포 서버인 경우(종류 local)에만 발급합니다 | 기본 배포 서버가 원격(ssh) | 서비스 서버를 기본 배포 서버로, 또는 그대로 사이트별 인증서 사용 |
| 40분 안에 TXT 가 보이지 않아 중단합니다 (마지막 발급: 실패) | DNS 에 TXT 를 넣지 않았거나 값이 다름·전파 지연 | TXT 를 확인하고 다시 "발급·갱신" (새 값이 뜬다) |
| too many certificates / rate limit | Let's Encrypt 발급 한도 (같은 이름 주 5회) | 1주일 뒤 다시. 인증서가 이미 있으면 `--keep-until-expiring` 이라 보통 발생하지 않음 |
| 서브 도메인 사이트가 발행 뒤 HTTP 로만 열림 — "운영자가 와일드카드 인증서를 발급하면 HTTPS 로 열립니다" | 와일드카드 인증서 없음 | 위 3장 절차. 발급되면 재배포 없이 HTTPS |
| 인증서 있음인데 특정 서브 도메인 사이트가 HTTP | 그 사이트의 nginx 설정이 와일드카드 전 것 | 그 사이트를 재배포하거나, 관리자 콘솔에서 "발급·갱신"(끝나면 설정을 다시 씀) |

## 6. 서버에 미리 발급해 둔 와일드카드 인증서 (v1.5.17)

서버를 설치할 때 운영자가 이미 `sudo certbot certonly … -d '*.example.com'` 으로 인증서를 받아 두었다면(이름은 무엇이든: `live/example.com`, `live/wild-example` …) 서비스가 그것을 **인지해 서브 도메인 사이트에 자동으로 쓴다**. 별도 설정은 없다.

- 감지: 배포 서버의 `/etc/letsencrypt/live/*/fullchain.pem` 을 sudo 로 훑어 SAN 에 `*.<플랫폼 도메인>` 이 있는 인증서를 고른다(`lib/deploy.js findWildcardCert`). 서비스가 발급한 `wh-wild-<도메인>` 이 있으면 그것, 없으면 만료가 가장 먼 것. 플랫폼 도메인은 설정이 없으면 서비스 공개 주소에서 유도된다(webmaker.example.com → example.com).
- 적용: 새로 발행하는 사이트는 vhost 구성 때 바로, 이미 HTTP 로 배포된 사이트는 **서비스 기동 20초 뒤** `ssl.autoApply` 가 nginx 설정을 다시 써서 HTTPS 가 된다(재배포 없음). 직접 실행: `node scripts/ssl-wildcard.js --apply`.
- 확인: 설치 점검표(초기 설정 페이지·시스템 설정 탭)의 "와일드카드 인증서 (*.도메인)" 항목, `node scripts/ssl-wildcard.js`(설치·갱신 스크립트가 마지막에 출력), 관리자 콘솔 › 설정 › SSL 상태 줄("서버에 미리 발급된 인증서 <이름> 를 씁니다").
- 갱신: 그 인증서를 받은 방법(certbot 타이머·DNS 플러그인 등)대로 이어진다. 관리자 콘솔의 "발급·갱신" 은 미리 발급된 인증서가 유효하면 409 로 거절하고(만료 20일 전부터 허용), 강제 갱신이면 서비스 이름(`wh-wild-<도메인>`)으로 따로 발급한다 — 그 뒤에는 서비스 이름이 우선한다.
- 조건: 배포 서버 종류 local 또는 ssh 모두 감지한다(ssh 는 그 서버에서 sudo 가 되어야 함). 발급(3장)은 local 만.

## 7. letsencrypt 밖의 와일드카드 인증서 (v1.5.27)

감지는 `/etc/letsencrypt/live` 외에 **nginx 설정이 참조하는 `ssl_certificate` 파일**과 **`/etc/ssl/*/*.pem|.crt`**(예: Cloudflare 원본 인증서 `/etc/ssl/cloudflare/example.pem` + `example.key`)의 SAN 도 본다. 키 파일은 같은 폴더의 `<이름>.key` / `privkey.pem` / `<이름>-key.pem` 중 있는 것이며, 키를 못 찾으면 후보에서 뺀다. 사이트 vhost 에는 그 경로가 그대로 들어간다(`ssl_certificate /etc/ssl/cloudflare/example.pem;`).
플랫폼 도메인에 인증서가 하나도 없으면(예: webmaker.ariweb.net 의 `*.ariweb.net`) 서브 도메인은 HTTP 로 열린다 — 3장 절차나 위 방법으로 받아 두면 다음 기동 때 자동 적용된다.