跳到主要内容

快速入门指南

从零开始搭建 FreeKit Pro Modules 开发环境，5 分钟完成首次运行

📋 前置要求​

必须安装​

  • .NET SDK 10.0+ - 下载地址
  • MySQL 8.4+ 或 SQL Server / PostgreSQL / SQLite - 主数据库
  • Redis 7.x+ - 缓存服务
  • Git - 版本控制

可选安装​

  • MeiliSearch 1.0+ - 全文搜索（用于 CmsKit 搜索功能）
  • Docker Desktop - 容器化部署
  • Visual Studio 2026 或 VS Code - 推荐 IDE 或 Rider

🚀 快速启动（5 分钟）​

步骤 1：克隆项目​

git clone https://github.com/luoyunchong/FreeKitModules.git
cd FreeKitModules

步骤 2：还原依赖​

dotnet restore

步骤 3：配置数据库连接​

编辑 src/Services/Host/FreeKit.Host/appsettings.Development.json：

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

步骤 4：启动服务​

cd src/Services/Host/FreeKit.Host
dotnet watch --launch-profile https-dev

步骤 5：访问应用​

打开浏览器访问：

🐳 使用 Docker 快速启动（推荐）​

如果你已安装 Docker Desktop，可以一键启动所有服务：

# 在项目根目录执行
docker-compose up -d

这将自动启动：

  • ✅ MySQL 8.4 数据库
  • ✅ Redis 7.4 缓存
  • ✅ RabbitMQ 3.13 消息队列
  • ✅ MeiliSearch v1.13 搜索引擎
  • ✅ FreeKitModules 主服务（10800+ 端口）

等待 2-3 分钟后访问 http://localhost:18080/api-docs/index.html

📝 你的第一个 API 调用​

1. 注册用户（BasicIdentity 模块）​

请求：

POST https://localhost:5001/api/Account/Register
Content-Type: application/json

{
  "userName": "testuser",
  "nickName": "测试用户",
  "email": "test@example.com",
  "password": "Password123!",
  "phoneNumber": "13800138000"
}

响应：

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userName": "testuser",
    "nickName": "测试用户"
  }
}

2. 登录获取 Token​

请求：

POST https://localhost:5001/api/Account/Login
Content-Type: application/json

{
  "userName": "testuser",
  "password": "Password123!"
}

响应：

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "expires_in": 7200
  }
}

3. 创建待办事项（需要认证）​

请求：

POST https://localhost:5001/api/ToDo
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "message": "我的第一个待办事项",
  "notificationTime": "2025-12-01T09:00:00"
}

响应：

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "我的第一个待办事项",
    "isDone": false,
    "createTime": "2025-11-24T10:30:00"
  }
}

4. 发布文章（CmsKit 模块）​

请求：

POST https://localhost:5001/api/Article
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "title": "我的第一篇文章",
  "content": "# Hello FreeKitModules\n\n这是我的第一篇文章！",
  "excerpt": "文章摘要",
  "keywords": "入门,教程",
  "editor": 1,
  "articleSource": 1
}

🔧 开发环境配置​

配置 appsettings.Development.json​

完整配置示例：

{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=FreeKitModules;User Id=sa;Password=YourPassword;TrustServerCertificate=true;"
  },
  "Redis": {
    "ConnectionString": "localhost:6379,password=,defaultDatabase=0"
  },
  "MeiliSearch": {
    "Host": "http://localhost:7700",
    "ApiKey": "masterKey"
  },
  "JWT": {
    "SecretKey": "YourSecretKeyAtLeast32Characters!!",
    "Issuer": "FreeKitModules",
    "Audience": "FreeKitModules.API",
    "ExpireMinutes": 120
  },
  "CAP": {
    "Enabled": true
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    }
  }
}

FreeSql 数据库自动同步​

开发环境会自动同步数据库表结构，无需手动创建表。

在 Program.cs 中已配置：

// 开发环境自动同步表结构
fsql.CodeFirst.SyncStructure<Article>();
fsql.CodeFirst.SyncStructure<User>();
// ... 其他实体

生产环境请关闭自动同步：

fsql.CodeFirst.IsAutoSyncStructure = false;

📦 模块说明​

已包含的模块​

模块说明端口
CmsKit内容社区平台（文章、沸点、评论）5001
BasicIdentity基础认证（登录、注册、Token）5001
Identity完整权限系统（角色、权限、在线用户）5001
Platform平台服务（代码生成、热点聚合）5001
ToDo待办事项管理5001
IM即时通讯（开发中）5001

添加新模块​

参考各模块的 IModuleStartup 实现代码中的模块注册顺序。

🧪 运行测试​

# 运行所有单元测试
dotnet test

# 运行指定项目测试
dotnet test tests/FreeKit.CmsKit.Tests

# 生成覆盖率报告
dotnet test /p:CollectCoverage=true /p:CoverageReportFormat=lcov

📚 下一步​

恭喜！你已经成功运行了 FreeKitModules。接下来可以：

  1. 阅读架构文档：CmsKit 系统架构
  2. 了解开发约定：参考各模块 README 与项目结构说明
  3. 查看 API 文档：API 接口文档
  4. 遇到问题：常见问题 FAQ

❓ 需要帮助？​

祝你开发愉快！ 🎉