Giao tiếp giữa các service: địa chỉ nội bộ và service chỉ nội bộ.
Cách các service của một ứng dụng kết nối với nhau qua địa chỉ nội bộ, các biến RIVERVO_<NAME>_URL, service không có địa chỉ công khai, nhiều instance, timeout và thử lại, kèm ví dụ cho Node.js, Laravel và Python.
Các service của một ứng dụng giao tiếp trực tiếp với nhau, không đi qua internet. Website có thể gọi API của chính nó, worker có thể gọi một service nội bộ — và lưu lượng này miễn phí: không được tính là lưu lượng.
Các ví dụ dưới đây dùng hai web service: web — website khách truy cập mở, có Public address, và api — chỉ web và các service khác gọi tới, đặt là Internal only.
Địa chỉ nội bộ
Mỗi web service — có địa chỉ công khai hay chỉ nội bộ — đều có Internal address dạng http://<service-name>:<port>, ví dụ http://api:8080. Địa chỉ hiển thị trên trang của service và ở Tổng quan của ứng dụng, kèm nút sao chép và gợi ý «Other services of this application reach it here — no internet, no traffic charges.»
- Cổng là 8080 với service build từ repository, hoặc Port bạn đặt với service từ image có sẵn.
- Chỉ các service của cùng ứng dụng mới truy cập được địa chỉ này. Không mở được từ internet hay từ ứng dụng khác.
- Địa chỉ dùng
http://. Kết nối nằm trong ứng dụng, nên không cần thiết lập chứng chỉ.
Biến chứa địa chỉ
Bạn không cần chép địa chỉ vào mã. Mỗi service mã của ứng dụng — web service, background worker và tác vụ theo lịch — nhận một biến chứa địa chỉ nội bộ của từng web service khác trong ứng dụng:
RIVERVO_<NAME>_URL=http://<name>:<port>
NAME là tên service viết hoa, dấu gạch ngang được đổi thành _:
| Service | Biến |
|---|---|
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 (từ image có sẵn, cổng 7700) | RIVERVO_SEARCH_URL=http://search:7700 |
- Service không nhận biến cho chính nó.
- Cơ sở dữ liệu và Valkey giữ
RIVERVO_<NAME>_URLriêng với địa chỉ kết nối. Tên service là duy nhất trong ứng dụng, nên các tên không bao giờ trùng nhau. - Các biến được liệt kê ở tab Variables trong nhóm Set automatically. Như mọi biến tự động, biến của riêng bạn (hoặc biến dùng chung) cùng tên sẽ thay thế nó — xem Biến môi trường.
- Biến đến với service ở lần deploy tiếp theo. Khi bạn thêm web service mới hoặc đổi tên, các service khác nhận biến mới hoặc biến đã đổi ở lần deploy tiếp theo của chúng. Hãy deploy lại để chúng nhận biến, ví dụ bằng
rivervo deploy <app> --no-build— lệnh này khởi động lại phiên bản đang chạy với biến mới, không cần build lại.
Service chỉ nội bộ
Web service mà chỉ các service khác của ứng dụng gọi tới — API phía sau website, backend quản trị, công cụ tìm kiếm — không cần có mặt trên internet. Hãy đặt nó là Internal only:
| Public address | Internal only | |
|---|---|---|
Địa chỉ trên internet https://<name>.rivervo.app | có | không |
| Tên miền riêng | có | không |
| Bản xem trước theo nhánh | có | không |
| Địa chỉ nội bộ cho các service khác | có | có |
| Nhiều instance và tự động mở rộng, log, giám sát, kiểm tra tình trạng | có | có |
Service chỉ nội bộ chạy như mọi service khác; chỉ các service khác của cùng ứng dụng mới truy cập được.
Chọn khi tạo service
Khi tạo web service — kể cả service đầu tiên của ứng dụng mới, từ repository, mẫu hay image có sẵn — hãy chọn Public address hoặc Internal only. Không có lựa chọn nào được chọn sẵn, nên quyết định luôn thuộc về bạn. Background worker, tác vụ theo lịch và cơ sở dữ liệu không bao giờ có địa chỉ công khai, nên không có lựa chọn này.
Service tạo trước khi có lựa chọn này vẫn giữ địa chỉ công khai.
Đổi sau
Service → Cài đặt → Public address: gạt công tắc và xác nhận. Chỉ Administrator của ứng dụng hoặc chủ tài khoản mới đổi được. Không có gì khởi động lại.
- Chuyển sang chỉ nội bộ bị từ chối khi service còn tên miền đang kết nối — hãy gỡ chúng ở tab Tên miền của service trước. Bản xem trước cũng phải tắt trước.
- Bật lại địa chỉ công khai sẽ trả lại cho service cùng địa chỉ
https://<name>.rivervo.app. Chứng chỉ có thể mất khoảng một phút. - Thêm tên miền vào service chỉ nội bộ sẽ bị từ chối — hãy bật địa chỉ công khai trước.
Tab Terminal trong service chỉ nội bộ hoạt động như ở mọi service khác.
Giao tiếp bất đồng bộ
Các lời gọi ở trên đều chờ phản hồi. Khi một service cần giao việc rồi làm tiếp — tác vụ nền, sự kiện mà nhiều service cùng phản ứng — hãy gửi tin nhắn qua queue hoặc message broker: Valkey, NATS hoặc RabbitMQ. Xem Sự kiện và queue.
Nhiều instance
Khi service được gọi chạy nhiều instance, tên nội bộ của nó dẫn tới tất cả instance đang chạy, và các kết nối được chia giữa chúng.
Client giữ kết nối mở và dùng lại (pool kết nối keep-alive) có thể tiếp tục gửi request tới cùng một instance; kết nối mới sẽ lại được chia đều. Điều này là bình thường và không cần thiết lập gì.
Timeout và thử lại
Trong lúc deploy, hoặc khi tự động mở rộng dừng một instance, request đang xử lý có thể thất bại. Hai thói quen giúp lời gọi giữa các service đáng tin cậy:
- Timeout ngắn — vài giây, để lời gọi không bao giờ bị treo khi instance nhận nó đang dừng.
- Thử lại một hoặc hai lần sau một khoảng nghỉ ngắn, với request an toàn để lặp lại — đọc dữ liệu bằng
GET. Không lặp lại request thay đổi dữ liệu (thanh toán, đơn hàng) trừ khi API của bạn phân biệt được request lặp lại với request mới.
Ví dụ: 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()Ví dụ: Laravel
Đặt địa chỉ trong config/services.php:
'api' => [
'url' => env('RIVERVO_API_URL'),
],Sau đó đọc bằng config(). Ở production, cấu hình được cache, và env() gọi ngoài các tệp cấu hình sẽ không trả về gì:
use Illuminate\Support\Facades\Http;
$orders = Http::timeout(5)
->retry(2, 200)
->get(config('services.api.url').'/orders')
->json();timeout(5) chờ tối đa 5 giây; retry(2, 200) thử tối đa 2 lần, cách nhau 200 ms.
Ví dụ: Python
import os
import requests
API = os.environ["RIVERVO_API_URL"]
orders = requests.get(f"{API}/orders", timeout=5).json()Với thử lại cho 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 thất bại — lỗi kết nối hoặc phản hồi 502, 503 hay 504 — được lặp lại tối đa 2 lần, với khoảng nghỉ ngắn tăng dần mỗi lần.
Từ dòng lệnh và Rivervo MCP
rivervo appsvà thông tin chi tiết của service hiển thị địa chỉ nội bộ của từng web service và cho biết service có địa chỉ công khai hay không.rivervo services set-public <service> on|offbật/tắt địa chỉ công khai. Lệnh cần vai trò Administrator và token có Full access.- Trong Rivervo MCP, công tắc tương tự là công cụ
set_public_address.
Xem Công cụ cho nhà phát triển về token và dòng lệnh.