AriWeb-Suite/modules/webmaker/docs/DOMAIN-SETUP.md

# 도메인 서비스 준비 목록과 만드는 방법

AI Webmaker v1.4.3 · 2026-10-09 작성 · 대상: 운영자(관리자 콘솔 사용자)

빌더의 **도메인** 탭(v1.4.0)이 실제로 동작하려면 서비스 밖에서 준비할 것(계정·DNS)과 관리자 콘솔에서 넣을 값이 있다.
이 문서는 그 목록, 각 항목을 만드는 방법, 2026-10-09 기준 두 운영 서버의 상태를 정리한 것이다.
기능 설명은 [README.md](../README.md) "도메인 · 계정 종류" 절, 오류 메시지와 원인은 [ERRORS.md](../ERRORS.md) "설정·운영 안내 (v1.4.0 도메인·메일)" 표에 있다.

---

## 1. 한눈에 보기

| # | 준비할 것 | 어디서 | 필요한 기능 | webmaker.ibit.kr (bear) | 192.168.20.66 |
|---|---|---|---|---|---|
| 1 | Openprovider 리셀러 계정 + 선불 잔액 | openprovider.com | 도메인 검색·구매·갱신·DNS | ❌ 없음 | ❌ 없음 |
| 2 | Openprovider 접속 정보 등록 | 관리자 콘솔 › 설정 › 외부 연동 접속 정보 | 1 과 같음 | ❌ 미등록 | ❌ 미등록 |
| 3 | 도메인 서비스 설정 (요율·플랫폼 도메인 등) | 관리자 콘솔 › 설정 › 도메인 서비스 | 가격·서브 도메인 | ✅ 기본값 (ibit.kr, 요율 250%) | ⚠️ 플랫폼 도메인 없음 (주소가 IP) |
| 4 | 서브 도메인용 DNS (`*.ibit.kr`) | hosting.co.kr DNS 관리 | 서브 도메인 계정의 `이름.ibit.kr` | ❌ 와일드카드 없음 | — |
| 5 | 웹서버·SSL 자동 설정 조건 (80/443, sudo, certbot) | 서비스 서버 | 연결한 도메인으로 사이트 열기·HTTPS | ✅ 준비됨 | — |
| 6 | Let's Encrypt 알림 이메일 | 관리자 콘솔 › 설정 › SSL | 인증서 만료 알림 | ⚠️ 비어 있음 (발급은 됨) | — |
| 7 | 메일 발송 키 (Resend) | 관리자 콘솔 › 설정 › 외부 연동 접속 정보 | 메일(MX) 자동 설정, 보내는 메일 | ✅ 등록됨 | — |
| 8 | 메일 서버 주소 (MX 호스트) | 관리자 콘솔 › 메일 시스템 (기본값) | 메일(MX) 자동 설정 | ❌ 비어 있음 | — |
| 9 | 받는 메일 서버 (mail-gateway 연동) | mail-gateway + 이 서비스 | 받는 메일 | ❌ 연동 전 (보내기만 가능) | — |
| 10 | 회원 계정 종류·캐시 | 관리자 콘솔 › 회원·청구 | 누가 무엇을 쓸 수 있는지, 구매 대금 | ✅ 기존 회원은 자체 도메인 | ✅ |
| 11 | 바깥 인터넷 접속 (Openprovider API, 환율) | 서비스 서버 | 가격·구매 | ✅ 확인함 | — |

✅ 준비됨 · ⚠️ 동작은 하지만 손볼 것 · ❌ 없으면 그 기능이 동작하지 않음 · — 이 서버에서는 해당 없음

**최소 구성**
- 자체 도메인 판매만: 1·2·10.
- 서브 도메인까지: 3·4 추가.
- 메일(MX)까지: 7·8 추가. 받는 메일은 9.

---

## 2. Openprovider 리셀러 계정 (항목 1)

도메인 등록 기관(레지스트라) 역할을 하는 공급사다. 이 서비스는 Openprovider API v1beta(`https://api.openprovider.eu/v1beta`)로 등록 가능 여부·가격 조회, 등록·갱신, DNS 영역 관리를 한다.

**만드는 방법**
1. https://www.openprovider.com 에서 리셀러(Reseller) 계정으로 가입한다.
   - 회사 정보·담당자·주소를 넣는다.
   - 가입 후 본인·회사 확인 절차가 있을 수 있다.
2. 요금제(멤버십)를 고른다.
   - 무료 등급으로 시작할 수 있다.
   - 유료 등급은 도메인 원가가 낮아진다.
   - 사용자 가격은 원가 × 요율이므로 원가가 낮을수록 사용자 가격도 내려간다.
3. **선불 잔액(예치금)을 충전한다.**
   - 도메인을 등록·갱신할 때마다 Openprovider 잔액에서 원가가 빠져나간다.
   - 잔액이 부족하면 구매가 `도메인 서비스 오류: …` 로 실패한다. 이때 사용자 캐시는 차감되지 않는다(서비스가 등록 성공 뒤에만 차감).
4. API 로 쓸 로그인 계정을 정한다.
   - 이 서비스는 제어판 로그인과 같은 **사용자 이름·비밀번호** 로 `/auth/login` 토큰을 받는다.
   - 운영용으로 API 전용 하위 사용자(sub-user)를 따로 만들어 쓰는 것을 권장한다.
   - 그러면 사람이 비밀번호를 바꿔도 서비스가 멈추지 않는다.
5. API 접근 허용 IP 를 확인한다.
   - Openprovider 제어판의 API 설정에 허용 IP 목록이 있으면 서비스 서버의 공인 IP 를 넣는다.
   - webmaker.ibit.kr(bear)의 바깥 주소는 **121.152.149.45**.
   - 허용되지 않으면 로그인 단계에서 `Openprovider 로그인 실패 (…)` 가 난다.
6. (선택) 시험 환경.
   - 실제 구매 전에 시험하려면 Openprovider 에 시험(sandbox) 계정을 요청한다.
   - 시험 주소는 2번 단계의 "주소" 칸에 넣는다.
   - 시험 주소를 받기 전에는 아래 9번 점검 순서에서 **가장 싼 도메인 1개로만** 실제 구매를 시험한다.

> 확인함 (2026-10-09): bear 에서 `api.openprovider.eu` 로 접속이 된다(가짜 계정으로 `Authentication/Authorization Failed` 응답 = 네트워크는 정상).

---

## 3. 접속 정보 등록 (항목 2)

**관리자 콘솔 › 설정 › 외부 연동 접속 정보**

| 칸 | 넣을 값 |
|---|---|
| 종류 | **Openprovider** |
| 주소 | 비워 두면 `https://api.openprovider.eu/v1beta` (시험 계정이면 그 주소) |
| API 키 또는 토큰 | Openprovider **비밀번호** |
| 설정 (한 줄에 이름=값) | `USERNAME=<Openprovider 사용자 이름>` (필수)<br>`NS_GROUP=dns-openprovider` (선택, 기본값과 같음) |

1. **암호화해 저장** 을 누른다.
   - 비밀번호는 `data/credentials.json` 에 AES-256-GCM 으로 암호화된다.
   - 화면에는 앞뒤 몇 글자만 보이고 다시 볼 수 없다.
2. 목록의 **연결 확인** 을 누른다. 서비스가 로그인한 뒤 확장자 목록(`/tlds`)을 받아 보고 결과를 표시한다.
3. 바꿀 때는 같은 종류로 새 값을 넣고 다시 저장한다. 비밀번호 칸을 비우고 저장하면 기존 비밀번호가 유지된다.

등록 전에는 사용자 도메인 탭에 **"도메인 서비스가 아직 준비되지 않았습니다. 관리자에게 문의하세요"** 가 보인다. 이때 검색·구매는 안 되고, 서브 도메인 등록은 된다.

**NS_GROUP (네임서버 그룹)**
- 구매한 도메인은 Openprovider 네임서버 그룹으로 등록되어, 이 서비스가 그 도메인의 DNS 레코드를 직접 관리한다.
- 기본 그룹 이름은 `dns-openprovider` 이다.
- 제어판에서 자기 네임서버 그룹(화이트라벨 네임서버 등)을 만들었다면 그 이름을 넣는다.

---

## 4. 도메인 서비스 설정 (항목 3)

**관리자 콘솔 › 설정 › 도메인 서비스** — 값마다 옆의 버튼을 눌러야 저장된다.

| 값 | 의미 | 권장 (webmaker) |
|---|---|---|
| 도메인 요율 % | 사용자 가격 = Openprovider 원가 × 요율 ÷ 100 을 그날 환율로 원화로 바꿔 100원 단위로 올림. 구매·갱신 전에 사용자에게 먼저 보인다 | 250 (요구 사항) |
| 플랫폼 도메인 | 서브 도메인 계정이 쓰는 도메인 (`이름.ibit.kr`) | `ibit.kr` (기본값으로 들어 있음) |
| DNS 방식 | **수동**: 운영자가 와일드카드 레코드를 한 번 넣음 (5장)<br>**자동(Openprovider)**: 플랫폼 도메인 DNS 가 Openprovider 에 있을 때 이름별 레코드를 서비스가 만듦 | 수동 (지금 ibit.kr DNS 는 hosting.co.kr) |
| 사이트 IP | 연결한 도메인이 가리킬 서버 IP. 비우면 서비스 주소의 IP | 비워 둠 (= 121.152.149.45) |
| 판매 확장자 | 검색에 쓰는 확장자 목록 | com, net, org, co, io, shop |
| 등록 금지 이름 | 서브 도메인으로 못 쓰는 이름 (www·mail·admin 등은 기본 금지) | `board, file, matrix, office, source` 추가 권장 — 이미 쓰는 ibit.kr 이름 (webmaker 는 기본 금지) |
| 새 가입자 계정 종류 | 서브 도메인 전용 / 자체 도메인 | 서브 도메인 전용 (기본) |
| 메일 시스템도 켜기 | 메일(MX) 자동 설정 때 그 사이트의 메일 시스템을 켬 | 켬 |

**192.168.20.66**
- 서비스 주소가 IP 라 플랫폼 도메인이 비어 있다.
- 그래서 새 가입자는 자동으로 자체 도메인 계정이 되고, 서브 도메인 등록은 `플랫폼 도메인이 설정되지 않았습니다` 로 막힌다.
- 이 서버에서 서브 도메인을 쓰려면 이 서버를 가리키는 도메인을 플랫폼 도메인으로 넣는다.

> 확인함: bear 에서 환율 조회가 된다(9.5 EUR → 14,419원 → 요율 250% 적용 시 36,100원).

---

## 5. 서브 도메인용 DNS — `*.ibit.kr` (항목 4)

서브 도메인 계정은 `mycompany.ibit.kr` 같은 이름을 등록한다. 이 이름이 실제로 열리려면 DNS 가 그 이름을 서비스 서버(121.152.149.45)로 보내야 한다.

**지금 상태 (2026-10-09)**
- `ibit.kr` 의 네임서버는 **hosting.co.kr** (ns1~ns4.hosting.co.kr) 이다.
- 이름마다 A 레코드가 따로 있다: board / file / matrix / office / source / webmaker → 모두 121.152.149.45.
- **와일드카드가 없다.**
- 그래서 지금 서브 도메인을 등록하면 서비스 안에서는 등록되지만 주소가 열리지 않는다.

### 방법 A (권장, 5분) — hosting.co.kr 에 와일드카드 1줄 추가
1. hosting.co.kr 에 로그인 → 도메인 관리 → `ibit.kr` → DNS(네임서버) 레코드 관리.
2. 레코드를 추가한다.

   | 호스트(이름) | 종류 | 값 | TTL |
   |---|---|---|---|
   | `*` | A | `121.152.149.45` | 기본값(3600 등) |

3. 기존 레코드(board·file·matrix·office·source·webmaker)는 그대로 둔다. 이름이 정확히 있는 레코드가 와일드카드보다 먼저 적용된다.
4. 확인: 몇 분~몇 시간 뒤 `dig +short 아무이름.ibit.kr` 이 `121.152.149.45` 를 돌려주면 된다.
5. 관리자 콘솔 › 설정 › 도메인 서비스 의 DNS 방식은 **수동** 그대로 둔다.

- 이 방법은 서브 도메인마다 DNS 를 바꿀 필요가 없다.
- 서브 도메인의 메일(MX) 레코드는 자동으로 만들 수 없다. 도메인 탭이 넣을 레코드를 표로 보여 주므로, 메일을 쓰는 서브 도메인만 hosting.co.kr 에 직접 넣는다.

### 방법 B — ibit.kr DNS 를 Openprovider 로 옮기기 (서브 도메인 메일까지 자동)
1. Openprovider 제어판에서 `ibit.kr` DNS 영역(zone)을 만들고, **지금 있는 레코드를 모두 먼저 옮겨 적는다.** 빠뜨리면 그 서비스가 멈춘다.
   - board / file / matrix / office / source / webmaker A 레코드
   - 그 밖에 hosting.co.kr 에 있는 TXT·MX 등
2. 도메인 등록 기관(hosting.co.kr)에서 `ibit.kr` 의 네임서버를 Openprovider 네임서버로 바꾼다. 전파에 최대 48시간이 걸린다.
3. 전파가 끝나면 관리자 콘솔 › 설정 › 도메인 서비스 의 DNS 방식을 **자동(Openprovider)** 으로 바꾸고 저장한다.
4. 이후 서브 도메인을 연결하면 A 레코드를, 메일(MX) 자동 설정을 누르면 메일 레코드를 서비스가 만든다.

위험이 큰 작업(사내 서비스 전체 DNS 이전)이므로 방법 A 로 먼저 운영하고, 서브 도메인 메일 자동화가 꼭 필요할 때 B 로 옮기는 것을 권장한다.

---

## 6. 웹서버·SSL (항목 5·6)

사용자가 도메인을 사이트에 **연결** 한 뒤 **발행(또는 재배포)** 하면 서비스가 자동으로 처리한다.
- 배포 서버에 그 도메인용 nginx 설정(`/etc/nginx/sites-available/wh-<사이트ID>.conf`)을 만든다.
- DNS 가 이 서버를 가리키는 도메인에 Let's Encrypt 인증서를 발급하고 HTTP→HTTPS 로 돌린다.

| 조건 | 상태 (bear) |
|---|---|
| 바깥에서 80·443 포트가 서비스 서버로 들어옴 | ✅ (121.152.149.45 → bear nginx) |
| 서비스 계정 `master` 가 비밀번호 없는 sudo | ✅ |
| certbot 설치 | ✅ `/usr/bin/certbot` |
| 배포 서버 "서비스 서버 (bear, webmaker.ibit.kr)" 의 도메인 vhost 관리 | ✅ (연결 확인: "도메인 vhost 설정 가능") |
| Let's Encrypt 알림 이메일 | ⚠️ 비어 있음 → 관리자 콘솔 › 설정 › **SSL (Let's Encrypt)** 에 운영자 메일을 넣고 저장 (만료·문제 알림을 받기 위해) |

**주의**
- 인증서는 DNS 가 이 서버를 가리켜야 발급된다.
  - 새로 산 도메인은 위임 전파(최대 48시간)가 끝난 뒤 발행해야 HTTPS 가 붙는다.
  - 전파 중에는 서비스가 발행을 막고 "DNS 연결이 진행 중입니다 … 약 N분 후에 다시 이용해 주세요" 를 보인다.
- Let's Encrypt 는 같은 등록 도메인(ibit.kr)당 주간 인증서 발급 수에 한도가 있다.
  - 서브 도메인마다 인증서를 따로 받으므로, 하루에 수십 개를 한꺼번에 연결하면 한도에 걸릴 수 있다.
  - 많아지면 `*.ibit.kr` 와일드카드 인증서(DNS 인증 필요 — 방법 B 이후 가능)를 검토한다.

---

## 7. 메일 (항목 7·8·9)

도메인 탭의 **메일(MX) 자동 설정** 은 그 도메인 DNS 에 다음을 넣는다.
- 받는 메일 MX
- SPF·DMARC
- Resend(보내는 메일) 서명 레코드(DKIM·반송 MX·SPF)

| 준비할 것 | 만드는 방법 | 상태 (bear) |
|---|---|---|
| 메일 발송 키 (Resend) | resend.com 가입 → API Keys 에서 키 발급 → 관리자 콘솔 › 설정 › 외부 연동 접속 정보 › 종류 "메일 발송 (Resend)" | ✅ 등록됨 |
| 메일 서버 주소 (MX 호스트) | 관리자 콘솔 › **메일 시스템** 탭의 기본값에 받는 메일 서버 이름을 넣는다 (예: mail-gateway 가 설치된 `mail.arihakdang.com`). 비어 있으면 메일(MX) 자동 설정이 `메일 서버 주소(MX 호스트)가 설정되지 않았습니다…` 로 멈춘다 | ❌ 비어 있음 |
| 받는 메일 처리 (mail-gateway 연동) | mail-gateway 서버가 MX 로 받은 메일을 이 서비스의 웹메일로 넘기는 연동. 소스 연동이 아직 끝나지 않아 지금은 **보내기만** 된다(웹메일 상태 "사용 가능 (보내기)") | ❌ 연동 전 |

**서브 도메인 사용자의 메일**
- 주소는 `admin@mycompany.ibit.kr`, 웹메일은 `https://mycompany.ibit.kr/mail` 이다.
- DNS 방식이 수동이면 넣을 레코드가 표로 나오므로, 운영자가 hosting.co.kr 에 직접 넣는다(5장).

---

## 8. 회원 계정 종류·캐시 (항목 10)

- **계정 종류**: 관리자 콘솔 › 회원·청구 › 회원 행의 선택 상자에서 고르고 **변경** 을 누른다.
  - **서브 도메인 전용**: `이름.ibit.kr` 검색·등록·연결·해제만 할 수 있다.
  - **자체 도메인**: 구매·갱신·DNS 관리를 할 수 있다.
  - 1.4.0 이전 회원과 관리자는 자체 도메인 계정이다.
- **캐시**:
  - 구매·갱신 금액은 사용자 캐시에서 차감된다.
  - 잔액이 모자라면 `캐시가 부족합니다 (필요 …, 잔액 …)` 로 구매 전에 막힌다. 회원·청구 탭에서 충전한다.
  - 표시 단위는 설정 › 캐시 표시 단위(v1.4.1). 1 단위 = 1원.
- **등록자 정보**:
  - 사용자가 처음 구매할 때 도메인 탭 › 등록자 정보(영문 이름·주소·전화·이메일)를 한 번 저장해야 한다.
  - 저장할 때 Openprovider 에 고객(handle)이 만들어지므로, 항목 1·2 가 준비된 뒤에만 보인다.

---

## 9. 준비 후 점검 순서

1. 외부 연동 접속 정보 › Openprovider › **연결 확인** → 성공.
2. 자체 도메인 계정으로 빌더 › 도메인 탭 › 아무 이름 **검색** → 확장자별 "구매 가능 / 사용 중" 과 원화 가격이 보이는지.
3. 가격 확인: 표시 가격 ≈ Openprovider 제어판의 원가 × 환율 × 요율(2.5). 다르면 요율·환율 설정 확인.
4. 등록자 정보 저장 → "저장했습니다".
5. **실제 구매 1회**: 가장 싼 확장자로 시험용 도메인 1개(예: 1년 `.com`).
   - 확인 창의 금액·잔액을 보고 구매한다.
   - 사용자 캐시 차감, Openprovider 잔액 차감, 내 도메인 목록에 "DNS 연결이 진행 중" 이 보이는지 확인한다.
6. DNS 레코드 열기 → `@`·`www` A 레코드(121.152.149.45)가 있는지. TXT 레코드 하나를 추가·삭제해 본다.
7. 사이트에 연결 → 관리 탭에서 발행. 전파 전에는 발행이 막히고 남은 시간이 보인다. 전파 후 발행하면 `https://도메인/` 이 열리는지(SSL 포함).
8. (항목 8 준비 후) 메일(MX) 자동 설정 → 레코드 생성 → 웹메일 상태가 "메일시스템 설정중" → "사용 가능 (보내기)" 로 바뀌는지.
9. 서브 도메인 계정(새로 가입한 계정)으로 `시험이름.ibit.kr` 중복 확인·등록·사이트 연결 → 발행 → `https://시험이름.ibit.kr/` 이 열리는지(항목 4 필요).

---

## 10. 자주 나는 메시지

| 메시지 | 원인 | 해결 |
|---|---|---|
| 도메인 서비스가 아직 준비되지 않았습니다 | Openprovider 접속 정보 없음 | 3장 |
| Openprovider 로그인 실패 (…) | 사용자 이름·비밀번호 틀림, 허용 IP 아님 | 2장 4·5, 3장 |
| 도메인 서비스 오류: … (구매·갱신 때) | Openprovider 잔액 부족, 그 확장자의 추가 요구 정보 등 | Openprovider 제어판에서 잔액·주문 기록 확인 |
| 먼저 등록자 정보(…)를 저장하세요 | 사용자가 등록자 정보 미입력 | 도메인 탭 › 등록자 정보 |
| 캐시가 부족합니다 (…) | 사용자 캐시 < 가격 | 회원·청구에서 충전 |
| 가격이 바뀌었습니다 (… → …) | 확인 창을 연 사이 원가·환율 변동 | 새 금액 확인 후 다시 구매 |
| 플랫폼 도메인이 설정되지 않았습니다 | 플랫폼 도메인 비어 있음 (66 은 기본) | 4장 |
| 서브 도메인을 등록했는데 주소가 안 열림 | `*.ibit.kr` 와일드카드 없음 | 5장 방법 A |
| 메일 서버 주소(MX 호스트)가 설정되지 않았습니다 | 메일 시스템 기본 MX 호스트 비어 있음 | 7장 |
| 메일 발송(Resend) 도메인을 준비하지 못했습니다 | Resend 키 없음·틀림 | 7장 |
| DNS 연결이 진행 중입니다 … 약 N분 후에 다시 이용해 주세요 | 정상 — 위임(최대 48시간)·레코드 전파 중 | 기다리면 자동으로 풀림 |