Corvus는 이렇게 동작합니다¶
그림 하나로 보는 원리¶
Corvus가 없으면 방문자가 웹 서버에 바로 접속합니다.
Corvus를 두면 80·443 포트로 들어오는 요청을 Corvus가 대신 받아서, 검사한 뒤 원래 가야 할 웹 서버로 넘겨 줍니다.
┌──────────────────────────────┐
방문자 ──► :80 / :443 ──►│ Corvus │──► 블로그 (컨테이너, 2368 포트)
│ · HTTPS 인증서 │──► Nextcloud (컨테이너, 80 포트)
│ · 공격 차단, 봇 차단 │──► 기존 웹사이트 (이 서버, 8080 포트)
│ · 접속 대기열, 트래픽 관제 │
└──────────────────────────────┘
관리 콘솔 :9443
방문자는 여전히 https://blog.example.com으로 접속하고, Corvus 뒤의 포트 번호는 보지 못합니다. 이런
프로그램을 리버스 프록시라고 부릅니다.
이 문서에서 쓰는 말¶
| 용어 | 뜻 |
|---|---|
| 게이트웨이 | 80·443 포트에서 방문자를 맞는 Corvus의 부분입니다. |
| 프록시 호스트 | Corvus에 만드는 규칙 하나입니다. "이 도메인으로 온 요청은 저 웹 서버로". 웹사이트나 앱마다 하나씩 만듭니다. |
| Corvus 뒤의 서비스, 전달 대상, 업스트림, 백엔드 | 실제로 페이지를 만드는 웹 서버나 앱입니다. 예: WordPress 컨테이너, 이미 쓰고 있던 nginx. Corvus가 요청을 넘겨 주고 응답을 방문자에게 돌려줍니다. |
| 전달 대상 호스트 / 포트 | Corvus에서 그 서비스에 닿는 주소입니다. 컨테이너 이름, IP 주소, 또는 같은 서버의 서비스라면 127.0.0.1. |
| 관리 콘솔 | 이 모든 것을 설정하는 웹 화면으로, 9443 포트에 있습니다. 방문자는 쓰지 않습니다. |
한 포트는 한 번에 프로그램 하나만 쓸 수 있습니다. Corvus가 80·443을 쓰므로, Corvus 뒤의 서비스는 다른 포트에서(또는 Docker 안에서만) 동작하고 Corvus가 그쪽으로 요청을 넘깁니다.
이미 80·443 포트를 쓰는 웹 서버가 있어요¶
웹 서버를 다른 포트로 옮기고, Corvus를 80·443으로 띄운 다음, 프록시 호스트를 새 포트로 연결하면 됩니다. 사이트 내용은 그대로이고, 웹 서버가 듣는 포트만 바뀝니다.
1. 웹 서버를 다른 포트로 옮기기¶
비어 있는 포트를 하나 고릅니다. 예: 8080. 이제부터 웹 서버는 평범한 HTTP만 제공하면 됩니다. HTTPS와 인증서는 Corvus가 맡습니다.
사이트 설정의 listen 줄을 바꿉니다.
server {
listen 8080; # 원래: listen 80;
# "listen 443 ssl" server 블록은 지우거나 다른 포트로 옮깁니다
server_name example.com;
...
}
그다음 sudo nginx -t && sudo systemctl reload nginx를 실행합니다.
ports.conf에서 Listen 80을 Listen 8080으로 바꾸고 Listen 443은 지웁니다. 가상 호스트의
<VirtualHost *:80>도 <VirtualHost *:8080>으로 바꿉니다. 그다음
sudo apachectl configtest && sudo systemctl reload apache2를 실행합니다.
그 컨테이너의 docker-compose.yml에서 공개 포트를 바꿉니다. 예: '80:80' 대신 '8080:80', 그리고
'443:443'은 지웁니다. 그다음 docker compose up -d를 실행합니다.
더 좋은 방법은 포트를 아예 공개하지 않고, Corvus와 같은 Docker 네트워크에 컨테이너를 넣는 것입니다. Corvus를 다른 컨테이너와 연결하기를 참고하세요.
새 포트에서 사이트가 응답하는지 확인합니다: curl -I http://127.0.0.1:8080
웹 서버가 Docker에서 오는 연결을 받아야 합니다
Corvus는 컨테이너 안에서 동작하므로 Docker를 거쳐 127.0.0.1:8080에 접속합니다. 웹 서버가
127.0.0.1에서만 듣고 있다면(예: listen 127.0.0.1:8080;) 모든 주소에서 듣도록 바꾸고(listen 8080;)
8080 포트는 방화벽으로 막아 두세요. 또는 Corvus를
호스트 네트워크로 실행합니다.
2. Corvus 설치하고 시작하기¶
이제 80·443 포트가 비었습니다. 설치를 따라 하세요.
3. 내 사이트용 프록시 호스트 만들기¶
관리 콘솔에서 프록시 호스트 → 프록시 호스트 추가를 누릅니다.
| 항목 | 값 |
|---|---|
| 도메인 | example.com (쓰고 있다면 www.example.com도) |
| 프로토콜 | http |
| 호스트 / IP | 127.0.0.1 (컨테이너 안에서는 이 서버를 뜻합니다) |
| 포트 | 8080 |
TLS 섹션에서 Let's Encrypt 인증서를 요청하고 HTTPS로 강제 이동을 켠 뒤 저장합니다. 이제 사이트가 Corvus를 거쳐 서비스됩니다. 자세한 내용은 첫 프록시 호스트를 참고하세요.
잘 안 될 때¶
- 502 Bad Gateway: Corvus가 8080 포트에 닿지 못합니다. 위의 주의 사항과 문제 해결을 확인하세요.
- 리디렉션 루프: 웹 서버나 앱이 스스로 HTTPS로 리디렉션하고 있습니다. 그 일은 Corvus가 이미 하므로
앱의 HTTPS 리디렉션을 끄거나, 앱에 프록시 뒤에 있다고 알려 주세요(앱은
X-Forwarded-Proto: https를 받습니다). - 링크가 이상하거나 혼합 콘텐츠 경고: 앱의 사이트 주소를
https://example.com으로 설정합니다 (WordPress: 설정 → 일반).
서비스가 다른 서버에 있어요¶
Corvus가 서비스와 같은 서버에 있을 필요는 없습니다. 인터넷 요청을 받는 게이트웨이 서버 한 대에 Corvus를 두고, 실제 서비스는 사설망의 다른 서버에서 운영하는 구성이 흔합니다.
인터넷 ──► :80 / :443 게이트웨이 서버 (Corvus) ──► 10.0.0.21:8080 (웹 서버)
──► 10.0.0.22:3000 (앱 서버)
──► nas.corp.example:5001 (NAS, HTTPS)
전달 대상 호스트에 그 서버의 주소를 적습니다. 10.0.0.21, 192.168.1.20 같은 사설 IP 주소나
DNS 이름을 쓸 수 있습니다. 사설 주소도 허용됩니다. 자체 서명 인증서로 HTTPS를 쓰는 서비스도 됩니다.
프로토콜을 https로 고르세요. Corvus는 뒤쪽 서비스의 인증서를 검사하지 않습니다.
DNS 이름. Corvus는 요청할 때 DNS로 이름을 찾습니다(30초마다 다시 찾으므로 주소가 바뀌어도 따라갑니다). 서버에서 이름을 입력할 때와 다른 점이 두 가지 있습니다.
- 전체 이름(
app01.corp.example)을 쓰세요. 짧은 이름(app01)은 안 될 수 있습니다. Corvus는/etc/resolv.conf의 search 도메인을 붙이지 않으므로, search 도메인 덕분에 찾아지던 짧은 이름은 502 Bad Gateway로 응답합니다. -
게이트웨이 서버의
/etc/hosts에만 있는 이름은 컨테이너 안에서 보이지 않습니다.docker-compose.yml의 Corvus 서비스에 추가하면 Corvus가 그 주소를 씁니다.
Docker 네트워크 대역이 사내망과 겹칠 때. Docker는 자기 네트워크에 쓸 사설 대역을 스스로 고릅니다
(예: 172.18.0.0/16, 192.168.16.0/20). 이 대역이 사내망에서도 쓰이면 Corvus가 그 대역의 서버에
닿지 못합니다. 그 서버로 가는 호스트만 502가 나고 나머지는 정상입니다.
docker network inspect <네트워크> | grep Subnet으로 확인하고, Corvus 네트워크에 사내망에서 쓰지 않는
대역을 지정하세요.
앞으로 만들 모든 Docker 네트워크가 사내 대역을 피하게 하려면 /etc/docker/daemon.json에
default-address-pools를 설정합니다.
저장하기 전에 확인하기. 프록시 호스트 화면의 연결 확인은 게이트웨이에서 같은 방식으로 이름을 찾아 대상에 접속해 보고, 위 문제 중 어느 것에 걸렸는지 알려 줍니다. 연결 확인을 참고하세요.
서비스 서버에서 할 일:
- 요청은 게이트웨이 서버의 주소에서 들어옵니다. 방문자의 주소는
X-Forwarded-For와X-Real-IP에 있습니다. 앱의 신뢰 프록시 설정(예: Nextcloud의trusted_proxies, nginx의set_real_ip_from)에 게이트웨이 서버 주소를 넣어야 실제 방문자 주소로 기록하고 제한합니다. - 서비스 포트에는 게이트웨이 서버만 접속하도록 방화벽을 설정하세요. 그렇지 않으면 사내망의 누구든 Corvus와 그 보호 기능을 건너뛰고 서비스에 바로 접속할 수 있습니다.