CodeSpirit（码灵）は、.NET 10 および Aspire 13.0 をベースに構築されたローコードフレームワークです。本稿では、開発環境のセットアップからプロジェクトの起動までの具体的な手順を解説します。
システム要件
フレームワークをスムーズに実行するためには、以下のハードウェアおよびソフトウェア環境が推奨されます。
- OS: Windows 10/11, macOS 12+, または Linux (Ubuntu 20.04+)
- CPU: Intel i5 / AMD Ryzen 5 以上（i7 / Ryzen 7 推奨）
- メモリ: 16GB RAM（32GB 推奨）
- ストレージ: 20GB以上の空き容量（SSD推奨）
開発ツールの準備
1. .NET 10 SDK のインストール
プラットフォームに応じて以下の方法でSDKを導入します。
Windows (Winget)
# パッケージマネージャー経由でインストール
winget install Microsoft.DotNet.SDK.10
macOS (Homebrew)
# Homebrew Caskを利用
brew install --cask dotnet-sdk
Linux (Ubuntu)
# Microsoftパッケージリポジトリの追加とインストール
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 --list-sdks
# 出力例: 10.0.x
2. IDE / エディタのセットアップ
Visual Studio 2026 を推奨しますが、Visual Studio Code を利用することも可能です。VS Codeを使用する場合は、C#拡張機能の導入が必要です。
code --install-extension ms-dotnettools.csharp
3. Docker Desktop の導入
Aspireによるインフラ管理のため、Docker Desktopが必要です。公式サイトからダウンロードし、インストール後に起動しておきます。
# 動作確認
docker info
プロジェクトの取得と初期設定
ソースコードの克隆
リポジトリからソースコードを取得します。
git clone https://gitee.com/magicodes/code-spirit.git
cd code-spirit
必須パラメータの設定
CodeSpiritはAI機能のためにLLM APIキーを必要とします。これらの機密情報は dotnet user-secrets を使用して管理することが推奨されます。appsettings.json に直接記述する方法もありますが、ソース管理への誤コミットを防ぐため、User Secretsが最適です。
設定手順 (User Secrets)
cd Src/CodeSpirit.AppHost
# User Secretsの初期化
dotnet user-secrets init
# LLM APIキーの設定 (例: DashScope/Alibaba Cloud)
dotnet user-secrets set "llm-ApiKey" "sk-xxxxxxxxxxxxxxxx"
# AIフォーム入力支援用のAPIキー設定
dotnet user-secrets set "ai-form-fill-llm-ApiKey" "sk-xxxxxxxxxxxxxxxx"
または、プロジェクトルートの appsettings.Development.json に直接記述する場合の構成例は以下の通りです。
{
"DatabaseType": "MySql",
"Logging": {
"LogLevel": {
"Default": "Information"
}
},
// 以下、LLM関連設定
"llm-ApiKey": "your-llm-api-key-here",
"llm-ApiBaseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"ai-form-fill-llm-ApiKey": "your-ai-form-fill-api-key-here"
}
アプリケーションの起動
CodeSpiritは.NET Aspireを利用して依存サービス（MySQL, Redis, RabbitMQ, GreptimeDB等）を自動的にオーケストレーションします。手動でのDockerコンテナ起動は不要です。
起動コマンド
# AppHostディレクトリへ移動
cd Src/CodeSpirit.AppHost
# アプリケーション実行
dotnet run
起動に成功すると、コンソールにAspire DashboardのURLが表示されます。
- Aspire Dashboard:
http://localhost:17109(ポートは自動割り当てされる場合があります) - Webアプリケーション:
https://localhost:7120
主要サービスとポート
Aspire Dashboardのリソースパネルから、各サービスの状態とポートを確認できます。
| サービス名 | 説明 | デフォルトポート |
|---|---|---|
| MySQL / SQL Server | メインデータベース | 3306 / 1433 |
| Redis | キャッシュ/セッション管理 | 6380 |
| RabbitMQ | メッセージキュー (管理UI含む) | 5672 / 15672 |
| GreptimeDB | 監査ログ用時系列DB | 4000 / 4001 |
| Seq | 構造化ログ | 5341 |
ログイン情報
初期状態でのログイン認証情報は以下の通りです。
- システム管理画面:
https://localhost:7120
ユーザー:systemadmin/ パスワード:CodeSpirit@2025 - デフォルトテナント:
https://localhost:7120/default/login
ユーザー:admin/ パスワード:123@Admin
トラブルシューティング
ページが開かない / コンテナ起動エラー
Dockerイメージのプルに失敗している可能性があります。Docker Desktopの設定でプロキシやミラーサーバーを適切に設定してください。また、dotnet run --force を実行し、Aspireの構成を強制的に再構築してみてください。
SSL証明書のエラー
開発用証明書が信頼されていない場合、HTTPSアクセスでエラーが発生します。以下のコマンドで証明書を信頼してください。
dotnet dev-certs https --trust
メモリ不足エラー
GreptimeDBなどのサービスが起動しない場合、システムリソースが不足している可能性があります。不要なアプリケーションを終了するか、Program.cs でコンテナへのメモリ割り当てを調整してください。
LLM API設定不備による起動失敗
ConfigCenter や Web サービスが正常に起動しない場合、LLM APIキーの設定漏れが原因であることが多いです。dotnet user-secrets list コマンドで設定値を確認し、必須パラメータが正しくセットされているか検証してください。
アーキテクチャ概要
プロジェクトはクリーンアーキテクチャ（Clean Architecture）を採用しており、以下の構造を持ちます。
CodeSpirit/
├── Src/
│ ├── ApiServices/ # 各種マイクロサービス (Identity, Exam, Messaging等)
│ ├── Components/ # 再利用可能なコンポーネント (Amis, Audit, LLM等)
│ ├── CodeSpirit.AppHost/ # Aspireホストプロジェクト
│ ├── CodeSpirit.Core/ # コアドメイン定義
│ └── CodeSpirit.Web/ # フロントエンドWebアプリ
└── Tests/ # テストプロジェクト