# 🚀 生产环境部署指南

## 📋 配置信息

- **生产域名：** `https://sports.rucky.cn`
- **Spotify Client ID：** `4ed200672ba1421baa31b9859bd84d39`
- **Redirect URI：** `https://sports.rucky.cn/`

## ✅ 部署前检查清单

### 1. Spotify Dashboard 配置

- [ ] 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
- [ ] 在 "Edit Settings" 中添加以下 Redirect URIs：
  - `http://localhost:5173/` （开发环境）
  - `https://sports.rucky.cn/` （生产环境）
- [ ] 点击 "Save" 保存设置

### 2. HTTPS 配置

- [ ] 确保生产域名已配置 SSL 证书
- [ ] 确保 `https://sports.rucky.cn` 可以正常访问
- [ ] 检查 HTTPS 重定向是否正确配置

### 3. 构建应用

```bash
# 安装依赖
npm install

# 构建生产版本
npm run build
```

构建完成后，`dist` 目录包含所有生产文件。

### 4. 部署文件

将 `dist` 目录的内容部署到你的服务器：

```bash
# 示例：使用 rsync 部署
rsync -avz --delete dist/ user@sports.rucky.cn:/var/www/sports.rucky.cn/

# 或使用 scp
scp -r dist/* user@sports.rucky.cn:/var/www/sports.rucky.cn/
```

## 🔧 Web 服务器配置

⚠️ **重要：必须配置 SPA 路由支持，否则刷新页面会 404！**

参考完整配置文件：
- `nginx.conf.example` - Nginx 完整配置
- `public/.htaccess` - Apache 配置（已自动包含在构建中）
- 详细说明见 `FIX_404_PROBLEM.md`

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name sports.rucky.cn;
    
    # HTTPS 重定向
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name sports.rucky.cn;
    
    # SSL 证书配置
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    
    # 网站根目录
    root /var/www/sports.rucky.cn;
    index index.html;
    
    # 🔥 关键配置：SPA 路由支持（解决刷新 404 问题）
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/javascript application/json;
}
```

### Apache 配置示例

⚠️ **`.htaccess` 文件已自动包含在 `public/` 目录中，构建时会自动复制到 `dist/`**

```apache
<VirtualHost *:80>
    ServerName sports.rucky.cn
    Redirect permanent / https://sports.rucky.cn/
</VirtualHost>

<VirtualHost *:443>
    ServerName sports.rucky.cn
    DocumentRoot /var/www/sports.rucky.cn
    
    # SSL 配置
    SSLEngine on
    SSLCertificateFile /path/to/your/certificate.crt
    SSLCertificateKeyFile /path/to/your/private.key
    
    # 🔥 关键配置：允许 .htaccess 覆盖（SPA 路由支持）
    <Directory /var/www/sports.rucky.cn>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    
    # 启用 Gzip
    <IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript application/json
    </IfModule>
</VirtualHost>
```

## 🧪 部署后测试

### 1. 基本访问测试
```bash
# 检查网站是否可访问
curl -I https://sports.rucky.cn/

# 应该返回 200 OK
```

### 2. Spotify 授权测试

1. 访问 `https://sports.rucky.cn/`
2. 点击 "音乐律动·步频检测"
3. 点击 "Spotify" 标签
4. 点击 "连接 Spotify 账号"
5. 应该正确跳转到 Spotify 授权页面
6. 授权后应该正确返回到你的应用

### 3. 功能测试

- [ ] 步频模式选择正常
- [ ] Spotify 授权流程正常
- [ ] 搜索功能正常
- [ ] 播放控制正常
- [ ] 可视化效果正常

## ⚠️ 常见问题

### Q1: 刷新页面出现 404 错误 🔥

**问题：** 访问 `https://sports.rucky.cn/music-rhythm` 正常，但刷新页面后出现 404

**原因：** 服务器没有配置 SPA 路由支持

**解决：**

**Nginx：**
```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

**Apache：**
确保 `AllowOverride All` 已启用，`.htaccess` 会自动处理

**测试：**
```bash
# 应该返回 index.html 而不是 404
curl -I https://sports.rucky.cn/music-rhythm
```

详细说明见：[FIX_404_PROBLEM.md](./FIX_404_PROBLEM.md)

### Q2: 授权后出现 "Redirect URI mismatch" 错误

**原因：** Redirect URI 配置不正确

**解决：**
1. 检查 Spotify Dashboard 中是否已添加 `https://sports.rucky.cn/`
2. 注意必须包含最后的斜杠 `/`
3. 确保协议是 `https://` 而不是 `http://`
4. 保存后等待几分钟让配置生效

### Q3: 静态资源加载失败

**原因：** 路径配置问题

**解决：**
1. 检查 `vite.config.js` 中的 `base` 配置
2. 确保静态资源路径正确
3. 检查文件权限

### Q4: HTTPS 证书问题

**解决：**
- 使用 Let's Encrypt 免费证书：
  ```bash
  # 安装 Certbot
  sudo apt-get install certbot python3-certbot-nginx
  
  # 获取证书
  sudo certbot --nginx -d sports.rucky.cn
  ```

## 🔐 安全建议

1. **启用 HTTPS**
   - 必须使用 HTTPS，否则 Spotify 授权可能失败
   - 定期更新 SSL 证书

2. **配置安全头**
   ```nginx
   add_header X-Frame-Options "SAMEORIGIN" always;
   add_header X-Content-Type-Options "nosniff" always;
   add_header X-XSS-Protection "1; mode=block" always;
   add_header Referrer-Policy "no-referrer-when-downgrade" always;
   ```

3. **保护 Client ID**
   - Client ID 可以公开，但注意限制 Redirect URI
   - 定期检查 Spotify Dashboard 的访问日志

4. **定期更新**
   - 定期更新依赖包
   - 关注安全漏洞公告

## 📊 性能优化

1. **启用缓存**
   - 静态资源设置长期缓存
   - HTML 文件设置短期缓存

2. **启用压缩**
   - Gzip/Brotli 压缩
   - 减少传输大小

3. **CDN 加速**（可选）
   - 将静态资源部署到 CDN
   - 提升全球访问速度

4. **监控性能**
   - 使用 Google Analytics
   - 监控页面加载时间
   - 追踪用户体验指标

## 🔄 更新部署

```bash
# 1. 拉取最新代码
git pull origin main

# 2. 安装依赖
npm install

# 3. 构建
npm run build

# 4. 备份当前版本
mv /var/www/sports.rucky.cn /var/www/sports.rucky.cn.backup

# 5. 部署新版本
rsync -avz --delete dist/ user@sports.rucky.cn:/var/www/sports.rucky.cn/

# 6. 测试
curl -I https://sports.rucky.cn/

# 7. 如果有问题，快速回滚
# mv /var/www/sports.rucky.cn.backup /var/www/sports.rucky.cn
```

## 📱 移动端适配

应用已适配移动端，确保：
- [ ] 响应式设计正常工作
- [ ] 触摸事件正常
- [ ] 移动端 Spotify 授权正常

## 🎯 环境变量（可选）

如果需要不同环境的配置，可以使用环境变量：

```javascript
// vite.config.js
export default {
  define: {
    'import.meta.env.VITE_SPOTIFY_CLIENT_ID': JSON.stringify(process.env.VITE_SPOTIFY_CLIENT_ID || '4ed200672ba1421baa31b9859bd84d39')
  }
}
```

```bash
# .env.production
VITE_SPOTIFY_CLIENT_ID=4ed200672ba1421baa31b9859bd84d39
```

## 📞 支持

如遇到问题：
1. 查看浏览器控制台错误
2. 检查网络请求
3. 查看 Spotify API 错误信息
4. 参考 [Spotify 开发者社区](https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer)

---

**部署成功后，记得分享你的音乐律动应用！** 🎉