服务间通信:内部地址与仅限内部的服务。
同一应用的服务如何通过内部地址互相访问、RIVERVO_<NAME>_URL 变量、没有公开地址的服务、多实例,以及超时和重试,附 Node.js、Laravel 和 Python 示例。
同一应用的服务之间直接通信,无需经过互联网。网站可以调用自己的 API,Worker 可以调用内部服务——这部分流量 免费:不计入流量。
以下示例使用两个 Web 服务:web 是访客打开的网站,设置为 公开地址;api 只被 web 和其他服务调用,设置为 仅限内部。
内部地址
每个 Web 服务——无论有公开地址还是仅限内部——都有一个 http://<service-name>:<port> 形式的 内部地址,例如 http://api:8080。它显示在服务页面和应用的 概览 中,带有复制按钮和提示:“本应用的其他服务通过此地址访问——不经过互联网,不收取流量费用。”
- 从仓库构建的服务端口为 8080;来自现成镜像的服务则为您设置的 端口。
- 只有同一应用的服务可以访问此地址。无法从互联网或其他应用访问。
- 该地址使用
http://。连接始终在应用内部,因此无需配置证书。
包含地址的变量
您无需将地址复制到代码中。应用的每个代码服务——Web 服务、后台 Worker 和定时作业——都会获得一个变量,其中包含应用中 其他每个 Web 服务 的内部地址:
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。服务名称在应用内唯一,因此名称不会冲突。 - 这些变量列在 变量 标签页的 自动设置 变量中。与所有自动变量一样,您自己的同名变量(或共享变量)会取而代之——请参阅环境变量。
- 变量 在服务下一次部署时 生效。添加新的 Web 服务或重命名服务后,其他服务会在下一次部署时获得新的或更改后的变量。请重新部署这些服务以使其生效,例如使用
rivervo deploy <app> --no-build——它会以新变量重新启动当前运行的版本,无需重新构建。
仅限内部的服务
只被应用其他服务调用的 Web 服务——网站背后的 API、管理后台、搜索引擎——无需暴露在互联网上。将其设置为 仅限内部:
| 公开地址 | 仅限内部 | |
|---|---|---|
互联网地址 https://<name>.rivervo.app | 是 | 否 |
| 您自己的域名 | 是 | 否 |
| 分支预览 | 是 | 否 |
| 供其他服务使用的内部地址 | 是 | 是 |
| 多实例和自动扩缩容、日志、监控、健康检查 | 是 | 是 |
仅限内部的服务与其他服务运行方式相同;只有同一应用的其他服务可以访问它。
创建服务时选择
创建 Web 服务 时——包括新应用的第一个服务,无论来自仓库、模板还是现成镜像——请选择 公开地址 或 仅限内部。不预先选定任何选项,因此始终由您决定。后台 Worker、定时作业和数据库从不拥有公开地址,因此无需选择。
在此选项推出之前创建的服务保留其公开地址。
之后切换
在服务 → 设置 → 公开地址 中:切换开关并确认。只有应用的 管理员 或账户所有者可以更改。不会重启任何服务。
- 服务已连接域名时,切换为仅限内部 会被拒绝——请先在其 域名 标签页中删除域名。预览也必须先关闭。
- 重新开启公开地址 后,服务会恢复相同的
https://<name>.rivervo.app地址。证书可能需要约一分钟。 - 无法为仅限内部的服务添加域名——请先开启其公开地址。
终端 标签页在仅限内部的服务中与其他服务一样可用。
异步通信
上述调用会等待响应。当服务需要移交工作后继续执行——后台任务、多个服务都需要响应的事件——请改用队列或消息代理发送消息: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) 最多尝试 2 次,每次间隔 200 毫秒。
示例: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和服务详情会显示每个 Web 服务的内部地址以及是否有公开地址。rivervo services set-public <service> on|off用于切换公开地址。需要管理员角色和具有 完全访问 权限的令牌。- 在 Rivervo MCP 中,相同的开关是
set_public_address工具。
有关令牌和命令行,请参阅开发者工具。