diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..50632a3
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,23 @@
+# cryptoHermes 部署变量
+# 复制本文件到 .env 然后按需修改
+# .env 不入库（.gitignore 已忽略）；.env.example 入库给团队作模板
+
+# ---- Postgres ----
+# 强密码必须在生产环境覆盖
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=hermes_market
+POSTGRES_PORT=5432
+
+# ---- App ----
+APP_PORT=8080
+APP_ENV=production
+
+# ---- Binance ----
+BINANCE_BASE_URL=https://fapi.binance.com
+
+# ---- 国内网络代理（如不需要可留空）----
+# 例如 http://host.docker.internal:7890
+HTTP_PROXY=
+HTTPS_PROXY=
+NO_PROXY=localhost,127.0.0.1,postgres,crypto-hermes-postgres
diff --git a/docker-compose.yml b/docker-compose.yml
index d4448ce..5a72253 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -3,26 +3,61 @@ services:
     image: timescale/timescaledb:latest-pg16
     container_name: crypto-hermes-postgres
     environment:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: hermes_market
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set, see .env.example}
+      POSTGRES_DB: ${POSTGRES_DB:-hermes_market}
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     volumes:
       - hermes_pg_data:/var/lib/postgresql/data
+    healthcheck:
+      # 用 pg_isready 探测，避免 init 期 race
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-hermes_market}"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 10s
+
+  # init container：跑完 migration 立即退出。
+  # 由 app 依赖它 service_completed_successfully，保证表存在再启动 app。
+  migrate:
+    image: migrate/migrate:v4.18.1
+    container_name: crypto-hermes-migrate
+    depends_on:
+      postgres:
+        condition: service_healthy
+    volumes:
+      - ./migrations:/migrations:ro
+    command:
+      - -path=/migrations
+      - -database=postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-hermes_market}?sslmode=disable
+      - up
+    restart: "no"
 
   app:
-    build: .
+    build:
+      context: .
+      dockerfile: Dockerfile
     container_name: crypto-hermes-market-gateway
     depends_on:
-      - postgres
+      postgres:
+        condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
     ports:
-      - "8080:8080"
+      - "${APP_PORT:-8080}:8080"
     environment:
       CONFIG_PATH: /app/config/config.yml
-      POSTGRES_DSN: postgres://postgres:postgres@crypto-hermes-postgres:5432/hermes_market?sslmode=disable
+      APP_ENV: ${APP_ENV:-production}
+      APP_PORT: ${APP_PORT:-8080}
+      POSTGRES_DSN: postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-hermes_market}?sslmode=disable
+      BINANCE_BASE_URL: ${BINANCE_BASE_URL:-https://fapi.binance.com}
+      # 透传代理：国内直连 fapi.binance.com 不稳，详见 AGENTS.md §7.5
+      HTTP_PROXY: ${HTTP_PROXY:-}
+      HTTPS_PROXY: ${HTTPS_PROXY:-}
+      NO_PROXY: ${NO_PROXY:-}
     volumes:
-      - ./config:/app/config
+      - ./config:/app/config:ro
 
 volumes:
   hermes_pg_data: