概述
本指南将帮助您快速搭建CodeSpirit（码灵）低代码框架的开发环境。CodeSpirit基于.NET 9和.NET Aspire构建，通过简单的几个步骤即可启动完整的开发环境。
注意：CodeSpirit一直在持续迭代之中，文档请以开源库最新文档为准。
快速开始
前置要求
操作系统: Windows 10/11, macOS 12+, 或 Linux (Ubuntu 20.04+)
CPU：Intel i5 或 AMD Ryzen 5 及以上（推荐i7/Ryzen 7）
内存: 16GB RAM（推荐32GB，Elasticsearch需要较多内存）
存储: 至少20GB可用空间（SSD推荐，Elasticsearch需要较快的磁盘I/O）
注意: CodeSpirit使用Elasticsearch进行审计日志存储和搜索，需要较高的系统配置以确保良好的性能。后续支持多种数据源，本地或轻量环境使用数据库。
1. 安装.NET 9 SDK
Windows
# 使用 winget 安装winget install Microsoft.DotNet.SDK.9
macOS
# 使用 Homebrewbrewinstall --cask dotnet-sdk
Linux (Ubuntu)
# 添加微软包源wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.debsudo dpkg -i packages-microsoft-prod.debsudo apt-get updatesudo apt-get install -y dotnet-sdk-9.0
dotnet --version# 应显示 9.x.x
2. 安装开发工具
Visual Studio 2022 (推荐)
选择工作负载：ASP.NET 和 Web 开发
或者 Visual Studio Code
# Windowswinget install Microsoft.VisualStudioCode# macOSbrew install --cask visual-studio-code# Linuxsudo snap install code --classic
VS Code必需扩展：
code --install-extension ms-dotnettools.csharpcode --install-extension ms-dotnettools.vscode-dotnet-runtime
3. 安装Docker Desktop
安装后启动Docker Desktop
验证安装：
docker --version项目启动
1. 克隆项目
git clone https://gitee.com/magicodes/code-spirit.gitcd code-spirit
2. 启动基础服务
CodeSpirit使用.NET Aspire自动管理所有依赖服务，无需手动启动Docker容器：
# .NET Aspire会自动启动以下服务：# - SQL Server (本地托管，后续支持其他数据库类型)# - Redis (端口: 61690)# - RabbitMQ (端口: 5672, 管理界面: 15672)# - Elasticsearch (端口: 61687)# - Seq日志服务 (端口: 61688)
服务说明:
SQL Server: 主数据库存储
Redis: 缓存和会话存储
RabbitMQ: 消息队列服务
Elasticsearch: 审计日志存储和搜索引擎
Seq: 结构化日志服务
3. 运行项目
使用.NET Aspire（推荐）
# 进入AppHost项目目录cd Src/CodeSpirit.AppHost# 运行Aspire应用dotnet run
启动后访问：
Aspire Dashboard: http://localhost:17109
Web应用: https://localhost:7120
身份认证API: https://localhost:17134
考试API: https://localhost:61882 (如果启用)
消息API: https://localhost:7252 (如果启用)
配置中心: https://localhost:62144 (如果启用)
或者使用Visual Studio
打开
CodeSpirit.sln设置CodeSpirit.AppHost为启动项目按 F5 运行
项目结构
CodeSpirit采用Clean Architecture设计，项目结构如下：
CodeSpirit/├── Src/│ ├── ApiServices/ # API服务（解决方案文件夹）│ ├── CodeSpirit.IdentityApi/ # 身份认证API│ ├── CodeSpirit.ExamApi/ # 考试系统API│ ├── CodeSpirit.MessagingApi/ # 消息服务API│ ├── CodeSpirit.ConfigCenter/ # 配置中心API│ ├── Components/ # 组件库│ │ ├── CodeSpirit.Aggregator/ # 聚合器组件│ │ ├── CodeSpirit.Amis/ # UI生成引擎│ │ ├── CodeSpirit.Authorization/ # 权限组件│ │ ├── CodeSpirit.Audit/ # 审计组件│ │ ├── CodeSpirit.Navigation/ # 导航组件│ │ ├── CodeSpirit.Charts/ # 智能图表组件│ │ ├── CodeSpirit.LLM/ # 大语言模型组件│ │ └── CodeSpirit.PdfGeneration/ # PDF生成组件│ ├── CodeSpirit.AppHost/ # Aspire应用宿主│ ├── CodeSpirit.Core/ # 核心定义│ ├── CodeSpirit.ServiceDefaults/ # 服务默认配置│ ├── CodeSpirit.Shared/ # 共享库│ ├── CodeSpirit.Web/ # Web前端项目│ └── CodeSpirit.Messaging/ # 消息传递库├── Tests/ # 测试项目├── Docs/ # 项目文档├── k8s/ # Kubernetes部署文件└── CodeSpirit.sln # 解决方案文件
默认配置
项目使用以下默认配置，由.NET Aspire自动管理：
数据库连接
SQL Server:
数据库: 自动创建和迁移
连接字符串: 开发环境使用LocalDB
缓存和消息队列
Redis:
localhost:61690RabbitMQ:
localhost:5672(管理界面: http://localhost:15672, 用户名/密码: admin/Password123)
其他服务端口
Elasticsearch:
localhost:61687(健康检查:http://localhost:61687/_cluster/health)
Seq日志服务:
localhost:61688Redis Commander:
localhost:61689
默认用户账号
系统会自动创建管理员账号：
用户名:
admin密码:
123@Admin角色:
Admin（系统管理员）
注意: 首次登录后请立即修改默认密码以确保系统安全。
开发工具配置
Visual Studio Code
创建 .vscode/launch.json：
{"version": "0.2.0","configurations": [{"name": "Launch CodeSpirit","type": "coreclr","request": "launch","preLaunchTask": "build","program": "${workspaceFolder}/Src/CodeSpirit.AppHost/bin/Debug/net9.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"}]}
验证安装
1. 检查服务状态
访问Aspire Dashboard (http://localhost:17109) 确认所有服务正常运行：
CodeSpirit.Web (Web前端)
CodeSpirit.IdentityApi (身份认证)
CodeSpirit.ExamApi (考试系统，可选)
CodeSpirit.MessagingApi (消息服务，可选)
CodeSpirit.ConfigCenter (配置中心，可选)
SQL Server (数据库)
Redis (缓存)
RabbitMQ (消息队列)
Elasticsearch (搜索引擎)
Seq (日志服务)
2. 测试API
# 测试健康检查curl https://localhost:17134/health# 测试登录curl -X POST "https://localhost:17134/api/identity/auth/login" \-H "Content-Type: application/json" \-d '{"userName": "admin", "password": "123456"}'
3. 验证Elasticsearch
# 检查Elasticsearch状态curl http://localhost:61687/_cluster/health# 查看审计日志索引curl http://localhost:61687/_cat/indices?v
4. 访问Web界面
打开浏览器访问https://localhost:7120，使用默认账号登录。
常见问题
端口冲突
如果遇到端口冲突，修改Src/CodeSpirit.AppHost/Program.cs中的端口配置。
Docker服务启动失败
由于项目使用.NET Aspire管理服务，如果遇到服务启动问题：
# 重启Aspire应用cd Src/CodeSpirit.AppHostdotnet run --force# 查看Aspire Dashboard中的服务状态# 访问 http://localhost:18888
Elasticsearch启动失败
# 在Aspire Dashboard中查看Elasticsearch状态# 如果内存不足，可以在Program.cs中调整ES配置# 检查系统资源使用情况# Elasticsearch需要至少2GB内存
SSL证书问题
# 信任开发证书dotnet dev-certs https --trust
数据库连接问题
# 检查SQL Server容器状态docker ps | grep sqlserver# 重启SQL Serverdocker restart sqlserver
内存不足问题
如果系统内存不足，可以：
关闭不必要的应用程序
调整Elasticsearch内存设置
考虑升级系统内存到推荐配置
开发模式
热重载开发
# 启用热重载cd Src/CodeSpirit.AppHostdotnet watch run
调试模式
在Visual Studio或VS Code中设置断点，按F5启动调试。
生产环境部署
使用Kubernetes部署
项目提供了完整的Kubernetes部署文件：
kubectl apply -f k8s/kubectl get pods -n code-spirit-release
使用Docker部署
# 构建所有服务的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 .
配置管理
生产环境配置通过以下方式管理：
Kubernetes ConfigMap: 存储应用配置
Kubernetes Secret: 存储敏感信息
配置中心: 动态配置管理
本文暂时没有评论，来添加一个吧(●'◡'●)