Skip to content

getting-started.md

Latest commit

 

History

History
412 lines (317 loc) · 16.7 KB

getting-started.md

File metadata and controls

412 lines (317 loc) · 16.7 KB
Raw

CentralAdmin 導入・起動ガイド

1. 構成

CentralAdmin は次の 2 つで動きます。

  • ca.exe: 管理PCで実行する Windows CLI / TUI
  • centraladmin-node: 各 Linux VPS 上で SCP:SL プロセスを管理する Node

管理PCからVPSへの接続には、Windows標準の OpenSSH を使用します。Node の HTTP / WebSocket ポートは VPS の外部へ公開せず、SSH ローカルポートフォワード 経由で接続します。

2. 必要条件

管理PC:

  • Windows x64
  • ssh、sftp が実行できること
  • 公開鍵認証、ssh-agent、または ~/.ssh/config でVPSへ非対話接続できること

VPS:

  • Linux x64
  • systemd --user が利用できること
  • SCP:SL を実行する一般ユーザーでSSH接続できること
  • サーバーのインストールパスとポートが分かっていること

Node は ~/.local/bin/centraladmin-node、設定は ~/.local/bin/node.json、 サービスは ~/.config/systemd/user/centraladmin-node.service に配置されます。 ログインしていない間も動かすには linger が必要です。ca node status が状態を 表示し、必要な場合は管理者が loginctl enable-linger <user> を実行します。

3. Windowsへのインストール

Release パッケージの実行ファイルを同じディレクトリへ置き、そのディレクトリを ユーザー PATH に追加します。PATH 変更後は新しいターミナルを開いてください。

このワークスペースでの既定配置は次のとおりです。

D:\Tools\CentralAdmin\ca.exe                  … CLI / TUI
D:\Tools\CentralAdmin\centraladmin-node       … linux-x64。`ca node install` が VPS へ配る
D:\Tools\CentralAdmin\centraladmin-node.exe   … win-x64。この PC のサーバーを動かす

centraladmin-node.exe が無いと ca up などのローカル機能が使えません。 VPS しか使わない場合は不要です。

確認:

ca --help
where.exe ca

ソースから再発行する場合:

dotnet publish src/CentralAdmin.Cli/CentralAdmin.Cli.csproj `
  -c Release -r win-x64 --self-contained true `
  -p:PublishSingleFile=true -p:DebugType=None -p:DebugSymbols=false `
  -o release/centraladmin-win-x64

dotnet publish src/CentralAdmin.Node/CentralAdmin.Node.csproj `
  -c Release -r linux-x64 --self-contained true `
  -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true `
  -p:DebugType=None -p:DebugSymbols=false `
  -o release/centraladmin-node-linux-x64

Node は単一ファイル転送を前提にするため、 IncludeNativeLibrariesForSelfExtract=true を外さないでください。

4. 初期設定

雛形を作成します。

ca init

既定の設定ファイルは %APPDATA%\CentralAdmin\centraladmin.toml です。別の設定を使う場合は、全コマンドで -c <path> を指定できます。

最小例:

[[hosts]]
name = "tokyo-1"
ssh = "scpsl@203.0.113.10:22"
node_port = 47800
tags = ["prod", "jp"]

[[servers]]
id = "jp-main"
host = "tokyo-1"
port = 7777
path = "/home/scpsl/scpsl"
launcher = "native"
args = []
tags = ["prod", "vanilla"]

ssh には [user@]host[:port] または ~/.ssh/config の Host 名を指定できます。 秘密鍵を設定ファイルへ書く必要はありません。特定の鍵を固定する場合だけ identity = "~/.ssh/id_ed25519" を追加します。

TUI のホスト追加・編集では、SSH 認証に「自動セットアップ」を選べます。 SSH パスワードをその場で1回だけ使い、~/.ssh/centraladmin_ed25519 に CentralAdmin専用鍵を作成して、接続ユーザーの authorized_keys へ公開鍵を登録します。 パスワードは画面では伏せ字になり、設定ファイル・環境変数・コマンドライン・一時 ファイルには保存されません。サーバー側でパスワードログインが無効な場合は、 既存の鍵を指定するか、VPSコンソールから公開鍵を登録してください。

ホスト定義は TOML を直接編集せず、CLI から管理できます。

# SSH ホストとこの PC を追加
ca host add tokyo-1 --ssh scpsl@example.com --tag prod --tag jp
ca host add local --local --scan-root 'D:\SCPSL_Works'

# 一覧と変更。名前変更時は [[servers]] の host 参照も同時に更新される
ca host list
ca host edit tokyo-1 --ssh scpsl@new.example.com
ca host edit tokyo-1 --rename tokyo-main

# サーバーから参照されていないホストだけ削除できる
ca host remove old-host

ca host edit では --node-port、--node-data-directory、--identity、 --node-binary、--scan-root、--tag も変更できます。任意項目を消す場合は 対応する --clear-* オプションを使います。サーバーパスの意味が変わるため、 サーバーから参照中のホストは ssh / local を切り替えられません。

通常と異なる場所を使うサーバーでは、[[servers]] に次を追加できます。

scp_config_path = "/home/scpsl/.config/SCP Secret Laboratory/config/7777"
exiled_plugins_path = "/home/scpsl/.config/EXILED/Plugins"

この PC のサーバーを管理する

管理PC自身で SCP:SL を動かす場合は、transport = "local" のホストを使います。 SSH も VPS も要りません。

[[hosts]]
name = "local"
transport = "local"
# 省略時は 47800。ローカルホストを複数置く場合だけ別々の値にします。
node_port = 47850
# サーバーの自動検出で掘るディレクトリ。Steam ライブラリは指定しなくても見つかります。
scan_roots = ['D:\SCPSL_Works']
tags = ["local"]

[[servers]]
id = "local-7777"
host = "local"
port = 7777
# Windows のパスはリテラル文字列(シングルクォート)で書くとエスケープが要りません。
path = 'D:\SCPSL_Works\11.1.0'
launcher = "native"

この設定は手で書かなくても、次のどちらかで自動生成されます。

ca up 7777        # 検出 → 追加 → 起動 まで一息に
ca server add     # 追加だけ(起動しない)

ローカルの centraladmin-node.exe は ca と同じディレクトリに置きます (見つからない場合は [[hosts]] の node_binary で明示できます)。 win-x64 向けの発行は次のとおりです。

dotnet publish src/CentralAdmin.Node/CentralAdmin.Node.csproj `
  -c Release -r win-x64 --self-contained true `
  -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true `
  -p:DebugType=None -p:DebugSymbols=false `
  -o release/centraladmin-win-x64

ローカルノードは ca から切り離して起動されるため、ca や TUI を閉じても ゲームサーバーは動き続けます。状態・シークレット・ログは %LOCALAPPDATA%\CentralAdmin\LocalNode\<node_port>\ に置かれます。

ca local up      # 起動(ca の操作時にも自動で起動します)
ca local status  # pid・管理台数・直近ログ
ca local down    # 稼働中のサーバーを停止してからノードを止める

5. 接続確認とNode導入

最初に設定、TCP、known_hosts、SSH、Node API を順番に確認します。

ca doctor
ca doctor host:tokyo-1

初回は Node が未導入という結果が含まれていても構いません。続けて、CLI と同じ ディレクトリにある Linux バイナリをVPSへ導入します。

ca node install tokyo-1
ca node status tokyo-1

更新時:

ca node update tokyo-1

ca node install tokyo-1 を導入済みのホストへ再実行した場合も、成果物の 差し替え後に既存サービスを再起動するため、最新の Node が反映されます。

同じ操作はTUIでも実行できます。ca でダッシュボードを開き、h のホスト管理で 対象のSSHホストを選んで i（導入）、u（更新）、r（状態確認）を押します。 Node列には稼働状態、PID、Lingerの警告、操作エラーが表示されます。

別の成果物を使う場合は ca node install tokyo-1 --binary <centraladmin-nodeへのパス> と指定します。

6. 起動と日常操作

# 一覧
ca status
ca status tag:prod

# 起動・停止・再起動
ca start jp-main --reason "起動"
ca stop host:tokyo-1 --reason "保守"
ca restart tag:prod --reason "更新反映"

# ログ
ca logs jp-main -n 200
ca logs jp-main -f
ca logs tag:prod -f --grep "(?i)exception"

# ホストの追加・一覧・編集・削除
ca host add tokyo-1 --ssh scpsl@example.com
ca host list
ca host edit tokyo-1 --tag prod --tag jp
ca host remove old-host

# サーバーの追加・一覧・編集・削除
ca up 7778                      # 追加して起動
ca server add --path 'D:\SCPSL' # 追加のみ
ca server list
ca server edit local-7778 --port 7779   # ポート等の変更(停止中のみ)
ca server remove local-7778
# Nodeへ接続できない場合だけ、管理設定から外す
ca server remove local-7778 --config-only

# 対話型ダッシュボード
ca

セレクタはサーバーID、tag:prod、host:tokyo-1、jp-*、またはカンマ区切りの 和集合を受け付けます。省略または * は全サーバーです。複数台または prod 対象の変更操作では確認が入り、非対話実行では --yes が必要です。

-c <path> などの共通オプションは、サブコマンドの後ろに置いてください (ca local status -c ...)。先頭に置くと既定コマンドの引数として解釈されます。

サーバーの追加・削除は、対応する Node に対してその場で反映されます。Node の 再起動は不要なので、同じホストで動いている他のサーバーは止まりません。 古い Node(動的登録に未対応)の場合だけ ca node update <host> を促します。

ダッシュボードのキー操作

キー 動作
↑↓ / j k サーバーを選ぶ
Tab 一覧と console を行き来する
PgUp / PgDn / Home / End console をスクロールする
f 新しい行への追従を切り替える
c consoleの色表示を切り替える（SCP:SLカラーコード／出力元に応じた色）
/ console を絞り込む(空で解除)
: 選択中のサーバーへコマンドを送る
s / x / r 起動 / 停止 / 再起動
a サーバーを追加する(設定にも書く)
e 選択中のサーバーの ID / ポート / パス / 起動方式を変える(停止中のみ)
n ポートを指定してすぐ起動する
D サーバーを設定とノードから外す(大文字のみ)
h ホスト管理を開く。f ファイル管理、i Node導入、u Node更新、r Node状態確認、a 追加、Enter/e 編集、D 削除
t バックグラウンド転送の進捗バーと履歴を開く
l ローカルノードを起動 / 停止する
d 選択中のサーバーを診断する
? ヘルプ
q / Esc 終了 / オーバーレイを閉じる

確認・入力・追加/編集ウィザードはすべて画面内で完結します。操作は背景で実行されるため、 実行中もコンソールの流入と状態表示は止まりません。

ホストのファイル管理とログ共有

h でホスト管理を開き、対象ホストを選んで f を押すと、そのホストの ログインユーザー権限でファイルを閲覧できます。ディレクトリは Enter、ファイルは Enter で内蔵エディタへ進みます。エディタはNORMAL/INSERTモード、hjkl、i/a/o などのVim風操作に加えて、Shift+矢印/Shift+Home/Shift+End での文字選択、 Ctrl+A 全選択、Ctrl+S 保存、Ctrl+C 選択範囲コピー（未選択時は現在行）、 Ctrl+V 貼り付けを使用できます。IME入力中はOSの実カーソルを編集中の文字位置へ合わせ、 背景更新による再描画を確定後まで保留します。Windowsのコピー／貼り付けは Unicodeクリップボードへ直接読み書きします。リモートファイルはOSの一時ディレクトリへ受信し、 保存または取り消し後に 一時ファイルを削除します。編集対象は64 MiB以下のUTF-8テキストです（編集中の本文は TUI上でも保持するため、メモリ保護の上限を設けています）。

ファイル画面で u を押し、OSのファイルマネージャーからファイルまたはフォルダを 端末へドラッグ＆ドロップすると、表示中のディレクトリへ転送できます。g は選択した ホスト側のファイル／フォルダを、入力したこちら側のディレクトリへ取得します。転送は バックグラウンドで続くため、画面を戻ってサーバー操作を継続できます。t で進捗バーを いつでも確認できます。

ファイル画面では通常の管理操作も行えます。n は新規ファイル、N は新規フォルダ、 c は同じホスト内でのコピー、m は移動または名前変更です。相対パスは表示中の ディレクトリを基準にします。既存の項目は暗黙に上書きしません。D は選択項目を削除し、 フォルダの場合は内容を含めて再帰削除するため、必ず確認画面が表示されます。

TUIが受信したconsoleログは、ANSI制御文字を除いた共有用コピーとしてCA実行ファイルと 同じ場所の logs/<ホスト名>/<ゲームポート>/console.log に追記されます。表示側の色は c で切り替えられますが、共有ログは検索・転送しやすいプレーンテキストを維持します。

サーバーの追加・変更・通常の削除は、設定ファイルと稼働中ノードの両方へ同時に反映されます。 削除時に Node へ接続できない場合、TUI は理由を表示したうえで「管理設定からのみ削除」する 二段階目の確認を出します。CLI では ca server remove <id> --config-only が同じ操作です。 この場合は Node 側の登録やプロセスが残る可能性があるため、接続復旧後に停止・整理してください。 ポートやパスの変更はノードへ登録し直す必要があるため、 停止中のサーバーにしか適用できません(稼働中は設定を書き換える前に拒否されます)。

JSONで処理したい場合:

ca status --json
ca node status tokyo-1 --json

7. ファイル配布

例として bundles/MyPlugin.dll を用意し、SHA-256を取得します。

(Get-FileHash .\bundles\MyPlugin.dll -Algorithm SHA256).Hash.ToLowerInvariant()

bundles/plugins.toml:

name = "my-plugin"
restart_required = true

[[files]]
source = "MyPlugin.dll"
target = "MyPlugin.dll"
scope = "exiled-plugins"
sha256 = "ここへ64桁のSHA-256"
mode = "0644"

source はバンドル TOML からの相対パスです。scope は install、 scp-config、exiled-plugins のいずれかです。

まず変更計画だけを確認し、その後に適用します。

ca push .\bundles\plugins.toml tag:staging --dry-run
ca push .\bundles\plugins.toml tag:staging --reason "plugin update"
ca push .\bundles\plugins.toml tag:prod --canary 1 --max-parallel 2 --yes

出力された commit operation ID から戻す場合:

ca rollback jp-main --op commit-... --reason "不具合復旧"

8. 診断

ca diagnose jp-main --agent codex --since 10m
ca watch

ca diagnose はログや状態を秘匿化した診断バンドルへまとめ、設定されたエージェント へ渡します。--no-redact は外部エージェントへ未秘匿データを渡すため、必要な場合 だけ使用してください。Codex を使う場合は、管理PC側で codex がインストール・認証 済みである必要があります。

9. 困ったとき

ca --help
ca <command> --help
ca doctor
ca node status tokyo-1
  • ca が見つからない: PATH追加後に新しいターミナルを開き、where.exe ca を確認。
  • SSHで止まる: ssh <設定した接続先> が非対話で成功するか確認。
  • ホスト鍵エラー: 警告内容を確認し、正しい鍵だと確認できた場合だけ known_hosts を更新。
  • Nodeが停止する: ca node status <host> と ca logs <server-id> を確認。
  • TUIが起動しない: 対話端末で引数なしの ca を実行。CIやリダイレクト環境では ca status --json などの動詞コマンドを使用。