
# GameFrameX Server
[](LICENSE)
[](https://github.com/GameFrameX/GameFrameX.Server.Source/releases)
[](https://dotnet.microsoft.com/download/dotnet/10.0)
[](https://gameframex.doc.alianblank.com)
[](https://discord.gg/VDWUjWMDw9)
[](https://github.com/GameFrameX/gameframex)
[](https://www.bilibili.com/video/BV1yrpeepEn7)
[](https://gitee.com/GameFrameX/gameframex)
**インディゲーム開発者向けオールインワンソリューション · インディ開発者の夢を支援**
[ドキュメント](https://gameframex.doc.alianblank.com) · [クイックスタート](#クイックスタート) · QQグループ: 467608841 / 233840761
[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | **日本語** | [한국어](README.ko.md)
## 目次
- [プロジェクト概要](#プロジェクト概要)
- [機能概要](#機能概要)
- [クイックスタート](#クイックスタート)
- [前提条件](#前提条件)
- [インストール](#インストール)
- [使用例](#使用例)
- [設定管理](#設定管理)
- [ビジネスロジック開発](#ビジネスロジック開発)
- [ホットアップデート機構](#ホットアップデート機構)
- [Docker デプロイ](#docker-デプロイ)
- [マルチプロセス・クロスプロセス連携](#マルチプロセスクロスプロセス連携)
- [モニタリングとオブザーバビリティ](#モニタリングとオブザーバビリティ)
- [テスト](#テスト)
- [アーキテクチャ](#アーキテクチャ)
- [プロジェクト構成](#プロジェクト構成)
- [プロセストポロジ同型](#プロセストポロジ同型)
- [マルチロール起動](#マルチロール起動)
- [Docker Compose ファイル](#docker-compose-ファイル)
- [依存関係](#依存関係)
- [ドキュメントとリソース](#ドキュメントとリソース)
- [コミュニティとサポート](#コミュニティとサポート)
- [コントリビュート](#コントリビュート)
- [変更履歴](#変更履歴)
- [ライセンス](#ライセンス)
---
## プロジェクト概要
GameFrameX Server は、C# .NET 10.0 で開発された高性能・クロスプラットフォームのゲームサーバーフレームワークです。Actor モデルを採用し、ホットアップデート機構をサポートしています。マルチプレイヤーオンラインゲーム開発向けに設計されており、Unity3D、Godot、LayaBox など多様なクライアントプラットフォームとの統合をサポートします。
**設計理念**: 大道至簡、シンプルイズベスト
---
### 機能概要
#### 高性能アーキテクチャ
- **Actor モデル**: TPL DataFlow 上に構築されたロックフリー・高同時実行システム。メッセージパッシングにより従来のロックのパフォーマンス劣化を回避
- **完全非同期プログラミング**: 完全な async/await 非同期プログラミングモデル
- **ゼロロック設計**: Actor 内部状態はメッセージキューによる直列化アクセスでロック不要
- **バッチ永続化**: バッチDB書き込みをサポート。バッチサイズとタイムアウト設定可能
- **スノーフレーク ID 生成**: 分散ユニーク ID ジェネレーター内蔵。ワーカーノード・データセンター設定対応
#### ホットアップデートシステム
- **ゼロダウンタイム更新**: 実行時に新しいロジックアセンブリをロード。サービス停止不要
- **状態・ロジック分離**: 永続化状態データ(Apps 層)とホットアップデート可能なビジネスロジック(Hotfix 層)を厳密に分離
- **グレースフル移行**: 旧アセンブリは10分間の猶予期間を保持。進行中のリクエスト完了後にアンロード
- **バージョン管理**: HTTP エンドポイント経由でバージョン番号を指定してロード可能
#### マルチプロトコルネットワーク通信
- **TCP**: SuperSocket ベースの高性能 TCP サーバー。メインゲーム通信プロトコル
- **UDP**: オプションの UDP プロトコルサポート
- **WebSocket**: SuperSocket WebSocket ベースの双方向通信
- **HTTP/HTTPS**: Kestrel ベースの HTTP サービス。Swagger ドキュメント、CORS、ヘルスチェック対応
- **KCP**: 正式サポート(オプトイン)に昇格した UDP 信頼性伝送。`KcpPort` が `0` の場合は TCP ポートを共用
#### データベースと永続化
- **デュアルデータベース Provider**: `DatabaseProvider` で `Mongo`(デフォルト)または `PostgreSql` を選択。両 Provider は同じ `GameFrameX.DataBase` 抽象レイヤーを共有
- **MongoDB Provider**: 完全な MongoDB 統合。ヘルスステートマシン対応(Healthy → Degraded → Unhealthy → Recovering)
- **PostgreSQL Provider**: Npgsql ベース。MongoDB Provider と同等のリトライ / リカバリ / 可用性 / ヘルスチェック能力を備える
- **透過的永続化**: StateComponent の自動シリアライズ/デシリアライズ。定期的バッチ upsert 操作で永続化
#### モニタリングとオブザーバビリティ
- **OpenTelemetry**: 包括的なメトリクス(Metrics)、トレーシング(Tracing)、ロギング(Logging)
- **Prometheus**: ネイティブメトリクスエクスポートエンドポイント
- **Grafana Loki**: ログ集約出力対応
- **Serilog**: 構造化ログ。コンソール、ファイル、Loki マルチ出力対応
---
## クイックスタート
### 前提条件
- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) のみをサポートします。.NET 8/9 はサポート対象外です。
- [MongoDB 4.x+](https://www.mongodb.com/try/download/community)(デフォルト Provider。`--DatabaseProvider=PostgreSql` で PostgreSQL も利用可能)
- Visual Studio 2022 または JetBrains Rider(推奨)
### インストール
1. **リポジトリをクローン**
```bash
git clone https://github.com/GameFrameX/GameFrameX.Server.Source.git
cd GameFrameX.Server.Source
```
2. **依存関係を復元**
```bash
dotnet restore
```
3. **プロジェクトをビルド**
```bash
dotnet build
```
4. **MongoDB を起動**
```bash
# ローカルインストール
mongod --dbpath /path/to/data
# または Docker を使用
docker run -d -p 27017:27017 --name mongo mongo:8.2
```
5. **サーバーを起動**
```bash
dotnet run --project GameFrameX.Launcher -- \
--ServerType=Game \
--ServerId=1000 \
--OuterPort=29100 \
--HttpPort=28080 \
--DataBaseUrl=mongodb://127.0.0.1:27017 \
--DataBaseName=gameframex
```
6. **起動確認**
- ヘルスチェック: `http://localhost:28080/health`(ライブネスプローブ: `/alive`)
- コンソールログで起動成功を確認
---
## 使用例
以下の例では、設定、ビジネスロジック、ホットアップデート、デプロイ、デバッグまでの開発フローを網羅しています。
---
### 設定管理
GameFrameX はコマンドライン引数(`--Key=Value`)で設定を行います。すべての設定項目は `StartupOptions` クラスで定義されています。
#### サーバー設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `ServerType` | サーバータイプ(必須) | なし | `Game`、`Social` |
| `ServerId` | サーバー一意 ID | なし | `1000` |
| `ServerInstanceId` | サーバーインスタンス ID(同タイプの異なるインスタンスを区別) | `0` | `1001` |
| `MinModuleId` | ビジネスモジュール開始 ID(モジュールシャーディング) | `0` | `100` |
| `MaxModuleId` | ビジネスモジュール終了 ID(モジュールシャーディング) | `0` | `1000` |
| `TimeZone` | サーバータイムゾーン | `Asia/Shanghai` | `UTC` |
| `IsUseTimeZone` | カスタムタイムゾーンを有効化 | `false` | `true` |
| `Language` | 言語設定 | なし | `zh-CN` |
#### ネットワーク設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `InnerHost` | 内部通信用 IP(クラスタ間) | `0.0.0.0` | `0.0.0.0` |
| `InnerPort` | 内部通信用ポート | `8888` | `29100` |
| `OuterHost` | 外部通信用 IP(クライアント向け) | `0.0.0.0` | `0.0.0.0` |
| `OuterPort` | 外部通信用ポート | なし | `29100` |
| `IsEnableTcp` | TCP サービスを有効化 | `true` | `true` |
| `IsEnableUdp` | UDP サービスを有効化 | `false` | `true` |
| `IsEnableKcp` | KCP サービスを有効化(設定ファイルのみ) | `false` | `true` |
| `KcpPort` | KCP ポート(`0` で TCP ポートを共用) | `0` | `29120` |
| `InterNodeAuthSecret` | ノード間 RPC 認証 共有シークレット(プロトコルハンドシェイク HMAC。空 = 無効)。クラスタ内の全ノードで同一値を設定 | なし | `s3cr3t` |
| `IsEnableWebSocket` | WebSocket を有効化 | `false` | `true` |
| `WsPort` | WebSocket ポート | `8889` | `29300` |
| `IsEnableHttp` | HTTP サービスを有効化 | `true` | `true` |
| `HttpPort` | HTTP サービスポート | `8080` | `28080` |
| `HttpsPort` | HTTPS サービスポート | なし | `443` |
| `HttpsCertPath` | HTTPS 証明書ファイルパス(PFX)、`HttpsPort > 0` の場合は必須 | なし | `/path/cert.pfx` |
| `HttpsCertPassword` | HTTPS 証明書パスワード(任意) | なし | |
| `HttpSignSecret` | HTTP 署名シークレット(HMAC-SHA256)、署名検証有効時は必須。空の場合はすべて拒否(fail-closed) | なし | `a-strong-secret` |
| `HttpUrl` | API ルートパス | `/game/api/` | `/game/api/` |
| `HttpIsDevelopment` | HTTP 開発モード(Swagger を有効化) | `false` | `true` |
| `Online` | Online 機能ファミリーの設定セクション:`EnableRuntime` / `EnableAdminApi`(既定 `false`)、`EnableRoles`(既定 `["Game"]`)、`Capabilities` / `Disable` フィルター、`UseGameDbStores`、機能 Id ごとの `Settings` | なし | `Configs/app_config.json` を参照 |
| `OnlineAdminPort` | Online 管理 API リッスンポート | `28090` | `28090` |
| `OnlineAdminApiPrefix` | Online 管理 API ルートプレフィックス | `online/admin` | `online/admin` |
| `OnlineTenantId` | Online Runtime 認可テナント ID(スコープトリプル) | `0` | `1` |
| `OnlineAppId` | Online Runtime 認可アプリ ID(スコープトリプル) | `0` | `1` |
#### データベース設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `DatabaseProvider` | データベース Provider | `Mongo` | `PostgreSql` |
| `DataBaseUrl` | データベース接続文字列 | なし | `mongodb://localhost:27017` |
| `DataBaseName` | データベース名 | なし | `gameframex` |
| `DataBasePassword` | データベースパスワード | なし | `your_password` |
#### Actor 設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `ActorTimeOut` | Actor タスク実行タイムアウト(ミリ秒) | `30000` | `60000` |
| `ActorQueueTimeOut` | Actor キュータイムアウト(ミリ秒) | `30000` | `60000` |
| `ActorRecycleTime` | Actor アイドルリサイクル時間(分) | `15` | `30` |
| `ActorLimitRule` | Actor 呼び出し制限ルール(None/NoBidirectionCall) | `None` | `NoBidirectionCall` |
| `HotfixVerifyEnabled` | ホットフィックス アセンブリ読み込み SHA-256 検証 | `false` | `true` |
| `SaveDataInterval` | データ保存間隔(ミリ秒) | `30000` | `60000` |
| `SaveDataBatchCount` | バッチ保存数 | `500` | `1000` |
| `SaveDataBatchTimeOut` | バッチ保存タイムアウト(ミリ秒) | `30000` | `60000` |
#### ログ設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `IsDebug` | デバッグログマスタースイッチ | `false` | `true` |
| `LogIsConsole` | コンソール出力 | `true` | `false` |
| `LogIsWriteToFile` | ファイル出力 | `true` | `false` |
| `LogEventLevel` | ログレベル | `Debug` | `Information` |
| `LogRollingInterval` | ログローリング間隔 | `Day` | `Hour` |
| `LogIsFileSizeLimit` | 単一ファイルサイズ制限 | `true` | `false` |
| `LogFileSizeLimitBytes` | ファイルサイズ制限 | `104857600` (100MB) | `52428800` |
| `LogRetainedFileCountLimit` | 保持ファイル数 | `31` | `90` |
| `LogIsGrafanaLoki` | Grafana Loki 出力 | `false` | `true` |
| `LogGrafanaLokiUrl` | Grafana Loki URL | `http://localhost:3100` | — |
#### モニタリング設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `IsOpenTelemetry` | OpenTelemetry を有効化 | `false` | `true` |
| `IsOpenTelemetryMetrics` | メトリクス収集を有効化 | `false` | `true` |
| `IsOpenTelemetryTracing` | 分散トレーシングを有効化 | `false` | `true` |
| `MetricsPort` | Prometheus メトリクスポート | `0`(HTTP ポートを共用) | `9090` |
| `IsMonitorMessageTimeOut` | メッセージ処理タイムアウト監視 | `false` | `true` |
| `MonitorMessageTimeOutSeconds` | タイムアウト閾値(秒) | `1` | `5` |
#### ID 生成設定
| 設定項目 | 説明 | デフォルト | 例 |
|:--------|:-----|:----------|:---|
| `WorkerId` | スノーフレーク ID ワーカーノード ID | `1` | `2` |
| `DataCenterId` | スノーフレーク ID データセンター ID | `1` | `2` |
#### 起動コマンド例
```bash
# 最小起動パラメータ
dotnet GameFrameX.Launcher.dll \
--ServerType=Game \
--ServerId=1000 \
--DataBaseUrl=mongodb://127.0.0.1:27017 \
--DataBaseName=game_db
# フル起動パラメータ
dotnet GameFrameX.Launcher.dll \
--ServerType=Game \
--ServerId=1000 \
--ServerInstanceId=1 \
--InnerHost=0.0.0.0 \
--InnerPort=29100 \
--OuterHost=0.0.0.0 \
--OuterPort=29100 \
--HttpPort=28080 \
--IsEnableHttp=true \
--HttpIsDevelopment=true \
--IsEnableWebSocket=false \
--DataBaseUrl=mongodb://127.0.0.1:27017 \
--DataBaseName=gameframex \
--IsDebug=true \
--IsOpenTelemetry=true \
--IsOpenTelemetryMetrics=true \
--LogIsConsole=true \
--LogIsWriteToFile=true
```
---
### ビジネスロジック開発
#### コンポーネント・エージェントパターン
フレームワークのコア設計パターンは**状態・ロジック分離**です。永続化状態(Apps 層、ホット更新不可)とビジネスロジック(Hotfix 層、ホット更新可能)を厳密に分離します。
**1. 状態の定義(Apps 層)**
```csharp
// GameFrameX.Apps/Player/BagState.cs
public class BagState : BaseCacheState
{
public List