From 650889eee19dfa4ae6bf31f6f5c3307b0921ebb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BD=95=E5=98=89=E6=82=A6?= <2834007710@qq.com>
Date: Tue, 10 Mar 2026 21:40:47 +0800
Subject: [PATCH 1/2] ci(docs): add docs deployment workflows

---
 .github/workflows/deploy-docs.yaml        | 171 ++++++++++++++++++++++
 .github/workflows/docs-deploy-verify.yaml | 128 ++++++++++++++++
 scripts/docs/README.md                    |  72 +++++++++
 3 files changed, 371 insertions(+)
 create mode 100644 .github/workflows/deploy-docs.yaml
 create mode 100644 .github/workflows/docs-deploy-verify.yaml
 create mode 100644 scripts/docs/README.md

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
new file mode 100644
index 00000000..6f497a19
--- /dev/null
+++ b/.github/workflows/deploy-docs.yaml
@@ -0,0 +1,171 @@
+name: Docs Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      line:
+        description: 'Docs line (v1 or v2)'
+        required: true
+        type: choice
+        options:
+          - v1
+          - v2
+      version:
+        description: 'Release tag (e.g. v2.0.0-beta.5)'
+        required: true
+        type: string
+      source_ref:
+        description: 'Git ref to build (e.g. refs/tags/v2.0.0-beta.5)'
+        required: true
+        type: string
+      source_sha:
+        description: 'Release commit SHA (optional)'
+        required: false
+        type: string
+      is_prerelease:
+        description: 'true for prerelease/beta'
+        required: true
+        default: 'true'
+        type: string
+      switch_current:
+        description: 'Switch current symlink after upload'
+        required: true
+        default: 'false'
+        type: string
+      update_root_redirect:
+        description: 'Update root redirect when release should become default'
+        required: true
+        default: 'false'
+        type: string
+
+concurrency:
+  group: docs-release-${{ inputs.version }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate line/version
+        run: |
+          if [[ "${{ inputs.line }}" == "v1" ]]; then
+            [[ "${{ inputs.version }}" =~ ^v1\. ]] || { echo "v1 must use v1.* tag"; exit 1; }
+          else
+            [[ "${{ inputs.version }}" =~ ^v2\. ]] || { echo "v2 must use v2.* tag"; exit 1; }
+          fi
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          npm i -g pnpm
+          pnpm install
+
+      - name: Resolve docs env
+        id: docs_env
+        run: |
+          if [[ "${{ inputs.line }}" == "v2" ]]; then
+            echo "PUBLIC_ORIGIN=https://v2.element-plus-x.com" >> $GITHUB_OUTPUT
+            if [[ "${{ inputs.is_prerelease }}" == "true" ]]; then
+              echo "VERSION_LABEL=v2.x (Beta)" >> $GITHUB_OUTPUT
+            else
+              echo "VERSION_LABEL=v2.x" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "PUBLIC_ORIGIN=https://v1.element-plus-x.com" >> $GITHUB_OUTPUT
+            echo "VERSION_LABEL=v1.x" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Build docs
+        env:
+          DOCS_LINE: ${{ inputs.line }}
+          DOCS_PUBLIC_ORIGIN: ${{ steps.docs_env.outputs.PUBLIC_ORIGIN }}
+          DOCS_VERSION_LABEL: ${{ steps.docs_env.outputs.VERSION_LABEL }}
+          DOCS_V1_ORIGIN: https://v1.element-plus-x.com
+          DOCS_V2_ORIGIN: https://v2.element-plus-x.com
+          DOCS_ROOT_ORIGIN: https://element-plus-x.com
+          DOCS_USE_SOURCE: 'true'
+        run: pnpm run build:docs
+
+      - name: Setup SSH
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.DOCS_DEPLOY_SSH_KEY }}
+
+      - name: Add deploy host to known_hosts
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+        run: |
+          mkdir -p ~/.ssh
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          ssh-keyscan -p "$PORT" -H "$DOCS_DEPLOY_HOST" >> ~/.ssh/known_hosts
+
+      - name: Upload release
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+          DOCS_DEPLOY_USER: ${{ secrets.DOCS_DEPLOY_USER }}
+          DOCS_DEPLOY_BASE_DIR: ${{ secrets.DOCS_DEPLOY_BASE_DIR }}
+        run: |
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          DOCS_BASE="${DOCS_DEPLOY_BASE_DIR}/${{ inputs.line }}"
+          RELEASE_DIR="${DOCS_BASE}/releases/${{ inputs.version }}"
+
+          ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "mkdir -p '$RELEASE_DIR'"
+          rsync -az --delete -e "ssh -p $PORT" apps/docs/.vitepress/dist/ "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST:$RELEASE_DIR/"
+          echo "Uploaded release to $RELEASE_DIR"
+
+      - name: Switch current symlink
+        if: inputs.switch_current == 'true'
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+          DOCS_DEPLOY_USER: ${{ secrets.DOCS_DEPLOY_USER }}
+          DOCS_DEPLOY_BASE_DIR: ${{ secrets.DOCS_DEPLOY_BASE_DIR }}
+        run: |
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          DOCS_BASE="${DOCS_DEPLOY_BASE_DIR}/${{ inputs.line }}"
+          RELEASE_DIR="${DOCS_BASE}/releases/${{ inputs.version }}"
+
+          ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "ln -sfn '$RELEASE_DIR' '$DOCS_BASE/current'"
+
+      - name: Update root redirect
+        if: inputs.update_root_redirect == 'true'
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+          DOCS_DEPLOY_USER: ${{ secrets.DOCS_DEPLOY_USER }}
+          DOCS_DEPLOY_BASE_DIR: ${{ secrets.DOCS_DEPLOY_BASE_DIR }}
+        run: |
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          ROOT_REDIRECT="${DOCS_DEPLOY_BASE_DIR}/root/redirect.conf"
+
+          if [[ "${{ inputs.line }}" == "v1" ]]; then
+            ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "mkdir -p '${DOCS_DEPLOY_BASE_DIR}/root' && echo 'set \\$root_target https://v1.element-plus-x.com;' > '$ROOT_REDIRECT'"
+          elif [[ "${{ inputs.line }}" == "v2" && "${{ inputs.is_prerelease }}" != "true" ]]; then
+            ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "mkdir -p '${DOCS_DEPLOY_BASE_DIR}/root' && echo 'set \\$root_target https://v2.element-plus-x.com;' > '$ROOT_REDIRECT'"
+          else
+            echo "Skipping root redirect update for prerelease line=${{ inputs.line }}"
+          fi
+
+      - name: Reload nginx
+        if: inputs.switch_current == 'true' || inputs.update_root_redirect == 'true'
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+          DOCS_DEPLOY_USER: ${{ secrets.DOCS_DEPLOY_USER }}
+        run: |
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "nginx -t && systemctl reload nginx"
diff --git a/.github/workflows/docs-deploy-verify.yaml b/.github/workflows/docs-deploy-verify.yaml
new file mode 100644
index 00000000..80abffe8
--- /dev/null
+++ b/.github/workflows/docs-deploy-verify.yaml
@@ -0,0 +1,128 @@
+name: Docs Deploy Verify
+
+on:
+  workflow_dispatch:
+    inputs:
+      line:
+        description: 'Docs line (v1 or v2)'
+        required: true
+        default: 'v2'
+        type: choice
+        options:
+          - v1
+          - v2
+      source_ref:
+        description: 'Git ref to build (branch or tag)'
+        required: true
+        default: 'refs/heads/updata-2602'
+        type: string
+      verify_id:
+        description: 'Verify directory suffix (defaults to run id)'
+        required: false
+        type: string
+
+concurrency:
+  group: docs-deploy-verify-${{ github.ref }}-${{ inputs.line }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-upload-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          npm i -g pnpm
+          pnpm install
+
+      - name: Resolve docs env
+        id: docs_env
+        run: |
+          if [[ "${{ inputs.line }}" == "v2" ]]; then
+            echo "PUBLIC_ORIGIN=https://v2.element-plus-x.com" >> $GITHUB_OUTPUT
+            echo "VERSION_LABEL=v2.x (Verify)" >> $GITHUB_OUTPUT
+          else
+            echo "PUBLIC_ORIGIN=https://v1.element-plus-x.com" >> $GITHUB_OUTPUT
+            echo "VERSION_LABEL=v1.x (Verify)" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Build docs
+        env:
+          DOCS_LINE: ${{ inputs.line }}
+          DOCS_PUBLIC_ORIGIN: ${{ steps.docs_env.outputs.PUBLIC_ORIGIN }}
+          DOCS_VERSION_LABEL: ${{ steps.docs_env.outputs.VERSION_LABEL }}
+          DOCS_V1_ORIGIN: https://v1.element-plus-x.com
+          DOCS_V2_ORIGIN: https://v2.element-plus-x.com
+          DOCS_ROOT_ORIGIN: https://element-plus-x.com
+          DOCS_USE_SOURCE: 'true'
+        run: pnpm run build:docs
+
+      - name: Resolve verify path
+        id: verify_path
+        env:
+          DOCS_DEPLOY_BASE_DIR: ${{ secrets.DOCS_DEPLOY_BASE_DIR }}
+        run: |
+          VERIFY_ID="${{ inputs.verify_id }}"
+          if [[ -z "$VERIFY_ID" ]]; then
+            VERIFY_ID="${{ github.run_id }}"
+          fi
+          REMOTE_DIR="${DOCS_DEPLOY_BASE_DIR}/verify/${{ inputs.line }}/$VERIFY_ID"
+          echo "VERIFY_ID=$VERIFY_ID" >> $GITHUB_OUTPUT
+          echo "REMOTE_DIR=$REMOTE_DIR" >> $GITHUB_OUTPUT
+
+      - name: Setup SSH
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.DOCS_DEPLOY_SSH_KEY }}
+
+      - name: Add deploy host to known_hosts
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+        run: |
+          mkdir -p ~/.ssh
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          ssh-keyscan -p "$PORT" -H "$DOCS_DEPLOY_HOST" >> ~/.ssh/known_hosts
+
+      - name: Upload verify build
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+          DOCS_DEPLOY_USER: ${{ secrets.DOCS_DEPLOY_USER }}
+        run: |
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          REMOTE_DIR="${{ steps.verify_path.outputs.REMOTE_DIR }}"
+
+          ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "mkdir -p '$REMOTE_DIR'"
+          rsync -az --delete -e "ssh -p $PORT" apps/docs/.vitepress/dist/ "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST:$REMOTE_DIR/"
+
+      - name: Verify remote artifacts
+        env:
+          DOCS_DEPLOY_HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+          DOCS_DEPLOY_PORT: ${{ secrets.DOCS_DEPLOY_PORT }}
+          DOCS_DEPLOY_USER: ${{ secrets.DOCS_DEPLOY_USER }}
+        run: |
+          PORT="${DOCS_DEPLOY_PORT:-22}"
+          REMOTE_DIR="${{ steps.verify_path.outputs.REMOTE_DIR }}"
+
+          ssh -p "$PORT" "$DOCS_DEPLOY_USER@$DOCS_DEPLOY_HOST" "\
+            test -d '$REMOTE_DIR' && \
+            test -f '$REMOTE_DIR/index.html' && \
+            (test -d '$REMOTE_DIR/assets' || test -d '$REMOTE_DIR/.vitepress')"
+
+      - name: Print verify target
+        run: |
+          echo "Docs verify upload completed."
+          echo "Remote path: ${{ steps.verify_path.outputs.REMOTE_DIR }}"
diff --git a/scripts/docs/README.md b/scripts/docs/README.md
new file mode 100644
index 00000000..ad7da7ea
--- /dev/null
+++ b/scripts/docs/README.md
@@ -0,0 +1,72 @@
+# Docs Deployment on Tencent Cloud (Lite Server)
+
+## DNS Records
+
+Create A records to your Tencent Cloud public IP:
+
+1. `element-plus-x.com`
+2. `v1.element-plus-x.com`
+3. `v2.element-plus-x.com`
+
+## Nginx Config
+
+1. Copy `scripts/docs/nginx/element-plus-x.conf` to `/etc/nginx/conf.d/element-plus-x.conf`.
+2. Create the redirect target file:
+
+```bash
+sudo mkdir -p /var/www/element-plus-x/root
+echo 'set $root_target https://v1.element-plus-x.com;' | sudo tee /var/www/element-plus-x/root/redirect.conf
+```
+
+3. Create base directories:
+
+```bash
+sudo mkdir -p /var/www/element-plus-x/v1/releases /var/www/element-plus-x/v2/releases
+sudo mkdir -p /var/www/element-plus-x/v1/current /var/www/element-plus-x/v2/current
+```
+
+4. Test and reload:
+
+```bash
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+## HTTPS (Recommended)
+
+Use Certbot to issue TLS certificates for the three domains. Example:
+
+```bash
+sudo apt update
+sudo apt install -y certbot python3-certbot-nginx
+sudo certbot --nginx -d element-plus-x.com -d v1.element-plus-x.com -d v2.element-plus-x.com
+```
+
+## GitHub Secrets Required
+
+Configure these secrets in the repo settings:
+
+1. `DOCS_DEPLOY_HOST`
+2. `DOCS_DEPLOY_PORT`
+3. `DOCS_DEPLOY_USER`
+4. `DOCS_DEPLOY_SSH_KEY`
+5. `DOCS_DEPLOY_BASE_DIR` (suggested: `/var/www/element-plus-x`)
+
+## Workflows
+
+### Docs Deploy Verify
+
+Use the `Docs Deploy Verify` workflow for the first end-to-end server test.
+
+- Trigger it manually from the default branch.
+- Point `source_ref` to the branch or tag you want to build.
+- It uploads to `${DOCS_DEPLOY_BASE_DIR}/verify/<line>/<verify_id>`.
+- It does not switch `current`, does not change `root/redirect.conf`, and does not reload nginx.
+
+### Docs Release
+
+Use the `Docs Release` workflow for release uploads and cutover.
+
+- `switch_current=false` uploads the release without switching live traffic.
+- `switch_current=true` updates the `<line>/current` symlink.
+- `update_root_redirect=true` updates the root domain redirect when the release should become the default docs line.

From be87f977a5b182c036ccb7ba87e7693273764c68 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BD=95=E5=98=89=E6=82=A6?= <2834007710@qq.com>
Date: Tue, 10 Mar 2026 22:23:51 +0800
Subject: [PATCH 2/2] ci(docs): pass github token to docs workflows

---
 .github/workflows/deploy-docs.yaml        | 2 ++
 .github/workflows/docs-deploy-verify.yaml | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 6f497a19..8d22c570 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -96,6 +96,8 @@ jobs:
           DOCS_V2_ORIGIN: https://v2.element-plus-x.com
           DOCS_ROOT_ORIGIN: https://element-plus-x.com
           DOCS_USE_SOURCE: 'true'
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: pnpm run build:docs
 
       - name: Setup SSH
diff --git a/.github/workflows/docs-deploy-verify.yaml b/.github/workflows/docs-deploy-verify.yaml
index 80abffe8..aa9c77d0 100644
--- a/.github/workflows/docs-deploy-verify.yaml
+++ b/.github/workflows/docs-deploy-verify.yaml
@@ -67,6 +67,8 @@ jobs:
           DOCS_V2_ORIGIN: https://v2.element-plus-x.com
           DOCS_ROOT_ORIGIN: https://element-plus-x.com
           DOCS_USE_SOURCE: 'true'
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: pnpm run build:docs
 
       - name: Resolve verify path