app-platform-designer

App Platform 设计技能

将自然语言描述转换为可用于生产环境的 App Platform 规范。

核心问题：“我想构建[描述]。我的 App Platform 架构应该是什么样的？”

生成内容：

• .do/app.yaml — App Platform 规范
• .do/deploy.template.yaml — 部署到 DO 按钮（公开仓库）
• .env.example — 环境变量模板

---

快速决策

What do you need?
├── Design new app from description → Workflow 1
├── Analyze repo and create spec → Workflow 2
├── Add Deploy to DO button → Workflow 3
└── Multi-environment setup → Workflow 4

---

工作流 1：自然语言 → App 规范

触发条件：“我需要一个具有[描述]的 Web 应用”

1. 收集需求：

   • 应用的功能是什么？
   • 使用什么语言／框架？
   • 有哪些数据库需求？
   • 是否需要后台处理？

2. 拆分组件：

   • 面向 HTTP 的组件 → services
   • 后台处理器 → workers
   • 一次性／定时任务 → jobs
   • 静态前端 → static_sites
   • 数据存储 → databases

3. 生成规范，包含运行状况检查、环境变量和路由

4. 验证： doctl apps spec validate .do/app.yaml

**完整指南：**参见 architecture-patterns.md

---

工作流 2：分析仓库 → App 规范

触发条件：“这是我的仓库，请创建 App 规范”

Check for:
├── Dockerfile → Use dockerfile build
├── package.json → Node.js app
├── requirements.txt / pyproject.toml → Python app
├── go.mod → Go app
├── Multiple directories with above → Monorepo

**完整指南：**参见 component-types.md

---

工作流 3：部署到 DO 按钮

触发条件：“添加部署到 DigitalOcean 按钮”

**要求：**公开的 GitHub 仓库

1. 创建 .do/deploy.template.yaml（将规范封装在 spec: 键下，并使用 git: 块）
2. 在 README 中添加按钮

[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/OWNER/REPO/tree/BRANCH)

**完整指南：**参见 deploy-to-do-button.md

---

推荐默认值

决策	默认值	原因
实例规格	apps-s-1vcpu-1gb	适合作为起点
实例数量	1	从最小配置开始
数据库	开发数据库	成本效益高
缓存	Valkey（而非 Redis）	Redis 已到生命周期终点
构建	如果存在 Dockerfile，则使用它	控制力更强
运行状况检查	/health 或 /healthz	行业标准
推送时部署	true	GitOps 工作流
区域	nyc	合适的默认值
源格式	git: 块	deploy.template.yaml 所需

---

组件摘要

类型	使用场景	示例
services	HTTP 工作负载	API、Web 应用
workers	后台处理	队列使用者、内部 API
jobs	一次性／定时任务	迁移、报告
static_sites	前端／文档	React、Vue、营销网站
databases	数据存储	PostgreSQL、Valkey

**完整指南：**参见 component-types.md

---

模式选择

What are you building?
├── Simple app (1 service)? → Pattern 1
├── Frontend + API? → Pattern 2
├── Need background processing? → Pattern 3
├── Monorepo? → Pattern 4
└── Complex SaaS? → Pattern 5

**完整模式：**参见 architecture-patterns.md

---

快速入门：单个服务 + DB

name: my-app
region: nyc

services:
  - name: web
    git:
      repo_clone_url: https://github.com/owner/repo.git
      branch: main
    http_port: 8080
    instance_size_slug: apps-s-1vcpu-1gb
    health_check:
      http_path: /health
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

databases:
  - name: db
    engine: PG
    production: false

---

快速入门：API + 前端

name: fullstack-app
region: nyc

services:
  - name: api
    git:
      repo_clone_url: https://github.com/owner/repo.git
      branch: main
    source_dir: /api
    http_port: 8080
    health_check:
      http_path: /health
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

static_sites:
  - name: frontend
    git:
      repo_clone_url: https://github.com/owner/repo.git
      branch: main
    source_dir: /frontend
    build_command: npm run build
    output_dir: dist
    envs:
      - key: VITE_API_URL
        scope: BUILD_TIME
        value: /api

databases:
  - name: db
    engine: PG
    production: false

ingress:
  rules:
    - match:
        path:
          prefix: /api
      component:
        name: api
    - match:
        path:
          prefix: /
      component:
        name: frontend

---

环境可移植设计

所有代码都必须适用于本地开发、Docker Compose 和 App Platform。

原则	实现方式
绑定到 $PORT	process.env.PORT || 3000
公共服务	列在 ingress.rules 中
内部服务	不列入 ingress，使用 ${name.PRIVATE_URL}
绝不硬编码	使用带默认值的环境变量

// Portable port binding
const port = process.env.PORT || 3000
server.listen({ port, host: '0.0.0.0' })

---

数据库速查

引擎	Slug	开发数据库？	备注
PostgreSQL	PG	是	推荐
Valkey	VALKEY	是	用它代替 Redis
MySQL	MYSQL	否	仅托管版
MongoDB	MONGODB	否	仅托管版

**完整指南：**参见 database-configuration.md

---

环境变量速查

作用范围	用例
RUN_TIME	密钥、数据库 URL
BUILD_TIME	公共 API URL、功能标志
RUN_AND_BUILD_TIME	NPM 令牌、共享配置

占位符	解析为
${db.DATABASE_URL}	数据库连接字符串
${service.PRIVATE_URL}	内部服务 URL
${service.PUBLIC_URL}	公共服务 URL

**完整指南：**参见 environment-variables.md

---

入口（路由）

ingress:
  rules:
    - match:
        path:
          prefix: /api
      component:
        name: api
    - match:
        path:
          prefix: /
      component:
        name: frontend

**高级路由：**参见 networking skill

---

验证

doctl apps spec validate .do/app.yaml
doctl apps spec validate .do/deploy.template.yaml

错误	修复方法
invalid component name	使用小写字母，仅使用连字符
unknown instance size	检查 instance-sizes.yaml
invalid database reference	确认数据库名称匹配
routes is deprecated	使用 ingress.rules

---

实例规格

标识符	CPU	内存	价格	用例
apps-s-1vcpu-0.5gb	1 个共享	512 MiB	$5/mo	工作进程、作业
apps-s-1vcpu-1gb	1 个共享	1 GiB	$12/mo	默认
apps-d-1vcpu-2gb	1 个专用	2 GiB	$39/mo	生产环境

**完整列表：**参见 shared/instance-sizes.yaml

---

参考文件

• component-types.md — 服务、工作进程、作业、静态站点
• architecture-patterns.md — 全部 5 种模式及其 YAML
• environment-variables.md — 作用范围、类型、占位符
• deploy-to-do-button.md — 模板转换、按钮 HTML
• database-configuration.md — 开发与托管、可绑定变量

---

共享参考资料

• AppSpec-Reference.md — 字段级语法、约束
• instance-sizes.yaml — 所有实例规格和价格
• regions.yaml — 可用区域
• bindable-variables.md — 所有可绑定变量模式

---

与其他技能集成

• → deployment：通过 GitHub Actions 部署生成的应用规范
• → devcontainers：创建与生产环境一致的本地开发环境
• → postgres：高级数据库配置
• → networking：自定义域名、CORS、VPC
• → migration：从其他平台迁移