feat: 标准化部署流程和文档化

- 添加 docs/deployment.md 完整部署文档，包含：
  - 环境要求
  - 首次部署流程
  - 版本更新流程
  - 回滚流程
  - 常见问题排查
  - 环境变量说明

- 添加标准化部署脚本：
  - scripts/deploy_production.sh: 生产环境部署脚本
  - scripts/deploy_staging.sh: 预发布环境部署脚本
  - scripts/rollback.sh: 回滚脚本（支持交互式和命令行模式）

- 完善 infra/docker/compose.yml：
  - 添加详细注释说明
  - 添加资源限制建议（注释）
  - 记录 web volume 挂载的注意事项（避免 403 问题）

- 添加 .github/workflows/release.yml：
  - 完整的发布流程
  - 构建所有三个镜像（api、worker、web）
  - 自动部署到生产环境
  - E2E 测试和 GitHub Release 创建

.github/workflows/release.yml

@@ -1,74 +1,414 @@
-name: Release
+# ===========================================
+# 小虾剪辑 SaaS 发布工作流
+# ===========================================
+#
+# 触发条件:
+#   - 推送 v* 格式的 tag (如 v0.1.5)
+#
+# 完整流程:
+#   1. 构建 API + Worker 镜像
+#   2. 构建 Web 镜像
+#   3. 创建 Release
+#   4. 上传到生产服务器
+#   5. 执行部署
+#   6. 运行 E2E 测试
+#
+# 环境变量:
+#   PRODUCTION_SSH_HOST  - 生产服务器地址
+#   PRODUCTION_SSH_USER - 生产服务器用户名
+#   PRODUCTION_SSH_KEY  - SSH 私钥
+#
+
+name: Release Pipeline
 
 on:
   push:
     tags:
       - 'v*'
 
+env:
+  VERSION: ${ { github.ref_name } }
+
 jobs:
+  # =========================================
+  # Job 1: 构建所有镜像
+  # =========================================
+  build-images:
+    name: Build All Images
+    runs-on: runtime-builder:host
+    container: localhost:5000/xiaoxia-ci-python:3.12
+    
+    outputs:
+      version: ${{ env.VERSION }}
+    
+    steps:
+      # 检出代码
+      - name: Checkout code
+        run: |
+          python - <<'PY'
+          import os
+          import tarfile
+          import urllib.request
+
+          api_url = os.environ['GITHUB_API_URL']
+          repository = os.environ['GITHUB_REPOSITORY']
+          sha = os.environ['GITHUB_SHA']
+          token = os.environ.get('GITHUB_TOKEN', '')
+          archive_url = f"{api_url}/repos/{repository}/archive/{sha}.tar.gz"
+          request = urllib.request.Request(archive_url)
+          if token:
+              request.add_header('Authorization', f'token {token}')
+          with urllib.request.urlopen(request, timeout=120) as response:
+              with open('/tmp/repo.tar.gz', 'wb') as archive:
+                  archive.write(response.read())
+          with tarfile.open('/tmp/repo.tar.gz', 'r:gz') as archive:
+              members = archive.getmembers()
+              top_level = members[0].name.split('/')[0] + '/'
+              for member in members:
+                  member.name = member.name.removeprefix(top_level)
+                  if member.name:
+                      archive.extract(member, '.')
+          PY
+
+      # 构建 API 镜像
+      - name: Build API Image
+        run: |
+          VERSION="${{ env.VERSION }}"
+          API_IMAGE="xiaoxia-saas-api:$VERSION"
+          docker build --pull=false \
+            -f infra/docker/api.Dockerfile \
+            -t "$API_IMAGE" \
+            -t "xiaoxia-saas-api:latest" \
+            .
+
+      # 构建 Worker 镜像
+      - name: Build Worker Image
+        run: |
+          VERSION="${{ env.VERSION }}"
+          WORKER_IMAGE="xiaoxia-saas-worker:$VERSION"
+          docker build --pull=false \
+            -f infra/docker/worker.Dockerfile \
+            -t "$WORKER_IMAGE" \
+            -t "xiaoxia-saas-worker:latest" \
+            .
+
+      # 构建 Web 镜像
+      - name: Build Web Image
+        run: |
+          VERSION="${{ env.VERSION }}"
+          # 先构建前端
+          docker run --rm \
+            --pull=never \
+            -v "$PWD:/workspace" \
+            -w /workspace/apps/web \
+            docker.m.daocloud.io/library/node:20 \
+            sh -lc 'npm ci && npm run build'
+          # 构建 Nginx 镜像
+          docker build --pull=false \
+            -f infra/docker/web-artifact.Dockerfile \
+            -t "xiaoxia-saas-web:$VERSION" \
+            .
+
+      # 保存镜像
+      - name: Save Images
+        run: |
+          VERSION="${{ env.VERSION }}"
+          mkdir -p dist/release-images dist/release-artifacts
+          
+          # 保存 API + Worker 镜像
+          docker save \
+            "xiaoxia-saas-api:$VERSION" \
+            "xiaoxia-saas-api:latest" \
+            "xiaoxia-saas-worker:$VERSION" \
+            "xiaoxia-saas-worker:latest" \
+            -o dist/release-images/xiaoxia-runtime-images-$VERSION.tar
+          
+          # 保存 Web 镜像
+          docker save "xiaoxia-saas-web:$VERSION" \
+            -o dist/release-images/xiaoxia-web-$VERSION.tar
+
+      # 上传镜像到构建服务器存储
+      - name: Upload Images Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-images-${{ env.VERSION }}
+          path: dist/release-images/
+          retention-days: 7
+
+  # =========================================
+  # Job 2: 打包源码
+  # =========================================
+  package-source:
+    name: Package Source
+    runs-on: runtime-builder:host
+    
+    needs: build-images
+    
+    steps:
+      - name: Checkout code
+        run: |
+          python - <<'PY'
+          import os
+          import tarfile
+          import urllib.request
+
+          api_url = os.environ['GITHUB_API_URL']
+          repository = os.environ['GITHUB_REPOSITORY']
+          sha = os.environ['GITHUB_SHA']
+          token = os.environ.get('GITHUB_TOKEN', '')
+          archive_url = f"{api_url}/repos/{repository}/archive/{sha}.tar.gz"
+          request = urllib.request.Request(archive_url)
+          if token:
+              request.add_header('Authorization', f'token {token}')
+          with urllib.request.urlopen(request, timeout=120) as response:
+              with open('/tmp/repo.tar.gz', 'wb') as archive:
+                  archive.write(response.read())
+          with tarfile.open('/tmp/repo.tar.gz', 'r:gz') as archive:
+              members = archive.getmembers()
+              top_level = members[0].name.split('/')[0] + '/'
+              for member in members:
+                  member.name = member.name.removeprefix(top_level)
+                  if member.name:
+                      archive.extract(member, '.')
+          PY
+
+      - name: Package Source
+        run: |
+          VERSION="${{ env.VERSION }}"
+          mkdir -p dist/release-artifacts
+          
+          # 排除不需要的文件
+          tar --exclude=.git \
+              --exclude=apps/web/node_modules \
+              --exclude=apps/web/dist \
+              --exclude=dist \
+              --exclude=*.pyc \
+              --exclude=__pycache__ \
+              -czf "dist/release-artifacts/xiaoxia-release-$VERSION.tar.gz" .
+
+      - name: Upload Source Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-source-${{ env.VERSION }}
+          path: dist/release-artifacts/
+          retention-days: 7
+
+  # =========================================
+  # Job 3: 部署到生产环境
+  # =========================================
+  deploy-production:
+    name: Deploy to Production
+    runs-on: runtime-builder:host
+    needs: [build-images, package-source]
+    
+    steps:
+      - name: Download Images
+        uses: actions/download-artifact@v4
+        with:
+          name: release-images-${{ env.VERSION }}
+          path: dist/release-images/
+
+      - name: Download Source
+        uses: actions/download-artifact@v4
+        with:
+          name: release-source-${{ env.VERSION }}
+          path: dist/release-artifacts/
+
+      - name: Upload to Production Server
+        env:
+          PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
+          PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
+          PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+        run: |
+          VERSION="${{ env.VERSION }}"
+          production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
+          production_user="${PRODUCTION_SSH_USER:-root}"
+          
+          mkdir -p ~/.ssh
+          if [ -n "${PRODUCTION_SSH_KEY:-}" ]; then
+            key_path="$HOME/.ssh/id_ed25519"
+            printf '%s\n' "$PRODUCTION_SSH_KEY" > "$key_path"
+            chmod 600 "$key_path"
+          else
+            key_path="/root/.ssh/xiaoxia_runtime_builder"
+          fi
+          
+          ssh-keyscan -H "$production_host" >> ~/.ssh/known_hosts 2>/dev/null || true
+          
+          # 创建目录
+          ssh -i "$key_path" "$production_user@$production_host" \
+            "mkdir -p /var/lib/xiaoxia-saas-production"
+
+      - name: Transfer and Deploy
+        env:
+          PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
+          PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
+          PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+        run: |
+          VERSION="${{ env.VERSION }}"
+          production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
+          production_user="${PRODUCTION_SSH_USER:-root}"
+          
+          if [ -n "${PRODUCTION_SSH_KEY:-}" ]; then
+            key_path="$HOME/.ssh/id_ed25519"
+          else
+            key_path="/root/.ssh/xiaoxia_runtime_builder"
+          fi
+          
+          # 上传镜像
+          scp -i "$key_path" \
+            "dist/release-images/xiaoxia-runtime-images-$VERSION.tar" \
+            "$production_user@$production_host:/var/lib/xiaoxia-saas-production/"
+          
+          scp -i "$key_path" \
+            "dist/release-images/xiaoxia-web-$VERSION.tar" \
+            "$production_user@$production_host:/var/lib/xiaoxia-saas-production/"
+          
+          # 上传源码
+          scp -i "$key_path" \
+            "dist/release-artifacts/xiaoxia-release-$VERSION.tar.gz" \
+            "$production_user@$production_host:/var/lib/xiaoxia-saas-production/"
+
+      - name: Execute Deployment
+        env:
+          PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
+          PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
+          PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+        run: |
+          VERSION="${{ env.VERSION }}"
+          production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
+          production_user="${PRODUCTION_SSH_USER:-root}"
+          
+          if [ -n "${PRODUCTION_SSH_KEY:-}" ]; then
+            key_path="$HOME/.ssh/id_ed25519"
+          else
+            key_path="/root/.ssh/xiaoxia_runtime_builder"
+          fi
+          
+          ssh -i "$key_path" "$production_user@$production_host" <<'REMOTE_DEPLOY'
+          set -eu
+          
+          VERSION="${{ env.VERSION }}"
+          cd /var/lib/xiaoxia-saas-production
+          
+          # 加载镜像
+          docker load -i "runtime-images-$VERSION.tar"
+          docker load -i "web-$VERSION.tar"
+          
+          # 解压源码
+          rm -rf repo
+          mkdir -p repo
+          tar -xzf "release-$VERSION.tar.gz" -C repo
+          
+          # 复制环境文件
+          cp .env repo/.env
+          
+          # 部署
+          cd repo
+          export API_IMAGE="xiaoxia-saas-api:$VERSION"
+          export WORKER_IMAGE="xiaoxia-saas-worker:$VERSION"
+          export WEB_IMAGE="xiaoxia-saas-web:$VERSION"
+          export APP_VERSION="$VERSION"
+          export RELEASE_VERSION="$VERSION"
+          
+          bash infra/docker/deploy-production.sh
+          
+          # 健康检查
+          i=0
+          while [ "$i" -lt 30 ]; do
+            if wget -qO- http://127.0.0.1:8001/health; then
+              echo "Deployment successful!"
+              exit 0
+            fi
+            i=$((i + 1))
+            sleep 2
+          done
+          
+          echo "Health check failed!"
+          exit 1
+          REMOTE_DEPLOY
+
+  # =========================================
+  # Job 4: 运行 E2E 测试
+  # =========================================
+  e2e-test:
+    name: Run E2E Tests
+    runs-on: runtime-builder:host
+    needs: deploy-production
+    
+    steps:
+      - name: Checkout code
+        run: |
+          python - <<'PY'
+          import os
+          import tarfile
+          import urllib.request
+
+          api_url = os.environ['GITHUB_API_URL']
+          repository = os.environ['GITHUB_REPOSITORY']
+          sha = os.environ['GITHUB_SHA']
+          token = os.environ.get('GITHUB_TOKEN', '')
+          archive_url = f"{api_url}/repos/{repository}/archive/{sha}.tar.gz"
+          request = urllib.request.Request(archive_url)
+          if token:
+              request.add_header('Authorization', f'token {token}')
+          with urllib.request.urlopen(request, timeout=120) as response:
+              with open('/tmp/repo.tar.gz', 'wb') as archive:
+                  archive.write(response.read())
+          with tarfile.open('/tmp/repo.tar.gz', 'r:gz') as archive:
+              members = archive.getmembers()
+              top_level = members[0].name.split('/')[0] + '/'
+              for member in members:
+                  member.name = member.name.removeprefix(top_level)
+                  if member.name:
+                      archive.extract(member, '.')
+          PY
+
+      - name: Run Playwright E2E
+        run: |
+          docker run --rm \
+            -e E2E_BASE_URL=https://saas.xiaoxiajianji.com \
+            -e E2E_API_BASE=https://api.xiaoxiajianji.com/api/v1 \
+            -e E2E_BROWSER_CHANNEL=chromium \
+            -v "$PWD:/workspace" \
+            -w /workspace/apps/web \
+            mcr.microsoft.com/playwright:v1.45.0-jammy \
+            sh -lc 'npm ci && npx playwright test --reporter=line --project=chromium e2e/'
+
+  # =========================================
+  # Job 5: 创建 GitHub Release
+  # =========================================
   create-release:
     name: Create Release
     runs-on: ubuntu-latest
+    needs: [deploy-production, e2e-test]
     
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    
-    - name: Generate changelog
-      id: changelog
-      run: |
-        # Extract changelog for this version
-        VERSION=${GITHUB_REF#refs/tags/}
-        echo "version=$VERSION" >> $GITHUB_OUTPUT
-    
-    - name: Create Release
-      uses: actions/create-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      with:
-        tag_name: ${{ github.ref }}
-        release_name: Release ${{ steps.changelog.outputs.version }}
-        body: |
-          See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
-        draft: false
-        prerelease: false
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-  build-and-push:
-    name: Build and Push Docker Image
-    runs-on: ubuntu-latest
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-    
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
-    
-    - name: Log in to Docker Hub
-      uses: docker/login-action@v3
-      with:
-        username: ${{ secrets.DOCKER_USERNAME }}
-        password: ${{ secrets.DOCKER_PASSWORD }}
-    
-    - name: Extract metadata
-      id: meta
-      uses: docker/metadata-action@v5
-      with:
-        images: xiaoxia/saas
-        tags: |
-          type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
-          type=raw,value=latest
-    
-    - name: Build and push
-      uses: docker/build-push-action@v5
-      with:
-        context: .
-        push: true
-        tags: ${{ steps.meta.outputs.tags }}
-        labels: ${{ steps.meta.outputs.labels }}
-        cache-from: type=gha
-        cache-to: type=gha,mode=max
+      - name: Generate Changelog
+        id: changelog
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          # 简单获取 CHANGELOG 中该版本的内容
+          CHANGELOG=$(awk "/^## \[$VERSION\]/,/^## \[/" CHANGELOG.md | head -n -1)
+          echo "body<<EOF" >> $GITHUB_OUTPUT
+          echo "## What's Changed" >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          echo "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          echo "**Full Changelog**: https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: ${{ steps.changelog.outputs.body }}
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/deployment.md

@@ -0,0 +1,386 @@
+# 小虾剪辑 SaaS 部署指南
+
+## 目录
+
+- [环境要求](#环境要求)
+- [首次部署流程](#首次部署流程)
+- [版本更新流程](#版本更新流程)
+- [回滚流程](#回滚流程)
+- [常见问题排查](#常见问题排查)
+- [环境变量说明](#环境变量说明)
+
+---
+
+## 环境要求
+
+### 服务器配置
+
+| 环境 | CPU | 内存 | 磁盘 | 说明 |
+|------|-----|------|------|------|
+| 生产环境 | 4 核+ | 8GB+ | 100GB+ SSD | 推荐 2 核 4GB 的独立数据库服务器 |
+| 预发布环境 | 2 核 | 4GB | 50GB+ | 可与生产环境共用服务器不同端口 |
+
+### 软件要求
+
+- **Docker**: 24.0+
+- **Docker Compose**: 2.20+
+- **操作系统**: Ubuntu 22.04 LTS 或 CentOS 8+
+- **网络**: 开放 80/443 端口（Web），可选开放 8000/8001（API 调试）
+
+### 网络要求
+
+- 服务器可访问外网（下载基础镜像）
+- 数据库和 Redis 端口仅内网访问
+- 域名已配置 DNS 解析
+
+---
+
+## 首次部署流程
+
+### 步骤 1: 准备服务器环境
+
+```bash
+# 安装 Docker
+curl -fsSL https://get.docker.com | sh
+
+# 安装 Docker Compose
+apt-get install docker-compose-plugin
+
+# 验证安装
+docker --version
+docker compose version
+```
+
+### 步骤 2: 创建网络
+
+```bash
+docker network create xiaoxia-net
+```
+
+### 步骤 3: 配置环境变量
+
+```bash
+# 生产环境
+cd /var/lib/xiaoxia-saas-production
+cp .env.production.example .env
+# 编辑 .env 文件，修改所有 CHANGE_THIS_* 的值
+vim .env
+```
+
+### 步骤 4: 初始化基础设施容器
+
+```bash
+# Staging 环境
+cd /var/lib/xiaoxia-saas-staging/repo/infra/docker
+docker compose -f infra.yml up -d
+
+# Production 环境
+cd /var/lib/xiaoxia-saas-production/repo/infra/docker
+docker compose -f infra-production.yml up -d
+```
+
+### 步骤 5: 验证基础设施
+
+```bash
+# 检查容器状态
+docker ps | grep xiaoxia
+
+# 预期输出应包含:
+# xiaoxia-postgres-production
+# xiaoxia-redis-production
+```
+
+### 步骤 6: 部署应用
+
+```bash
+# Staging 环境
+cd /var/lib/xiaoxia-saas-staging/repo
+bash infra/docker/deploy-staging.sh
+
+# Production 环境（需要先构建镜像并上传）
+bash infra/docker/deploy-production.sh
+```
+
+---
+
+## 版本更新流程
+
+### 方式一: CI/CD 自动部署（推荐）
+
+#### Staging 环境
+推送到 `main` 或 `develop` 分支自动触发部署。
+
+#### Production 环境
+1. 创建并推送 tag:
+```bash
+git tag v0.1.x
+git push origin v0.1.x
+```
+2. CI/CD 自动完成构建和部署。
+
+### 方式二: 手动部署
+
+#### 步骤 1: 构建镜像（在构建服务器）
+
+```bash
+# 在构建服务器执行
+git clone https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas.git
+cd xiaoxia-saas
+
+# 构建 API 和 Worker 镜像
+bash scripts/build_release_images.sh v0.1.x
+
+# 构建 Web 镜像
+docker build -f infra/docker/web-artifact.Dockerfile \
+  -t xiaoxia-saas-web:v0.1.x .
+
+# 打包镜像
+docker save xiaoxia-saas-api:v0.1.x xiaoxia-saas-worker:v0.1.x \
+  -o runtime-images-v0.1.x.tar
+docker save xiaoxia-saas-web:v0.1.x -o web-v0.1.x.tar
+
+# 打包源码
+tar --exclude=.git --exclude=apps/web/node_modules \
+  -czf release-v0.1.x.tar.gz .
+```
+
+#### 步骤 2: 上传到生产服务器
+
+```bash
+# 上传到生产服务器
+scp runtime-images-v0.1.x.tar user@production:/var/lib/xiaoxia-saas-production/
+scp web-v0.1.x.tar user@production:/var/lib/xiaoxia-saas-production/
+scp release-v0.1.x.tar.gz user@production:/var/lib/xiaoxia-saas-production/
+```
+
+#### 步骤 3: 部署到生产环境
+
+```bash
+# 在生产服务器执行
+cd /var/lib/xiaoxia-saas-production
+
+# 加载镜像
+docker load -i runtime-images-v0.1.x.tar
+docker load -i web-v0.1.x.tar
+
+# 解压源码
+tar -xzf release-v0.1.x.tar.gz
+cp .env .env.backup
+
+# 执行部署
+RELEASE_VERSION=v0.1.x bash repo/infra/docker/deploy-production.sh
+```
+
+#### 步骤 4: 验证部署
+
+```bash
+# 检查容器状态
+docker compose -f infra/docker/compose.yml ps
+
+# 健康检查
+curl https://saas.xiaoxiajianji.com/
+curl https://api.xiaoxiajianji.com/health
+```
+
+---
+
+## 回滚流程
+
+### 方式一: 使用回滚脚本
+
+```bash
+# 查看可用的历史版本
+ls -la /var/lib/xiaoxia-saas-production/runtime-images-*.tar
+
+# 回滚到指定版本
+bash scripts/rollback.sh v0.1.x
+```
+
+### 方式二: 手动回滚
+
+#### 步骤 1: 停止当前容器
+
+```bash
+cd /var/lib/xiaoxia-saas-production/repo/infra/docker
+docker compose --env-file ../../.env down
+```
+
+#### 步骤 2: 加载旧版本镜像
+
+```bash
+cd /var/lib/xiaoxia-saas-production
+docker load -i runtime-images-v0.1.y.tar
+docker load -i web-v0.1.y.tar
+```
+
+#### 步骤 3: 部署旧版本
+
+```bash
+RELEASE_VERSION=v0.1.y bash repo/infra/docker/deploy-production.sh
+```
+
+#### 步骤 4: 验证回滚
+
+```bash
+# 检查版本号
+curl https://api.xiaoxiajianji.com/health | jq .version
+
+# 检查容器
+docker compose -f infra/docker/compose.yml ps
+```
+
+---
+
+## 常见问题排查
+
+### 问题 1: Web 容器返回 403
+
+**症状**: 访问网站返回 403 Forbidden
+
+**原因**: web-dist volume 错误挂载
+
+**排查**:
+```bash
+# 检查 web 容器日志
+docker logs xiaoxia-web-production
+
+# 检查 web 容器挂载
+docker inspect xiaoxia-web-production | jq '.[0].Mounts'
+```
+
+**解决方案**:
+```bash
+# 确保不要在生产环境使用 volume 挂载 web-dist
+# 检查 docker-compose.yml 确保没有错误的 volume 挂载
+```
+
+### 问题 2: API 健康检查失败
+
+**症状**: API 容器不断重启
+
+**排查**:
+```bash
+# 查看 API 日志
+docker logs xiaoxia-api-production
+
+# 检查数据库连接
+docker exec -it xiaoxia-api-production python -c \
+  "from sqlalchemy import create_engine; \
+   engine = create_engine('$DATABASE_URL'); \
+   print(engine.table_names())"
+```
+
+**解决方案**:
+1. 确保数据库容器正常运行
+2. 检查 DATABASE_URL 配置正确
+3. 检查 .env 文件是否存在
+
+### 问题 3: 镜像构建失败
+
+**症状**: OOM 或构建超时
+
+**排查**:
+```bash
+# 检查构建服务器内存
+free -h
+
+# 检查磁盘空间
+df -h
+```
+
+**解决方案**:
+```bash
+# 添加 swap
+fallocate -l 4G /swapfile
+mkswap /swapfile
+swapon /swapfile
+```
+
+### 问题 4: 数据库迁移失败
+
+**症状**: 应用启动但报错缺少表
+
+**排查**:
+```bash
+# 检查迁移状态
+docker exec -it xiaoxia-api-production \
+  sh -c 'alembic current'
+```
+
+**解决方案**:
+```bash
+# 手动执行迁移
+docker exec -it xiaoxia-api-production \
+  sh -c 'alembic upgrade head'
+```
+
+### 问题 5: Worker 不处理任务
+
+**排查**:
+```bash
+# 检查 worker 日志
+docker logs xiaoxia-worker-production
+
+# 检查 Redis 连接
+docker exec -it xiaoxia-redis-production redis-cli ping
+```
+
+---
+
+## 环境变量说明
+
+### 必需配置
+
+| 变量名 | 说明 | 示例 |
+|--------|------|------|
+| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql://user:pass@host:5432/db` |
+| `REDIS_URL` | Redis 连接字符串 | `redis://:pass@host:6379/0` |
+| `JWT_SECRET_KEY` | JWT 密钥（至少 32 字符） | `your-random-secret-key` |
+
+### 应用配置
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `APP_ENV` | 运行环境 | `staging` / `production` |
+| `DEBUG` | 调试模式 | `false` |
+| `LOG_LEVEL` | 日志级别 | `INFO` / `WARNING` |
+| `BASE_URL` | 应用基础 URL | `https://saas.xiaoxiajianji.com` |
+
+### 邮件配置
+
+| 变量名 | 说明 |
+|--------|------|
+| `SMTP_HOST` | SMTP 服务器地址 |
+| `SMTP_PORT` | SMTP 端口（587 或 465） |
+| `SMTP_USER` | SMTP 用户名 |
+| `SMTP_PASSWORD` | SMTP 密码 |
+| `SMTP_FROM_EMAIL` | 发件人邮箱 |
+
+### 存储配置（可选）
+
+| 变量名 | 说明 |
+|--------|------|
+| `OSS_ENDPOINT` | 阿里云 OSS 端点 |
+| `OSS_ACCESS_KEY_ID` | OSS Access Key |
+| `OSS_ACCESS_KEY_SECRET` | OSS Secret |
+| `OSS_BUCKET_NAME` | OSS Bucket 名称 |
+
+### 部署配置
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `API_IMAGE` | API 镜像名 | `xiaoxia-saas-api:dev` |
+| `WORKER_IMAGE` | Worker 镜像名 | `xiaoxia-saas-worker:dev` |
+| `WEB_IMAGE` | Web 镜像名 | `xiaoxia-saas-web:dev` |
+| `WEB_PORT` | Web 端口 | `3001` (staging) / `3002` (production) |
+| `API_PORT` | API 端口 | `8000` (staging) / `8001` (production) |
+
+---
+
+## 安全建议
+
+1. **定期更新**: 保持 Docker 和基础镜像更新
+2. **密钥管理**: 使用 Docker secrets 或外部密钥管理服务
+3. **网络隔离**: 限制数据库和 Redis 端口仅内网访问
+4. **日志审计**: 定期检查容器日志和系统日志
+5. **备份策略**: 定期备份数据库和关键配置文件

infra/docker/compose.yml

@@ -1,80 +1,189 @@
+# ===========================================
+# 小虾剪辑 SaaS Docker Compose 配置
+# ===========================================
+#
+# 用法:
+#   Staging: docker compose --env-file ../../.env -f compose.yml up -d
+#   Production: 设置相关环境变量后执行
+#
+# 环境变量说明:
+#   API_IMAGE        - API 镜像名称 (默认: xiaoxia-saas-api:dev)
+#   WORKER_IMAGE     - Worker 镜像名称 (默认: xiaoxia-saas-worker:dev)
+#   WEB_IMAGE        - Web 镜像名称 (默认: xiaoxia-saas-web:dev)
+#   WEB_DOCKERFILE   - Web Dockerfile 路径
+#   WEB_NGINX_CONF   - Nginx 配置文件路径
+#   API_PORT         - API 端口映射 (staging: 8000, production: 8001)
+#   WEB_PORT         - Web 端口映射 (staging: 3001, production: 3002)
+#   GENERATED_FILES_HOST_DIR - 生成文件的主机目录
+#   WORKER_CONCURRENCY        - Worker 并发数 (默认: 1)
+#   WORKER_MAX_TASKS_PER_CHILD - Worker 每个子进程最大任务数 (默认: 100)
+#
+# 重要: 
+#   - 生产环境不要挂载 web-dist volume，否则会导致 403
+#   - 确保 xiaoxia-net 网络已创建: docker network create xiaoxia-net
+#
+
 services:
+  # =========================================
+  # API 服务
+  # =========================================
   api:
     image: ${API_IMAGE:-xiaoxia-saas-api:dev}
-    build:
-      context: ../..
-      dockerfile: infra/docker/api.Dockerfile
+    # 不在生产环境构建镜像，使用预构建的镜像
+    # build:
+    #   context: ../..
+    #   dockerfile: infra/docker/api.Dockerfile
+    
     container_name: xiaoxia-api-${ENV:-staging}
     restart: unless-stopped
+    
+    # 环境变量文件（包含数据库密码等敏感信息）
     env_file:
       - ../../.env
+    
     environment:
       APP_ENV: ${APP_ENV:-staging}
       APP_VERSION: ${APP_VERSION:-0.1.0}
       GENERATED_FILES_DIR: /app/generated
       GENERATED_FILES_URL_PREFIX: /generated-files
       PUBLIC_API_BASE_URL: ${PUBLIC_API_BASE_URL:-https://api.xiaoxiajianji.com}
+    
+    # 端口映射
+    # Staging: 8000 -> 8000
+    # Production: 8001 -> 8000
     ports:
       - "${API_PORT:-8000}:8000"
+    
+    # 共享生成文件目录
     volumes:
       - generated-files:/app/generated
+    
     networks:
       - xiaoxia-net
+    
+    # 健康检查配置
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"]
       interval: 30s
       timeout: 10s
       retries: 3
       start_period: 40s
+    
+    # =========================================
+    # 资源限制建议（生产环境建议启用）
+    # =========================================
+    # deploy:
+    #   resources:
+    #     limits:
+    #       cpus: '2.0'
+    #       memory: 2G
+    #     reservations:
+    #       cpus: '0.5'
+    #       memory: 512M
 
+  # =========================================
+  # Worker 服务（Celery 任务队列）
+  # =========================================
   worker:
     image: ${WORKER_IMAGE:-xiaoxia-saas-worker:dev}
-    build:
-      context: ../..
-      dockerfile: infra/docker/worker.Dockerfile
+    
     container_name: xiaoxia-worker-${ENV:-staging}
     restart: unless-stopped
+    
     env_file:
       - ../../.env
+    
     environment:
       APP_ENV: ${APP_ENV:-staging}
       APP_VERSION: ${APP_VERSION:-0.1.0}
       WORKER_CONCURRENCY: ${WORKER_CONCURRENCY:-1}
+      WORKER_MAX_TASKS_PER_CHILD: ${WORKER_MAX_TASKS_PER_CHILD:-100}
       GENERATED_FILES_DIR: /app/generated
       GENERATED_FILES_URL_PREFIX: /generated-files
       PUBLIC_API_BASE_URL: ${PUBLIC_API_BASE_URL:-https://api.xiaoxiajianji.com}
+    
     volumes:
       - generated-files:/app/generated
+    
     networks:
       - xiaoxia-net
+    
+    # =========================================
+    # 资源限制建议（生产环境建议启用）
+    # =========================================
+    # 注意: Worker 需要处理视频，建议分配更多资源
+    # deploy:
+    #   resources:
+    #     limits:
+    #       cpus: '2.0'
+    #       memory: 4G
+    #     reservations:
+    #       cpus: '0.5'
+    #       memory: 1G
 
+  # =========================================
+  # Web 服务（Nginx + 前端静态文件）
+  # =========================================
   web:
     image: ${WEB_IMAGE:-xiaoxia-saas-web:dev}
-    build:
-      context: ../..
-      dockerfile: ${WEB_DOCKERFILE:-infra/docker/web.Dockerfile}
-      args:
-        NGINX_CONF: ${WEB_NGINX_CONF:-infra/docker/nginx.conf}
+    # 不在生产环境构建镜像，使用 web-artifact.Dockerfile
+    # build:
+    #   context: ../..
+    #   dockerfile: ${WEB_DOCKERFILE:-infra/docker/web.Dockerfile}
+    #   args:
+    #     NGINX_CONF: ${WEB_NGINX_CONF:-infra/docker/nginx.conf}
+    
     container_name: xiaoxia-web-${ENV:-staging}
     restart: unless-stopped
+    
+    # 端口映射
+    # Staging: 3001 -> 80
+    # Production: 3002 -> 80 (通过 Nginx 反向代理)
     ports:
       - "${WEB_PORT:-3001}:80"
+    
     networks:
       - xiaoxia-net
+    
+    # =========================================
+    # 重要: 生产环境不要添加任何 volume 挂载到 /usr/share/nginx/html
+    # 这会导致静态文件被覆盖，返回 403 错误
+    # =========================================
+    
     healthcheck:
       test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:80"]
       interval: 30s
       timeout: 5s
       retries: 3
+    
+    # =========================================
+    # 资源限制建议
+    # =========================================
+    # deploy:
+    #   resources:
+    #     limits:
+    #       cpus: '0.5'
+    #       memory: 256M
 
+# ===========================================
+# 共享卷配置
+# ===========================================
 volumes:
   generated-files:
     driver: local
     driver_opts:
       type: none
       o: bind
+      # 重要: 确保主机目录存在且有正确权限
+      # Staging: /var/lib/xiaoxia-saas-staging/generated
+      # Production: /var/lib/xiaoxia-saas-production/generated
       device: ${GENERATED_FILES_HOST_DIR:-/var/lib/xiaoxia-saas-staging/generated}
 
+# ===========================================
+# 网络配置
+# ===========================================
 networks:
   xiaoxia-net:
     external: true
+    # 注意: 必须先创建网络
+    # docker network create xiaoxia-net

scripts/deploy_staging.sh

@@ -0,0 +1,300 @@
+#!/bin/sh
+#
+# 小虾剪辑 SaaS 预发布环境部署脚本
+#
+# 用法:
+#   ./deploy_staging.sh <commit-sha>              # 部署指定 commit
+#   ./deploy_staging.sh                          # 使用当前 HEAD
+#
+# 环境变量:
+#   GITHUB_SHA           - Git commit SHA
+#   SKIP_MIGRATION       - 跳过数据库迁移 (true/false)
+#   SKIP_HEALTH_CHECK    - 跳过健康检查 (true/false)
+#   BUILD_WEB            - 是否构建 Web 镜像 (0/1)
+#   REBUILD_BACKEND      - 是否重新构建后端镜像 (0/1)
+#
+
+set -eu
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+ROOT_DIR="$SCRIPT_DIR"
+COMPOSE_DIR="$ROOT_DIR/repo/infra/docker"
+ENV_FILE="$ROOT_DIR/.env"
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo "${RED}[ERROR]${NC} $1"; }
+log_step() { echo "${BLUE}[STEP]${NC} $1"; }
+
+# 显示横幅
+show_banner() {
+    echo ""
+    echo "=========================================="
+    echo "  小虾剪辑 SaaS 预发布环境部署脚本"
+    echo "=========================================="
+    echo ""
+}
+
+# 检查前置条件
+check_prerequisites() {
+    log_step "检查前置条件..."
+    
+    # 检查 Docker
+    if ! command -v docker >/dev/null 2>&1; then
+        log_error "Docker 未安装"
+        exit 1
+    fi
+    
+    # 检查 Docker Compose
+    if ! docker compose version >/dev/null 2>&1; then
+        log_error "Docker Compose 未安装"
+        exit 1
+    fi
+    
+    # 检查目录
+    if [ ! -d "$COMPOSE_DIR" ]; then
+        log_error "找不到部署目录: $COMPOSE_DIR"
+        exit 1
+    fi
+    
+    # 检查环境变量文件
+    if [ ! -f "$ENV_FILE" ]; then
+        log_error "找不到环境变量文件: $ENV_FILE"
+        exit 1
+    fi
+    
+    # 加载环境变量
+    set -a
+    . "$ENV_FILE"
+    set +a
+    
+    log_info "前置条件检查通过"
+}
+
+# 检查系统资源
+check_resources() {
+    log_step "检查系统资源..."
+    
+    # 检查内存
+    available_mb=$(free -m | awk '/^Mem:/{print $7}')
+    min_memory_mb=1024
+    
+    if [ "$available_mb" -lt "$min_memory_mb" ]; then
+        log_warn "可用内存不足: ${available_mb}MiB (建议至少 ${min_memory_mb}MiB)"
+    else
+        log_info "内存检查通过: ${available_mb}MiB 可用"
+    fi
+    
+    # 检查磁盘空间
+    available_gb=$(df -BG "$ROOT_DIR" | awk 'NR==2 {print $4}' | tr -d 'G')
+    min_disk_gb=5
+    
+    if [ "$available_gb" -lt "$min_disk_gb" ]; then
+        log_error "磁盘空间不足: ${available_gb}GB (建议至少 ${min_disk_gb}GB)"
+        exit 1
+    fi
+    
+    log_info "磁盘空间检查通过: ${available_gb}GB 可用"
+}
+
+# 检查基础设施容器
+check_infrastructure() {
+    log_step "检查基础设施..."
+    
+    containers="xiaoxia-postgres xiaoxia-redis"
+    
+    for name in $containers; do
+        if docker inspect "$name" >/dev/null 2>&1; then
+            state=$(docker inspect -f '{{.State.Status}}' "$name")
+            if [ "$state" = "running" ]; then
+                log_info "容器正常: $name ($state)"
+            else
+                log_error "容器未运行: $name ($state)"
+                log_info "请先启动基础设施: docker compose -f infra/docker/infra.yml up -d"
+                exit 1
+            fi
+        else
+            log_error "容器不存在: $name"
+            log_info "请先启动基础设施: docker compose -f infra/docker/infra.yml up -d"
+            exit 1
+        fi
+    done
+}
+
+# 确保目录存在
+ensure_directories() {
+    log_step "确保必要目录存在..."
+    
+    mkdir -p "$ROOT_DIR/repo/apps/web/public"
+    mkdir -p "$ROOT_DIR/generated"
+    
+    # 创建占位文件
+    if [ ! -f "$ROOT_DIR/repo/apps/web/public/.keep" ]; then
+        printf 'placeholder' > "$ROOT_DIR/repo/apps/web/public/.keep"
+    fi
+    
+    log_info "目录检查完成"
+}
+
+# 部署服务
+deploy_services() {
+    commit_sha="${1:-${GITHUB_SHA:-local}}"
+    
+    log_step "部署服务..."
+    
+    cd "$COMPOSE_DIR"
+    
+    # 设置环境变量
+    export COMPOSE_PROJECT_NAME=xiaoxia-staging-app
+    export WEB_PORT="${WEB_PORT:-3001}"
+    export DOCKER_BUILDKIT=0
+    export COMPOSE_DOCKER_CLI_BUILD=0
+    export APP_ENV="staging"
+    export APP_VERSION="$commit_sha"
+    
+    # 设置镜像标签
+    web_tag="staging-${commit_sha:0:8}"
+    export WEB_IMAGE="xiaoxia-saas-web:$web_tag"
+    
+    # 构建后端镜像
+    if [ "${REBUILD_BACKEND:-0}" = "1" ]; then
+        if [ "${ALLOW_STAGING_BUILDS:-false}" != "true" ]; then
+            log_error "不允许在业务服务器构建后端镜像"
+            log_info "请在 CI 服务器构建后上传，或设置 ALLOW_STAGING_BUILDS=true"
+            exit 1
+        fi
+        log_info "构建后端镜像..."
+        docker compose --env-file "$ENV_FILE" build --pull=false api
+        docker compose --env-file "$ENV_FILE" build --pull=false worker
+    fi
+    
+    # 构建 Web 镜像
+    if [ "${BUILD_WEB:-0}" = "1" ]; then
+        if [ "${ALLOW_STAGING_BUILDS:-false}" != "true" ]; then
+            log_error "不允许在业务服务器构建 Web 镜像"
+            log_info "请在 CI 服务器构建后上传，或设置 ALLOW_STAGING_BUILDS=true"
+            exit 1
+        fi
+        log_info "构建 Web 镜像..."
+        docker compose --env-file "$ENV_FILE" build --pull=false web
+    fi
+    
+    # 执行数据库迁移
+    if [ "${SKIP_MIGRATION:-0}" != "1" ]; then
+        log_step "执行数据库迁移..."
+        docker compose --env-file "$ENV_FILE" run --rm --no-deps api \
+            sh -c 'cd /app && alembic upgrade head' || true
+    fi
+    
+    # 启动服务
+    log_info "启动服务..."
+    docker compose --env-file "$ENV_FILE" up -d api worker web
+    
+    log_info "服务部署完成"
+}
+
+# 健康检查
+health_check() {
+    if [ "${SKIP_HEALTH_CHECK:-false}" = "true" ]; then
+        log_warn "跳过健康检查"
+        return 0
+    fi
+    
+    log_step "执行健康检查..."
+    
+    max_attempts=30
+    attempt=0
+    
+    # 检查 API
+    while [ $attempt -lt $max_attempts ]; do
+        if curl -sf "http://127.0.0.1:8000/health" >/dev/null 2>&1; then
+            log_info "API 健康检查通过"
+            break
+        fi
+        attempt=$((attempt + 1))
+        echo -n "."
+        sleep 2
+    done
+    
+    echo ""
+    
+    if [ $attempt -eq $max_attempts ]; then
+        log_error "API 健康检查超时"
+        log_warn "请检查日志: docker compose -f infra/docker/compose.yml logs api"
+        return 1
+    fi
+    
+    # 检查 Web
+    attempt=0
+    while [ $attempt -lt 10 ]; do
+        if curl -sf "http://127.0.0.1:${WEB_PORT:-3001}/" >/dev/null 2>&1; then
+            log_info "Web 健康检查通过"
+            break
+        fi
+        attempt=$((attempt + 1))
+        echo -n "."
+        sleep 2
+    done
+    
+    echo ""
+    
+    log_info "健康检查完成"
+}
+
+# 显示部署状态
+show_status() {
+    log_step "部署状态:"
+    echo ""
+    
+    cd "$COMPOSE_DIR"
+    docker compose --env-file "$ENV_FILE" ps
+    
+    echo ""
+    log_info "部署完成!"
+    log_info "Commit: ${1:-${GITHUB_SHA:-local}}"
+    log_info "Web: http://127.0.0.1:${WEB_PORT:-3001}/"
+    log_info "API: http://127.0.0.1:8000/health"
+}
+
+# 主流程
+main() {
+    commit_sha="${1:-${GITHUB_SHA:-}}"
+    
+    show_banner
+    
+    # 显示配置
+    echo "部署配置:"
+    echo "  Commit: ${commit_sha:-当前 HEAD}"
+    echo "  环境文件: $ENV_FILE"
+    echo "  Web 端口: ${WEB_PORT:-3001}"
+    echo "  跳过迁移: ${SKIP_MIGRATION:-0}"
+    echo "  跳过健康检查: ${SKIP_HEALTH_CHECK:-false}"
+    echo "  构建后端: ${REBUILD_BACKEND:-0}"
+    echo "  构建 Web: ${BUILD_WEB:-0}"
+    echo ""
+    
+    # 执行部署流程
+    check_prerequisites
+    check_resources
+    check_infrastructure
+    ensure_directories
+    deploy_services "$commit_sha"
+    
+    if ! health_check; then
+        log_warn "健康检查失败，但服务可能正在启动"
+    fi
+    
+    show_status "$commit_sha"
+    
+    echo ""
+    log_info "部署成功完成!"
+}
+
+main "$@"