speccore 8.3.290 → 8.3.296

package/templates/deploy-docker/README.md

@@ -0,0 +1,296 @@
+# Docker 部署指南
+
+> 本目录提供前后端 Docker 部署的模板和示例，涵盖本地构建、镜像仓库推送、远程服务器拉取运行全流程。
+
+---
+
+## 目录结构
+
+```
+deploy-docker/
+├── frontend.Dockerfile      # 前端 Nginx 多阶段构建示例
+├── backend-node.Dockerfile  # Node.js 后端多阶段构建示例（Express/NestJS/Koa）
+├── nginx.conf               # Nginx 自定义配置（SPA 路由 + API 代理 + 静态缓存）
+├── docker-compose.yml       # 前后端 + MySQL + Redis 编排示例
+├── deploy-remote.sh         # 服务器端 Docker 部署脚本
+└── README.md                # 本文件
+```
+
+> Java 后端 Dockerfile 见 `templates/deploy-java/Dockerfile`；
+> 纯服务器 Nginx 站点配置（非容器）见 `templates/deploy-nginx/nginx-site.conf`。
+
+---
+
+## 核心问题解答
+
+### Q1: Docker 部署是否需要上传文件？
+
+**不需要传统意义上的 SCP 文件上传**，但有三种等价的"文件传输"方式：
+
+| 方式 | 说明 | 适用场景 |
+|------|------|----------|
+| **镜像仓库**（推荐） | `docker build` → `docker push` → 远程 `docker pull` | 有私有 registry（Harbor/Nexus/阿里云 ACR） |
+| **docker save + scp** | `docker save` 导出 tar → scp 到服务器 → `docker load` | 无 registry 的内网环境 |
+| **远程 build** | SSH 到服务器，在服务器上 `docker build` | 服务器性能强于本地 |
+
+speccore `docker` 类型默认采用**镜像仓库方式**（推荐）。
+
+### Q2: 远程服务器上如何部署？
+
+speccore `docker` 类型现已支持 `host` 字段，部署流程如下：
+
+```yaml
+deploy:
+  staging:
+    type: docker
+    dockerfile: ./Dockerfile
+    registry: registry.example.com      # 镜像仓库（远程部署必填）
+    image: my-project/order-service
+    tag: staging
+    host: deployer@staging-server.com   # 远程服务器（新增支持）
+    key: ~/.ssh/id_rsa
+    # script: 自定义远程命令（可选，默认执行 pull → stop → rm → run）
+```
+
+执行流程：
+1. **本地** `docker build`
+2. **本地** `docker push registry.example.com/my-project/order-service:staging`
+3. **SSH 远程** `docker pull && docker stop && docker rm && docker run`
+
+### Q3: 前端 + 后端都有 Docker，怎么一起部署？
+
+**方式 A：分别部署（推荐，解耦前后端发布节奏）**
+
+```yaml
+# PROJECT.yaml
+platforms:
+  - name: admin-web
+    type: frontend
+    code_path: ./admin-web
+    deploy:
+      staging:
+        type: docker
+        dockerfile: ./Dockerfile
+        registry: registry.example.com
+        image: my-project/admin-web
+        tag: staging
+        host: deployer@staging-server.com
+        key: ~/.ssh/id_rsa
+        # 自定义端口映射
+        script: "docker pull registry.example.com/my-project/admin-web:staging && docker stop admin-web 2>/dev/null; docker rm admin-web 2>/dev/null; docker run -d --name admin-web --restart always -p 80:80 registry.example.com/my-project/admin-web:staging"
+
+  - name: order-service
+    type: backend
+    code_path: ./order-service
+    deploy:
+      staging:
+        type: docker
+        dockerfile: ./Dockerfile
+        registry: registry.example.com
+        image: my-project/order-service
+        tag: staging
+        host: deployer@staging-server.com
+        key: ~/.ssh/id_rsa
+        script: "docker pull registry.example.com/my-project/order-service:staging && docker stop order-service 2>/dev/null; docker rm order-service 2>/dev/null; docker run -d --name order-service --restart always -p 8080:8080 registry.example.com/my-project/order-service:staging"
+```
+
+分别执行：
+```bash
+speccore deploy --env staging --platform admin-web
+speccore deploy --env staging --platform order-service
+```
+
+**方式 B：Docker Compose 统一部署**
+
+将 `docker-compose.yml` 放到服务器，speccore 负责 push 镜像，服务器端执行 compose：
+
+```yaml
+# PROJECT.yaml
+platforms:
+  - name: fullstack
+    type: infra
+    code_path: ./infra/docker
+    deploy:
+      staging:
+        type: script
+        script: ./scripts/deploy-compose.sh
+```
+
+```bash
+# scripts/deploy-compose.sh（在服务器上执行）
+docker-compose -f /opt/deploy/docker-compose.yml pull
+docker-compose -f /opt/deploy/docker-compose.yml up -d
+```
+
+---
+
+## 各文件说明
+
+### frontend.Dockerfile
+
+前端多阶段构建：
+- **阶段 1**（Node）：`npm ci && npm run build`
+- **阶段 2**（Nginx）：托管 `dist/` 静态资源
+
+支持通过 `BUILD_ENV` 构建参数切换环境：
+```bash
+docker build --build-arg BUILD_ENV=staging -t admin-web:staging .
+```
+
+### backend-node.Dockerfile
+
+Node.js 后端多阶段构建（Express / NestJS / Koa）：
+- **阶段 1**（Node）：`npm ci && npm run build`
+- **阶段 2**（Node）：仅生产依赖 + `dist/`，非 root 用户运行
+
+内置健康检查（`/healthz`，按实际路由调整），与 docker-compose 的 healthcheck 联动。
+
+### nginx.conf
+
+- SPA 路由回退（`try_files`）
+- 静态资源长期缓存
+- `/api/` 代理到后端容器
+
+### docker-compose.yml
+
+完整编排示例，包含：
+- `frontend`（Nginx）
+- `backend`（Spring Boot / Node）
+- `mysql`（数据库，可选）
+- `redis`（缓存，可选）
+
+通过 `.env` 文件注入敏感配置：
+```bash
+# .env
+REGISTRY=registry.example.com
+TAG=staging
+PROFILE=staging
+DB_PASSWORD=your-db-pass
+REDIS_PASSWORD=your-redis-pass
+```
+
+### deploy-remote.sh
+
+服务器端容器管理脚本：
+- 拉取最新镜像
+- 停止并删除旧容器
+- 清理旧镜像（保留最近 3 个标签）
+- 启动新容器
+- 状态检查
+
+---
+
+## 快速开始
+
+### 场景 1：前端 Docker 部署到远程服务器
+
+```bash
+# 1. 复制 Dockerfile
+cp templates/deploy-docker/frontend.Dockerfile admin-web/Dockerfile
+cp templates/deploy-docker/nginx.conf admin-web/nginx.conf
+
+# 2. 配置 PROJECT.yaml
+#    type: docker, host: 服务器地址, registry: 镜像仓库
+
+# 3. 部署
+speccore deploy --env staging --platform admin-web
+```
+
+### 场景 2：后端 Java Docker 部署
+
+见 `templates/deploy-java/Dockerfile`（已包含多阶段构建）。
+
+### 场景 3：前后端 + 数据库一次性启动
+
+```bash
+# 在服务器上
+scp templates/deploy-docker/docker-compose.yml deployer@server:/opt/deploy/
+scp templates/deploy-docker/.env deployer@server:/opt/deploy/
+
+ssh deployer@server "cd /opt/deploy && docker-compose up -d"
+```
+
+---
+
+## 数据库 / Redis 配置
+
+### 方式 1：独立数据库（推荐生产环境）
+
+数据库和 Redis 由运维独立维护，应用通过环境变量连接：
+
+```yaml
+# docker-compose.yml 中 backend 的 environment
+- DB_HOST=prod-mysql.internal
+- DB_PORT=3306
+- DB_NAME=order_db
+- DB_USER=order_user
+- DB_PASS=${DB_PASSWORD}
+- REDIS_HOST=prod-redis.internal
+- REDIS_PORT=6379
+```
+
+### 方式 2：Docker Compose 内置数据库（推荐测试环境）
+
+直接使用 `docker-compose.yml` 中的 `mysql` 和 `redis` 服务，应用通过服务名连接：
+
+```yaml
+# backend 的 environment
+- DB_HOST=mysql      # Docker 网络内服务名即主机名
+- REDIS_HOST=redis
+```
+
+### 方式 3：Spring Boot 多环境配置
+
+```yaml
+# src/main/resources/application-staging.yml
+spring:
+  datasource:
+    url: jdbc:mysql://${DB_HOST:mysql}:${DB_PORT:3306}/${DB_NAME:order_db}
+    username: ${DB_USER:root}
+    password: ${DB_PASS:}
+  data:
+    redis:
+      host: ${REDIS_HOST:redis}
+      port: ${REDIS_PORT:6379}
+      password: ${REDIS_PASS:}
+```
+
+---
+
+## 常见问题
+
+**Q: 没有镜像仓库怎么办？**
+
+使用 `docker save + scp + docker load`：
+
+```bash
+# 本地
+docker build -t order-service:staging .
+docker save order-service:staging | gzip > order-service-staging.tar.gz
+scp order-service-staging.tar.gz deployer@server:/tmp/
+
+# 远程
+ssh deployer@server "gunzip -c /tmp/order-service-staging.tar.gz | docker load"
+ssh deployer@server "docker stop order-service; docker rm order-service; docker run -d --name order-service -p 8080:8080 order-service:staging"
+```
+
+或改用 `script` 类型，将上述命令写入脚本由 speccore 执行。
+
+**Q: 如何查看远程容器日志？**
+
+```bash
+ssh deployer@server "docker logs -f order-service --tail 100"
+```
+
+**Q: 如何回滚？**
+
+```bash
+# 重新部署上一个标签
+speccore deploy --env staging --platform order-service --skip-build
+# 然后手动在服务器上 docker run 指定旧标签
+```
+
+或保留多个标签版本：
+```bash
+ssh deployer@server "docker stop order-service; docker rm order-service; docker run -d --name order-service order-service:v1.2.3"
+```

package/templates/deploy-docker/backend-node.Dockerfile

@@ -0,0 +1,52 @@
+# ═══════════════════════════════════════════════════════════
+# Node.js 后端 Docker 多阶段构建示例（Express / NestJS / Koa）
+# ═══════════════════════════════════════════════════════════
+#
+# 用法：
+#   1. 将本文件复制到后端工程根目录，重命名为 Dockerfile
+#   2. 在 PROJECT.yaml 中配置 docker 类型部署：
+#        type: docker
+#        dockerfile: ./Dockerfile
+#        registry: <镜像仓库>
+#        image: <镜像名>
+#        tag: staging
+#   3. 执行: speccore deploy --env staging --platform <后端端名>
+#
+# 多阶段构建：Node 编译 → 精简运行镜像
+# ═══════════════════════════════════════════════════════════
+
+# ── 阶段 1：依赖安装 + 构建 ──
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+# 先复制依赖文件（利用 Docker 缓存层）
+COPY package*.json ./
+RUN npm ci
+
+# 复制源码并构建
+COPY . .
+RUN npm run build
+
+# ── 阶段 2：运行（只装生产依赖，镜像更小）──
+FROM node:20-alpine
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+# 复制依赖与构建产物
+COPY --from=builder /app/package*.json ./
+RUN npm ci --omit=dev
+COPY --from=builder /app/dist ./dist
+
+# 非 root 用户运行（安全最佳实践）
+RUN addgroup -S app && adduser -S app -G app
+USER app
+
+# 健康检查（按实际端口调整，Express 项目可用 /healthz 路由）
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/healthz || exit 1
+
+EXPOSE 3000
+
+# 启动命令（按实际入口调整，如 dist/main.js、dist/server.js）
+CMD ["node", "dist/main.js"]

package/templates/deploy-docker/deploy-remote.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════
+# Docker 远程部署脚本（服务器端执行）
+# ═══════════════════════════════════════════════════════════
+#
+# 用法：
+#   ./deploy-remote.sh <image> <container-name> [run-args]
+#
+# 示例：
+#   ./deploy-remote.sh registry.example.com/order-service:staging order-service "-p 8080:8080 -e SPRING_PROFILES_ACTIVE=staging"
+#
+# 该脚本用于服务器端手动更新容器，也可作为 speccore deploy script 的远程命令。
+# ═══════════════════════════════════════════════════════════
+
+set -euo pipefail
+
+IMAGE="${1:-}"
+NAME="${2:-}"
+RUN_ARGS="${3:-}"
+
+if [ -z "$IMAGE" ] || [ -z "$NAME" ]; then
+  echo "用法: $0 <image> <container-name> [run-args]"
+  echo "示例: $0 registry.example.com/order-service:staging order-service \"-p 8080:8080\""
+  exit 1
+fi
+
+echo "========================================"
+echo "Docker 远程部署"
+echo "镜像: $IMAGE"
+echo "容器: $NAME"
+echo "========================================"
+
+# ── 1. 拉取最新镜像 ──
+echo "📥 拉取镜像..."
+docker pull "$IMAGE"
+
+# ── 2. 停止并删除旧容器 ──
+if docker ps -a --format '{{.Names}}' | grep -q "^${NAME}$"; then
+  echo "🛑 停止旧容器: $NAME"
+  docker stop "$NAME" || true
+  echo "🗑️  删除旧容器: $NAME"
+  docker rm "$NAME" || true
+else
+  echo "ℹ️ 无旧容器需要清理"
+fi
+
+# ── 3. 清理旧镜像（保留最近 3 个标签） ──
+echo "🧹 清理旧镜像..."
+IMAGE_BASE=$(echo "$IMAGE" | cut -d: -f1)
+docker images "$IMAGE_BASE" --format '{{.Repository}}:{{.Tag}}' | tail -n +4 | xargs -r docker rmi || true
+
+# ── 4. 启动新容器 ──
+echo "🚀 启动新容器..."
+if [ -n "$RUN_ARGS" ]; then
+  # shellcheck disable=SC2086
+  docker run -d --name "$NAME" --restart always $RUN_ARGS "$IMAGE"
+else
+  docker run -d --name "$NAME" --restart always "$IMAGE"
+fi
+
+# ── 5. 等待并检查状态 ──
+echo "⏳ 等待容器启动..."
+sleep 3
+
+if docker ps --format '{{.Names}}' | grep -q "^${NAME}$"; then
+  echo "✅ 容器已启动: $NAME"
+else
+  echo "❌ 容器启动失败"
+  echo "📋 日志:"
+  docker logs "$NAME" --tail 50 || true
+  exit 1
+fi
+
+# ── 6. 显示状态 ──
+echo ""
+echo "========================================"
+echo "📋 部署完成"
+echo "========================================"
+docker ps --filter "name=$NAME" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

package/templates/deploy-docker/docker-compose.yml

@@ -0,0 +1,113 @@
+# ═══════════════════════════════════════════════════════════
+# 前后端 Docker Compose 编排示例
+# ═══════════════════════════════════════════════════════════
+#
+# 适用场景：一台服务器上同时部署前端 + 后端 + 数据库/Redis
+#
+# 用法：
+#   1. 将本文件复制到服务器上的部署目录
+#   2. 配置 .env 文件（数据库密码等敏感信息）
+#   3. 执行: docker-compose up -d
+#
+# 与 speccore deploy 结合：
+#   - speccore 负责 build && push 镜像
+#   - 服务器端手动或通过 CI 执行 docker-compose pull && up -d
+#   - 也可将 docker-compose 作为 speccore 的 script 部署方式执行
+# ═══════════════════════════════════════════════════════════
+
+version: "3.8"
+
+services:
+  # ── 前端 ──
+  frontend:
+    image: ${REGISTRY:-registry.example.com}/my-project/admin-web:${TAG:-staging}
+    container_name: admin-web
+    restart: unless-stopped
+    ports:
+      - "80:80"
+    networks:
+      - app-network
+    depends_on:
+      - backend
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 10s
+
+  # ── 后端 ──
+  backend:
+    image: ${REGISTRY:-registry.example.com}/my-project/order-service:${TAG:-staging}
+    container_name: order-service
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    environment:
+      - SPRING_PROFILES_ACTIVE=${PROFILE:-staging}
+      - JAVA_OPTS=-Xms512m -Xmx1024m
+      # 数据库连接（建议通过 .env 或 Docker Secrets 注入密码）
+      - DB_HOST=mysql
+      - DB_PORT=3306
+      - DB_NAME=order_db
+      - DB_USER=root
+      - DB_PASS=${DB_PASSWORD:-secret}
+      # Redis 连接
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - REDIS_PASS=${REDIS_PASSWORD:-}
+    networks:
+      - app-network
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_started
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/actuator/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+
+  # ── MySQL（如需内置数据库，否则删除此段） ──
+  mysql:
+    image: mysql:8.0
+    container_name: mysql
+    restart: unless-stopped
+    environment:
+      - MYSQL_ROOT_PASSWORD=${DB_PASSWORD:-secret}
+      - MYSQL_DATABASE=order_db
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql-data:/var/lib/mysql
+      # - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # ── Redis（如需内置缓存，否则删除此段） ──
+  redis:
+    image: redis:7-alpine
+    container_name: redis
+    restart: unless-stopped
+    command: redis-server --requirepass ${REDIS_PASSWORD:-}
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    networks:
+      - app-network
+
+networks:
+  app-network:
+    driver: bridge
+
+volumes:
+  mysql-data:
+  redis-data:

package/templates/deploy-docker/frontend.Dockerfile

@@ -0,0 +1,43 @@
+# ═══════════════════════════════════════════════════════════
+# 前端 Docker 构建示例（Nginx 多阶段构建）
+# ═══════════════════════════════════════════════════════════
+#
+# 用法：
+#   1. 将本文件复制到前端工程根目录
+#   2. 如有自定义 nginx 配置，一并复制 nginx.conf 到同目录
+#   3. 在 PROJECT.yaml 中配置 docker 类型部署
+#   4. 执行: speccore deploy --env staging --platform admin-web
+#
+# 多阶段构建：Node 编译 → Nginx 托管静态资源
+# ═══════════════════════════════════════════════════════════
+
+# ── 阶段 1：构建 ──
+FROM node:18-alpine AS builder
+WORKDIR /app
+
+# 先复制依赖文件（利用 Docker 缓存层）
+COPY package*.json ./
+RUN npm ci
+
+# 复制源码并构建
+COPY . .
+ARG BUILD_ENV=staging
+RUN npm run build:$BUILD_ENV
+
+# ── 阶段 2：运行 ──
+FROM nginx:alpine
+WORKDIR /usr/share/nginx/html
+
+# 复制构建产物
+COPY --from=builder /app/dist .
+
+# 复制自定义 nginx 配置（可选，没有则使用 Nginx 默认配置）
+# COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost/ || exit 1
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]

package/templates/deploy-docker/nginx.conf

@@ -0,0 +1,30 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # 前端路由支持（SPA 应用）
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # 静态资源缓存
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # API 代理到后端（按需配置）
+    location /api/ {
+        proxy_pass http://backend:8080/api/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    # 禁止访问隐藏文件
+    location ~ /\. {
+        deny all;
+    }
+}