常见问题
本文档收集了 AudioDock 使用和开发过程中的常见问题及解决方案。
目录
安装问题
Q1: 安装时出现 “command not found: npm” 错误
A: 您的系统没有安装 Node.js 和 npm。
解决方案:
# macOS (使用 Homebrew)
brew install node
# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm
# Windows
# 从 https://nodejs.org/ 下载安装包Q2: 安装依赖时出现网络超时错误
A: 可能是网络问题或 npm 镜像源问题。
解决方案:
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 或者使用 yarn
npm install -g yarn
yarn install
# 设置代理（如果需要）
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080Q3: 数据库迁移失败
A: 数据库连接配置错误或权限不足。
解决方案:
# 检查数据库服务是否运行
sudo systemctl status postgresql
# 检查连接配置
cat .env | grep DATABASE_URL
# 手动创建数据库
createdb audiodock_dev
psql -d audiodock_dev -c "CREATE USER audiodock WITH PASSWORD 'password';"
psql -d audiodock_dev -c "GRANT ALL PRIVILEGES ON DATABASE audiodock_dev TO audiodock;"使用问题
Q4: 音乐文件无法导入
A: 文件格式不支持或文件损坏。
解决方案:
- 检查文件格式: AudioDock 支持 MP3, FLAC, AAC, WAV, OGG, M4A 格式
- 检查文件权限: 确保应用有读取文件的权限
- 检查文件完整性: 尝试用其他播放器打开文件
- 查看日志: 检查应用日志获取详细错误信息
Q5: 播放时没有声音
A: 音频输出配置错误或系统音频问题。
解决方案:
- 检查系统音量: 确保系统音量未静音
- 检查音频输出设备: 在设置中选择正确的音频输出设备
- 重启音频服务:
# macOS sudo killall coreaudiod # Linux pulseaudio -k && pulseaudio --start - 检查音频文件: 尝试播放其他文件
Q6: 同步功能不工作
A: 网络问题或设备配置错误。
解决方案:
- 检查网络连接: 确保所有设备在同一网络中
- 检查防火墙: 确保端口 3001 未被防火墙阻止
- 重新登录: 在所有设备上重新登录账户
- 检查日志: 查看同步服务的日志信息
Q7: 歌词无法显示
A: 网络问题或歌曲信息不完整。
解决方案:
- 检查网络连接: 确保可以访问互联网
- 手动搜索歌词: 在歌曲详情页点击”搜索歌词”
- 检查歌曲信息: 确保歌曲有完整的元数据（标题、艺术家）
- 使用本地歌词: 将歌词文件 (.lrc) 放在歌曲同一目录
开发问题
Q8: 开发服务器启动失败
A: 端口被占用或配置错误。
解决方案:
# 检查端口占用
lsof -i :3000
lsof -i :3001
# 杀死占用进程
kill -9 <PID>
# 使用其他端口
npm run dev -- -p 3002
# 检查错误日志
npm run dev 2>&1 | grep -i errorQ9: TypeScript 编译错误
A: 类型定义缺失或版本不兼容。
解决方案:
# 安装缺失的类型定义
npm install --save-dev @types/node @types/react @types/react-dom
# 更新 TypeScript
npm install --save-dev typescript@latest
# 清理并重新构建
rm -rf node_modules package-lock.json
npm install
npm run buildQ10: 测试用例失败
A: 测试环境配置问题或代码变更。
解决方案:
# 运行特定测试查看详细错误
npm test -- --grep "测试名称"
# 更新测试快照
npm test -- -u
# 清理测试数据库
npm run test:clean
# 查看测试覆盖率报告
npm run test:coverageQ11: 插件开发问题
A: 插件接口不匹配或依赖问题。
解决方案:
- 检查插件接口: 确保实现了所有必需的方法
- 查看示例插件: 参考官方示例插件
- 调试插件:
// 启用调试模式 AudioDock.enableDebugging({ level: 'debug' }); // 检查插件注册 console.log(AudioDock.getRegisteredPlugins()); - 检查依赖版本: 确保插件与主应用版本兼容
部署问题
Q12: Docker 容器启动失败
A: 镜像问题或配置错误。
解决方案:
# 查看容器日志
docker logs <container_id>
# 检查镜像是否存在
docker images | grep audiodock
# 重新拉取镜像
docker-compose pull
# 检查 Docker 配置
docker info
docker versionQ13: 数据库连接失败
A: 数据库配置错误或网络问题。
解决方案:
# 测试数据库连接
psql -h localhost -U audiodock -d audiodock_prod
# 检查环境变量
echo $DATABASE_URL
# 检查网络连接
nc -zv localhost 5432
# 查看数据库日志
sudo journalctl -u postgresql -fQ14: 内存使用过高
A: 内存泄漏或配置不当。
解决方案:
- 监控内存使用:
# 查看进程内存 top -o mem # Docker 容器内存 docker stats # Kubernetes Pod 内存 kubectl top pods - 调整内存限制:
# docker-compose.yml services: api: deploy: resources: limits: memory: 1G - 启用内存分析:
node --inspect --inspect-brk app.js
Q15: SSL 证书问题
A: 证书过期或配置错误。
解决方案:
# 检查证书有效期
openssl x509 -in certificate.pem -noout -dates
# 重新生成证书 (Let's Encrypt)
certbot renew --force-renewal
# 测试 SSL 配置
openssl s_client -connect audiodock.example.com:443
# 更新 Nginx 配置
sudo nginx -t
sudo systemctl reload nginx故障排除
通用故障排除步骤
1. 查看日志
# 应用日志
tail -f /var/log/audiodock/app.log
# 系统日志
sudo journalctl -f
# Docker 日志
docker-compose logs -f
# Kubernetes 日志
kubectl logs -f deployment/audiodock-api2. 检查服务状态
# 系统服务
sudo systemctl status audiodock
# Docker 服务
docker-compose ps
# Kubernetes 服务
kubectl get all -n audiodock3. 测试网络连接
# 测试端口
nc -zv localhost 3000
nc -zv localhost 3001
# 测试 API
curl http://localhost:3001/health
# 测试数据库
psql -h localhost -U audiodock -c "SELECT 1;"4. 资源监控
# CPU 和内存
htop
# 磁盘使用
df -h
# 网络流量
iftop
# 进程监控
ps aux | grep audiodock紧急恢复步骤
服务不可用
-
重启服务:
sudo systemctl restart audiodock # 或 docker-compose restart # 或 kubectl rollout restart deployment/audiodock-api -
回滚到上一个版本:
# Docker docker-compose up -d --force-recreate # Kubernetes kubectl rollout undo deployment/audiodock-api -
启用维护模式:
# 设置维护页面 echo "系统维护中，请稍后再试" > /var/www/maintenance.html # 配置 Nginx 返回维护页面 sudo nginx -s reload
数据丢失
-
从备份恢复:
# 恢复数据库 gunzip -c backup.sql.gz | psql -U audiodock -d audiodock_prod # 恢复文件 tar -xzf backup_files.tar.gz -C /data/audiodock -
检查点恢复:
# PostgreSQL 时间点恢复 psql -U postgres -c "SELECT pg_start_backup('recovery');" # ... 恢复操作 ... psql -U postgres -c "SELECT pg_stop_backup();"
联系支持
如果以上解决方案都无法解决问题，请通过以下方式联系技术支持：
-
GitHub Issues: 报告问题
- 提供详细的错误信息
- 包含日志文件
- 描述复现步骤
-
Discord 社区: 加入讨论
- 实时技术支持
- 社区帮助
- 功能讨论
-
邮箱支持: support@audiodock.com
- 企业级支持
- 安全漏洞报告
- 功能请求
提供信息时请包含:
- AudioDock 版本号
- 操作系统和版本
- 错误日志
- 复现步骤
- 已尝试的解决方案
相关文档: