> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 常見問題

> 系統需求、支援平台、更新跟解除安裝 Panguard AI。

## 支援的作業系統

| 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 需要管理員權限 |

## 系統需求

<AccordionGroup>
  <Accordion title="Node.js">
    需要 **Node.js >= 20**。Panguard 用了 top-level await、native fetch 這些現代 JavaScript 功能，要 Node.js 20 以上才跑得動。

    看你裝的版本：

    ```bash theme={null}
    node --version
    ```

    用 [nvm](https://github.com/nvm-sh/nvm) 裝或升級：

    ```bash theme={null}
    nvm install 20
    nvm use 20
    ```

    或用套件管理器：

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Root / 管理員權限">
    不同模組的權限需求不同：

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

    需要提權的模組用 `sudo` 跑：

    ```bash theme={null}
    sudo panguard guard start
    ```
  </Accordion>

  <Accordion title="磁碟空間">
    | 元件                   | 大概大小                  |
    | -------------------- | --------------------- |
    | Panguard CLI + 核心    | 約 50 MB               |
    | ATR 規則（768 條）        | 約 10 MB               |
    | Threat Cloud 資料庫（自架） | 100 MB -- 10 GB（看資料量） |
    | Guard log + 資料       | 會一直長，建議至少 1 GB        |
  </Accordion>

  <Accordion title="網路">
    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。
  </Accordion>
</AccordionGroup>

## 怎麼更新

把 Panguard 更新到最新版：

<CodeGroup>
  ```bash npm（全域安裝） theme={null}
  npm update -g panguard
  ```

  ```bash npx（免安裝） theme={null}
  npx panguard@latest doctor
  ```

  ```bash 確認版本 theme={null}
  panguard --version
  ```
</CodeGroup>

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

```bash theme={null}
# 重啟 Guard
sudo panguard guard stop
sudo panguard guard start
```

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

## 怎麼解除安裝

要從系統徹底移除 Panguard：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={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*"
    ```
  </Tab>
</Tabs>

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

## 常見錯誤訊息

<AccordionGroup>
  <Accordion title="Error: Node.js version 20 or later is required">
    你的 Node.js 版本太舊。升級到 Node.js 20+： `bash nvm install 20 && nvm use 20 `
  </Accordion>

  <Accordion title="Error: EACCES permission denied">
    你跑需要提權的模組但沒用 root： `bash sudo panguard guard start ` 不想用 root
    的話，看[系統服務指南](/guides/system-service)。
  </Accordion>

  <Accordion title="Error: Cannot find module 'panguard'">
    Panguard 沒裝成全域，或你的 PATH 沒包含 npm global bin 目錄： `bash npm install -g panguard #
            或檢查 PATH： npm config get prefix `
  </Accordion>

  <Accordion title="Error: ECONNREFUSED">
    目標服務沒跑或連不到。檢查： - 服務有啟動嗎？（`panguard status`） - Port 對嗎？（看環境變數） -
    防火牆有沒有擋？
  </Accordion>
</AccordionGroup>