WEB FOUNDATIONS / N3M TUNNELS
주소 하나가
내 폴더까지 도착하는 과정.
코드는 작성할 수 있지만 웹 서버 운영은 익숙하지 않은 개발자를 위한 설명서입니다. 이번에 입력한 DNS 레코드, Cloudflare의 구름 버튼, 인증서와 API 토큰이 각각 무엇을 바꿨는지 실제 프로젝트에 연결해 읽습니다.
사람이 읽는 이름을 서버의 IP 주소로 찾습니다. 파일을 보내거나 사용자를 인증하지 않습니다.
인증서로 접속 이름과 서버를 확인하고, 통신 내용을 암호화하며 변조를 탐지합니다.
공유 이름에 연결된 에이전트를 찾아 파일 요청을 전달합니다. 접근 권한은 앱이 따로 검사합니다.
문서 ID PW-LEARN-001 · 개정 001-02. 기존 계획 문서의 식별·개정·절차·검증 추적 방식을 이어받은 학습 보충 문서입니다. S1000D XML/BREX 또는 ASD-STE100 인증 문서로 주장하지 않습니다. 한국어 학습 설명이 목적입니다.
주소를 해체하면, 필요한 기술이 보입니다.
이 주소는 구조를 설명하기 위한 예시입니다. 실제 활성 공유나 현재 제품의 다운로드 API 경로가 아닙니다.
| 부분 | 뜻 | 누가 사용하나? |
|---|---|---|
https | HTTP를 TLS로 보호해서 통신하겠다는 약속 | 브라우저와 접속 서버 |
abc.tunnels.n3m.kr | 접속할 호스트 이름. abc는 공유를 구분하는 부분 | DNS 조회, TLS 이름 검증, 웹 요청 라우팅 |
생략된 :443 | HTTPS의 기본 포트. 한 IP에서 어떤 통신 창구를 사용할지 결정 | 운영체제의 네트워크 연결 |
/files/report.pdf | 서버에 요청하는 자원의 경로. Windows 절대경로와 다름 | 웹 서버와 애플리케이션 |
?download=1 | 애플리케이션이 해석하는 추가 매개변수 | 애플리케이션. 비밀을 넣으면 로그 등에 남을 수 있음 |
이 그림은 TCP 위의 HTTP/1.1·HTTP/2를 설명합니다. DNS 조회와 연결은 캐시·재사용될 수 있어 매 요청마다 모든 과정을 반복하지는 않습니다. HTTP/3의 QUIC 연결은 여기서 다루지 않습니다.
DNS는 URL 전체가 아니라 호스트 이름을 조회합니다. 따라서 DNS 설정에 https://, 파일 경로, 포트를 넣지 않습니다. 주소 끝의 #section 같은 fragment는 일반 HTTP 요청에 실리지 않고 브라우저가 처리합니다.
원리 근거: MDN · URL의 구성.
Cloudflare에 추가한 것은 주소 안내 규칙입니다.
n3m.kr이라는 DNS 관리 영역 안에서 이름 칸에 *.tunnels를 입력하면 전체 이름은 *.tunnels.n3m.kr이 됩니다. 별표는 여러 공유 이름을 한꺼번에 같은 공개 진입점으로 보낼 때 사용합니다.
| 설정 항목 | 이번 구성 | 이유 |
|---|---|---|
레코드 종류 A | 호스트 이름 → 원본 서버의 공인 IPv4 | 외부 브라우저가 도달할 서버를 지정 |
이름 tunnels | tunnels.n3m.kr | 에이전트가 연결할 기본 주소. 와일드카드와 별도 등록 |
이름 *.tunnels | abc.tunnels.n3m.kr 같은 공유 주소 | 공유할 때마다 DNS 레코드를 새로 만들 필요를 없앰 |
| 와일드카드 프록시 상태 | DNS only · 회색 구름 | 공유 브라우저가 원본 서버의 인증서를 직접 사용 |
| TTL | DNS 응답을 캐시할 시간 | 공유 만료 시간이나 인증서 유효기간과 무관 |
AAAA는 IPv6 주소용이고, CNAME은 다른 DNS 이름을 가리키는 별칭이며, TXT는 검증 등에 쓰는 문자열 기록입니다. 원본 서버가 IPv6로 접속을 받지 못하면 실제 서비스를 가리키는 AAAA를 임의로 추가하지 않습니다.
DNS 등록은 서버 실행이 아닙니다. 이름이 올바른 IP로 조회되어도 443 포트, 인증서, Nginx 설정, Rust 프로세스가 준비되지 않으면 파일 서비스는 열리지 않습니다. 또한 DNS 응답의 IP가 Cloudflare 주소라면 그것을 원본 서버 공인 IP로 복사하면 안 됩니다.
DNS 와일드카드와 인증서 와일드카드는 서로 다른 규칙입니다. DNS는 명시된 레코드나 위임의 존재에 따라 와일드카드 적용이 달라지고, 더 깊은 이름에도 답할 수 있습니다. DNS가 답한다고 인증서의 이름 범위도 맞는 것은 아닙니다. N3M Tunnels 공유 이름은 한 단계만 사용하도록 설계했습니다.
구름의 색은 파일 요청이 지나가는 길을 바꿉니다.
Cloudflare는 이 구성에서 두 역할을 할 수 있습니다. 하나는 이름을 IP로 알려주는 DNS 관리, 다른 하나는 웹 요청을 대신 받아 원본 서버에 전달하는 리버스 프록시입니다. DNS only로 바꿔도 DNS 관리는 계속 Cloudflare가 맡습니다.
주황색 구름의 위 그림은 Cloudflare와 원본 사이도 HTTPS로 보호하고 인증서를 검증하는 Full (strict)에 맞춘 구조입니다. 이 문서는 현재 계정의 SSL 모드를 확인했다는 뜻이 아닙니다. 브라우저가 보는 edge 인증서와 원본 서버의 인증서는 서로 다른 위치에서 사용됩니다.
이번에는 공유 주소의 회색 구름과 원본 서버의 공개 신뢰 인증서를 선택했습니다. 그래서 공유 트래픽은 Cloudflare의 웹 프록시·캐시·WAF를 거치지 않고 서버로 직접 들어옵니다. 원본 IP와 443 접근 경로가 외부에 도달 가능해야 합니다. tunnels 기본 주소와 *.tunnels는 다른 이름이므로 서로 다른 프록시 설정을 가질 수 있습니다.
경고의 의미 · “This hostname is not covered by a certificate.”는 *.tunnels라는 DNS 이름의 철자가 잘못됐다는 뜻이 아닙니다. 당시 Cloudflare가 방문자에게 제시할 기본 인증서에 깊은 공유 주소가 포함되지 않는다는 의미였습니다.
회색 구름으로 바꾸면 브라우저가 인증서를 확인할 상대가 원본 서버로 바뀝니다. 이제 그 서버에 적합한 인증서를 적용해야 합니다. 프록시를 계속 사용할 수도 있지만, 그 경우에는 공유 와일드카드를 포함하는 Cloudflare 쪽 인증서와 원본 쪽 TLS를 각각 준비해야 합니다.
근거: Cloudflare · 프록시 상태, 기본 인증서의 이름 범위. DNS only에서는 일반 브라우저가 신뢰하는 인증서를 사용합니다. Cloudflare Origin CA 인증서만으로 직접 접속을 해결하는 구성은 아닙니다.
인증서는 공개 증명서, 개인키는 서버의 비밀입니다.
TLS 연결에서 브라우저는 인증서의 이름이 접속 주소와 맞는지, 유효기간이 남았는지, 신뢰하는 인증기관으로 연결되는 서명이 있는지 등을 검사합니다. 서버는 해당 인증서와 연결된 개인키를 보유했음을 증명하고, 양쪽은 통신을 보호할 키를 합의합니다.
| 개념 | 역할 | 이번 프로젝트에서 |
|---|---|---|
| 인증기관 · CA | 도메인 관리 권한을 확인하고 인증서에 서명 | Let’s Encrypt. 인증서 발급 서비스 |
| 인증서 · certificate | 도메인 이름·공개키·유효기간·서명 등의 공개 정보 | fullchain.pem은 서버 인증서와 필요한 중간 인증서 묶음 |
| 개인키 · private key | 서버가 해당 공개키의 짝을 가진다는 증명에 사용 | privkey.pem. 서버에서 보호하며 방문자에게 보내지 않음 |
| TLS | 서버 인증과 통신 내용의 암호화·무결성 보호 | HTTPS와 WSS 연결을 보호 |
| Certbot | 인증기관과 대화해 발급·갱신을 수행하는 클라이언트 | Ubuntu에서 실행하는 운영 도구. 인증기관 자체는 아님 |
도메인 검증 인증서는 해당 이름의 관리 권한을 확인한 결과입니다. 사이트의 사업 신뢰도, 코드의 무결함, 파일의 안전성까지 보증하지는 않습니다. 또한 HTTPS는 전송 중 보호입니다. 저장된 파일의 암호화나 파일을 볼 수 있는 사용자의 권한은 애플리케이션이 별도로 책임집니다.
N3M Tunnels의 목표 연결은 브라우저↔공개 진입점, 에이전트↔공개 진입점을 각각 TLS로 보호합니다. Ubuntu에서 TLS를 종료하고 중계하므로 서버는 파일 내용을 처리할 수 있습니다. 서버도 내용을 볼 수 없는 종단 간 암호화를 구현했다고 해석하면 안 됩니다.
원리 근거: Let’s Encrypt · 동작 원리, Nginx · 인증서와 개인키 설정.
별표 하나는 인증서에서 점 하나를 넘지 않습니다.
| 인증서에 들어간 이름 | 접속 주소 | 이름 범위 |
|---|---|---|
*.n3m.kr | tunnels.n3m.kr | 일치 |
*.n3m.kr | abc.tunnels.n3m.kr | 불일치 · 한 단계 더 깊음 |
*.tunnels.n3m.kr | abc.tunnels.n3m.kr | 일치 |
*.tunnels.n3m.kr | tunnels.n3m.kr | 불일치 · 별표 자리가 없음 |
*.tunnels.n3m.kr | a.b.tunnels.n3m.kr | 불일치 · 별표 자리에 두 단계가 있음 |
따라서 하나의 인증서에 tunnels.n3m.kr와 *.tunnels.n3m.kr를 함께 넣습니다. 이 이름 목록을 SAN · Subject Alternative Name이라고 합니다. 인증서를 두 장 발급해야 한다는 뜻은 아닙니다.
이름 범위만 바꿔 보는 실험
브라우저 안에서 이름만 비교합니다. DNS 조회·인증서 발급·설정 변경·입력 저장·외부 통신을 하지 않습니다. 실제 인증서 검증기를 대체하지 않습니다.
범위 근거: RFC 9525 · TLS 이름 일치 규칙. 이름 범위가 맞아도 만료·체인·서버 적용 문제가 있으면 HTTPS는 실패합니다.
API 토큰은 자동으로 소유권을 증명하기 위한 열쇠입니다.
Let’s Encrypt는 “그 도메인을 관리하는 사람이 맞는가?”를 확인합니다. 이번 와일드카드에는 DNS에 지정된 값을 쓰는 DNS-01 방식을 사용합니다. 발급과 갱신 대화를 자동화하는 규약은 ACME입니다.
확인용 이름은 _acme-challenge.tunnels.n3m.kr이고 기록 종류는 TXT입니다. Certbot의 Cloudflare 플러그인이 검증용 값을 잠시 등록하고 작업 후 정리합니다. 이 기록은 소유권 확인에 쓰이며 파일 전송 경로가 아닙니다. 기본 주소와 와일드카드를 동시에 검증할 때 같은 이름에 여러 TXT 값이 잠시 존재할 수 있습니다.
사용자가 만든 Cloudflare API 토큰은 이 DNS 작업의 권한입니다. 이번 범위는 Zone → DNS → Edit, 대상 영역은 n3m.kr입니다. 도메인 하나로 제한했어도 그 영역의 DNS를 수정할 수 있으므로 서버 관리자만 읽도록 보관합니다. 서비스의 로그인 비밀번호나 방문자 공유 키와는 다른 비밀입니다.
왜 자동 갱신까지 하나?
인증서에는 유효기간이 있습니다. 자동 갱신은 만료 전에 새 인증서를 받고 웹 서버가 이를 사용하게 하는 작업입니다. 인증서를 파일로 받아 둔 것만으로 Nginx가 새 인증서를 읽었다고 볼 수는 없습니다.
왜 매번 TXT를 손으로 안 넣나?
수동 DNS 인증은 발급할 때마다 사람이 값을 등록해야 합니다. API 방식은 서버가 같은 절차를 반복할 수 있어 갱신을 자동화할 수 있습니다. 토큰을 폐기하거나 만료시키면 갱신 권한도 사라집니다.
서버의 certbot.timer가 갱신을 주기적으로 확인합니다. 성공한 발급·갱신 뒤에는 설정 검사 nginx -t를 통과하고 Nginx를 reload하도록 hook을 기록했습니다. --dry-run은 시험 인증기관에서 갱신 과정을 확인하는 명령이며, 이번 명령에서는 운영 인증서 교체와 deploy hook 실행까지 시험하는 것은 아닙니다.
근거: Let’s Encrypt · DNS-01, Cloudflare 플러그인의 토큰 권한·보관, Certbot · 갱신과 hook.
Nginx는 한 서버의 여러 웹 서비스를 나눠 받습니다.
하나의 Ubuntu 서버에 콘솔, 터널, 기존 notParsec 서비스를 함께 두도록 설계했습니다. 아래는 적용할 라우팅 구성입니다. 인터넷에 노출하는 443 포트는 Nginx가 받고, 이름과 경로를 보고 내부 프로그램에 전달하도록 구성합니다. 이런 역할을 리버스 프록시라고 부릅니다.
| 공개 이름 | 담당 기능 | 같은 서버 안의 대상 |
|---|---|---|
console.n3m.kr | 통합 관리 UI와 관리 API 연결 | 127.0.0.1:18082 · 콘솔 |
tunnels.n3m.kr | 에이전트 WSS 연결과 터널 서버 상태 | 127.0.0.1:18081 · N3M Tunnels |
*.tunnels.n3m.kr | 개별 공유의 웹 파일 접근 | 같은 터널 서버 → 공유 이름으로 연결 선택 |
remote.n3m.kr | 기존 notParsec 서비스·문서 유지 | 기존 서비스 :18080 및 문서 경로 |
127.0.0.1은 그 컴퓨터 자신을 뜻합니다. 내부 포트를 인터넷에 직접 공개하지 않고 Nginx를 거쳐 접근하게 하는 구성입니다. 콘솔은 내부 API를 호출하되 제품의 DB와 파일을 직접 소유하지 않는 경계를 유지합니다.
이름은 두 시점에 사용됩니다. TLS 연결을 시작할 때 SNI로 인증서를 고르고, HTTP 요청에서는 Host 또는 HTTP/2의 :authority로 요청 대상을 구분합니다. 인증서는 TLS 단계에 필요하므로 인증서가 잘못된 문제를 HTTP 경로 수정만으로 해결할 수 없습니다.
# 설명용 핵심 설정. 전체 운영 설정을 대체하는 파일이 아닙니다.
server_name tunnels.n3m.kr *.tunnels.n3m.kr;
ssl_certificate /etc/letsencrypt/live/tunnels.n3m.kr/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/tunnels.n3m.kr/privkey.pem;
# 이후 location에서 내부 Rust 서비스로 전달
인증서 발급은 디스크에 파일을 준비하는 일입니다. 이 경로를 사용하는 Nginx의 서버 설정을 설치하고 reload하는 일은 별도입니다. 요청 이름에 맞는 설정이 없으면 기본 가상 서버가 응답할 수 있습니다.
요청 처리 근거: Nginx · 이름에 따른 서버 선택, Nginx · TLS의 SNI. 포트와 경로 표는 프로젝트 설치 템플릿에 근거한 구성입니다.
임시 주소는 DNS가 아니라 터널 서버가 배정합니다.
일반 가정의 Windows PC는 공유기와 방화벽 뒤에 있어 외부에서 새 연결을 바로 받기 어렵습니다. 에이전트가 먼저 공개 Ubuntu 서버로 연결을 열면, 서버는 그 연결을 통해 파일 요청을 전달할 수 있습니다. WSS는 TLS로 보호하는 WebSocket이며, 연결을 유지하면서 양방향 메시지를 주고받습니다.
현재 기본 주소 tunnels.n3m.kr는 Cloudflare 프록시를 거칩니다. 따라서 에이전트의 실제 연결 경로에는 Windows → Cloudflare → Ubuntu 구간이 있으며, 위 그림에서는 중간 프록시를 생략했습니다. 프록시와 원본 사이의 TLS 설정은 별도로 확인해야 합니다.
- Windows에서 공유할 폴더를 선택합니다.
tunnels serve명령은 지정한 폴더를 에이전트의 공유 루트로 삼습니다. 다른 폴더까지 접근하지 못하게 경로 경계를 검사해야 합니다. - 에이전트가 서버에 인증하고 WSS 연결을 엽니다.
기본 연결 주소는
wss://tunnels.n3m.kr/agent/v1/connect입니다. 공유하는 Windows 쪽은 외부로 연결합니다. 공개 Ubuntu 서버 쪽의 접근 가능한 443은 별도로 필요합니다. - 서버가 난수 이름과 공유 정보를 배정합니다.
현재 코드는 96비트 난수 이름, SQLite의 이름 고유 제약과 사용한 이름 기록을 사용합니다. URL과 별도의 방문자 접근 키를 반환합니다. 충돌 자동 재시도·생성 요청 멱등성은 후속 항목입니다.
- 방문자가 받은 주소를 엽니다.
이미 준비한 와일드카드 DNS가 서버로 안내하고, 와일드카드 인증서가 이름 검증에 사용됩니다. Rust 서버가 공유 이름과 활성 에이전트 연결을 찾고 방문자 권한을 검사합니다.
- 에이전트가 파일을 읽거나 씁니다.
서버가 요청과 응답을 중계합니다. 파일의 원본은 Windows 공유 폴더에 있습니다. PC가 꺼지거나 공유가 끝나면 DNS가 남아 있어도 파일 서비스는 사용할 수 없습니다.
서로 다른 세 개의 수명 · DNS TTL은 주소 응답의 캐시 시간, 인증서 유효기간은 TLS 신뢰의 기간, 터널 만료는 앱이 공유를 허용하는 기간입니다. 어느 하나를 늘려도 나머지가 자동으로 연장되지는 않습니다.
이 구조는 인터넷에서 파일을 다룬다는 사용감이 클라우드 드라이브와 비슷하지만, 서버에 파일 전체를 동기화해서 영구 보관하는 드라이브는 아닙니다. 현재 첫 구현은 파일당 8MiB의 버퍼 기반 전송입니다. 대용량 스트리밍·이어받기·자동 재연결·예약 주소·Windows 네트워크 드라이브는 별도 후속 개발입니다.
구현 근거: crates/portway/src/agent_cli.rs, server.rs, protocol.rs, files.rs. 요구와 제한은 임시 주소 설계 및 기능 진행표를 참고하세요. Cloudflare DNS를 사용한다고 Cloudflare Tunnel 제품을 사용 중인 것은 아닙니다.
우리가 한 일과, 아직 확인할 일을 분리합니다.
사용자는 DNS 레코드와 프록시 상태를 수정하고 Cloudflare 토큰을 생성했습니다. 이후 인증서 준비 도구를 직접 실행하여 TUNNELS_CERTIFICATE_READY 성공 로그를 전달하고 전체 서비스 설치를 완료했습니다. 후속 직접 검사에서 서비스 실행, 공개 TLS 이름·신뢰 검증과 공개 경로 20개 검사를 통과했습니다. 개발 작업에서는 Rust 터널 초기 구현, 별도 관리 콘솔, 배포 설정과 인증서 준비 도구를 작성했습니다. 도구를 만들거나 시험했다는 사실은 실제 외부 접속까지 완료됐다는 뜻이 아닙니다.
관측 시각: 2026-10-05 19:55 KST · 아래 표는 사용자 실행 로그, 시각을 명시한 기존 DNS 조회와 최신 읽기 전용 운영 검증을 구분한 기록입니다. 이 페이지를 열 때마다 서버를 조회하는 대시보드가 아닙니다. 도메인·서비스 상태는 이후 변경될 수 있습니다.
| 항목 | 판정 | 확인 근거와 한계 |
|---|---|---|
| 통합 콘솔 | 운영 확인 | console.n3m.kr의 정상 JSON, 설치된 화면·스크립트·스타일 일치와 콘솔 서비스 실행을 확인했습니다. 공개 경로 전체 20개 검사를 통과했습니다. |
| 기본 주소 DNS | 조회 확인 | 19:09 조회에서 tunnels.n3m.kr는 Cloudflare 프록시 IPv4·IPv6로 확인됐습니다. 19:55 공개 경로 검증에서 터널 readiness가 올바른 빈 본문 200을 반환했습니다. |
| 와일드카드 DNS | 변경 확인 | 19:09 조회에서 임의 공유 이름이 비 Cloudflare IPv4 한 개로 조회되고 AAAA는 없었습니다. 19:55 새 임의 이름으로 신뢰·이름 검증을 켠 HTTPS 접속에 성공했습니다. 실제 IP는 공개하지 않습니다. |
| 인증서 준비 도구 | 코드·시험 완료 | 숨김 토큰 입력, 보호 파일 저장, DNS-01 발급, 갱신 시험을 수행하는 도구를 작성·검증했습니다. |
| Cloudflare 플러그인 | 설치 확인 | 서버에 Certbot용 Cloudflare DNS 플러그인이 실제로 설치된 것을 확인했습니다. |
| 터널 인증서 발급·갱신 | 사용자 실행 확인 | 사용자가 전달한 TUNNELS_CERTIFICATE_READY 로그로 발급·갱신 시험 성공을 확인했습니다. 이후 공개 인증서의 신뢰·이름·유효기간은 별도로 직접 검증했습니다. 갱신 시험 로그와 공개 접속 검증은 다른 근거입니다. |
| 공유 주소의 HTTPS | 공개 TLS 검증 통과 | 새 임의 공유 이름에 대해 시스템 신뢰·호스트 이름 검증을 켠 TLS 1.3 접속이 성공했습니다. 인증서는 tunnels.n3m.kr와 *.tunnels.n3m.kr를 포함하며 미등록 공유 요청은 404를 반환했습니다. |
| 터널 서비스 | 실행 확인 | 사용자의 전체 서비스 설치 후 portway·n3m-console·notparsec-control이 active/enabled였습니다. 터널 내부 18081과 공개 readiness의 빈 본문 200을 확인했습니다. portway는 호환 내부 이름입니다. |
| Windows 실제 파일 왕복 | 검증 대기 | Windows CLI 앱과 다른 네트워크의 브라우저 사이에서 실제 업로드·다운로드·해시 일치·종료를 검증하지 않았습니다. 서버 설치 성공으로 이 항목을 완료 처리하지 않습니다. |
이번에 준비한 인증서 도구의 내부 작업
- 관리자 권한과 터미널 입력 환경을 확인합니다.
권한이 없으면 서버 설정이나 토큰 입력 전에 중단합니다. 운영체제의 sudo 비밀번호는 Cloudflare 비밀번호와 다릅니다.
- 기존 Certbot 계정과 Nginx 설정을 확인합니다.
기존 production 계정을 재사용하고 필요한 Cloudflare DNS 플러그인을 Ubuntu 패키지로 설치합니다.
- 토큰을 숨김 입력으로 받아 보호 파일에 저장합니다.
디렉토리는
0700, 파일은0600입니다. 0600은 소유자의 읽기·쓰기만 허용하고 그룹과 다른 사용자에게는 권한을 주지 않는다는 뜻입니다. 기존 보호 파일은 재사용하며 토큰을 명령행 인수로 보내지 않습니다. - 두 이름의 인증서를 요청하고 결과를 검사합니다.
이름 목록과 유효기간, 저장된 DNS 갱신 설정을 검사합니다. 발급 과정이 성공한 뒤에만 다음 단계로 갑니다.
- 해당 인증서의 갱신 시험과 타이머를 확인합니다.
모든 검사에 성공해야
TUNNELS_CERTIFICATE_READY를 표시합니다. 이 문구도 제품 서비스 설치 완료를 뜻하지는 않습니다.
도구: n3m-console/deploy/ubuntu/setup_tunnels_tls.py. 준비 검증은 신규 격리 시험 28개와 기존 운영 설치 시험을 합친 59개, 콘솔 Rust 시험 9개 및 정적 검사입니다. 실제 DNS-01 요청이나 Windows 파일 왕복을 대신하는 시험은 아닙니다. 이 학습 문서 게시 작업은 인증서나 서비스 설정을 대신 적용하지 않습니다.
명령 하나에도 준비·변경·검증을 나눠 읽습니다.
아래 명령은 Ubuntu 서버에서 n3m-console 프로젝트 폴더를 현재 경로로 열었을 때의 예시입니다. Windows 에이전트에서 실행하는 명령과 구분하세요. 이미 성공한 단계를 학습 목적으로 반복할 필요는 없습니다.
① 무엇을 할지 확인 · 읽기 전용
python3 deploy/ubuntu/setup_tunnels_tls.py --check
대상 도메인과 플러그인 준비 여부를 표시합니다. 토큰을 읽거나 인증서를 발급하지 않습니다.
② 인증서 준비 · 관리자 권한으로 변경
sudo python3 deploy/ubuntu/setup_tunnels_tls.py --apply
sudo가 묻는 것은 Ubuntu 계정 비밀번호입니다. 이후 Cloudflare API token (hidden input)에 생성한 토큰을 입력합니다. 문자가 화면에 표시되지 않는 것이 정상입니다. 토큰은 이 공개 문서나 채팅에 붙여넣지 않습니다. 명령 성공 여부는 마지막 성공 문구와 오류 없이 종료됐는지를 함께 확인합니다.
③ 서비스 적용 · 인증서 준비 뒤의 별도 변경
sudo python3 deploy/ubuntu/install.py --preflight
sudo python3 deploy/ubuntu/install.py --apply --bundle dist/release
먼저 사전 검사가 통과해야 설치 명령을 진행합니다. 기존 설치기는 콘솔과 터널 서비스를 함께 설정하고, 콘솔이 터널 관리 API를 호출할 자격을 연결합니다. 두 서비스가 재시작됩니다. 기존 설정의 백업과 실패 시 복구가 포함되며 notParsec 제품 DB나 파일 원본을 옮기지 않습니다.
④ 공개 접속 확인 · 검증
python3 deploy/ubuntu/verify.py --management-active --match-local --evidence /tmp/tunnels-public-verification.json
curl --fail --show-error https://tunnels.n3m.kr/health/ready
curl --verbose https://learning-probe.tunnels.n3m.kr/
기존 관리 경로가 콘솔로 이관된 현재 구성의 예시입니다. learning-probe는 활성 공유가 아닌 인증서 점검용 이름이므로, TLS 검증을 통과한 뒤에는 공유 없음 응답이 나올 수 있습니다. 그것과 인증서 오류를 구분합니다. --evidence는 필수 인자로, 검증 결과를 지정한 JSON 파일에 저장합니다. 검증을 끄는 -k를 붙이면 정상 인증서 확인 시험이 되지 않습니다. 마지막에는 실제 에이전트와 방문자로 파일 해시까지 비교해야 합니다.
도메인 A 레코드 변경과 DNS-01 발급은 별개입니다. TXT 검증이 가능하면 서비스가 아직 시작되지 않았어도 인증서 발급이 가능하지만, 이용자 접속을 위해서는 올바른 DNS·TLS·서비스가 모두 필요합니다.
오류가 난 층부터 확인하면 원인을 좁힐 수 있습니다.
| 관찰한 현상 | 먼저 볼 층 | 확인할 내용 |
|---|---|---|
| 이름을 찾을 수 없음 · NXDOMAIN | DNS | 이름·레코드·위임·캐시. 기본 tunnels와 *.tunnels를 구분 |
| 연결 거부 또는 시간 초과 | 네트워크·프로세스 | IP, 443, 방화벽·포트 전달, Nginx 수신 여부 |
| 인증서 이름 불일치 | TLS | SAN의 이름 범위, SNI, 어떤 서버가 어떤 인증서를 제시하는지 |
| 인증서 만료·신뢰 오류 | TLS·갱신 | 유효기간, 중간 인증서 체인, 시스템 시간, 갱신 기록 |
| 502 Bad Gateway | Nginx → 내부 앱 | 대상 포트·앱 실행·연결 실패. 프록시가 어느 응답을 냈는지 확인 |
| 401·403 | 인증·권한 | 응답한 서비스 확인 후 방문자 키, 관리자 세션, 허용 Origin 확인 |
| 공유 없음·만료·오프라인 | 터널 앱·Windows 에이전트 | 이름 배정, 활성 연결, 공유 수명, 선택한 폴더의 접근 상태 |
| 200인데 엉뚱한 화면·JSON | 호스트 라우팅 | 기본 가상 서버가 응답했는지, 본문과 서버 역할이 기대와 맞는지 |
과거 관측 · 2026-10-05 19:09 KST · 터널 서비스가 설치되지 않은 시점에도 tunnels.n3m.kr/health/ready가 200을 반환했습니다. 본문은 콘솔의 {"portway":"independent","status":"ready"}와 같았고, 원본 서버가 제시한 인증서도 콘솔용이었습니다. 상태 코드만으로 터널 정상이라고 판단할 수 없는 사례입니다. 이후 19:55 KST 검증에서는 터널 서비스가 실행 중이었고 readiness가 올바른 빈 본문 200을 반환했으며, 새 공유 이름의 TLS 검증과 미등록 공유 404 응답도 확인했습니다. 이 문단의 콘솔 인증서 오류는 현재 상태가 아닌 설치 전 기록입니다.
실무 확인 순서는 DNS 조회 → TLS 이름·체인 검증 → 기대하는 HTTP 본문 → 내부 서비스 → 에이전트 파일 왕복입니다. DNS 응답·설정 파일·200 응답은 각각 특정 단계의 근거일 뿐, 전체 기능의 성공 증거는 아닙니다.
접근 로그의 IP도 관찰 위치를 알아야 읽을 수 있습니다. Cloudflare를 거치면 원본 서버가 직접 본 상대는 Cloudflare일 수 있습니다. 전달 헤더를 실제 방문자 IP로 사용하려면 신뢰할 프록시 범위를 검증해야 합니다. IP 하나만으로 정확한 개인이나 물리적 위치를 확정할 수는 없습니다.
다음 질문에 답할 수 있으면 구조를 이해한 것입니다.
임시 공유를 100개 만들면 DNS 레코드와 인증서도 100개가 필요한가요?
이 구성에서는 필요하지 않습니다. 와일드카드 DNS와 인증서를 공통으로 준비하고, 애플리케이션이 공유 이름과 에이전트 연결의 매핑을 관리합니다. 각 공유의 인증·권한·수명은 따로 관리합니다.
회색 구름으로 바꾸면 HTTPS 암호화도 꺼지나요?
프록시를 거치지 않게 바뀌는 것입니다. 원본 서버에 공개 신뢰 인증서를 적용하면 브라우저와 원본 서버 사이에서 HTTPS를 사용합니다. 회색 구름을 눌렀다는 사실만으로 인증서가 발급되지는 않습니다.
인증서를 받았는데 왜 여전히 콘솔 인증서가 보일까요?
발급은 파일 생성, 적용은 웹 서버 설정입니다. 대상 이름의 Nginx 설정과 인증서 경로가 연결되어 있는지, reload됐는지, 요청이 올바른 서버에 도착하는지 확인합니다.
HTTPS가 되면 URL을 아는 사람은 파일을 읽어도 되나요?
HTTPS는 통신을 보호합니다. 방문자에게 파일 접근을 허용할지는 별도 인증과 권한 검사로 결정합니다. 현재 코드는 URL과 방문자 접근 키를 따로 발급합니다.
Windows PC가 꺼져도 DNS가 남아 있으면 파일이 열리나요?
아닙니다. DNS는 Ubuntu 진입점을 계속 가리킬 수 있지만 원본 파일을 처리할 에이전트가 없습니다. 공유 종료와 DNS 기록 삭제는 같은 작업이 아닙니다.
용어를 코드와 연결해서 기억하기
| 용어 | 개발자 관점의 역할 |
|---|---|
| DNS | 호스트 이름으로 접속 목적지를 찾는 분산 조회 시스템 |
| 인증서 · SAN | 어떤 도메인 이름과 공개키를 인증기관이 연결해 확인했는지 나타내는 정보 |
| 리버스 프록시 | 클라이언트 요청을 받아 내부 서비스로 전달하는 앞단 서버 |
| 에이전트 | Windows의 선택한 폴더를 다루고 서버에 먼저 연결하는 프로그램 |
| 터널 | 에이전트 연결을 통해 요청을 전달할 수 있게 만든 논리적 통로 |
| 관리 콘솔 | 터널 상태·접근 기록·제어를 제공하는 별도의 관리 애플리케이션 |
| ACME · Certbot | 인증서 발급·갱신 규약과 그 규약을 실행하는 도구 |
읽은 근거와 다음 문서
- MDN · URL 구조 — 주소를 구성하는 각 부분.
- Cloudflare · Wildcard DNS records — 별표 이름, 명시 레코드와의 관계.
- Cloudflare · Proxy status — DNS only와 프록시의 차이.
- Cloudflare · Universal SSL limitations — 기본 edge 인증서의 범위.
- Let’s Encrypt · DNS-01 — 와일드카드 도메인 검증.
- Certbot Cloudflare 플러그인 — 제한 토큰과 보호 파일.
- Certbot · 인증서 갱신 — dry-run과 배포 hook의 차이.
- Nginx · HTTPS 구성 / 요청 처리 — 인증서 선택과 가상 서버.
- N3M Tunnels 개발 계획과 기능 진행표 — 현재 구현, 수용 기준, 후속 개발.
공식 문서 확인일 2026.10.05 KST. 일반 원리는 위 자료에, 프로젝트의 동작과 한계는 Rust 소스·설치 스크립트·진행 원장·읽기 전용 운영 조회에 근거합니다. 학습 원본은 design/learning.*, 생성기는 tools/build_learning.py이며 공개 결과 HTML을 직접 편집하지 않습니다.