docs: 添加生产环境部署指南

2026-01-11 22:06:42 +08:00
parent a6efb5a7e7
commit 39ed862064
1 changed files with 238 additions and 0 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,238 @@
+# AI 写作工坊 - 生产环境部署指南
+
+## 🏗️ 项目架构
+
+本项目是一个纯前端 Vue 3 应用，使用 Vite 构建，数据存储在浏览器 IndexedDB 中。
+
+### 技术栈
+- **前端框架**: Vue 3 + Composition API
+- **构建工具**: Vite
+- **状态管理**: Pinia
+- **数据存储**: IndexedDB (sql.js)
+- **API 调用**: 直接调用各 LLM 服务商 API
+
+## 📦 构建生产版本
+
+```bash
+# 安装依赖
+npm install
+
+# 构建生产版本
+npm run build
+
+# 预览生产版本
+npm run preview
+```
+
+构建产物位于 `dist/` 目录，是纯静态文件。
+
+---
+
+## 🚀 部署方案
+
+### 方案一：Vercel（推荐）
+
+最简单的部署方式，自动 CI/CD。
+
+1. **连接仓库**
+   - 访问 [vercel.com](https://vercel.com)
+   - 导入 Git 仓库
+
+2. **配置环境变量**
+   在 Vercel 控制台设置：
+   ```
+   VITE_DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions
+   VITE_DEEPSEEK_API_KEY=sk-xxx
+   VITE_DEEPSEEK_MODEL=deepseek-chat
+   ```
+
+3. **部署**
+   - 每次 push 到 main 分支自动部署
+
+### 方案二：Netlify
+
+与 Vercel 类似的静态站点托管。
+
+1. 在 Netlify 导入仓库
+2. 构建命令: `npm run build`
+3. 发布目录: `dist`
+4. 在 Site settings > Environment 设置环境变量
+
+### 方案三：自托管 Nginx
+
+适合私有化部署。
+
+1. **构建**
+   ```bash
+   npm run build
+   ```
+
+2. **Nginx 配置**
+   ```nginx
+   server {
+       listen 80;
+       server_name your-domain.com;
+       root /var/www/ai-writer/dist;
+       index index.html;
+
+       # SPA 路由支持
+       location / {
+           try_files $uri $uri/ /index.html;
+       }
+
+       # 静态资源缓存
+       location /assets {
+           expires 1y;
+           add_header Cache-Control "public, immutable";
+       }
+
+       # Gzip 压缩
+       gzip on;
+       gzip_types text/plain text/css application/json application/javascript;
+   }
+   ```
+
+3. **部署脚本**
+   ```bash
+   #!/bin/bash
+   cd /path/to/ai-writer
+   git pull origin main
+   npm install
+   npm run build
+   rsync -avz dist/ /var/www/ai-writer/dist/
+   ```
+
+### 方案四：Docker
+
+适合容器化部署。
+
+1. **Dockerfile**
+   ```dockerfile
+   # 构建阶段
+   FROM node:20-alpine as builder
+   WORKDIR /app
+   COPY package*.json ./
+   RUN npm ci
+   COPY . .
+   ARG VITE_DEEPSEEK_API_KEY
+   ARG VITE_DEEPSEEK_API_URL
+   RUN npm run build
+
+   # 运行阶段
+   FROM nginx:alpine
+   COPY --from=builder /app/dist /usr/share/nginx/html
+   COPY nginx.conf /etc/nginx/conf.d/default.conf
+   EXPOSE 80
+   CMD ["nginx", "-g", "daemon off;"]
+   ```
+
+2. **构建并运行**
+   ```bash
+   docker build \
+     --build-arg VITE_DEEPSEEK_API_KEY=sk-xxx \
+     --build-arg VITE_DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions \
+     -t ai-writer .
+   
+   docker run -d -p 8080:80 ai-writer
+   ```
+
+---
+
+## ⚠️ 安全注意事项
+
+### API Key 安全
+
+由于这是纯前端应用，API Key 会被打包到 JS 文件中。有以下解决方案：
+
+1. **内部使用**：如果只在内网使用，风险可控
+
+2. **API 中继**（推荐）：
+   - 部署一个后端代理服务
+   - 前端调用代理，代理转发到 LLM API
+   - API Key 只存在于后端
+
+3. **IP 白名单**：
+   - 在 LLM 服务商配置 API Key 的 IP 白名单
+   - 限制只能从部署服务器的 IP 调用
+
+### 环境变量最佳实践
+
+```bash
+# 生产环境 .env.production
+VITE_DEEPSEEK_API_URL=https://your-proxy.com/v1/chat/completions
+VITE_DEEPSEEK_API_KEY=xxx
+```
+
+---
+
+## 📊 推荐部署架构
+
+```
+                    ┌─────────────┐
+                    │   用户浏览器  │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │  CDN / 边缘  │  (Vercel/Netlify/CloudFlare)
+                    └──────┬──────┘
+                           │
+              ┌────────────┴────────────┐
+              │                         │
+       ┌──────▼──────┐          ┌──────▼──────┐
+       │  静态资源    │          │  API 中继   │ (可选)
+       │  (dist/)    │          │  (后端代理)  │
+       └─────────────┘          └──────┬──────┘
+                                       │
+                                ┌──────▼──────┐
+                                │  LLM API    │
+                                │  (DeepSeek) │
+                                └─────────────┘
+```
+
+---
+
+## 🔧 持续部署 (GitHub Actions 示例)
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          
+      - name: Install & Build
+        run: |
+          npm ci
+          npm run build
+        env:
+          VITE_DEEPSEEK_API_KEY: ${{ secrets.VITE_DEEPSEEK_API_KEY }}
+          VITE_DEEPSEEK_API_URL: ${{ secrets.VITE_DEEPSEEK_API_URL }}
+          
+      - name: Deploy to Server
+        # 根据您的部署目标配置
+```
+
+---
+
+## 📝 总结
+
+| 方案 | 复杂度 | 适用场景 | 成本 |
+|-----|-------|---------|-----|
+| Vercel | ⭐ | 快速上线、个人项目 | 免费 |
+| Netlify | ⭐ | 同上 | 免费 |
+| Nginx | ⭐⭐ | 私有化部署 | 服务器成本 |
+| Docker | ⭐⭐⭐ | 企业级、容器编排 | 服务器成本 |
+
+**推荐**：先用 Vercel 快速部署验证，后续根据需求迁移到自托管方案。