nuwax安装部署过程中常见问题

安装部署过程中可能遇到的常见问题及解决方案如下：

🔧 安装部署常见问题及解决方案

1. 服务启动失败

• 问题表现：Docker服务无法正常启动
• 解决方案：
  1. 检查 Docker 是否正常运行
  2. 使用 ./nuwax-cli status 查看详细状态
  3. 检查端口是否被占用

2. 无法访问服务

• 问题表现：浏览器无法打开 http://localhost
• 解决方案：
  1. 确认服务已正常启动
  2. 输入 docker ps 命令查看容器状态
  3. 使用 ./nuwax-cli ducker 查看容器启动情况
  4. 检查防火墙设置
  5. 确认端口配置正确

3. 权限问题 - Permission denied

• 问题表现：出现 "Permission denied" 错误

• 解决方案：

  • Linux（Ubuntu 22.04 LTS）：确保用户在 docker 组中
  • macOS：允许未知开发者运行，确保OrbStack或Docker Desktop已启动
  • 使用 sudo 执行命令：sudo ./nuwax-cli auto-upgrade-deploy run

  [图片上传失败...(image-dbbbe3-1769217097965)]

4. 配置文件问题

• 问题表现：配置错误导致服务异常
• 解决方案：
  1. 使用 ./nuwax-cli init --force 重新初始化配置
  2. 检查 config.toml 文件是否存在

5. 页面无法正常打开

• 问题表现：服务启动但页面无法访问

• 解决方案：

  1. 执行命令：./nuwax-cli ducker
  2. 查看容器管理界面，检查 frontend、backend 容器是否启动
  3. 如果容器未启动，选中容器后按 r (run) 启动容器
  4. 在浏览器打开 "http://localhost" 查看是否正常访问

  [图片上传失败...(image-d14b16-1769217097965)]

6. 解压失败 - Directory not empty(os error 39)

• 问题表现：解压时出现目录非空错误

• 解决方案：

  # 先完全停止掉docker服务
  ./nuwax-cli docker-service stop
  
  # 重新执行一键部署命令
  ./nuwax-cli auto-upgrade-deploy run
  

  [图片上传失败...(image-783f58-1769217097965)]

7. 界面提示系统异常

• 问题表现：登录后界面显示系统异常

• 解决方案：

  1. 查看后台系统日志：./docker/logs/agent/app.log
  2. 重启服务（推荐）：

     ./nuwax-cli docker-service restart
     

  3. 或者停止后重新启动：

     ./nuwax-cli docker-service stop
     ./nuwax-cli docker-service start
     

  [图片上传失败...(image-7783ed-1769217097965)]

8. 下载失败 - error decoding response body

• 问题表现：网络原因导致下载失败

• 解决方案：

  1. 重新执行一键部署命令，会自动断点续传：

     ./nuwax-cli auto-upgrade-deploy run
     

  [图片上传失败...(image-5300f6-1769217097965)]

📋 常用管理命令

服务管理

• 启动服务：./nuwax-cli docker-service start
• 停止服务：./nuwax-cli docker-service stop
• 重启服务：./nuwax-cli docker-service restart
• 检查状态：./nuwax-cli docker-service status

部署命令

• 初始化配置：./nuwax-cli init
• 一键部署：./nuwax-cli auto-upgrade-deploy run
• 指定端口部署：./nuwax-cli auto-upgrade-deploy run --port 8099

💡 预防措施

1. 环境准备：确保系统满足要求（Ubuntu 22.04 LTS或以上，4核8G或以上）
2. 权限检查：确保有Docker权限，验证方式 docker ps
3. 端口检查：确保80端口未被占用，或使用指定端口部署
4. 网络稳定：确保网络连接稳定，避免下载中断

如果遇到其他问题，建议查看详细日志文件或联系技术支持。更多详细信息可参考安装部署文档。