콘텐츠로 이동

Corvus는 이렇게 동작합니다

그림 하나로 보는 원리

Corvus가 없으면 방문자가 웹 서버에 바로 접속합니다.

방문자 ──► :80 / :443  내 웹 서버

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가 그 주소를 씁니다.

        extra_hosts:
          - 'app01.corp.example:10.0.0.21'
    

Docker 네트워크 대역이 사내망과 겹칠 때. Docker는 자기 네트워크에 쓸 사설 대역을 스스로 고릅니다 (예: 172.18.0.0/16, 192.168.16.0/20). 이 대역이 사내망에서도 쓰이면 Corvus가 그 대역의 서버에 닿지 못합니다. 그 서버로 가는 호스트만 502가 나고 나머지는 정상입니다. docker network inspect <네트워크> | grep Subnet으로 확인하고, Corvus 네트워크에 사내망에서 쓰지 않는 대역을 지정하세요.

networks:
  default:
    ipam:
      config:
        - subnet: 172.30.0.0/24

앞으로 만들 모든 Docker 네트워크가 사내 대역을 피하게 하려면 /etc/docker/daemon.json에 default-address-pools를 설정합니다.

저장하기 전에 확인하기. 프록시 호스트 화면의 연결 확인은 게이트웨이에서 같은 방식으로 이름을 찾아 대상에 접속해 보고, 위 문제 중 어느 것에 걸렸는지 알려 줍니다. 연결 확인을 참고하세요.

서비스 서버에서 할 일:

  • 요청은 게이트웨이 서버의 주소에서 들어옵니다. 방문자의 주소는 X-Forwarded-For와 X-Real-IP에 있습니다. 앱의 신뢰 프록시 설정(예: Nextcloud의 trusted_proxies, nginx의 set_real_ip_from)에 게이트웨이 서버 주소를 넣어야 실제 방문자 주소로 기록하고 제한합니다.
  • 서비스 포트에는 게이트웨이 서버만 접속하도록 방화벽을 설정하세요. 그렇지 않으면 사내망의 누구든 Corvus와 그 보호 기능을 건너뛰고 서비스에 바로 접속할 수 있습니다.

다음 단계