app-platform-migration

App Platform 迁移技能

将现有应用迁移到 DigitalOcean App Platform，并如实评估其功能支持情况。

理念

这项技能是诚实的合作伙伴，而不是魔法棒。它会：

1. 全面分析，然后再提出更改建议
2. 尽可能有把握地进行映射
3. 清晰、具体地说明差距
4. 遇到不确定情况时，先询问再继续
5. 绝不猜测或忽略不兼容之处

提示：对于复杂的多步骤迁移，请先使用 planner 技能。有关所有可用技能，请参阅 根目录中的 SKILL.md。

---

快速决策

What's your source platform?
├── Heroku (Procfile, app.json, heroku.yml) → See Heroku Deep Chapter below
├── Docker Compose → See Quick Start below
├── Render/Railway/Fly.io → See Quick Start below
├── AWS ECS/App Runner → Complex migration, see reference
└── Just Dockerfile → See Quick Start below

---

支持的平台

平台	配置文件	支持级别
Heroku	Procfile、app.json、heroku.yml	完全支持（深度章节）
Docker Compose	docker-compose.yml	完全支持
Render	render.yaml	完全支持
Railway	railway.json、railway.toml	完全支持
Fly.io	fly.toml	完全支持
AWS ECS	任务定义 JSON	部分支持
AWS App Runner	apprunner.yaml	部分支持
通用 Docker	仅 Dockerfile	完全支持

---

迁移工作流

Phase 1: DISCOVERY
├── Clone/access repository
├── Detect source platform
├── Analyze architecture
└── Inventory all services

Phase 2: MAPPING
├── Map services → App Platform components
├── Map databases → Managed databases
├── Map storage → Spaces
├── Map secrets → GitHub Secrets
└── Identify unmappable items → REPORT TO USER

Phase 3: REFACTORING
├── Create target branch(es)
├── Update environment variables
├── Remove platform-specific code
├── Update Dockerfile if needed
└── Generate app spec

Phase 4: VALIDATION
├── Validate: doctl apps spec validate
├── Review changes with user
└── Generate migration checklist

Phase 5: HANDOFF
├── Push branches to repo
├── Provide manual steps checklist
└── Suggest deployment skill

---

快速开始

基本迁移

# User provides repo URL
"Migrate this app to App Platform: https://github.com/myorg/myapp"

# AI will:
# 1. Clone and analyze
# 2. Detect platform
# 3. Present mapping proposal
# 4. Ask for approval
# 5. Create branch with refactored code + app spec

指定分支

"Migrate my Heroku app. Put test config in 'migrate/test', prod in 'migrate/prod'"

完整工作流：请参阅 workflow-examples.md

---

Heroku 迁移（深度章节）

针对 Heroku 的迁移提供了一个内容全面的章节，深入介绍 Procfile、app.json、heroku.yml、构建包、流水线、附加组件和 CLI 映射。

从这里开始：阅读 heroku-overview.md，确定迁移模式（问答、引导式或自动迁移），然后按照其中的指引查看：

• heroku-concepts.md — Heroku 配置文件架构、CLI 命令、构建包检测、流水线结构
• heroku-mapping.md — 组件类型、构建配置、环境变量、实例规格、网络、区域
• heroku-addons.md — 从 app.json 检测附加组件、DO 托管服务的对应项、外部替代方案
• heroku-workflows.md — 问答、引导式和自动迁移模式的分步流程

快速映射（Heroku）

Heroku	App Platform
web 进程	services
worker 进程	workers
release 阶段	jobs (PRE_DEPLOY)
heroku-postgresql	托管 Postgres
heroku-redis	托管 Valkey
Config Vars	GitHub Secrets
Pipelines	GitHub Actions
Review Apps	预览环境
Heroku Scheduler	jobs (CRON_TRIGGER)

完整映射：请参阅 heroku-mapping.md

---

快速映射参考

Docker Compose

Docker Compose	App Platform
services.<name>.ports	services
services.<name>（无端口）	workers
services.postgres	托管 Postgres
services.redis	托管 Valkey
volumes	Spaces（无持久卷）

完整映射表：请参阅 platform-mappings.md

---

无法映射的项目（快速参考）

来源	问题	选项
CloudFront CDN	没有 DO CDN	使用外部 CDN（Cloudflare）或跳过
AWS Secrets Manager	模型不同	GitHub Secrets
持久卷	不支持	文件使用 Spaces，数据使用托管数据库
ARM 容器	仅支持 AMD64	为 AMD64 重新构建

完整列表：请参阅 platform-mappings.md

---

输出产物

文件	用途
.do/app.yaml	App Platform 规范
.do/deploy.template.yaml	一键部署到 DO
MIGRATION.md	迁移检查清单和状态
.env.example	环境变量模板

App 规范模板：参见 app-spec-generation.md

---

脚本

脚本	用途
scripts/detect_platform.py	根据文件检测源平台
scripts/analyze_architecture.py	分析应用架构
scripts/generate_app_spec.py	生成 .do/app.yaml
scripts/generate_checklist.py	生成迁移检查清单

---

参考文件

Heroku（深度章节）

• heroku-overview.md - 入门指南：进行任何 Heroku 迁移前请先阅读
• heroku-concepts.md - Procfile、app.json、heroku.yml、流水线、CLI
• heroku-mapping.md - Heroku → App Platform 功能深度映射
• heroku-addons.md - 插件生态系统映射（Postgres、Redis 等）
• heroku-workflows.md - 迁移工作流：问答、引导式、自动迁移

通用

• platform-mappings.md - 所有平台检测、映射表和注意事项
• code-refactoring.md - 环境变量更新、S3/Valkey 迁移、数据迁移
• workflow-examples.md - Docker Compose、AWS ECS 操作演示
• app-spec-generation.md - 测试/生产规范模板、默认值

---

常见问题（快速修复）

问题	原因	修复方法
App 规范验证失败	YAML 无效	检查缩进，运行 doctl apps spec validate
数据库连接失败	URL 格式错误	使用 ${db.DATABASE_URL} 绑定
构建失败	缺少依赖项	检查 Dockerfile 构建依赖
端口绑定失败	PORT 处理错误	绑定到 $PORT 或 0.0.0.0:8080
健康检查失败	路径错误	确认 /health 端点存在

完整故障排查：参见 code-refactoring.md

---

与其他技能集成

• → deployment：迁移后的 GitHub Actions 工作流
• → postgres：复杂数据库设置、架构隔离
• → devcontainers：迁移后的本地开发环境
• → troubleshooting：用于排查迁移问题的调试容器

---

文档链接

• App 规范参考
• Heroku 迁移指南
• 部署到 DO 按钮