CodeSpirit 开发环境搭建指南

码灵

发布于 2025-12-17 15:05:35

1580

概述

本指南将帮助您快速搭建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

# 使用 Homebrewbrew 
install --cask dotnet-sdk

Linux (Ubuntu)

# 添加微软包源
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-9.0

验证安装

dotnet --version
# 应显示 9.x.x

2. 安装开发工具

Visual Studio 2022 (推荐)

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

或者 Visual Studio Code

# 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

3. 安装Docker Desktop

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

验证安装：

docker --version

项目启动

1. 克隆项目

git clone https://gitee.com/magicodes/code-spirit.git
cd 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:61690
RabbitMQ: localhost:5672 (管理界面: http://localhost:15672, 用户名/密码: admin/Password123)

其他服务端口

Elasticsearch: localhost:61687 (健康检查:http://localhost:61687/_cluster/health)
Seq日志服务: localhost:61688
Redis 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.AppHost
dotnet 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 Server
docker restart sqlserver

内存不足问题

如果系统内存不足，可以：

关闭不必要的应用程序
调整Elasticsearch内存设置
考虑升级系统内存到推荐配置

开发模式

热重载开发

# 启用热重载
cd Src/CodeSpirit.AppHost
dotnet watch run

调试模式

在Visual Studio或VS Code中设置断点，按F5启动调试。

生产环境部署

使用Kubernetes部署

项目提供了完整的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: 存储敏感信息
配置中心: 动态配置管理

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-06-02，如有侵权请联系 cloudcommunity@tencent.com 删除

数据库

本文分享自麦扣聊技术微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度