Pi Web 的這個教學只處理標題中的具體任務。 Pi Web 預設只監聽 127.0.0.1，而且沒有應用層認證；它能呼叫高權限 Agent，因此遠端存取首選 SSH 本地轉發，而不是直接綁定 0.0.0.0。
以下所有操作都先放在測試儲存庫、測試帳號或僅回環監聽的服務中。指令中的網域名稱、使用者名稱、路徑與金鑰是佔位符，執行前需要替換。
先理解 Pi Web 的無認證邊界
這一節解決的是「先理解 Pi Web 的無認證邊界」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。
對 Pi Web 而言，判斷依據是：Pi Web 預設只監聽 127.0.0.1，而且沒有應用層認證；它能呼叫高權限 Agent，因此遠端存取首選 SSH 本地轉發，而不是直接綁定 0.0.0.0。不要在這個階段順手打開更多權限。
|
|
執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。
Node.js 22.19 版本檢查
按下面順序處理：
- 讀取實際版本和目前配置。
- 只改變與本節相關的一項設定。
- 執行一個唯讀或可撤銷的請求。
- 檢查日誌、退出碼和最終檔案。
- 失敗時恢復剛才那一項修改。
|
|
這裡的完成標準不是介面出現，而是「Node.js 22.19 版本檢查」有可重複結果。
保持回環監聽啟動服務
| 要檢查的內容 | 合格表現 | 需要停止的信號 |
|---|---|---|
| 保持回環監聽啟動服務 | 輸入和輸出範圍明確 | 自動擴大到其他項目或帳號 |
| 權限 | 只獲得完成任務所需權限 | 要求管理員權限或完整金鑰 |
| 日誌 | 能定位失敗且已經脫敏 | 出現 Token、Cookie 或私有正文 |
| 回退 | 能恢復上一步狀態 | 修改不可逆且沒有備份 |
|
|
表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。
SSH 本機連接埠轉送的完整路徑
圍繞「SSH 本機連接埠轉送的完整路徑」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。
|
|
建議記錄以下四項：
- 執行前的版本或 Git 提交。
- 實際輸入，不記錄秘密值。
- 可觀察的輸出、狀態碼或 diff。
- 恢復動作以及恢復後的複查結果。
如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。
從客戶端確認連接埠只在本機開放
這一節解決的是「從客戶端確認連接埠只在本機開放」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。
對 Pi Web 而言，判斷依據是：Pi Web 預設只監聽 127.0.0.1，而且沒有應用層認證；它能呼叫高權限 Agent，因此遠端存取首選 SSH 本地轉發，而不是直接綁定 0.0.0.0。不要在這個階段順手打開更多權限。
|
|
執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。
多用戶伺服器如何隔離會話文件
按下面順序處理：
- 讀取實際版本和目前配置。
- 只改變與本節相關的一項設定。
- 執行一個唯讀或可撤銷的請求。
- 檢查日誌、退出碼和最終檔案。
- 失敗時恢復剛才那一項修改。
|
|
這裡的完成標準不是介面出現，而是「多用戶伺服器如何隔離會話檔案」有可重複結果。
為什麼不建議直接使用 0.0.0.0
| 要檢查的內容 | 合格表現 | 需要停止的信號 |
|---|---|---|
| 為什麼不建議直接使用 0.0.0.0 | 輸入和輸出範圍明確 | 自動擴大到其他項目或帳號 |
| 權限 | 只獲得完成任務所需權限 | 要求管理員權限或完整金鑰 |
| 日誌 | 能定位失敗且已經脫敏 | 出現 Token、Cookie 或私有正文 |
| 回退 | 能恢復上一步狀態 | 修改不可逆且沒有備份 |
|
|
表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。
必須反代時增加哪些保護
圍繞「必須反代時增加哪些保護」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。
|
|
建議記錄以下四項：
- 執行前的版本或 Git 提交。
- 實際輸入，不記錄秘密值。
- 可觀察的輸出、狀態碼或 diff。
- 恢復動作以及恢復後的複查結果。
如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。
代理環境變數如何傳給服務端請求
這一節解決的是「代理環境變數如何傳給服務端請求」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。
對 Pi Web 而言，判斷依據是：Pi Web 預設只監聽 127.0.0.1，而且沒有應用層認證；它能呼叫高權限 Agent，因此遠端存取首選 SSH 本地轉發，而不是直接綁定 0.0.0.0。不要在這個階段順手打開更多權限。
|
|
執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。
隧道斷開與頁面假在線
按下面順序處理：
- 讀取實際版本和目前配置。
- 只改變與本節相關的一項設定。
- 執行一個唯讀或可撤銷的請求。
- 檢查日誌、退出碼和最終檔案。
- 失敗時恢復剛才那一項修改。
|
|
這裡的完成標準不是介面出現，而是「隧道斷開與頁面假在線」有可重複結果。
關閉服務並清理殘留端口
| 要檢查的內容 | 合格表現 | 需要停止的信號 |
|---|---|---|
| 關閉服務並清理殘留連接埠 | 輸入和輸出範圍明確 | 自動擴大到其他項目或帳號 |
| 權限 | 只獲得完成任務所需權限 | 要求管理員權限或完整金鑰 |
| 日誌 | 能定位失敗且已經脫敏 | 出現 Token、Cookie 或私有正文 |
| 回退 | 能恢復上一步狀態 | 修改不可逆且沒有備份 |
|
|
表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。
遠端存取驗收清單
圍繞「遠端存取驗收清單」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。
|
|
建議記錄以下四項：
- 執行前的版本或 Git 提交。
- 實際輸入，不記錄秘密值。
- 可觀察的輸出、狀態碼或 diff。
- 恢復動作以及恢復後的複查結果。
如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。
限制 SSH 轉送帳號
這一節解決的是「限制 SSH 轉送帳號」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。
對 Pi Web 而言，判斷依據是：Pi Web 預設只監聽 127.0.0.1，而且沒有應用層認證；它能呼叫高權限 Agent，因此遠端存取首選 SSH 本地轉發，而不是直接綁定 0.0.0.0。不要在這個階段順手打開更多權限。
|
|
執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。
Pi 會話檔案的備份邊界
按下面順序處理：
- 讀取實際版本和目前配置。
- 只改變與本節相關的一項設定。
- 執行一個唯讀或可撤銷的請求。
- 檢查日誌、退出碼和最終檔案。
- 失敗時恢復剛才那一項修改。
|
|
這裡的完成標準不是介面出現，而是「Pi 會話檔案的備份邊界」有可重複結果。
反代認證失效立即停用路由
| 要檢查的內容 | 合格表現 | 需要停止的信號 |
|---|---|---|
| 反代認證失效立即停用路由 | 輸入和輸出範圍明確 | 自動擴大到其他項目或帳號 |
| 權限 | 只獲得完成任務所需權限 | 要求管理員權限或完整金鑰 |
| 日誌 | 能定位失敗且已經脫敏 | 出現 Token、Cookie 或私有正文 |
| 回退 | 能恢復上一步狀態 | 修改不可逆且沒有備份 |
|
|
表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。
升級後再複查監聽位址
圍繞「升級後複查監聽位址」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。
|
|
建議記錄以下四項：
- 執行前的版本或 Git 提交。
- 實際輸入，不記錄秘密值。
- 可觀察的輸出、狀態碼或 diff。
- 恢復動作以及恢復後的複查結果。
如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。
Pi Web 常見問題
是否可以跳過測試環境，直接把 Pi Web 用到正式專案？
不建議。至少先完成一次最小成功請求、一次故意失敗和一次恢復演練。
Pi Web 指令能運作但結果不對，先查哪裡？
先查輸入範圍、實際生效的配置和上游響應，再查模型總結。進程正常不代表業務結果正確。
如何避免 Pi Web 的金鑰或令牌進入 Git？
使用系統環境變數、Secret 管理或專案外設定文件，並在提交前搜尋 diff。發現洩漏後必須輪換密鑰。
升級 Pi Web 時最容易漏掉什麼？
最容易漏掉配置格式、預設監聽位址、權限範圍和快取相容性。升級前儲存版本與驗證樣本。
Pi Web 驗收問題
完成後應能回答下面的問題：
- 使用的是哪個確切版本？
- 哪些目錄、連接埠、帳號和外部服務可被存取？
- 成功結果如何回到原始資料或 Git diff？
- 上游失敗時會報錯、重試還是切換？
- 金鑰是否可能出現在日誌或歷史記錄？
- 如何在十分鐘內回到修改前狀態？
如果其中任何一項無法回答，Pi Web 仍處於試用狀態，不應擴大權限或接取生產自動化。