Files
pages/docs/design/configuration-panels.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

14 KiB

Configuration panels, bookmarks, and resource charts

Resource history is now collected by a built-in background event, not by an open browser. The current persistence, retention and extension-catalog design is specified in System extensions; it supersedes the earlier in-memory live-sampling description below.

Bookmark sections and direct home-page management are specified in Home navigation and hosted Vim. The flat bookmark representation below remains compatible; section rows extend it.

設定画面の構成

/-/sys/config?panel=<id> を共通シェルとする。config_panels.go の サーバー所有レジストリがグループとパネルIDを定義する。

グループ パネルID
表示・ナビゲーション home, editor, bookmarks, nav-home, nav-system
コンテンツ objects, assets
認証・アクセス auth(アカウント), auth-providers, auth-sessions
キャンパス・ドメイン campuses, domains
連携アダプタ adapters, adapters-builtin, adapter-<plugin-id>
運用 scheduler(実行状態・リソース), logs(実行履歴・ログ), events, queue

選択グループを展開し、他グループは折りたたむ。各summaryは手動でも開閉可能。 サイドバー全体を閉じた場合は本文の幅も広げる。小画面は縦並びとする。 パネル選択をURLに反映するため再読み込み/直接リンクで同じパネルを開ける。 既存の panel=nav は nav-home として扱う。

共通CSSは /static/css/config.css、遷移・APIエラー処理・グラフは /static/js/config-panels.js。チェックボックスはネイティブinputを残した role=switch とし、labelの data-label をCSSの attr(data-label) で表示する。 inputにも翻訳済み aria-label を付け、キーボード操作・disabled・フォーム所属・ 送信値を保持する。秘密情報は既存のpassword入力と空欄時保持の契約に従う。

スケジューラの情報分離

  • 実行状態: 件数、直近25ジョブ、再試行/キャンセル、プレビュー生成の手動トリガー。
  • イベント: 実施タイミング、次回実行、追加/実行/削除。周期と日時は選択した スケジュール方式に対応する項目だけ表示。優先度・試行回数・JSONは詳細設定に置く。
  • キュー: 一時停止、並列数、キュー深度、リトライ待ち時間、履歴保持。
  • ログ: 直近50件の実行ログ。
  • リソース: 下記のライブグラフ。

従来はスケジューラを開くと4種類のAPIをまとめて取得していた。現在は選択した パネルで必要なAPIだけ取得し、遷移時に中止する。定期取得はリソースパネルに限定。 設定フォームを定期更新で上書きしない。APIの非JSONエラーも本文/ステータスとして 表示し、JSON構文エラーで本来のエラーを隠さない。

アセット一覧の障害と是正

報告: Unexpected token 'o', "forbidden: "... is not valid JSON。 原因はGETがendpoint policyに登録されていなかったこと。POST/DELETEの登録により 同じエンドポイントがmethod-closedになり、一覧GETが認可ハンドラに到達する前に 拒否されていた。GET/POST/DELETEは型付きpolicyからアセット管理ハンドラへ渡し、 現行のキャンパス/ドメイン管理者権限をハンドラで検証する。

調査時の asset:image:profile は、HEAD、履歴、実ファイルSHA-256が一致し、 記録サイズ・実サイズともに2,627バイトだった。データを削除・再生成する必要はない。

あわせて以下を是正した。

  • 参照数を「同一ドメインにPathを持つ参照元Revisionの異なり数」に統一。 過去HEADと現在HEADを含める。詳細はPath別の行を返すため、同じRevisionの 別名Pathがある場合の行数は参照数と一致するとは限らない。
  • HEAD履歴がない旧データも、現在HEADから依存関係を取得可能にした。
  • 更新/削除は書き込みSQLでも期待HEADを比較し、競合を検出する。
  • 同じバイト列でもMIME/ファイル名を変えた場合はメタデータと履歴を更新する。
  • CLIのアセット書き込みもMIME、ファイル名、サイズ、履歴を同一トランザクションで更新。
  • 一覧APIは no-store。画面はテキスト形式の拒否応答も読み取れる。

HEADハッシュのETagはバイト列の識別子である。メタデータだけの同時更新を厳密に 区別するには将来、Asset状態バージョンを含めた条件付き更新契約が必要。

ブックマークマネージャー

panel=bookmarks でドメイン共通のブックマークを最大64件管理する。 行には名前、指定方法(Path / URL)、宛先、上下移動、削除を用意する。 保存時に管理者権限を検証し、入力が不正なら保存済み一覧を変更しない。

既存の home_bookmarks JSONを継承し、kind を任意追加する。

[{"label":"Docs","kind":"path","href":"/docs"},
 {"label":"External","kind":"url","href":"https://example.com/"}]

Pathはドメインルート相対の意味を持ち、URL化するときに空白・%・Unicodeを 適切にエスケープする。URLはHTTP(S)またはルート相対URLを許可し、JavaScript、 プロトコル相対URL、資格情報を含むURLは拒否する。ローカルの宛先は表示時にも認可する。 ホーム設定の保存ではブックマークを更新せず、別パネルの保存で消える事故を防ぐ。 現在は「検索+ブックマーク」のホームに反映し、共通サイドバー実装時に同じデータを使う。 個人ブックマーク、フォルダ分類、UUID追従型ブックマークは将来の別拡張とする。

設定テーブルの表示密度

設定画面の .recent-table / .config-form-table に限定して行の余白を圧縮する。 セルの上下paddingは0.22rem、行内コントロールは高さ1.8rem、セル内フォームの外余白は0。 空のform要素は表示しないが、form IDを用いた行内入力・保存/削除との関連付けは維持する。 名前と識別子を1行にまとめ、通常セルは折り返さず、幅不足はテーブル領域内で横スクロール。 長いPath・ファイル名・URL・補足説明は全文をDOMとtitleに残した省略表示とする。 ログ展開行とその本文は例外として複数行表示を保つ。Viewer/Editorなど他画面のテーブルには適用しない。

リソースグラフ

scheduler パネルはhtop型の監視画面とし、上部に現在値と4つのグラフ、下部に 実行中ジョブのみを表示する。旧 panel=resources は scheduler の別名として維持。 収集設定・表示期間・自動更新・指標の説明は、タイトル横の歯車から開くネイティブdialogに まとめる。閉じるボタン・Escape・背景クリックで閉じ、歯車へフォーカスを戻す。 別パネルへの移動時も閉じる。表示設定は即時反映し、同一originのlocalStorage pageswiki.monitor.display.v1 に期間・自動更新ON/OFF・現在値とグラフの更新間隔を保存。 初期値は1時間・自動更新ON・現在値1秒・グラフ5秒。保存された期間があれば優先する。 不正な値は使わず、storage利用不可でも既定値で動作する。収集設定は保存操作でDBへ永続化。 時間範囲はタイトル直下に1つだけ表示し、各グラフの時間ラベル・表示点数は出さない。 更新操作はリロードアイコン、設定は歯車。履歴へのリンクはサイドバーに集約する。 グラフは常に1行4列。狭い画面ではグラフ領域内だけ横スクロールし、2列/1列へ折り返さない。

GET /_/api/v1/queue/resources の現在値と GET /_/api/v1/queue/jobs?status=running&limit=100 を既定1秒間隔で取得する(要求完了後に次を予約し、重複実行しない)。実行中の絞り込みはLIMITより前にDBで行い、最近終了した ジョブに長時間実行ジョブが埋もれない。ワーカー上限32に対し表示上限100。 現在値のキュー統計はstatus索引で待機・実行中だけを集計し、完了履歴を全走査しない。 グラフは既定5秒ごとに、現在値から得たライブサンプルを履歴へ重ねて描画する。 両間隔は1〜60秒で設定可能。グラフ間隔は現在値の間隔以上に補正する。 永続履歴APIの再取得は30秒ごとに抑え、期間変更と手動更新時は即時再取得。 ライブバッファも描画も最大361点。I/O速度は間引き前に計算し、時間バケットの最終値を描く。 ブラウザ内ライブサンプルはDBへ書き戻さず、再起動後は永続サンプルから復元する。 バックグラウンド収集は引き続きビルトイン resource.sample イベントで行い、画面を閉じても7日間保持する。 詳しい収集契約は システム拡張 を参照。 パネルを離れる、タブが非表示になる、自動更新を止める場合は定期取得を停止する。 取得中リクエストはAbortControllerで中止し、古い結果が再表示しないよう世代を管理する。

グラフはテーマの色を使ったSVGで、外部ライブラリ/CDN不要。

実行履歴とログ

logs パネルにジョブと実行ログを統合。既定は終了状態 (succeeded/skipped/failed/cancelled)、待機・個別状態のフィルタも用意する。 GET /_/api/v1/queue/jobs?status=history&limit=50&cursor=... のkeysetページングで 50件ずつ置換し、DOMへ無制限に追記しない。順序は投入時刻降順+UUID降順。 完了状態用partial indexを指定し、SQLiteが状態別索引のIN検索後に保持履歴全体を 一時ソートする計画を避ける。ジョブpayloadは一覧SQLでも応答でも読み出さない。 新しいジョブへは更新ボタンで戻る。cursorは位置を表すのみで認可は毎要求再検査する。 ログはジョブの展開時だけ /_/api/v1/event/logs?job_uuid=...&limit=100 で取得。 以前のログは before_id で100件ずつ置換する。内容はHTMLではなくテキストとして表示。 実行中のキャンセル、失敗等の再試行を維持する。終了した実行中行は次回更新で消える。 実行状態は秒数・試行数を示すが、ジョブ別のCPU/RSS計測や進捗率を捏造しない。

指標 意味
CPU ホストの1分ロードアベレージ。CPU使用率ではない
メモリ このGoプロセスのheap bytes
I/O PagesWikiプロセスの読み込み・書き込み速度(B/s)。2系列で表示
キュー負荷 待機ジョブ数+実行ワーカー数

これらはドメイン別ではなくインスタンス/ホスト単位の指標。 ディスク容量は現在値カードに残し、グラフの1枠はI/Oに使う。I/Oの計測範囲と制約は システム拡張の監視仕様を参照。 コンテナCPU制限・RSS・cgroup使用率・複数インスタンス・長期保管は将来の 監視プロバイダ拡張として別API/保持方針を設計する。

アダプタ個別パネルの拡張契約

現行プラグインは adapter-<id> に個別パネルを持ち、共通partialで接続先・ 対応MIME/拡張子、有効化、別タブ、既定エディタ、HTML/Markdown変換を編集できる。 旧 /-/sys/config/adapters?id=... のGETは統合パネルへリダイレクトする。 保存も同じパネルに戻り、ドメイン別の既存プラグイン設定へ保存する。

将来のアダプタ固有項目は次の契約で追加する。

  1. サーバーが信頼するmanifestに settings_schema_version と複数のパネル定義を登録。 定義は id, title_key, group, fields とし、フィールドはboolean、text、 enum、number、secretの許可リストから選ぶ。現行partialがその最初の実装。
  2. 保存先は (domain_uuid, adapter_id, schema_version) で区切る。バリデーションと schema移行はサーバー所有。未定義キーは拒否し、秘密値は読み出しレスポンスに含めない。
  3. 特殊UIが必要な場合のみ、サーバー登録済みの専用partial/モジュールを使う。 プラグインやドキュメントから任意HTML/JavaScriptを設定画面に挿入しない。
  4. 外部設定画面の埋め込みが必要な場合は、別途sandbox iframeと固定originの postMessage契約を設計する。通常ログインCookie/Bearerをiframeへ渡さない。
  5. アダプタ固有の接続確認・秘密管理・長い検証処理は個別APIとイベントへ分離。

汎用schema rendererと外部設定iframeは未実装。今回の共通シェル・レジストリ・ アダプタpartialを拡張点として使用する。

検証

  • 管理者のAsset GETが成功し、一般ユーザーのGETが拒否されるHTTP回帰テスト。
  • 参照数のドメイン分離、旧HEAD参照、同一バイト列のメタデータ訂正。
  • ブックマーク保存/不正URL拒否、アダプタ個別設定の保存と戻り先。
  • 設定HTMLの重複ID、メニューの未定義パネル、inline JavaScriptの構文検証。
  • Chromiumでassets/events/queue/resources/bookmarks/adapter個別パネルを確認。 PAGESWIKI_BROWSER_TEST=1 go test ./internal/server -run TestConfigChromiumSmoke
  • CLI: python3 -m unittest discover -s data -p test_cli_assets.py。