SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 已更新 2026-10-24

open-kritt VPS 自架與 Docker Compose 掃描設定

學會在 VPS 以 Docker Compose 自架 open-kritt、固定 release 版本,透過 SSH tunnel 連接 5173 UI,並在首次掃描前設定 provider 額度。

為什麼要在 VPS 上自架 open-kritt,而不是在筆記型電腦上

請在可銷毀並重建的伺服器上自架 open-kritt。此工具會在可丟棄的工作容器中以 root 執行分析代理程式,為每個代理程式提供可寫入的程式碼副本與直接的網際網路存取,並將主機的 Docker socket 掛載至其 engine service。若伺服器專門用於這項工作,這是合理的取捨。但若該機器同時存放 SSH keys,這樣做就不安全。

預設設定中的 4 項特性支持上述建議,而且這 4 項都來自專案自己的 README 與 compose file。

代理程式的權限本來就很高。 README 表示,啟用工具的代理程式會在可丟棄的工作容器中以 root 執行,使用可寫入的 repository 副本與直接的網際網路存取。因此,它們可以安裝工具、編譯目標、執行測試,以及建立概念驗證。掃描不是讀取檔案的 linter,而是由你主動要求執行的任意程式碼。網際網路存取具有雙面刃效果:代理程式在研究目標時擷取的任何內容,都是進入其 prompt 的不受信任文字;這與你 讓代理程式自行進行網頁搜尋時承受的風險相同。

engine 持有 Docker socket。 docker-compose.yml 會將主機的 Docker socket 掛載至 engine service,因為 engine 會為每個工作建立並啟動一個掃描容器。任何能存取該 socket 的程序,都可以啟動掛載主機檔案系統的容器。因此,執行 engine 的主機等同於已被 engine 取得 root 權限。

沒有登入畫面。 backend 未提供應用程式驗證機制。能存取該連接埠,就能存取你的掃描結果與 provider 額度。

你掃描的程式碼通常不是自己的。 將代理程式指向第三方 repository,代表會在你的機器上以 root 執行該 repository 的 build,且具備網路存取權限。

如果你讀過 為什麼 coding agent 應在可丟棄的 VM 中執行,就會知道這是相同的威脅模型,只是風險更高。請為 open-kritt 準備一台不執行其他服務的 VPS,並使用 獨立的最低權限使用者帳號操作該 VPS,而不是使用 root。

open-kritt 的實際功能

open-kritt(儲存庫為 Kritt-ai/open-kritt,採用 AGPL-3.0 授權)會將漏洞研究拆分成小型工作,讓多個 AI agents 平行執行這些工作,然後去除重複項目並排列結果。您可以將工作流程定義為一連串聚焦的提示,每個步驟都會接收前置步驟提供的結構化內容。掃描目標可以是遠端或本機 git 儲存庫。分析引擎可以使用 Codex 或 Claude Code。出現候選項目後,可選擇執行後置腳本,嘗試驗證候選項目或建立概念驗證。設計這類工作流程屬於一般的 agent 工作,而非安全性工作。因此,如果您還不熟悉提示、工具與內容傳遞,了解如何組成 agents 對結果的幫助會大於本指南中的任何設定。

最後取得的是依優先順序排列的候選項目清單。請將它視為分流佇列,而不是報告。

開始前的準備項目

  • 執行 Ubuntu 24.04、Debian 12 或 Rocky Linux 9 的 VPS。安裝文件列出這些經過測試的發行版,支援 x86_64 與 ARM64。
  • Docker Engine 與 Compose plugin。
  • 主機上的 Node.js 20 或更新版本,因為 ./kritt CLI 在主機上執行,而不是在容器內執行。
  • 一個模型提供者:Codex login,或 OPENAI_API_KEY、CODEX_API_KEY、ANTHROPIC_API_KEY 或 OPENROUTER_API_KEY。
  • 只有在計畫掃描私有 repository 時才需要 GITHUB_TOKEN。隨附的 .env.example 已明確說明:僅使用 GitHub token 無法執行掃描。

先安裝 Docker 與 Node 20

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

登出後重新登入,讓新的群組成員資格生效,然後確認 Compose 外掛程式已存在。

docker compose version

如果顯示版本字串,表示 Compose 已安裝為外掛程式。docker: 'compose' is not a docker command 表示改用舊的獨立 docker-compose 二進位檔,而 open-kritt 會呼叫 docker compose。加入 docker 群組等同於取得主機的 root 權限,因此只能將執行 open-kritt 的帳號加入該群組。如需較完整的設定說明,請參閱 在 VPS 上執行 Docker。

Ubuntu 24.04 在自己的套件庫中提供 Node 18,而 CLI 在低於 20 的版本上會結束執行。Node 20 本身也已達生命週期終點,不再接收更新,因此請從 NodeSource 安裝 Node 22。它同樣符合 20 以上的版本檢查。

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -v

這裡 node -v 必須輸出 v22.,低於 v20. 的任何版本都會被 CLI 拒絕。在 Rocky Linux 9 上,對應的作法是先執行 sudo dnf module enable nodejs:22 -y,再執行 sudo dnf install -y nodejs。

複製 open-kritt 並鎖定標記版本

git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt
git fetch --tags
git tag --list
git checkout v1.4.1

main會隨著你的操作變動,標記則不會。截至 12 October 2026,最新標記為 v1.4.1,發布於 16 August 2026;git tag --list則會顯示複製當天可用的內容。v1.4.0(12 August 2026)加入下方 sizing 一節所述的記憶體感知 runner 核准機制;v1.4.1 修正 ranker 忽略使用者提供的排名規則的錯誤。簽出標記後,儲存庫會處於 detached HEAD 狀態,這在此處是正確的:你是將此複本作為鎖定版本的部署,而不是要提交變更的分支。之後若要升級,請先閱讀發布說明,再執行 git fetch --tags、簽出新的標記,最後再次執行 ./kritt start,因為 start會重新建置映像。

請勿搭配 sudo 執行 ./kritt。文件對此有明確說明。CLI 會管理 .data/ 下、屬於專案的憑證目錄;以 root 執行會讓這些目錄的擁有者變成 root,導致下一次以一般使用者執行時無法寫入。

使用 ./kritt setup 設定模型存取權

./kritt setup

此命令會在 .env.example 不存在時,從 .env.example 建立 .env,顯示每組認證的狀態,並讓您設定或取消設定認證。它不會將認證值回印到終端機。.env 與引擎認證檔案的檔案模式都會設為 0600。

如果您希望手動處理:

cp .env.example .env
chmod 600 .env
mkdir -p .data/codex
chmod 700 .data/codex

接著將 provider key 編輯至 .env,並將檔案維持為 0600。無論採用哪種方式,該伺服器現在都存放著可用的 provider 認證,因此更應避免在這台主機上存放其他內容。請只為此專案建立一組 key,日後撤銷時就不會影響其他重要項目。避免讓 AI agents 接觸 secrets 說明了更廣泛的做法。

第一次掃描前設定供應商支出上限

open-kritt 的設計會同時分派多個工作,而這些分派工作會產生成本。v1.4.1 中 .env.example 的預設值相對保守:ENGINE_WORKER_COUNT=2,檔案將其描述為適用於小型 2-vCPU 機器的保守預設值,以及 ENGINE_MAX_CONCURRENT_SCANS=1。更上層的是 ENGINE_WORKERS_PER_ACCOUNT=15,也就是單一供應商帳戶允許同時執行的 root model 呼叫上限;另有 ENGINE_CODEX_MAX_SUBAGENTS_PER_SESSION=5,因為 Codex 工作階段最多可執行 5 個子代理程式。在較大的 VPS 上提高 worker 數量後,同時進行的 model 呼叫數也會隨之增加。

儲存庫中沒有任何設定會限制支出。.env.example 中沒有預算設定。引擎本身的停止條件只有這些 worker 限制,以及 ENGINE_HARNESS_TIMEOUT_SECONDS;該值預設為每次 harness 執行 7200 秒。這裡的 harness 是一個持續使用工具和內容呼叫 model 的迴圈,直到某個條件結束執行。因此,該逾時值限制的是 包裝 model 的程式所經過的實際時間,而不是 model 在其中產生的支出上限。因此,上限必須設定在供應商端。請開啟供應商主控台,在第一次掃描前設定每月硬性上限,不要等到掃描後才設定。控制 AI 代理程式在 VPS 上的成本說明各供應商的設定方式。

本機也有一項停止機制。設定 ENGINE_WORKER_COUNT=0 後,系統會暫停接收新工作;stack 啟動後,也能在 Settings 畫面變更相同的 worker 值。

本指南不列出每次掃描的價格,因為成本取決於儲存庫大小、建立的工作流程,以及背後使用的 model。請先對一個小型儲存庫執行一次掃描,再查看供應商的用量頁面,之後才將它用於大型目標。

啟動 stack 並檢查其健康狀態

./kritt start

此命令會檢查 .env 和至少一組認證資料,然後執行 docker compose up --build。第一次建置需要較長時間,因為它會建置 frontend、backend、engine、executor view 和 database 映像檔。命令也會以前景模式執行,因此關閉 SSH 工作階段會停止 stack。請在 tmux 中啟動,或在第一次建置成功後以 detached 模式啟動。這兩種方式在重新開機後都不會自行恢復。因此,如果希望伺服器重新啟動後自動恢復 stack,讓 self-hosted agent 在重新開機後持續執行中的 systemd unit 模式可直接套用。

docker compose up -d --build
docker compose ps

docker compose ps 應列出 open-kritt-frontend、open-kritt-backend、open-kritt-engine、open-kritt-executor-view 和 open-kritt-db。接著在伺服器本機檢查 backend 是否有回應。

curl -s http://127.0.0.1:3002/api/health

收到 JSON 回應表示 backend 正常運作。Failed to connect to 127.0.0.1 port 3002: Connection refused 表示 backend 未正常運作,docker compose logs backend 會說明原因。請在 repository 目錄中使用 docker compose down 停止所有元件。

另一個可選步驟是:docker compose exec backend npm run seed 會載入示範資料。這是在投入任何資源執行實際掃描前,快速查看介面的簡便方式。

透過 SSH tunnel 存取 5173 埠上的 UI

compose 檔案中的每個服務預設都繫結至 127.0.0.1:frontend 使用 5173、backend 使用 3002、executor view 使用 8090,而 Postgres 使用 5432。不要修改這些繫結設定,改由自己的電腦透過 SSH 轉送連接埠。

ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip

在該指令執行期間,使用本機瀏覽器開啟 http://localhost:5173。-N 表示連線會建立轉送,但不會開啟 shell。若還需要 executor view,請在同一個指令中再加入一個 -L 8090:127.0.0.1:8090。

許多人會想設定 FRONTEND_BIND_ADDRESS=0.0.0.0,直接略過 tunnel。不要這樣做。backend 沒有登入畫面,因此任何能連到該頁面的使用者,都可以啟動掃描並消耗 provider credit。相較之下,Vaultwarden 的設計就是供網際網路存取,而 強化其安全性仍取決於 admin token 與備份檔案;這些控制手段是 open-kritt 所沒有的。底下還有另一個陷阱:published container port 會在 ufw 的預設政策套用前先行處理,因此 ufw deny 5173 規則看似正確,實際上卻不會封鎖任何流量。繞過 ufw 的 Docker 埠說明了造成這種結果的規則鏈。

VPS 規模

ENGINE_MIN_FREE_STORAGE_GB 預設為 20。可用儲存空間低於此值時,掃描引擎拒絕啟動新的單工作容器。建置映像、checkout 快取、Postgres 資料與工作區都位於同一個磁碟,因此 20 GB 的 VPS 完全無法啟動掃描。請將 40 GB 視為最低容量。若要掃描大型儲存庫,應配置更多空間。不要為了回收這台主機的成本,而在旁邊放置耗用大量儲存空間的服務。PhotoPrism 與 Immich 的這項比較顯示媒體庫會多快耗盡掃描所需的剩餘空間。對看似不會增加負擔的附加元件,也有相同問題:將 Jellyfin 媒體庫重新設計成 90 年代出租店的瀏覽器前端,仍會在其後方帶入完整的媒體伺服器與轉碼檔案,請將它放在其他主機。

記憶體需求可用簡單算式估算。相關設定自 v1.4.0 起提供,因此適用於上方固定的 tag,但不適用於更舊的 tag。ENGINE_MEMORY_RESERVE_GB=2 會為引擎、資料庫、API 與短暫的額外負載保留記憶體。每個掃描 runner 另外有 ENGINE_SCAN_RUNNER_MEMORY_RESERVATION_MB=1536 的軟性保留量與 ENGINE_SCAN_RUNNER_MEMORY_MB=1536 的硬性上限。因此,2 個 worker 在其他服務啟動前就需要約 5 GB。引擎只會啟動符合剩餘記憶體預算的 runner。小型主機上的掃描會因此排隊,而不是直接失敗。這比遭到 out-of-memory killer 終止的處理方式好得多。相同的計算方式也適用於讓每個工作單位使用獨立容器的工具。這就是為什麼OpenBot 為每位 AI coworker 使用 1 個容器和瀏覽器時,會遠早於受 CPU 限制而先遇到 RAM 上限。

2 個清理設定預設為 true:ENGINE_AUTO_PRUNE_DOCKER_BUILD_CACHE 與 ENGINE_AUTO_PRUNE_UNUSED_DOCKER_IMAGES。工作完成後,引擎會移除未使用的建置快取、未使用的映像與已停止的掃描容器。任何容器所參照的映像、服務容器、bind mount、資料庫資料、認證資料與 volume 都會保留。這也是不應共用主機的另一個理由:未由你設定的清理程序,可能會對該 Docker daemon 執行操作。

多數人最後會調整的引擎設定
  • ENGINE_WORKER_COUNT:由掃描步驟與後處理共用的 worker slot 總數。設為 0 可暫停接收新工作。
  • ENGINE_MAX_CONCURRENT_SCANS:同時允許的掃描數量。排隊中的掃描會等到使用中的 pool 清空後才執行。
  • ENGINE_MAX_WORKERS_PER_SCAN:設為 0 時,會在掃描之間平均分配總 slot 數。
  • ENGINE_HARNESS_TIMEOUT_SECONDS:預設為 7200。這是單一失控工作可持續的最長時間。引擎接受 60 至 86400;超出此範圍的值,包括 0,都會回復為 7200。
  • ENGINE_MIN_FREE_STORAGE_GB:儲存空間下限。ENGINE_IGNORE_LOW_STORAGE=true 會停用此防護機制,檔案也會警告這可能填滿主機磁碟。
  • ENGINE_SCAN_RUNNER_MEMORY_MB:每個 runner 的硬性記憶體上限。設為 0 可移除上限。
  • ENGINE_SCAN_RUNNER_MEMORY_RESERVATION_MB:每個 runner 的軟性保留量,准入判定會依此計算。降低此值會讓閒置記憶體超額配置,但硬性上限仍會限制突發用量。

掃描本機儲存庫而不外洩

LOCAL_REPOS_PATH 預設為 ./local_repos,並以唯讀方式繫結掛載至 backend 和 engine 容器。因此,您放入主機上該資料夾的儲存庫會立即出現在容器內。請使用全新的複製內容,不要使用工作目錄。工作容器會取得可寫入的副本,且容器內具有 root 權限和對外網際網路存取權。這表示該副本中的任何內容都可能遭到修改,或被傳送出主機。在複製專案之前,請先移除 .env 檔案和私密金鑰。

你會取得的結果,以及不會取得的結果

你會取得依排名排列的候選發現項目,但不會取得已驗證的漏洞。排名與去重功能會決定分流佇列的順序,但不能證明項目確實存在。後置腳本可以嘗試驗證並建立概念驗證,這是工具能提供的最強訊號;但後置腳本執行失敗,不代表該發現項目是錯誤的。仍須由人員逐一檢視每個候選項目。候選項目與證明之間存在落差,因此值得借用要求代理程式提供可由你自行重新執行的證據:可依需求重現的發現項目,比必須完全信任其結果的排名項目更有價值。

本指南不會聲稱 open-kritt 找出多少個真實錯誤,因為我們尚未進行測量。任何人若宣稱已針對你的程式碼庫測得偵測率,實際上都沒有在你的程式碼庫上執行測試。請先掃描一個你已經熟悉的程式碼庫:你能自行判斷的發現項目,是成本最低的校準方式。

在這裡,授權的重要性高於大多數自架工具。這些代理程式會編譯並執行程式碼,也會連線至網路,因此概念驗證步驟可能接觸線上系統。請將工具指向你擁有或受委託測試的程式碼,並在執行任何操作前,以文件記錄目標範圍。如果你設定 ANTHROPIC_API_KEY 並使用 Claude Code 引擎,在 VPS 上安全執行 Claude Code 中的沙箱使用習慣同樣適用於這些代理程式。

FAQ

為什麼 open-kritt 需要專用 VPS?

因為 open-kritt 的分析代理程式會在 root 身分下,於可丟棄的工作容器中執行。這些容器包含您程式碼的可寫入副本,並可直接存取網際網路。此外,引擎服務會掛載主機的 Docker socket,以便每項工作啟動一個容器。任何可存取該 socket 的程序,都能啟動掛載主機檔案系統的容器。因此,整個堆疊都應視為具備該主機的 root 權限。使用專用 VPS 時,這是可接受的取捨,且重建該主機不會造成損失。若在日常使用的工作站上執行,您的 SSH 金鑰與瀏覽器設定檔,就會和正在掃描的程式碼處於同一個信任邊界內。

可以公開連接埠 5173,而不使用 SSH tunnel 嗎?

不應這樣做。後端發布時未啟用應用程式驗證,因此該連接埠是網際網路與您的掃描結果及供應商額度之間唯一的防線。compose 檔案因此將每項服務繫結至 127.0.0.1。請執行 ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip,然後在本機瀏覽 http://localhost:5173。ufw 規則無法取代這項做法,因為已發布的 Docker 連接埠會在 ufw 的預設政策套用前先行處理。

如何避免 open-kritt 的支出超過預算?

請在第一次掃描前,先於模型供應商的管理主控台設定硬性上限,因為 open-kritt 本身沒有預算設定。前幾次執行請保留發布時的並行預設值 ENGINE_WORKER_COUNT=2 與 ENGINE_MAX_CONCURRENT_SCANS=1,並注意一個供應商帳戶預設最多允許 15 個並行的 root 模型呼叫,而 Codex 工作階段最多可執行 5 個子代理程式。ENGINE_WORKER_COUNT=0 會暫停接收新工作,是最快的本機停止方式。

應該簽出哪個版本?

應使用 tag,絕不要使用 main。git fetch --tags 搭配 git tag --list 可顯示可用版本;v1.4.1 於 16 August 2026 發布,截至 12 October 2026 是最新版本。固定版本後,數個月後重新建置仍會產生相同的堆疊。升級也會變成閱讀發布說明後再作出的決定,而不是因不同日期 clone 專案所產生的附帶結果。

掃描始終不會開始。應檢查什麼?

先檢查可用磁碟空間,因為可用儲存空間低於 ENGINE_MIN_FREE_STORAGE_GB 時,引擎不會啟動每項工作的掃描容器;該值預設為 20 GB。接著確認 ENGINE_WORKER_COUNT 不是 0,因為該值會暫停接收新工作。然後執行 ./kritt setup,確認確實已設定模型認證資訊,因為單獨使用 GITHUB_TOKEN 無法執行掃描。docker compose logs engine 會指出略過該工作的原因。

這篇文章對您有幫助嗎?