render-debug

调试 Render 部署

使用日志、指标和数据库查询分析部署故障。找出根本原因并应用修复。

何时使用此技能

在以下情况下启用此技能：

• Render 上的部署失败
• 服务无法启动或持续崩溃
• 用户提到错误、日志或调试
• 健康检查超时
• 生产环境中的应用错误
• 性能问题（响应缓慢）
• 数据库连接问题

Render 访问权限

在读取日志、指标或数据库状态之前，请按照 references/render-access.md 建立访问权限并确认目标工作区。优先使用 MCP；CLI 可提供日志和部署状态，而指标和结构化数据库查询则需要 MCP。

---

调试工作流

如果故障涉及配置或密钥，请在检查或更改服务变量之前阅读 references/environment-variables.md。 如果故障涉及部署状态、发布、健康检查、重启、回滚或关停，请在诊断前阅读 references/deployments.md。

步骤 1：识别失败的服务

list_services()

如果尚未配置 MCP，请询问用户是要设置 MCP（推荐），还是继续使用 CLI。然后继续操作。

查找状态为失败的服务。获取详细信息：

get_service(serviceId: "<id>")

步骤 2：获取日志

构建／部署日志（大多数故障）：

list_logs(resource: ["<service-id>"], type: ["build"], limit: 200)

运行时错误日志：

list_logs(resource: ["<service-id>"], level: ["error"], limit: 100)

搜索特定错误：

list_logs(resource: ["<service-id>"], text: ["KeyError", "ECONNREFUSED"], limit: 50)

HTTP 错误日志：

list_logs(resource: ["<service-id>"], statusCode: ["500", "502", "503"], limit: 50)

步骤 3：分析错误模式

将日志错误与已知模式进行匹配：

错误	日志模式	常见修复方法
MISSING_ENV_VAR	KeyError、not defined	添加到 render.yaml 或 update_environment_variables
PORT_BINDING	EADDRINUSE	使用 0.0.0.0:$PORT
MISSING_DEPENDENCY	Cannot find module	添加到 package.json/requirements.txt
DATABASE_CONNECTION	ECONNREFUSED :5432	检查 DATABASE_URL 和数据库状态
HEALTH_CHECK	Health check timeout	添加 /health 端点，检查端口绑定
OUT_OF_MEMORY	heap out of memory、exit 137	优化内存或升级套餐
BUILD_FAILURE	Command failed	修复构建命令或依赖项

完整错误目录：references/error-patterns.md

如果错误在多次部署中反复出现： 不要再逐项修补，应进行全面排查。扫描代码库／配置，找出该类错误的所有可能原因（相关环境变量、构建配置、依赖项或类型错误），并在下次重新部署前一并解决。

步骤 4：检查指标（性能问题）

对于崩溃、响应缓慢或资源问题：

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["cpu_usage", "memory_usage", "memory_limit"]
)

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_latency"],
  httpLatencyQuantile: 0.95
)

详细的指标指南：references/metrics-debugging.md

步骤 5：调试数据库问题

对于数据库相关错误：

# Check database status
list_postgres_instances()

# Check connections
get_metrics(resourceId: "<postgres-id>", metricTypes: ["active_connections"])

# Query directly
query_render_postgres(
  postgresId: "<postgres-id>",
  sql: "SELECT state, count(*) FROM pg_stat_activity GROUP BY state"
)

详细的数据库指南：references/database-debugging.md

步骤 6：应用修复

对于环境变量：

update_environment_variables(
  serviceId: "<service-id>",
  envVars: [{"key": "MISSING_VAR", "value": "value"}]
)

对于代码更改：

1. 编辑源文件
2. 提交并推送
3. 如果启用了自动部署，将自动触发部署

步骤 7：验证修复

# Check deploy status
list_deploys(serviceId: "<service-id>", limit: 1)

# Check for new errors
list_logs(resource: ["<service-id>"], level: ["error"], limit: 20)

# Check metrics
get_metrics(resourceId: "<service-id>", metricTypes: ["http_request_count"])

---

快速工作流

常见场景的预置调试流程：

场景	工作流
部署失败	list_deploys → list_logs(type: build) → 修复 → 重新部署
应用崩溃	list_logs(level: error) → get_metrics(memory) → 修复
应用运行缓慢	get_metrics(http_latency) → get_metrics(cpu) → query_postgres
数据库连接问题	list_postgres → get_metrics(connections) → query_postgres
部署后检查	list_deploys → list_logs(error) → get_metrics

详细工作流：references/quick-workflows.md

---

快速参考

MCP 工具

# Service Discovery
list_services()
get_service(serviceId: "<id>")
list_postgres_instances()

# Logs
list_logs(resource: ["<id>"], level: ["error"], limit: 100)
list_logs(resource: ["<id>"], type: ["build"], limit: 200)
list_logs(resource: ["<id>"], text: ["search"], limit: 50)

# Metrics
get_metrics(resourceId: "<id>", metricTypes: ["cpu_usage", "memory_usage"])
get_metrics(resourceId: "<id>", metricTypes: ["http_latency"], httpLatencyQuantile: 0.95)

# Database
query_render_postgres(postgresId: "<id>", sql: "SELECT ...")

# Deployments
list_deploys(serviceId: "<id>", limit: 5)

# Environment Variables
update_environment_variables(serviceId: "<id>", envVars: [{key, value}])

CLI 命令（备用）

render services -o json
render logs -r <service-id> --level error -o json
render logs -r <service-id> --tail -o text
render deploys create <service-id> --wait

---

参考资料

• Render 访问权限： references/render-access.md
• 环境变量： references/environment-variables.md
• 计算计划： references/compute-plans.md
• 部署： references/deployments.md
• 错误模式： references/error-patterns.md
• 指标调试： references/metrics-debugging.md
• 数据库调试： references/database-debugging.md
• 快速工作流： references/quick-workflows.md
• 日志分析： references/log-analysis.md
• 故障排查： references/troubleshooting.md

相关技能

• render-deploy — 将新应用部署到 Render
• render-monitor — 持续监控服务运行状况
• render-mcp — MCP 服务设置和能力发现

当前文档检索

每当此技能要求你查阅当前的 Render 文档时：

1. 使用可用的 URL 获取工具或 HTTP 客户端（如 curl）直接检索链接的 Markdown 文档。不要用网页搜索摘要代替文档。
2. 确认检索成功并返回了预期文档，然后阅读其内容。保存文件或打印文件路径并不足够。
3. 如果请求失败，或你的工具无法读取 Markdown 响应，则打开并阅读链接的 HTML 版本。
4. 如果两个版本都无法检索，请说明当前参考资料不可用，并遵循技能中针对该主题的后备方案。仅将随附指南用于稳定不变的限制，不要猜测可能变化的平台细节。

当任务需要查阅多个参考资料时，对每一份资料都执行此流程，并区分已验证的文档和仍不可用的文档。