网络与端点

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

Aspire 让您可以在本地开发、测试和调试云原生应用。内循环（inner loop）网络是其中的关键一环：它让应用之间能够互相通信，而不需要您去关心实际端口。

代理心智模型

把 Aspire 的网络想象成酒店前台：

• 客户（调用 API 的代码）总是去找前台（代理），地址固定且已知。
• 前台把请求转给实际的房间（您的服务），无论它在哪里。
• 如果有多个房间（副本），前台负责决定连哪一个。

客户端  ──►  代理 :5000  ──►  服务 :52847
                        └──►  服务 :52848

这个设计解决了三类问题：

问题	代理如何解决
端口冲突	两个服务不能同时用 5000 端口，但代理可以为每个服务分配不同端口。
多副本	服务有多实例时，代理自动承担负载均衡。
服务重启	服务在新端口上重启时，代理地址保持不变。

关键认知

您永远不需要知道服务实际运行在哪个端口。使用代理地址即可，其余交给 Aspire。

端点（Endpoints）

端点描述应用与依赖之间的连接信息：服务名、主机端口、协议、环境变量等。Aspire 会根据资源配置自动创建端点，也可以用 WithEndpoint 显式添加。

// 自动创建（HTTP 项目默认就有）
var api = builder.AddProject<Projects.Api>("api");

// 显式添加
var catalogApi = builder.AddContainer("catalog-api", "catalog-api")
    .WithHttpEndpoint(targetPort: 8080, name: "http")
    .WithHttpsEndpoint(targetPort: 8443, name: "https");

// 只是标记为需要外部访问，不新增端点
builder.AddProject<Projects.Web>("web")
    .WithExternalHttpEndpoints();

常用端点 API

API	说明
WithHttpEndpoint(port, targetPort, name)	添加 HTTP 端点。targetPort 是容器内端口。
WithHttpsEndpoint(port, targetPort, name)	添加 HTTPS 端点。
WithEndpoint(port, targetPort, name, ...)	添加通用端点（TCP 等）。
WithExternalHttpEndpoints()	把资源上所有 HTTP 端点标记为对外可见。
WithEndpointProxySupport(false)	关闭该端点的代理。

代理端口 vs 目标端口

• targetPort：容器/进程内部监听的端口。
• port：代理对外暴露的端口。不指定时由 Aspire 自动分配（随机端口），这正是它避免端口冲突的方式。

无代理端点

把端点的 IsProxied 设为 false 后，客户端会直连资源，而不经过 Aspire 的代理。

var api = builder.AddProject<Projects.Api>("api")
    .WithEndpoint("https", e => e.IsProxied = false);

Aspire 13.4 起的默认行为

从 Aspire 13.4 开始，持久化（persistent）的可执行文件与项目资源上的端点默认无代理；持久化容器则仍与「会话容器」一样默认使用代理端点。

容器网络

当您添加一个或多个容器资源时，Aspire 会创建一个专用的容器桥接网络，用于容器之间的服务发现。这个虚拟网络提供 DNS 服务，容器可以通过 DNS 名互相寻址。

网络的生命周期取决于容器资源的生存期：

• 如果所有容器都是会话生存期，网络随 AppHost 结束而销毁。
• 只要有一个容器是持久化生存期，网络就会被保留，以便下次运行时复用。

资源生存期

生存期	行为	适用场景
会话（Session）	默认。AppHost 启动时创建，AppHost 退出时销毁。	临时依赖、无需跨运行保留状态的进程。
持久化（Persistent）	AppHost 退出后资源继续运行，下次运行可复用同一实例。	启动耗时长、需要稳定本地端点、需要保留数据的资源。

// 容器资源（长期支持的写法）
var pg = builder.AddPostgres("pg")
    .WithLifetime(ContainerLifetime.Persistent);

// 需要回到默认行为时
pg.WithLifetime(ContainerLifetime.Session);

实验性 API

面向容器、可执行文件与项目的共享生存期 API（WithSessionLifetime、WithPersistentLifetime 等）目前是实验性的，会产生诊断 ASPIREPERSISTENCE001。容器场景请继续使用 WithLifetime(ContainerLifetime.*)。

排查端口冲突

提示 “Address already in use”

1. 如果同时运行了多个 Aspire 应用，先用 aspire ps 查看，再用 aspire stop 停止多余的实例。

2. 查找占用端口的进程：

   PowerShell

   netstat -ano | findstr :5000
   # 记下最后一列的 PID，然后：
   taskkill /PID <pid> /F

   Bash

   lsof -i :5000
   kill -9 <pid>

3. 若确实需要固定端口，请显式指定 port 参数。

:::

下一步

• 服务发现
• 数据持久化
• 健康检查