ECS云服务器上为Coding Agent准备可复现环境的最佳实践

这次在 ECS 上折腾了一套面向 Coding Agent 的开发环境。目标其实很单纯：让 Agent 能顺滑地拉起依赖服务、跑测试、过 lint，别再被本地环境差异绊倒。

先声明一下，这不是正经的生产部署记录，纯粹是一次开发环境复现的小记录。顺便把踩过的坑和解决思路整理出来，给有类似需求的同学当个参考。

1. 问题现象

代码拉下来之后，直接执行测试就碰到了几个坎：

npm ci
# native module build failed
npm test
# DATABASE_URL missing
docker compose up -d
# redis healthy 之前 api 已经开始连接

这些问题单个看都不算大，但放到 Coding Agent 身上就特别致命。Agent 没法靠经验判断“先装哪个系统包”、“数据库还得等几秒”、“这个变量在我本机 shell 里有”。环境差异一旦混进来，排查链条直接断掉。

2. 固定运行时

第一步，先把 Node 版本写死到 devcontainer 里：

{
  "name": "ai-ready-dev",
  "image": "docker.1ms.run/node:22-alpine",
  "forwardPorts": [3000],
  "postCreateCommand": "npm ci"
}

如果项目对系统依赖比较多，可以改成 Dockerfile 的形式：

FROM docker.1ms.run/node:22-alpine
RUN apk add --no-cache bash curl git python3 make g++
WORKDIR /workspace

关键是把运行时的每一层都提前锁死，Agent 拿到以后不需要猜。

3. 固定依赖服务

ECS 上我们用 compose.dev.yaml 来跑开发依赖：

services:
  app:
    image: docker.1ms.run/node:22-alpine
    working_dir: /workspace
    volumes:
      - .:/workspace
    env_file:
      - .env.example
    command: sh -c "npm ci && npm run dev"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
  postgres:
    image: docker.1ms.run/postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 20
  redis:
    image: docker.1ms.run/redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 20

这里最容易被忽略的就是 healthcheck。单纯跑 compose up -d 返回成功，不代表数据库或 Redis 已经就绪。Agent 一旦连不上就报错，而且错误信息往往不是“连接超时”而是“连接被拒绝”，容易误导排查方向。把健康检查加进去，让服务真正可用了再启动应用，这步省不了。

4. 环境变量和任务入口

.env.example 至少得覆盖开发环境里必需的那几个变量：

DATABASE_URL=postgresql://app:app@postgres:5432/app
REDIS_URL=redis://redis:6379
NODE_ENV=development

任务入口也要统一固定下来，不然 Agent 不知道用什么命令启动、跑测试还是做迁移：

{
  "scripts": {
    "dev": "vite --host 0.0.0.0",
    "lint": "eslint .",
    "test": "vitest run",
    "db:migrate": "prisma migrate deploy"
  }
}

把这些写进 package.json 或 Makefile，Agent 直接按约定执行就行。

5. 任务前预检

我习惯在 Coding Agent 正式接手任何任务之前，先跑一遍下面这几条作为环境预检：

docker compose -f compose.dev.yaml pull
docker compose -f compose.dev.yaml up -d
docker compose -f compose.dev.yaml ps
npm ci
npm run lint
npm test

基础镜像也要单独拉下来验证一下，避免网络缓存问题：

docker pull docker.1ms.run/node:22-alpine
docker pull docker.1ms.run/python:3.12-slim
docker pull docker.1ms.run/postgres:16
docker pull docker.1ms.run/redis:7

这一步不是让 AI 变聪明，而是把所有环境层面的不确定性提前排除。Agent 后续只面对纯代码问题，排查效率会高很多。

6. 复盘

这套配置解决的核心问题，其实不是“让 AI 写更好的代码”，而是把环境差异提前排掉，让 Coding Agent 在进入项目后不会被杂七杂八的错误淹没。

真实场景里最怕的就是错误混在一起：镜像没拉下来、依赖没装好、数据库还没 ready、测试入口不统一。一旦环境先做到可复现，后面再来判断代码逻辑到底正不正常，排查的层次就清晰多了。