fix(deploy): harden Linux Web upgrades

2026-08-06 22:24:13 +08:00 · 2026-07-18 08:28:06 -07:00
parent a73fa877a0
commit 62d852c2b3
5 changed files with 154 additions and 13 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@

 ## [未发布 (Unreleased)]

+### 修复 (Fixes)
+
+- **Linux Web 升级不再假成功** — 部署脚本会沿用已有 systemd 工作目录，拒绝 root/普通用户权限模式错位；Git 拉取失败或存在本地修改时立即停止，构建成功后重启服务并输出实际面板版本。README 与 Linux 部署指南同步补充系统级/用户级升级命令和版本核验步骤
+
 ## [0.19.0] - 2026-07-15

 ### 新功能 (Features)
--- a/README.md
+++ b/README.md
@@ -249,22 +249,34 @@ ClawPanel 提供多种升级方式，根据你的安装方式选择对应方案

 **方式一：一键升级脚本（推荐）**

+系统级安装（`/opt/clawpanel`）：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | sudo bash
+```
+
+普通用户安装（`~/.local/share/clawpanel`）：
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash
 ```

-脚本会自动检测已有安装，拉取最新代码并重新构建。
+脚本会读取已有 systemd 服务的实际工作目录，使用 `git pull --ff-only` 拉取代码，重新构建并重启服务。Git 拉取失败、本地存在未提交修改或权限模式不匹配时会明确报错并停止，不会继续用旧源码构建。

 **方式二：手动升级**

 ```bash
 cd /opt/clawpanel  # 替换为实际安装目录
-git pull origin main
+git status --short  # 有输出时先处理本地修改
+git pull --ff-only origin main
 npm install
 npm run build
+node -p "require('./package.json').version"  # 应输出最新版本
 sudo systemctl restart clawpanel
 ```

+普通用户服务将最后一行替换为 `systemctl --user restart clawpanel`。升级后如果浏览器仍显示旧版本，请使用 `Ctrl+F5` 强制刷新。
+
 > **升级 OpenClaw**：面板和 OpenClaw 版本需要匹配。可在「服务管理」页面一键升级，或手动执行：
 > ```bash
 > sudo npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com
--- a/docs/linux-deploy.md
+++ b/docs/linux-deploy.md
@@ -319,19 +319,38 @@ sudo firewall-cmd --reload

 ### 更新 ClawPanel

+推荐直接重新运行部署脚本。必须与原安装权限保持一致：
+
+```bash
+# 系统级安装（/opt/clawpanel）
+curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | sudo bash
+
+# 普通用户安装（~/.local/share/clawpanel）
+curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash
+```
+
+脚本会自动读取 systemd 服务的 `WorkingDirectory`，更新实际运行的目录，并在构建后重启对应服务。拉取失败、存在未提交修改或权限模式不匹配时，脚本会停止并显示具体原因。
+
+手动升级：
+
 ```bash
 cd /opt/clawpanel        # root 部署路径
 # 或 ~/.local/share/clawpanel  # 普通用户路径

-git pull origin main
+git status --short       # 有输出时先处理本地修改
+git pull --ff-only origin main
 npm install --registry https://registry.npmmirror.com
+npm run build
+node -p "require('./package.json').version"  # 核对实际源码版本
 sudo systemctl restart clawpanel  # 或 pm2 restart clawpanel
 ```

+普通用户 systemd 服务使用 `systemctl --user restart clawpanel`。升级后浏览器仍显示旧页面时，使用 `Ctrl+F5` 强制刷新。
+
 > 国内拉不到 GitHub？可切换到 AtomGit 镜像：
 > ```bash
 > git remote set-url origin https://atomgit.com/qingchencloud/clawpanel.git
-> git pull origin main
+> git pull --ff-only origin main
 > ```

 ### 更新 OpenClaw
--- a/scripts/linux-deploy.sh
+++ b/scripts/linux-deploy.sh
@@ -10,6 +10,7 @@ echo ""
 PANEL_PORT=1420
 REPO_URL="https://github.com/qingchencloud/clawpanel.git"
 REPO_URL_GITEE="https://gitee.com/QtCodeCreators/clawpanel.git"
+DEPLOY_SCRIPT_URL="https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh"
 NPM_REGISTRY="https://registry.npmmirror.com"
 PANEL_NODE_MIN_VERSION="18.0.0"
 OPENCLAW_RECOMMENDED_VERSION="2026.7.1-zh.2"
@@ -25,14 +26,61 @@ if [ "$(id -u)" = "0" ]; then
    IS_ROOT=true
    INSTALL_DIR="/opt/clawpanel"
    SYSTEMD_DIR="/etc/systemd/system"
-    echo "🔑 以 root 身份运行，安装到 $INSTALL_DIR"
+    SERVICE_SCOPE="system"
 else
    IS_ROOT=false
    INSTALL_DIR="$HOME/.local/share/clawpanel"
    SYSTEMD_DIR="$HOME/.config/systemd/user"
-    echo "👤 以普通用户身份运行，安装到 $INSTALL_DIR"
+    SERVICE_SCOPE="user"
 fi

+# 优先沿用已有 systemd 服务的工作目录，避免用不同权限重复安装两套面板
+select_install_context() {
+    local system_install_dir=""
+    local user_install_dir=""
+
+    if command -v systemctl &> /dev/null; then
+        system_install_dir=$(systemctl show clawpanel --property=WorkingDirectory --value 2>/dev/null || true)
+        if [ "$IS_ROOT" = false ]; then
+            user_install_dir=$(systemctl --user show clawpanel --property=WorkingDirectory --value 2>/dev/null || true)
+        fi
+    fi
+
+    if [ -z "$system_install_dir" ] && [ -f "/etc/systemd/system/clawpanel.service" ]; then
+        system_install_dir=$(sed -n 's/^WorkingDirectory=//p' /etc/systemd/system/clawpanel.service | head -1)
+    fi
+    if [ "$IS_ROOT" = false ] && [ -z "$user_install_dir" ] && [ -f "$HOME/.config/systemd/user/clawpanel.service" ]; then
+        user_install_dir=$(sed -n 's/^WorkingDirectory=//p' "$HOME/.config/systemd/user/clawpanel.service" | head -1)
+    fi
+
+    if [ "$IS_ROOT" = false ] && [ -n "$user_install_dir" ] && [ -f "$user_install_dir/package.json" ]; then
+        INSTALL_DIR="$user_install_dir"
+        SYSTEMD_DIR="$HOME/.config/systemd/user"
+        SERVICE_SCOPE="user"
+    elif [ -n "$system_install_dir" ] && [ -f "$system_install_dir/package.json" ]; then
+        if [ "$IS_ROOT" = false ]; then
+            echo "❌ 检测到系统级 ClawPanel 安装: $system_install_dir"
+            echo "   请使用 root 权限升级，避免在用户目录重复安装："
+            echo "   curl -fsSL $DEPLOY_SCRIPT_URL | sudo bash"
+            exit 1
+        fi
+        INSTALL_DIR="$system_install_dir"
+        SYSTEMD_DIR="/etc/systemd/system"
+        SERVICE_SCOPE="system"
+    elif [ "$IS_ROOT" = false ] && [ -f "/opt/clawpanel/package.json" ]; then
+        echo "❌ 检测到系统级 ClawPanel 安装: /opt/clawpanel"
+        echo "   请使用 root 权限升级，避免在用户目录重复安装："
+        echo "   curl -fsSL $DEPLOY_SCRIPT_URL | sudo bash"
+        exit 1
+    fi
+
+    if [ "$SERVICE_SCOPE" = "system" ]; then
+        echo "🔑 使用系统级安装目录: $INSTALL_DIR"
+    else
+        echo "👤 使用用户级安装目录: $INSTALL_DIR"
+    fi
+}
+
 # 带权限执行（安装系统包时需要）
 run_pkg_cmd() {
    if [ "$IS_ROOT" = true ]; then
@@ -313,7 +361,22 @@ install_clawpanel() {
    if [ -d "$INSTALL_DIR" ] && [ -f "$INSTALL_DIR/package.json" ]; then
        echo "📦 ClawPanel 已存在，更新中..."
        cd "$INSTALL_DIR"
-        git pull origin main 2>/dev/null || true
+        if [ ! -d ".git" ]; then
+            echo "❌ ClawPanel 源码更新失败：$INSTALL_DIR 不是 Git 仓库"
+            echo "   请保留 ~/.openclaw 数据后重新执行安装脚本"
+            exit 1
+        fi
+        if ! git diff --quiet || ! git diff --cached --quiet; then
+            echo "❌ ClawPanel 源码更新失败：检测到未提交的本地修改"
+            echo "   请先执行 git status 并处理这些修改，脚本不会自动覆盖"
+            git status --short
+            exit 1
+        fi
+        if ! git pull --ff-only origin main; then
+            echo "❌ ClawPanel 源码更新失败，请检查上方 Git 错误、网络和远程仓库地址"
+            echo "   当前远程: $(git remote get-url origin 2>/dev/null || echo '未知')"
+            exit 1
+        fi
        # 清理可能损坏的 node_modules（上次 npm install 失败残留）
        if [ -d "node_modules" ] && [ ! -f "node_modules/.package-lock.json" ]; then
            echo "⚠️  检测到不完整的 node_modules，清理后重新安装..."
@@ -342,7 +405,9 @@ install_clawpanel() {
    echo "📦 构建生产版本..."
    cd "$INSTALL_DIR"
    npx vite build
+    PANEL_VERSION=$(node -p "require('./package.json').version")
    echo "✅ ClawPanel 安装完成: $INSTALL_DIR"
+    echo "✅ ClawPanel 版本: $PANEL_VERSION"
    echo "✅ 启动命令: npm run serve"
 }

@@ -357,7 +422,7 @@ setup_systemd() {
    echo "🔧 创建 systemd 服务..."
    mkdir -p "$SYSTEMD_DIR"

-    if [ "$IS_ROOT" = true ]; then
+    if [ "$SERVICE_SCOPE" = "system" ]; then
        cat > "$SYSTEMD_DIR/clawpanel.service" << EOF
 [Unit]
 Description=ClawPanel Web - OpenClaw Management Panel
@@ -379,7 +444,7 @@ WantedBy=multi-user.target
 EOF
        systemctl daemon-reload
        systemctl enable clawpanel
-        systemctl start clawpanel
+        systemctl restart clawpanel
    else
        cat > "$SYSTEMD_DIR/clawpanel.service" << EOF
 [Unit]
@@ -401,11 +466,11 @@ WantedBy=default.target
 EOF
        systemctl --user daemon-reload
        systemctl --user enable clawpanel
-        systemctl --user start clawpanel
+        systemctl --user restart clawpanel
        # 允许用户服务在未登录时继续运行
        loginctl enable-linger "$(whoami)" 2>/dev/null || true
    fi
-    echo "✅ systemd 服务已创建并启动"
+    echo "✅ systemd 服务已更新并重启"
 }

 # 获取本机 IP
@@ -443,6 +508,7 @@ EOF

 # 主流程
 main() {
+    select_install_context
    detect_os
    echo ""
    install_git
@@ -454,7 +520,7 @@ main() {

    local ip=$(get_local_ip)

-    if [ "$IS_ROOT" = true ]; then
+    if [ "$SERVICE_SCOPE" = "system" ]; then
        local ctl_cmd="systemctl"
    else
        local ctl_cmd="systemctl --user"
@@ -477,7 +543,7 @@ main() {
    echo "  常用命令："
    echo "    $ctl_cmd status clawpanel    # 查看状态"
    echo "    $ctl_cmd restart clawpanel   # 重启面板"
-    if [ "$IS_ROOT" = true ]; then
+    if [ "$SERVICE_SCOPE" = "system" ]; then
        echo "    journalctl -u clawpanel -f    # 查看日志"
    else
        echo "    journalctl --user -u clawpanel -f    # 查看日志"
--- a/tests/linux-deploy-upgrade-policy.test.js
+++ b/tests/linux-deploy-upgrade-policy.test.js
@@ -0,0 +1,40 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const read = path => readFileSync(new URL(`../${path}`, import.meta.url), 'utf8')
+const script = read('scripts/linux-deploy.sh')
+const readme = read('README.md')
+const linuxGuide = read('docs/linux-deploy.md')
+
+test('Linux Web 升级失败必须中止并保留完整 Git 错误', () => {
+  assert.doesNotMatch(script, /git pull origin main 2>\/dev\/null \|\| true/)
+  assert.match(script, /git pull --ff-only origin main/)
+  assert.match(script, /源码更新失败/)
+})
+
+test('Linux Web 升级必须识别已有 systemd 工作目录并阻止权限模式错位', () => {
+  assert.match(script, /select_install_context\(\)/)
+  assert.match(script, /systemctl show clawpanel[^\n]*WorkingDirectory/)
+  assert.match(script, /检测到系统级 ClawPanel 安装/)
+  assert.match(script, /curl -fsSL[^\n]*\| sudo bash/)
+})
+
+test('Linux Web 构建后必须重启已有服务并输出实际版本', () => {
+  assert.match(script, /systemctl restart clawpanel/)
+  assert.match(script, /systemctl --user restart clawpanel/)
+  assert.doesNotMatch(script, /systemctl start clawpanel/)
+  assert.doesNotMatch(script, /systemctl --user start clawpanel/)
+  assert.match(script, /ClawPanel 版本:.*PANEL_VERSION/)
+})
+
+test('Linux Web 升级文档必须区分 system 与 user 服务并提供可诊断命令', () => {
+  for (const [name, content] of [
+    ['README.md', readme],
+    ['docs/linux-deploy.md', linuxGuide],
+  ]) {
+    assert.match(content, /curl -fsSL[^\n]*\| sudo bash/, `${name} 缺少系统级升级命令`)
+    assert.match(content, /git pull --ff-only origin main/, `${name} 仍使用不可诊断的 git pull`)
+    assert.match(content, /node -p [^\n]*package\.json/, `${name} 缺少升级后版本核验`)
+  }
+})