- 前端: 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)
738 lines
26 KiB
Markdown
738 lines
26 KiB
Markdown
# 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 编排容器 |