서비스 간 통신: 내부 주소와 내부 전용 서비스.
한 애플리케이션의 서비스가 내부 주소로 서로 연결되는 방식, RIVERVO_<NAME>_URL 변수, 공개 주소가 없는 서비스, 인스턴스 여러 개, 타임아웃과 재시도를 Node.js, Laravel, Python 예시와 함께 안내합니다.
한 애플리케이션의 서비스는 인터넷을 거치지 않고 서로 직접 통신합니다. 사이트가 자체 API를 호출하거나 워커가 내부 서비스를 호출할 수 있으며, 이 트래픽은 무료로 트래픽으로 계산되지 않습니다.
아래 예시에서는 웹 서비스 두 개를 사용합니다. 방문자가 여는 사이트인 web은 공개 주소, web과 다른 서비스만 호출하는 api는 내부 전용으로 설정되어 있습니다.
내부 주소
모든 웹 서비스는 공개 주소가 있든 내부 전용이든 http://<service-name>:<port> 형식의 내부 주소를 가집니다(예: http://api:8080). 이 주소는 서비스 페이지와 애플리케이션의 개요에 복사 버튼, 그리고 “이 애플리케이션의 다른 서비스가 여기로 접속합니다. 인터넷을 거치지 않으며 트래픽 요금이 없습니다.”라는 안내와 함께 표시됩니다.
- 포트는 저장소로 빌드한 서비스는 8080, 준비된 이미지로 만든 서비스는 지정한 포트입니다.
- 이 주소에는 같은 애플리케이션의 서비스만 접근할 수 있습니다. 인터넷이나 다른 애플리케이션에서는 열리지 않습니다.
- 주소는
http://를 사용합니다. 연결이 애플리케이션 안에서만 이루어지므로 인증서를 설정할 필요가 없습니다.
주소가 담긴 변수
코드에 주소를 복사해 넣을 필요가 없습니다. 애플리케이션의 모든 코드 서비스(웹 서비스, 백그라운드 워커, 예약 작업)는 애플리케이션의 다른 웹 서비스 각각의 내부 주소를 변수로 받습니다.
RIVERVO_<NAME>_URL=http://<name>:<port>
NAME은 서비스 이름을 대문자로 바꾸고 하이픈을 _로 바꾼 것입니다.
| 서비스 | 변수 |
|---|---|
api | RIVERVO_API_URL=http://api:8080 |
admin-api | RIVERVO_ADMIN_API_URL=http://admin-api:8080 |
web | RIVERVO_WEB_URL=http://web:8080 |
search(준비된 이미지, 포트 7700) | RIVERVO_SEARCH_URL=http://search:7700 |
- 서비스는 자기 자신에 대한 변수는 받지 않습니다.
- 데이터베이스와 Valkey는 연결 주소가 담긴 자체
RIVERVO_<NAME>_URL을 유지합니다. 서비스 이름은 애플리케이션 안에서 고유하므로 이름이 겹치지 않습니다. - 변수는 변수 탭의 자동 설정 변수 목록에 표시됩니다. 다른 자동 변수와 마찬가지로 같은 이름의 변수(또는 공유 변수)를 직접 만들면 그 값이 대신 사용됩니다. 환경 변수를 참고하세요.
- 변수는 다음 배포 때 서비스에 전달됩니다. 새 웹 서비스를 추가하거나 이름을 바꾸면 다른 서비스는 다음 배포 때 새 변수 또는 변경된 변수를 받습니다. 바로 반영하려면 다시 배포하세요. 예를 들어
rivervo deploy <app> --no-build는 새 빌드 없이 실행 중인 버전을 새 변수로 다시 시작합니다.
내부 전용 서비스
사이트 뒤의 API, 관리용 백엔드, 검색 엔진처럼 애플리케이션의 다른 서비스만 호출하는 웹 서비스는 인터넷에 공개할 필요가 없습니다. 내부 전용으로 설정하세요.
| 공개 주소 | 내부 전용 | |
|---|---|---|
인터넷 주소 https://<name>.rivervo.app | 있음 | 없음 |
| 자체 도메인 | 있음 | 없음 |
| 브랜치 미리보기 | 있음 | 없음 |
| 다른 서비스를 위한 내부 주소 | 있음 | 있음 |
| 인스턴스 여러 개와 자동 확장, 로그, 모니터링, 상태 확인 | 있음 | 있음 |
내부 전용 서비스는 다른 서비스와 똑같이 실행되며, 같은 애플리케이션의 다른 서비스만 접근할 수 있습니다.
서비스를 만들 때 선택
웹 서비스를 만들 때(저장소, 템플릿 또는 준비된 이미지로 새 애플리케이션의 첫 서비스를 만드는 경우 포함) 공개 주소 또는 내부 전용을 선택합니다. 미리 선택된 항목이 없으므로 항상 직접 선택합니다. 백그라운드 워커, 예약 작업, 데이터베이스는 공개 주소가 없으므로 선택 항목이 없습니다.
이 선택 기능이 생기기 전에 만든 서비스는 공개 주소를 유지합니다.
나중에 전환
서비스 → 설정 → 공개 주소에서 스위치를 바꾸고 확인합니다. 애플리케이션의 관리자 또는 계정 소유자만 변경할 수 있습니다. 재시작은 없습니다.
- 서비스에 도메인이 연결되어 있으면 내부 전용으로 전환할 수 없습니다. 먼저 도메인 탭에서 도메인을 삭제하세요. 미리보기도 먼저 꺼야 합니다.
- 공개 주소를 다시 켜면 서비스는 같은
https://<name>.rivervo.app주소를 받습니다. 인증서 발급에는 1분 정도 걸릴 수 있습니다. - 내부 전용 서비스에는 도메인을 추가할 수 없습니다. 먼저 공개 주소를 켜세요.
터미널 탭은 내부 전용 서비스에서도 다른 서비스와 똑같이 작동합니다.
비동기 통신
위의 호출은 응답을 기다립니다. 서비스가 작업을 넘기고 바로 다음 일을 해야 할 때(백그라운드 작업, 여러 서비스가 반응하는 이벤트)는 대신 큐나 메시지 브로커(Valkey, NATS 또는 RabbitMQ)로 메시지를 보내세요. 이벤트와 큐를 참고하세요.
인스턴스 여러 개
호출하는 서비스가 인스턴스 여러 개로 실행 중이면, 내부 이름은 실행 중인 모든 인스턴스로 연결되고 연결은 인스턴스들에 나뉩니다.
연결을 열어 두고 재사용하는 클라이언트(keep-alive 연결 풀)는 같은 인스턴스로 계속 요청을 보낼 수 있으며, 새 연결은 다시 나뉩니다. 정상적인 동작이며 따로 설정할 필요가 없습니다.
타임아웃과 재시도
배포 중이거나 자동 확장으로 인스턴스가 중지될 때 처리 중이던 요청이 실패할 수 있습니다. 다음 두 가지 습관으로 서비스 간 호출을 안정적으로 만들 수 있습니다.
- 짧은 타임아웃 — 몇 초로 두어, 요청이 간 인스턴스가 중지되는 중에도 호출이 멈춰 있지 않게 합니다.
- 반복해도 안전한 요청(
GET으로 데이터 읽기)은 짧은 간격을 두고 한두 번 재시도합니다. 데이터를 바꾸는 요청(결제, 주문)은 API가 반복된 요청과 새 요청을 구분할 수 있을 때만 반복하세요.
예: Node.js
const api = process.env.RIVERVO_API_URL
async function getWithRetry(url, attempts = 3) {
for (let i = 1; ; i++) {
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) })
if (res.status < 500 || i === attempts) return res
} catch (err) {
if (i === attempts) throw err
}
await new Promise((resolve) => setTimeout(resolve, 200 * i))
}
}
const res = await getWithRetry(`${api}/orders`)
const orders = await res.json()예: Laravel
config/services.php에 주소를 넣습니다.
'api' => [
'url' => env('RIVERVO_API_URL'),
],그다음 config()로 읽습니다. 운영 환경에서는 설정이 캐시되므로 설정 파일 밖에서 호출한 env()는 아무 값도 반환하지 않습니다.
use Illuminate\Support\Facades\Http;
$orders = Http::timeout(5)
->retry(2, 200)
->get(config('services.api.url').'/orders')
->json();timeout(5)는 최대 5초를 기다리고, retry(2, 200)은 200ms 간격으로 최대 2번 시도합니다.
예: Python
import os
import requests
API = os.environ["RIVERVO_API_URL"]
orders = requests.get(f"{API}/orders", timeout=5).json()GET 재시도 포함:
import os
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
API = os.environ["RIVERVO_API_URL"]
session = requests.Session()
retry = Retry(total=2, backoff_factor=0.2, allowed_methods=["GET"], status_forcelist=[502, 503, 504])
session.mount("http://", HTTPAdapter(max_retries=retry))
orders = session.get(f"{API}/orders", timeout=5).json()실패한 GET(연결 오류 또는 502, 503, 504 응답)은 매번 조금씩 늘어나는 짧은 간격을 두고 최대 2번 반복됩니다.
명령줄과 Rivervo MCP에서
rivervo apps와 서비스 상세 정보에는 각 웹 서비스의 내부 주소와 공개 주소 여부가 표시됩니다.rivervo services set-public <service> on|off로 공개 주소를 전환합니다. 관리자 역할과 전체 접근 토큰이 필요합니다.- Rivervo MCP에서는 같은 전환 기능이
set_public_address도구입니다.
토큰과 명령줄은 개발자 도구를 참고하세요.