立即开始

服务间通信:内部地址与仅限内部的服务。

同一应用的服务如何通过内部地址互相访问、RIVERVO_<NAME>_URL 变量、没有公开地址的服务、多实例,以及超时和重试,附 Node.js、Laravel 和 Python 示例。

2 分钟阅读

同一应用的服务之间直接通信,无需经过互联网。网站可以调用自己的 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 是大写的服务名称,短横线替换为 _:

服务变量
apiRIVERVO_API_URL=http://api:8080
admin-apiRIVERVO_ADMIN_API_URL=http://admin-api:8080
webRIVERVO_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 工具。

有关令牌和命令行,请参阅开发者工具。

还有疑问?

和我们聊聊——AI 即时回答,需要时工程师加入,全天候在线。

联系技术支持