CodeSpirit 开发环境搭建及启动指南
<h2 id="概述">概述</h2><p>本指南将帮助您快速搭建CodeSpirit（码灵）低代码框架的开发环境。CodeSpirit基于 .NET 10 和 Aspire 13.0 构建，通过简单的几个步骤即可启动完整的开发环境。</p>
<p><strong>最后更新</strong>: 2025年12月22日<br>
<strong>框架版本</strong>: v2.0.0<br>
<img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224131727898-298580147.png" alt="image" loading="lazy"></p>
<h2 id="快速开始">快速开始</h2>
<h3 id="前置要求">前置要求</h3>
<ul>
<li><strong>操作系统</strong>: Windows 10/11, macOS 12+, 或 Linux (Ubuntu 20.04+)</li>
<li><strong>CPU</strong>: Intel i5 或 AMD Ryzen 5 及以上（推荐i7/Ryzen 7）</li>
<li><strong>内存</strong>: 16GB RAM（推荐32GB）</li>
<li><strong>存储</strong>: 至少20GB可用空间（SSD推荐）</li>
</ul>
<blockquote>
<p><strong>注意</strong>: CodeSpirit默认使用GreptimeDB进行审计日志存储和搜索。Elasticsearch为可选组件，如需使用请参考相关配置文档。</p>
</blockquote>
<h3 id="1-安装-net-10-sdk">1. 安装 .NET 10 SDK</h3>
<h4 id="windows">Windows</h4>
<pre><code class="language-powershell"># 使用 winget 安装
winget install Microsoft.DotNet.SDK.10
# 或下载安装包
# https://dotnet.microsoft.com/download/dotnet/10.0
</code></pre>
<h4 id="macos">macOS</h4>
<pre><code class="language-bash"># 使用 Homebrew
brew install --cask dotnet-sdk
# 或下载安装包
# https://dotnet.microsoft.com/download/dotnet/10.0
</code></pre>
<h4 id="linux-ubuntu">Linux (Ubuntu)</h4>
<pre><code class="language-bash"># 添加微软包源
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
</code></pre>
<h4 id="验证安装">验证安装</h4>
<pre><code class="language-bash">dotnet --version
# 应显示 10.x.x
</code></pre>
<h3 id="2-安装开发工具">2. 安装开发工具</h3>
<h4 id="visual-studio-2026-推荐">Visual Studio 2026 (推荐)</h4>
<ul>
<li>下载地址: https://visualstudio.microsoft.com/vs/</li>
<li>选择工作负载：<strong>ASP.NET 和 Web 开发</strong></li>
</ul>
<h4 id="或者-visual-studio-code">或者 Visual Studio Code</h4>
<pre><code class="language-bash"># Windows
winget install Microsoft.VisualStudioCode
# macOS
brew install --cask visual-studio-code
# Linux
sudo snap install code --classic
</code></pre>
<p>VS Code必需扩展：</p>
<pre><code class="language-bash">code --install-extension ms-dotnettools.csharp
code --install-extension ms-dotnettools.vscode-dotnet-runtime
</code></pre>
<h3 id="3-安装docker-desktop">3. 安装Docker Desktop</h3>
<ul>
<li>下载地址: https://www.docker.com/products/docker-desktop</li>
<li>安装后启动Docker Desktop</li>
</ul>
<p>验证安装：</p>
<pre><code class="language-bash">docker --version
</code></pre>
<h2 id="项目启动">项目启动</h2>
<h3 id="1-克隆项目">1. 克隆项目</h3>
<pre><code class="language-bash">git clone https://gitee.com/magicodes/code-spirit.git
cd code-spirit
</code></pre>
<h3 id="2-启动基础服务">2. 启动基础服务</h3>
<p>CodeSpirit使用Aspire自动管理所有依赖服务，无需手动启动Docker容器：</p>
<pre><code class="language-bash"># Aspire会自动启动以下服务：
# - MySQL/SQL Server (根据配置选择，端口: 3306/1433)
# - Redis (端口: 6380)
# - RabbitMQ (端口: 5672, 管理界面: 15672)
# - GreptimeDB (端口: 4000/4001)
# - Seq日志服务 (端口: 5341)
</code></pre>
<blockquote>
<p><strong>服务说明</strong>:</p>
<ul>
<li><strong>MySQL/SQL Server</strong>: 主数据库存储（根据DatabaseType配置选择）</li>
<li><strong>Redis</strong>: 缓存和会话存储（端口: 6380）</li>
<li><strong>RabbitMQ</strong>: 消息队列服务（管理界面端口: 15672）</li>
<li><strong>GreptimeDB</strong>: 时序数据库，用于审计日志存储（HTTP端口: 4000, gRPC端口: 4001）</li>
<li><strong>Seq</strong>: 结构化日志服务（端口: 5341）</li>
</ul>
</blockquote>
<h3 id="3-运行项目">3. 运行项目</h3>
<h4 id="使用net-aspire推荐">使用.NET Aspire（推荐）</h4>
<pre><code class="language-bash"># 进入AppHost项目目录
cd Src/CodeSpirit.AppHost
# 运行Aspire应用
dotnet run
</code></pre>
<p>如果是正常启动，将看到以下缤纷的控制台输出：</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224131931648-1820053723.png" alt="image" loading="lazy"></p>
<p>启动后访问：</p>
<ul>
<li><strong>Aspire Dashboard</strong>: http://localhost:17109（自动打开）</li>
<li><strong>Web应用</strong>: https://localhost:7120（启动后显示具体端口）</li>
</ul>
<blockquote>
<p><strong>注意</strong>:</p>
</blockquote>
<blockquote>
<ol>
<li>实际端口号可能因系统配置而异，请查看Aspire Dashboard获取准确的端口信息。</li>
<li>如何登录页没有正常呈现，请按照下面的必填参数配置进行配置。</li>
</ol>
</blockquote>
<h4 id="或者使用visual-studio">或者使用Visual Studio</h4>
<ol>
<li>
<p>打开 <code>CodeSpirit.sln</code></p>
</li>
<li>
<p>设置 <code>CodeSpirit.AppHost</code> 为启动项目</p>
</li>
<li>
<p>按 F5 运行<br>
<img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224131917733-1101676572.png" alt="image" loading="lazy"><br>
注意，需确保以下服务均正常启动：<br>
<img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224131931648-1820053723.png" alt="image" loading="lazy"></p>
</li>
</ol>
<h2 id="项目结构">项目结构</h2>
<p>CodeSpirit采用Clean Architecture设计，项目结构如下：</p>
<pre><code>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 # 解决方案文件
</code></pre>
<h2 id="默认配置">默认配置</h2>
<p>项目使用以下默认配置，由.NET Aspire自动管理：</p>
<h3 id="数据库连接">数据库连接</h3>
<ul>
<li>
<p><strong>数据库类型</strong>: 支持MySQL和SQL Server两种数据库（通过<code>DatabaseType</code>配置选择）</p>
</li>
<li>
<p><strong>MySQL</strong>: 端口3306，由Aspire自动配置</p>
<p>可以从资源面板访问管理UI（phpmyadmin）：<br>
<img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132002956-598129788.png" alt="image" loading="lazy"></p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132042244-558588173.png" alt="image" loading="lazy"></p>
</li>
<li>
<p><strong>SQL Server</strong>: 端口1433，由Aspire自动配置</p>
</li>
<li>
<p><strong>数据库</strong>: 自动创建和迁移</p>
</li>
<li>
<p><strong>连接字符串</strong>: 由Aspire自动管理</p>
</li>
</ul>
<h3 id="缓存和消息队列">缓存和消息队列</h3>
<ul>
<li>
<p><strong>Redis</strong>: <code>localhost:6380</code>（具体见管理UI）</p>
</li>
<li>
<p><strong>RabbitMQ</strong>: <code>localhost:5672</code> (管理界面: http://localhost:15672, 用户名/密码: admin/Password123)</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132123458-1426760447.png" alt="image" loading="lazy"></p>
</li>
</ul>
<h3 id="其他服务端口">其他服务端口</h3>
<ul>
<li>
<p><strong>GreptimeDB</strong>:</p>
<ul>
<li>HTTP端口: <code>localhost:4000</code></li>
<li>gRPC端口: <code>localhost:4001</code></li>
<li>健康检查: http://localhost:4000/health</li>
</ul>
</li>
<li>
<p><strong>Seq日志服务</strong>: <code>localhost:5341</code>（具体端口见资源面板）</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132136208-2065968736.png" alt="image" loading="lazy"></p>
</li>
<li>
<p><strong>Redis Commander</strong>: 通过Aspire Dashboard访问</p>
</li>
</ul>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132147317-671812413.png" alt="image" loading="lazy"></p>
<h2 id="必填参数配置">必填参数配置</h2>
<p>CodeSpirit 使用 .NET Aspire 的参数管理机制来配置敏感信息和环境相关参数。在首次启动前，您需要配置以下必填参数。提示UI如下：<br>
<img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132156259-1567610099.png" alt="image" loading="lazy"><br>
<img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132203941-1321498621.png" alt="image" loading="lazy"></p>
<h3 id="参数配置方式">参数配置方式</h3>
<p>Aspire 支持两种参数配置方式，配置系统会按以下优先级读取（高优先级会覆盖低优先级）：</p>
<ol>
<li><strong>User Secrets</strong>（开发环境推荐，避免提交敏感信息到代码库）</li>
<li><strong>appsettings.json</strong>（开发环境备选方案）</li>
</ol>
<blockquote>
<p><strong>提示</strong>: 对于敏感信息（如 API 密钥），强烈推荐使用 User Secrets，避免将密钥提交到代码库。</p>
</blockquote>
<h3 id="必填参数列表">必填参数列表</h3>
<h4 id="llm-配置参数">LLM 配置参数</h4>
<p>以下参数用于配置通用 LLM 服务（如 AI 卡片、智能审批等功能）：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>说明</th>
<th>是否必填</th>
<th>默认值</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>llm-ApiKey</code></td>
<td>LLM API密钥</td>
<td>✅ <strong>必填</strong></td>
<td>无</td>
</tr>
<tr>
<td><code>llm-ApiBaseUrl</code></td>
<td>LLM API基础地址</td>
<td>可选</td>
<td><code>https://dashscope.aliyuncs.com/compatible-mode/v1</code></td>
</tr>
<tr>
<td><code>llm-ModelName</code></td>
<td>LLM模型名称</td>
<td>可选</td>
<td><code>qwen-flash</code></td>
</tr>
<tr>
<td><code>llm-TimeoutSeconds</code></td>
<td>请求超时时间（秒）</td>
<td>可选</td>
<td><code>120</code></td>
</tr>
<tr>
<td><code>llm-MaxTokens</code></td>
<td>最大Token数</td>
<td>可选</td>
<td><code>2048</code></td>
</tr>
<tr>
<td><code>llm-UseProxy</code></td>
<td>是否使用代理</td>
<td>可选</td>
<td><code>false</code></td>
</tr>
<tr>
<td><code>llm-ProxyAddress</code></td>
<td>代理地址</td>
<td>可选</td>
<td>空字符串</td>
</tr>
</tbody>
</table>
<h4 id="ai表单填充-llm-配置参数">AI表单填充 LLM 配置参数</h4>
<p>以下参数用于配置 AI 表单智能填充功能：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>说明</th>
<th>是否必填</th>
<th>默认值</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ai-form-fill-llm-ApiKey</code></td>
<td>AI表单填充LLM API密钥</td>
<td>✅ <strong>必填</strong></td>
<td>无</td>
</tr>
<tr>
<td><code>ai-form-fill-llm-ApiBaseUrl</code></td>
<td>API基础地址</td>
<td>可选</td>
<td><code>https://dashscope.aliyuncs.com/compatible-mode/v1</code></td>
</tr>
<tr>
<td><code>ai-form-fill-llm-ModelName</code></td>
<td>模型名称</td>
<td>可选</td>
<td><code>qwen3-max-preview</code></td>
</tr>
<tr>
<td><code>ai-form-fill-llm-DisableThinking</code></td>
<td>禁用思考模式</td>
<td>可选</td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>ai-form-fill-llm-ResponseFormatType</code></td>
<td>响应格式类型</td>
<td>可选</td>
<td><code>json_object</code></td>
</tr>
<tr>
<td><code>ai-form-fill-llm-Temperature</code></td>
<td>温度参数</td>
<td>可选</td>
<td><code>0.1</code></td>
</tr>
<tr>
<td><code>ai-form-fill-llm-TopP</code></td>
<td>TopP参数</td>
<td>可选</td>
<td><code>0.9</code></td>
</tr>
<tr>
<td><code>ai-form-fill-llm-EnableStreaming</code></td>
<td>启用流式响应</td>
<td>可选</td>
<td><code>true</code></td>
</tr>
</tbody>
</table>
<h4 id="其他可选参数">其他可选参数</h4>
<p>以下参数已有默认值，通常无需修改：</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>说明</th>
<th>默认值</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>jwt-SecretKey</code></td>
<td>JWT密钥</td>
<td><code>ECBF8FA013844D77AE041A6800D7FF8F</code></td>
</tr>
<tr>
<td><code>jwt-Issuer</code></td>
<td>JWT颁发者</td>
<td><code>codespirit.com</code></td>
</tr>
<tr>
<td><code>jwt-Audience</code></td>
<td>JWT受众</td>
<td><code>CodeSpirit</code></td>
</tr>
<tr>
<td><code>mysql-password</code></td>
<td>MySQL密码</td>
<td><code>Password123</code></td>
</tr>
<tr>
<td><code>sqlserver-password</code></td>
<td>SQL Server密码</td>
<td><code>P@ssword123456</code></td>
</tr>
<tr>
<td><code>rabbitmq-username</code></td>
<td>RabbitMQ用户名</td>
<td><code>admin</code></td>
</tr>
<tr>
<td><code>rabbitmq-password</code></td>
<td>RabbitMQ密码</td>
<td><code>Password123</code></td>
</tr>
</tbody>
</table>
<h3 id="配置方法">配置方法</h3>
<h4 id="方法一使用-user-secrets推荐开发环境">方法一：使用 User Secrets（推荐开发环境）</h4>
<p>使用 .NET User Secrets 可以安全地存储敏感信息，无需担心提交到代码库：</p>
<pre><code class="language-bash"># 进入 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
</code></pre>
<h4 id="方法二使用-appsettingsjson开发环境备选">方法二：使用 appsettings.json（开发环境备选）</h4>
<p>编辑 <code>Src/CodeSpirit.AppHost/appsettings.json</code> 文件，添加参数配置：</p>
<pre><code class="language-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"
}
</code></pre>
<blockquote>
<p><strong>⚠️ 重要提示</strong>:</p>
<ul>
<li>如果使用 <code>appsettings.json</code> 配置敏感信息，请确保该文件已添加到 <code>.gitignore</code> 中</li>
<li>或者创建 <code>appsettings.Local.json</code> 文件（该文件默认已在 <code>.gitignore</code> 中），避免将 API 密钥提交到代码库</li>
<li><strong>强烈推荐使用 User Secrets 方式</strong>，更安全且不会误提交</li>
</ul>
</blockquote>
<h3 id="获取-api-密钥">获取 API 密钥</h3>
<h4 id="阿里云通义千问dashscope">阿里云通义千问（DashScope）</h4>
<p>开发阶段免费额度完全够用：</p>
<ol>
<li>访问 阿里云 DashScope</li>
<li>注册/登录账号</li>
<li>创建 API Key</li>
<li>将 API Key 配置到上述参数中</li>
</ol>
<blockquote>
<p>💡 <strong>推荐阅读</strong>：阿里云通义千问免费体验指南 - 详细的注册指南、配置教程和成本分析，帮助您零成本体验 CodeSpirit 的强大 AI 能力！</p>
</blockquote>
<h4 id="openai如使用-openai-兼容接口">OpenAI（如使用 OpenAI 兼容接口）</h4>
<p>如果使用 OpenAI 兼容的 API 服务，需要修改以下参数：</p>
<p>使用 User Secrets 配置：</p>
<pre><code class="language-bash">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"
</code></pre>
<p>或使用 appsettings.json 配置：</p>
<pre><code class="language-json">{
"llm-ApiBaseUrl": "https://api.openai.com/v1",
"llm-ModelName": "gpt-4",
"llm-ApiKey": "your-openai-api-key-here"
}
</code></pre>
<h3 id="验证参数配置">验证参数配置</h3>
<p>启动项目后，如果参数配置不正确，您会在控制台或 Aspire Dashboard 中看到相关错误信息。确保以下服务能够正常启动：</p>
<ul>
<li>✅ ConfigCenter（配置中心）- 需要 LLM 参数</li>
<li>✅ Web 前端 - 需要 AI 表单填充 LLM 参数</li>
</ul>
<blockquote>
<p><strong>提示</strong>: 如果暂时不需要使用 AI 功能，可以设置一个占位符值，但某些依赖 AI 的功能将无法正常工作。</p>
</blockquote>
<h2 id="开发工具配置">开发工具配置</h2>
<h3 id="visual-studio-code">Visual Studio Code</h3>
<p>创建 <code>.vscode/launch.json</code>：</p>
<pre><code class="language-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"
}
}
]
}
</code></pre>
<p>创建 <code>.vscode/tasks.json</code>：</p>
<pre><code class="language-json">{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"command": "dotnet",
"type": "process",
"args": ["build", "${workspaceFolder}/CodeSpirit.sln"],
"problemMatcher": "$msCompile"
}
]
}
</code></pre>
<h2 id="验证安装-1">验证安装</h2>
<h3 id="1-检查服务状态">1. 检查服务状态</h3>
<p>访问Aspire Dashboard (http://localhost:17109) 确认所有服务正常运行：</p>
<ul>
<li>✅ CodeSpirit.Web (Web前端)</li>
<li>✅ CodeSpirit.IdentityApi (身份认证)</li>
<li>✅ CodeSpirit.ConfigCenter (配置中心)</li>
<li>✅ CodeSpirit.MessagingApi (消息服务)</li>
<li>✅ CodeSpirit.ExamApi (考试系统)</li>
<li>✅ CodeSpirit.FileStorageApi (文件存储)</li>
<li>✅ CodeSpirit.SurveyApi (问卷调查)</li>
<li>✅ CodeSpirit.ApprovalApi (审批流程)</li>
<li>✅ CodeSpirit.PathfinderApi (AI目标管理)</li>
<li>✅ MySQL/SQL Server (数据库，根据配置)</li>
<li>✅ Redis (缓存)</li>
<li>✅ RabbitMQ (消息队列)</li>
<li>✅ GreptimeDB (时序数据库)</li>
<li>✅ Seq (日志服务)</li>
</ul>
<h3 id="2-检查错误">2. 检查错误</h3>
<p>打开结构化日志面板，检查是否存在错误：</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132237841-409615542.png" alt="image" loading="lazy"></p>
<h3 id="3-访问web界面">3. 访问Web界面</h3>
<p>系统平台：https://localhost:7120</p>
<p>账号：systemadmin</p>
<p>密码：CodeSpirit@2025</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132247398-182230200.png" alt="image" loading="lazy"></p>
<p>登录后可以看到系统平台后台管理UI：</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132258347-1684698426.png" alt="image" loading="lazy"></p>
<p>租户平台（默认租户）：https://localhost:7120/default/login</p>
<p>账号：admin</p>
<p>密码：123@Admin</p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132312276-873776487.png" alt="image" loading="lazy"></p>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132320900-136012642.png" alt="image" loading="lazy"></p>
<h2 id="常见问题">常见问题</h2>
<h3 id="无法打开网页">无法打开网页</h3>
<p>一般是以下情况导致：</p>
<ol>
<li>
<p>镜像无法拉取，一般在docker面板或Aspire管理面板的日志中可以看到。建议配置镜像源或路由上网。</p>
</li>
<li>
<p>关键服务故障，比如Web服务出现故障。</p>
</li>
<li>
<p>端口冲突或网络错误，具体可以看启动控制台错误：</p>
</li>
</ol>
<p><img src="https://img2024.cnblogs.com/blog/70544/202512/70544-20251224132339285-1584044125.png" alt="image" loading="lazy"></p>
<h3 id="端口冲突">端口冲突</h3>
<p>如果遇到端口冲突，修改 <code>Src/CodeSpirit.AppHost/Program.cs</code> 中的端口配置。</p>
<h3 id="docker服务启动失败">Docker服务启动失败</h3>
<p>由于项目使用.NET Aspire管理服务，如果遇到服务启动问题：</p>
<pre><code class="language-bash"># 重启Aspire应用
cd Src/CodeSpirit.AppHost
dotnet run --force
# 查看Aspire Dashboard中的服务状态
# 访问 http://localhost:17109
</code></pre>
<h3 id="greptimedb启动失败">GreptimeDB启动失败</h3>
<pre><code class="language-bash"># 在Aspire Dashboard中查看GreptimeDB状态
# 如果内存不足，可以在Program.cs中调整GreptimeDB配置
# 检查系统资源使用情况
# GreptimeDB需要至少512MB内存
</code></pre>
<h3 id="ssl证书问题">SSL证书问题</h3>
<pre><code class="language-bash"># 信任开发证书
dotnet dev-certs https --trust
</code></pre>
<h3 id="数据库连接问题">数据库连接问题</h3>
<pre><code class="language-bash"># 检查数据库容器状态（根据配置的数据库类型）
docker ps | grep mysql # MySQL
docker ps | grep sqlserver # SQL Server
# 重启数据库容器
docker restart mysql # MySQL
docker restart sqlserver# SQL Server
# 或在Aspire Dashboard中查看数据库状态和连接信息
</code></pre>
<h3 id="内存不足问题">内存不足问题</h3>
<p>如果系统内存不足，可以：</p>
<ol>
<li>关闭不必要的应用程序</li>
<li>调整GreptimeDB内存设置（在Program.cs中）</li>
<li>考虑升级系统内存到推荐配置（16GB推荐，32GB更佳）</li>
</ol>
<h3 id="llm-api-密钥未配置">LLM API 密钥未配置</h3>
<p>如果启动时遇到以下错误或服务无法正常启动：</p>
<ul>
<li>ConfigCenter 服务启动失败</li>
<li>Web 前端无法访问 AI 功能</li>
<li>控制台提示缺少 LLM 配置参数</li>
</ul>
<p><strong>解决方案</strong>：</p>
<ol>
<li>
<p><strong>检查参数是否已配置</strong>：</p>
<pre><code class="language-bash"># 查看 User Secrets（如果使用）
cd Src/CodeSpirit.AppHost
dotnet user-secrets list
</code></pre>
</li>
<li>
<p><strong>配置缺失的参数</strong>：</p>
<ul>
<li>参考 必填参数配置 章节</li>
<li>确保至少配置了 <code>llm-ApiKey</code> 和 <code>ai-form-fill-llm-ApiKey</code> 两个必填参数</li>
</ul>
</li>
<li>
<p><strong>验证配置</strong>：</p>
<ul>
<li>重启应用后，检查 Aspire Dashboard 中的服务状态</li>
<li>查看服务日志确认参数是否正确加载</li>
</ul>
</li>
</ol>
<blockquote>
<p><strong>提示</strong>: 如果暂时不需要使用 AI 功能，可以设置占位符值（如 <code>placeholder-key</code>），但相关 AI 功能将无法正常工作。</p>
</blockquote>
<h2 id="开发模式">开发模式</h2>
<h3 id="热重载开发">热重载开发</h3>
<pre><code class="language-bash"># 启用热重载
cd Src/CodeSpirit.AppHost
dotnet watch run
</code></pre>
<h3 id="调试模式">调试模式</h3>
<p>在Visual Studio或VS Code中设置断点，按F5启动调试。</p>
<h2 id="生产环境部署">生产环境部署</h2>
<h3 id="使用kubernetes部署">使用Kubernetes部署</h3>
<p>项目提供了完整的Kubernetes部署文件：</p>
<pre><code class="language-bash"># 部署到Kubernetes集群
kubectl apply -f k8s/
# 查看部署状态
kubectl get pods -n code-spirit-release
</code></pre>
<h3 id="使用docker部署">使用Docker部署</h3>
<pre><code class="language-bash"># 构建所有服务的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 .
</code></pre>
<h3 id="配置管理">配置管理</h3>
<p>生产环境配置通过以下方式管理：</p>
<ul>
<li><strong>Kubernetes ConfigMap</strong>: 存储应用配置</li>
<li><strong>Kubernetes Secret</strong>: 存储敏感信息</li>
<li><strong>配置中心</strong>: 动态配置管理</li>
</ul>
<h2 id="下一步">下一步</h2>
<p>环境搭建完成后，您可以：</p>
<ol>
<li>📖 阅读 项目整体架构设计</li>
<li>🔧 了解 CodeSpirit.Core核心框架</li>
<li>📋 查看 总体技术体系说明</li>
<li>🔐 学习 统一异常处理指南</li>
<li>💻 参考 CRUD开发示例 开始开发</li>
</ol>
<h2 id="获取帮助">获取帮助</h2>
<p>如果遇到问题，请参考：</p>
<ul>
<li>GitHub Issues</li>
<li>项目Wiki</li>
<li>讨论区</li>
</ul>
<p>祝您开发愉快！🚀</p>
</div>
<div id="MySignature" role="contentinfo">
作者：雪雁<br>出处：http://www.cnblogs.com/codelove/
<br>如果喜欢作者的文章，请关注【CodeSpirit-码灵】公众号以便第一时间获得最新内容。本文版权归作者所有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。<br><b>静听鸟语花香，漫赏云卷云舒。</b>
<br>
<img src="https://images.cnblogs.com/cnblogs_com/codelove/315887/o_251224070213_%E5%85%AC%E4%BC%97%E5%8F%B7.jpg" width="100" height="100"><br><br>
来源：https://www.cnblogs.com/codelove/p/19392132
頁:
[1]