newToy/PRODUCTION_DEPLOYMENT.md

🚀 生产环境部署指南

📋 配置信息

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

✅ 部署前检查清单

1. Spotify Dashboard 配置

• 访问 Spotify Developer Dashboard
• 在 "Edit Settings" 中添加以下 Redirect URIs：
  • http://localhost:5173/ （开发环境）
  • https://sports.rucky.cn/ （生产环境）
• 点击 "Save" 保存设置

2. HTTPS 配置

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

3. 构建应用

# 安装依赖
npm install

# 构建生产版本
npm run build

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

4. 部署文件

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

# 示例：使用 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 配置示例

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/

<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. 基本访问测试

# 检查网站是否可访问
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：

location / {
    try_files $uri $uri/ /index.html;
}

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

测试：

# 应该返回 index.html 而不是 404
curl -I https://sports.rucky.cn/music-rhythm

详细说明见：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 免费证书：

  # 安装 Certbot
  sudo apt-get install certbot python3-certbot-nginx
  
  # 获取证书
  sudo certbot --nginx -d sports.rucky.cn
  

🔐 安全建议

1. 启用 HTTPS

   • 必须使用 HTTPS，否则 Spotify 授权可能失败
   • 定期更新 SSL 证书

2. 配置安全头

   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
   • 监控页面加载时间
   • 追踪用户体验指标

🔄 更新部署

# 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 授权正常

🎯 环境变量（可选）

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

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

# .env.production
VITE_SPOTIFY_CLIENT_ID=4ed200672ba1421baa31b9859bd84d39

📞 支持

如遇到问题：

1. 查看浏览器控制台错误
2. 检查网络请求
3. 查看 Spotify API 错误信息
4. 参考 Spotify 开发者社区

---

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