Document Docker Compose deployment workflow

README.md

@@ -43,6 +43,60 @@ pnpm dev
 
 后端热更新可通过 `GO_WATCH_SHUTDOWN_GRACE_MS` 和 `GO_WATCH_RESTART_DELAY_MS` 调整旧进程退出等待时间与重启间隔。
 
+## Docker Compose 一键部署
+
+仓库内提供了面向 `linux/amd64` 的 Docker Compose 构建和部署脚本，会自动构建 API/Web 镜像、启动 PostgreSQL、执行数据库迁移，并验证 API 与 Web 是否可访问：
+
+```bash
+scripts/deploy-compose.sh
+```
+
+部署成功后默认访问地址：
+
+- Web: `http://127.0.0.1:5178`
+- API: `http://127.0.0.1:8088/healthz`
+- Web 反代 API: `http://127.0.0.1:5178/gateway-api/healthz`
+
+常用覆盖项：
+
+```bash
+AI_GATEWAY_IMAGE_TAG=2026.05.23-1 scripts/deploy-compose.sh
+AI_GATEWAY_IMAGE_TAG=2026.05.23-1 AI_GATEWAY_PUSH=1 scripts/deploy-compose.sh
+AI_GATEWAY_IMAGE_TAG=2026.05.23-1 scripts/deploy-compose.sh push
+AI_GATEWAY_WEB_PORT=8080 AI_GATEWAY_API_PORT=18088 scripts/deploy-compose.sh
+AI_GATEWAY_GO_PROXY='https://proxy.golang.org,direct' scripts/deploy-compose.sh
+AI_GATEWAY_SKIP_BUILD=1 scripts/deploy-compose.sh
+scripts/deploy-compose.sh down
+scripts/deploy-compose.sh clean
+```
+
+默认镜像地址为：
+
+- API: `registry.cn-shanghai.aliyuncs.com/easyaigc/ai-gateway:latest`
+- Web: `registry.cn-shanghai.aliyuncs.com/easyaigc/ai-gateway-web:latest`
+
+执行 `scripts/deploy-compose.sh push` 或设置 `AI_GATEWAY_PUSH=1` 时，会同时推送当前版本 tag 和 `latest`。当前版本 tag 优先使用 `AI_GATEWAY_IMAGE_TAG`；如果没有设置，则使用根 `package.json` 里的 `version`。
+
+推送前需要先登录阿里云镜像仓库：
+
+```bash
+docker login --username=<your-aliyun-account> registry.cn-shanghai.aliyuncs.com
+```
+
+Web 容器的 Nginx 配置通过 bind mount 挂载自仓库文件 [docker/nginx.conf](docker/nginx.conf)，可直接修改该文件调整静态资源和 `/gateway-api` 反向代理配置。修改后执行以下命令使配置生效：
+
+```bash
+docker compose -f docker-compose.yml restart web
+```
+
+Compose 默认使用独立容器数据库 `postgres:18-alpine`，数据卷会保留在 `postgres_data` 和 `api_data`。为避免本地开发 `.env` 中的 `localhost` 数据库地址污染容器部署，compose 使用 `AI_GATEWAY_COMPOSE_*` 变量作为容器部署专用覆盖，例如：
+
+```bash
+AI_GATEWAY_COMPOSE_DATABASE_URL='postgresql://easyai:easyai2025@postgres:5432/easyai_ai_gateway?sslmode=disable' scripts/deploy-compose.sh
+```
+
+数据库迁移仍通过 `migrator` 容器执行，但脚本使用 `docker compose run --rm migrator`，迁移成功后不会留下 `migrator-1 Exited` 容器。
+
 ## OpenAPI 文档
 
 修改 `apps/api/internal/httpapi` 下的接口、请求或响应类型后，请重新执行：