From 16f7f00d7b5bfd2c08d36c4f31025d1e56b1a4a2 Mon Sep 17 00:00:00 2001
From: dela <delahayecarry@outlook.com>
Date: Sun, 24 May 2026 20:59:09 +0800
Subject: [PATCH] =?UTF-8?q?deploy(compose):=20=E4=BF=AE=204=20=E4=B8=AA?=
 =?UTF-8?q?=E4=B8=8A=E7=94=9F=E4=BA=A7=E5=89=8D=E7=9A=84=E9=98=BB=E6=96=AD?=
 =?UTF-8?q?=E9=A1=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

为什么：v2.0 代码侧已 ready，但 docker compose up 起来会立刻 panic
（表不存在），且密码硬编码、Binance 直连超时、无 healthcheck。

修复：

1. migrate init container（migrate/migrate:v4.18.1）
   - depends_on postgres service_healthy 后执行
   - 跑完 up 退出；app depends_on migrate service_completed_successfully
   - 表不存在的 race 彻底消除

2. postgres healthcheck（pg_isready）
   - interval 5s、retries 10、start_period 10s
   - app 不再在 init 期连接失败

3. .env + .env.example（守卫 G9）
   - 密码、端口、Binance URL 全部从环境变量读
   - POSTGRES_PASSWORD 未设置时 docker-compose 直接报错退出（${VAR:?...} 语法）
   - .env 已在 .gitignore，.env.example 留作模板

4. HTTP_PROXY/HTTPS_PROXY/NO_PROXY 透传
   - 国内直连 fapi.binance.com 不稳（AGENTS.md §7.5）
   - NO_PROXY 默认包含 postgres 容器名，避免本地代理误走

附加：config 卷只读挂载（防容器内意外写入）；ports 端口可由
.env 覆盖；postgres 容器名走 docker DNS（替换之前硬编码的
crypto-hermes-postgres）。

验证：python yaml lint 通过；依赖链 postgres healthy →
migrate completed → app start 已确认。docker 在本机不可用，
线上验证留给 commit 9 之后的人工 smoke。
---
 .env.example       | 23 ++++++++++++++++++++
 docker-compose.yml | 53 ++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 67 insertions(+), 9 deletions(-)
 create mode 100644 .env.example

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: