AppFolio 部署集成
概述
使用 Docker 部署一个容器化的 AppFolio 物业管理集成服务。本技能涵盖构建连接到 AppFolio Stack API 的生产就绪镜像,用于管理物业、租户和工作订单。包含多物业设置的环境配置、验证 API 连接的健康检查,以及跨物业组合实现零停机部署的滚动更新策略。
前提条件
- 一份已验证的供应商合同以及一个由密钥管理器支持的、与合同绑定的 AppFolio 客户端;不要将凭据值放入镜像层、Compose 文件、Shell 历史记录或部署日志中。
- 一个能够执行真实滚动/金丝雀更新的部署平台,具备就绪检查、流量控制、回滚和已命名的发布负责人。
- 独立的暂存和生产身份、一个合成的暂存环境烟雾测试夹具,以及针对未知写入或协调状态的应急预案。
说明
- 构建一个以非 root 用户运行的镜像,锁定依赖项,并仅暴露一个本地的活动端点;供应商可用性属于就绪检查,而非进程存活检查。
- 在运行时从密钥管理器注入已验证的客户端配置,并通过授权的安全读取在暂存环境中验证其合同。
- 逐步推出新修订版,监控经过处理的就绪/错误信号,并在流量窗口成功完成前保留先前的修订版。
- 如果任何就绪检查、合同、密钥或协调检查失败,则停止流量提升,并通过部署平台回滚。
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();
// 活动检查证明此进程可以提供服务;它不应仅因外部供应商降级而重启一个健康的工作进程。
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: '供应商就绪检查失败' });
}
});
部署步骤
第一步:构建
docker build -t appfolio-integration:latest .
第二步:运行
docker run -d --name appfolio-integration \
-p 3000:3000 \
-e APPFOLIO_API_KEY -e APPFOLIO_BASE_URL -e APPFOLIO_COMPANY_ID \
appfolio-integration:latest
第三步:验证
curl -s http://localhost:3000/health | jq .
第四步:滚动更新
# 将不可变的镜像摘要提交到平台的部署控制器。
# 将 /health 配置为活动检查,/ready 配置为就绪检查,分阶段转移流量,
# 并保留先前的修订版,直到发布窗口完成。
错误处理
| 问题 | 原因 | 修复 |
|---|---|---|
401 Unauthorized | API 密钥无效或已过期 | 在 AppFolio Stack 合作伙伴门户中重新生成密钥 |
403 Forbidden | 缺少属性访问权限 | 向 AppFolio 管理员请求额外的权限范围 |
404 Not Found | 基础 URL 或公司 ID 错误 | 验证 APPFOLIO_BASE_URL 是否与您的子域名匹配 |
429 Rate Limited | 每分钟请求过多 | 实现指数退避算法,窗口为 60 秒 |
| 容器立即退出 | 缺少必需的环境变量 | 确保在启动前设置所有环境变量 |
输出
- 一个非 root 容器,包含一个本地活动端点和一个独立的、经过处理的供应商就绪结果
- 一个密钥管理器/运行时配置边界,而非镜像或命令中的凭据值
- 一份分阶段部署收据,包含就绪证据、流量状态、负责人、回滚目标和协调状态
示例
对于属性同步发布,将新镜像部署到暂存环境,使用合成的安全读取夹具,并确认 /health 保持活动状态,而 /ready 反映供应商客户端结果。只有在托管身份、处理后的就绪检查、警报和回滚目标都经过验证后,才促进一小部分生产流量。如果就绪检查失败、缺少密钥或先前的写入具有未知结果,则冻结提升,将流量返回到先前的修订版,并在尝试再次发布之前分配协调任务。
资源
后续步骤
请参阅 appfolio-webhooks-events。