> ## 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.

# Guard 問題

> 排解 Panguard Guard 啟動、效能跟偵測的問題。

## Guard 已經在跑了

```
Error: Panguard Guard is already running (PID: 12345)
```

另一個 Guard 實例已經在跑。先停掉：

```bash theme={null}
# 停掉正在跑的
sudo panguard guard stop

# stop 失敗的話，手動殺
cat ~/.panguard-guard/guard.pid
sudo kill $(cat ~/.panguard-guard/guard.pid)
rm ~/.panguard-guard/guard.pid

# 重新啟動
sudo panguard guard start
```

<Warning>
  同一台機器不要跑多個 Guard 實例。它們會在 log 檔存取、防火牆規則、監控資源上打架。
</Warning>

如果 PID 檔指向一個已經不存在的 process（過期 PID）：

```bash theme={null}
# 確認 process 真的不在了
ps -p $(cat ~/.panguard-guard/guard.pid)

# 如果顯示 "no such process"，放心刪 PID 檔
rm ~/.panguard-guard/guard.pid
sudo panguard guard start
```

***

## 權限不夠

```
Error: EACCES: permission denied, open '/var/log/auth.log'
```

Guard 需要 root/admin 權限讀系統 log 跟管防火牆規則。

<Tabs>
  <Tab title="用 sudo 跑">
    ```bash theme={null}
    sudo panguard guard start
    ```
  </Tab>

  <Tab title="裝成系統服務">
    裝成帶適當權限的 systemd 服務：

    ```bash theme={null}
    sudo panguard guard install-service
    sudo systemctl start panguard-guard
    sudo systemctl enable panguard-guard
    ```

    看服務狀態：

    ```bash theme={null}
    sudo systemctl status panguard-guard
    ```
  </Tab>

  <Tab title="macOS launchd">
    ```bash theme={null}
    sudo panguard guard install-service
    sudo launchctl load /Library/LaunchDaemons/com.panguard.guard.plist
    ```
  </Tab>
</Tabs>

***

## 記憶體吃太多

Guard 記憶體用量超出預期的話：

<AccordionGroup>
  <Accordion title="看目前用量">
    ```bash theme={null}
    panguard status --verbose
    ```

    正常範圍：

    | 元件                | 一般記憶體用量         |
    | ----------------- | --------------- |
    | 核心 agent          | 50--100 MB      |
    | ATR 規則引擎（768 條規則） | 約 30 MB         |
    | AI 分析（本機）         | 100--500 MB     |
    | **合計**            | **170--620 MB** |
  </Accordion>

  <Accordion title="降低記憶體用量">
    1. **關掉用不到的監控** -- 把不需要的子系統監控關掉：
       ```bash theme={null}
       panguard config set monitoring.dockerEvents false
       panguard config set monitoring.kernelModules false
       ```

    2. **減少規則數** -- 停用不需要的規則類別：
       ```bash theme={null}
       panguard config set rules.excludeCategories '["informational", "test"]'
       ```

    3. **用雲端 AI 取代本機** -- 從 Ollama 切到雲端 AI provider，省掉本機模型佔的記憶體：
       ```bash theme={null}
       export ANTHROPIC_API_KEY=sk-ant-...
       # 有跑 Ollama 的話可以停掉
       ```

    4. **調 GC 設定** -- Node.js 記憶體最佳化：
       ```bash theme={null}
       export NODE_OPTIONS="--max-old-space-size=512"
       ```
  </Accordion>
</AccordionGroup>

***

## 誤報太多

Guard 對正常活動發了一堆警示的話：

<AccordionGroup>
  <Accordion title="延長學習期">
    預設學習期 7 天。如果你的工作負載比較複雜，拉長一點：

    ```bash theme={null}
    panguard config set learningDays 14
    ```

    重設學習資料重來：

    ```bash theme={null}
    sudo panguard guard stop
    panguard config set mode learning
    sudo panguard guard start
    ```
  </Accordion>

  <Accordion title="調偵測閾值">
    拉高特定威脅類型的門檻：

    ```bash theme={null}
    # 暴力破解要更多事件才觸發
    panguard config set response.minConfidence 0.90

    # 拉高 SSH 失敗閾值
    panguard config set rules.sshFailureThreshold 20
    ```
  </Accordion>

  <Accordion title="把已知安全的 IP 跟 process 加白名單">
    把信任的 IP 跟 process 加白名單：

    ```bash theme={null}
    # IP 白名單
    panguard config set response.whitelistedIps '["10.0.0.0/8", "192.168.1.100"]'

    # Process 白名單
    panguard config set response.whitelistedProcesses '["backup-agent", "monitoring-daemon"]'
    ```
  </Accordion>

  <Accordion title="關掉吵的規則">
    找出造成誤報的規則，關掉它：

    ```bash theme={null}
    # 看最近的低嚴重性警示跟規則 ID
    panguard guard logs --severity low --limit 20

    # 停用特定規則
    panguard config set rules.excludeIds '["ATR-2025-0099"]'
    ```
  </Accordion>
</AccordionGroup>

***

## 自動回應沒動作

Guard 偵測到威脅但沒自動處理的話：

<AccordionGroup>
  <Accordion title="看信心閾值">
    自動回應只在 AI 信心分數超過 `minConfidence` 時才觸發：

    ```bash theme={null}
    # 看目前閾值
    panguard config get response.minConfidence
    ```

    偵測到的都低於閾值的話，小心地降一點：

    ```bash theme={null}
    panguard config set response.minConfidence 0.80
    ```

    <Warning>
      `minConfidence` 設到 0.7 以下會大幅增加誤報風險（封到正常 IP 或殺到正常 process）。
    </Warning>
  </Accordion>

  <Accordion title="確認回應有開">
    ```bash theme={null}
    panguard config get response.enabled
    panguard config get response.autoBlock
    ```

    沒開的話打開：

    ```bash theme={null}
    panguard config set response.enabled true
    panguard config set response.autoBlock true
    ```
  </Accordion>

  <Accordion title="看運作模式">
    `learning` 跟 `detect` 模式不會執行自動回應：

    ```bash theme={null}
    panguard config get mode
    ```

    切到 `protect` 模式：

    ```bash theme={null}
    panguard config set mode protect
    sudo panguard guard restart
    ```
  </Accordion>

  <Accordion title="看有沒有開核准要求">
    如果 `requireApproval` 是開的，Guard 會發核准請求而不是直接動手：

    ```bash theme={null}
    panguard config get response.requireApproval
    # 是 true 的話看待處理的核准：
    panguard guard approvals
    ```
  </Accordion>
</AccordionGroup>

***

## Guard 啟動就掛

<AccordionGroup>
  <Accordion title="看 log">
    ```bash theme={null}
    cat ~/.panguard-guard/logs/guard.log | tail -50
    ```

    或用 CLI：

    ```bash theme={null}
    panguard guard logs --limit 50
    ```
  </Accordion>

  <Accordion title="跑診斷">
    ```bash theme={null}
    panguard doctor
    ```

    會檢查 Node.js 版本、權限、磁碟空間、port 可用性、config 格式。
  </Accordion>

  <Accordion title="重設 config">
    config 檔壞掉的話：

    ```bash theme={null}
    # 先備份
    cp ~/.panguard-guard/config.json ~/.panguard-guard/config.json.bak

    # 刪掉重來
    rm ~/.panguard-guard/config.json
    sudo panguard guard start
    ```
  </Accordion>
</AccordionGroup>