为了让新加入团队的开发同学彻底摆脱“配置环境两整天”的困境，BitzOrcas.Modern 采用 .NET Aspire AppHost 作为本地开发的第一编排入口。无需在物理机上手工安装配置 SQL Server 或 Redis，只需一行命令即可在 Docker 中以完全生产对齐的拓扑拉起全部基础设施与应用程序。
本地 Aspire 编排拓扑与真实端口矩阵
真实端口映射与服务矩阵
端口事实源是 src/Hosts/BitzOrcas.AppHost/LocalDevPorts.cs 与各宿主 launchSettings.json：AppHost 只硬钉两个宿主端口——SQL Server 14333 与编排前端 5860；其余资源由 Aspire DCP 动态分配或按配置绑定，连接串经编排注入，不要手工硬编码。
| 服务名称 | 宿主访问地址 | 用途说明 |
|---|---|---|
| Aspire Dashboard | 以启动控制台输出为准 | 统一 OpenTelemetry 仪表盘：容器状态、实时日志、分布式 Tracing 与 Metric 指标（OTLP 16175、资源服务 17037，见 AppHost launchSettings） |
| YARP 网关 | http://localhost:6880 | 前端反向代理与统一路由网关入口 |
| API Host | http://localhost:6881https://localhost:6883 | 核心 Minimal API；文档在 /scalar/v1 |
| Web 前端管理台 | http://localhost:5860 | React 19 + Vite 本地开发热重载服务器 |
| SQL Server 2022 | localhost,14333 | AppHost 持久化路径硬钉端口；用户 sa，口令由 AppHost 参数/环境变量给定，与 docker-compose 的 1433 容器互不冲突 |
| Redis 7 | DCP 动态端口 / 默认 6379 | 连接串由编排注入；docker-compose 场景固定为 localhost:6379 |
| MinIO 对象存储 | DCP 动态端口 / 默认 9000 | 连接串由编排注入；S3 兼容 API 与控制台 |
日常开发启动与数据卷持久化范式
1. 团队日常开发：数据卷持久化模式（推荐）
在日常编码迭代中，我们希望数据库数据在电脑关机或重启 AppHost 后依然保留，避免反复播种与建库：
# 设置持久化环境变量并拉起全套服务ASPIRE_PERSIST_SQLSERVER=true ASPIRE_PERSIST_MINIO=true dotnet run --project src/Hosts/BitzOrcas.AppHost2. 数据库热重置：一键整库清理与重新初始化
当本地测试产生了脏数据、或拉取了最新的破坏性数据库架构变更时，通过专用开关一键整库重建：
# 强制整库重建并重新导入纯净种子数据BITZORCAS_ASPIRE_RESET_SCHEMA=true dotnet run --project src/Hosts/BitzOrcas.AppHost疑难排查与常见本地故障
- 端口冲突报错（
14333或6880/6881被占用）：- 检查本地是否已启动了旧的 Docker 容器或本地物理 SQL Server / IIS 实例；
- 执行
lsof -i :14333或lsof -i :6880查找并终止冲突进程。
- Docker Desktop 资源不足：
- SQL Server 2022 容器要求 Docker 至少分配 2GB 内存，推荐在 Docker Desktop 设置中为 Docker 引擎分配 4GB 以上内存；
- Apple Silicon (M1/M2/M3/M4) 设备上，请确认 Docker 设置中启用了 Rosetta 2 模拟加速以支持
linux/amd64镜像。