322 lines
7.5 KiB
Markdown
322 lines
7.5 KiB
Markdown
# 🚀 生产环境部署指南
|
||
|
||
## 📋 配置信息
|
||
|
||
- **生产域名：** `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)
|
||
|
||
---
|
||
|
||
**部署成功后，记得分享你的音乐律动应用！** 🎉
|
||
|