AppFolio 调试包 是做什么的?
概览
本调试包从 AppFolio 物业管理 API 集成中收集诊断证据,用于支持升级和根因分析。它捕获针对属性、租户和工作订单端点的 API 连接性、使用客户端凭证对的身份验证状态、集成管道中的近期错误日志以及 SDK 版本信息。生成的 tarball 包为支持工程师提供了诊断连接故障、身份验证拒绝和数据同步问题所需的一切,无需实时访问您的环境。
前提条件
- 已安装
curl、jq、tar - 已配置
APPFOLIO_CLIENT_ID和APPFOLIO_CLIENT_SECRET(基本认证对) - 已将
APPFOLIO_BASE_URL设置为您的 Stack API 基础地址(例如https://yourcompany.appfolio.com/api/v1)
使用说明
- 获得事件批准并确定受影响的时段、投资组合和安全只读探测项;不要仅因为可用就收集租户、租约、付款或原始日志正文。
- 仅创建包含脱敏配置状态、提供商状态/延迟、速率限制标头和包版本的包;将凭据保留在 argv 之外。
- 在共享之前检查每个文件,使用加密或批准的支持渠道传输归档文件,并根据事件策略删除本地副本。
- 如果证据需要敏感记录,请停止并获取单独批准的极简导出,而不是扩展此通用调试包。
调试收集脚本
#!/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 "=== 环境 ===" > "$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 健康状态 ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# 工作订单端点探测
echo "=== 工作订单 ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# 租户端点探测
echo "=== 租户 ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# 仅日志清单;原始日志可能包含租户和财务数据。
echo "=== 日志清单 ===" > "$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 "=== 速率限制 ===" > "$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 "=== 依赖项 ===" > "$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 |
| 租户端点返回 403 禁止访问 | tenants.txt HTTP 403 | Stack API 作用域缺失;在 AppFolio 合作伙伴门户中请求租户读取权限 |
| 429 请求过多 | rate-limits.txt 显示 retry-after 标头 | 退避并实现指数重试;AppFolio 允许 120 req/min |
| 工作订单超时 | api-health.txt 显示时间 > 30s | 减小 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 或超时,仅收集脱敏的时序/状态证据并检查提供商状态页面。如果支持人员需要特定的租户或付款记录,请使用单独批准的极简导出,该导出具有自己的保留和访问控制。
示例
对于生产同步超时,创建一个覆盖受影响时段和一个属性安全只读探测的包。确认其中包含状态/延迟、速率标头、依赖项版本和日志文件元数据,但不包含响应体、凭证、租户或财务数据。在将归档文件上传到批准的加密支持通道之前,请对其进行审查。如果审查发现存在原始负载或密钥,请删除归档文件,根据需要轮换密钥,并在上报之前重新生成最小化的包。
自动化健康检查
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。