常见问题

本文收集了使用过程中的常见问题及解决方案。

安装部署

Q: 端口被占用怎么办？

解决方案：

1. 检查哪个进程占用了端口：

# Linux/Mac
lsof -i :80
lsof -i :7501

# Windows
netstat -ano | findstr :80

2. 修改配置文件 server/configs/config.yaml 中的端口配置

3. 重新启动服务：

sudo systemctl restart mika

Q: 数据库连接失败？

解决方案：

1. 检查 MySQL 服务是否正常运行：

systemctl status mysql

2. 确认数据库配置正确，检查 server/configs/config.yaml
3. 检查数据库用户权限
4. 查看 MySQL 日志：

tail -f /var/log/mysql/error.log

Q: 如何重新进入安装引导？

解决方案：

删除安装配置文件，然后重启服务：

rm server/configs/install.json
sudo systemctl restart mika

再次访问系统即可进入安装引导页。

Q: 宝塔面板部署后 502 错误？

解决方案：

1. 检查后端服务是否运行：

systemctl status mika

2. 检查端口是否监听：

netstat -tlnp | grep 7501

3. 查看后端日志：

journalctl -u mika -n 100

4. 检查 Nginx 代理配置是否正确

视频转码

Q: 视频转码失败？

排查步骤：

1. 检查 FFmpeg 是否正确安装：

ffmpeg -version

2. 检查磁盘空间：

df -h

3. 查看转码任务日志
4. 检查视频文件是否损坏

常见原因：

• FFmpeg 未安装或版本过低
• 磁盘空间不足
• 视频文件损坏
• 不支持的视频格式

Q: 转码速度很慢？

优化建议：

1. 启用硬件加速：

   • NVIDIA GPU: 使用 h264_nvenc
   • Intel CPU: 使用 h264_qsv

2. 调整转码参数：

transcode:
  preset: fast  # 从 medium 改为 fast

3. 降低并发数：

queue:
  max_concurrent: 1  # 减少并发

4. 升级服务器配置：推荐 4 核 8GB 以上

Q: 转码后画质差？

解决方案：

1. 提高输出码率：

transcode:
  video_bitrate: 5000  # 提高码率

2. 降低 CRF 值（值越小质量越高）：

transcode:
  crf: 20  # 默认 23，改为 20

3. 使用更高的分辨率输出

Q: 播放视频卡顿？

排查步骤：

1. 检查服务器带宽
2. 检查视频码率是否过高
3. 启用 CDN 加速
4. 检查播放器配置

优化建议：

• 降低视频码率
• 启用多码率自适应
• 使用 CDN 分发
• 优化分片时长

存储问题

Q: 上传大文件失败？

解决方案：

1. 修改 Nginx 配置：

client_max_body_size 5G;
client_body_timeout 3600s;
proxy_read_timeout 3600s;

2. 修改系统上传限制：

upload:
  max_size: 5368709120  # 5GB

3. 使用分片上传功能

Q: 存储空间不足？

解决方案：

1. 清理临时文件：

# 手动清理
rm -rf app/public/temp/*

# 或使用系统清理功能

2. 删除不需要的视频
3. 迁移到云存储（OSS/COS）
4. 扩展磁盘空间

Q: 云存储上传失败？

排查步骤：

1. 检查 AccessKey 配置是否正确
2. 检查 Bucket 权限设置
3. 检查网络连接
4. 查看错误日志

常见原因：

• AccessKey 无权限
• Bucket 不存在或区域错误
• 网络连接问题
• 跨域配置问题

Q: 视频无法播放，提示跨域错误？

解决方案：

1. 配置 Nginx 跨域头：

add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods GET,HEAD;

2. 云存储配置 CORS：

{
  "AllowedOrigin": ["*"],
  "AllowedMethod": ["GET", "HEAD"],
  "AllowedHeader": ["*"]
}

用户相关

Q: 忘记管理员密码？

解决方案：

方法一：使用命令行工具

./server reset-password --username admin --password newpassword

方法二：直接修改数据库

-- 使用 bcrypt 加密的密码哈希
UPDATE users SET password = '新密码哈希' WHERE username = 'admin';

Q: 用户无法登录？

排查步骤：

1. 检查账号状态是否被禁用
2. 检查密码是否正确
3. 检查是否超过登录尝试限制
4. 清除浏览器缓存和 Cookie
5. 查看登录日志

Q: Token 频繁失效？

解决方案：

1. 增加 Token 有效期：

jwt:
  expire: 604800  # 7 天

2. 启用 Token 自动刷新
3. 检查服务器时间是否正确

性能问题

Q: 系统响应慢？

优化建议：

1. 启用缓存：

cache:
  video:
    enabled: true
    ttl: 3600

2. 优化数据库：

   • 添加索引
   • 优化慢查询
   • 增加连接池

3. 使用 CDN 加速静态资源

4. 升级服务器配置

Q: 数据库查询慢？

解决方案：

1. 开启慢查询日志：

database:
  slow_query:
    enabled: true
    threshold: 200  # 毫秒

2. 分析慢查询并添加索引
3. 优化 SQL 语句
4. 考虑读写分离

Q: 内存占用过高？

排查步骤：

1. 检查转码并发数是否过多
2. 检查是否有内存泄漏
3. 限制缓存大小
4. 增加服务器内存

其他问题

Q: 如何备份数据？

备份命令：

# 备份数据库
mysqldump -u root -p mika_transcode > backup_$(date +%Y%m%d).sql

# 备份视频文件
tar -czvf videos_backup.tar.gz app/public/videos/

# 备份配置文件
cp -r server/configs configs_backup/

Q: 如何升级系统？

升级步骤：

1. 备份数据和配置文件
2. 从发布页下载最新版本压缩包
3. 解压新版本覆盖旧文件
4. 重启服务：

# 停止服务
ps aux | grep mika-server
kill xxxxx

# 启动新版本
nohup ./bin/mika-server > server.log 2>&1 &

5. 检查数据库迁移（如有）

Q: 如何查看系统日志？

日志位置：

日志	位置
应用日志	server/logs/app.log
Nginx 日志	/var/log/nginx/
MySQL 日志	/var/log/mysql/

查看命令：

# 应用日志
tail -f server/logs/app.log

# 服务日志
journalctl -u mika -f

Q: 如何联系技术支持？

支持渠道：

1. 提交 GitHub Issue
2. 发送邮件至 support@example.com
3. 加入交流群

提交问题时请提供：

• 系统版本
• 部署方式
• 错误日志
• 复现步骤

下一步

• 系统配置 - 详细配置说明
• API 接口 - API 文档
• 项目介绍 - 了解更多功能