---
site: "zyx.tw"
title: "我把網路設定放進 Git，先改檔案再動設備"
description: "以檔案記錄預期狀態，合併後套用規則，持續比對設備差異。"
url: "https://www.zyx.tw/map/machines/network-in-git"
---

# 我把網路設定放進 Git，先改檔案再動設備

紀錄 021，經驗 L2，821 字，2 分鐘，v2.0.0，更新 2026-11-16

我的網路設定放在 Git 倉庫，透過 Git 保存檔案與修改紀錄。檔案登記網段、設備與存取規則，也就是誰能連到什麼。Claude Code 連線前先讀這些資料，查明連線方式。

我的做法是：先改檔案，再動設備，讓檔案成為網路設定的依據。 存取規則只開放指定服務，不直接開放整個網路。

## 合併前檢查規則，合併後才套用

我用 Tailscale 的 MCP 工具讀取或檢查狀態。MCP 是把服務操作提供給 agent 使用的開放標準。修改存取規則則先改檔案，再送出 pull request，也就是修改合併前的檢查關卡。

pull request 階段會自動執行存取規則測試，此時網路設定尚未改變。合併後才把規則套用到網路，並把網段表交給維運服務，也就是定期檢查實際狀態的程式，用來比對差異。

這裡套用的是存取規則，設備仍需另外操作。我把新增設備的步驟，以及 agent 可做與不可做的事寫進倉庫說明，要求 agent 操作前先讀。

下圖區分檢查、套用與只改後台的結果，呈現修改放在哪裡會如何影響實際網路。

**修改放在哪裡 pull request 裡**

檢查階段:
- 自動執行存取規則測試
- 尚未套用到網路

先測試存取規則，網路設定尚未改變。

**修改放在哪裡 合併之後**

套用階段:
- 把存取規則套用到網路
- 把網段表交給維運服務比對

網段表用於比對狀態。設備仍需另外操作。

**修改放在哪裡 只在後台修改**

設定不一致:
- 後續合併會覆蓋後台的修改
- 維運服務比對差異並發出通知

後台的修改沒有寫進檔案。後續套用會覆蓋這些修改。

## 檔案寫結果，程式持續比對

這個做法靠宣告式設定成立：檔案只寫想要的狀態，達成結果的步驟由程式決定。因此，網段表不是一串設備操作指令。

程式定期讀取檔案並觀察設備，發現差異時修正實際狀態，或發出通知。

```
while True:
    want = read(git, "main")        # desired state
    have = observe(devices)         # actual state
    for change in diff(want, have):
        if AUTO_APPLY:
            apply(change)           # must be idempotent
        else:
            notify(change)          # drift report
    sleep(INTERVAL)
```

AUTO\_APPLY 分支決定如何處理差異：啟用時執行 apply(change)，否則執行 notify(change)，只發出通知。

要讓這個迴圈安全重複執行，修改必須具備冪等性，也就是重複套用同一個修改，結果仍與只套用一次相同。

下圖逐步呈現這段迴圈，從讀取預期狀態、觀察設備，到處理差異後等待下一輪。

```text
while True:
    want = read(git, "main")        # desired state
    have = observe(devices)         # actual state
    for change in diff(want, have):
        if AUTO_APPLY:
            apply(change)           # must be idempotent
        else:
            notify(change)          # drift report
    sleep(INTERVAL)
```

Figure: Pseudo code of a reconciliation loop: read the desired state from Git, observe the actual state, and for each difference either apply it or report it, then wait and repeat.

1. Want: 想要的狀態來自 Git 的主分支。
2. Have: 實際狀態直接向設備查詢。
3. Diff: 兩者的差異，就是需要處理的項目。
4. Apply: 自動套用差異，讓實際狀態回到檔案寫的樣子。
5. Notify: 不自動套用時，只回報差異，由人決定。

## 自動套用也會套用錯誤

實際狀態與檔案不同稱為飄移；只在後台修改的設定，會被後續套用覆蓋。

自動修正雖然省事，寫錯的檔案也會被套用。因此，風險高的設備先只通知，確認後再套用。

## 先有登記資料，再決定是否自動套用

如果還沒有網段與設備清單，可以請 Claude Code 盤點，將結果寫成檔案放進倉庫。有了登記資料，再加入自動套用。

## 來源

- [OpenGitOps principles](https://opengitops.dev/), OpenGitOps
- [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/), Kubernetes docs

## 地圖

- 相關：[私有網路由協調伺服器管金鑰與規則，資料在機器之間傳送](https://www.zyx.tw/map/machines/private-network.md)
- 相關：[我用環境目錄把設備名稱接到用途、連線與詳細筆記](https://www.zyx.tw/map/machines/what-runs-where.md)
- 回到：[機房](https://www.zyx.tw/map.md)
