# 探測器

註冊分散式網路觀測點、安裝 Linux agent、設定標籤與位置、輪替金鑰，以及判讀探測器狀態。

探測器代表一個在真實網路環境中執行的 Netstamp agent。請將探測器放在量測差異會影響問題判斷的位置，例如使用者網路、不同地區或網路供應商、辦公室、實驗室、叢集或邊緣節點。

## 支援平台

控制器提供的安裝程式目前支援：

- Linux amd64（`x86_64` 或 `amd64`）
- Linux arm64（`aarch64` 或 `arm64`）
- systemd 服務管理

安裝程式需要 root 權限、`curl` 或 `wget`，以及能連至控制器的對外 HTTP(S) 連線。執行檔會安裝至 `/usr/local/bin/netstamp-agent`。

## 建立並安裝探測器

1. 開啟「**探測器 → 新增探測器**」。
2. 輸入穩定且容易辨識的名稱。
3. 搜尋地點，或輸入緯度與經度。
4. 建立探測器。Netstamp 會回傳探測器 ID 及只顯示一次的金鑰。
5. 在目標主機執行產生的安裝程式與服務安裝指令。
6. 等待設定精靈收到已簽署的心跳訊號。

服務指令的格式如下：

```bash
sudo netstamp-agent service install \
  --url 'https://netstamp.example.com' \
  --probe-id '<probe UUID>' \
  --probe-secret '<one-time secret>'
```

服務管理程式會建立專用的系統使用者與群組、由 root 擁有的環境設定檔、資料目錄及 systemd unit。確切路徑與指令請參閱[探測器 agent 維運](/zh-TW/docs/guides/probe-operations/)。

## 位置

位置名稱、緯度與經度會用於地圖及公開狀態頁的位置檢視。這些資料不會限制探測器的執行範圍，也不會自動找出主機位置。請依預計公開的位置精細度，提供足夠準確的座標。

選擇搜尋模式時，建立精靈會使用地點搜尋服務。若不想進行這項外部查詢，可以改為手動輸入十進位座標。

## 標籤

你可以加入以下標籤：

```text
region=ap-east
provider=isp-a
environment=production
role=edge
```

檢查選擇器會根據探測器標籤進行比對。變更標籤後，控制器重新整理指派狀態時，實際生效的指派可能隨之增加或移除。

## 「已啟用」與「上線」不同

- **已啟用**：決定探測器是否能接收檢查指派。
- **上線**：表示控制器近期收到探測器在執行階段送出的心跳訊號。

探測器狀態可能包含上次回報時間、開始上線時間、持續上線時間、agent 版本、本機位址、公開 IPv4／IPv6 及自治系統資訊。已啟用但離線的探測器仍會保留設定，但不會產生量測結果。

## 輪替金鑰

如果金鑰可能外洩、主機已重建或管理權移交，請輪替探測器憑證：

1. 開啟探測器詳細資料。
2. 輪替金鑰。
3. 立即複製新金鑰。
4. 在主機上執行產生的服務安裝指令。
5. 重新啟動服務，並確認控制器收到新的心跳訊號。

輪替完成後，舊金鑰會立即失效。新金鑰的明文內容只會顯示一次，之後無法再次取得。

## 刪除或暫時停止探測器

若要停止新的檢查指派但保留歷史資料，請停用探測器。只有在專案不再需要保留這個探測器資源時才將它刪除。從主機解除安裝服務不會刪除控制器中的探測器；刪除控制器中的探測器，也不會移除主機上的軟體。