bitzorcas
中 EN

Guide

故障排除

BitzOrcas.Modern 首次运行和日常开发中的常见问题与修复方案。

Last updated

以下每一条都是实际遇到的故障模式，以 症状 → 原因 → 修复 的形式呈现。

首次运行

端口冲突

症状： API 无法绑定端口，或浏览器在熟悉的端口上显示了不同的应用。

以下是 API 固定占用的端口（来自 launchSettings.json）：

端口服务
7132 / 5196API https / http

SQL Server 和 RabbitMQ 使用 Aspire 分配的动态主机端口——查看 Aspire 仪表板获取实际映射。本地安装的 SQL Server（端口 1433）不会冲突，因为 Aspire 会将其映射到不同的主机端口。

查找并终止占用端口的进程：

Terminal window
# macOS / Linux
lsof -i :7132
kill <pid>

容器与 Aspire

基础设施容器（SQL Server、RabbitMQ）默认使用 ContainerLifetime.Persistent——它们在 AppHost 关闭后仍然存活。这使得重启更快，但也是以下问题的根源。

SQL Server 容器在 Aspire 版本升级后退出

症状： SQL Server 容器状态为 Exited (1)；日志抱怨来自另一版本的数据。

AppHost 调用 AddSqlServer("sqlserver") 时未固定镜像标签，因此 SQL Server 版本随 Aspire 包默认值变化。你的持久化数据卷是由不同版本初始化的，SQL Server 拒绝在无法读取的数据目录上启动。

清除容器和卷（这会删除所有本地数据——下次启动时 --init-schema 会重建一切）：

Terminal window
# 查找并移除容器 + 卷
docker ps -a | grep sqlserver
docker rm -f <容器-id>
docker volume rm <卷名>

重新启动 AppHost；运行 --init-schema 重建和重新填充数据。

容器因 Docker 网络删除而孤立

症状： Docker Desktop 重启或 Aspire 升级后，容器显示 Exited (255) 或卡在 Starting；日志提及 network ... not found。

持久化容器存活时间超过 Aspire 创建它们的 Docker 网络。移除过期容器并重新启动：

Terminal window
docker rm -f <过期容器>

重新启动 AppHost；它会在新网络上重建容器并重新挂载现有卷。

RabbitMQ 无法启动 — 管理插件版本不兼容

症状： RabbitMQ 容器启动时退出；日志抱怨插件版本不兼容。

清除容器和卷：

Terminal window
docker rm -f <rabbitmq 容器>
docker volume rm <rabbitmq 卷>

数据库与 Schema 初始化

Schema 初始化失败 — “IPersistenceSchemaInitializer not registered”

症状： --init-schema 以退出码 2 结束，日志显示 未注册 IPersistenceSchemaInitializer。

Schema 初始化器需要配置的持久化适配器。确保：

  • ConnectionStrings:Default 已设置（或 SqlSugar:ConnectionString）。
  • RabbitMq:Host 已设置（CAP Outbox 表在同一数据库创建）。
  • 目标 SQL Server 数据库已存在且用户具有 CREATE TABLE / CREATE INDEX 权限。
Terminal window
# appsettings.Development.json 示例连接串
{
  "ConnectionStrings": {
    "Default": "Server=localhost,1433;Database=BitzOrcas;User Id=sa;Password=<YourStrong!Passw0rd>;TrustServerCertificate=True;"
  },
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672
  }
}

种子数据有失败

症状： --seed-demo 以退出码 3 结束，日志显示种子步骤失败。

查看日志输出找出具体哪个步骤失败。常见原因：

  • CSV 文件格式错误或编码问题。
  • 外键约束违反——父表种子尚未运行（检查数字前缀顺序）。
  • 重复键——对部分填充的数据库重新运行种子。种子运行器是幂等的，但某些冲突模式可能需要手动清理。

API 与配置

API 无法启动 — JWT 签名密钥验证

症状： 启动时抛出 OptionsValidationException，消息涉及 JWT 签名密钥。

JWT 认证方案在启动时验证签名密钥——必须存在且至少 32 个字符。appsettings.json 发布时密钥为空；只有 appsettings.Development.json 有开发用默认值。

Terminal window
# 通过环境变量设置真实密钥（>= 32 字符）
JwtOptions__SigningKey="<你的随机32+字符密钥>"

本地可使用 user-secrets 替代；生产环境使用环境变量或密钥管理服务。

RabbitMQ 连接被拒绝

症状： API 启动但 CAP（事件总线）无法连接到 RabbitMQ；日志显示连接被拒绝。

CAP 需要 RabbitMQ 来处理集成事件。如果不使用 Aspire（独立运行 API），确保 RabbitMQ 正在运行且连接配置正确：

{
  "RabbitMq": {
    "Host": "localhost",
    "Port": 5672,
    "UserName": "guest",
    "Password": "guest"
  }
}

如果不需要事件总线，可配置 CAP 使用内存传输（仅限开发环境）。

测试

集成测试失败 — Docker 未运行

症状： 所有测试因 Docker 连接错误而失败。

集成测试使用 Testcontainers 运行（每次测试运行启动 SQL Server + RabbitMQ），因此运行中的 Docker 守护进程是硬性要求。

Terminal window
# 启动 Docker Desktop / docker 守护进程，然后：
dotnet test BitzOrcas.Modern.slnx

如果无法运行 Docker，可单独运行单元测试项目——它们不依赖容器。