Address PR review feedback

fix: correct index preview form layout

.github/scripts/deploy_windows_winrm.py

@@ -29,13 +29,18 @@ def main() -> int:
     port = optional_env("KK_DEPLOY_PORT", "5985")
     username = require_env("KK_DEPLOY_USERNAME")
     password = require_env("KK_DEPLOY_PASSWORD")
-    deploy_root = optional_env("KK_DEPLOY_ROOT", r"C:\kkFileView-5.0")
-    health_url = optional_env("KK_DEPLOY_HEALTH_URL", "http://127.0.0.1:8012/")
-    artifact_name = optional_env("KK_DEPLOY_ARTIFACT_NAME", "kkfileview-server-jar")
-    repository = require_env("GITHUB_REPOSITORY_NAME")
-    run_id = require_env("GITHUB_RUN_ID_VALUE")
-    artifact_token = require_env("KK_DEPLOY_ARTIFACT_TOKEN")
-    dry_run = optional_env("KK_DEPLOY_DRY_RUN", "false").lower()
+    env_pairs = {
+        "KK_DEPLOY_ROOT": optional_env("KK_DEPLOY_ROOT", r"C:\kkFileView-5.0"),
+        "KK_DEPLOY_HEALTH_URL": optional_env("KK_DEPLOY_HEALTH_URL", "http://127.0.0.1:8012/"),
+        "KK_DEPLOY_REPO_URL": optional_env("KK_DEPLOY_REPO_URL", "https://github.com/kekingcn/kkFileView.git"),
+        "KK_DEPLOY_BRANCH": optional_env("KK_DEPLOY_BRANCH", "master"),
+        "KK_DEPLOY_SOURCE_ROOT": optional_env("KK_DEPLOY_SOURCE_ROOT", r"C:\kkFileView-source"),
+        "KK_DEPLOY_JAVA_HOME": optional_env("KK_DEPLOY_JAVA_HOME", r"C:\Program Files\jdk-21.0.2"),
+        "KK_DEPLOY_GIT_EXE": optional_env("KK_DEPLOY_GIT_EXE", r"C:\kkFileView-tools\git\cmd\git.exe"),
+        "KK_DEPLOY_MVN_CMD": optional_env("KK_DEPLOY_MVN_CMD", r"C:\kkFileView-tools\maven\bin\mvn.cmd"),
+        "KK_DEPLOY_MAVEN_SETTINGS": optional_env("KK_DEPLOY_MAVEN_SETTINGS", ""),
+        "KK_DEPLOY_DRY_RUN": optional_env("KK_DEPLOY_DRY_RUN", "false").lower(),
+    }
 
     script_path = pathlib.Path(__file__).with_name("remote_windows_deploy.ps1")
     script_body = script_path.read_text(encoding="utf-8")
@@ -77,16 +82,19 @@ $ErrorActionPreference = 'Stop'
 $raw = Get-Content -LiteralPath '{ps_quote(remote_b64_path)}' -Raw
 [System.IO.File]::WriteAllBytes('{ps_quote(remote_ps1_path)}', [Convert]::FromBase64String($raw))
 try {{
+"""
+        + "\n".join(
+            f"  $env:{key} = '{ps_quote(value)}'" for key, value in env_pairs.items()
+        )
+        + f"""
   powershell -NoProfile -ExecutionPolicy Bypass -File '{ps_quote(remote_ps1_path)}' `
-    -Repository '{ps_quote(repository)}' `
-    -RunId '{ps_quote(run_id)}' `
-    -ArtifactName '{ps_quote(artifact_name)}' `
-    -GitHubToken '{ps_quote(artifact_token)}' `
-    -DeployRoot '{ps_quote(deploy_root)}' `
-    -HealthUrl '{ps_quote(health_url)}' `
-    -DryRun '{ps_quote(dry_run)}'
   $code = $LASTEXITCODE
 }} finally {{
+"""
+        + "\n".join(
+            f"  Remove-Item Env:{key} -ErrorAction SilentlyContinue" for key in env_pairs
+        )
+        + f"""
   Remove-Item '{ps_quote(remote_b64_path)}' -Force -ErrorAction SilentlyContinue
   Remove-Item '{ps_quote(remote_ps1_path)}' -Force -ErrorAction SilentlyContinue
 }}

.github/scripts/remote_windows_deploy.ps1

@@ -1,26 +1,52 @@
-param(
-    [Parameter(Mandatory = $true)][string]$Repository,
-    [Parameter(Mandatory = $true)][string]$RunId,
-    [Parameter(Mandatory = $true)][string]$ArtifactName,
-    [Parameter(Mandatory = $true)][string]$GitHubToken,
-    [Parameter(Mandatory = $true)][string]$DeployRoot,
-    [Parameter(Mandatory = $true)][string]$HealthUrl,
-    [string]$DryRun = 'false'
-)
-
 $ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
 
 function Write-Step {
     param([string]$Message)
     Write-Host "==> $Message"
 }
 
+function Get-RequiredEnv {
+    param([string]$Name)
+
+    $Value = [Environment]::GetEnvironmentVariable($Name)
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        throw "Missing required environment variable: $Name"
+    }
+
+    return $Value
+}
+
+function Get-OptionalEnv {
+    param(
+        [string]$Name,
+        [string]$DefaultValue
+    )
+
+    $Value = [Environment]::GetEnvironmentVariable($Name)
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $DefaultValue
+    }
+
+    return $Value
+}
+
+$DeployRoot = Get-OptionalEnv 'KK_DEPLOY_ROOT' 'C:\kkFileView-5.0'
+$HealthUrl = Get-OptionalEnv 'KK_DEPLOY_HEALTH_URL' 'http://127.0.0.1:8012/'
+$RepoUrl = Get-OptionalEnv 'KK_DEPLOY_REPO_URL' 'https://github.com/kekingcn/kkFileView.git'
+$Branch = Get-OptionalEnv 'KK_DEPLOY_BRANCH' 'master'
+$SourceRoot = Get-OptionalEnv 'KK_DEPLOY_SOURCE_ROOT' 'C:\kkFileView-source'
+$JavaHome = Get-OptionalEnv 'KK_DEPLOY_JAVA_HOME' 'C:\Program Files\jdk-21.0.2'
+$GitExe = Get-OptionalEnv 'KK_DEPLOY_GIT_EXE' 'C:\kkFileView-tools\git\cmd\git.exe'
+$MvnCmd = Get-OptionalEnv 'KK_DEPLOY_MVN_CMD' 'C:\kkFileView-tools\maven\bin\mvn.cmd'
+$MavenSettings = Get-OptionalEnv 'KK_DEPLOY_MAVEN_SETTINGS' ''
+$DryRun = Get-OptionalEnv 'KK_DEPLOY_DRY_RUN' 'false'
+
 $BinDir = Join-Path $DeployRoot 'bin'
 $StartupScript = Join-Path $BinDir 'startup.bat'
 $ReleaseDir = Join-Path $DeployRoot 'releases'
 $DeployTmp = Join-Path $DeployRoot 'deploy-tmp'
-$ArtifactZip = Join-Path $DeployTmp 'artifact.zip'
-$ExtractDir = Join-Path $DeployTmp 'artifact'
+$BuildOutputDir = Join-Path (Join-Path $SourceRoot 'server') 'target'
 
 if (-not (Test-Path $DeployRoot)) {
     throw "Deploy root not found: $DeployRoot"
@@ -39,6 +65,23 @@ if (-not $CurrentJar) {
     throw "No kkFileView jar found in $BinDir"
 }
 
+$JavaExe = Join-Path $JavaHome 'bin\java.exe'
+if (-not (Test-Path $JavaExe)) {
+    throw "JDK 21 java executable not found: $JavaExe"
+}
+
+if (-not (Test-Path $GitExe)) {
+    throw "Git executable not found: $GitExe"
+}
+
+if (-not (Test-Path $MvnCmd)) {
+    throw "Maven executable not found: $MvnCmd"
+}
+
+if (-not [string]::IsNullOrWhiteSpace($MavenSettings) -and -not (Test-Path $MavenSettings)) {
+    throw "Maven settings file not found: $MavenSettings"
+}
+
 $JarName = $CurrentJar.Name
 $JarPath = $CurrentJar.FullName
 
@@ -46,6 +89,74 @@ Write-Step "Deploy root: $DeployRoot"
 Write-Step "Current jar: $JarPath"
 Write-Step "Startup script: $StartupScript"
 Write-Step "Health url: $HealthUrl"
+Write-Step "Source root: $SourceRoot"
+Write-Step "Branch: $Branch"
+Write-Step "Git exe: $GitExe"
+Write-Step "Maven cmd: $MvnCmd"
+Write-Step "Java home: $JavaHome"
+if (-not [string]::IsNullOrWhiteSpace($MavenSettings)) {
+    Write-Step "Maven settings: $MavenSettings"
+}
+
+function Invoke-External {
+    param(
+        [string]$FilePath,
+        [string[]]$Arguments,
+        [string]$WorkingDirectory = $null
+    )
+
+    $previous = $null
+    if ($WorkingDirectory) {
+        $previous = Get-Location
+        Set-Location $WorkingDirectory
+    }
+
+    try {
+        & $FilePath @Arguments
+        if ($LASTEXITCODE -ne 0) {
+            throw "Command failed ($LASTEXITCODE): $FilePath $($Arguments -join ' ')"
+        }
+    } finally {
+        if ($previous) {
+            Set-Location $previous
+        }
+    }
+}
+
+function Assert-SafeSourceRoot {
+    param([string]$PathToCheck)
+
+    $FullPath = [System.IO.Path]::GetFullPath($PathToCheck)
+    $RootPath = [System.IO.Path]::GetPathRoot($FullPath)
+    if ($FullPath.TrimEnd('\') -eq $RootPath.TrimEnd('\')) {
+        throw "Refusing to use drive root as source root: $FullPath"
+    }
+
+    $DangerousLeafNames = @(
+        'Windows',
+        'Users',
+        'Program Files',
+        'Program Files (x86)',
+        'ProgramData'
+    )
+    $LeafName = Split-Path -Leaf $FullPath.TrimEnd('\')
+    if ($DangerousLeafNames -contains $LeafName) {
+        throw "Refusing to use a high-risk source root path: $FullPath"
+    }
+}
+
+$env:JAVA_HOME = $JavaHome
+$env:Path = (Join-Path $JavaHome 'bin') + ';' + (Split-Path -Parent $GitExe) + ';' + (Split-Path -Parent $MvnCmd) + ';' + $env:Path
+
+Write-Step 'Validating Git executable'
+Invoke-External -FilePath $GitExe -Arguments @('--version')
+
+Write-Step 'Validating Maven executable'
+$MavenVersionArgs = @('-version')
+if (-not [string]::IsNullOrWhiteSpace($MavenSettings)) {
+    $MavenVersionArgs = @('-s', $MavenSettings, '-version')
+}
+Invoke-External -FilePath $MvnCmd -Arguments $MavenVersionArgs
 
 if ($DryRun -eq 'true') {
     Write-Step "Dry run enabled, remote validation finished"
@@ -55,41 +166,51 @@ if ($DryRun -eq 'true') {
 New-Item -ItemType Directory -Force -Path $ReleaseDir | Out-Null
 New-Item -ItemType Directory -Force -Path $DeployTmp | Out-Null
 
-if (Test-Path $ArtifactZip) {
-    Remove-Item $ArtifactZip -Force
+function Sync-Repository {
+    Assert-SafeSourceRoot -PathToCheck $SourceRoot
+
+    if (-not (Test-Path (Join-Path $SourceRoot '.git'))) {
+        if (Test-Path $SourceRoot) {
+            Remove-Item $SourceRoot -Recurse -Force
+        }
+
+        $parent = Split-Path -Parent $SourceRoot
+        if ($parent) {
+            New-Item -ItemType Directory -Force -Path $parent | Out-Null
+        }
+
+        Write-Step "Cloning repository from $RepoUrl"
+        Invoke-External -FilePath $GitExe -Arguments @('clone', '--depth', '1', '--branch', $Branch, '--single-branch', $RepoUrl, $SourceRoot)
+        return
+    }
+
+    Write-Step "Fetching latest branch state from origin/$Branch"
+    Invoke-External -FilePath $GitExe -Arguments @('remote', 'set-url', 'origin', $RepoUrl) -WorkingDirectory $SourceRoot
+    Invoke-External -FilePath $GitExe -Arguments @('fetch', '--prune', '--depth', '1', 'origin', $Branch) -WorkingDirectory $SourceRoot
+    Invoke-External -FilePath $GitExe -Arguments @('checkout', '-B', $Branch, "origin/$Branch") -WorkingDirectory $SourceRoot
+    Invoke-External -FilePath $GitExe -Arguments @('reset', '--hard', "origin/$Branch") -WorkingDirectory $SourceRoot
+    Invoke-External -FilePath $GitExe -Arguments @('clean', '-fd') -WorkingDirectory $SourceRoot
 }
 
-if (Test-Path $ExtractDir) {
-    Remove-Item $ExtractDir -Recurse -Force
+function Build-KkFileView {
+    Write-Step 'Building kkFileView from source'
+    $BuildArgs = @('-B', 'clean', 'package', '-Dmaven.test.skip=true', '--file', 'pom.xml')
+    if (-not [string]::IsNullOrWhiteSpace($MavenSettings)) {
+        $BuildArgs = @('-s', $MavenSettings) + $BuildArgs
+    }
+    Invoke-External -FilePath $MvnCmd -Arguments $BuildArgs -WorkingDirectory $SourceRoot
 }
 
-$Headers = @{
-    Authorization = "Bearer $GitHubToken"
-    Accept = "application/vnd.github+json"
-    "X-GitHub-Api-Version" = "2022-11-28"
-    "User-Agent" = "kkFileView-auto-deploy"
-}
+Sync-Repository
+Build-KkFileView
 
-$ArtifactsApi = "https://api.github.com/repos/$Repository/actions/runs/$RunId/artifacts"
-Write-Step "Resolving workflow artifact: $ArtifactName"
-$ArtifactsResponse = Invoke-RestMethod -Headers $Headers -Uri $ArtifactsApi -Method Get
-$Artifact = $ArtifactsResponse.artifacts | Where-Object { $_.name -eq $ArtifactName } | Select-Object -First 1
-
-if (-not $Artifact) {
-    throw "Artifact '$ArtifactName' not found for workflow run $RunId"
-}
-
-Write-Step "Downloading artifact from GitHub Actions"
-Invoke-WebRequest -Headers $Headers -Uri $Artifact.archive_download_url -OutFile $ArtifactZip
-Expand-Archive -LiteralPath $ArtifactZip -DestinationPath $ExtractDir -Force
-
-$DownloadedJars = Get-ChildItem $ExtractDir -Filter 'kkFileView-*.jar' -Recurse
+$DownloadedJars = Get-ChildItem $BuildOutputDir -Filter 'kkFileView-*.jar' -File
 if (-not $DownloadedJars) {
-    throw "No kkFileView jar found inside artifact '$ArtifactName'"
+    throw "No kkFileView jar found in build output: $BuildOutputDir"
 }
 
 if ($DownloadedJars.Count -ne 1) {
-    throw "Expected exactly one kkFileView jar inside artifact '$ArtifactName', found $($DownloadedJars.Count)"
+    throw "Expected exactly one kkFileView jar in build output, found $($DownloadedJars.Count)"
 }
 
 $DownloadedJar = $DownloadedJars[0]
@@ -98,27 +219,33 @@ $Timestamp = Get-Date -Format 'yyyyMMddHHmmss'
 $BackupJar = Join-Path $ReleaseDir ("{0}.{1}.bak" -f $JarName, $Timestamp)
 
 function Stop-KkFileView {
+    foreach ($Process in @(Get-KkFileViewJavaProcesses) + @(Get-KkFileViewLauncherProcesses)) {
+        Write-Step "Stopping process $($Process.ProcessId)"
+        Stop-Process -Id $Process.ProcessId -Force -ErrorAction SilentlyContinue
+    }
+}
+
+function Get-KkFileViewJavaProcesses {
     $JarPattern = [regex]::Escape($JarName)
-    $Processes = Get-CimInstance Win32_Process | Where-Object {
+    return Get-CimInstance Win32_Process | Where-Object {
         $_.Name -match '^java(\.exe)?$' -and $_.CommandLine -and $_.CommandLine -match $JarPattern
     }
+}
 
-    foreach ($Process in $Processes) {
-        Write-Step "Stopping java process $($Process.ProcessId)"
-        Stop-Process -Id $Process.ProcessId -Force -ErrorAction SilentlyContinue
+function Get-KkFileViewLauncherProcesses {
+    $StartupPattern = [regex]::Escape([System.IO.Path]::GetFileName($StartupScript))
+    return Get-CimInstance Win32_Process | Where-Object {
+        $_.Name -ieq 'cmd.exe' -and $_.CommandLine -and $_.CommandLine -match $StartupPattern
     }
 }
 
 function Wait-KkFileViewStopped {
     param([int]$TimeoutSeconds = 30)
 
-    $JarPattern = [regex]::Escape($JarName)
     for ($i = 0; $i -lt $TimeoutSeconds; $i++) {
-        $Processes = Get-CimInstance Win32_Process | Where-Object {
-            $_.Name -match '^java(\.exe)?$' -and $_.CommandLine -and $_.CommandLine -match $JarPattern
-        }
-
-        if (-not $Processes) {
+        $JavaProcesses = @(Get-KkFileViewJavaProcesses)
+        $CmdProcesses = @(Get-KkFileViewLauncherProcesses)
+        if ((@($JavaProcesses).Count + @($CmdProcesses).Count) -eq 0) {
             return $true
         }
 
@@ -130,20 +257,37 @@ function Wait-KkFileViewStopped {
 
 function Start-KkFileView {
     Write-Step "Starting kkFileView"
-    Start-Process -FilePath 'cmd.exe' -ArgumentList '/c', "`"$StartupScript`"" -WorkingDirectory $BinDir -WindowStyle Hidden
+    $CreateResult = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
+        CommandLine = ('cmd.exe /c ""' + $StartupScript + '""')
+        CurrentDirectory = $BinDir
+    }
+
+    if ($CreateResult.ReturnValue -ne 0) {
+        throw "Failed to start kkFileView launcher, Win32_Process.Create returned $($CreateResult.ReturnValue)"
+    }
+
+    Write-Step "Launcher process created with pid $($CreateResult.ProcessId)"
 }
 
 function Wait-Health {
     param([string]$Url)
 
+    $SuccessfulChecks = 0
     for ($i = 0; $i -lt 24; $i++) {
         Start-Sleep -Seconds 5
         try {
             $Response = Invoke-WebRequest -Uri $Url -UseBasicParsing -TimeoutSec 5
-            if ($Response.StatusCode -eq 200) {
+            if ($Response.StatusCode -eq 200 -and @(Get-KkFileViewJavaProcesses).Count -gt 0) {
+                $SuccessfulChecks++
+            } else {
+                $SuccessfulChecks = 0
+            }
+
+            if ($SuccessfulChecks -ge 3) {
                 return $true
             }
         } catch {
+            $SuccessfulChecks = 0
             Start-Sleep -Milliseconds 200
         }
     }

.github/workflows/master-auto-deploy.yml

@@ -11,47 +11,24 @@ concurrency:
 
 permissions:
   contents: read
-  actions: read
 
 jobs:
-  build:
-    runs-on: ubuntu-22.04
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@v4
-        with:
-          java-version: '21'
-          distribution: temurin
-          cache: maven
-
-      - name: Build with Maven
-        run: mvn -B package -Dmaven.test.skip=true --file pom.xml
-
-      - name: Upload server jar artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: kkfileview-server-jar
-          path: server/target/kkFileView-*.jar
-          retention-days: 7
-
   deploy-windows:
-    needs: build
     runs-on: ubuntu-22.04
     env:
-      GITHUB_REPOSITORY_NAME: ${{ github.repository }}
-      GITHUB_RUN_ID_VALUE: ${{ github.run_id }}
-      KK_DEPLOY_ARTIFACT_TOKEN: ${{ secrets.KK_DEPLOY_ARTIFACT_TOKEN }}
       KK_DEPLOY_HOST: ${{ secrets.KK_DEPLOY_HOST }}
       KK_DEPLOY_PORT: ${{ secrets.KK_DEPLOY_PORT }}
       KK_DEPLOY_USERNAME: ${{ secrets.KK_DEPLOY_USERNAME }}
       KK_DEPLOY_PASSWORD: ${{ secrets.KK_DEPLOY_PASSWORD }}
       KK_DEPLOY_ROOT: ${{ secrets.KK_DEPLOY_ROOT }}
       KK_DEPLOY_HEALTH_URL: ${{ secrets.KK_DEPLOY_HEALTH_URL }}
-      KK_DEPLOY_ARTIFACT_NAME: kkfileview-server-jar
+      KK_DEPLOY_REPO_URL: ${{ vars.KK_DEPLOY_REPO_URL }}
+      KK_DEPLOY_BRANCH: ${{ vars.KK_DEPLOY_BRANCH }}
+      KK_DEPLOY_SOURCE_ROOT: ${{ vars.KK_DEPLOY_SOURCE_ROOT }}
+      KK_DEPLOY_JAVA_HOME: ${{ vars.KK_DEPLOY_JAVA_HOME }}
+      KK_DEPLOY_GIT_EXE: ${{ vars.KK_DEPLOY_GIT_EXE }}
+      KK_DEPLOY_MVN_CMD: ${{ vars.KK_DEPLOY_MVN_CMD }}
+      KK_DEPLOY_MAVEN_SETTINGS: ${{ vars.KK_DEPLOY_MAVEN_SETTINGS }}
 
     steps:
       - name: Checkout repository
@@ -67,7 +44,6 @@ jobs:
 
       - name: Validate deploy secrets
         run: |
-          test -n "$KK_DEPLOY_ARTIFACT_TOKEN" || (echo "Missing secret: KK_DEPLOY_ARTIFACT_TOKEN" && exit 1)
           test -n "$KK_DEPLOY_HOST" || (echo "Missing secret: KK_DEPLOY_HOST" && exit 1)
           test -n "$KK_DEPLOY_USERNAME" || (echo "Missing secret: KK_DEPLOY_USERNAME" && exit 1)
           test -n "$KK_DEPLOY_PASSWORD" || (echo "Missing secret: KK_DEPLOY_PASSWORD" && exit 1)

.gitignore

@@ -26,6 +26,7 @@ nbdist/
 ### VS Code ###
 .vscode/
 .DS_Store
+.artifacts/
 
 server/src/main/cache/
 server/src/main/file/

doc/ci-auto-deploy.md

@@ -8,34 +8,50 @@
 - 运行配置：`C:\kkFileView-5.0\config\test.properties`
 - 健康检查地址：`http://127.0.0.1:8012/`
 
-服务器当前没有安装 `git` 和 `mvn`，因此自动部署链路采用：
+当前自动部署链路采用服务器拉最新源码并本机编译的方式：
 
-1. GitHub Actions 在 `master` 合并后构建 `kkFileView-*.jar`
-2. 通过 WinRM 连接 Windows 服务器
-3. 由服务器从当前 workflow run 下载 jar artifact
-4. 备份线上 jar，替换为新版本
+1. 通过 WinRM 连接 Windows 服务器
+2. 在服务器上的源码目录执行 `git fetch/reset/clean`，同步到 `origin/$KK_DEPLOY_BRANCH`（默认 `master`）
+3. 使用服务器上的 JDK 21 和 Maven 执行 `mvn clean package -Dmaven.test.skip=true`
+4. 备份线上 jar，替换为新构建产物
 5. 使用现有 `startup.bat` 重启，并做健康检查
 6. 如果健康检查失败，则自动回滚旧 jar 并重新拉起
 
 ## 需要配置的 GitHub Secrets
 
 - `KK_DEPLOY_HOST`
-- `KK_DEPLOY_ARTIFACT_TOKEN`
 - `KK_DEPLOY_USERNAME`
 - `KK_DEPLOY_PASSWORD`
 
-下面这些可以不配，未配置时会使用默认值：
+以下部署参数当前由 workflow 从 GitHub Secrets 读取；如果未单独配置，则使用脚本默认值：
 
 - `KK_DEPLOY_PORT=5985`
 - `KK_DEPLOY_ROOT=C:\kkFileView-5.0`
 - `KK_DEPLOY_HEALTH_URL=http://127.0.0.1:8012/`
 
-其中 `KK_DEPLOY_ARTIFACT_TOKEN` 建议使用单独的细粒度 token，只授予当前仓库所需的最小读取权限，不要复用默认 `GITHUB_TOKEN` 到生产服务器。
+下面这些非敏感参数可以通过 workflow env 或 GitHub Variables 覆盖；未配置时会使用默认值：
+- `KK_DEPLOY_REPO_URL=https://github.com/kekingcn/kkFileView.git`
+- `KK_DEPLOY_BRANCH=master`
+- `KK_DEPLOY_SOURCE_ROOT=C:\kkFileView-source`
+- `KK_DEPLOY_JAVA_HOME=C:\Program Files\jdk-21.0.2`
+- `KK_DEPLOY_GIT_EXE=C:\kkFileView-tools\git\cmd\git.exe`
+- `KK_DEPLOY_MVN_CMD=C:\kkFileView-tools\maven\bin\mvn.cmd`
+- `KK_DEPLOY_MAVEN_SETTINGS=`
+
+如果服务器到 GitHub 的拉取速度不稳定，也可以把 `KK_DEPLOY_REPO_URL` 改成你自己的 Git 镜像地址。
+如果服务器访问 Maven Central 不稳定，也可以通过 `KK_DEPLOY_MAVEN_SETTINGS` 指向自定义 `settings.xml`，切换到就近镜像仓库。
+
+## 服务器前置环境
+
+服务器需要具备以下工具：
+
+- Git for Windows（推荐安装在 `C:\kkFileView-tools\git`）
+- Apache Maven 3.9.x（推荐安装在 `C:\kkFileView-tools\maven`）
+- JDK 21（当前线上已存在：`C:\Program Files\jdk-21.0.2`）
 
 ## Workflow
 
 新增 workflow：`.github/workflows/master-auto-deploy.yml`
 
 - 触发条件：`push` 到 `master`，或手动 `workflow_dispatch`
-- 构建产物：`kkfileview-server-jar`
-- 部署方式：WinRM + GitHub Actions artifact 下载
+- 部署方式：WinRM + 服务器源码同步 + 服务器本机 Maven 编译 + jar 替换/回滚

server/src/main/config/application.properties

@@ -97,11 +97,11 @@ office.type.web = ${KK_OFFICE_TYPE_WEB:web}
 
 # Office文档预览类型
 # 支持动态配置，可选值：image/pdf
-office.preview.type = ${KK_OFFICE_PREVIEW_TYPE:image}
+office.preview.type = ${KK_OFFICE_PREVIEW_TYPE:pdf}
 
 # 是否关闭Office预览模式切换开关，默认为false（允许切换）
 # 设置为true时，用户无法在图片和PDF模式间切换
-office.preview.switch.disabled = ${KK_OFFICE_PREVIEW_SWITCH_DISABLED:false}
+office.preview.switch.disabled = ${KK_OFFICE_PREVIEW_SWITCH_DISABLED:true}
 
 
 ###############################################################################
@@ -475,4 +475,4 @@ kk.scriptjs = true
 ###############################################################################
 
 # 纯文本文件类型，直接显示
-simText = ${KK_SIMTEXT:txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd}
+simText = ${KK_SIMTEXT:txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd}

server/src/main/java/cn/keking/service/CompressFileReader.java

@@ -59,21 +59,26 @@ public class CompressFileReader {
             for (final ISimpleInArchiveItem item : simpleInArchive.getArchiveItems()) {
                 if (!item.isFolder()) {
                     final Path filePathInsideArchive = getFilePathInsideArchive(item, folderPath);
-                    ExtractOperationResult result = item.extractSlow(data -> {
-                        try (OutputStream out = new BufferedOutputStream(new FileOutputStream(filePathInsideArchive.toFile(), true))) {
-                            out.write(data);
-                        } catch (IOException e) {
-                            throw new RuntimeException(e);
-                        }
-                        return data.length;
-                    }, filePassword);
-                    if (result != ExtractOperationResult.OK) {
-                        ExtractOperationResult result1 = ExtractOperationResult.valueOf("WRONG_PASSWORD");
-                        if (result1.equals(result)) {
-                            throw new Exception("Password");
-                        }else {
-                            throw new Exception("Failed to extract RAR file.");
+                    Files.deleteIfExists(filePathInsideArchive);
+                    try (OutputStream out = new BufferedOutputStream(new FileOutputStream(filePathInsideArchive.toFile(), false))) {
+                        ExtractOperationResult result = item.extractSlow(data -> {
+                            try {
+                                out.write(data);
+                            } catch (IOException e) {
+                                throw new RuntimeException(e);
+                            }
+                            return data.length;
+                        }, filePassword);
+                        if (result != ExtractOperationResult.OK) {
+                            ExtractOperationResult result1 = ExtractOperationResult.valueOf("WRONG_PASSWORD");
+                            if (result1.equals(result)) {
+                                throw new Exception("Password");
+                            } else {
+                                throw new Exception("Failed to extract RAR file.");
+                            }
                         }
+                    } catch (IOException e) {
+                        throw new RuntimeException(e);
                     }
 
                     FileType type = FileType.typeFromUrl(filePathInsideArchive.toString());
@@ -110,4 +115,4 @@ public class CompressFileReader {
     }
 
 
-}
+}

server/src/main/java/cn/keking/service/impl/OfficeFilePreviewImpl.java

@@ -348,4 +348,4 @@ public class OfficeFilePreviewImpl implements FilePreview {
         }
         return null;
     }
-}
+}

server/src/main/resources/static/css/main-pages.css

@@ -547,28 +547,31 @@ a:focus {
 }
 
 .preview-options {
-    display: flex;
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
     align-items: center;
     gap: 12px;
     margin-bottom: 14px;
-    overflow-x: auto;
-    padding-bottom: 4px;
+    overflow: visible;
+    padding-bottom: 0;
 }
 
 .preview-grid {
-    display: flex;
-    flex-wrap: nowrap;
+    display: grid;
+    grid-template-columns: repeat(5, minmax(108px, 1fr));
     gap: 12px;
     margin-bottom: 0;
     overflow: visible;
     padding-bottom: 0;
-    flex: 1 1 auto;
-    min-width: 620px;
+    min-width: 0;
+    width: 100%;
 }
 
 .preview-grid .form-control {
-    flex: 1 1 0;
-    min-width: 150px;
+    width: 100%;
+    min-width: 0;
+    padding-left: 16px;
+    padding-right: 16px;
 }
 
 .preview-switches {
@@ -578,7 +581,7 @@ a:focus {
     margin-bottom: 0;
     overflow: visible;
     padding-bottom: 0;
-    flex: 0 0 auto;
+    width: 100%;
 }
 
 .preview-switches label {
@@ -586,7 +589,7 @@ a:focus {
     align-items: center;
     gap: 8px;
     margin: 0;
-    padding: 10px 14px;
+    padding: 10px 12px;
     border-radius: 999px;
     background: rgba(255, 255, 255, 0.76);
     border: 1px solid rgba(17, 19, 21, 0.08);
@@ -1264,6 +1267,10 @@ a:focus {
     .archive-grid {
         grid-template-columns: repeat(2, minmax(0, 1fr));
     }
+
+    .preview-grid {
+        grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+    }
 }
 
 @media (max-width: 768px) {
@@ -1304,16 +1311,8 @@ a:focus {
         grid-template-columns: 1fr;
     }
 
-    .preview-grid {
-        flex-wrap: wrap;
-        min-width: 0;
-        overflow-x: visible;
-    }
-
     .preview-options {
-        display: block;
-        overflow-x: visible;
-        padding-bottom: 0;
+        grid-template-columns: 1fr;
     }
 
     .preview-url {

server/src/main/resources/web/main/index.ftl

@@ -12,7 +12,7 @@
     <link rel="stylesheet" href="bootstrap/css/bootstrap.min.css"/>
     <link rel="stylesheet" href="bootstrap-table/bootstrap-table.min.css"/>
     <link rel="stylesheet" href="css/theme.css"/>
-    <link rel="stylesheet" href="css/main-pages.css?v=v1-polish-20260411-3"/>
+    <link rel="stylesheet" href="css/main-pages.css?v=v1-polish-20260411-5"/>
     <script type="text/javascript" src="js/jquery-3.6.1.min.js"></script>
     <script type="text/javascript" src="js/jquery.form.min.js"></script>
     <script type="text/javascript" src="bootstrap/js/bootstrap.min.js"></script>
@@ -493,8 +493,8 @@
             search: false,
             searchOnEnterKey: false,
             showSearchButton: false,
-            showRefresh: true,
-            showColumns: true,
+            showRefresh: false,
+            showColumns: false,
             clickToSelect: true,
             locale: 'zh-CN',
             columns: [{

server/src/main/resources/web/pdf.ftl

@@ -27,7 +27,7 @@
     if (kkagent === 'true' || !url.startsWith(baseUrl)) {
        url = baseUrl + 'getCorsFile?urlPath=' + encodeURIComponent(Base64.encode(url))+ "&key=${kkkey}";
     }
-    document.getElementsByTagName('iframe')[0].src = "${baseUrl}pdfjs/web/viewer.html?file=" + encodeURIComponent(url) + "&disablepresentationmode=${pdfPresentationModeDisable}&disableopenfile=${pdfOpenFileDisable}&disableprint=${pdfPrintDisable}&disabledownload=${pdfDownloadDisable}&disablebookmark=${pdfBookmarkDisable}&disableediting=${pdfDisableEditing}";
+    document.getElementsByTagName('iframe')[0].src = "${baseUrl}pdfjs/web/viewer.html?file=" + encodeURIComponent(url) + "&disablepresentationmode=${pdfPresentationModeDisable}&disableopenfile=${pdfOpenFileDisable}&disableprint=${pdfPrintDisable}&disabledownload=${pdfDownloadDisable}&disablebookmark=${pdfBookmarkDisable}&disableediting=${pdfDisableEditing}#page=1&pagemode=thumbs";
     document.getElementsByTagName('iframe')[0].height = document.documentElement.clientHeight - 10;
     /**
      * 页面变化调整高度

server/src/main/resources/web/picture.ftl

@@ -9,7 +9,15 @@
     <script src="js/base64.min.js"></script>
     <style>
         body {
-            background-color: #404040;
+            background-color: #f1f3f5;
+        }
+        .viewer-container:focus {
+            outline: none !important;
+        }
+        .viewer-container:focus-visible {
+            outline: 2px solid rgba(95, 107, 122, 0.65) !important;
+            outline-offset: 2px;
+            box-shadow: 0 0 0 4px rgba(95, 107, 122, 0.14);
         }
         #image { width: 800px; margin: 0 auto; font-size: 0;}
         #image li {  display: inline-block;width: 50px;height: 50px; margin-left: 1%; padding-top: 1%;}
@@ -77,4 +85,4 @@
     }
 </script>
 </body>
-</html>
+</html>

server/src/test/java/cn/keking/PdfViewerCompatibilityTests.java

@@ -26,6 +26,20 @@ public class PdfViewerCompatibilityTests {
         assertTrue(workerScript.contains("import \"../web/compatibility.mjs\";"));
     }
 
+    @Test
+    void shouldOpenPdfPreviewWithThumbnailSidebarByDefault() throws IOException {
+        String pdfTemplate = readResource("/web/pdf.ftl");
+
+        assertTrue(pdfTemplate.contains("#page=1&pagemode=thumbs"));
+    }
+
+    @Test
+    void shouldPreferPdfForOfficePreviewByDefault() throws IOException {
+        String properties = readResource("/application.properties");
+
+        assertTrue(properties.contains("office.preview.type = ${KK_OFFICE_PREVIEW_TYPE:pdf}"));
+    }
+
     private String readResource(String resourcePath) throws IOException {
         try (InputStream inputStream = getClass().getResourceAsStream(resourcePath)) {
             assertNotNull(inputStream);