概述

本指南將幫助您快速搭建CodeSpirit（碼靈）低代碼框架的開發環境。CodeSpirit基於 .NET 10 和 Aspire 13.0 構建，通過簡單的幾個步驟即可啓動完整的開發環境。

最後更新: 2025年12月22日
框架版本: v2.0.0

快速開始

前置要求

• 操作系統: Windows 10/11, macOS 12+, 或 Linux (Ubuntu 20.04+)
• CPU: Intel i5 或 AMD Ryzen 5 及以上（推薦i7/Ryzen 7）
• 內存: 16GB RAM（推薦32GB）
• 存儲: 至少20GB可用空間（SSD推薦）

注意: CodeSpirit默認使用GreptimeDB進行審計日誌存儲和搜索。Elasticsearch為可選組件，如需使用請參考相關配置文檔。

1. 安裝 .NET 10 SDK

Windows

# 使用 winget 安裝
winget install Microsoft.DotNet.SDK.10

# 或下載安裝包
# https://dotnet.microsoft.com/download/dotnet/10.0

macOS

# 使用 Homebrew
brew install --cask dotnet-sdk

# 或下載安裝包
# https://dotnet.microsoft.com/download/dotnet/10.0

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-10.0

驗證安裝

dotnet --version
# 應顯示 10.x.x

2. 安裝開發工具

Visual Studio 2026 (推薦)

• 下載地址: 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使用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）

3. 運行項目

使用.NET Aspire（推薦）

# 進入AppHost項目目錄
cd Src/CodeSpirit.AppHost

# 運行Aspire應用
dotnet run

如果是正常啓動，將看到以下繽紛的控制枱輸出：

啓動後訪問：

• Aspire Dashboard: http://localhost:17109（自動打開）
• Web應用: https://localhost:7120（啓動後顯示具體端口）

注意:

1. 實際端口號可能因系統配置而異，請查看Aspire Dashboard獲取準確的端口信息。
2. 如何登錄頁沒有正常呈現，請按照下面的必填參數配置進行配置。

或者使用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
│   │   ├── 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:

  • HTTP端口: localhost:4000
  • gRPC端口: localhost:4001
  • 健康檢查: http://localhost:4000/health

• Seq日誌服務: localhost:5341（具體端口見資源面板）

  

• Redis Commander: 通過Aspire Dashboard訪問

必填參數配置

CodeSpirit 使用 .NET Aspire 的參數管理機制來配置敏感信息和環境相關參數。在首次啓動前，您需要配置以下必填參數。提示UI如下：

參數配置方式

Aspire 支持兩種參數配置方式，配置系統會按以下優先級讀取（高優先級會覆蓋低優先級）：

1. User Secrets（開發環境推薦，避免提交敏感信息到代碼庫）
2. appsettings.json（開發環境備選方案）

提示: 對於敏感信息（如 API 密鑰），強烈推薦使用 User Secrets，避免將密鑰提交到代碼庫。

必填參數列表

LLM 配置參數

以下參數用於配置通用 LLM 服務（如 AI 卡片、智能審批等功能）：

AI表單填充 LLM 配置參數

以下參數用於配置 AI 表單智能填充功能：

其他可選參數

以下參數已有默認值，通常無需修改：

配置方法

方法一：使用 User Secrets（推薦開發環境）

使用 .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

方法二：使用 appsettings.json（開發環境備選）

編輯 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 方式，更安全且不會誤提交

獲取 API 密鑰

阿里雲通義千問（DashScope）

開發階段免費額度完全夠用：

1. 訪問 阿里雲 DashScope
2. 註冊/登錄賬號
3. 創建 API Key
4. 將 API Key 配置到上述參數中

💡 推薦閲讀：阿里雲通義千問免費體驗指南 - 詳細的註冊指南、配置教程和成本分析，幫助您零成本體驗 CodeSpirit 的強大 AI 能力！

OpenAI（如使用 OpenAI 兼容接口）

如果使用 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 中看到相關錯誤信息。確保以下服務能夠正常啓動：

• ✅ ConfigCenter（配置中心）- 需要 LLM 參數
• ✅ Web 前端 - 需要 AI 表單填充 LLM 參數

提示: 如果暫時不需要使用 AI 功能，可以設置一個佔位符值，但某些依賴 AI 的功能將無法正常工作。

開發工具配置

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/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"
    }
  ]
}

驗證安裝

1. 檢查服務狀態

訪問Aspire Dashboard (http://localhost:17109) 確認所有服務正常運行：

• ✅ CodeSpirit.Web (Web前端)
• ✅ CodeSpirit.IdentityApi (身份認證)
• ✅ CodeSpirit.ConfigCenter (配置中心)
• ✅ CodeSpirit.MessagingApi (消息服務)
• ✅ CodeSpirit.ExamApi (考試系統)
• ✅ CodeSpirit.FileStorageApi (文件存儲)
• ✅ CodeSpirit.SurveyApi (問卷調查)
• ✅ CodeSpirit.ApprovalApi (審批流程)
• ✅ CodeSpirit.PathfinderApi (AI目標管理)
• ✅ MySQL/SQL Server (數據庫，根據配置)
• ✅ Redis (緩存)
• ✅ RabbitMQ (消息隊列)
• ✅ GreptimeDB (時序數據庫)
• ✅ Seq (日誌服務)

2. 檢查錯誤

打開結構化日誌面板，檢查是否存在錯誤：

3. 訪問Web界面

系統平台：https://localhost:7120

賬號：systemadmin

密碼：CodeSpirit@2025

登錄後可以看到系統平台後台管理UI：

租户平台（默認租户）：https://localhost:7120/default/login

賬號：admin

密碼：123@Admin

常見問題

無法打開網頁

一般是以下情況導致：

1. 鏡像無法拉取，一般在docker面板或Aspire管理面板的日誌中可以看到。建議配置鏡像源或路由上網。

2. 關鍵服務故障，比如Web服務出現故障。

3. 端口衝突或網絡錯誤，具體可以看啓動控制枱錯誤：

端口衝突

如果遇到端口衝突，修改 Src/CodeSpirit.AppHost/Program.cs 中的端口配置。

Docker服務啓動失敗

由於項目使用.NET Aspire管理服務，如果遇到服務啓動問題：

# 重啓Aspire應用
cd Src/CodeSpirit.AppHost
dotnet run --force

# 查看Aspire Dashboard中的服務狀態
# 訪問 http://localhost:17109

GreptimeDB啓動失敗

# 在Aspire Dashboard中查看GreptimeDB狀態
# 如果內存不足，可以在Program.cs中調整GreptimeDB配置

# 檢查系統資源使用情況
# GreptimeDB需要至少512MB內存

SSL證書問題

# 信任開發證書
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中查看數據庫狀態和連接信息

內存不足問題

如果系統內存不足，可以：

1. 關閉不必要的應用程序
2. 調整GreptimeDB內存設置（在Program.cs中）
3. 考慮升級系統內存到推薦配置（16GB推薦，32GB更佳）

LLM API 密鑰未配置

如果啓動時遇到以下錯誤或服務無法正常啓動：

• ConfigCenter 服務啓動失敗
• Web 前端無法訪問 AI 功能
• 控制枱提示缺少 LLM 配置參數

解決方案：

1. 檢查參數是否已配置：

   # 查看 User Secrets（如果使用）
   cd Src/CodeSpirit.AppHost
   dotnet user-secrets list
   

2. 配置缺失的參數：

   • 參考 必填參數配置 章節
   • 確保至少配置了 llm-ApiKey 和 ai-form-fill-llm-ApiKey 兩個必填參數

3. 驗證配置：

   • 重啓應用後，檢查 Aspire Dashboard 中的服務狀態
   • 查看服務日誌確認參數是否正確加載

提示: 如果暫時不需要使用 AI 功能，可以設置佔位符值（如 placeholder-key），但相關 AI 功能將無法正常工作。

開發模式

熱重載開發

# 啓用熱重載
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: 存儲敏感信息
• 配置中心: 動態配置管理

下一步

環境搭建完成後，您可以：

1. 📖 閲讀 項目整體架構設計
2. 🔧 瞭解 CodeSpirit.Core核心框架
3. 📋 查看 總體技術體系説明
4. 🔐 學習 統一異常處理指南
5. 💻 參考 CRUD開發示例 開始開發

獲取幫助

如果遇到問題，請參考：

• GitHub Issues
• 項目Wiki
• 討論區

祝您開發愉快！🚀