render-private-services

Render 私有服务

私有服务与 Web 服务相同，但没有公开 URL。它们只能由同一私有网络（同一区域 + 工作区）中的其他 Render 服务访问。可将其用于内部 API、微服务、gRPC 服务、边车进程，以及任何不应直接暴露于互联网的服务。

适用场景

• 在公共网关后构建内部 API 或微服务
• 运行仅供自己的服务调用的 gRPC、TCP 或其他非 HTTP 服务
• 部署基础设施组件（Elasticsearch、ClickHouse、RabbitMQ）
• 在私有服务和后台工作进程之间进行选择

对于面向公众的 HTTP 服务，请使用 render-web-services。对于不接收任何流量的服务，请使用 render-background-workers。

配置或排查私有网络连接之前，请阅读 references/private-networking.md。 附加或更改持久磁盘之前，请阅读 references/persistent-disks.md。 在私有服务、Web 服务和工作进程之间进行选择时，请阅读 references/service-types.md。

私有服务与后台工作进程

标准	私有服务	后台工作进程
绑定到端口	是（必需）	否
接收私有网络流量	是	否
发送出站流量	是	是
有内部主机名	是	否
使用场景	内部 API、gRPC、TCP 服务	队列消费者、异步处理器

经验法则： 如果进程监听端口并由其他服务调用，它就是私有服务。如果进程从队列拉取任务且从不接收请求，它就是后台工作进程。

私有服务的工作方式

• 没有 onrender.com 子域名，无法从互联网访问
• 同一区域和工作区中的服务可通过私有网络上的 <service-name>:<port> 访问
• 可监听任何端口（受限系统端口除外），不限于 HTTP 或端口 10000
• 支持任何协议：HTTP、gRPC、TCP、WebSocket、自定义二进制协议
• 与 Web 服务采用相同的构建和部署生命周期（构建命令、启动命令、预部署）
• 支持持久磁盘和 Docker 运行时。使用磁盘的私有服务保持为单实例，且无法使用自动扩缩容或零停机部署；详情请参阅 references/persistent-disks.md。

连接到私有服务

其他服务通过其内部主机名和端口引用私有服务：

http://<service-name>:<port>

在 Blueprints 中，使用 fromService 配置地址：

- key: INTERNAL_API_URL
  fromService:
    name: my-api
    type: pserv
    property: hostport

pserv 可用的 fromService 属性：

属性	值
host	内部主机名（例如 my-api）
port	服务监听的端口
hostport	组合后的 host:port（例如 my-api:10000）

也可以使用 envVarKey（而非 property）引用私有服务中的特定环境变量。

端口绑定

私有服务必须至少绑定一个端口。如果进程不需要接收流量，请改为创建后台工作进程。

• 绑定到 0.0.0.0（不要绑定到 127.0.0.1 或 localhost）
• PORT 环境变量默认值为 10000；选择其他端口之前，请在 references/private-networking.md 中确认当前限制
• 对于非 HTTP 协议（gRPC、TCP），请将服务器配置为使用所需端口，并告知使用方 hostport

Blueprint 配置

services:
  - type: pserv
    name: internal-api
    runtime: node
    region: oregon
    plan: starter
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: db
          property: connectionString

微服务模式（网关 + 内部服务）

services:
  - type: web
    name: gateway
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci && npm run build
    startCommand: npm start
    envVars:
      - key: USER_SERVICE_URL
        fromService:
          name: user-service
          type: pserv
          property: hostport
      - key: BILLING_SERVICE_URL
        fromService:
          name: billing-service
          type: pserv
          property: hostport

  - type: pserv
    name: user-service
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci
    startCommand: node server.js
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: db
          property: connectionString

  - type: pserv
    name: billing-service
    runtime: python
    plan: starter
    region: oregon
    buildCommand: pip install -r requirements.txt
    startCommand: gunicorn billing:app
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: db
          property: connectionString

参考资料

文档	内容
references/private-networking.md	当前私有网络范围、地址、端口、服务发现、隔离和故障排查
references/patterns.md	微服务拓扑、gRPC 设置和边车模式
references/persistent-disks.md	附加到服务的磁盘限制、配置、容量规划和快照
references/service-types.md	服务类型选择和执行模型

相关技能

• render-web-services — 公共 HTTP 服务
• render-networking — 私有网络、DNS、服务发现
• render-background-workers — 不接收流量的服务
• render-blueprints — 完整的 render.yaml 架构、fromService 接线
• render-scaling — 私有服务的计算计划和自动扩缩

获取当前文档

每当此技能要求你查阅当前的 Render 文档时：

1. 使用可用的 URL 获取工具或 HTTP 客户端（例如 curl）直接获取链接的 Markdown 文档。不要用网页搜索摘要代替文档。
2. 确认获取成功并返回了预期文档，然后阅读其内容。仅保存文件或打印文件路径并不足够。
3. 如果请求失败，或你的工具无法读取 Markdown 响应，请打开并阅读链接的 HTML 版本。
4. 如果两个版本都无法获取，请说明当前参考文档不可用，并遵循技能中的特定主题回退方案。仅将随附指南用于稳定的限制，不要猜测平台上可能变动的细节。

如果任务需要多个参考文档，请对每个文档应用此流程，并区分已验证的文档与仍不可用的文档。