代码安装与本地配置：容器基础设施与数据库初始化

在大型分布式系统的研发协作中，“在我的电脑上能跑，但在你的电脑上报错”是最常见的效能杀手。导致这种现象的根源通常有三个：

• 容器镜像版本漂移：使用 :latest 或松散标签，导致团队成员在不同时间拉取的数据库与中间件版本产生隐式行为差异；
• 配置与凭据硬编码：直接在 appsettings.json 中明文提交本地开发连接串，一旦被开发者误带入代码库，极易引发严重安全事故；
• 数据库初始化脚本乱序：依赖人工按顺序执行庞大的 SQL 脚本，在遇到多租户种子数据与复合外键约束时极易因执行中断而陷入脏状态。

BitzOrcas.Modern 贯彻“环境即代码与零信任配置”原则。本地基础设施采用按 SHA-256 摘要严格锁定的容器组，核心宿主内置编译期 Schema 初始化与种子执行引擎，确保任意开发节点均可在 3 分钟内拉起一份绝对确定性的本地沙箱。

基础设施与初始化执行时序

从克隆代码到 API 宿主就绪，完整的初始化流水线由以下四个环环相扣的步骤构成：

第一步：克隆代码仓库并还原依赖

首先克隆仓库并还原 .NET 10 与 C# 14 编译所需的全部 NuGet 包。BitzOrcas 启用了 Central Package Management (CPM)，所有依赖版本由根目录的 Directory.Packages.props 严格统一锁定：

# 克隆代码仓库
git clone https://github.com/shbitz/BitzOrcas.Modern.git
cd BitzOrcas.Modern

# 还原全解决方案 NuGet 依赖包 (确保已安装 .NET 10 SDK)
dotnet restore

第二步：拉起受治理的 Docker 基础设施

仓库根目录提供了已预置高可用拓扑的 docker-compose.yml。为了消灭版本漂移，关键基础设施镜像均按镜像摘要（Image Digest）锁定：

# 启动本地基础中间件
docker compose up -d

# 检查容器运行状态与健康检查探针 (STATUS 需为 healthy 或 Up)
docker compose ps

本地容器矩阵规划与端口分配如下：

第三步：注入本地开发配置（零信任原则）

在 src/Hosts/BitzOrcas.Api/appsettings.json 中，ConnectionStrings:Default 被刻意保留为空字符串。数据库连接串属于环境事实，绝不应当写入版本控制系统。

在本地开发时，推荐通过当前终端会话的环境变量（Environment Variables）注入。在 .NET 配置体系中，冒号分层键通过双下划线 (__) 进行映射：

# macOS / Linux 终端配置 (按需替换密码或数据库名称)
export ConnectionStrings__Default="Server=localhost,1433;Database=BitzOrcas_Dev;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;MultipleActiveResultSets=True;"

若在 Windows PowerShell 环境中操作：

$env:ConnectionStrings__Default="Server=localhost,1433;Database=BitzOrcas_Dev;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;MultipleActiveResultSets=True;"

连接串中的关键参数考量：

• TrustServerCertificate=True：允许在本地开发阶段信任 SQL Server 容器生成的自签名 TLS 证书；
• MultipleActiveResultSets=True (MARS)：允许在同一个物理连接上交错执行多个异步查询，支撑复杂领域聚合的加载。

第四步：执行幂等建库、灌入种子并启动

BitzOrcas 的主宿主内嵌了轻量级 Schema 编排引擎。它不需要预先安装任何第三方迁移工具，通过命令行标志参数直接驱动初始化：

# 确保全量代码通过编译期源生成器装配
dotnet build

# 执行建表、建立索引、创建 CAP Outbox 发件箱表并灌入系统种子数据
dotnet run --project src/Hosts/BitzOrcas.Api -- --init-schema

命令执行机制剖析

1. --init-schema：

   • 检查目标数据库是否存在；若不存在则自动执行 CREATE DATABASE；
   • 收集所有已注册模块的 Fluent 映射元数据，执行幂等建表与索引创建；
   • 初始化 CAP 事务性发件箱专用表（cap.published 与 cap.received）；
   • 执行 ISeedStep 清单，创建内置超级管理员（admin / Admin@2026）与预置租户 1000001（Demo Tenant）；
   • 执行完毕后自动平稳退出，进程返回退出码 0。

2. --seed-only：

   • 适用于数据库表结构已由 DBA 预建完毕、仅需在全新环境中补全系统字典、权限元数据与演示租户数据的场景。

初始化完成后，即可正常启动 API 宿主进程：

dotnet run --project src/Hosts/BitzOrcas.Api

控制台将输出类似以下日志，证明服务已成功绑定本地端口并就绪：

[02:40:00 INF] Now listening on: http://localhost:6881
[02:40:00 INF] Now listening on: https://localhost:6883
[02:40:00 INF] Application started. Press Ctrl+C to shut down.
[02:40:00 INF] Hosting environment: Development

常见初始化排错速查

1. SQL Server 端口 1433 冲突

若本机已安装本地 SQL Server 实例，Docker 容器可能因端口已被监听而启动失败：

# 检查 1433 端口占用情况
lsof -i :1433   # macOS / Linux
netstat -ano | findstr 1433   # Windows

解法：在 docker-compose.yml 中将主机映射端口改为 11433:1433，并同步修改环境变量连接串中的端口号 Server=localhost,11433;...。

2. 数据库连接握手超时（Container Not Ready）

SQL Server 容器启动后，其内部引擎初始化通常需要 10~15 秒。若在容器刚启动时立即运行 --init-schema，可能遇到 SqlException: A connection was successfully established with the server, but then an error occurred during the pre-login handshake。
解法：运行 docker compose ps 确认 SQL Server 容器状态显示为 (healthy) 后，再执行建库命令。