跳到主要内容

常见问题 FAQ

以下问题按当前代码结构整理，默认前提是你运行的是 src\Services\Host 下的宿主项目。

启动与环境​

启动后访问地址不对​

先看宿主的 launchSettings.json 和 ASPNETCORE_PATHBASE。

当前默认地址：

宿主本地默认地址
FreeKit.Hosthttps://localhost:7002/kit_api
FreeKit.Job.Hosthttps://localhost:7000/job_api
FreeKit.MessageHandler.Hosthttps://localhost:7003/message_api
FreeKit.HealthCheckshttps://localhost:5005

所以 FreeKit.Host 的 Swagger 不是 /swagger，而是：

https://localhost:7002/kit_api/swagger

端口被占用​

可以先找占用端口的 PID，再停止具体进程：

Get-NetTCPConnection -LocalPort 7002 | Select-Object LocalPort, OwningProcess
Stop-Process -Id <PID>

数据库与 FreeSql​

启动时报数据库连接失败​

优先检查：

  1. ConnectionStrings.MySql
  2. ShortUrlConnectionStrings.MySql
  3. LogConnectionStrings.MySql
  4. Redis 连接 ConnectionStrings.Redis

开发环境下 FreeKit.Host 常见最小配置：

"ConnectionStrings": {
  "DefaultDB": "0",
  "MySql": "Data Source=localhost;Port=3306;User ID=root;Password=<password>;Initial Catalog=freekit;Charset=utf8mb4;SslMode=none;",
  "Redis": "localhost:6379,password=<password>,defaultDatabase=1"
}

表没有自动创建​

当前项目不是在 Program.cs 里集中同步表，而是分散在各模块 IModuleStartup.Configure(...) 中。

例如：

  • CmsKitModuleStartup.Configure(...)
  • IdentityModuleStartup.Configure(...)
  • PlatformModuleStartup.Configure(...)

如果新实体没建表，先检查它是否被加入对应模块的 SyncStructure(...)。

改了实体但表结构没跟上​

FreeSql 的 CodeFirst 适合建表与补充简单字段，不要把它当成完整数据库迁移系统。生产环境下建议自己控制 DDL 变更。

模块注册​

加了模块代码但主宿主没生效​

默认主宿主加载模块的来源不是“扫描所有项目”，而是 src\Services\Host\FreeKit.DI\E.cs：

builder.UseFreeKit(
    moduleTypeMap: E.Modules,
    extraAssemblies: new[] { typeof(Program).Assembly }
);

如果模块没生效，通常少了下面两步中的一步：

  1. FreeKit.DI.csproj 没有添加项目引用
  2. E.Modules 没有注册 <Module>ModuleStartup

为什么 Mall 代码在仓库里，但主宿主没接口​

因为当前默认 E.Modules 并没有注册 MallModuleStartup。仓库有模块代码，不代表默认主宿主已经启用它。

路由与接口​

为什么旧文档里的 /api/Account/Login 访问不到​

因为当前代码路由前缀已经按模块拆分，典型前缀如下：

  • api/identity/*
  • api/cms/*
  • api/cms/admin/*
  • api/plat/*
  • api/im/*
  • api/v1/*

例如认证接口对应的是：

api/identity/account

而不是旧的无模块前缀写法。

如何确认某个接口到底在哪里​

优先顺序：

  1. 主宿主 Swagger / RapiDoc
  2. 对应模块控制器上的 [Route(...)]
  3. 该模块 README 或专题文档

CAP、消息与任务​

Compose 启动后为什么还有功能不可用​

一些能力依赖额外服务：

  • 搜索能力依赖 MeiliSearch
  • 异步消息依赖 RabbitMQ
  • 定时任务依赖 Job 宿主

主 API 宿主启动成功，不等于 Job / Message 相关能力已经完整可用。

FreeScheduler 入口在哪里​

当前代码里：

  • 主宿主：/kit_api/job
  • Job 宿主：/job_api/job

如果主宿主没看到任务页面，先确认访问路径包含了 ASPNETCORE_PATHBASE。

认证与权限​

401 / 403 怎么区分​

当前项目通过 KitAuthorizationMiddlewareResultHandler 返回标准 ApiResponse：

  • 10000：认证失败
  • 10001：无权限
  • 10050：Token 过期

先区分是没登录、Token 过期，还是策略权限不足。

Docker 部署​

run_freekit_pro_modules 读取哪个环境文件​

脚本优先读取：

  1. build/compose/freekit_pro_modules/.env.local
  2. 否则读取 build/compose/freekit_pro_modules/.env

Compose 为什么没有 HealthChecks UI​

因为当前 docker-compose.yml 只包含：

  • mysql
  • redis
  • rabbitmq
  • meilisearch
  • host
  • job
  • message

独立 FreeKit.HealthChecks 服务需要单独运行。

文档与代码不一致怎么办​

以代码为准，优先检查：

  1. Program.cs
  2. E.cs
  3. 控制器 [Route]
  4. appsettings*.json
  5. build/compose/freekit_pro_modules/docker-compose.yml