TLS 인증서 및 HTTPS

HTTPS는 패스키, OIDC 콜백 및 대부분의 인터넷 서비스를 위한 기본 요소입니다. 인증서는 방문자가 실제로 사용하는 인증 Host와 서비스 Host를 포함합니다. 내부 주소나 이전 도메인에만 인증서를 발급하면 게이트웨이에서 여전히 브라우저 경고나 로그인 실패가 발생합니다.

페이지 구성 및 인증서 출처

SSL/HTTPS는 다음 세 개의 탭으로 구성됩니다.

탭	관리 항목
인증서 설정	현재 HTTPS 상태, 게이트웨이 배포 모드, 수동 업로드 및 인증서 라이브러리
자체 서명된 인증서	로컬 루트 CA와 해당 CA에서 발급한 도메인 / IP 서버 인증서
ACME 인증서 / DNS-01 인증서	여러 발급 신청, 발급, 갱신, 로그 및 인증서 라이브러리 연결

출처	적합한 환경	주의 사항
기존 인증서 업로드	CDN, 관리 패널 또는 다른 도구에서 인증서를 이미 발급함	인증서 체인과 개인 키를 함께 보관하고 갱신 담당을 기록
자체 서명 인증서	LAN 테스트 또는 임시 확인	클라이언트에서 직접 신뢰하도록 설정해야 하므로 일반 인터넷 접근에는 부적합
ACME	검증 가능한 도메인이 있고 자동 갱신을 원함	현재 발급 절차는 DNS-01을 사용하므로 DNS API 자격 증명을 보호해야 함

인증서 라이브러리 및 수동 업로드

업로드 영역에는 PEM 인증서와 개인 키를 직접 붙여넣을 수 있습니다. 공유 디렉터리를 지원하는 플랫폼에서는 공유 파일에서도 읽을 수 있습니다. 인증서와 개인 키가 서로 일치해야 하며 인증서 체인에는 서버 인증서와 필요한 중간 인증서가 포함됩니다.

저장할 때는 다음 두 가지 작업을 선택할 수 있습니다.

작업	결과
라이브러리에만 저장	검증 후 라이브러리에 저장하며 현재 외부 제공 인증서는 바꾸지 않음
저장 및 활성화	라이브러리에 저장하고 현재 활성 / 기본 폴백 인증서로 설정한 뒤 즉시 게이트웨이와 동기화

인증서 라이브러리에는 출처, 적용 도메인, 유효 기간, 업데이트 시각 및 Host 적용 상태가 표시됩니다. 사용 중인 인증서를 삭제하면 HTTPS도 함께 비활성화됩니다. 인증서 라이브러리 지우기는 모든 인증서와 게이트웨이가 이미 받은 인증서 세트를 지우고 HTTPS를 비활성화합니다. HTTPS만 잠시 끄려면 상태 카드의 HTTPS 비활성화를 사용합니다. 인증서는 라이브러리에 그대로 남습니다.

단일 활성 인증서 및 다중 인증서 SNI

인증서 라이브러리에는 여러 인증서를 보관할 수 있으며 배포 모드 및 게이트웨이 동기화에서 게이트웨이가 실제로 받을 인증서 수를 결정합니다.

배포 모드	게이트웨이 동작	적합한 환경
단일 활성 인증서	현재 활성 인증서만 전송하며 모든 도메인에 같은 인증서를 반환	하나의 와일드카드 또는 SAN 인증서로 모든 Host를 포함
다중 인증서 SNI	전체 인증서 세트를 전송하고 TLS SNI에 따라 도메인의 인증서를 선택	서로 다른 상위 도메인이나 출처의 인증서를 하나의 게이트웨이에서 함께 사용

다중 인증서 SNI에서도 기본 / 폴백 인증서가 하나 필요합니다. 클라이언트가 SNI를 보내지 않거나 알 수 없는 Host에 접근하거나 일치하는 인증서가 없으면 게이트웨이는 기본 인증서를 반환합니다. 인증서 배포 모드를 전환한 뒤에는 페이지의 “현재 게이트웨이에서 받은 인증서”를 확인합니다. 저장된 모드와 실행 모드가 다르거나 동기화 오류가 있다면 인증서 라이브러리 내용만 보고 적용 여부를 판단하면 안 됩니다.

서브도메인 환경에서는 인증 Host와 외부에 공개하는 모든 서비스 Host를 포함합니다. 와일드카드 *.example.com은 한 단계의 서브도메인만 포함하며 루트 도메인 example.com이나 a.b.example.com은 포함하지 않습니다. 페이지의 Host 적용 범위 분석은 현재 매핑을 함께 확인해 누락된 항목을 표시합니다.

외부 도구에서 인증서 받기

인증서 설정 → 외부 인증서 받기를 사용하면 인증서 발급과 갱신은 Certd, acme.sh, lego 또는 Certbot이 담당하고 전체 인증서 체인과 개인 키는 fn-knock으로 푸시할 수 있습니다. 이 엔드포인트가 CA에 인증서를 신청하지는 않습니다. fn-knock은 배포 요청을 인증하고 인증서를 검증해 라이브러리에 저장하며, 필요한 경우 게이트웨이를 업데이트합니다.

다음 환경에 적합합니다.

• Certd에서 여러 도메인, VPS, NAS 또는 CDN 인증서를 이미 중앙 관리함
• DNS API 자격 증명을 fn-knock에 중복 저장하지 않고 기존 acme.sh, lego 또는 Certbot 갱신 작업을 유지하려 함
• 발급한 인증서 하나를 여러 fn-knock 인스턴스에 배포해야 함
• fn-knock 호스트에서 DNS-01을 직접 실행할 수 없지만 내부 네트워크의 인증서 푸시는 받을 수 있음

동작 모델

전체 배포는 다음 순서로 진행됩니다.

1. 외부 도구가 CA에서 인증서를 발급하거나 갱신합니다.
2. 발급이 성공하면 Webhook 또는 deploy hook이 fullchain과 개인 키를 바인딩 전용 주소로 보냅니다.
3. fn-knock은 해당 바인딩의 Bearer Token으로 인증하고 요청 크기, PEM, 전체 인증서 체인, 유효 기간 및 인증서/개인 키 일치를 확인합니다.
4. 인증서는 고정 슬롯 external_<binding_id>에 저장됩니다. 이후 갱신은 같은 라이브러리 레코드를 교체하므로 매번 인증서가 추가되지 않습니다.
5. 해당 인증서가 현재 사용 중이면 활성/기본 역할을 유지한 채 게이트웨이를 즉시 업데이트합니다. 활성 인증서가 아니라면 기존 기본 인증서를 차지하지 않습니다. 다중 인증서 SNI 모드에서는 전체 인증서 세트를 다시 동기화합니다.
6. 게이트웨이 동기화가 성공하면 엔드포인트에 최근 수신 시각, 도메인 및 만료 시각이 표시됩니다. 동기화에 실패하면 비 2xx 응답을 반환하고 fn-knock은 이전 설정 복원을 시도합니다. 외부 도구는 이 배포를 실패로 기록하고 자체 정책에 따라 재시도해야 합니다.

fn-knock에 현재 인증서가 하나도 없으면 외부 엔드포인트에서 처음으로 받은 인증서가 자동으로 활성화되어 게이트웨이에 배포됩니다. 이미 다른 현재 인증서가 있으면 새 엔드포인트의 첫 푸시는 인증서 라이브러리에만 추가됩니다. 공개 기본 인증서를 교체하려면 라이브러리에서 직접 활성화합니다.

도구	fn-knock에서 생성하는 구성	실행 시점
Certd	PUT Webhook URL, Header, JSON 템플릿 및 성공 표시	Certd 인증서 파이프라인에 “Webhook 방식으로 인증서 배포” 단계 추가
acme.sh	URL과 Token이 포함된 deploy hook 스크립트	발급 후 --deploy-hook fnknock 실행
lego	lego v5 deploy hook 및 v4 renew hook과 호환되는 스크립트	갱신 명령이나 .lego.yaml에서 호출
Certbot	RENEWED_LINEAGE를 읽는 deploy hook 스크립트	renewal hook 디렉터리에 두거나 certbot renew --deploy-hook으로 호출

인증서 수신 엔드포인트 만들기

1. SSL 인증서 → 인증서 설정을 열고 외부 인증서 받기를 펼칩니다.
2. 인증서 도구에서 Certd, acme.sh, lego 또는 Certbot을 선택합니다.
3. Certd example.com 또는 Certbot gateway-01처럼 인증서나 대상 노드를 구분할 이름을 입력합니다.
4. 수신 엔드포인트 만들기를 클릭합니다.
5. 생성된 구성을 즉시 모두 복사합니다. Token은 엔드포인트 생성 또는 Token 재생성 직후 한 번만 표시되며 구성 영역을 닫은 뒤에는 다시 읽을 수 없습니다.

엔드포인트 하나는 고정 인증서 슬롯 하나와 독립 Token 하나를 가집니다. 서로 관계없는 인증서를 같은 엔드포인트로 보내면 나중 푸시가 이전 인증서를 교체합니다. 여러 fn-knock 인스턴스도 Token을 공유하지 말고 각 인스턴스에 엔드포인트를 만듭니다.

공용, LAN 또는 루프백 엔드포인트 선택

푸시 엔드포인트는 HTTPS 인증 Host를 통한 공용 URL, 명시적으로 허용한 RFC1918 주소와 게이트웨이 포트를 쓰는 LAN HTTPS, 같은 호스트 도구용 루프백 호환 URL을 제공합니다. 다른 장치나 클라우드는 관리 포트를 열지 않는 /__certificates__/<BINDING_ID> 공용 경로를 권장합니다. LAN은 비루프백 리스너와 기본 인증서가 필요하며 최대 16개 IPv4를 허용합니다. IP와 기본 인증서 이름이 다를 때의 -k는 선택한 LAN에만 사용하고 공용 경로에는 사용하지 마세요.

모든 엔드포인트는 같은 바인딩 Token과 검증을 사용합니다. Token은 임의 SAN을 배포하고 같은 SAN의 기존 인증서를 인수할 수 있으므로 인증서 관리자 자격 증명으로 취급하고 노출 시 즉시 교체하세요.

루프백 호환 엔드포인트와 BACKEND_PORT

생성되는 기본 URL은 다음과 같습니다.

http://127.0.0.1:7998/api/integrations/certificates/<BINDING_ID>

포트는 fn-knock 런타임의 BACKEND_PORT에서 가져오며 7998은 기본값일 뿐입니다. 관리 백엔드는 기본적으로 127.0.0.1과 ::1에서만 수신하므로 인증서 도구와 fn-knock이 같은 호스트 또는 네트워크 네임스페이스에 있을 때만 이 주소를 직접 사용할 수 있습니다.

이 호환 URL은 같은 호스트나 네트워크 네임스페이스에서만 사용합니다. 호스트 루프백은 격리 컨테이너 내부를 가리키지 않습니다. 다른 장치에서는 공용 인증 Host 또는 명시적으로 켠 LAN 엔드포인트를 사용하고 BACKEND_PORT를 공개하지 마세요. Token을 URL, Query String, Access Log 또는 디버그 출력에 기록하지 마세요.

Certd Webhook 설정

Certd 엔드포인트를 만든 뒤 fn-knock에 표시된 필드를 해당 Certd 인증서 파이프라인에 복사합니다.

1. 파이프라인에 도메인 인증서를 성공적으로 출력하는 발급 작업이 있는지 확인합니다.
2. 발급 작업 다음에 Webhook 방식으로 인증서 배포 단계를 추가합니다.
3. 도메인 인증서에는 앞 발급 작업의 출력 인증서를 선택하고 관계없는 인증서를 선택하지 않습니다.
4. 아래 표대로 배포 값을 입력한 뒤 파이프라인을 저장합니다.

Certd 필드	값	설명
작업 이름	fn-knock으로 인증서 푸시	대상 노드 이름을 포함할 수 있음
Webhook URL	fn-knock에 표시된 푸시 URL	도구 위치에 따라 공용 HTTPS, LAN HTTPS 또는 루프백 선택
요청 방식	PUT	POST로 변경하지 않음
ContentType	application/json	Certd가 JSON으로 전송하도록 설정
Headers	Authorization=Bearer fnk_cert_<YOUR_TOKEN>	Certd의 이 입력란은 key=value 형식이며 전체 Token은 fn-knock에서 복사
메시지 Body 템플릿	{"cert":"${crt}","key":"${key}"}	${crt}는 전체 인증서 내용이고 ${key}는 개인 키
인증서 검증 무시	일반적으로 끔	HTTP에는 검증할 TLS 인증서가 없고, HTTPS 역방향 프록시는 가능하면 신뢰 체인을 수정
성공 판정	"success":true	응답 상태도 2xx여야 하며 비 2xx는 실패로 처리

이미지의 <BINDING_ID>와 fnk_cert_<YOUR_TOKEN>은 문서용 자리표시자이므로 그대로 사용할 수 없습니다. 생성하거나 Token을 교체한 엔드포인트에서 실제 값을 복사합니다. Header는 Authorization=Bearer ...이며 일반 HTTP 문서의 콜론 표기 Authorization: Bearer ...가 아닙니다. 이 Certd 입력란은 각 줄에 key=value 형식을 요구합니다.

저장 후 Certd 파이프라인을 한 번 직접 실행합니다. Webhook 단계만 실행하려면 앞 작업의 인증서 출력을 읽을 수 있는지 먼저 확인합니다. 성공하면 Certd 단계가 성공으로 표시되고 fn-knock은 "success":true가 포함된 JSON을 반환하며 엔드포인트의 최근 수신 상태를 업데이트합니다.

acme.sh, lego 또는 Certbot 사용

이 세 도구에서는 JSON을 직접 만들 필요가 없습니다. 도구를 선택해 엔드포인트를 만들면 fn-knock이 푸시 URL과 Token이 포함된 스크립트를 생성합니다. 스크립트는 jq로 PEM 줄바꿈을 안전하게 JSON으로 만들고 curl로 요청합니다. 파일 권한을 제한하고 CI 로그에 스크립트 내용을 출력하지 않습니다.

acme.sh

1. 생성된 스크립트를 ~/.acme.sh/deploy/fnknock.sh로 저장합니다.
2. chmod 700 ~/.acme.sh/deploy/fnknock.sh를 실행합니다.
3. 발급 성공 뒤 다음 명령으로 배포합니다.

~/.acme.sh/acme.sh --deploy -d example.com --deploy-hook fnknock

스크립트는 acme.sh deploy hook이 전달하는 개인 키와 fullchain 인자를 사용합니다. 와일드카드 인증서는 acme.sh에 등록된 해당 인증서의 주 도메인을 지정합니다. --deploy는 기존 발급 결과를 배포하며 새 인증서를 신청하는 명령이 아닙니다.

lego

1. 생성된 스크립트를 고정 경로에 저장하고 chmod 700 /path/to/fn-knock-lego-hook.sh를 실행합니다.
2. lego v5에서는 다음 명령을 사용합니다.

lego --deploy-hook=/path/to/fn-knock-lego-hook.sh renew

.lego.yaml의 hooks.deploy.command에도 설정할 수 있습니다. lego v4에서는 --renew-hook=/path/to/fn-knock-lego-hook.sh를 사용합니다. 생성 스크립트는 v5 LEGO_HOOK_* 변수와 v4 호환 변수를 모두 인식합니다.

Certbot

1. 생성된 스크립트를 /etc/letsencrypt/renewal-hooks/deploy/fn-knock에 저장합니다.
2. chmod 700 /etc/letsencrypt/renewal-hooks/deploy/fn-knock를 실행합니다.
3. 테스트하거나 Hook을 직접 지정합니다.

certbot renew --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/fn-knock

스크립트는 Certbot의 RENEWED_LINEAGE에서 fullchain.pem과 privkey.pem을 읽습니다. deploy hook은 갱신 성공 뒤에만 실행됩니다. 테스트할 때는 Certbot이 제공하는 절차를 사용하고 Staging 인증서가 운영 인증서로 푸시되지 않는지 확인합니다.

첫 푸시, 갱신 및 배포 역할

푸시 전 상태	fn-knock 동작
현재 인증서 없음	고정 외부 인증서 레코드를 만들고 현재 인증서로 자동 설정한 뒤 게이트웨이 동기화
단일 활성 인증서 모드에서 다른 현재 인증서가 있음	새 인증서를 라이브러리에 추가하지만 공개 인증서는 변경하지 않음
이 엔드포인트 인증서가 이미 현재 인증서임	같은 레코드를 교체하고 현재 역할을 유지한 채 게이트웨이 업데이트
다중 인증서 SNI 모드	엔드포인트 인증서를 교체하고 전체 세트를 다시 동기화하며 기존 기본 항목은 유지
완전히 같은 인증서와 개인 키를 다시 푸시	멱등 성공하며 라이브러리에 다시 쓰거나 불필요한 게이트웨이 재로드를 하지 않음
새 인증서 만료가 슬롯의 기존 인증서보다 빠름	이전 인증서로 잘못 롤백하는 것을 막기 위해 409 Conflict 반환

fn-knock은 인증서 체인의 순서와 서명, 중간 인증서의 CA/Key Usage, 체인 내 모든 인증서의 시작 및 만료 시각, 리프 인증서와 개인 키 일치를 검증합니다. 필수 중간 인증서가 없거나 순서가 잘못된 체인, 아직 유효하지 않거나 만료된 인증서, 일치하지 않는 키는 거부됩니다. Request Body 상한은 1 MiB입니다.

인증서 출처는 외부 푸시로 기록되고 source_provider로 Certd, acme.sh, lego 및 Certbot을 구분합니다. 상태와 로그에는 바인딩, 결과, Fingerprint, 도메인 및 유효 기간만 기록하며 PEM 개인 키나 평문 Token은 기록하지 않습니다.

배포 성공 확인

푸시 뒤 다음 순서로 확인합니다.

1. 외부 도구에서 인증서 발급뿐 아니라 배포 작업도 성공했는지 확인합니다.
2. fn-knock 엔드포인트가 수신 중과 최근 수신 성공을 표시하고 도메인, 최근 수신 시각 및 만료 시각이 올바른지 확인합니다.
3. 라이브러리에 해당 엔드포인트용 외부 인증서가 하나만 있고 다음 갱신 뒤에도 개수가 늘지 않는지 확인합니다.
4. 공개할 인증서라면 현재/기본 인증서인지 또는 다중 인증서 SNI 게이트웨이 세트에 포함되었는지 확인합니다.
5. 실제 접속 경로에서 게이트웨이가 반환하는 인증서를 확인합니다.

openssl s_client \
  -connect auth.example.com:443 \
  -servername auth.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

최근 수신 성공은 fn-knock이 이번 내용을 수락했다는 뜻입니다. 실제 공개 인증서인지는 활성 역할, 배포 모드 및 인터넷 트래픽이 이 게이트웨이에 도착하는지에 따라 달라집니다.

엔드포인트 및 Token 관리

• 수신 일시 중지: 엔드포인트와 기존 인증서는 유지하지만 새 푸시는 사용할 수 없게 합니다.
• 새 Token 생성: 이전 Token은 즉시 무효가 되고 새 Token은 한 번만 표시됩니다. Certd 또는 deploy hook 스크립트를 갱신하지 않으면 401을 받습니다.
• 이름 저장: 표시 이름만 바꾸며 인증서 슬롯, URL, Token 및 저장된 인증서는 바뀌지 않습니다.
• 엔드포인트 삭제: URL과 Token을 취소하지만 가져온 인증서는 기본적으로 유지하여 사용 중 HTTPS가 끊기지 않게 합니다. 인증서가 필요 없으면 라이브러리에서 별도로 삭제합니다.

Token은 바인딩 하나의 인증서 슬롯에 배포할 권한만 제공합니다. /api/admin/ssl/*을 호출하거나 다른 바인딩을 조작할 수 없습니다. 자동화에 관리 세션 Cookie를 사용하지 않습니다.

여러 fn-knock 인스턴스

Certd에서 여러 VPS 또는 NAS로 배포할 때는 각 fn-knock에서 엔드포인트를 만들고 인스턴스마다 독립 배포 단계를 추가합니다.

인증서 발급/갱신
├── fn-knock gateway-01로 푸시(독립 URL + Token)
├── fn-knock gateway-02로 푸시(독립 URL + Token)
└── CDN 또는 다른 서비스로 푸시

이렇게 하면 Token 하나의 유출, 접근할 수 없는 노드 또는 게이트웨이 동기화 실패가 모든 노드의 공용 자격 증명 문제로 확대되지 않습니다. Certd에서 각 배포 단계 결과를 따로 기록하고 래퍼 스크립트가 일부 노드 실패를 숨기지 않게 합니다.

외부 푸시 문제 해결

HTTP 상태	일반적인 원인	해결 방법
400 Bad Request	잘못된 JSON/PEM, 불완전하거나 순서가 틀린 체인, 키 불일치, 아직 유효하지 않거나 만료된 인증서	fullchain과 일치하는 개인 키를 보내고 Certd의 ${crt}/${key} JSON 템플릿 유지
401 Unauthorized	Token 누락, 복사 오류, 교체된 Token 또는 잘못된 Certd Header 형식	fn-knock에서 Token을 다시 생성하고 Authorization=Bearer ...를 완전히 업데이트
404 Not Found	바인딩이 삭제/일시 중지되었거나 URL의 바인딩 ID가 없음	엔드포인트 상태와 전체 경로를 확인하고 다른 인스턴스 URL을 재사용하지 않음
409 Conflict	새 인증서가 기존 인증서보다 먼저 만료되거나 동시 변경을 안전하게 저장할 수 없음	파이프라인이 이전 결과물을 보내지 않는지 확인하고 같은 엔드포인트 동시 쓰기를 피한 뒤 재시도
413 Payload Too Large	JSON Body가 1 MiB 초과	로그, PKCS#12, 중복 인증서 또는 관계없는 내용이 PEM에 포함되지 않았는지 확인
500 Internal Server Error	구성 또는 배포 상태 저장 실패	fn-knock 로그와 디스크/구성 저장소를 확인하고 외부 작업은 실패로 유지한 채 재시도
502 Bad Gateway	검증 뒤 게이트웨이 동기화 실패. 이전 설정 복원 확인 여부가 응답에 표시됨	현재 공개 인증서를 확인하고 게이트웨이 상태와 fn-knock 로그를 점검한 뒤 재시도

Certd에서 발급은 성공했지만 fn-knock이 첫 푸시 대기 중이면 배포 단계가 실행되지 않았거나 Webhook에 접근할 수 없거나 잘못된 앞 단계 인증서 출력을 선택한 것입니다. Certd 작업 로그에서 요청이 실제 전송되었는지 확인한 뒤 같은 호스트의 127.0.0.1:${BACKEND_PORT} 또는 다른 호스트용 역방향 프록시 경로를 확인합니다.

자체 서명 루트 CA

자체 서명된 인증서는 다음 순서로 사용합니다.

1. 루트 인증서를 초기화하고 루트 CA를 다운로드합니다.
2. 접근에 사용할 모든 클라이언트나 관리 대상 기기에 루트 CA를 신뢰할 수 있는 루트 인증서로 설치합니다.
3. 도메인 및 IP 목록에 실제 접속 이름을 추가합니다.
4. 배포를 클릭해 서버 인증서를 발급하고 설치하거나 서버 인증서를 다운로드해 직접 사용합니다.

서버 인증서의 유효 기간은 20년입니다. 유효 기간이 길다고 해서 개인 키 보호나 폐기 계획을 무시해도 되는 것은 아닙니다. 루트 CA를 재생성하거나 지우면 기존 루트 CA에서 발급한 서버 인증서를 더 이상 신뢰할 수 없으므로 화면에서 두 번 확인을 요구합니다. 실행 전에 새 루트 인증서 배포와 롤백 방안을 준비합니다.

자체 서명 인증서는 통제된 LAN, 테스트 기기 또는 루트 인증서를 일괄 배포할 수 있는 환경에 적합합니다. 인터넷 방문자, 서드파티 OIDC 및 관리되지 않는 클라이언트에는 일반적으로 공개적으로 신뢰받는 CA를 사용합니다.

ACME 발급 신청

Windows 이외의 플랫폼에서 처음 사용할 때는 먼저 시스템 설정 → ACME에서 acme.sh를 초기화하고 필요에 따라 기본 CA를 선택합니다. CA를 전환해도 이후 발급 신청과 자동 갱신에만 영향을 주며 이미 발급되거나 배포된 인증서를 즉시 교체하지는 않습니다.

각 ACME 발급 신청은 다음 항목을 독립적으로 저장합니다.

• 이름과 하나 이상의 도메인
• DNS 제공자 및 해당 신청에서 사용하는 API 자격 증명
• 자동 갱신 스위치
• 현재 인증서, 인증서 라이브러리 연결 및 최근 작업 상태

저장은 발급 신청 설정만 수정하며 저장 후 발급 신청은 발급 작업을 즉시 제출합니다. 발급에 성공하면 인증서가 인증서 라이브러리에 자동으로 동기화되지만 반드시 현재 인증서가 되는 것은 아닙니다. 단일 활성 모드에서는 현재 인증서로 설정을 추가로 실행할 수 있고, 다중 인증서 SNI 모드에서는 게이트웨이 인증서 세트에 포함되었는지 확인합니다.

같은 발급 신청을 갱신하거나 재발급할 때는 이미 연결된 인증서 라이브러리 레코드를 제자리에서 교체하고 기존 레이블과 활성 / 기본 배포 역할을 유지해 인증서가 중복으로 추가되지 않도록 합니다. 도메인을 수정한 뒤 발급 작업이 실패하거나 중지되면 이전에 사용할 수 있던 발급 결과를 보존합니다. 새 인증서를 게이트웨이에 전송하지 못하면 이전 SSL 설정을 복원해 다시 전송합니다. 그 사이 더 최신 설정이 동시에 저장되었다면 해당 설정을 보존해 전송합니다. 작업 자체는 계속 실패로 종료되므로 로그에서 이전 설정을 복원했는지, 최신 설정을 보존했는지 또는 보안 설정도 복구하지 못했는지 확인합니다.

발급 신청 메뉴에서는 작업 로그 보기, 인증서 다운로드, 인증서 라이브러리 수동 업데이트, 배포, 인증서 삭제 또는 발급 신청 삭제를 실행할 수 있습니다. 두 삭제 작업의 범위는 다음과 같이 다릅니다.

작업	보존되는 내용
인증서 삭제	발급 신청 설정은 유지하고 현재 저장된 발급 결과와 인증서 라이브러리 연결을 제거
발급 신청 삭제	발급 신청 설정을 삭제하며 기존 인증서와 연결도 함께 정리

작업이 실행 중이거나 자동 갱신 중이어도 발급 신청의 DNS 설정은 편집하고 저장할 수 있습니다. 다른 발급, 배포, 삭제처럼 현재 작업과 충돌하는 작업은 계속 잠깁니다. 작업 로그에서는 DNS 자격 증명, DNS API 요청 한도 또는 ACME 빈도 제한 등의 원인을 안내합니다. 작업 중지는 먼저 취소를 요청하고 해당 작업이 소유한 프로세스 그룹을 종료합니다. 실행기와 런타임 잠금이 모두 끝난 뒤에만 성공으로 표시됩니다. 페이지에 PID나 중지 오류가 남아 있으면 두 번째 작업을 즉시 시작하지 말고 이전 프로세스가 종료되었는지 먼저 확인합니다.

자동 갱신 일정 및 복구

자동 갱신을 활성화한 발급 신청은 서비스 시작 직후 확인되며 이후 기본적으로 6시간마다 스캔됩니다. 인증서 만료까지 30일 이하가 남으면 갱신 대기열에 들어갑니다. 여러 신청이 대상이면 만료가 가까운 순서대로 직렬 처리하여 DNS API와 ACME 클라이언트를 동시에 호출하지 않습니다.

• 자동 스캔과 개별 발급 작업은 소유권과 하트비트가 있는 별도의 런타임 잠금을 사용하므로 같은 서비스에서 중복 갱신이 실행되지 않습니다. 수동 작업이 이미 실행 중이면 해당 스캔은 안전하게 건너뜁니다.
• 서비스 재시작 후 새 프로세스에 실행기가 없는 queued/running 작업은 중지됨으로 복구하고 남은 런타임 잠금을 정리한 뒤 다시 스캔합니다. 프로세스 안에서 취소 중인 작업은 기존 실행기가 끝날 때까지 잠금을 유지하여 이전 작업과 새 작업이 겹치지 않게 합니다.
• RFC 3339와 기존 인증서에 흔히 사용되는 OpenSSL UTC 만료 시간을 모두 인식합니다. 만료 시간을 해석할 수 없으면 경고를 남기고 건너뛰며 ‘갱신 불필요’로 잘못 판단하지 않습니다.
• 각 스캔이 끝나면 인증서 라이브러리와 게이트웨이 배포를 다시 조정합니다. 한 번의 갱신 실패가 이후 예약 스캔을 막지 않으며 이전에 사용 가능했던 인증서와 SSL 설정은 앞 절의 복구 규칙에 따라 보존됩니다.
• 자동 갱신이 실패하거나 중지되면 기본적으로 6시간 재시도 백오프를 적용하여 매 스캔마다 DNS API와 CA를 즉시 다시 호출하지 않습니다. 해당 발급 신청을 편집하면 다음 스캔에서 다시 시도할 수 있습니다.

페이지에는 별도의 ‘다음 스캔 시간’ 스위치가 없습니다. 수동 신청을 반복하지 말고 발급 신청의 최근 작업 상태, 인증서 만료 시간 및 로그로 성공 여부를 확인합니다.

Windows 네이티브 버전: DNS-01 인증서

Windows x86_64 버전에서는 SSL/HTTPS → DNS-01 인증서에서 인증서를 신청합니다. 설치 패키지에 인증서 클라이언트가 내장되어 있어 ACME.sh를 초기화하거나 다운로드할 필요가 없습니다. 이 경로는 Let's Encrypt만 사용하고 DNS-01 검증만 허용하며 HTTP-01이나 다른 인증 기관으로 전환하는 기능은 제공하지 않습니다.

페이지에서 지원되는 DNS 제공자를 선택하고 최소 권한의 API 자격 증명을 저장합니다. 현재 Alibaba Cloud DNS, Baidu Cloud DNS, Cloudflare, DNSPod, Tencent Cloud DNSPod, DuckDNS, Dynu, dynv6, GoDaddy, Huawei Cloud DNS 및 Porkbun을 지원합니다. Cloudflare는 API 토큰과 Global API Key 방식의 자격 증명을 모두 지원하며 특정 Zone으로 제한한 토큰을 우선 사용합니다.

새 발급 신청은 기본적으로 자동 갱신을 활성화하며 발급에 성공하면 인증서 라이브러리에 추가됩니다. 단일 활성 인증서 모드에서는 처음 발급한 뒤에도 현재 인증서로 직접 설정합니다. Windows 페이지에서는 acme.sh 초기화가 필요하지 않으며 CA 전환도 제공하지 않습니다.

fnOS SSL 인증서 라이브러리 동기화(네이티브 FPK 전용)

fnOS 네이티브 FPK에서는 시스템 설정 → fnOS → fnOS SSL 인증서 동기화를 통해 fn-knock 인증서 라이브러리의 내용을 fnOS 시스템에 있는 기존 인증서 레코드와 동기화할 수 있습니다.

동기화는 도메인과 SAN 집합이 완전히 일치하는 기존 fnOS 인증서만 업데이트하며 fnOS 시스템의 인증서 레코드를 새로 만들거나 삭제하지 않습니다. 따라서 양쪽의 적용 도메인 집합이 일치하는지 먼저 확인한 뒤 개별 또는 전체 동기화를 실행합니다. 일치하는 항목이 없다면 동기화 기능이 대신 만들 것으로 기대하지 말고 인증서 레코드부터 조정합니다.

필요할 때 직접 동기화하거나 자동 동기화를 활성화할 수 있습니다. 자동 모드는 로컬 인증서 라이브러리가 변경된 뒤 잠시 변경 사항을 모아 기다렸다가 일치하는 항목을 한 번에 동기화하고 fnOS 서비스를 한 번 새로 고칩니다. 대상 인증서에서 fnOS 자체 자동 갱신도 활성화했다면 이후 갱신이 동기화 결과를 덮어쓸 수 있으므로 어느 쪽에서 갱신을 담당할지 명확히 정합니다.

권장 설정 순서

1. 외부에 최종 공개할 도메인과 포트를 정하고 사설망 주소로 먼저 인증서를 신청하지 않습니다.
2. DNS에서 인증 Host와 서비스 Host가 올바르게 조회되는지 확인합니다.
3. SSL/HTTPS에서 인증서를 업로드, 신청 또는 선택합니다.
4. 인증서 수에 따라 단일 활성 인증서나 다중 인증서 SNI를 선택하고 게이트웨이가 예상한 인증서 세트를 받았는지 확인합니다.
5. 인증서 적용 범위 안내를 확인하고 포함되지 않은 Host를 수정합니다.
6. 모바일 네트워크에서 인증 Host와 서비스 Host 하나에 접근해 브라우저 인증서 체인, 도메인, 유효 기간 및 로그인 절차를 확인합니다.

자동 HTTPS의 범위

시스템의 자동 HTTPS는 게이트웨이에서 HTTP를 HTTPS로 리디렉션하고 설정된 인증서를 활성화하는 기능만 담당합니다. 도메인을 대신 신청하거나 라우터 포트를 열거나 CDN 오리진 연결을 설정하지는 않습니다. Docker와 OpenWrt 환경에서는 호스트 관련 스위치를 제공하지 않습니다. 외부 리버스 프록시에서 TLS를 종료한다면 해당 프록시가 HTTPS를 강제합니다. Windows에서 이 스위치가 표시되더라도 실제 인바운드 경로와 사용할 수 있는 80번 포트가 먼저 필요합니다. 7999가 기본적으로 모든 인터페이스에서 수신 대기한다는 사실만으로 Windows 방화벽, 라우터/NAT 또는 통신사가 인터넷 접근을 허용했다는 뜻은 아닙니다.

문제 해결

• 브라우저에 도메인 불일치가 표시됨: 인증서의 DNS 이름이 현재 Host를 포함하지 않거나 업스트림 CDN이 잘못된 사이트를 오리진으로 사용하고 있습니다.

• 인증서가 라이브러리에 있지만 인터넷에서 이전 인증서를 반환함: 현재 / 기본 인증서로 설정되었는지, 배포 모드가 올바른지, 게이트웨이가 받은 인증서 세트가 업데이트되었는지 확인합니다.

• 여러 도메인에서 같은 잘못된 인증서를 반환함: 현재 단일 활성 모드인지, 다중 인증서 SNI에서 일치하는 항목이 없어 기본 인증서로 폴백했는지 확인합니다.

• 업로드 실패: PEM 내용, 개인 키 일치 여부 및 인증서 체인 순서를 확인하고 PKCS#12 파일 내용을 PEM 입력란에 업로드하지 않습니다.

• ACME 실패: DNS 제공자 자격 증명, DNS API 요청 한도 및 TXT 레코드 전파를 확인합니다. 현재 발급 절차에서는 DNS-01만 사용하므로 HTTP-01 방식으로 문제를 해결하려고 하지 않습니다.

• ACME 발급에 성공했지만 적용되지 않음: 인증서 라이브러리 연결과 단일 활성 모드에서 현재 인증서로 설정을 실행했는지 확인합니다.

• cloudflared에서 https://localhost:7999 사용 실패: 업스트림 TLS 이름과 인증서가 일치하는지 확인합니다. 일치시킬 수 없다면 검증된 HTTP 오리진 연결 방식을 먼저 사용하거나 터널의 TLS 설정을 조정합니다.

• 서비스 페이지는 정상이나 패스키를 사용할 수 없음: 인증 Host에 유효한 HTTPS와 올바른 RP 도메인으로 접근하는지 확인합니다.

• DDNS 관리

• 서브도메인 매핑

• Cloudflared 터널

• 시스템 설정 및 유지 관리