docs: 更新 CI/CD 接入指南，改用日志捕获 + run_number 方式

- 核心要点：tee 捕获日志、github.run_number、模板语法、单一综合上报 - 完整 Gitea Actions 集成示例（含日志收集和失败判断逻辑） - 字段说明中标注 run_url 的正确拼接方式 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 10:18:22 +08:00 · 2026-02-26 10:18:22 +08:00 · 89f19e9776
commit 89f19e9776
parent cd22a5696b
1 changed files with 104 additions and 91 deletions
--- a/docs/integration_guide.md
+++ b/docs/integration_guide.md
@ -408,32 +408,39 @@ void main() {

 > `source: "cicd"`

-在 Gitea Actions 流水线中，为每个关键步骤添加失败上报，构建/测试/Lint 失败时自动上报到 Log Center。
+在 Gitea Actions 流水线中添加失败上报，构建/测试/部署失败时自动捕获实际错误日志并上报到 Log Center。
+
+### 核心要点
+
+1. **用 `tee` 捕获日志** — 构建和部署步骤的输出必须通过 `2>&1 | tee /tmp/xxx.log` 捕获，否则上报的 stack_trace 为空
+2. **用 `github.run_number`** — URL 中必须使用 `${{ github.run_number }}`（仓库维度序号），**不要用 `github.run_id`**（全局ID，会导致跳转到错误页面）
+3. **用 `${{ }}` 模板语法** — 比 `$GITHUB_*` 环境变量更可靠
+4. **单一综合上报步骤** — 一个 `if: failure()` 步骤自动判断哪个阶段失败，收集对应日志

 ### 上报格式

 ```json
 {
  "project_id": "rtc_backend",
-  "environment": "cicd",
+  "environment": "main",
  "level": "ERROR",
  "source": "cicd",
-  "commit_hash": "abc1234",
+  "commit_hash": "abc1234def5678",
+  "repo_url": "https://gitea.airlabs.art/zyc/rtc_backend.git",
  "error": {
-    "type": "DockerBuildError",
-    "message": "Docker build failed",
-    "file_path": null,
-    "line_number": null,
-    "stack_trace": ["Build step failed. Check CI logs for details."]
+    "type": "CICDFailure",
+    "message": "[build] Build and Deploy failed on branch main",
+    "stack_trace": ["...实际构建日志最后 50 行..."]
  },
  "context": {
-    "workflow_name": "Build and Deploy",
-    "job_name": "build",
-    "step_name": "Build Docker Image",
-    "run_id": "123",
+    "job_name": "build-and-deploy",
+    "step_name": "build",
+    "workflow": "Build and Deploy",
+    "run_id": "24",
    "branch": "main",
-    "repository": "team/rtc_backend",
-    "run_url": "https://gitea.airlabs.art/team/rtc_backend/actions/runs/123"
+    "actor": "zyc",
+    "commit": "abc1234def5678",
+    "run_url": "https://gitea.airlabs.art/zyc/rtc_backend/actions/runs/24"
  }
 }
 ```
@ -443,20 +450,19 @@ void main() {
 | 字段 | 说明 |
 |------|------|
 | `source` | **必须**设为 `"cicd"` |
-| `environment` | 设为 `"cicd"` |
-| `error.type` | 推荐值：`DockerBuildError`, `NpmBuildError`, `TestFailure`, `LintError`, `CIBuildError` |
-| `error.file_path` | 可为 `null` |
-| `error.line_number` | 可为 `null` |
-| `context.workflow_name` | 工作流名称 |
-| `context.job_name` | Job 名称 |
+| `environment` | 用分支名 `${{ github.ref_name }}`，如 `main`、`dev` |
+| `repo_url` | 仓库地址，便于 Repair Agent 关联 |
+| `error.type` | 推荐 `CICDFailure`（通用）或 `DockerBuildError` / `TestFailure` / `DeployError` |
+| `error.stack_trace` | **实际错误日志**（通过 `tee` 捕获），不要写死占位文字 |
+| `context.run_id` | **必须用 `${{ github.run_number }}`**（不是 `github.run_id`） |
+| `context.run_url` | 拼接方式：`https://gitea.airlabs.art/${{ github.repository }}/actions/runs/${{ github.run_number }}` |
 | `context.step_name` | 失败的步骤名称 |
-| `context.run_id` | 运行 ID |
-| `context.run_url` | CI 运行详情链接 |
-| `context.branch` | 分支名 |
+| `context.actor` | 触发者 |
+| `context.commit` | 完整 commit hash |

-### Gitea Actions 集成方式
+### Gitea Actions 集成方式（推荐）

-为每个关键步骤添加 `id`，然后在末尾添加条件上报步骤：
+以下是完整示例，关键点：构建步骤用 `tee` 捕获日志，末尾一个综合上报步骤自动判断失败阶段。

 ```yaml
 name: Build and Deploy
@ -465,87 +471,94 @@ on:
  push:
    branches: [main]

-env:
-  LOG_CENTER_URL: https://qiyuan-log-center-api.airlabs.art
-
 jobs:
-  build:
+  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
+
+      # ===== 构建步骤：用 tee 捕获日志 =====

-      # 关键步骤：添加 id
      - name: Build Docker Image
        id: build
-        run: docker build -t myapp:latest .
-
-      - name: Run Tests
-        id: test
-        run: docker run myapp:latest python -m pytest
+        run: |
+          set -o pipefail
+          docker buildx build \
+            --push \
+            --provenance=false \
+            --tag your-registry/your-app:latest \
+            . 2>&1 | tee /tmp/build.log

      - name: Deploy
        id: deploy
-        run: kubectl apply -f k8s/
-
-      # ===== 失败上报步骤（放在所有关键步骤之后） =====
-
-      - name: Report Build Failure
-        if: failure() && steps.build.outcome == 'failure'
        run: |
-          curl -s -X POST "${LOG_CENTER_URL}/api/v1/logs/report" \
-            -H "Content-Type: application/json" \
-            -d '{
-              "project_id": "'"${GITHUB_REPOSITORY##*/}"'",
-              "environment": "cicd",
-              "level": "ERROR",
-              "source": "cicd",
-              "commit_hash": "'"$GITHUB_SHA"'",
-              "error": {
-                "type": "DockerBuildError",
-                "message": "Docker build failed",
-                "file_path": null,
-                "line_number": null,
-                "stack_trace": ["Docker build step failed. Check CI logs."]
-              },
-              "context": {
-                "workflow_name": "'"$GITHUB_WORKFLOW"'",
-                "job_name": "'"$GITHUB_JOB"'",
-                "step_name": "Build Docker Image",
-                "run_id": "'"$GITHUB_RUN_ID"'",
-                "branch": "'"$GITHUB_REF_NAME"'",
-                "repository": "'"$GITHUB_REPOSITORY"'",
-                "run_url": "'"$GITHUB_SERVER_URL"'/'"$GITHUB_REPOSITORY"'/actions/runs/'"$GITHUB_RUN_ID"'"
-              }
-            }' --connect-timeout 5 --max-time 10 || true
+          set -o pipefail
+          {
+            kubectl apply -f k8s/deployment.yaml
+            kubectl rollout restart deployment/your-app
+          } 2>&1 | tee /tmp/deploy.log

-      - name: Report Test Failure
-        if: failure() && steps.test.outcome == 'failure'
+      # ===== 失败上报（单一综合步骤） =====
+
+      - name: Report failure to Log Center
+        if: failure()
        run: |
-          curl -s -X POST "${LOG_CENTER_URL}/api/v1/logs/report" \
+          # 判断哪个步骤失败，收集对应日志
+          BUILD_LOG=""
+          DEPLOY_LOG=""
+          FAILED_STEP="unknown"
+
+          if [[ "${{ steps.build.outcome }}" == "failure" ]]; then
+            FAILED_STEP="build"
+            if [ -f /tmp/build.log ]; then
+              BUILD_LOG=$(tail -50 /tmp/build.log | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
+            fi
+          elif [[ "${{ steps.deploy.outcome }}" == "failure" ]]; then
+            FAILED_STEP="deploy"
+            if [ -f /tmp/deploy.log ]; then
+              DEPLOY_LOG=$(tail -50 /tmp/deploy.log | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
+            fi
+          fi
+
+          ERROR_LOG="${BUILD_LOG}${DEPLOY_LOG}"
+          if [ -z "$ERROR_LOG" ]; then
+            ERROR_LOG="No captured output. Check Gitea Actions UI for details."
+          fi
+
+          # 判断 source
+          if [[ "$FAILED_STEP" == "deploy" ]]; then
+            SOURCE="deployment"
+            ERROR_TYPE="DeployError"
+          else
+            SOURCE="cicd"
+            ERROR_TYPE="DockerBuildError"
+          fi
+
+          curl -s -X POST "https://qiyuan-log-center-api.airlabs.art/api/v1/logs/report" \
            -H "Content-Type: application/json" \
-            -d '{
-              "project_id": "'"${GITHUB_REPOSITORY##*/}"'",
-              "environment": "cicd",
-              "level": "ERROR",
-              "source": "cicd",
-              "commit_hash": "'"$GITHUB_SHA"'",
-              "error": {
-                "type": "TestFailure",
-                "message": "Tests failed in CI pipeline",
-                "file_path": null,
-                "line_number": null,
-                "stack_trace": ["Test step failed. Check CI logs."]
+            -d "{
+              \"project_id\": \"your_project_id\",
+              \"environment\": \"${{ github.ref_name }}\",
+              \"level\": \"ERROR\",
+              \"source\": \"${SOURCE}\",
+              \"commit_hash\": \"${{ github.sha }}\",
+              \"repo_url\": \"https://gitea.airlabs.art/zyc/your_project.git\",
+              \"error\": {
+                \"type\": \"${ERROR_TYPE}\",
+                \"message\": \"[${FAILED_STEP}] Build and Deploy failed on branch ${{ github.ref_name }}\",
+                \"stack_trace\": [\"${ERROR_LOG}\"]
              },
-              "context": {
-                "workflow_name": "'"$GITHUB_WORKFLOW"'",
-                "job_name": "'"$GITHUB_JOB"'",
-                "step_name": "Run Tests",
-                "run_id": "'"$GITHUB_RUN_ID"'",
-                "branch": "'"$GITHUB_REF_NAME"'",
-                "repository": "'"$GITHUB_REPOSITORY"'",
-                "run_url": "'"$GITHUB_SERVER_URL"'/'"$GITHUB_REPOSITORY"'/actions/runs/'"$GITHUB_RUN_ID"'"
+              \"context\": {
+                \"job_name\": \"build-and-deploy\",
+                \"step_name\": \"${FAILED_STEP}\",
+                \"workflow\": \"${{ github.workflow }}\",
+                \"run_id\": \"${{ github.run_number }}\",
+                \"branch\": \"${{ github.ref_name }}\",
+                \"actor\": \"${{ github.actor }}\",
+                \"commit\": \"${{ github.sha }}\",
+                \"run_url\": \"https://gitea.airlabs.art/${{ github.repository }}/actions/runs/${{ github.run_number }}\"
              }
-            }' --connect-timeout 5 --max-time 10 || true
+            }" || true
 ```

 ### 使用 report-cicd-error.sh 脚本