Files
pages/docs/operations/gecko-relay.md
T
Anya Tokugawa b90aef79d0
Build and publish container images / images (push) Successful in 11m37s
Release container images / release (push) Successful in 22s
feat: add browser upload queue and trusted sessions with bounded projections
2026-11-08 20:27:04 +09:00

12 KiB
Raw Permalink Blame History

RSS Gecko中継の試験導入

RSS本文上で原文を読むための、端末側Gecko WASMと自前Wisp中継の実験機能です。 通常の新規タブ・iframe表示は変更しません。DBスキーマ変更はありません。 本番への自動導入・自動有効化は行いません。

構成と有効化条件

PagesWikiのログイン済み・activeな利用者だけが、 /_/api/v1/extension/organizer.feeds/browser/以下を使います。 同じDomainでorganizer.feedsとviewer.geckoの両方が有効で、 本体に中継URLと共有鍵ファイルが設定されていることが必要です。 viewer.geckoはmanifestで既定無効です。個人設定の「RSSの記事リンクの開き方」で Geckoを選ぶと、RSS画面だけにCOOP/COEPを追加します。選択済みでも管理者が無効化した場合は新規タブへ戻ります。

ブラウザには中継の鍵を渡しません。本体が認証後に30秒の署名付きgrantを発行して内部HTTP要求へ追加します。 WebSocketではOriginも検査し、grantは一回限りです。既存接続の認証・利用者状態・拡張の有効状態は5秒間隔で再検査します。 中継はCookie、WikiのBearer token、FreshRSSの資格情報を受け取りません。

固定するエンジン

HeyPuter/firefox-wasm v0.0.1を使います。 対応commitはeadcb5fa828d7e8b54ae2df13b6b3208f6553944です。

配布物gecko.js-v0.0.1.tar.gzのSHA-256:

bac28056a00ef6e5fb4345117e73d3629e75aca00dac71389fabbce39c018a73

エンジン単体のdist/ではなく、後述するsource/notice付きbundleをread-onlyで/geckoへmountします。 起動時に次の両ファイルに加え、manifestに列挙された全ソース・NOTICE・フォントをhash検査し、 欠損・改変・異なる版の混在があれば中継は起動しません。

ファイル SHA-256
gecko.js e5aeebffd21106eccf23b1219316221add5e95085bc5a1bfb941117cfcd75ef7
gecko.wasm.zst ebd6c75179152624d9644865e11792ed25cadc714d9e0985f412baf9c637a086

資産URLにもassets/v0.0.1/を含め、版をまたいだJS/WASMのcache混在を避けます。 初回にはJS・圧縮WASM・日本語フォントの合計54,643,095 bytes(約52.1MiB)の転送とWASMの展開・compileが必要です。 約1.2GBの対応ソースは閲覧の起動時には取得せず、ⓘから明示的にダウンロードするときだけ配信します。 本体のDocker buildにFirefoxのソースビルドを加えません。

Dockerfile.gecko-relayは自前の中継バイナリだけを含みます。エンジンは同梱・再配布しません。 エンジンをイメージへ同梱する場合だけでなく、mountした資産を利用者へ配信する前にもnoticeと対応sourceの提供が必要です。 固定版のMPL宣言、第三者依存物、今回の配布範囲は再配布条件を参照してください。 v0.13.0の本番配備ではエンジンを配信していません。新しいrelayは完成したbundleを必須とします。

bundle生成

Python 3.11以降を使い、十分な空き容量のあるディスク上で実行します。ソースarchiveは展開せず保持します。

python tools/gecko/bundle.py --cache /srv/gecko-cache --output /srv/gecko/v0.0.1-bundle1
# 同一入力からの再生成。出力先はまだ存在しない新しいディレクトリを指定する。
python tools/gecko/bundle.py --cache /srv/gecko-cache --output /srv/gecko/rebuilt --offline

出力manifestのSHA-256が84953114f5e393dd97d9f948a5bc51c95b9355b58461dd3355e068a96cb2e381と一致することを確認します。 稼働中のmount先を上書きせず、source/noticeの提供を含めて不変の単位で保全します。

配置

任意の追加ファイルdocker-compose.gecko.ymlを通常のCompose定義に重ねます。 このoverlayはappだけへ接続設定を追加し、app2は自動変更しません。

必要な環境変数:

変数 内容
PAGESWIKI_GECKO_KEY_PATH 32文字以上の十分ランダムな共有鍵のファイル絶対Path。appとrelayへ同じread-only mount
PAGESWIKI_GECKO_ASSETS_DIR 全ファイルを検証したbundleの絶対Path。engineだけのdistは禁止
PAGESWIKI_GECKO_IMAGE Giteaで配布したpageswiki-gecko-relay:sha-...またはrelease tag。省略時は開発用image
PAGESWIKI_GECKO_FRONT_SUBNET 内部接続網。既定172.24.0.0/27。既存LANとの重複を避ける
PAGESWIKI_GECKO_EGRESS_SUBNET 中継の外向き網。既定172.24.0.32/27

鍵はイメージ、Git、コマンド引数、ログへ含めません。relayはUID/GID 10001:10001で動きます。 mount元ファイルをこのUIDまたはGIDで読み取り可能にし、他の利用者から読めない権限にしてください。 本体のPAGESWIKI_GECKO_RELAYは内部の固定URL、PAGESWIKI_GECKO_KEY_FILEはmount先です。 これらは初回参照時に読み込むため、変更・鍵ローテーション時は本体とrelayを再起動します。

設定確認・試験起動の例:

docker compose -f docker-compose.yml -f docker-compose.gecko.yml config --quiet
docker compose -f docker-compose.yml -f docker-compose.gecko.yml build gecko-relay
docker compose -f docker-compose.yml -f docker-compose.gecko.yml up -d gecko-relay app

本体も今回の実装を含むイメージに更新する必要があります。既存のregistry/deploy用overrideがある場合は それも指定し、意図せず旧イメージや開発ビルドを本番へ適用しないでください。

外向き通信の制限

relayは公開ポートを持たず、通常のWikiネットワークやDBデータをmountしません。 ただしDocker bridgeの分離だけでは外向き通信を制限できません。試験導入前にホストまたは外部firewallで、 relayのegressから管理網・社内網・metadata・Wiki/DBホストへの到達を拒否し、公開TCP 80/443と管理されたDNSだけを許可します。 rootless Dockerとrootful Dockerでは適用点が異なるため、ホスト固有のiptablesをこのoverlayから自動変更しません。

アプリケーション側でもIPv4/IPv6のprivate、loopback、link-local、特殊用途アドレスを拒否します。 名前解決で返された全アドレスを検証してから、そのIPを直接dialします。検証後の再名前解決はしません。 UDP、80/443以外のTCP、単一ラベルのホスト名は拒否します。 これはWisp v1フレームを用いた制限付きTCP profileであり、Wispの全機能互換サーバーではありません。

上限と監視

対象 上限
同時セッション Domain+本人ごとに1、サービス全体4
同時TCP stream セッションごと16
接続試行 セッションごと256
合計転送量 セッションごと送受信合計256MiB
帯域 セッションごと送受信合計2MiB/s、初期burst 2MiB
セッション期限 15分
WebSocket受信idle 90秒
宛先接続 名前解決込み8秒、個別dial 2秒
relayコンテナ 256MiB、0.5 CPU、64 PIDs、read-only、capabilitiesなし
閲覧プロファイル 日本語フォントを含むvolatileな32MiB・2,048 entries、端末のOPFSへ永続化しない
source/noticeダウンロード 全体2接続まで。ETag・Range対応。閲覧streamの枠とは分離

relayの稼働状態・接続数・送受信bytes・拒否数は、コンテナ内の次の操作でJSON取得できます。 鍵はファイルから読み、標準出力には含めません。counterは再起動でリセットします。

docker compose -f docker-compose.yml -f docker-compose.gecko.yml exec gecko-relay gecko-relay --status

/healthは内容なしの死活確認、/statusは署名付き内部要求だけに応答します。 CPU・メモリはコンテナ監視を使います。設定画面の資源グラフへの統合は未完了です。 記事URL、本文、プロファイル内容、資格情報はrelayログに記録しません。

無効化と切り戻し

管理画面の拡張一覧でviewer.geckoを無効化できます。UIが使えない場合は、対象Domainを選択した ローカルdata/pageswiki-cliで次を実行します。

extension viewer.gecko off

既存WebSocketは次の認証再検査時に終了します。新たな閲覧も拒否し、RSSの原文リンクは新規タブへ戻ります。 緊急時はrelayコンテナを停止します。DB移行の巻き戻しは不要です。

受入と制約

自動テストでは外部アクセスしない合成Wisp応答を使い、実際のGecko WASMで描画、canvasクリックによる遷移、 ビューア内の「戻る」、iframe削除後の接続終了を確認します。実FreshRSS、外部カレンダー、メール本文は使いません。 専用イメージのbuildと、--network none・非root・read-only・資源制限付きの一時コンテナで、 固定資産の起動時検査と--statusも確認済みです。本番の中継・ネットワーク設定は変更していません。

go test -race ./internal/geckorelay ./internal/server -run 'TestGrant|TestDestinations|TestRelay|TestAssets|TestFeedGeckoAuthorization|TestFeedGeckoWebsocket'
PAGESWIKI_BROWSER_TEST=1 PAGESWIKI_GECKO_TEST_ASSETS=/verified/bundle go test ./internal/server -run '^TestFeedGeckoChromium$' -count=1
PAGESWIKI_GECKO_TEST_BUNDLE=/verified/bundle go test ./internal/geckorelay -run TestDistribution
# 公開テストサイトへの実通信。実RSS・外部カレンダー・メールは使用しない。
PAGESWIKI_BROWSER_TEST=1 PAGESWIKI_GECKO_TEST_ASSETS=/verified/bundle PAGESWIKI_GECKO_PUBLIC_HTTPS_TEST=1 go test ./internal/server -run '^TestFeedGeckoChromium$' -count=1
node internal/server/testdata/feed-gecko-profile.mjs

原文クリック時にだけ起動し、閉じるとiframe・worker・接続を破棄します。タブを60秒非表示にした場合も閉じます。 再表示では静的資産のHTTP cacheを使えますが、エンジンは再起動します。 戻る/進むは最大64件のURLを再読み込みする方式です。上流の最小GREにはSessionStoreFunctionsがなく、 標準のhistory.back()が失敗するため、フォーム内容やスクロール位置を復元する履歴ではありません。 画面のcanvasは最大1920×1080、experimental WASM JITとGPUは無効です。

HTTPSの実描画と期限切れ証明書の拒否を確認しました。上流最小GREはエラーページの部品が不足するため、 about:neterror/about:certerrorを検知してcanvasを隠し、PagesWiki側で説明します。証明書の無視・例外追加は提供しません。 Noto CJKをメモリプロファイルのfontsに置き、エンジンを改変せず日本語描画も確認しています。

検索アイコンまたはCtrl/Cmd+Fからページ内検索できます。検索語は256文字まで、前後検索と一致なしの表示に対応し、合成記事で日本語検索を確認しています。起動失敗または120秒の起動上限到達時はiframeを破棄し、元記事を別タブで開く導線を残します。上流のdestroy呼出しだけではWASM資源の解放にならないため、親側のiframe破棄まで行います。TestFeedGeckoStartupFailureChromium はフォント取得失敗時の破棄と代替導線を検証します。

本番の標準機能に昇格する前に、Safari/iPhone SE、IME、コピー、実サイト互換性、 複数タブ・低メモリ端末の測定、コンテナ外向きfirewallを検証します。 外部ページのiframe拒否とは別の仕組みですが、すべてのサイトでの動作や軽さを保証するものではありません。