CodeSpirit 开发环境搭建指南 - 未分类

概述

本指南将帮助您快速搭建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.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: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.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部署文件：

# 部署到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: 存储敏感信息
配置中心: 动态配置管理