AppFolio 部署整合 是做什麼的?
概述
使用 Docker 部署一個容器化的 AppFolio 物業管理整合服務。本技能涵蓋建置一個生產就緒的映像檔,該映像檔連接至 AppFolio Stack API,用於管理物業、租戶和工單。包括多物業設定的環境配置、驗證 API 連線的運作狀態檢查,以及在您的物業組合中實現零停機部署的滾動更新策略。
先決條件
- 一份已驗證的供應商合約,以及一個由密碼管理器支援、綁定合約的 AppFolio 客戶端;請勿將憑證值放入映像檔層、docker-compose 檔案、 shell 歷史紀錄或部署日誌中。
- 一個能夠執行真實滾動/金絲雀更新、具備就緒檢查、流量控制、回滾 功能,並指定發布擁有者的部署平台。
- 分別的 staging 與 production 身分、一個合成的 staging 煙霧測試 fixture,以及一份針對未知寫入或協調狀態的事故應變計畫。
操作說明
- 建置一個非 root 使用者映像檔,鎖定相依套件,並僅暴露一個本地 的存活端點;供應商的可用性屬於準備就緒檢查,而非程序存活範疇。
- 在執行階段從密碼管理器注入已驗證的客戶端配置,並透過授權的 安全讀取在 staging 環境中驗證其合約。
- 逐步推出新版本,監控經過修飾的準備就緒/錯誤訊號,並在流量 窗口成功切換前保留先前的版本。
- 若任何準備就緒、合約、密碼或協調檢查失敗,則停止流量提升, 並透過部署平台進行回滾。
Docker 配置
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build
FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD node -e "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
CMD ["node", "dist/index.js"]
執行階段配置
# 這些值由部署平台的密碼管理器注入;請勿將即時憑證貼到終端機命令或版本控制的配置中。
APPFOLIO_BASE_URL="供應商提供的基礎 URL"
APPFOLIO_COMPANY_ID="已核准的物業組合識別碼"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"
運作狀態檢查端點
import express from 'express';
const app = express();
// 存活端點證明此程序可以提供服務;它不應因為外部供應商降級而重新啟動一個健康的 worker。
app.get('/health', (_req, res) => {
res.json({ status: 'healthy', service: 'appfolio-integration' });
});
app.get('/ready', async (_req, res) => {
try {
const response = await createVerifiedAppFolioClient().get('/properties?limit=1');
if (response.status < 200 || response.status >= 300) throw new Error(`AppFolio API 回傳 ${response.status}`);
res.json({ status: 'ready', service: 'appfolio-integration', timestamp: new Date().toISOString() });
} catch (error) {
res.status(503).json({ status: 'not-ready', error: '供應商準備就緒檢查失敗' });
}
});
部署步驟
步驟 1:建置
docker build -t appfolio-integration:latest .
步驟 2:執行
docker run -d --name appfolio-integration \
-p 3000:3000 \
-e APPFOLIO_API_KEY -e APPFOLIO_BASE_URL -e APPFOLIO_COMPANY_ID \
appfolio-integration:latest
步驟 3:驗證
curl -s http://localhost:3000/health | jq .
步驟 4:滾動更新
# 將不可變的映像檔摘要提交至平台的部署控制器。
# 將 /health 配置為存活檢查,/ready 配置為準備就緒檢查,分階段轉移流量,
# 並在發布窗口完成前保留先前的版本。
錯誤處理
| 問題 | 原因 | 修正方式 |
|---|---|---|
401 Unauthorized | API 金鑰無效或過期 | 在 AppFolio Stack 合作夥伴入口網站重新產生金鑰 |
403 Forbidden | 缺少物業存取範圍 | 向 AppFolio 管理員請求額外的範圍 |
404 Not Found | 基礎 URL 或公司 ID 不正確 | 確認 APPFOLIO_BASE_URL 與您的子網域相符 |
429 Rate Limited | 每分鐘請求次數過多 | 實作指數退避演算法,窗口時間 60 秒 |
| 容器立即退出 | 缺少必要的環境變數 | 確保在啟動前設定所有環境變數 |
輸出
- 一個非 root 使用者的容器,包含本地存活端點和獨立的、經過修飾的供應商準備就緒結果
- 一個密碼管理器/執行階段配置的邊界,而非將憑證值放在映像檔或命令中
- 一個階段性部署收據,包含準備就緒證據、流量狀態、擁有者、回滾目標和協調狀態
範例
對於一個物業同步發布,將新的映像檔部署至 staging 環境,搭配一個合成的安全讀取 fixture,確認 /health 保持存活,同時 /ready 反映供應商客戶端結果。僅在受管身分、修飾過的準備就緒、警報和回滾目標都驗證通過後,才將少量的生產流量切換過去。如果準備就緒檢查失敗、密碼遺失,或先前的寫入有未知結果,請凍結提升動作,將流量導回先前的版本,並在嘗試再次推出之前指派協調工作。
資源
後續步驟
請參閱 appfolio-webhooks-events。