概述

---

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

• 下载地址：https://visualstudio.microsoft.com/vs/

•  选择工作负载：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

• 下载地址：https://www.docker.com/products/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

1. 打开 CodeSpirit.sln

2. 设置 CodeSpirit.AppHost 为启动项目

3. 按 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

内存不足问题

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

1. 关闭不必要的应用程序

2. 调整Elasticsearch内存设置

3. 考虑升级系统内存到推荐配置

开发模式

---

热重载开发

# 启用热重载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: 存储敏感信息

• 配置中心: 动态配置管理