mcpField
A
app-platform-troubleshooting

app-platform-troubleshooting

github.com/digitalocean-labs云与 DevOps3891 次安装3 天前更新
代码仓库

关于 app-platform-troubleshooting

面向 DigitalOcean App Platform 开发者的故障排查技能，通过容器实时访问或日志分析指导诊断，并可借助调试容器隔离基础设施问题。

主要功能

  1. 01通过 SDK 进行实时 Shell 诊断
  2. 02分析运行、构建和崩溃日志
  3. 03使用调试容器验证基础设施
  4. 04常见错误与修复速查

适用场景

  1. 01通过 Shell 调查已部署应用
  2. 02根据日志诊断构建或部署失败
  3. 03区分基础设施故障与应用问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/digitalocean-labs/do-app-platform-skills --skill app-platform-troubleshooting

安装后在 Claude Code 中输入/app-platform-troubleshooting确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
reference/
app-maintenance.md
debug-container.md
diagnostic-scripts.md
live-troubleshooting.md
logs-analysis.md
networking-issues.md

详细介绍

应用平台故障排查技能

将调试从猜测转变为快速诊断和修复。

理念

Traditional: See error → Guess → Change → Push → Wait 5-7 min → Repeat
With skill:  See error → Diagnose → Fix → Verify → Commit proper fix

快速决策

Is the app deployed with running containers?
├── YES → Can we access the shell?
│         ├── YES → LIVE MODE (SDK shell access)
│         └── NO  → LOGS-ONLY MODE (fetch logs)
└── NO (build/deploy failed) → LOGS-ONLY MODE

模式 1：实时故障排查（快速入门）

from do_app_sandbox import Sandbox

app = Sandbox.get_from_id(app_id="<app-id>", component="web")

# Diagnostics
app.exec("env | grep DATABASE")
app.exec("curl -v localhost:8080/health")
app.exec("ps aux | head -10")

完整指南：参见 live-troubleshooting.md

模式 2：仅分析日志（快速入门）

# Runtime logs
doctl apps logs <app_id> <component> --type run

# Build logs
doctl apps logs <app_id> <component> --type build

# Crash logs
doctl apps logs <app_id> --type=run_restarted

完整指南：参见 logs-analysis.md

调试容器（基础设施问题）

大约 30-45 秒即可部署，用于区分基础设施问题和应用问题：

services:
  - name: debug
    image:
      registry_type: GHCR
      registry: ghcr.io
      repository: bikramkgupta/debug-python
      tag: latest
    http_port: 8080
    envs:
      - key: DATABASE_URL
        value: ${db.DATABASE_URL}

# Run validation suite
validate-infra all
validate-infra database
validate-infra kafka

完整指南：参见 debug-container.md

快速参考：退出代码

代码信号含义
0-正常退出（不应退出）
1-一般错误
127-找不到命令
137SIGKILL因 OOM 被终止
143SIGTERM正常关闭

快速参考：常见修复方法

问题快速修复方法
应用立即退出检查是否正在监听 $PORT
502 错误检查健康检查端点，确认应用正在运行
数据库连接失败使用调试容器，确认可信来源
构建失败检查依赖项，查看构建日志
因 OOM 被终止升级实例规格
健康检查失败绑定到 0.0.0.0，而不是 localhost
启动缓慢增加 initial_delay_seconds

参考文件

何时升级处理

遇到以下情况时，请联系 DigitalOcean Support：

  • 重新部署后内部错误仍然存在
  • 需要提高资源限制
  • 多个应用受到影响（平台问题）
  • 无法诊断 VPC/网络问题

升级处理前，请收集：

doctl apps get <app_id> -o json > app_info.json
doctl apps logs <app_id> <component> --type run > runtime.log
doctl apps spec get <app_id> > app_spec.yaml

与其他技能集成

  • → deployment：修复后，部署正确的更改
  • → devcontainers：在本地复现问题
  • → postgres：数据库专属配置
  • → networking：完整的网络文档

评论

支持 Markdown