diff options
| author | Sho Sakuma <me@m1sk9.dev> | 2026-08-31 15:32:37 +0900 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-08-31 15:32:37 +0900 |
| commit | 0e24ee83bc05ec4761d46696d07d4a2a4f0b97b6 (patch) | |
| tree | 370c556ac68086bb9203bb60b4b3f4b82e195db3 /website/src/ja/docs | |
| parent | 907778db55f7038385100bb2e389f15b6cba75eb (diff) | |
| parent | 2dcf483773fa1e0968f879e5758bf7e723601f05 (diff) | |
| download | LunaticChat-0e24ee83bc05ec4761d46696d07d4a2a4f0b97b6.tar.gz LunaticChat-0e24ee83bc05ec4761d46696d07d4a2a4f0b97b6.tar.bz2 LunaticChat-0e24ee83bc05ec4761d46696d07d4a2a4f0b97b6.zip | |
Merge pull request #297 from m1sk9/feat/release-v1.4.0
feat: Release LunaticChat v1.4.0
Diffstat (limited to 'website/src/ja/docs')
| -rw-r--r-- | website/src/ja/docs/configuration.md | 71 | ||||
| -rw-r--r-- | website/src/ja/docs/developers/engine.md | 11 | ||||
| -rw-r--r-- | website/src/ja/docs/features/admin.md | 49 | ||||
| -rw-r--r-- | website/src/ja/docs/permissions.md | 2 | ||||
| -rw-r--r-- | website/src/ja/docs/reference/commands.md | 15 |
5 files changed, 137 insertions, 11 deletions
diff --git a/website/src/ja/docs/configuration.md b/website/src/ja/docs/configuration.md index a2ae86f..59d0c73 100644 --- a/website/src/ja/docs/configuration.md +++ b/website/src/ja/docs/configuration.md @@ -22,7 +22,8 @@ LunaticChat の設定は `plugins/LunaticChat/config.yml` で管理されますï |---|---|---| | `messageFormat.*` | はい | — | | `features.*` | — | はい | -| `debug`, `checkForUpdates`, `language`, `userSettingsFilePath` | — | はい | +| `debug` | はい | — | +| `checkForUpdates`, `language`, `userSettingsFilePath` | — | はい | このコマンドはプレイヤーのほかコンソール・RCON からも実行できます.`lunaticchat.command.lc.reload` (デフォルト: op) が必要です. @@ -46,11 +47,77 @@ LunaticChat の設定は `plugins/LunaticChat/config.yml` で管理されますï | キー | 型 | デフォルト | 説明 | |------|------|------------|------| -| `debug` | Boolean | `false` | デバッグログを有効にする | +| `debug` | Boolean またはブロック | `false` | デバッグログ.[デバッグログ](#デバッグログ) を参照 | | `userSettingsFilePath` | String | `"player-settings.yaml"` | プレイヤー設定ファイルのパス | | `checkForUpdates` | Boolean | `true` | 起動時にアップデートを確認する | | `language` | String | `"en"` | プラグインの言語 (`en` / `ja`) | +## デバッグログ <Badge type="tip" text="v1.4.0~" /> + +`debug` は,LunaticChat がサーバーログにどれだけ書き出すかをカテゴリ単位で決めます.カテゴリはプラグイン +の領域を表すため,チャット経路の計装を入れてもハンドシェイクの問題が埋もれません. + +| カテゴリ | 出力する内容 | +|---|---| +| `config` | 起動時に読み込んだ設定と,リロードでの差分 | +| `chat` | メッセージのルーティング判定,クロスサーバーの重複排除ヒット | +| `channel` | 参加・離脱と,拒否された理由 | +| `conversion` | ローマ字変換の判定とキャッシュヒット | +| `protocol` | 送受信のサブチャネル・バイト長・メッセージ ID | +| `velocity` | ハンドシェイク,接続状態,presence,リレー判定 | +| `storage` | デバウンス保存,アトミック書き込みとそのサイズ | +| `command` | 権限拒否とコマンド結果 | + +書き方は 3 通りあります. + +```yaml +debug: false # 無効 (yes / no / on / off も使用可) + +debug: true # 全カテゴリ + +debug: velocity,protocol # 指定したカテゴリのみ + +debug: + enabled: true + categories: [velocity, protocol] # 同じ内容をブロックで書く場合 +``` + +`enabled: false` は,隣に `categories` が書かれていてもそちらより優先されます.そのビルドが知らない +カテゴリ名は警告として報告され,正しく書かれたカテゴリはそのまま適用されます. + +デバッグ行は `[LC/<カテゴリ>]` を前置して `INFO` で出力します.Paper の既定の log4j 設定では `INFO` +未満が出力されないためです. + +### 稼働中のカテゴリ切り替え + +``` +/lc debug # 現在出力しているカテゴリ +/lc debug <category> on|off +/lc debug all on|off +``` + +変更されるのは稼働中のサーバーだけで,`config.yml` は書き換えません.再起動または `/lc reload` で +ファイルの値に戻ります.`lunaticchat.command.lc.debug` (デフォルト: op) が必要です. + +### 診断レポート + +`/lc dump` は `plugins/LunaticChat/debug/report-<タイムスタンプ>.txt` を書き出し,プラグインフォルダーに出力した旨をチャットに返します.正確なパスはサーバーログにのみ残ります(このコマンドはファイルアクセスを持たない相手にも渡せるためです). +レポートにはプラグイン・プロトコル・サーバー・Java の版数,有効な機能,Velocity の接続状態,各ストアの +件数が含まれます.メッセージ本文・プレイヤー名・UUID は意図的に含めていないため,そのまま bug report に +貼れます.`lunaticchat.command.lc.dump` (デフォルト: op) が必要です. + +**Velocity プロキシ**には設定ファイルがないため,同じ記法をシステムプロパティまたは環境変数から読み取ります. + +``` +java -Dlunaticchat.debug=velocity,protocol -jar velocity.jar + +LUNATICCHAT_DEBUG=velocity,protocol +``` + +システムプロパティが環境変数より優先されます.これをハンドシェイクで伝播させないのは意図的です.プロキシ +は複数バックエンドの共有物であり,1 台の Paper サーバーが全体のログ量を決めてしまうためです. + + ## 機能設定 (`features`) ### クイックリプライ (`features.quickReplies`) diff --git a/website/src/ja/docs/developers/engine.md b/website/src/ja/docs/developers/engine.md index f798335..19071d4 100644 --- a/website/src/ja/docs/developers/engine.md +++ b/website/src/ja/docs/developers/engine.md @@ -81,6 +81,17 @@ UUID シリアライザが 2 つあるのは用途が違うためです. ドメインエラーを Paper / Velocity 双方で同じ型として扱えるよう,例外を engine に集約しています.共通の封印基底は持たず,`Exception` を直接継承するフラット構造です.存在/参照系・状態系・制限系・権限/BAN・KICK 系に分類でき,多くが `playerId` / `channelId` / `limit` をコンストラクタで受けてメッセージを自前生成します.基底を持たないため,呼び出し側は個別に catch する前提です. +## debug — 両プラットフォームが読む単一のスイッチ + +デバッグログは実装よりも先に契約です.`config.yml` とプロキシのシステムプロパティは `velocity,protocol` を同じ意味に解釈しなければならず,片側で増えたカテゴリはもう片側にも存在しなければなりません.そのため語彙を engine に置き,書き出しだけを platform 側に残しています. + +- `DebugCategory` — ログを出せる領域.運用者が書く綴りを `key` として持つ +- `DebugCategories.parse` / `resolve` — デバッグスイッチの唯一の解釈.Paper の `DebugConfigSerializer` と Velocity の `VelocityDebugSwitch` が共有する.未知の名前は例外にせず収集するため,タイポの影響はその名前だけに留まる +- `DebugLogger` — `log(category) { message }`.lambda であることが要点で,チャット経路は 1 通あたり 1 回計装されるが,無効時は文字列自体が組み立てられない +- `DebugState` — 現在有効なカテゴリ.`/lc reload` と `/lc debug` が稼働中に差し替える + +`JulDebugLogger` (Paper) と `Slf4jDebugLogger` (Velocity) はどちらも `INFO` で出力します.どちらのプラットフォームも,既定のログ設定では `INFO` 未満を出力しないためです. + ## permission / command — 中立抽象 Bukkit / Velocity どちらの API にも渡せる中立表現として,権限とコマンド結果を engine に置いています. diff --git a/website/src/ja/docs/features/admin.md b/website/src/ja/docs/features/admin.md index 17e08f8..dca648b 100644 --- a/website/src/ja/docs/features/admin.md +++ b/website/src/ja/docs/features/admin.md @@ -42,6 +42,44 @@ layout: doc - `config.yml` を完全に読み取れない場合は拒否されます.読み取れなかった設定をすべてまとめて表示し,稼働中の設定はそのまま維持されます.読み取れない設定を個別にデフォルトへフォールバックさせて起動を続行する起動時よりも厳格です - リロードはサーバーログにも記録されるため,フォーマットを変更した時期をあとから追跡できます.ファイルの読み取りはメインスレッド外で行われ,RCON セッションは応答が届く前に切断されるため,RCON から実行した場合の結果はコマンド出力ではなくログで確認します +## デバッグログ (`/lc debug`) <Badge type="tip" text="v1.4.0~" /> + +デバッグログは `config`,`chat`,`channel`,`conversion`,`protocol`,`velocity`,`storage`,`command` のカテゴリに分かれています.ハンドシェイクを追うために有効化しても,チャット 1 通あたり 1 行のログでログが埋まることはありません.各カテゴリが何を出力するかは[デバッグログ](/ja/docs/configuration#デバッグログ)を参照してください. + +``` +/lc debug # 現在出力しているカテゴリ +/lc debug velocity on +/lc debug all off +``` + +- **パーミッション**: `lunaticchat.command.lc.debug` (デフォルト: op).コンソール・RCON からも実行可能 +- 変更は `config.yml` に**書き戻されません**.再起動または `/lc reload` でファイルの値に戻るため,切り忘れたカテゴリがセッションを超えて残ることはありません +- ログ行は `[LC/<カテゴリ>]` を前置して `INFO` で出力されます.Paper の既定の log4j 設定では `INFO` 未満が出力されないためです + +Velocity プロキシには `config.yml` がないため,同じ記法を `-Dlunaticchat.debug=velocity,protocol` または環境変数 `LUNATICCHAT_DEBUG` から読み取ります. + +## 診断レポート (`/lc dump`) <Badge type="tip" text="v1.4.0~" /> + +bug report のトリアージに必要な情報を `plugins/LunaticChat/debug/report-<タイムスタンプ>.txt` に書き出し,プラグインフォルダーに出力した旨をチャットに返します. + +``` +/lc dump +``` + +レポートに含まれる内容: + +- LunaticChat の版数とコミット,プロトコル版数 +- サーバー実装・Bukkit API・Java・OS の版数 +- 有効な機能と,このサーバーの `serverName` +- ログを出力しているデバッグカテゴリ +- Velocity の接続状態,プロキシ側プラグインの版数,最後のエラー +- チャンネル数とメンバー総数,変換キャッシュの使用量,プレイヤー設定の件数 +- 導入されているプラグイン一覧 + +**メッセージ本文・プレイヤー名・UUID は意図的に含めていません**.公開 issue に貼ることを前提とした成果物であるためです. + +- **パーミッション**: `lunaticchat.command.lc.dump` (デフォルト: op).コンソール・RCON からも実行可能 + ## スパイモード `lunaticchat.spy` パーミッション (デフォルト: op) を持つプレイヤーは,サーバー上で送信されるダイレクトメッセージとチャンネルメッセージの両方を閲覧できます. @@ -78,15 +116,6 @@ checkForUpdates: true nightly ビルドは[セキュリティポリシー](https://github.com/m1sk9/LunaticChat/blob/main/.github/SECURITY.md)のサポート対象外です.本番サーバーではリリースビルドを使用してください. -## デバッグモード - -`debug` を `true` にすると,プラグインの詳細なログが出力されます.問題の調査やバグ報告時に有用です. - -```yaml -# config.yml -debug: true -``` - ## 言語設定 プレイヤーに表示されるメッセージの言語を切り替えられます.プラグインログやコンソール出力には影響せず,英語のみ出力となります. @@ -104,3 +133,5 @@ language: "ja" # "en" または "ja" | `lunaticchat.channelbypass` | op | チャンネル制限のバイパス | | `lunaticchat.noticeupdate` | op | アップデート通知の受信 | | `lunaticchat.command.lcv.status` | op | `/lcv status` コマンドの使用 | +| `lunaticchat.command.lc.debug` | op | `/lc debug` コマンドの使用 | +| `lunaticchat.command.lc.dump` | op | `/lc dump` コマンドの使用 | diff --git a/website/src/ja/docs/permissions.md b/website/src/ja/docs/permissions.md index 05ca9cb..90b7611 100644 --- a/website/src/ja/docs/permissions.md +++ b/website/src/ja/docs/permissions.md @@ -49,3 +49,5 @@ LunaticChat のすべてのパーミッションノードの一覧です. | `lunaticchat.channelbypass` | op | チャンネル制限のバイパス(キック・BAN 保護,強制削除) | | `lunaticchat.command.lcv.status` | op | `/lcv status` コマンドの使用 | | `lunaticchat.command.lc.reload` | op | `/lc reload` コマンドの使用 | +| `lunaticchat.command.lc.debug` | op | `/lc debug` コマンドの使用 | +| `lunaticchat.command.lc.dump` | op | `/lc dump` コマンドの使用 | diff --git a/website/src/ja/docs/reference/commands.md b/website/src/ja/docs/reference/commands.md index 6d34f1c..a51530e 100644 --- a/website/src/ja/docs/reference/commands.md +++ b/website/src/ja/docs/reference/commands.md @@ -44,6 +44,21 @@ LunaticChat で使用できるすべてのコマンドのリファレンスでã� - **コンソール・RCON からも実行可能** - `config.yml` を完全に読み取れない場合は拒否され,稼働中の設定がそのまま維持されます +### `/lc debug [category] [on|off]` <Badge type="tip" text="v1.4.0~" /> + +ログを出力しているデバッグカテゴリを表示し,個別に切り替えます.`all` は全カテゴリを指します.[デバッグログ](/ja/docs/configuration#デバッグログ)を参照してください. + +- **パーミッション**: `lunaticchat.command.lc.debug` (デフォルト: op) +- **コンソール・RCON からも実行可能** +- 変更は `config.yml` に書き戻されません.再起動または `/lc reload` でファイルの値に戻ります + +### `/lc dump` <Badge type="tip" text="v1.4.0~" /> + +診断レポートを `plugins/LunaticChat/debug/` に書き出し,その旨をチャットに返します.正確なパスはサーバーログにのみ残ります.版数・有効な機能・接続状態・各ストアの件数を含み,メッセージ本文・プレイヤー名・UUID は含みません. + +- **パーミッション**: `lunaticchat.command.lc.dump` (デフォルト: op) +- **コンソール・RCON からも実行可能** + ### `/lc settings [key] [on|off]` プレイヤー個人の設定を確認・変更します.引数なしで設定一覧を表示します. |
