CodeSpirit 开发环境搭建及启动指南

概述

本指南将帮助您快速搭建CodeSpirit（码灵）低代码框架的开发环境。CodeSpirit基于 .NET 10 和 Aspire 13.0 构建，通过简单的几个步骤即可启动完整的开发环境。
最后更新: 2025年12月22日
框架版本: v2.0.0

快速开始

前置要求

• 操作系统: Windows 10/11, macOS 12+, 或 Linux (Ubuntu 20.04+)
  
• CPU: Intel i5 或 AMD Ryzen 5 及以上（推荐i7/Ryzen 7）
  
• 内存: 16GB RAM（推荐32GB）
  
• 存储: 至少20GB可用空间（SSD推荐）
  

注意: CodeSpirit默认使用GreptimeDB进行审计日志存储和搜索。Elasticsearch为可选组件，如需使用请参考相关配置文档。

1. 安装 .NET 10 SDK

Windows

1. # 使用 winget 安装
2. winget install Microsoft.DotNet.SDK.10
4. # 或下载安装包
5. # https://dotnet.microsoft.com/download/dotnet/10.0

复制代码

macOS

1. # 使用 Homebrew
2. brew install --cask dotnet-sdk
4. # 或下载安装包
5. # https://dotnet.microsoft.com/download/dotnet/10.0

复制代码

Linux (Ubuntu)

1. # 添加微软包源
2. wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
3. sudo dpkg -i packages-microsoft-prod.deb
4. sudo apt-get update
5. sudo apt-get install -y dotnet-sdk-10.0

复制代码

验证安装

1. dotnet --version
2. # 应显示 10.x.x

复制代码

2. 安装开发工具

Visual Studio 2026 (推荐)

• 下载地址: https://visualstudio.microsoft.com/vs/
  
• 选择工作负载：ASP.NET 和 Web 开发
  

或者 Visual Studio Code

1. # Windows
2. winget install Microsoft.VisualStudioCode
4. # macOS
5. brew install --cask visual-studio-code
7. # Linux
8. sudo snap install code --classic

复制代码

VS Code必需扩展：

1. code --install-extension ms-dotnettools.csharp
2. code --install-extension ms-dotnettools.vscode-dotnet-runtime

复制代码

3. 安装Docker Desktop

• 下载地址: https://www.docker.com/products/docker-desktop
  
• 安装后启动Docker Desktop
  

验证安装：

1. docker --version

复制代码

项目启动

1. 克隆项目

1. git clone https://gitee.com/magicodes/code-spirit.git
2. cd code-spirit

复制代码

2. 启动基础服务

CodeSpirit使用Aspire自动管理所有依赖服务，无需手动启动Docker容器：

1. # Aspire会自动启动以下服务：
2. # - MySQL/SQL Server (根据配置选择，端口: 3306/1433)
3. # - Redis (端口: 6380)
4. # - RabbitMQ (端口: 5672, 管理界面: 15672)
5. # - GreptimeDB (端口: 4000/4001)
6. # - Seq日志服务 (端口: 5341)

复制代码

服务说明:

• MySQL/SQL Server: 主数据库存储（根据DatabaseType配置选择）
  
• Redis: 缓存和会话存储（端口: 6380）
  
• RabbitMQ: 消息队列服务（管理界面端口: 15672）
  
• GreptimeDB: 时序数据库，用于审计日志存储（HTTP端口: 4000, gRPC端口: 4001）
  
• Seq: 结构化日志服务（端口: 5341）
  

3. 运行项目

使用.NET Aspire（推荐）

1. # 进入AppHost项目目录
2. cd Src/CodeSpirit.AppHost
4. # 运行Aspire应用
5. dotnet run

复制代码

如果是正常启动，将看到以下缤纷的控制台输出：

启动后访问：

• Aspire Dashboard: http://localhost:17109（自动打开）
  
• Web应用: https://localhost:7120（启动后显示具体端口）
  

注意:

• 实际端口号可能因系统配置而异，请查看Aspire Dashboard获取准确的端口信息。
  
• 如何登录页没有正常呈现，请按照下面的必填参数配置进行配置。
  

或者使用Visual Studio

• 打开 CodeSpirit.sln
  
• 设置 CodeSpirit.AppHost 为启动项目
  
• 按 F5 运行
  
  
  
  注意，需确保以下服务均正常启动：
  
  
  
  

项目结构

CodeSpirit采用Clean Architecture设计，项目结构如下：

1. CodeSpirit/
2. ├── Src/
3. │   ├── ApiServices/                     # API服务（解决方案文件夹）
4. │   │   ├── CodeSpirit.IdentityApi/      # 身份认证API
5. │   │   ├── CodeSpirit.ExamApi/          # 考试系统API  
6. │   │   ├── CodeSpirit.MessagingApi/     # 消息服务API
7. │   │   ├── CodeSpirit.ConfigCenter/    # 配置中心API
8. │   │   ├── CodeSpirit.FileStorageApi/  # 文件存储API
9. │   │   ├── CodeSpirit.SurveyApi/        # 问卷调查API
10. │   │   ├── CodeSpirit.ApprovalApi/      # 审批工作流API
11. │   │   ├── CodeSpirit.PathfinderApi/    # AI目标管理API
12. │   │   └── CodeSpirit.AiCardsApi/       # AI卡片API
13. │   ├── Components/                     # 组件库
14. │   │   ├── CodeSpirit.Aggregator/       # 聚合器组件
15. │   │   ├── CodeSpirit.AiFormFill/       # AI表单智能填充组件
16. │   │   ├── CodeSpirit.Amis/             # UI生成引擎
17. │   │   ├── CodeSpirit.Authorization/    # 权限组件
18. │   │   ├── CodeSpirit.Audit/            # 审计组件
19. │   │   ├── CodeSpirit.Caching/          # 分布式缓存组件
20. │   │   ├── CodeSpirit.Charts/           # 智能图表组件
21. │   │   ├── CodeSpirit.ConfigCenter.Client/ # 配置中心客户端
22. │   │   ├── CodeSpirit.LLM/              # 大语言模型组件
23. │   │   ├── CodeSpirit.Messaging/        # 消息队列组件
24. │   │   ├── CodeSpirit.MultiTenant/      # 多租户组件
25. │   │   ├── CodeSpirit.Navigation/       # 导航组件
26. │   │   ├── CodeSpirit.PdfGeneration/    # PDF生成组件
27. │   │   ├── CodeSpirit.ScheduledTasks/   # 定时任务组件
28. │   │   ├── CodeSpirit.Settings/         # 设置管理组件
29. │   │   ├── CodeSpirit.Shared/           # 组件共享库
30. │   │   └── CodeSpirit.UdlCards/         # UDL卡片组件
31. │   ├── CodeSpirit.AppHost/              # Aspire应用宿主
32. │   ├── CodeSpirit.Core/                 # 核心定义
33. │   ├── CodeSpirit.ServiceDefaults/      # 服务默认配置
34. │   ├── CodeSpirit.Shared/               # 全局共享库
35. │   └── CodeSpirit.Web/                  # Web前端项目
36. ├── Tests/                               # 测试项目
37. ├── Docs/                                # 项目文档
38. ├── k8s/                                 # Kubernetes部署文件
39. └── CodeSpirit.sln                       # 解决方案文件

复制代码

默认配置

项目使用以下默认配置，由.NET Aspire自动管理：
数据库连接

• 数据库类型: 支持MySQL和SQL Server两种数据库（通过DatabaseType配置选择）
  
• MySQL: 端口3306，由Aspire自动配置
  可以从资源面板访问管理UI（phpmyadmin）：
  
  
  
  
  
  
  
• SQL Server: 端口1433，由Aspire自动配置
  
• 数据库: 自动创建和迁移
  
• 连接字符串: 由Aspire自动管理
  

缓存和消息队列

• Redis: localhost:6380（具体见管理UI）
  
• RabbitMQ: localhost:5672 (管理界面: http://localhost:15672, 用户名/密码: admin/Password123)
  
  
  
  

其他服务端口

• GreptimeDB:
  
  
  
  • HTTP端口: localhost:4000
    
  • gRPC端口: localhost:4001
    
  • 健康检查: http://localhost:4000/health
    
  
  
• Seq日志服务: localhost:5341（具体端口见资源面板）
  
  
  
  
• Redis Commander: 通过Aspire Dashboard访问
  

必填参数配置

CodeSpirit 使用 .NET Aspire 的参数管理机制来配置敏感信息和环境相关参数。在首次启动前，您需要配置以下必填参数。提示UI如下：

参数配置方式

Aspire 支持两种参数配置方式，配置系统会按以下优先级读取（高优先级会覆盖低优先级）：

• User Secrets（开发环境推荐，避免提交敏感信息到代码库）
  
• appsettings.json（开发环境备选方案）
  

提示: 对于敏感信息（如 API 密钥），强烈推荐使用 User Secrets，避免将密钥提交到代码库。

必填参数列表

LLM 配置参数

以下参数用于配置通用 LLM 服务（如 AI 卡片、智能审批等功能）：
参数名称说明是否必填默认值llm-ApiKeyLLM API密钥✅ 必填无llm-ApiBaseUrlLLM API基础地址可选https://dashscope.aliyuncs.com/compatible-mode/v1llm-ModelNameLLM模型名称可选qwen-flashllm-TimeoutSeconds请求超时时间（秒）可选120llm-MaxTokens最大Token数可选2048llm-UseProxy是否使用代理可选falsellm-ProxyAddress代理地址可选空字符串AI表单填充 LLM 配置参数

以下参数用于配置 AI 表单智能填充功能：
参数名称说明是否必填默认值ai-form-fill-llm-ApiKeyAI表单填充LLM API密钥✅ 必填无ai-form-fill-llm-ApiBaseUrlAPI基础地址可选https://dashscope.aliyuncs.com/compatible-mode/v1ai-form-fill-llm-ModelName模型名称可选qwen3-max-previewai-form-fill-llm-DisableThinking禁用思考模式可选trueai-form-fill-llm-ResponseFormatType响应格式类型可选json_objectai-form-fill-llm-Temperature温度参数可选0.1ai-form-fill-llm-TopPTopP参数可选0.9ai-form-fill-llm-EnableStreaming启用流式响应可选true其他可选参数

以下参数已有默认值，通常无需修改：
参数名称说明默认值jwt-SecretKeyJWT密钥ECBF8FA013844D77AE041A6800D7FF8Fjwt-IssuerJWT颁发者codespirit.comjwt-AudienceJWT受众CodeSpiritmysql-passwordMySQL密码Password123sqlserver-passwordSQL Server密码P@ssword123456rabbitmq-usernameRabbitMQ用户名adminrabbitmq-passwordRabbitMQ密码Password123配置方法

方法一：使用 User Secrets（推荐开发环境）

使用 .NET User Secrets 可以安全地存储敏感信息，无需担心提交到代码库：

1. # 进入 AppHost 项目目录
2. cd Src/CodeSpirit.AppHost
4. # 初始化 User Secrets（如果尚未初始化）
5. dotnet user-secrets init
7. # 设置 LLM API 密钥
8. dotnet user-secrets set "llm-ApiKey" "your-llm-api-key-here"
10. # 设置 AI 表单填充 LLM API 密钥
11. dotnet user-secrets set "ai-form-fill-llm-ApiKey" "your-ai-form-fill-llm-api-key-here"
13. # 清除所有密钥
14. # dotnet user-secrets clear

复制代码

方法二：使用 appsettings.json（开发环境备选）

编辑 Src/CodeSpirit.AppHost/appsettings.json 文件，添加参数配置：

1. {
2.   "DatabaseType": "MySql",
3.   "Logging": {
4.     "LogLevel": {
5.       "Default": "Information",
6.       "Microsoft.AspNetCore": "Warning",
7.       "Aspire.Hosting.Dcp": "Warning"
8.     }
9.   },
10.   "llm-ApiKey": "your-llm-api-key-here",
11.   "ai-form-fill-llm-ApiKey": "your-ai-form-fill-llm-api-key-here"
12. }

复制代码

⚠️ 重要提示:

• 如果使用 appsettings.json 配置敏感信息，请确保该文件已添加到 .gitignore 中
  
• 或者创建 appsettings.Local.json 文件（该文件默认已在 .gitignore 中），避免将 API 密钥提交到代码库
  
• 强烈推荐使用 User Secrets 方式，更安全且不会误提交
  

获取 API 密钥

阿里云通义千问（DashScope）

开发阶段免费额度完全够用：

• 访问 阿里云 DashScope
  
• 注册/登录账号
  
• 创建 API Key
  
• 将 API Key 配置到上述参数中
  

<blockquote>

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！