AppFolio 除錯套件 是做什麼的?
概述
此除錯套件從 AppFolio 物業管理 API 整合收集診斷證據,用於支援升級與根本原因分析。它會擷取針對 properties、tenants 及 work_orders 端點的 API 連線狀態、使用客戶端憑證對進行驗證、來自整合管道的近期錯誤日誌,以及 SDK 版本資訊。最終的壓縮套件能讓支援工程師無需即時存取您的環境,即可診斷連線失敗、驗證拒絕與資料同步問題。
前置條件
- 已安裝
curl、jq、tar - 已設定
APPFOLIO_CLIENT_ID與APPFOLIO_CLIENT_SECRET(基本驗證憑證對) - 已將
APPFOLIO_BASE_URL設定為您的 Stack API 基礎網址(例如https://yourcompany.appfolio.com/api/v1)
指示
- 取得事件核准,並定義受影響的時間範圍、投資組合與安全唯讀探測;切勿僅因資料可用就收集租戶、租約、付款或原始日誌內容。
- 建立僅包含經過編輯的設定狀態、提供者狀態/延遲、速率限制標頭與套件版本的套件;確保憑證不出現在命令列參數中。
- 在分享前檢閱每個檔案,使用加密或經核可的支援管道傳送封存檔,並依據事件政策刪除本機副本。
- 若證據需要機敏記錄,請停止並取得另行核准的最小匯出,而非擴充此通用除錯套件。
除錯收集腳本
#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
"$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
probe() {
endpoint="$1"
curl -s -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
--netrc-file "$NETRC_FILE" "${APPFOLIO_BASE_URL}/${endpoint}?per_page=1" \
|| printf 'UNREACHABLE\n'
}
# 環境檢查
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"
# 僅 API 連線中繼資料 — 絕不將 API 回應主體寫入此套件。
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# Work orders 端點探測
echo "=== Work Orders ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# Tenant 端點探測
echo "=== Tenants ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# 僅記錄日誌清單;原始日誌可能包含租戶與財務資料。
echo "=== Log Inventory ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s bytes\n' 2>/dev/null \
|| echo "No sync logs found" >> "$BUNDLE/app-logs.txt"
# 速率限制標頭
echo "=== Rate Limits ===" > "$BUNDLE/rate-limits.txt"
curl -sI --netrc-file "$NETRC_FILE" \
"${APPFOLIO_BASE_URL}/properties?per_page=1" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE/rate-limits.txt"
# 套件版本
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "No AppFolio npm packages found" >> "$BUNDLE/deps.txt"
tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"
分析套件
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # 確認憑證已設定
cat debug-appfolio-*/api-health.txt # 檢查 HTTP 狀態與延遲
cat debug-appfolio-*/rate-limits.txt # 確認未被限流
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # 解析錯誤負載
常見問題
| 症狀 | 在套件中檢查 | 修正 |
|---|---|---|
| 所有端點回傳 401 | environment.txt 顯示用戶端 ID/密碼未設定 | 在環境變數中設定 APPFOLIO_CLIENT_ID 與 APPFOLIO_CLIENT_SECRET |
| tenants 回傳 403 禁止 | tenants.txt HTTP 403 | Stack API 範圍遺漏;在 AppFolio 合作夥伴入口網站請求租戶讀取權限 |
| 429 請求過多 | rate-limits.txt 顯示 retry-after 標頭 | 減速並實作指數退避;AppFolio 允許每分鐘 120 次請求 |
| work orders 逾時 | api-health.txt 顯示時間 > 30 秒 | 減少 per_page 參數;按 updated_since 篩選以縮小結果集 |
| 空置產清單 | api-health.txt 回傳 [] | 確認 APPFOLIO_BASE_URL 指向正確的投資組合;檢查物業群組篩選器 |
| SSL 憑證錯誤 | api-health.txt 顯示 curl SSL 錯誤 | 更新 CA 套件:sudo update-ca-certificates;檢查代理設定 |
輸出
- 一份可檢閱、經過編輯的套件,包含設定存在性、端點狀態與延遲、速率限制標頭、日誌清單與相依性中繼資料
- 一份支援交接收據,說明事件範圍與機敏資料排除項目,而非封裝租戶、付款或原始應用程式記錄
- 當無法安全收集所需證據時,執行失敗關閉決策
錯誤處理
將探測失敗視為探測失敗的證據,而非允許擷取更大的回應或繞過憑證控制。對於 401/403,與憑證擁有者確認受管用戶端設定;對於 429,保留速率標頭並暫停進一步探測;對於 5xx 或逾時,僅收集經過編輯的時序/狀態證據,並檢查提供者狀態頁面。若支援人員需要特定租戶或付款記錄,請使用另行核准的最小匯出,並附帶其自己的保留與存取控制。
範例
針對生產同步逾時,建立涵蓋受影響時間範圍與一個 properties 安全唯讀探測的套件。確認其中包含狀態/延遲、速率標頭、相依性版本與日誌檔案中繼資料—但不包含任何回應主體、憑證、租戶或財務資料。在上傳至核可的加密支援管道前,檢閱封存檔。若檢閱發現原始負載或機密,請刪除封存檔,視需要輪換憑證,並在升級前重新產生最小化的套件。
自動化健康檢查
async function checkAppFolioHealth(): Promise<{
status: string;
latencyMs: number;
endpoints: Record<string, number>;
}> {
const baseUrl = process.env.APPFOLIO_BASE_URL;
const creds = Buffer.from(
`${process.env.APPFOLIO_CLIENT_ID}:${process.env.APPFOLIO_CLIENT_SECRET}`
).toString("base64");
const headers = { Authorization: `Basic ${creds}` };
const endpoints = ["properties", "tenants", "work_orders"];
const results: Record<string, number> = {};
const start = Date.now();
for (const ep of endpoints) {
const res = await fetch(`${baseUrl}/${ep}?per_page=1`, { headers });
results[ep] = res.status;
}
return {
status: Object.values(results).every((s) => s === 200) ? "healthy" : "degraded",
latencyMs: Date.now() - start,
endpoints: results,
};
}
資源
後續步驟
請參閱 appfolio-rate-limits。