From 34be13f8bc7c6ba745d6b1024dee1b5f16ab03da Mon Sep 17 00:00:00 2001
From: dash <1549469775@qq.com>
Date: Sat, 22 Nov 2025 15:55:55 +0800
Subject: [PATCH] Update deployment documentation and scripts for sqlite3
 issues. Added a troubleshooting section in DEPLOY.md, created fix-sqlite3.sh
 script for automated binding fixes, and enhanced deploy.sh to check for
 necessary build tools and rebuild sqlite3 as part of the deployment process.

---
 DEPLOY.md      | 45 +++++++++++++++++++++++++++++++++
 deploy.sh      | 37 +++++++++++++++++++++++++++
 fix-sqlite3.sh | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 162 insertions(+)
 create mode 100644 fix-sqlite3.sh

diff --git a/DEPLOY.md b/DEPLOY.md
index 9ad7ddf..eace5a8 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -323,6 +323,51 @@ pnpm migrate:rollback:prod
 pnpm migrate:prod
 ```
 
+### sqlite3 bindings 错误
+
+如果遇到以下错误：
+```
+Could not locate the bindings file. Tried:
+ → /path/to/sqlite3/build/node_sqlite3.node
+```
+
+这是因为 `sqlite3` 是原生模块，需要在目标平台重新编译。
+
+**快速修复：**
+
+```bash
+# 使用修复脚本（推荐）
+chmod +x fix-sqlite3.sh
+./fix-sqlite3.sh
+```
+
+**手动修复：**
+
+```bash
+# 1. 安装编译工具（根据系统选择）
+# Debian/Ubuntu
+sudo apt-get update
+sudo apt-get install -y python3 make g++ build-essential
+
+# CentOS/RHEL
+sudo yum install -y python3 make gcc-c++
+
+# Alpine
+sudo apk add --no-cache python3 make g++
+
+# 2. 停止服务
+pm2 stop just-demo-backend
+
+# 3. 进入 backend 目录并重建 sqlite3
+cd backend
+rm -rf node_modules/.pnpm/sqlite3@* node_modules/sqlite3
+pnpm rebuild sqlite3 || pnpm install sqlite3 --force
+
+# 4. 返回根目录并重启服务
+cd ..
+pm2 restart just-demo-backend
+```
+
 ### 前端无法访问后端
 
 检查 `backend/.env` 中的 `FRONTEND_URL` 配置是否正确。
diff --git a/deploy.sh b/deploy.sh
index 74bb5dd..bc17ba2 100644
--- a/deploy.sh
+++ b/deploy.sh
@@ -37,10 +37,47 @@ if ! command -v pm2 &> /dev/null; then
 fi
 echo -e "${GREEN}✅ PM2 已安装${NC}"
 
+# 3.5. 检查并安装编译工具（sqlite3 需要）
+echo -e "${BLUE}🔧 检查编译工具...${NC}"
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    # Linux 系统
+    if command -v apt-get &> /dev/null; then
+        # Debian/Ubuntu
+        if ! command -v python3 &> /dev/null || ! command -v make &> /dev/null || ! command -v g++ &> /dev/null; then
+            echo "正在安装编译工具 (python3, make, g++)..."
+            sudo apt-get update
+            sudo apt-get install -y python3 make g++ build-essential
+        fi
+    elif command -v yum &> /dev/null; then
+        # CentOS/RHEL
+        if ! command -v python3 &> /dev/null || ! command -v make &> /dev/null || ! command -v g++ &> /dev/null; then
+            echo "正在安装编译工具 (python3, make, gcc-c++)..."
+            sudo yum install -y python3 make gcc-c++
+        fi
+    elif command -v apk &> /dev/null; then
+        # Alpine
+        if ! command -v python3 &> /dev/null || ! command -v make &> /dev/null || ! command -v g++ &> /dev/null; then
+            echo "正在安装编译工具 (python3, make, g++)..."
+            sudo apk add --no-cache python3 make g++
+        fi
+    fi
+fi
+echo -e "${GREEN}✅ 编译工具已就绪${NC}"
+
 # 4. 安装依赖
 echo -e "${BLUE}📦 安装项目依赖...${NC}"
 pnpm install:all
 
+# 4.5. 强制重建 sqlite3（确保原生模块正确编译）
+echo -e "${BLUE}🔨 重建 sqlite3 原生模块...${NC}"
+cd backend
+# 删除 sqlite3 模块并重新安装，确保在当前平台编译
+rm -rf node_modules/.pnpm/sqlite3@* 2>/dev/null || true
+rm -rf node_modules/sqlite3 2>/dev/null || true
+pnpm rebuild sqlite3 || pnpm install sqlite3 --force
+cd ..
+echo -e "${GREEN}✅ sqlite3 重建完成${NC}"
+
 # 5. 构建项目
 echo -e "${BLUE}🔨 构建项目...${NC}"
 pnpm build
diff --git a/fix-sqlite3.sh b/fix-sqlite3.sh
new file mode 100644
index 0000000..65c6d11
--- /dev/null
+++ b/fix-sqlite3.sh
@@ -0,0 +1,80 @@
+#!/bin/bash
+
+# 修复 sqlite3 bindings 问题的脚本
+# 使用方法: chmod +x fix-sqlite3.sh && ./fix-sqlite3.sh
+
+set -e
+
+echo "🔧 修复 sqlite3 bindings 问题..."
+
+# 颜色定义
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# 检查编译工具
+echo -e "${BLUE}📦 检查编译工具...${NC}"
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    if command -v apt-get &> /dev/null; then
+        # Debian/Ubuntu
+        if ! command -v python3 &> /dev/null || ! command -v make &> /dev/null || ! command -v g++ &> /dev/null; then
+            echo "正在安装编译工具..."
+            sudo apt-get update
+            sudo apt-get install -y python3 make g++ build-essential
+        fi
+    elif command -v yum &> /dev/null; then
+        # CentOS/RHEL
+        if ! command -v python3 &> /dev/null || ! command -v make &> /dev/null || ! command -v g++ &> /dev/null; then
+            echo "正在安装编译工具..."
+            sudo yum install -y python3 make gcc-c++
+        fi
+    elif command -v apk &> /dev/null; then
+        # Alpine
+        if ! command -v python3 &> /dev/null || ! command -v make &> /dev/null || ! command -v g++ &> /dev/null; then
+            echo "正在安装编译工具..."
+            sudo apk add --no-cache python3 make g++
+        fi
+    fi
+fi
+
+# 进入 backend 目录
+cd backend
+
+# 停止 PM2 服务（如果正在运行）
+echo -e "${BLUE}⏸️  停止后端服务...${NC}"
+pm2 stop just-demo-backend 2>/dev/null || true
+
+# 删除旧的 sqlite3 模块
+echo -e "${BLUE}🗑️  清理旧的 sqlite3 模块...${NC}"
+rm -rf node_modules/.pnpm/sqlite3@* 2>/dev/null || true
+rm -rf node_modules/sqlite3 2>/dev/null || true
+
+# 重新安装 sqlite3
+echo -e "${BLUE}📦 重新安装 sqlite3...${NC}"
+pnpm rebuild sqlite3 || pnpm install sqlite3 --force
+
+# 验证安装
+echo -e "${BLUE}✅ 验证 sqlite3 安装...${NC}"
+if node -e "require('sqlite3')" 2>/dev/null; then
+    echo -e "${GREEN}✅ sqlite3 安装成功！${NC}"
+else
+    echo -e "${RED}❌ sqlite3 安装失败，请检查错误信息${NC}"
+    exit 1
+fi
+
+# 返回根目录
+cd ..
+
+# 重启 PM2 服务
+echo -e "${BLUE}🚀 重启后端服务...${NC}"
+pm2 restart just-demo-backend || pm2 start ecosystem.config.js
+
+echo ""
+echo -e "${GREEN}🎉 修复完成！${NC}"
+echo ""
+echo "如果问题仍然存在，请尝试："
+echo "  1. 完全删除 node_modules: rm -rf backend/node_modules"
+echo "  2. 重新安装依赖: cd backend && pnpm install"
+echo "  3. 重启服务: pm2 restart just-demo-backend"
+