跳到主要内容

快速开始

本页完成主解决方案构建和 FreeKit.Host 首次启动。若只想通过 Docker 运行整套环境，直接前往 FreeKit 部署。

环境要求​

工具要求用途
.NET SDK10.0+构建和运行所有主项目
Git支持 submodule拉取 src/FreeKit
MySQL8.x主数据、任务与日志等数据源
Redis7.x 建议缓存、调度和 SignalR 连接映射
RabbitMQ按需CAP 消息传输；也可按宿主配置使用其他模式
MeiliSearch按需CmsKit 全文搜索，MeiliSearch:Enable=false 时可关闭

仓库 Compose 当前固定的基础设施镜像为 MySQL 8.4、Redis 7.4、RabbitMQ 3.13 和 MeiliSearch 1.13。

1. 克隆并初始化子模块​

git clone --recurse-submodules https://github.com/luoyunchong/freekit-pro-modules.git
cd freekit-pro-modules

如果仓库已经克隆但 src/FreeKit 为空：

git submodule update --init --recursive

2. 还原并构建​

dotnet restore FreeKitModules.slnx
dotnet build FreeKitModules.slnx -c Release

FreeKitModules.slnx 不包含 auth/、basic/、cg/ 的独立解决方案；需要修改这些项目时分别构建其 .slnx。详见仓库地图。

3. 准备基础设施​

可复用仓库 Compose，只启动依赖服务：

docker compose \
  --env-file build/compose/freekit_pro_modules/.env \
  -f build/compose/freekit_pro_modules/docker-compose.yml \
  up -d mysql redis rabbitmq meilisearch

.env 中包含本地 Compose 所需端口和凭据。请为自己的环境创建私有覆盖文件，不要把真实生产凭据写入文档或提交新的明文配置。

4. 配置本地连接​

开发宿主从 src/Services/Host/FreeKit.Host/appsettings.Development.json 读取默认值。建议通过 User Secrets 或环境变量覆盖，而不是把个人凭据提交到仓库：

$env:ConnectionStrings__MySql = 'Data Source=localhost;Port=13306;User ID=root;Password=<password>;Initial Catalog=freekit;Charset=utf8mb4;SslMode=none'
$env:ConnectionStrings__Redis = 'localhost:16379,password=<password>,defaultDatabase=1'
$env:MeiliSearch__Enable = 'false'

Linux/macOS 使用同名环境变量即可。双下划线 __ 对应 JSON 层级分隔符。

5. 启动主宿主​

dotnet run --project src/Services/Host/FreeKit.Host --launch-profile https-dev
入口地址
Swagger UIhttps://localhost:7000/kit_api/swagger
RapiDochttps://localhost:7000/kit_api/r
健康检查https://localhost:7000/kit_api/health
FreeScheduler UIhttps://localhost:7000/kit_api/job/

/kit_api 来自 appsettings.Development.json 的 ASPNETCORE_PATHBASE。如果通过 --no-launch-profile 或其他环境运行，应以实际监听地址和 PathBase 为准。

6. 了解开发初始化​

在 DEBUG 编译下，主宿主会执行模块的调试期结构同步，并调用 MigrationStartAsync()。这方便本地开发，但生产环境不能依赖 Debug CodeFirst 完成破坏性结构变更；生产发布应使用显式 DDL/迁移和回滚方案。

7. 运行测试​

dotnet test FreeKitModules.slnx

只修改文档时还需要：

cd docs-site
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build

常见问题​

现象首先检查
src/FreeKit 项目不存在是否执行 git submodule update --init --recursive
数据库连接失败当前环境、连接字符串端口、Compose 容器状态
打开 /swagger 返回 404开发环境实际路径是 /kit_api/swagger
模块 Controller 未出现主 Host 是否引用 *.HttpApi，hostModules 是否注册对应 HttpApi startup
只有健康检查没有 Trace/health 的 Trace 在应用侧被过滤，改访问普通 API

下一步​