devcontainers

Dev Containers 技能

为 DigitalOcean App Platform 应用设置与生产环境一致的本地开发环境。

核心价值：将 7 分钟的部署周期缩短为 30 秒的反馈循环。

快速决策

What do you need?
├── New project setup → Workflow 1
├── Existing App Platform app → Workflow 2
└── CLI-only testing (no IDE) → See cli-workflow.md

---

快速开始：克隆并复制

# Clone the reference devcontainer
git clone --depth 1 https://github.com/bikramkgupta/do-app-devcontainer.git /tmp/devcontainer-ref

# Copy to your project
cp -r /tmp/devcontainer-ref/.devcontainer /path/to/your-project/

# Clean up
rm -rf /tmp/devcontainer-ref

然后在 .devcontainer/devcontainer.json 中自定义 COMPOSE_PROFILES：

"containerEnv": {
  "COMPOSE_PROFILES": "app,postgres,minio"
}

---

可用配置

配置	服务	适用场景
postgres	PostgreSQL 18	SQL 数据库
mysql	MySQL 8	MySQL 数据库
mongo	MongoDB 8	文档数据库
valkey	Valkey 8	兼容 Redis 的缓存
kafka	Confluent Kafka 7.7	消息流
minio	RustFS	兼容 S3 的存储
opensearch	OpenSearch 3.0	全文搜索

---

连接字符串

服务	连接字符串
PostgreSQL	postgresql://postgres:password@postgres:5432/app
MySQL	mysql://mysql:mysql@mysql:3306/app
MongoDB	mongodb://mongodb:mongodb@mongo:27017/app?authSource=admin
Valkey	redis://valkey:6379
Kafka	kafka:9092
RustFS	http://minio:9000（凭据：rustfsadmin/rustfsadmin）
OpenSearch	http://opensearch:9200

容器内：使用服务名称（例如，postgres:5432） 主机上：使用 docker compose port 查找映射端口

---

工作流 1：新项目设置

触发条件：“我正在使用 [语言] 和 [服务] 构建应用”

1. 从参考仓库复制 .devcontainer/（参见“快速开始”）
2. 根据所需服务设置 COMPOSE_PROFILES
3. 创建包含连接字符串的 env-devcontainer.example
4. 在 VS Code/Cursor 中打开 →“Reopen in Container”

devcontainer.json 模板：

{
  "name": "App Platform Dev Environment",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/app",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/python:1": {},
    "ghcr.io/devcontainers-extra/features/uv:1": {},
    "ghcr.io/devcontainers-extra/features/digitalocean-cli:1": {},
    "ghcr.io/anthropics/devcontainer-features/claude-code:1": {},
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
  },
  "containerEnv": {
    "COMPOSE_PROFILES": "app,postgres"
  },
  "initializeCommand": "cd \"${localWorkspaceFolder}\" && bash .devcontainer/init.sh",
  "postCreateCommand": ".devcontainer/post-create.sh",
  "remoteUser": "vscode",
  "shutdownAction": "stopCompose"
}

---

工作流 2：添加到现有 App Platform 应用

触发条件：“我有一个 App Platform 应用，帮我在本地运行它”

1. 读取 .do/app.yaml 以检测服务
2. 将 App Platform 映射到本地容器：

App Platform	本地配置
databases[].engine: PG	postgres
databases[].engine: MYSQL	mysql
databases[].engine: MONGODB	mongo
databases[].engine: REDIS	valkey
Spaces 附件	minio

3. 生成环境变量映射：

# Production (App Platform injects)
# DATABASE_URL=${db.DATABASE_URL}

# Local Development
DATABASE_URL=postgresql://postgres:password@postgres:5432/app

---

环境模板

# env-devcontainer.example

# Database
DATABASE_URL=postgresql://postgres:password@postgres:5432/app

# Cache
REDIS_URL=redis://valkey:6379

# S3-compatible storage (RustFS)
SPACES_ENDPOINT=http://minio:9000
SPACES_KEY_ID=rustfsadmin
SPACES_SECRET_KEY=rustfsadmin
SPACES_BUCKET_NAME=my-app-local
SPACES_FORCE_PATH_STYLE=true

---

参考仓库提供的内容

.devcontainer/
├── devcontainer.json           # IDE configuration
├── docker-compose.yml          # All 7 backing services
├── init.sh                     # Git worktree support
├── post-create.sh              # Post-creation setup
├── .env                        # Generated (gitignored)
└── tests/                      # Service connectivity tests
    ├── agent-test.sh           # E2E validation
    ├── run-all-tests.sh        # Master test runner
    └── test-*.sh               # Individual service tests

---

测试服务

# Test all running services
.devcontainer/tests/run-all-tests.sh --all

# Test specific services
.devcontainer/tests/run-all-tests.sh postgres minio

# List available tests
.devcontainer/tests/run-all-tests.sh --list

---

健康检查时间

服务	就绪时间
PostgreSQL、MySQL、MongoDB、Valkey、RustFS	<10s
Kafka	60s+（KRaft 初始化）
OpenSearch	30-60s（JVM 预热）

---

快速故障排查

问题	修复方法
端口冲突	配置使用动态端口（127.0.0.1:0:PORT），不应发生冲突
Git 命令失败	重建容器以重新运行 init.sh
Kafka 启动缓慢	等待 60s+，检查：docker compose logs kafka
OpenSearch 内存不足	增加堆内存：OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g
权限被拒绝	运行：sudo chown -R vscode:vscode /home/vscode

---

参考文件

文件	内容
service-templates.md	全部 7 个 docker-compose 服务块
s3-storage-patterns.md	RustFS 设置、本地与生产环境
agent-verification.md	AI Agent 的 CLI 测试工作流
cli-workflow.md	端口转发、环境变量加载、启动
language-configurations.md	Node、Python、Go 热重载配置

---

限制

此技能不处理：

• 云部署 → 使用 deployment 技能
• 生产应用规格 → 使用 designer 技能
• 数据库迁移 → 请自行选择迁移工具
• DigitalOcean Functions → 无法容器化
• SSL/TLS → 本地使用 HTTP；生产环境会自动处理 SSL

---

与其他技能集成

• → designer：本地测试后设计生产应用规范
• → deployment：配置 GitHub Actions CI/CD
• → postgres：配置托管数据库权限
• → troubleshooting：排查生产环境问题

---

外部参考

• VS Code 开发容器
• Docker Compose
• 参考实现