vibe_coding/docs/runbooks/deployment.md

🚢 Deployment Runbook

PHP Hyperf + Swoole + Vue 3 部署流程指南

---

环境

环境	URL	触发
Development	localhost:8200 (前端) / localhost:9501 (后端)	本地开发
Staging	staging.example.com	merge to develop
Production	www.example.com	merge to main

Docker Compose 模板

version: '3.8'

services:
  # Nginx — 负载均衡 + 静态资源 + SSL
  nginx:
    image: nginx:1.25-alpine
    container_name: app_nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./docker/nginx/conf.d:/etc/nginx/conf.d
      - ./Case-Database-Frontend-user/dist:/usr/share/nginx/html/user
      - ./Case-Database-Frontend-admin/dist:/usr/share/nginx/html/admin
      - ./docker/nginx/ssl:/etc/nginx/ssl
    depends_on:
      - hyperf
    networks:
      - app_network
    restart: unless-stopped

  # Hyperf — PHP 8.1 + Swoole (HTTP + WebSocket)
  hyperf:
    build:
      context: ./Case-Database-Backend
      dockerfile: Dockerfile
    container_name: app_backend
    ports:
      - "9501:9501"   # HTTP API
      - "9502:9502"   # WebSocket
    volumes:
      - ./Case-Database-Backend:/opt/www
    environment:
      - APP_ENV=${APP_ENV:-production}
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_DATABASE=${DB_DATABASE}
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_AUTH=${REDIS_AUTH}
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app_network
    restart: unless-stopped

  # MySQL 8.1 — 主数据库
  mysql:
    image: mysql:8.1
    container_name: app_mysql
    ports:
      - "${DB_PORT:-3307}:3306"
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: ${DB_DATABASE}
      MYSQL_USER: ${DB_USERNAME}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
      - ./docker/mysql/conf.d:/etc/mysql/conf.d
      - ./docker/mysql/init:/docker-entrypoint-initdb.d
    command: >
      --default-authentication-plugin=caching_sha2_password
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --max-connections=500
      --innodb-buffer-pool-size=1G
      --slow-query-log=ON
      --long-query-time=1
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app_network
    restart: unless-stopped

  # Redis 7 — 缓存 + 队列 + Session
  redis:
    image: redis:7.2-alpine
    container_name: app_redis
    ports:
      - "${REDIS_PORT:-6379}:6379"
    command: redis-server --requirepass ${REDIS_AUTH} --maxmemory 512mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_AUTH}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app_network
    restart: unless-stopped

volumes:
  mysql_data:
    driver: local
  redis_data:
    driver: local

networks:
  app_network:
    driver: bridge

Backend Dockerfile

FROM hyperf/hyperf:8.1-alpine-v3.18-swoole

LABEL maintainer="Enterprise Digital Platform"

ENV TIMEZONE=Asia/Shanghai
ENV APP_ENV=production

WORKDIR /opt/www

COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-scripts

COPY . .
RUN composer dump-autoload -o

EXPOSE 9501 9502

ENTRYPOINT ["php", "/opt/www/bin/hyperf.php", "start"]

部署检查清单

部署前

• 所有后端测试通过 (composer test)
• 所有前端测试通过 (npm test)
• 代码审查已批准
• 数据库迁移已准备 (php bin/hyperf.php migrate:status)
• 环境变量已配置 (.env)
• Redis 连接正常
• 静态分析通过 (composer analyse)

部署步骤

# 1. 拉取最新代码
git pull origin main

# 2. 后端依赖更新
cd Case-Database-Backend && composer install --no-dev -o

# 3. 数据库迁移
php bin/hyperf.php migrate

# 4. 前端构建
cd Case-Database-Frontend-user && npm ci && npm run build
cd ../Case-Database-Frontend-admin && npm ci && npm run build

# 5. 重启服务
docker-compose restart hyperf
docker-compose restart nginx

# 6. 验证
curl -s https://your-domain.com/admin/health | jq

部署后

• 健康检查通过
• 监控无异常 (CPU/内存/连接数)
• 数据库迁移成功
• WebSocket 连接正常
• 队列消费进程运行中

回滚

# 代码回滚
git revert HEAD
git push origin main

# 数据库回滚
php bin/hyperf.php migrate:rollback --step=1

# Docker 容器回滚到上一个镜像
docker-compose pull hyperf
docker-compose up -d hyperf

扩展到多实例

# 水平扩展 Hyperf 实例
docker-compose up -d --scale hyperf=3

# Nginx upstream 配置多后端
upstream hyperf_cluster {
    server hyperf_1:9501;
    server hyperf_2:9501;
    server hyperf_3:9501;
}

---

最后更新: YYYY-MM-DD