Linux へデプロイ（systemd / OpenRC）

このページは、一般的な Linux ホストを対象としています。インストーラーは amd64、arm64、armv7 に対応し、systemd を採用したディストリビューションと Alpine Linux の OpenRC 上で動作します。ホストでは root 権限が必要で、systemd または OpenRC が正常に起動していなければなりません。init システムを持たない軽量コンテナではホスト向けインストーラーを使えないため、Docker へのデプロイを選んでください。

インストーラーは必要に応じて curl、openssl、tar、unzip、gzip、ポート確認用ツールを導入します。Alpine では、実行に必要な Bash と依存パッケージも apk からインストールします。

Linux 版は 7991 で管理パネルを、7999 で Go ゲートウェイ入口を提供します。管理パネルへのアクセスは LAN、VPN、またはアクセス制御された HTTPS リバースプロキシ経由に限定し、インターネットへ直接ポートフォワーディングしないでください。

インストール

systemd ディストリビューション

ターミナルで次のコマンドを実行します。

curl -fsSL https://cdn.fnknock.cn/install.sh | sudo bash

Alpine Linux（OpenRC）

初回インストール時は Bash がまだ入っていない場合があるため、sh でインストーラーを起動します。

curl -fsSL https://cdn.fnknock.cn/install.sh | sudo sh

インストーラーは OpenRC が稼働中であることを確認し、fn-knock を default ランレベルへ登録してすぐに起動します。rc-service コマンドは存在していても /run/openrc がない場合、OpenRC で正常にブートしたホストではありません。その場合は、中途半端なサービス設定を残さずにインストールを中止します。

どちらのサービスマネージャーでも、インストーラーは最初に既存の fn-knock を検出します。

• 初回インストールでは、続行または終了を選べます。
• インストール済みの場合は、最新版の導入、管理メニュー、サービス状態の確認、アンインストールから選べます。
• リリースパッケージをダウンロードする前に、必要な TCP ポートを確認します。使用中のポートがある場合は、待ち受け情報を表示してポート設定メニューへ移動し、変更後にインストールを続行します。

インストール済みプログラムが見つからず、古い /etc/fn-knock/fn-knock.env だけが残っている場合は、「残存ポート設定」があることを明示し、既存設定の保持、変更、消去を選べます。「古いポート設定を消去」を選んでも、削除されるのはこの環境ファイルだけで、ポートがデフォルト値へ戻ります。/var/lib/fn-knock のデータやゲートウェイ設定は削除されません。

インストールが完了したら、ブラウザーで次の URL を開きます。

http://<サーバーアドレス>:7991/

画面の案内に従って管理パネルのパスワードを設定します。このパスワードは管理パネルだけを保護するもので、サービスへアクセスするときに使う TOTP、ユーザー名とパスワード、パスキーとは別の認証情報です。

デフォルトポート

7999 は、設定済みマッピングのサービストラフィックを受ける最も重要な Go ゲートウェイ入口です。Linux のポート設定メニューでは先頭に表示されます。

ポート	用途	デフォルトの待ち受け範囲
7999	Go ゲートウェイ入口	全インターフェース
7991	管理パネル	全インターフェース
7998	Rust 管理バックエンド	ローカルホストのみ
7997	認証サービス	ローカルホストのみ
7996	Go 管理インターフェース	ローカルホストのみ

初回インストール時も既存環境の更新時も、対応する番号を入力してポートを変更できます。番号が重複している場合や、すでに他のサービスが使用している場合は保存できません。

管理コマンド

インストール後は sudo knock で管理メニューを開けます。よく使う非対話コマンドは次のとおりです。

sudo knock status
sudo knock restart
sudo knock config
sudo knock update
sudo knock logs
sudo knock reset-panel-password

sudo knock status は、サービスの自動起動と稼働状態、外部向け待ち受けポート、server-admin-rs と go-reauth-proxy の 2 つの主要プロセスについて、PID、RSS メモリ、合計メモリを表示します。

コマンドは現在の環境に合うサービスマネージャーを自動で使います。systemd では systemctl、OpenRC では rc-service を使用します。どちらもサービス状態、外部向け待ち受け、主要プロセスのメモリを表示し、systemd ではさらにメイン PID、直近の終了コード、起動時刻も確認できます。

ログの確認には次のコマンドを使います。

sudo knock logs
sudo knock logs --follow

systemd では journalctl を読み、OpenRC では /var/log/fn-knock.log を表示または追尾します。ログファイルがまだ作成されていない場合、knock logs はサービス障害として扱わず、その旨を案内します。

sudo knock config は、番号付きのポート一覧を表示します。1～5 で対象ポートを変更し、S で検証して保存、R でデフォルトポートへ戻します。サービスの稼働中に現在の待ち受けポートを変更せず保存しても、誤って競合とは判定されません。

sudo knock reset-panel-password の実行には確認が必要です。管理パネルのパスワード、パネルへの全ログインセッション、ログイン失敗によるバックオフ記録が消去されます。次回、7991 の実際の管理 URL へアクセスすると、初回のパスワード設定画面が再び表示されます。

更新とロールバック

sudo knock update を実行すると、ローカルと配布元のバージョンが並んで表示されます。アップデーターは現在のアーキテクチャ用マニフェストを固定 URL から取得します。リリース処理がその URL の CDN キャッシュを更新して読み戻し検証を行うため、コマンドは確認のたびにランダムなクエリパラメーターを追加しません。

ローカルと配布元のバージョンが同じ場合でも、確認のうえ同じバージョンを再ダウンロードして再配置できます。新バージョンの起動後は管理パネルのヘルスチェックが行われます。起動に失敗した場合は、以前のバージョン、管理コマンド、対応する systemd ユニットまたは OpenRC サービススクリプト、サービスの起動・停止状態が復元されます。

以前のバージョンが残っている場合は、次のコマンドで戻せます。

sudo knock rollback

データとバックアップ

デフォルトインストールで使用する主なパスは次のとおりです。

パス	内容
/opt/fn-knock	バージョン別のプログラム、現行バージョンへのリンク、ロールバック用に保持したバージョン
/etc/fn-knock	ポートの環境ファイルとゲートウェイ設定
/var/lib/fn-knock	SQLite、証明書、秘密鍵、ダウンロード済みリソース、その他のアプリデータ
/var/log/fn-knock.log	OpenRC のサービスログ。systemd では journal を使用

更新や移行の前に、メンテナンス画面から .knock をエクスポートし、さらに /etc/fn-knock と /var/lib/fn-knock をバックアップします。アプリアーカイブは復元可能な設定の移行に使い、ディレクトリのバックアップは SQLite とプラットフォーム固有の実行データを保持するために使います。どちらか一方だけでは代用できません。対象範囲と復元手順の詳細はバックアップ・復元・データ消去を参照してください。

これらのディレクトリには認証情報や秘密鍵が含まれます。バックアップは暗号化し、root または実際の保守担当者だけが読める権限にしてください。ディレクトリ全体を通常のログ添付ファイルとしてアップロードしてはいけません。

リバースプロキシとセキュリティ境界

外部から管理する必要がある場合は、HTTPS リバースプロキシ経由の入口を優先してください。インストール後に次のコマンドを実行すると、Nginx の設定例を出力できます。

sudo knock nginx

リバースプロキシで TLS を有効にし、信頼できる送信元 IP、VPN のアドレス範囲、または追加認証でアクセスを制限します。Linux 版はホストのファイアウォールを変更しません。サービスに本当に必要なポートだけを開放してください。管理画面とサービス用ゲートウェイ入口の違いは、ポートと入口を参照してください。

既存の業務ドメインのサブパスに配置する

クラウドサーバー上の Nginx がすでに https://www.example.com を提供している場合は、別のドメインや公開ポートを追加せずに、fn-knock の管理パネルをサブパスに配置できます。次の例では /fn-knock/ を推奨値として使用していますが、既存のサービスが使っていない別のパスへ変更できます。www.example.com に対応する HTTPS の server {} ブロックへ設定を追加します。

# パスを変更する場合は、次の行の /fn-knock だけを変更する
location ~ ^(?<panel_prefix>/fn-knock)(?<panel_uri>/.*)?$ {
    if ($panel_uri = "") {
        return 308 $panel_prefix/$is_args$args;
    }

    include /etc/nginx/snippets/migrated-proxy-headers.conf;

    proxy_http_version 1.1;

    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Prefix $panel_prefix;

    proxy_redirect ~^(/.*)$ $panel_prefix$1;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;

    rewrite ^ $panel_uri break;
    proxy_pass http://127.0.0.1:7991;
}

この例では、管理パネルがデフォルトのポート 7991 を使用していることを前提としています。インストール時にポートを変更した場合は、proxy_pass も変更してください。/etc/nginx/snippets/migrated-proxy-headers.conf がすでに存在し、現在のサイトで共通利用するプロキシリクエストヘッダーを設定している必要もあります。既存サイトが別の共通プロキシ設定を使用している場合は、include のパスを実際のファイルへ変更してください。

Nginx の location では、set で定義した変数を直接参照できません。この例では代わりに正規表現の名前付きキャプチャを使用します。/fn-knock は一度だけ記述され、$panel_prefix に保存されるため、たとえば /knock-admin へ変更するときも location の行だけを編集します。$panel_uri はプレフィックスより後ろのリクエストパスを保持し、プロキシする前に外部プレフィックスを取り除くために使われます。同じ server に別の正規表現 location がある場合は、同じリクエストに一致する可能性があるルールより前にこのブロックを配置してください。

• 末尾のスラッシュがないプレフィックスは、元のクエリパラメーターを保持したまま、ステータス 308 で / 付きの URL へリダイレクトされます。
• rewrite は $panel_uri を使って、管理パネルへ転送する前に外部プレフィックスを取り除きます。X-Forwarded-Prefix は管理パネルに外部パスを伝え、proxy_redirect はアップストリームが返したルート相対のリダイレクトを同じプレフィックス配下へ書き換えます。
• X-Forwarded-Host と X-Forwarded-Port は、アクセスに使われた実際のドメインとポートを保持します。

設定を保存したら構文を確認し、ホストが使用するサービスマネージャーで Nginx をリロードします。

sudo nginx -t
sudo systemctl reload nginx

Alpine Linux では次を使用します。

sudo rc-service nginx reload

リロードに成功すると、この例では https://www.example.com/fn-knock/ から管理パネルへアクセスできます。推奨パスを変更した場合は、アクセス URL にも同じ新しいプレフィックスを使用します。末尾のスラッシュがない URL は自動的にリダイレクトされます。このパスがプロキシするのは 7991 の管理入口だけであり、7999 のサービス用ゲートウェイ入口を置き換えるものではありません。インターネットから到達できる場合は、送信元 IP の制限、VPN、または追加認証で引き続き保護してください。

アンインストール

sudo knock uninstall

通常のアンインストールでは、プログラムと現在のサービスマネージャーへの登録（systemd ユニットまたは OpenRC サービススクリプト）だけを削除し、/etc/fn-knock の設定と /var/lib/fn-knock のデータは残します。--purge を明示的に指定し、対話端末で DELETE と入力した場合に限り、設定とデータを完全に削除します。

次に読むページ：

• デプロイ方法とアクセス構成を選ぶ
• ポートと入口
• バックアップ・復元・データ消去
• ダッシュボードとシステム更新