常見問題

支援的作業系統

OS	最低版本	架構	備註
macOS	12 (Monterey)+	x64、ARM64 (Apple Silicon)	完整支援含 Guard
Ubuntu	20.04 LTS+	x64、ARM64	推薦的 Linux 發行版
Debian	11 (Bullseye)+	x64、ARM64	完整支援
CentOS / RHEL	8+	x64	SELinux 相容
Windows	10 (build 1903)+	x64	Guard 需要管理員權限

系統需求

Node.js

需要 Node.js >= 20。Panguard 用了 top-level await、native fetch 這些現代 JavaScript 功能，要 Node.js 20 以上才跑得動。看你裝的版本：

node --version

用 nvm 裝或升級：

nvm install 20
nvm use 20

或用套件管理器：

# macOS
brew install node@20

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows (winget)
winget install OpenJS.NodeJS.LTS

Root / 管理員權限

不同模組的權限需求不同：

模組	要 Root/Admin	原因
`panguard scan`	不用	用使用者權限讀檔案
`panguard guard`	要	要讀系統 log、管防火牆規則
`panguard report`	不用	從已有資料產生報告

需要提權的模組用 sudo 跑：

sudo panguard guard start

磁碟空間

元件	大概大小
Panguard CLI + 核心	約 50 MB
ATR 規則（768 條）	約 10 MB
Threat Cloud 資料庫（自架）	100 MB — 10 GB（看資料量）
Guard log + 資料	會一直長，建議至少 1 GB

網路

Panguard 需要對外 HTTPS 連線：

目的地	用途
`tc.panguard.ai`	Threat Cloud 情報 feed
`registry.npmjs.org`	套件安裝跟更新
`api.anthropic.com`	AI 分析（如果用 Anthropic）
`api.openai.com`	AI 分析（如果用 OpenAI）
`localhost:11434`	Ollama 本機 AI（如果有設定）

所有連線都可以透過 HTTPS_PROXY 環境變數走 HTTP proxy。

怎麼更新

把 Panguard 更新到最新版：

npm update -g panguard

npx panguard@latest doctor

panguard --version

更新後記得重啟跑著的服務：

# 重啟 Guard
sudo panguard guard stop
sudo panguard guard start

Panguard 會自動檢查更新，有新版時在 CLI 顯示提醒。ATR 偵測規則獨立於 CLI 更新。

怎麼解除安裝

要從系統徹底移除 Panguard：

macOS / Linux
Windows

# 1. 停掉所有服務
sudo panguard guard stop

# 2. 移除系統服務（如果有裝）
sudo panguard guard uninstall-service

# 3. 移除 npm 套件
npm uninstall -g panguard

# 4. 刪掉資料目錄
rm -rf ~/.panguard
rm -rf ~/.panguard-guard

# 5. 刪掉憑證
rm -f ~/.panguard/credentials.json

# 6. 移除 Guard 加的防火牆規則
# macOS:
sudo pfctl -F all
# Linux:
sudo iptables -F PANGUARD 2>/dev/null
sudo iptables -X PANGUARD 2>/dev/null

# 1. 停掉所有服務
panguard guard stop

# 2. 移除 Windows 服務（如果有裝）
panguard guard uninstall-service

# 3. 移除 npm 套件
npm uninstall -g panguard

# 4. 刪掉資料目錄
Remove-Item -Recurse -Force "$HOME\.panguard"
Remove-Item -Recurse -Force "$HOME\.panguard-guard"

# 5. 移除防火牆規則
Remove-NetFirewallRule -DisplayName "Panguard*"

解除安裝會刪掉所有本機資料，包含掃描歷史、威脅 log 跟 config。需要歷史紀錄的話，先跑 panguard report generate 匯出。

常見錯誤訊息

Error: Node.js version 20 or later is required

你的 Node.js 版本太舊。升級到 Node.js 20+： bash nvm install 20 && nvm use 20

Error: EACCES permission denied

你跑需要提權的模組但沒用 root： bash sudo panguard guard start 不想用 root 的話，看系統服務指南。

Error: Cannot find module 'panguard'

Panguard 沒裝成全域，或你的 PATH 沒包含 npm global bin 目錄： bash npm install -g panguard # 或檢查 PATH： npm config get prefix

Error: ECONNREFUSED

目標服務沒跑或連不到。檢查： - 服務有啟動嗎？（panguard status） - Port 對嗎？（看環境變數） - 防火牆有沒有擋？

開始使用

核心概念

操作指南

設定

疑難排解

支援的作業系統

系統需求

怎麼更新

怎麼解除安裝

常見錯誤訊息

​支援的作業系統

​系統需求

​怎麼更新

​怎麼解除安裝

​常見錯誤訊息

支援的作業系統

系統需求

怎麼更新

怎麼解除安裝

常見錯誤訊息