时间：2025-12-29 15:07
人气：
作者：admin
本指南将帮助您快速搭建CodeSpirit（码灵）低代码框架的开发环境。CodeSpirit基于 .NET 10 和 Aspire 13.0 构建，通过简单的几个步骤即可启动完整的开发环境。
最后更新: 2025年12月22日
框架版本: v2.0.0
注意: CodeSpirit默认使用GreptimeDB进行审计日志存储和搜索。Elasticsearch为可选组件，如需使用请参考相关配置文档。
# 使用 winget 安装
winget install Microsoft.DotNet.SDK.10
# 或下载安装包
# https://dotnet.microsoft.com/download/dotnet/10.0
# 使用 Homebrew
brew install --cask dotnet-sdk
# 或下载安装包
# https://dotnet.microsoft.com/download/dotnet/10.0
# 添加微软包源
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y dotnet-sdk-10.0
dotnet --version
# 应显示 10.x.x
# Windows
winget install Microsoft.VisualStudioCode
# macOS
brew install --cask visual-studio-code
# Linux
sudo snap install code --classic
VS Code必需扩展：
code --install-extension ms-dotnettools.csharp
code --install-extension ms-dotnettools.vscode-dotnet-runtime
验证安装：
docker --version
git clone https://gitee.com/magicodes/code-spirit.git
cd code-spirit
CodeSpirit使用Aspire自动管理所有依赖服务，无需手动启动Docker容器：
# Aspire会自动启动以下服务：
# - MySQL/SQL Server (根据配置选择，端口: 3306/1433)
# - Redis (端口: 6380)
# - RabbitMQ (端口: 5672, 管理界面: 15672)
# - GreptimeDB (端口: 4000/4001)
# - Seq日志服务 (端口: 5341)
服务说明:
- MySQL/SQL Server: 主数据库存储（根据DatabaseType配置选择）
- Redis: 缓存和会话存储（端口: 6380）
- RabbitMQ: 消息队列服务（管理界面端口: 15672）
- GreptimeDB: 时序数据库，用于审计日志存储（HTTP端口: 4000, gRPC端口: 4001）
- Seq: 结构化日志服务（端口: 5341）
# 进入AppHost项目目录
cd Src/CodeSpirit.AppHost
# 运行Aspire应用
dotnet run
如果是正常启动，将看到以下缤纷的控制台输出：
启动后访问：
注意:
- 实际端口号可能因系统配置而异，请查看Aspire Dashboard获取准确的端口信息。
- 如何登录页没有正常呈现，请按照下面的必填参数配置进行配置。
打开 CodeSpirit.sln
设置 CodeSpirit.AppHost 为启动项目
按 F5 运行
注意，需确保以下服务均正常启动：
CodeSpirit采用Clean Architecture设计，项目结构如下：
CodeSpirit/
├── Src/
│ ├── ApiServices/ # API服务（解决方案文件夹）
│ │ ├── CodeSpirit.IdentityApi/ # 身份认证API
│ │ ├── CodeSpirit.ExamApi/ # 考试系统API
│ │ ├── CodeSpirit.MessagingApi/ # 消息服务API
│ │ ├── CodeSpirit.ConfigCenter/ # 配置中心API
│ │ ├── CodeSpirit.FileStorageApi/ # 文件存储API
│ │ ├── CodeSpirit.SurveyApi/ # 问卷调查API
│ │ ├── CodeSpirit.ApprovalApi/ # 审批工作流API
│ │ ├── CodeSpirit.PathfinderApi/ # AI目标管理API
│ │ └── CodeSpirit.AiCardsApi/ # AI卡片API
│ ├── Components/ # 组件库
│ │ ├── CodeSpirit.Aggregator/ # 聚合器组件
│ │ ├── CodeSpirit.AiFormFill/ # AI表单智能填充组件
│ │ ├── CodeSpirit.Amis/ # UI生成引擎
│ │ ├── CodeSpirit.Authorization/ # 权限组件
│ │ ├── CodeSpirit.Audit/ # 审计组件
│ │ ├── CodeSpirit.Caching/ # 分布式缓存组件
│ │ ├── CodeSpirit.Charts/ # 智能图表组件
│ │ ├── CodeSpirit.ConfigCenter.Client/ # 配置中心客户端
│ │ ├── CodeSpirit.LLM/ # 大语言模型组件
│ │ ├── CodeSpirit.Messaging/ # 消息队列组件
│ │ ├── CodeSpirit.MultiTenant/ # 多租户组件
│ │ ├── CodeSpirit.Navigation/ # 导航组件
│ │ ├── CodeSpirit.PdfGeneration/ # PDF生成组件
│ │ ├── CodeSpirit.ScheduledTasks/ # 定时任务组件
│ │ ├── CodeSpirit.Settings/ # 设置管理组件
│ │ ├── CodeSpirit.Shared/ # 组件共享库
│ │ └── CodeSpirit.UdlCards/ # UDL卡片组件
│ ├── CodeSpirit.AppHost/ # Aspire应用宿主
│ ├── CodeSpirit.Core/ # 核心定义
│ ├── CodeSpirit.ServiceDefaults/ # 服务默认配置
│ ├── CodeSpirit.Shared/ # 全局共享库
│ └── CodeSpirit.Web/ # Web前端项目
├── Tests/ # 测试项目
├── Docs/ # 项目文档
├── k8s/ # Kubernetes部署文件
└── 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:
localhost:4000localhost:4001Seq日志服务: localhost:5341（具体端口见资源面板）
Redis Commander: 通过Aspire Dashboard访问
CodeSpirit 使用 .NET Aspire 的参数管理机制来配置敏感信息和环境相关参数。在首次启动前，您需要配置以下必填参数。提示UI如下：
Aspire 支持两种参数配置方式，配置系统会按以下优先级读取（高优先级会覆盖低优先级）：
提示: 对于敏感信息（如 API 密钥），强烈推荐使用 User Secrets，避免将密钥提交到代码库。
以下参数用于配置通用 LLM 服务（如 AI 卡片、智能审批等功能）：
| 参数名称 | 说明 | 是否必填 | 默认值 |
|---|---|---|---|
llm-ApiKey |
LLM API密钥 | ✅ 必填 | 无 |
llm-ApiBaseUrl |
LLM API基础地址 | 可选 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
llm-ModelName |
LLM模型名称 | 可选 | qwen-flash |
llm-TimeoutSeconds |
请求超时时间（秒） | 可选 | 120 |
llm-MaxTokens |
最大Token数 | 可选 | 2048 |
llm-UseProxy |
是否使用代理 | 可选 | false |
llm-ProxyAddress |
代理地址 | 可选 | 空字符串 |
以下参数用于配置 AI 表单智能填充功能：
| 参数名称 | 说明 | 是否必填 | 默认值 |
|---|---|---|---|
ai-form-fill-llm-ApiKey |
AI表单填充LLM API密钥 | ✅ 必填 | 无 |
ai-form-fill-llm-ApiBaseUrl |
API基础地址 | 可选 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
ai-form-fill-llm-ModelName |
模型名称 | 可选 | qwen3-max-preview |
ai-form-fill-llm-DisableThinking |
禁用思考模式 | 可选 | true |
ai-form-fill-llm-ResponseFormatType |
响应格式类型 | 可选 | json_object |
ai-form-fill-llm-Temperature |
温度参数 | 可选 | 0.1 |
ai-form-fill-llm-TopP |
TopP参数 | 可选 | 0.9 |
ai-form-fill-llm-EnableStreaming |
启用流式响应 | 可选 | true |
以下参数已有默认值，通常无需修改：
| 参数名称 | 说明 | 默认值 |
|---|---|---|
jwt-SecretKey |
JWT密钥 | ECBF8FA013844D77AE041A6800D7FF8F |
jwt-Issuer |
JWT颁发者 | codespirit.com |
jwt-Audience |
JWT受众 | CodeSpirit |
mysql-password |
MySQL密码 | Password123 |
sqlserver-password |
SQL Server密码 | P@ssword123456 |
rabbitmq-username |
RabbitMQ用户名 | admin |
rabbitmq-password |
RabbitMQ密码 | Password123 |
使用 .NET User Secrets 可以安全地存储敏感信息，无需担心提交到代码库：
# 进入 AppHost 项目目录
cd Src/CodeSpirit.AppHost
# 初始化 User Secrets（如果尚未初始化）
dotnet user-secrets init
# 设置 LLM API 密钥
dotnet user-secrets set "llm-ApiKey" "your-llm-api-key-here"
# 设置 AI 表单填充 LLM API 密钥
dotnet user-secrets set "ai-form-fill-llm-ApiKey" "your-ai-form-fill-llm-api-key-here"
# 清除所有密钥
# dotnet user-secrets clear
编辑 Src/CodeSpirit.AppHost/appsettings.json 文件，添加参数配置：
{
"DatabaseType": "MySql",
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Aspire.Hosting.Dcp": "Warning"
}
},
"llm-ApiKey": "your-llm-api-key-here",
"ai-form-fill-llm-ApiKey": "your-ai-form-fill-llm-api-key-here"
}
⚠️ 重要提示:
- 如果使用
appsettings.json配置敏感信息，请确保该文件已添加到.gitignore中- 或者创建
appsettings.Local.json文件（该文件默认已在.gitignore中），避免将 API 密钥提交到代码库- 强烈推荐使用 User Secrets 方式，更安全且不会误提交
开发阶段免费额度完全够用：
???? 推荐阅读：阿里云通义千问免费体验指南 - 详细的注册指南、配置教程和成本分析，帮助您零成本体验 CodeSpirit 的强大 AI 能力！
如果使用 OpenAI 兼容的 API 服务，需要修改以下参数：
使用 User Secrets 配置：
dotnet user-secrets set "llm-ApiBaseUrl" "https://api.openai.com/v1"
dotnet user-secrets set "llm-ModelName" "gpt-4"
dotnet user-secrets set "llm-ApiKey" "your-openai-api-key-here"
或使用 appsettings.json 配置：
{
"llm-ApiBaseUrl": "https://api.openai.com/v1",
"llm-ModelName": "gpt-4",
"llm-ApiKey": "your-openai-api-key-here"
}
启动项目后，如果参数配置不正确，您会在控制台或 Aspire Dashboard 中看到相关错误信息。确保以下服务能够正常启动：
提示: 如果暂时不需要使用 AI 功能，可以设置一个占位符值，但某些依赖 AI 的功能将无法正常工作。
创建 .vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch CodeSpirit",
"type": "coreclr",
"request": "launch",
"preLaunchTask": "build",
"program": "${workspaceFolder}/Src/CodeSpirit.AppHost/bin/Debug/net10.0/CodeSpirit.AppHost.dll",
"cwd": "${workspaceFolder}/Src/CodeSpirit.AppHost",
"env": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
]
}
创建 .vscode/tasks.json：
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"command": "dotnet",
"type": "process",
"args": ["build", "${workspaceFolder}/CodeSpirit.sln"],
"problemMatcher": "$msCompile"
}
]
}
访问Aspire Dashboard (http://localhost:17109) 确认所有服务正常运行：
打开结构化日志面板，检查是否存在错误：
账号：systemadmin
密码：CodeSpirit@2025
登录后可以看到系统平台后台管理UI：
租户平台（默认租户）：https://localhost:7120/default/login
账号：admin
密码：123@Admin
一般是以下情况导致：
镜像无法拉取，一般在docker面板或Aspire管理面板的日志中可以看到。建议配置镜像源或路由上网。
关键服务故障，比如Web服务出现故障。
端口冲突或网络错误，具体可以看启动控制台错误：
如果遇到端口冲突，修改 Src/CodeSpirit.AppHost/Program.cs 中的端口配置。
由于项目使用.NET Aspire管理服务，如果遇到服务启动问题：
# 重启Aspire应用
cd Src/CodeSpirit.AppHost
dotnet run --force
# 查看Aspire Dashboard中的服务状态
# 访问 http://localhost:17109
# 在Aspire Dashboard中查看GreptimeDB状态
# 如果内存不足，可以在Program.cs中调整GreptimeDB配置
# 检查系统资源使用情况
# GreptimeDB需要至少512MB内存
# 信任开发证书
dotnet dev-certs https --trust
# 检查数据库容器状态（根据配置的数据库类型）
docker ps | grep mysql # MySQL
docker ps | grep sqlserver # SQL Server
# 重启数据库容器
docker restart mysql # MySQL
docker restart sqlserver # SQL Server
# 或在Aspire Dashboard中查看数据库状态和连接信息
如果系统内存不足，可以：
如果启动时遇到以下错误或服务无法正常启动：
解决方案：
检查参数是否已配置：
# 查看 User Secrets（如果使用）
cd Src/CodeSpirit.AppHost
dotnet user-secrets list
配置缺失的参数：
llm-ApiKey 和 ai-form-fill-llm-ApiKey 两个必填参数验证配置：
提示: 如果暂时不需要使用 AI 功能，可以设置占位符值（如
placeholder-key），但相关 AI 功能将无法正常工作。
# 启用热重载
cd Src/CodeSpirit.AppHost
dotnet watch run
在Visual Studio或VS Code中设置断点，按F5启动调试。
项目提供了完整的Kubernetes部署文件：
# 部署到Kubernetes集群
kubectl apply -f k8s/
# 查看部署状态
kubectl get pods -n code-spirit-release
# 构建所有服务的Docker镜像
dotnet publish CodeSpirit.sln -c Release
# 使用项目提供的Dockerfile构建镜像
docker build -f Src/CodeSpirit.Web/Dockerfile -t codespirit-web:latest .
docker build -f Src/CodeSpirit.IdentityApi/Dockerfile -t codespirit-identity:latest .
生产环境配置通过以下方式管理：
环境搭建完成后，您可以：
如果遇到问题，请参考：
祝您开发愉快！????
作者：雪雁
关注微信