docs: 添加部署文档

2026-03-28 17:01:29 +08:00 · 2026-03-28 17:01:29 +08:00 · 9f3f5c9e55
commit 9f3f5c9e55
parent ce208df092
1 changed files with 396 additions and 0 deletions
--- a/DEPLOY.md
+++ b/DEPLOY.md
@ -0,0 +1,396 @@
+# 部署文档
+
+## 项目概览
+
+**技术栈：** Nuxt 4 + Nuxt UI + Pinia + ofetch
+
+**构建产物：** SSR 模式，生成 `.output` 目录（包含 Node.js 服务器）
+
+---
+
+## 一、构建前准备
+
+### 1.1 环境变量配置
+
+复制 `.env.example` 为 `.env`：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件：
+
+```env
+# API 后端地址
+NUXT_PUBLIC_API_BASE=https://api.yourdomain.com
+
+# 站点地址
+NUXT_PUBLIC_SITE_URL=https://yourdomain.com
+NUXT_PUBLIC_SITE_NAME=LinkShare Blog
+```
+
+---
+
+## 二、构建应用
+
+### 2.1 安装依赖并构建
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建生产版本
+pnpm run build
+```
+
+构建产物位于 `.output/` 目录：
+
+```
+.output/
+├── public/          # 静态资源
+├── server/          # Node.js 服务器
+│   └── index.mjs   # 入口文件
+└── server/
+    └── index.mjs
+```
+
+### 2.2 本地预览
+
+```bash
+# 构建后本地测试
+pnpm run preview
+```
+
+---
+
+## 三、部署方案
+
+### 方案 1：直接部署（推荐）
+
+**适用场景：** 支持 SSR 的服务器环境
+
+**启动命令：**
+
+```bash
+# 设置环境变量
+export NUXT_PUBLIC_API_BASE="https://api.yourdomain.com"
+export NUXT_PUBLIC_SITE_URL="https://yourdomain.com"
+export NUXT_PUBLIC_SITE_NAME="LinkShare Blog"
+
+# 启动服务器
+node .output/server/index.mjs
+```
+
+**使用 PM2 管理进程：**
+
+```bash
+# 安装 PM2
+npm install -g pm2
+
+# 启动应用
+pm2 start .output/server/index.mjs --name "binglogy-blog" -- \
+  --env production
+
+# 查看状态
+pm2 status
+
+# 查看日志
+pm2 logs binglogy-blog
+
+# 设置开机自启
+pm2 save
+pm2 startup
+```
+
+**PM2 配置文件（ecosystem.config.js）：**
+
+```javascript
+module.exports = {
+  apps: [{
+    name: 'binglogy-blog',
+    script: '.output/server/index.mjs',
+    instances: 'max',
+    exec_mode: 'cluster',
+    env: {
+      NODE_ENV: 'production',
+      NUXT_PUBLIC_API_BASE: 'https://api.yourdomain.com',
+      NUXT_PUBLIC_SITE_URL: 'https://yourdomain.com',
+      NUXT_PUBLIC_SITE_NAME: 'LinkShare Blog',
+      PORT: 3000
+    }
+  }]
+}
+```
+
+使用配置文件启动：
+
+```bash
+pm2 start ecosystem.config.js
+```
+
+---
+
+### 方案 2：Docker 部署
+
+**Dockerfile：**
+
+```dockerfile
+# 构建阶段
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# 安装 pnpm
+RUN npm install -g pnpm
+
+# 安装依赖
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# 构建应用
+COPY . .
+RUN pnpm run build
+
+# 生产阶段
+FROM node:20-alpine
+
+WORKDIR /app
+
+# 设置环境变量
+ENV NODE_ENV=production
+
+# 复制构建产物
+COPY --from=builder /app/.output ./.output
+COPY --from=builder /app/public ./public
+
+# 暴露端口
+EXPOSE 3000
+
+# 启动服务器
+CMD ["node", ".output/server/index.mjs"]
+```
+
+**docker-compose.yml：**
+
+```yaml
+version: '3.8'
+
+services:
+  frontend:
+    build: .
+    container_name: binglogy-blog
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - NUXT_PUBLIC_API_BASE=https://api.yourdomain.com
+      - NUXT_PUBLIC_SITE_URL=https://yourdomain.com
+      - NUXT_PUBLIC_SITE_NAME=LinkShare Blog
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    networks:
+      - binglogy
+
+networks:
+  binglogy:
+    driver: bridge
+```
+
+**构建和启动：**
+
+```bash
+# 构建镜像
+docker compose build
+
+# 启动服务
+docker compose up -d
+
+# 查看日志
+docker compose logs -f
+
+# 停止服务
+docker compose down
+```
+
+---
+
+### 方案 3：Nginx 反向代理
+
+**适用场景：** 生产环境，配合 Nginx 使用
+
+**Nginx 配置：**
+
+```nginx
+server {
+    listen 80;
+    server_name yourdomain.com;
+
+    # HTTPS 重定向
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name yourdomain.com;
+
+    # SSL 证书
+    ssl_certificate /etc/nginx/ssl/yourdomain.com.pem;
+    ssl_certificate_key /etc/nginx/ssl/yourdomain.com.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+
+    # Gzip 压缩
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xml+rss application/rss+xml font/truetype font/opentype application/vnd.ms-fontobject image/svg+xml;
+
+    # 静态资源缓存
+    location /_nuxt/ {
+        alias /path/to/.output/public/_nuxt/;
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # 其他静态文件
+    location /static/ {
+        alias /path/to/.output/public/static/;
+        expires 30d;
+        add_header Cache-Control "public";
+    }
+
+    # 代理到 Nuxt
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        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_cache_bypass $http_upgrade;
+    }
+
+    # 错误页面
+    error_page 404 /404.html;
+    error_page 500 502 503 504 /50x.html;
+}
+```
+
+---
+
+## 四、路由规则配置
+
+项目已配置以下路由规则（nuxt.config.ts）：
+
+```typescript
+nitro: {
+  routeRules: {
+    '/': { isr: 60 },           // 首页每60秒重新验证
+    '/article/**': { isr: 300 }, // 文章页每300秒重新验证
+    '/admin/**': { ssr: false }, // 管理后台纯客户端渲染
+  },
+}
+```
+
+---
+
+## 五、环境变量说明
+
+| 变量名 | 说明 | 默认值 | 必填 |
+|-------|------|-------|-----|
+| NUXT_PUBLIC_API_BASE | 后端 API 地址 | http://localhost:3001 | 是 |
+| NUXT_PUBLIC_SITE_URL | 站点 URL | http://localhost:3000 | 否 |
+| NUXT_PUBLIC_SITE_NAME | 站点名称 | LinkShare Blog | 否 |
+| PORT | 服务端口 | 3000 | 否 |
+
+---
+
+## 六、常见问题
+
+### 6.1 启动报错 "Cannot find module"
+
+**原因：** 构建产物未正确复制
+
+**解决：** 确保 `.output` 目录完整，运行 `pnpm run build` 重新构建
+
+### 6.2 API 请求跨域
+
+**原因：** 后端 CORS 配置不正确
+
+**解决：** 后端需允许前端域名，建议使用 Nginx 反向代理，前端和后端同源
+
+### 6.3 页面加载慢
+
+**原因：** SSR 首次渲染较慢
+
+**解决：** 
+- 调整 ISR 缓存时间（nuxt.config.ts 中的 routeRules）
+- 使用 CDN 加速静态资源
+- 启用 Nginx Gzip 压缩
+
+### 6.4 内存占用过高
+
+**原因：** Node.js 默认内存限制
+
+**解决：** 
+```bash
+node --max-old-space-size=4096 .output/server/index.mjs
+```
+
+---
+
+## 七、生产环境检查清单
+
+- [ ] 环境变量已正确配置
+- [ ] 后端 API 地址正确
+- [ ] SSL 证书已配置（HTTPS）
+- [ ] Nginx 反向代理已配置
+- [ ] Gzip 压缩已启用
+- [ ] 静态资源缓存策略已设置
+- [ ] 进程管理工具已配置（PM2/Docker）
+- [ ] 错误监控已配置（可选）
+
+---
+
+## 八、监控和日志
+
+### 8.1 PM2 日志
+
+```bash
+# 实时日志
+pm2 logs binglogy-blog --lines 100
+
+# 错误日志
+pm2 logs binglogy-blog --err
+
+# 日志文件位置
+~/.pm2/logs/
+```
+
+### 8.2 Docker 日志
+
+```bash
+# 实时日志
+docker logs -f binglogy-blog
+
+# 最近100行
+docker logs --tail 100 binglogy-blog
+```
+
+### 8.3 Nginx 日志
+
+```bash
+# 访问日志
+tail -f /var/log/nginx/access.log
+
+# 错误日志
+tail -f /var/log/nginx/error.log
+```