数据持久化

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

默认情况下，Aspire 中的容器资源是会话级的：AppHost 退出时容器被销毁，里面的数据也一并消失。对于数据库、存储、消息队列这类需要跨多次运行保留数据的资源，就需要显式配置持久化。

Aspire 提供两种方式：数据卷（volumes）与绑定挂载（bind mounts）。

选择哪种方式

方式	数据位置	能否从宿主机直接访问	典型用途
数据卷	Docker 管理的卷	❌	数据库数据，追求性能与可移植性。
绑定挂载	宿主机指定目录	✅	需要直接编辑/查看文件，例如导入脚本。

使用数据卷

数据卷由容器运行时管理，通常位于宿主机上某个由运行时掌控的目录中。

var sql = builder.AddSqlServer("sql")
    .WithDataVolume();

var sqldb = sql.AddDatabase("sqldb");

WithDataVolume() 会创建一个以资源名命名的卷并挂载到该资源约定的数据目录。也可以显式指定卷名：

var pg = builder.AddPostgres("pg")
    .WithDataVolume("aspire-pg-data");

数据卷在 Kubernetes 上

部署到 Kubernetes 时，数据卷会被映射为持久卷（PersistentVolume）。相关配置（存储类、访问模式、容量）可以在发布阶段调整，详见 Kubernetes 部署。

使用绑定挂载

绑定挂载让您既能从容器内访问数据，也能从宿主机的进程访问。挂载建立后，您可以在宿主机上把文件复制进去，容器里就能立即看到。

WithBindMount 接受三个参数：

参数	含义
source	宿主机上要挂载的目录路径。
target	容器内的目标路径。
isReadOnly	数据是否只读，默认 false。

var sql = builder.AddSqlServer("sql")
    .WithBindMount(source: @"C:\SqlServer\Data", target: "/var/opt/mssql")
    .AddDatabase("sqldb");

部分容器资源还提供了更简洁的便捷 API。下面的写法与上面等价：

var sql = builder.AddSqlServer("sql")
    .WithDataBindMount(source: @"C:\SqlServer\Data")
    .AddDatabase("sqldb");

跨平台路径

绑定挂载的源路径是宿主机路径。团队协作时，硬编码 C:\... 或 /Users/... 会在其他成员的机器上失败。建议改用数据卷，或通过外部参数传入路径。

持久化密码（很重要）

使用数据卷时，数据库的密码在多次启动之间必须保持一致。Aspire 默认会为「服务器型」资源自动生成随机密码：

var sql = builder.AddSqlServer("sql")
    .WithDataVolume();

var sqldb = sql.AddDatabase("sqldb");

由于调用 AddSqlServer 时没有提供密码，Aspire 会自动生成一个。

自动生成的密码不是持久的

这个密码每次运行 AppHost 都会变化。一旦配合数据卷使用，数据卷里保存了旧密码创建的数据，新密码将无法访问，典型表现是启动后立刻报认证失败。

解决办法一：用用户机密覆盖

aspire secret set Parameters:sql-password <password>

命名规则为 Parameters:{资源名}-password：

资源类型	托管包	示例资源名	覆盖键
MySQL	Aspire.Hosting.MySql	mysql	Parameters:mysql-password
Oracle	Aspire.Hosting.Oracle	oracle	Parameters:oracle-password
PostgreSQL	Aspire.Hosting.PostgreSQL	postgresql	Parameters:postgresql-password
RabbitMQ	Aspire.Hosting.RabbitMq	rabbitmq	Parameters:rabbitmq-password
SQL Server	Aspire.Hosting.SqlServer	sql	Parameters:sql-password

解决办法二：显式创建参数

var sqlPassword = builder.AddParameter("sql-password", secret: true);

var sql = builder.AddSqlServer("sql", password: sqlPassword)
    .WithDataVolume();

var sqldb = sql.AddDatabase("sqldb");

详见外部参数与机密。

让容器跨运行存活

数据卷只保证数据不丢，但容器本身在 AppHost 退出后仍会被销毁（下次运行会重新创建并挂载同一个卷）。如果您希望容器本身也保持运行：

var pg = builder.AddPostgres("pg")
    .WithDataVolume()
    .WithLifetime(ContainerLifetime.Persistent);

持久化生存期的容器会跨 AppHost 运行复用，同时它也会让容器网络被保留。详见网络与端点。

清理数据

删除数据卷（Docker）

docker volume ls
docker volume rm <volume-name>

重置整个 Aspire 环境

aspire stop
aspire cache clear

删除数据卷不可恢复

docker volume rm 会永久删除其中的数据。执行前请确认没有需要保留的内容。

下一步

• 网络与端点
• 外部参数与机密
• 仪表板简介