Ctrlk
HomepageSystem Status
For the complete documentation index, see llms.txt. This page is also available as Markdown.

サービスモードREST API

KeeperコマンダーサービスモードでREST APIを作成

Keeperコマンダーサービスモード

Keeperコマンダーのサービスモードモジュールを使うと、最小限の設定で安全なREST APIサーバーを立ち上げ、コマンダーのCLIコマンドをREST API経由で実行できます。セキュリティと構成の柔軟性を保ったまま運用でき、ローカルでの稼働に加え、必要に応じてNgrokまたはCloudflareトンネルを組み合わせ、ルーティング可能なアドレスを公開することもできます。

特徴

コア機能

  • APIサーバー: コマンダーCLIコマンドを実行するためのFlaskベースのREST APIサーバー

  • サービス管理: APIサービスのライフサイクル全体の管理

  • 構成管理: インタラクティブなセットアップと簡略化されたセットアップの両方に対応した柔軟な構成システム

  • セキュリティ制御: APIキー管理、アクセス制御、レート制限、IP許可/拒否などの包括的なセキュリティ機能

  • APIバージョン管理: 同期処理 (v1) と非同期処理 (v2) の両方に対応する2種類のAPIバージョン

  • リクエストキューシステム: 追跡とステータス監視を備えた高度な非同期リクエスト処理

  • 柔軟なホスティングオプション: オンプレミス、Dockerコンテナ、クラウドでの実行。統合されたNgrokまたはCloudflareトンネルエージェントに対応

サービスコマンド

コマンド
説明

service-create

カスタマイズ可能な設定でサービスを初期化および構成する

service-start

既存の構成でサービスを開始する

service-stop

実行中のサービスを正常に停止する

service-status

現在のサービスステータスを表示する

service-config-add

新しいAPI構成とコマンドアクセス設定を追加する

service-docker-setup

KSM構成を使用したDockerサービスモードの自動セットアップ

slack-app-setup

コマンダーサービスモードを使用したSlackアプリ連携の自動セットアップ

teams-app-setup

コマンダーサービスモードを使用したTeamsアプリ連携の自動セットアップ

slack-app-setup、teams-app-setup、service-docker-setup コマンドでは、認証情報がローカルの config.json に保存されている必要があります。

OSのキーチェーンに認証情報が保存されている状態では、これらのコマンドは動作しません。先に keeper shell --config-file でコマンダーを起動するか、login --config-file でログインしてから、コマンドを再実行してください。

エラーの例

セキュリティ機能

  • APIキー認証

  • 設定可能なトークンの有効期限 (分/時間/日)

  • API応答のオプションのAES-256 GCM暗号化

  • 提供された証明書 (.pem) を使用したTLS対応

  • 構成可能なルールによるレート制限

  • IP許可リスト (ホワイトリスト) とIP拒否リスト (ブラックリスト) の管理

  • リクエストの検証とポリシーの適用

  • 秘密鍵を使用したローカルサービス構成JSONまたはYAMLファイルの暗号化

セキュリティ

Keeperコマンダーサービスモード機能は、既存のコマンダーセッションをREST APIでラップするセルフホステッドミドルウェアです。この機能は、高速なリクエストとシンプルなHTTPSベースのAPIが求められる環境に適しています。

この機能を最も安全に使用するためには、以下のことをお勧めします。

  • コマンダーサービス専用のサービスアカウントを使用し、必要な権限と機能のみに範囲を限定してください。

  • また、コマンドのアクセス制御についても、ユースケースに応じて必要なコマンドのみに制限することを推奨します。

  • REST APIエンドポイントへのアクセスにIPホワイトリストを適用する。

  • コマンダーサービスを実行しているマシンへのアクセスを保護する。

  • 異なるコマンドや使用ケースごとに異なるAPIトークンを使用する。

使用法

基本設定

Keeperコマンダーをインストールしてからシェルへログインします。

プロンプトが表示されたら、Keeperの認証情報を使用してログインします。コマンダーサービスモードは通常サービスとして実行されるため、生体認証ログイン、または永続的なログインセッションの利用を推奨します。

生体認証ログイン

または、以下のコマンドを使用して永続的なログインセッションを作成します。

サービスモードの作成: 対話的設定の使用

対話形式のプロンプトを使ってサービスを作成・構成します。

以下の項目の設定を求められます。

  • ポート番号

  • Ngrok認証トークン (任意)

  • Cloudflareトンネルトークン (任意)

  • TLS証明書のパス (任意)

  • リクエストキューシステム (y/n)

  • セキュリティ設定 (任意)

  • 設定フォーマット (yaml/json) (未作成の場合)

  • 実行モード (フォアグラウンド/バックグラウンド)

  • コマンドアクセス制御

例: TLS証明書 (https) を使用してサービスモードを作成する

ストリームライン構成

1つのコマンドでサービスをすばやく構成できます (デフォルトはフォアグラウンドモードでHTTP)。

Ngrokを使用してすばやく構成する場合 (Ngrok認証トークンとNgrokサブドメインを指定)

Cloudflareを使用してすばやく構成する場合 (Cloudflare認証トークンとドメイン名を指定)

詳細オプションを使用して構成する場合

ストリームラインパラメータ

  • -p, --port: サービスのポート番号 (簡易構成を開始するために必須)

  • -c, --commands: 許可コマンドまたはエイリアスのカンマ区切りリスト (必須)

  • -ng, --ngrok: クラウド管理のURLアクセス用のNgrok認証トークン (任意)

  • -cd: Ngrokカスタムドメイン。サブドメイン部分のみ (任意)

  • -cf,--cloudflare: クラウド管理のURLアクセス用のCloudflareトンネルトークン (任意)

  • -cfd: Cloudflareカスタムドメイン (任意)

  • -crtf, --certfile: SSL証明書ファイルのパス。.crt、.pem、.key を指定可能 (任意)

  • -crtp, --certpassword: SSL証明書のパスワード (任意)

  • -q, --queue_enabled: リクエストキューシステムを有効化 (y/n) - デフォルト: y

  • -rm, --run_mode: サービスの実行モード (foreground/background) - デフォルト: foreground

  • -f, --fileformat: 構成ファイル形式 (json/yaml) - サービスはセットアップを促す前に、ローカルの構成ファイルとボルトで既存の構成形式を確認します。

  • -rl, --ratelimit: IPごと・エンドポイントごとのレート制限 (例: 10/minute、100/hour、1000/day) (任意)

  • -aip, --allowedip: IP許可リスト (任意) - デフォルト: 0.0.0.0/0,::/0

  • -dip: 拒否IPリスト (任意)

  • -ek, --encryption_key: AES-256応答暗号化用のBase64エンコード32バイト鍵 (任意)

  • -te, --token_expiration: APIキーの有効期限 (例: 30m、24h、7d) (任意)

  • -ur, --update-record <RECORD_UID>: 生成されたAPIキーとサービスURLを指定したボルトレコードに保存する - ログからAPIキーを隠すのに便利 (任意)

構成ファイル

初期設定後、コマンダーはボルトに「Commander Service Mode」というタイトルのレコードを作成します。このレコードには service_config という名前のYAML/JSONファイルが含まれます。

コマンダーサービスモードレコード

次回以降の起動では、パラメータなしの service-start コマンドが必要です。構成は、ローカルの暗号化された service_config ファイルから読み込まれます。

構成はボルトに安全に保存されていますが、サービスは起動時にローカルにキャッシュされた暗号化ファイルを使用します。ボルトからの再読み込みを強制するには、service-start を実行する前にローカルの構成ファイル (~/.keeper/service_config.json または .yaml) を削除してください。

例: ターミナルからフォアグラウンドで起動する

サービスはシステムのターミナルから起動できます。たとえば、以下のコマンドは /api/v1 をフォアグラウンドモードで実行します (/api/v2 ではキューモード (-q y) を有効化してください)。

Ctrl-Cでサービスを停止できます。サービスを作成したあとは、ターミナルからは次のように起動するだけでかまいません。

生体認証ログインまたは永続ログインが有効になっている場合、サービスの起動はシームレスに行われます。

サービス管理

サービスステータスを確認します。

追加の構成を追加します。

サービスを開始します。

サービスを停止します。

ヘルスチェック

コマンダーのサービスモードでは、サービスの稼働状態を確認するためのヘルスチェック用URLが用意されています。以下は、サービスがlocalhostのポート8080で稼働している場合の例です。

リクエスト

レスポンス

サポート

サポートや機能のリクエストについては、GitHubでIssueを開くか、以下までお問い合わせください。

以下の手順

前へ自動実行次へAPIの使用

最終更新