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

176 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](https://github.com/HeyPuter/firefox-wasm/releases/tag/v0.0.1)を使います。
対応commitは`eadcb5fa828d7e8b54ae2df13b6b3208f6553944`です。
配布物`gecko.js-v0.0.1.tar.gz`のSHA-256:
```text
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宣言、第三者依存物、今回の配布範囲は[再配布条件](gecko-redistribution.md)を参照してください。
v0.13.0の本番配備ではエンジンを配信していません。新しいrelayは完成したbundleを必須とします。
### bundle生成
Python 3.11以降を使い、十分な空き容量のあるディスク上で実行します。ソースarchiveは展開せず保持します。
```sh
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を再起動します。
設定確認・試験起動の例:
```sh
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は再起動でリセットします。
```sh
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`で次を実行します。
```text
extension viewer.gecko off
```
既存WebSocketは次の認証再検査時に終了します。新たな閲覧も拒否し、RSSの原文リンクは新規タブへ戻ります。
緊急時はrelayコンテナを停止します。DB移行の巻き戻しは不要です。
## 受入と制約
自動テストでは外部アクセスしない合成Wisp応答を使い、実際のGecko WASMで描画、canvasクリックによる遷移、
ビューア内の「戻る」、iframe削除後の接続終了を確認します。実FreshRSS、外部カレンダー、メール本文は使いません。
専用イメージのbuildと、`--network none`・非root・read-only・資源制限付きの一時コンテナで、
固定資産の起動時検査と`--status`も確認済みです。本番の中継・ネットワーク設定は変更していません。
```sh
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拒否とは別の仕組みですが、すべてのサイトでの動作や軽さを保証するものではありません。