在复杂的企业级多模块单体与容器化工程中，因环境漂移、端口冲突或代码生成缓存引起的异常往往会中断开发节奏。
本文档基于底座工程的物理事实，提供高频故障诊断矩阵与秒级自愈指令集。
平台真实服务与端口拓扑矩阵
1. 端口冲突与进程释放（Address Already in Use）
当启动时出现 System.IO.IOException: Failed to bind to address: address already in use，说明目标端口已被其他进程占用。请对照以下真实端口矩阵定位并终止占用进程：
| 服务名称 | 默认端口 | macOS / Linux 端口释放命令 | Windows PowerShell 释放命令 |
|---|---|---|---|
| API Host | 6881 / 6883 | lsof -ti :6881,6883 | xargs kill -9 | Get-NetTCPConnection -LocalPort 6881 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } |
| YARP Gateway | 6880 | lsof -ti :6880 | xargs kill -9 | Get-NetTCPConnection -LocalPort 6880 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } |
| Web 前端 | 6800 | lsof -ti :6800 | xargs kill -9 | Get-NetTCPConnection -LocalPort 6800 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } |
| SQL Server | 1433 / 14333 | lsof -ti :1433 | xargs kill -9 | Get-NetTCPConnection -LocalPort 1433 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } |
| Redis | 6379 | lsof -ti :6379 | xargs kill -9 | Get-NetTCPConnection -LocalPort 6379 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } |
| RabbitMQ | 5672 / 15672 | lsof -ti :5672,15672 | xargs kill -9 | Get-NetTCPConnection -LocalPort 5672 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } |
2. 数据库连接异常与握手超时（Cannot Open Database）
常见报错：
Microsoft.Data.SqlClient.SqlException: Cannot open database "BitzOrcas_Dev" requested by the login.A connection was successfully established with the server, but then an error occurred during the pre-login handshake.
自愈排查路径：
- 核实容器运行健康状态：
运行
docker compose ps，确认 SQL Server 容器的状态显示为(healthy)。SQL Server 首次拉起通常需要 10~15 秒完成内部数据库初始化，未进入健康状态前运行建库命令会导致握手超时。 - Apple Silicon (M1/M2/M3/M4) 转译延迟：
SQL Server 官方镜像仅提供
linux/amd64架构。在 macOS 上通过 Docker Desktop 或 OrbStack 运行时依赖 Rosetta 2 指令集转译，冷启动可能需要 30 秒以上，请预留充裕的容器初始化时间。 - 数据库尚未创建：
若报错
Cannot open database "BitzOrcas_Dev"，说明数据库尚未完成初始化。请先执行带建库参数的命令：Terminal window dotnet run --project src/Hosts/BitzOrcas.Api -- --init-schema
3. Roslyn Source Generator 增量生成缓存未更新
现象：
在切片中新增了 [GenerateEndpoint] 命令、或在聚合根上添加了 [BitzTable] / [BitzColumn] 映射注解，但编译时 IDE 报错找不到生成的扩展方法，或 Minimal API 端点返回 404。
根因： JetBrains Rider 或 Visual Studio 在后台运行的 Roslyn 常驻分析器进程（Analyzer Server）缓存了旧版虚拟语法树，未及时触发增量编译。
自愈方案：
# 1. 深度清理全解决方案的 bin 与 obj 目录git clean -xfd -e "!*.env*" src/ tests/
# 2. 强制全量重新构建 (禁用增量构建以迫使生成器重新扫描语法树)dotnet build --no-incremental4. HTTPS 本地开发证书不受信任（SSL Error）
现象：
- 前端向
https://localhost:6883发起 API 请求时控制台报错net::ERR_CERT_AUTHORITY_INVALID； - 浏览器打开 Scalar 文档页面时显示红字安全警告。
自愈方案：
# 1. 清理本地全部旧证书与失效信任链dotnet dev-certs https --clean
# 2. 重新签发并注册至系统受信任根证书存储区dotnet dev-certs https --trust对于 Linux 用户，由于系统无统一的受信任根证书存储区，建议在本地开发环境直接使用 HTTP 协议访问 http://localhost:6881。
5. 环境变量双下划线层级映射陷阱
现象：
在终端执行了 export ConnectionStrings:Default="..."，但程序启动依然提示连接字符串为空。
根因：
在 Bash、Zsh 或大多数 Linux Shell 中，环境变量名不支持包含冒号 :。在 .NET 配置体系中，系统级环境变量必须使用双下划线 (__) 代替冒号：
# 错误写法 (冒号无法被标准 Shell 解析或会被截断)export ConnectionStrings:Default="Server=..."
# 正确写法 (双下划线在 .NET 中自动映射为 ConnectionStrings:Default)export ConnectionStrings__Default="Server=localhost,1433;Database=BitzOrcas_Dev;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;MultipleActiveResultSets=True;"系统启动时将无缝将 ConnectionStrings__Default 映射至 IConfiguration["ConnectionStrings:Default"]。