Files
Sisyphus (主代理) 02762400fb chore: 项目基线提交 - 拼豆图纸生成器 V1.0 核心代码
- 前端: React+Vite 首页/AI专区, 算法库(MARD色板/量化/背景去除), API对接
- 后端: Express+SQLite, 兑换码/订单/支付/chibi生成, 风控+云端同步
- CI/CD: GitHub Actions + Docker + nginx 配置
- 文档: PRD/DESIGN/LAUNCH/ROADMAP/E2E/竞品对照等 15 份
- 工程: 任务看板(taskboard) + 健康巡检(agent-health) + Git流程(gitflow)
2026-08-13 21:40:27 +08:00

26 KiB
Raw Permalink Blame History

PERLER LAB 拼豆图纸生成器 · 部署架构文档

文档版本:v1.0 | 编写角色:架构师(Oracle-Architect-Agent) 适用范围:开发环境 / 预发布环境 / 生产环境


目录

  1. 部署架构图
  2. 环境规划
  3. Docker 镜像设计
  4. 域名与 HTTPS 方案
  5. 数据库备份策略
  6. 监控告警方案
  7. 上线 Checklist

1. 部署架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        用户浏览器 (Browser)                         │
│              https://perlerlab.com  ← 用户访问入口                  │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
                     ╔═════╧══════════════════════════════╗
                     ║   Cloudflare CDN (可选)             ║
                     ║   - DDoS 防护                       ║
                     ║   - SSL 证书托管                    ║
                     ║   - 缓存静态资源                    ║
                     ╚═════╤══════════════════════════════╝
                           │
                  ┌────────┴────────┐
                  │  HTTPS :443     │
                  └────────┬────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
   │  主机 Nginx   │  │ Certbot 证书 │  │  监控脚本     │
   │  (Let's Encrypt) │  │ 自动续期   │  │ (cron)       │
   └──────┬───────┘  └──────────────┘  └──────────────┘
          │ 反向代理 / 80→8080(frontend) /api→8788(server)
          │
          ▼
┌───────────────────────────────────┐
│  Docker Compose (同一台主机)      │
│                                   │
│  ┌──────────────────────────┐    │
│  │  perler-lab-frontend     │    │
│  │  (nginx:1.27-alpine)     │    │
│  │  端口 :8080              │    │
│  │  - 静态资源 (dist/ + public/)│  │
│  │  - SPA 路由回退           │    │
│  │  - /api 反向代理 → server │    │
│  └──────────┬───────────────┘    │
│             │ 内部网络 perler-net │
│  ┌──────────▼───────────────┐    │
│  │  perler-lab-server       │    │
│  │  (node:20-slim)          │    │
│  │  端口 :8788              │    │
│  │  Express + better-sqlite3│    │
│  ├──────────────────────────┤    │
│  │  Volume: db-data:/app/data│   │
│  │  ┌──────────────────┐   │    │
│  │  │  perler-lab.db   │   │    │
│  │  │  perler-lab.db-  │   │    │
│  │  │  wal (WAL)       │   │    │
│  │  │  perler-lab.db-  │   │    │
│  │  │  shm (WAL)       │   │    │
│  │  └──────────────────┘   │    │
│  └──────────────────────────┘    │
└───────────────────────────────────┘

请求流程

用户访问 https://perlerlab.com
  │
  ▼
Let's Encrypt → 主机 Nginx (443) → 解密 TLS
  │
  ├── /api/* → 反代 localhost:8788 → server 容器
  │              → Express 路由 → better-sqlite3
  │              → 返回 JSON
  │
  └── /* → 反代 localhost:8080 → frontend 容器
              → nginx 内部
                 ├── /assets/* → 强缓存 (30d)
                 ├── /dist/*   → 强缓存 (30d)
                 ├── /favicon  → 缓存 (7d)
                 └── /* → try_files → /index.html (SPA)

2. 环境规划

2.1 环境矩阵

维度 开发环境 (dev) 预发布 (staging) 生产 (prod)
目的 本地开发调试 联调 / 验收测试 正式对外服务
机器 开发者笔记本 轻量云服务器 (2C4G) 云服务器 (4C8G)
域名 localhost:8080 staging.perlerlab.com perlerlab.com
HTTPS 无(HTTP) Let's Encrypt(自动) Let's Encrypt(自动)
数据库 SQLite 本地文件 SQLite + 每日备份 SQLite + 每小时备份
Docker 可选(直接 node 启动) 必选(docker compose) 必选(docker compose)
日志级别 debug info warn
支付 模拟接口 沙箱环境 正式支付对接
监控 无 基础健康检查 完整告警链

2.2 开发环境快速启动

# 终端 1:启动后端
cd perler-lab-server
npm install
npm run dev          # tsx watch src/server.ts → http://localhost:8788

# 终端 2:前端库(编译 + 测试)
cd perler-lab
npm install
npm test             # 运行测试
npm run typecheck    # 类型检查

2.3 生产环境最低要求

资源 最低配置 推荐配置
CPU 2 核 4 核
内存 4 GB 8 GB
磁盘 20 GB SSD 50 GB SSD
带宽 5 Mbps 20 Mbps
OS Ubuntu 22.04 LTS Ubuntu 24.04 LTS
Docker 24+ 27+

3. Docker 镜像设计

3.1 前端镜像 (perler-lab/Dockerfile)

┌─────────────────────────────────────────────┐
│  Stage 1: build (node:20-alpine)             │
│  ┌───────────────────────────────────────┐  │
│  │ COPY package.json + tsconfig.json + src │  │
│  │ RUN npm install                        │  │
│  │ RUN npx tsc              → dist/       │  │
│  └───────────────────────────────────────┘  │
│                      ▼                       │
│  Stage 2: serve (nginx:1.27-alpine)          │
│  ┌───────────────────────────────────────┐  │
│  │ COPY nginx.conf  → /etc/nginx/conf.d/  │  │
│  │ COPY --from=build /app/dist → html/dist│  │
│  │ COPY public/      → html/ (静态资源)    │  │
│  │ EXPOSE 80                              │  │
│  │ HEALTHCHECK: wget /healthz             │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

构建命令:

docker build -t perler-lab-frontend:latest perler-lab

关键设计决策:

  • 使用 npx tsc 而非 npm run build(package.json 中无 build 脚本,不修改源码)
  • 无 package-lock.json → 使用 npm install 而非 npm ci
  • dist/ 与 public/ 合并至 nginx 根目录,统一对外服务
  • 若未来前端迁移至 Next.js,需改为 next build + node server.js 模式,此 Dockerfile 需重构

3.2 后端镜像 (perler-lab-server/Dockerfile)

┌──────────────────────────────────────────────────┐
│  Stage 1: build (node:20-slim)                    │
│  ┌────────────────────────────────────────────┐  │
│  │ apt-get: python3, make, g++ (原生模块编译)   │  │
│  │ COPY package.json + package-lock.json       │  │
│  │ RUN npm ci            (含 devDeps)          │  │
│  │ COPY src/ + tsconfig.json                   │  │
│  │ RUN npm run build     (tsc → dist/)         │  │
│  └────────────────────────────────────────────┘  │
│                       ▼                            │
│  Stage 2: runtime (node:20-slim)                   │
│  ┌────────────────────────────────────────────┐  │
│  │ COPY node_modules/  (含 devDeps,需 tsx)    │  │
│  │ COPY dist/          (编译产物)              │  │
│  │ COPY src/           (tsx 运行时需要源码)     │  │
│  │ COPY package.json                           │  │
│  │ RUN mkdir /app/data + useradd perler        │  │
│  │ ENV PORT=8788                               │  │
│  │ EXPOSE 8788                                 │  │
│  │ HEALTHCHECK: fetch /health                  │  │
│  │ CMD npm run start   (tsx src/server.ts)     │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

构建命令:

docker build -t perler-lab-server:latest perler-lab-server

为什么用 slim 而非 alpine:

better-sqlite3 提供 glibc (Debian/Ubuntu) 的预编译二进制,在 alpine (musl) 上则需从源码编译。slim 镜像体积比 alpine 大 ~50MB,但构建更快、更可靠,且原生模块兼容性更好。

为什么运行时依赖 devDeps (tsx):

server.ts 中的 isMain 检查通过 process.argv[1].endsWith("server.ts") 判断是否为入口文件。编译后的 dist/server.js 不满足此条件,因此必须使用 tsx 直接运行 .ts 源码。这与 package.json 中定义的 start 脚本一致。

3.3 Docker Compose 启动

完整启动命令:

# 从项目根目录
docker compose -f perler-lab-server/docker-compose.yml up -d --build

# 查看日志
docker compose -f perler-lab-server/docker-compose.yml logs -f

# 停止
docker compose -f perler-lab-server/docker-compose.yml down

服务端口映射:

服务 容器内端口 宿主机端口 说明
frontend 80 8080 通过主机 Nginx 反代 443→8080
server 8788 不暴露 仅 frontend 内部网络访问

4. 域名与 HTTPS 方案

4.1 架构概览

采用 主机 Nginx 反代 Docker Compose 的经典模式:

互联网 → 主机 Nginx (443) → 反代到 Docker Compose 服务
         ↑
  Let's Encrypt (Certbot 自动续期)

4.2 主机 Nginx 配置

创建 /etc/nginx/sites-available/perlerlab.com:

server {
    listen 80;
    server_name perlerlab.com staging.perlerlab.com;

    # Let's Encrypt 验证目录
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    # 其余 HTTP 请求重定向到 HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name perlerlab.com;

    ssl_certificate     /etc/letsencrypt/live/perlerlab.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/perlerlab.com/privkey.pem;

    # SSL 配置(Mozilla 推荐)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1h;

    # 安全头
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

    # 前端静态资源 → Docker frontend 服务
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # API 请求直接反代到后端(绕过前端 nginx 的 /api 代理)
    # 如果希望走前端 nginx 的 /api 代理,可将此 blocks 注释,仅保留上面 /
    location /api/ {
        proxy_pass http://127.0.0.1:8788;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }

    # 健康检查
    location /healthz {
        access_log off;
        return 200 "OK";
    }

    # 日志
    access_log /var/log/nginx/perlerlab-access.log;
    error_log  /var/log/nginx/perlerlab-error.log;
}

4.3 Let's Encrypt 证书申请与自动续期

# 安装 Certbot
sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx

# 申请证书(自动配置 Nginx)
sudo certbot --nginx -d perlerlab.com -d staging.perlerlab.com

# 测试自动续期
sudo certbot renew --dry-run

Certbot 自动在 /etc/cron.d/certbot 中配置每日续期检查。可手动添加 crontab 确认:

# 每天凌晨 3 点检查续期
0 3 * * * /usr/bin/certbot renew --quiet && systemctl reload nginx

4.4 防火墙配置

# 开放 80/443 端口(Ubuntu UFW)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp          # SSH
sudo ufw enable

# 确认状态
sudo ufw status verbose

5. 数据库备份策略

5.1 备份方案

PERLER LAB 使用 SQLite(单文件),备份策略简单直接:

备份策略矩阵:
┌──────────────┬────────────┬────────────┬───────────────┐
│ 环境         │ 频率        │ 保留天数    │ 方式          │
├──────────────┼────────────┼────────────┼───────────────┤
│ 开发 (dev)   │ 不备份      │ -          │ -             │
│ 预发布 (stg) │ 每日 04:00 │ 7 天       │ docker cp     │
│ 生产 (prod)  │ 每小时      │ 30 天      │ sqlite3 .backup│
└──────────────┴────────────┴────────────┴───────────────┘

5.2 生产环境备份脚本

创建 /opt/perler-lab/scripts/backup-db.sh:

#!/bin/bash
# ============================================================
# PERLER LAB SQLite 数据库备份脚本
# - 使用 sqlite3 .backup 命令在线热备(WAL 模式下安全)
# - 压缩后上传到备份目录 / 对象存储
# - 保留最近 30 天备份
# ============================================================

set -euo pipefail

# 配置
BACKUP_ROOT="/opt/perler-lab/backups"
DB_VOLUME_NAME="perler-lab-server_db-data"
DB_FILE="perler-lab.db"
TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
BACKUP_DIR="${BACKUP_ROOT}/${TIMESTAMP}"
RETENTION_DAYS=30

# 创建备份目录
mkdir -p "${BACKUP_DIR}"

# 方法 1:通过临时容器使用 sqlite3 .backup(推荐——WAL 安全,不停机)
# 启动临时容器挂载 volume,执行 .backup 命令,完成后自动删除
docker run --rm \
    -v "${DB_VOLUME_NAME}:/data:ro" \
    -v "${BACKUP_DIR}:/backup" \
    alpine:3.20 \
    sh -c "
        apk add --no-cache sqlite > /dev/null
        # 使用 sqlite3 .backup 命令进行在线热备
        sqlite3 /data/${DB_FILE} \".backup /backup/${DB_FILE}\"
        echo 'sqlite3 .backup 完成'
    "

# 方法 2:退路——直接复制文件(如果 .backup 不可用)
# 注意:WAL 模式下直接复制文件可能不完整,.backup 更可靠
# docker run --rm -v ${DB_VOLUME_NAME}:/data:ro -v ${BACKUP_DIR}:/backup alpine cp /data/perler-lab.db* /backup/

# 压缩备份
cd "${BACKUP_ROOT}"
tar czf "${TIMESTAMP}.tar.gz" "${TIMESTAMP}"
rm -rf "${TIMESTAMP}"

# 清理过期备份
find "${BACKUP_ROOT}" -name "*.tar.gz" -mtime +${RETENTION_DAYS} -delete

echo "备份完成:${BACKUP_ROOT}/${TIMESTAMP}.tar.gz"

# 可选:上传到对象存储(OSS / S3 兼容)
# if command -v rclone &> /dev/null; then
#     rclone copy "${BACKUP_ROOT}/${TIMESTAMP}.tar.gz" remote:perler-lab-backups/
# fi

5.3 定时任务配置

# 每小时备份(生产环境)
sudo crontab -e -u root
# 添加以下行:
0 * * * * /opt/perler-lab/scripts/backup-db.sh >> /var/log/perler-db-backup.log 2>&1

5.4 恢复流程

# 从备份恢复数据库
# 1. 停止服务
docker compose -f perler-lab-server/docker-compose.yml down

# 2. 从备份 tar.gz 恢复
RESTORE_FILE="/opt/perler-lab/backups/20260813-120000.tar.gz"
TEMP_DIR=$(mktemp -d)
tar xzf "${RESTORE_FILE}" -C "${TEMP_DIR}"

# 3. 恢复数据到 volume
# 先删除旧 volume 内容
docker run --rm -v perler-lab-server_db-data:/data alpine rm -f /data/perler-lab.db*
# 复制备份
docker run --rm \
    -v "${TEMP_DIR}:/backup:ro" \
    -v perler-lab-server_db-data:/data \
    alpine cp /backup/perler-lab.db /data/

# 4. 重启服务
docker compose -f perler-lab-server/docker-compose.yml up -d

# 5. 验证
curl http://localhost:8788/health

# 6. 清理临时目录
rm -rf "${TEMP_DIR}"

6. 监控告警方案

6.1 健康检查体系

Docker Compose 中配置了自动健康检查:

服务 检查方式 间隔 超时 重试 启动宽限
frontend wget /healthz 30s 5s 3 10s
server fetch /health 30s 5s 3 15s

当服务连续 3 次健康检查失败时,Docker 将标记容器为 unhealthy(不会自动重启——restart: unless-stopped 只在容器退出时重启,不因健康检查失败重启)。

6.2 监控命令速查

# 查看所有服务状态
docker compose -f perler-lab-server/docker-compose.yml ps

# 查看健康检查状态
docker inspect --format='{{json .State.Health}}' perler-lab-server
docker inspect --format='{{json .State.Health}}' perler-lab-frontend

# 实时日志
docker compose -f perler-lab-server/docker-compose.yml logs -f

# 查看资源使用
docker stats perler-lab-server perler-lab-frontend

# 查看数据库文件大小
docker run --rm -v perler-lab-server_db-data:/data alpine du -sh /data/

6.3 简易监控脚本

创建 /opt/perler-lab/scripts/health-check.sh:

#!/bin/bash
# ============================================================
# PERLER LAB 简易健康巡检脚本
# 配合 crontab 每 5 分钟执行,失败时发送告警
# ============================================================

set -euo pipefail

ALERT_EMAIL="admin@perlerlab.com"  # 替换为实际告警邮箱
COMPOSE_DIR="/opt/perler-lab/perler-lab-server"
SLACK_WEBHOOK=""  # 可选:Slack Webhook URL

check_service() {
    local name=$1
    local url=$2
    local status_code

    status_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "${url}" || echo "000")

    if [ "${status_code}" != "200" ]; then
        echo "[ALERT] ${name} 健康检查失败 (HTTP ${status_code})"
        # 邮件告警
        echo "${name} 健康检查失败 (HTTP ${status_code}) at $(date)" \
            | mail -s "[PERLER LAB] ${name} 服务异常" "${ALERT_EMAIL}"
        return 1
    fi
    echo "[OK] ${name} 健康检查通过 (HTTP ${status_code})"
    return 0
}

# 检查前端
check_service "frontend" "http://localhost:8080/healthz"

# 检查后端
check_service "server" "http://localhost:8788/health"

# 检查磁盘使用
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ "${DISK_USAGE}" -gt 85 ]; then
    echo "[WARN] 磁盘使用率 ${DISK_USAGE}% 超过 85%"
fi

# 检查内存使用
MEM_USAGE=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100}')
if [ "${MEM_USAGE}" -gt 90 ]; then
    echo "[WARN] 内存使用率 ${MEM_USAGE}% 超过 90%"
fi

6.4 告警规则

指标 阈值 动作 响应时间
前端健康检查 连续 2 次失败 邮件告警 5 分钟内
后端健康检查 连续 2 次失败 邮件告警 5 分钟内
磁盘使用率 > 85% 邮件告警 1 小时内
内存使用率 > 90% 邮件告警 1 小时内
证书过期 距到期 < 30 天 邮件告警 每日检查
备份失败 最后一次备份 > 2 小时 邮件告警 2 小时内

6.5 日志管理

# Nginx 日志(主机层)
/var/log/nginx/perlerlab-access.log
/var/log/nginx/perlerlab-error.log

# Docker 容器日志
docker logs perler-lab-server
docker logs perler-lab-frontend

# 日志轮转配置(/etc/logrotate.d/perler-lab)
/var/log/nginx/perlerlab-*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        systemctl reload nginx > /dev/null 2>&1 || true
    endscript
}

7. 上线 Checklist

7.1 部署前检查

  • 代码检查

    • perler-lab 与 perler-lab-server 全部测试通过
    • 类型检查无错误 (npm run typecheck)
    • 所有 .env 示例文件已提交,敏感值通过 GitHub Secrets 注入
    • 代码已合并到 main 分支
  • 基础设施

    • 服务器已开通,SSH 密钥已配置
    • Docker 已安装 (docker --version)
    • Docker Compose 已安装 (docker compose version)
    • 域名 DNS 已解析到服务器 IP
    • 80/443 端口防火墙已开放
    • 磁盘空间 > 10 GB (df -h)
  • 数据库

    • 确认 SQLite 数据目录 data/ 已创建
    • 首次启动时 initDatabase() 自动创建表
    • 备份脚本已部署并测试
  • HTTPS

    • Let's Encrypt 证书已申请
    • 自动续期 cron 已配置
    • 主机 Nginx 配置已加载 (nginx -t && systemctl reload nginx)
  • 部署

    • 首次部署建议手动执行 docker compose up -d --build
    • 验证所有服务健康检查通过
    • 验证 API 端点可用 (curl /health)
    • 验证前端页面可访问
    • 验证兑换码流程完整

7.2 部署步骤(首次)

# 1. SSH 登录服务器
ssh root@perlerlab.com

# 2. 安装 Docker
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER
# 退出重连使生效

# 3. 克隆代码
git clone <仓库地址> /opt/perler-lab
cd /opt/perler-lab

# 4. 启动服务
docker compose -f perler-lab-server/docker-compose.yml up -d --build

# 5. 验证
curl http://localhost:8080/healthz
curl http://localhost:8788/health

7.3 部署步骤(更新)

# 方式一:自动(CI/CD)
# 推送 main 分支 → GitHub Actions 自动执行 deploy 步骤

# 方式二:手动
ssh root@perlerlab.com
cd /opt/perler-lab
git pull origin main
docker compose -f perler-lab-server/docker-compose.yml up -d --build
docker image prune -f

7.4 回滚方案

# 回滚到上一个版本
# 1. 查看历史提交
git log --oneline -10

# 2. 回退代码
git reset --hard <上一个正常提交的 SHA>

# 3. 重新构建部署
docker compose -f perler-lab-server/docker-compose.yml up -d --build

# 4. 如果 Docker 镜像有问题,拉取之前构建的版本
# docker tag perler-lab-frontend:previous perler-lab-frontend:latest
# docker compose -f perler-lab-server/docker-compose.yml up -d

7.5 上线后验证清单

  • 访问 https://perlerlab.com → 页面正常加载
  • 访问 https://perlerlab.com/api/codes → 返回 401/404 而非 502
  • 上传图片 → 生成拼豆图纸 → 预览正常
  • 兑换码输入 → 解锁成功 → 下载正常
  • 移动端适配 → 响应式布局正常
  • SSL 证书 → 浏览器地址栏显示安全锁
  • 页面加载速度 → Lighthouse 分数 > 70
  • 备份脚本手动执行一遍 → 确认备份文件生成

附录:常见问题

Q1: 为什么后端用 tsx 而非 node dist/server.js?

因为 server.ts 中的 isMain 检查使用 process.argv[1].endsWith("server.ts") 判断是否为主入口。编译后的 dist/server.js 不满足此条件,无法自动启动 Express 服务。使用 tsx 直接运行 TypeScript 源码与此检查兼容,且与 package.json 的 start 脚本一致。

若未来重构 server.ts 的入口判断逻辑,可将启动方式改为 node dist/server.js 并移除 devDeps (tsx)。

Q2: 数据丢失怎么办?

按照第 5 节的恢复流程操作。如果 backup 不可用,可以尝试从 WAL 文件恢复(sqlite3 会在启动时自动回放 WAL 日志)。

Q3: 如何迁移到 MySQL/PostgreSQL?

当前架构设计为 SQLite 单文件模式,适合 MVP 阶段。后续若需迁移:

  1. 将 Express 路由层与数据库层解耦(使用 Repository 模式)
  2. 引入 Prisma / Drizzle ORM 替代参数化 SQL
  3. 数据库连接信息通过环境变量注入
  4. 迁移数据后更新 Dockerfile 无需 node:20-slim(无原生模块依赖)

Q4: 如何扩展多节点?

当前设计为单机部署。若需横向扩展:

  1. 将 SQLite 替换为 PostgreSQL(支持并发读写)
  2. 引入 Redis 存储会话和缓存
  3. frontend nginx 作为反向代理分发到多个 backend 实例
  4. 使用 Docker Swarm 或 Kubernetes 编排容器