CUPS Web: CUPS にブラウザー印刷インターフェースを追加

hanxi/cups-web: READMEが定義する対象

CUPS Web は CUPS の上に構築されたウェブベースの印刷管理ツールです。リポジトリの説明では、家庭用 USB プリンターをいつでもアクセス可能なネットワーク印刷サービスに変えることを目的としており、README は家庭や小規模オフィスでの利用を想定しています。ユーザーはブラウザーからファイルをアップロードし、リモートで印刷ジョブを送信し、アプリは印刷の履歴を保存します。バックエンドは Go、フロントエンドは Vue 3 で、デフォルトブランチは master です。

hanxi/cups-web のREADMEと素材に記載された範囲を対象にします。 記載内容から確認できる事実と、READMEが説明していない事項を分けて読みます。スター数や説明文は利用の手掛かりにはなりますが、性能や長期運用を証明するものではありません。文書にない挙動は未確認として扱います。

hanxi/cups-web の第1章では、READMEに登場する固有のファイル名、コマンド、設定キー、対応形式を一つずつ拾います。小さな入力を用意して処理を実行し、成功時の出力だけでなく失敗時のログと終了状態も記録します。設定を変更したときは変更点を残し、同じ入力で結果がどう変わるかを比較します。これにより、機能の存在と自分の環境で使えることを混同しません。

hanxi/cups-web: 入力と出力の境界

README が挙げる対応形式は、PDF、画像（JPG、PNG、GIF、HEIC）、Office 文書（doc/docx/xls/xlsx/ppt/pptx）、OFD、プレーンテキストです。Office 文書は LibreOffice で PDF に変換され、OFD は ofdrw をベースにした組み込みの Java 変換器で変換され、テキストと画像はサーバー側で PDF にレンダリングされます。複数の画像を一度に選んで一つの PDF に結合できます。印刷オプションには部数、両面、カラー/モノクロ、用紙サイズ、用紙タイプ、向き、ページ範囲、拡大縮小、鏡像印刷があります。プレビューでは変換後の PDF、用紙方向の視覚的な確認、ページ数見積もりが表示されます。トラブルシューティングの節では Office と OFD の変換に 60 秒のタイムアウトがあり、複雑な文書は失敗しうると書かれています。

hanxi/cups-web の第2章では、READMEに登場する固有のファイル名、コマンド、設定キー、対応形式を一つずつ拾います。小さな入力を用意して処理を実行し、成功時の出力だけでなく失敗時のログと終了状態も記録します。設定を変更したときは変更点を残し、同じ入力で結果がどう変わるかを比較します。これにより、機能の存在と自分の環境で使えることを混同しません。

hanxi/cups-web: 構成要素から見える設計

Docker イメージには Debian のプリンタードライバーパッケージ一式が含まれています。printer-driver-all、printer-driver-cups-pdf、printer-driver-escpr、printer-driver-foo2zjs、printer-driver-brlaser、foomatic-db-compressed-ppds と openprinting-ppds の PPD ライブラリ、hplip に hpijs-ppds と hp-ppd、そして IPP Everywhere、AirPrint、Mopria のドライバーレス対応のための ipp-usb です。Canon UFR II、Canon CAPT、HP LaserJet 1020 ファームウェア、Epson ESC/P-R 2、Epson 中国版、Konica Minolta bizhub、Sharp PostScript、Gutenprint といったベンダードライバーは、管理者にだけ見えるウェブページか、docker exec で driver-install のようなコマンドを実行して、必要に応じてインストールします。README のアーキテクチャ列は実際の制約を示しています。ベンダーが現在の CPU アーキテクチャ向けのバイナリを提供していない場合、インストールボタンは無効になり理由が表示されます。インストールはバックグラウンドで非同期に実行され、ページの進捗カードは 2 秒ごとに更新されます。apt と dpkg がグローバルロックを持つため、ドライバータスクは同時に一つだけ実行できます。アップロードしたカスタム .ppd は .drivers ボリュームにスナップショットされ、コンテナ再構築後に復元されますが、.deb パッケージは記録されるだけで、再起動後に再アップロードが必要です。

hanxi/cups-web の第3章では、READMEに登場する固有のファイル名、コマンド、設定キー、対応形式を一つずつ拾います。小さな入力を用意して処理を実行し、成功時の出力だけでなく失敗時のログと終了状態も記録します。設定を変更したときは変更点を残し、同じ入力で結果がどう変わるかを比較します。これにより、機能の存在と自分の環境で使えることを混同しません。

hanxi/cups-web: 導入手順を追う

ユーザーシステムには admin と user の二つのロールがあります。初回起動時にアプリはデフォルトの admin/admin アカウントを作成し、README はこのアカウントを削除も名前変更もできないと明記しています。各印刷ジョブはファイル、ページ数、部数、両面とカラーの設定、ステータスを記録します。管理コンソールではユーザーの作成と編集、ユーザー名や期間による印刷記録の検索、そして時間ごとのチェックで期限切れの記録と対応ファイルを削除するデータ保持ポリシーの適用を行います。クイックスタートの節では、初回ログイン後にすぐデフォルトパスワードを変更するよう促しています。

hanxi/cups-web のREADMEにあるインストール手順、コマンド、設定ファイルを対象にします。 記載内容から確認できる事実と、READMEが説明していない事項を分けて読みます。スター数や説明文は利用の手掛かりにはなりますが、性能や長期運用を証明するものではありません。文書にない挙動は未確認として扱います。

hanxi/cups-web の第4章では、READMEに登場する固有のファイル名、コマンド、設定キー、対応形式を一つずつ拾います。小さな入力を用意して処理を実行し、成功時の出力だけでなく失敗時のログと終了状態も記録します。設定を変更したときは変更点を残し、同じ入力で結果がどう変わるかを比較します。これにより、機能の存在と自分の環境で使えることを混同しません。

hanxi/cups-web: 運用時に確認する条件

README は二つのデプロイ方法を説明しています。Docker Compose ファイルは CUPS とウェブサービスを同一コンテナで起動し、ポート 631 を CUPS に、ポート 1180 をホスト上のウェブ UI にマッピングし、四つのデータボリュームと USB デバイスツリーをマウントします。バイナリ単体にはウェブサービスのみが含まれます。README によると CUPS はホスト側で既にインストール・設定されている必要があり、ドライバー管理ページは動作しません。インストールスクリプトと /opt/cups-drivers ディレクトリがイメージ内にしか存在しないためです。プリンターの自動検出は cups-client パッケージの lpinfo に依存し、Office、OFD、PDF の正規化にはホスト上の LibreOffice、Java、Ghostscript が必要です。OFD 印刷がそのまま使えるのは Docker イメージだけで、バイナリデプロイでは Java ランタイムと /ofd-converter.jar に配置した ofd-converter.jar が必要です。

hanxi/cups-web のREADMEに記載された入力形式、出力、ログ、依存関係を確認対象にします。 記載内容から確認できる事実と、READMEが説明していない事項を分けて読みます。スター数や説明文は利用の手掛かりにはなりますが、性能や長期運用を証明するものではありません。文書にない挙動は未確認として扱います。

hanxi/cups-web の第5章では、READMEに登場する固有のファイル名、コマンド、設定キー、対応形式を一つずつ拾います。小さな入力を用意して処理を実行し、成功時の出力だけでなく失敗時のログと終了状態も記録します。設定を変更したときは変更点を残し、同じ入力で結果がどう変わるかを比較します。これにより、機能の存在と自分の環境で使えることを混同しません。

hanxi/cups-web: 採用前に見るべき制約

環境変数でウェブの待受アドレス（LISTEN_ADDR、デフォルト :8080）、SQLite データベースのパス（DB_PATH）、アップロードディレクトリ（UPLOAD_DIR）、CUPS のエンドポイント（CUPS_HOST）、CUPS 管理者のユーザー名とパスワード（CUPSADMIN と CUPSPASSWORD、どちらもデフォルトは print）、タイムゾーン（TZ、デフォルト Asia/Shanghai）を設定します。compose ファイルはウェブポートをホストの 1180 にマッピングし直します。四つのボリュームが永続データを保持します。.etc は CUPS 設定、.data は cups-web データベース、.uploads は元ファイルと変換後の PDF、.drivers は手動インストールしたドライバーのスナップショットです。バックアップの節ではデータベースをコピーし、他の三つのディレクトリを tar でまとめます。そして .drivers がサードパーティードライバーの唯一のコピーであり、スナップショットがアーキテクチャ固有であることに注意を促しています。amd64 でバックアップした .drivers を arm64 マシンに復元すると、別アーキテクチャ向けにインストールされたという警告が出ます。USB ホットプラグ対応は /dev/bus/usb をディレクトリとしてマウントし、メジャー番号 189 の device cgroup ルールを追加することに依存しており、device_cgroup_rules が使えない環境では privileged: true が代替として示されています。

hanxi/cups-web の第6章では、READMEに登場する固有のファイル名、コマンド、設定キー、対応形式を一つずつ拾います。小さな入力を用意して処理を実行し、成功時の出力だけでなく失敗時のログと終了状態も記録します。設定を変更したときは変更点を残し、同じ入力で結果がどう変わるかを比較します。これにより、機能の存在と自分の環境で使えることを混同しません。

編集部の結論

hanxi/cups-web が向くのは、READMEに示された対象と入力形式が自分の用途に一致し、固有の導入手順を実行できる人です。短いサンプルで hanxi/cups-web の出力、エラー、依存関係を確認し、対応していない環境や文書にない性能を前提にしないでください。採用を決める前に、READMEの具体的なコマンドと設定ファイルを使った検証結果を残す必要があります。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes