chore: wire real host-based gitea deploy

.gitea/workflows/deploy.yml

@@ -7,177 +7,110 @@ on:
       - 'v*'
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v3
-    
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v2
-    
-    - name: Build API image
-      run: |
-        docker build -t xiaoxia-saas-api:${{ github.sha }} \
-          -f infra/docker/api.Dockerfile .
-    
-    - name: Build Worker image
-      run: |
-        docker build -t xiaoxia-saas-worker:${{ github.sha }} \
-          -f infra/docker/worker.Dockerfile .
-    
-    - name: Save Docker images
-      run: |
-        docker save xiaoxia-saas-api:${{ github.sha }} | gzip > api-image.tar.gz
-        docker save xiaoxia-saas-worker:${{ github.sha }} | gzip > worker-image.tar.gz
-    
-    - name: Move images to temp
-      run: |
-        mv api-image.tar.gz /tmp/
-        mv worker-image.tar.gz /tmp/
-
   deploy-staging:
+    name: Deploy Staging
     runs-on: ubuntu-latest
-    needs: build
     if: github.ref == 'refs/heads/main'
-    
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v3
-    
-    - name: Deploy to staging
+
+    - name: Sync code to staging workspace
       run: |
-        # Load Docker images
-        docker load < /tmp/api-image.tar.gz
-        docker load < /tmp/worker-image.tar.gz
-        
-        # Prepare staging directory
-        mkdir -p /var/lib/xiaoxia-saas-staging
-        cp .env.staging /var/lib/xiaoxia-saas-staging/.env
-        
-        # Tag as staging
-        docker tag xiaoxia-saas-api:${{ github.sha }} xiaoxia-saas-api:staging
-        docker tag xiaoxia-saas-worker:${{ github.sha }} xiaoxia-saas-worker:staging
-        
-        # Deploy with staging env
-        cd /var/lib/xiaoxia-saas-staging
-        cat > docker-compose.yml << 'COMPOSE'
-version: '3.9'
-services:
-  api:
-    image: xiaoxia-saas-api:staging
-    restart: unless-stopped
-    env_file:
-      - ./.env
-    ports:
-      - "8001:8000"
-    depends_on:
-      - postgres
-      - redis
+        mkdir -p /var/lib/xiaoxia-saas-staging/repo
+        rsync -a --delete --exclude '.git' ./ /var/lib/xiaoxia-saas-staging/repo/
 
-  worker:
-    image: xiaoxia-saas-worker:staging
-    restart: unless-stopped
-    env_file:
-      - ./.env
-    depends_on:
-      - redis
-      - postgres
+    - name: Verify staging env file
+      run: |
+        test -f /var/lib/xiaoxia-saas-staging/.env
 
-  postgres:
-    image: postgres:16
-    restart: unless-stopped
-    environment:
-      POSTGRES_DB: xiaoxia_saas_staging
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: CHANGE_ME_STAGING_DB_PASSWORD
-    volumes:
-      - postgres_staging_data:/var/lib/postgresql/data
+    - name: Prepare staging env
+      run: |
+        cp /var/lib/xiaoxia-saas-staging/.env /var/lib/xiaoxia-saas-staging/repo/.env
 
-  redis:
-    image: redis:7
-    restart: unless-stopped
+    - name: Build staging images
+      run: |
+        docker build \
+          -t xiaoxia-saas-api:${{ github.sha }} \
+          -t xiaoxia-saas-api:staging \
+          -f /var/lib/xiaoxia-saas-staging/repo/infra/docker/api.Dockerfile \
+          /var/lib/xiaoxia-saas-staging/repo
+        docker build \
+          -t xiaoxia-saas-worker:${{ github.sha }} \
+          -t xiaoxia-saas-worker:staging \
+          -f /var/lib/xiaoxia-saas-staging/repo/infra/docker/worker.Dockerfile \
+          /var/lib/xiaoxia-saas-staging/repo
+
+    - name: Deploy staging containers
+      run: |
+        cd /var/lib/xiaoxia-saas-staging/repo/infra/docker
+        API_IMAGE=xiaoxia-saas-api:staging \
+        WORKER_IMAGE=xiaoxia-saas-worker:staging \
+        docker compose up -d postgres redis api worker
+        docker compose ps
+
+    - name: Verify staging health
+      run: |
+        for i in $(seq 1 30); do
+          if curl -fsS http://127.0.0.1:8000/api/v1/health; then
+            exit 0
+          fi
+          sleep 2
+        done
+        exit 1
 
-volumes:
-  postgres_staging_data:
-COMPOSE
-        
-        docker-compose up -d
-        rm -f /tmp/api-image.tar.gz /tmp/worker-image.tar.gz
-        
-        echo "✅ Staging deployment completed"
-    
   deploy-production:
+    name: Deploy Production
     runs-on: ubuntu-latest
-    needs: build
     if: startsWith(github.ref, 'refs/tags/v')
-    
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v3
-    
-    - name: Deploy to production
+
+    - name: Sync code to production workspace
       run: |
-        # Load Docker images
-        docker load < /tmp/api-image.tar.gz
-        docker load < /tmp/worker-image.tar.gz
-        
-        # Prepare production directory
-        mkdir -p /var/lib/xiaoxia-saas-production
-        cp .env.production /var/lib/xiaoxia-saas-production/.env
-        
-        # Tag as production version
-        docker tag xiaoxia-saas-api:${{ github.sha }} xiaoxia-saas-api:${{ github.ref_name }}
-        docker tag xiaoxia-saas-worker:${{ github.sha }} xiaoxia-saas-worker:${{ github.ref_name }}
-        docker tag xiaoxia-saas-api:${{ github.sha }} xiaoxia-saas-api:latest
-        docker tag xiaoxia-saas-worker:${{ github.sha }} xiaoxia-saas-worker:latest
-        
-        # Deploy with production env
-        cd /var/lib/xiaoxia-saas-production
-        cat > docker-compose.yml << 'COMPOSE'
-version: '3.9'
-services:
-  api:
-    image: xiaoxia-saas-api:latest
-    restart: unless-stopped
-    env_file:
-      - ./.env
-    ports:
-      - "8000:8000"
-    depends_on:
-      - postgres
-      - redis
+        mkdir -p /var/lib/xiaoxia-saas-production/repo
+        rsync -a --delete --exclude '.git' ./ /var/lib/xiaoxia-saas-production/repo/
 
-  worker:
-    image: xiaoxia-saas-worker:latest
-    restart: unless-stopped
-    env_file:
-      - ./.env
-    depends_on:
-      - redis
-      - postgres
+    - name: Verify production env file
+      run: |
+        test -f /var/lib/xiaoxia-saas-production/.env
 
-  postgres:
-    image: postgres:16
-    restart: unless-stopped
-    environment:
-      POSTGRES_DB: xiaoxia_saas_production
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: CHANGE_ME_PRODUCTION_DB_PASSWORD
-    volumes:
-      - postgres_production_data:/var/lib/postgresql/data
+    - name: Prepare production env
+      run: |
+        cp /var/lib/xiaoxia-saas-production/.env /var/lib/xiaoxia-saas-production/repo/.env
 
-  redis:
-    image: redis:7
-    restart: unless-stopped
+    - name: Build production images
+      run: |
+        docker build \
+          -t xiaoxia-saas-api:${{ github.sha }} \
+          -t xiaoxia-saas-api:${{ github.ref_name }} \
+          -t xiaoxia-saas-api:latest \
+          -f /var/lib/xiaoxia-saas-production/repo/infra/docker/api.Dockerfile \
+          /var/lib/xiaoxia-saas-production/repo
+        docker build \
+          -t xiaoxia-saas-worker:${{ github.sha }} \
+          -t xiaoxia-saas-worker:${{ github.ref_name }} \
+          -t xiaoxia-saas-worker:latest \
+          -f /var/lib/xiaoxia-saas-production/repo/infra/docker/worker.Dockerfile \
+          /var/lib/xiaoxia-saas-production/repo
 
-volumes:
-  postgres_production_data:
-COMPOSE
-        
-        docker-compose up -d
-        rm -f /tmp/api-image.tar.gz /tmp/worker-image.tar.gz
-        
-        echo "✅ Production deployment completed: ${{ github.ref_name }}"
+    - name: Deploy production containers
+      run: |
+        cd /var/lib/xiaoxia-saas-production/repo/infra/docker
+        API_IMAGE=xiaoxia-saas-api:latest \
+        WORKER_IMAGE=xiaoxia-saas-worker:latest \
+        docker compose up -d postgres redis api worker
+        docker compose ps
+
+    - name: Verify production health
+      run: |
+        for i in $(seq 1 30); do
+          if curl -fsS http://127.0.0.1:8000/api/v1/health; then
+            exit 0
+          fi
+          sleep 2
+        done
+        exit 1

docs/CI-CD.md

@@ -2,137 +2,102 @@
 
 ## Gitea Actions
 
-本项目使用 Gitea Actions 实现 CI/CD 流水线。
+本项目使用 Gitea Actions + 本机 act_runner 实现 CI/CD。
 
 ### 工作流文件
 
 **1. `.gitea/workflows/tests.yml` - 自动化测试**
 
 触发条件：
-- 每次 push 到 main 分支
+- 每次 push 到 `main`
 - 每次创建 Pull Request
 
 包含任务：
 - `test` - 运行集成测试，生成覆盖率报告
-- `lint` - 代码质量检查（Black、Flake8、MyPy）
+- `lint` - 运行 Black / Flake8 / MyPy
 
 **2. `.gitea/workflows/deploy.yml` - 自动化部署**
 
 触发条件：
-- push 到 main 分支 → 部署到 staging 环境
-- 创建 tag (v*) → 部署到 production 环境
+- push 到 `main` → 部署到 staging
+- push tag `v*` → 部署到 production
 
-当前状态：占位，待补充真实部署脚本
+实际行为：
+- runner 在部署主机本机执行 workflow
+- workflow 将仓库同步到 `/var/lib/xiaoxia-saas-staging/repo` 或 `/var/lib/xiaoxia-saas-production/repo`
+- 读取服务器本地真实 `.env`
+- 本机构建 API / Worker 镜像
+- 使用 `infra/docker/compose.yml` 启动 `postgres` / `redis` / `api` / `worker`
+- 部署后用 `/api/v1/health` 做健康校验
+
+---
+
+## 部署目录约定
+
+### Staging
+- 环境根目录：`/var/lib/xiaoxia-saas-staging`
+- 真实环境文件：`/var/lib/xiaoxia-saas-staging/.env`
+- Actions 同步代码目录：`/var/lib/xiaoxia-saas-staging/repo`
+
+### Production
+- 环境根目录：`/var/lib/xiaoxia-saas-production`
+- 真实环境文件：`/var/lib/xiaoxia-saas-production/.env`
+- Actions 同步代码目录：`/var/lib/xiaoxia-saas-production/repo`
 
 ---
 
 ## 本地验证
 
-在推送前，可以本地运行验证：
+推送前建议先跑：
 
 ### 运行测试
 ```bash
 pytest tests/integration/ -v --cov=packages --cov=apps --cov-report=html
 ```
 
-### 代码格式化
+### 代码格式化检查
 ```bash
-black packages/ apps/ tests/
+black --check packages/ apps/ tests/
 ```
 
-### 代码检查
+### 静态检查
 ```bash
-# Flake8
 flake8 packages/ apps/ tests/ --max-line-length=120 --extend-ignore=E203,W503
-
-# MyPy
 mypy packages/ apps/ --ignore-missing-imports
 ```
 
-### 排序 imports
-```bash
-isort packages/ apps/ tests/
-```
-
 ---
 
-## Gitea Actions 配置
+## 当前已验证结论
 
-### 前提条件
-
-1. Gitea 服务器需要启用 Actions 功能
-2. 需要配置 Actions Runner
-
-### 启用步骤
-
-**在 Gitea 服务器上**：
-
-1. 编辑 `/etc/gitea/app.ini`（或对应配置文件）：
-```ini
-[actions]
-ENABLED = true
-```
-
-2. 重启 Gitea：
-```bash
-systemctl restart gitea
-```
-
-3. 安装 Actions Runner：
-```bash
-# 下载 act_runner
-wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64
-chmod +x act_runner-linux-amd64
-mv act_runner-linux-amd64 /usr/local/bin/act_runner
-
-# 注册 runner
-act_runner register --instance http://your-gitea-server --token YOUR_RUNNER_TOKEN
-
-# 运行 runner
-act_runner daemon
-```
-
-4. 在仓库设置中启用 Actions
-
----
-
-## 验证 CI/CD
-
-推送代码后，在 Gitea 仓库页面查看：
-- Actions 标签页
-- 查看工作流运行状态
-- 查看测试结果和覆盖率报告
+- Gitea Actions 已启用
+- `act_runner` 已注册并持续运行
+- staging 可手工部署并已完成真实业务闭环验证
+- 当前 CI/CD 的关键目标是让 Gitea push 后自动完成同机部署，而不是只保留占位 YAML
 
 ---
 
 ## 故障排查
 
-### Actions 未触发
-- 检查 Gitea 是否启用 Actions
-- 检查工作流文件路径是否正确（`.gitea/workflows/`）
-- 检查 YAML 语法是否正确
+### Actions 触发了但 checkout 失败
+优先检查 runner 能否从 job 容器访问 Gitea 实例地址。
 
-### 测试失败
-- 查看 Actions 日志
-- 本地运行 `pytest tests/integration/ -v`
-- 检查依赖是否完整
+### Deploy 成功但业务链不通
+优先检查：
+- `/var/lib/xiaoxia-saas-staging/.env`
+- `MINIO_ENDPOINT`
+- `DATABASE_URL`
+- worker 日志中的 Celery 任务消费情况
 
-### Linting 失败
-- 本地运行 `black --check packages/`
-- 本地运行 `flake8 packages/`
-- 修复后重新推送
-
----
-
-## 未来扩展
-
-- [ ] 添加性能测试
-- [ ] 添加安全扫描
-- [ ] 添加 Docker 镜像构建
-- [ ] 添加自动化部署脚本
-- [ ] 添加 Slack/钉钉通知
+### 健康检查失败
+查看：
+```bash
+docker compose ps
+docker compose logs api --tail=200
+docker compose logs worker --tail=200
+```
 
 ---
 
 **最后更新**: 2026-06-15  
-**状态**: 配置完成，待 Gitea Actions 启用
+**状态**: CI/CD 已接入真实主机部署模型，待 push 后持续验证稳定性

infra/docker/compose.yml

@@ -1,4 +1,3 @@
-version: '3.9'
 services:
   web:
     image: node:20
@@ -12,7 +11,7 @@ services:
       - api
 
   api:
-    image: xiaoxia-saas-api:dev
+    image: ${API_IMAGE:-xiaoxia-saas-api:dev}
     build:
       context: ../..
       dockerfile: infra/docker/api.Dockerfile
@@ -27,7 +26,7 @@ services:
       - redis
 
   worker:
-    image: xiaoxia-saas-worker:dev
+    image: ${WORKER_IMAGE:-xiaoxia-saas-worker:dev}
     build:
       context: ../..
       dockerfile: infra/docker/worker.Dockerfile