diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..7aafa14 --- /dev/null +++ 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 快速部署验证,后续根据需求迁移到自托管方案。