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

738 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PERLER LAB 拼豆图纸生成器 · 部署架构文档
> 文档版本:v1.0 | 编写角色:架构师(Oracle-Architect-Agent)
> 适用范围:开发环境 / 预发布环境 / 生产环境
---
## 目录
1. [部署架构图](#1-部署架构图)
2. [环境规划](#2-环境规划)
3. [Docker 镜像设计](#3-docker-镜像设计)
4. [域名与 HTTPS 方案](#4-域名与-https-方案)
5. [数据库备份策略](#5-数据库备份策略)
6. [监控告警方案](#6-监控告警方案)
7. [上线 Checklist](#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 开发环境快速启动
```bash
# 终端 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 │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
**构建命令:**
```bash
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) │ │
│ └────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```
**构建命令:**
```bash
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 启动
**完整启动命令:**
```bash
# 从项目根目录
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`:
```nginx
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 证书申请与自动续期
```bash
# 安装 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 确认:
```bash
# 每天凌晨 3 点检查续期
0 3 * * * /usr/bin/certbot renew --quiet && systemctl reload nginx
```
### 4.4 防火墙配置
```bash
# 开放 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`:
```bash
#!/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 定时任务配置
```bash
# 每小时备份(生产环境)
sudo crontab -e -u root
# 添加以下行:
0 * * * * /opt/perler-lab/scripts/backup-db.sh >> /var/log/perler-db-backup.log 2>&1
```
### 5.4 恢复流程
```bash
# 从备份恢复数据库
# 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 监控命令速查
```bash
# 查看所有服务状态
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`:
```bash
#!/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 日志管理
```bash
# 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 部署步骤(首次)
```bash
# 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 部署步骤(更新)
```bash
# 方式一:自动(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 回滚方案
```bash
# 回滚到上一个版本
# 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 编排容器