> ## 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 裝成 systemd、launchd 或 Windows 服務，開機自動跑、持續防護。

# 系統服務安裝

把 Guard 裝成系統服務，開機自動啟動、掛掉自動重啟，不需手動介入就能持續跑。

***

## 快速安裝

```bash theme={null}
# 裝成系統服務
panguard guard install

# 移除系統服務
panguard guard uninstall
```

`install` 指令會偵測你的 OS，自動建立對應的服務 config。

***

## 各平台說明

<Tabs>
  <Tab title="macOS (launchd)">
    Guard 建立一個 LaunchDaemon plist：

    ```
    /Library/LaunchDaemons/ai.panguard.guard.plist
    ```

    **裝好之後：**

    * 開機自動啟動
    * 異常退出自動重啟
    * 日誌寫到 `/var/log/panguard-guard.log`

    **手動管理：**

    ```bash theme={null}
    # 查服務狀態
    sudo launchctl list | grep panguard

    # 手動啟動
    sudo launchctl load /Library/LaunchDaemons/ai.panguard.guard.plist

    # 手動停止
    sudo launchctl unload /Library/LaunchDaemons/ai.panguard.guard.plist
    ```
  </Tab>

  <Tab title="Linux (systemd)">
    Guard 建立一個 systemd unit 檔：

    ```
    /etc/systemd/system/panguard-guard.service
    ```

    **Unit 檔範例：**

    ```ini theme={null}
    [Unit]
    Description=Panguard Guard Agent
    After=network-online.target
    Wants=network-online.target

    [Service]
    Type=simple
    User=panguard
    Group=panguard
    WorkingDirectory=/opt/panguard
    ExecStart=/usr/bin/node /opt/panguard/dist/cli/index.js guard --mode protection --data-dir /var/panguard-guard
    Restart=always
    RestartSec=10
    StandardOutput=journal
    StandardError=journal
    SyslogIdentifier=panguard-guard

    # 安全強化
    NoNewPrivileges=true
    ProtectSystem=strict
    ProtectHome=true
    ReadWritePaths=/var/panguard-guard
    PrivateTmp=true

    # 回應動作需要的 capabilities
    AmbientCapabilities=CAP_NET_ADMIN CAP_KILL CAP_SYS_PTRACE

    Environment=NODE_ENV=production
    Environment=PANGUARD_DATA_DIR=/var/panguard-guard
    EnvironmentFile=-/etc/panguard/guard.env

    [Install]
    WantedBy=multi-user.target
    ```

    **手動管理：**

    ```bash theme={null}
    # 查服務狀態
    systemctl status panguard-guard

    # 啟動 / 停止
    sudo systemctl start panguard-guard
    sudo systemctl stop panguard-guard

    # 看日誌
    journalctl -u panguard-guard -f
    ```

    **需要的 Linux capabilities：**

    | Capability       | 用途                    |
    | ---------------- | --------------------- |
    | `CAP_NET_ADMIN`  | 透過 iptables 封鎖 IP     |
    | `CAP_KILL`       | 砍掉惡意 process          |
    | `CAP_SYS_PTRACE` | 記憶體掃描偵測 fileless 惡意軟體 |
  </Tab>

  <Tab title="Windows (Services)">
    Guard 註冊為 Windows 服務：

    ```
    Service Name:    PanguardGuard
    Display Name:    Panguard Guard AI
    ```

    **裝好之後：**

    * 開機自動啟動
    * 異常退出自動重啟
    * 日誌寫到 Windows Event Log

    **手動管理：**

    ```powershell theme={null}
    # 查服務狀態
    sc.exe query PanguardGuard

    # 啟動 / 停止
    sc.exe start PanguardGuard
    sc.exe stop PanguardGuard
    ```
  </Tab>
</Tabs>

***

## 手動 systemd 設定（進階）

要完全掌控服務 config 的話，照以下步驟：

<Steps>
  <Step title="建立系統使用者">
    ```bash theme={null}
    sudo useradd --system --home-dir /opt/panguard --shell /usr/sbin/nologin panguard
    ```
  </Step>

  <Step title="建立目錄">
    ```bash theme={null}
    sudo mkdir -p /opt/panguard /var/panguard-guard /etc/panguard
    sudo chown -R panguard:panguard /opt/panguard /var/panguard-guard
    ```
  </Step>

  <Step title="部署應用程式">
    ```bash theme={null}
    sudo cp -r dist/ /opt/panguard/dist/
    sudo cp -r node_modules/ /opt/panguard/node_modules/
    ```
  </Step>

  <Step title="建立環境檔">
    ```bash theme={null}
    sudo tee /etc/panguard/guard.env << 'EOF'
    PANGUARD_DATA_DIR=/var/panguard-guard
    OLLAMA_ENDPOINT=http://localhost:11434
    EOF

    sudo chmod 600 /etc/panguard/guard.env
    sudo chown panguard:panguard /etc/panguard/guard.env
    ```

    <Warning>
      環境檔裡有密鑰。權限務必設 `600`，owner 限定為服務使用者。
    </Warning>
  </Step>

  <Step title="啟用並啟動">
    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable panguard-guard
    sudo systemctl start panguard-guard
    sudo systemctl status panguard-guard
    ```
  </Step>
</Steps>

***

## Manager 服務

Manager 也能裝成 systemd 服務，適合分散式部署：

```ini theme={null}
[Unit]
Description=Panguard Manager Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=panguard
Group=panguard
WorkingDirectory=/opt/panguard
ExecStart=/usr/bin/node /opt/panguard/dist/cli/index.js manager --port 8443
Restart=always
RestartSec=10

NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/panguard-manager
PrivateTmp=true

Environment=NODE_ENV=production
EnvironmentFile=-/etc/panguard/manager.env

[Install]
WantedBy=multi-user.target
```

***

## Watchdog 健康監控

系統服務內建 watchdog 機制：

* 每 60 秒檢查 Guard process 健康狀態
* 記憶體用量異常時重啟
* CPU 用量異常時降級
* 重啟次數超過門檻就停止並通知

***

## 批次部署腳本

產生一行安裝腳本，方便跨多台機器部署：

```bash theme={null}
panguard guard install-script
```

產生的腳本會：

1. 下載 Panguard AI
2. 安裝依賴
3. 裝成系統服務
4. 啟動 Guard

***

## 資料目錄

| 平台      | 預設路徑                        |
| ------- | --------------------------- |
| macOS   | `~/.panguard-guard/`        |
| Linux   | `~/.panguard-guard/`        |
| Windows | `%APPDATA%\panguard-guard\` |

用 `--data-dir` 覆蓋：

```bash theme={null}
panguard guard start --data-dir /opt/panguard/data
```

**目錄內容：**

* `guard.pid` -- PID 檔（防止跑多個實例）
* `baseline/` -- 行為基線資料
* `rules/` -- 自訂 ATR 規則
* `logs/` -- 事件日誌（JSONL，自動輪替）
* `config.json` -- Guard config

***

## PID 管理

Guard 用 PID 檔管理 process 狀態：

* 啟動時寫入 PID
* 正常關閉時移除 PID 檔
* 防止多個實例同時跑
* 支援 SIGTERM 和 SIGINT 優雅關閉

***

## 相關文件

<CardGroup cols={2}>
  <Card title="即時防護" icon="shield" href="/guides/real-time-protection">
    設定 Guard 做持續監控和回應。
  </Card>

  <Card title="Docker 部署" icon="docker" href="/guides/docker-deployment">
    用容器跑 Guard。
  </Card>

  <Card title="多端點部署" icon="server" href="/guides/multi-endpoint">
    把 Guard agent 連線到集中式 Manager。
  </Card>

  <Card title="環境變數" icon="sliders" href="/configuration/environment-variables">
    完整環境變數參考。
  </Card>
</CardGroup>