在日常开发与多模块联调中，最令开发者疲惫的是维护繁琐的微服务启停脚本：数据库容器挂掉、缓存配置不一致、前端与网关端口错位等问题层出不穷。

BitzOrcas.Modern 深度集成了 .NET Aspire AppHost。借助 Aspire 的现代编排能力，开发者仅需一条命令即可同时拉起 SQL Server、Redis、RabbitMQ、MinIO 等基础设施容器与后端 API Host、YARP Gateway 及 Web 前端实例，并自动挂载工业级的集中式 OpenTelemetry 链路追踪仪表盘。

开发调试与编排架构拓扑

第一步：首选启动模式 — .NET Aspire AppHost 一键编排

在仓库根目录下执行启动命令，AppHost 将自动完成全栈服务的拓扑编排与启动依赖检测：

# 启动 Aspire AppHost
dotnet run --project src/Hosts/BitzOrcas.AppHost

启动完成后，控制台将输出 Aspire Dashboard 的控制面板 URL（通常为 http://localhost:15000 或随机高位端口）。在浏览器中打开该面板，可获得完整的系统可观测性支持：

Resources 资源全景：实时监控所有后端进程与容器的运行状态、内存开销与环境变量；
Structured Traces 全链路追踪：可视化查看每个入站 HTTP 请求穿透 10 级应用管道与数据库 SQL 执行的微秒级甘特图；
Console & Structured Logs 集中日志：聚合所有子系统的结构化日志流，支持按 TraceId 实现秒级过滤。

第二步：开发数据生命周期管理（持久化与重置）

频繁重启 AppHost 不应导致已录入的业务数据丢失。AppHost 提供了细粒度的数据卷持久化与数据播种开关：

1. 团队日常功能开发：开启数据卷持久化（推荐默认）

开启数据库与对象存储持久化，确保测试案件、租户配置与上传文档跨会话保留：

# 仅持久化数据库与文件存储（避免旧 Redis 脏缓存或 RabbitMQ 堆积消息影响本地调试）
ASPIRE_PERSIST_SQLSERVER=true ASPIRE_PERSIST_MINIO=true dotnet run --project src/Hosts/BitzOrcas.AppHost

# 或一键持久化全量基础设施卷
ASPIRE_PERSIST_VOLUMES=true dotnet run --project src/Hosts/BitzOrcas.AppHost

2. 破坏性重构环境自愈：受控清库与重播种子（Reset Schema）

当实体模型发生重大破坏性变更，需要将本地数据库彻底清空并重新灌入演示数据时：

# 仅允许在 Development 本地环境执行，生产与预发环境会自动触发安全熔断
BITZORCAS_ASPIRE_RESET_SCHEMA=true BITZORCAS_ASPIRE_SEED_DEMO=true dotnet run --project src/Hosts/BitzOrcas.AppHost

第三步：不停服维护与单组件秒级热重启

在日常迭代中，若对 API 进行了代码改动，无需停止整个 Aspire 编排网络：

Dashboard 秒级热重启：在 Aspire Dashboard 界面中找到 bitzorcas-api，点击右上角的 Restart 按钮。底层 SQL Server 与 Redis 容器保持运行，API 实例将在 1 秒内完成热重启；
独立重放系统种子（—seed-only）：当修改了菜单权限清单或主数据字典 CSV，需要在不重启进程的前提下增量同步至数据库时，另开终端运行：
增量重放系统种子
```
dotnet run --project src/Hosts/BitzOrcas.Api -- --seed-only
```

第四步：备用启动模式 — 独立 Shell 模式（Non-Aspire）

在低资源开发机或轻量级 CI 自动化构建流水线中，可直接使用原生 Docker Compose + dotnet run 组合：

# 1. 后台拉起基础设施容器
docker compose up -d

# 2. 启动 API Host (监听 http://localhost:6881 与 https://localhost:6883)
dotnet run --project src/Hosts/BitzOrcas.Api

第五步：发起首个认证请求

服务就绪后，可通过浏览器访问平台宿主内置的交互式 API 文档：http://localhost:6881/scalar/v1。

在终端中按顺序执行以下请求，验证端到端健康与认证管道：

1. 存活探针与获取密码加密公钥

# 1. 验证 API 宿主健康存活探针 (返回 HTTP 200 与健康状态 JSON)
curl -i http://localhost:6881/health/live

# 2. 获取服务端 RSA-OAEP 加密公钥与 keyId
curl -i http://localhost:6881/api/auth/cipher-key

公钥端点响应示例：

{
  "keyId": "cipher-key-20260923",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n",
  "serverTime": 1790188800
}

2. 发起登录请求

登录接口 POST /api/auth/login 拒绝接收明文口令。开发环境下推荐直接使用 Web 前端管理端页面（http://localhost:6800）或 Scalar 文档调试页进行自动加密登录。

使用预置超级管理员账号：

用户名：admin
开发默认口令：Admin@2026（由前端自动获取公钥组装 nonce|timestamp|Admin@2026 并完成 RSA-OAEP 加密后提交）

3. 携带颁发的 JWT 校验当前身份信息

登录成功后，从响应的 JSON 中提取 accessToken 并调用用户自省端点：

curl http://localhost:6881/api/auth/me \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>"

响应将完整输出当前用户的租户标识、用户基本信息及包含 RootCrossTenant 与 TenantDataScope 在内的多维授权快照：

{
  "userId": "1000000000000001",
  "tenantId": "1000001",
  "userName": "admin",
  "displayName": "系统超级管理员",
  "roles": ["SuperAdmin"],
  "permissions": [
    "Identity.User.Search",
    "Identity.User.Create",
    "Authorization.Role.Grant",
    "Authorization.TenantDataScope",
    "Authorization.RootCrossTenant"
  ]
}

至此，你已完整走通了 BitzOrcas.Modern 从拓扑编排、数据持久化到安全身份认证的全生命周期。接下来可查阅预置演示账号与口令注入契约或进入实战教程构建你的第一个垂直切片业务。