快速上手教程_小龙虾ai本地部署怎么用 一键部署脚本与常见问题解答

1. 环境与需求检查

1.1 检查操作系统与资源：推荐 Ubuntu 20.04/22.04 或同类 Linux，至少 8GB 内存，磁盘 50GB 以上。
1.2 GPU 与驱动：若使用 GPU 推理，确认 NVIDIA 驱动与 CUDA（nvidia-smi 可用），同时安装 nvidia-docker2。若无 GPU 可使用 CPU 模式但速度较慢。
1.3 工具依赖：需安装 git、curl、docker、docker-compose、python3（可选），并确保用户有 sudo 权限。

2. 获取一键部署脚本

2.1 克隆代码库：在终端运行 git clone <仓库地址>，例如 git clone https://github.com/example/xiaolongxia-ai.git。
2.2 进入目录：cd xiaolongxia-ai，查看 README 与 deploy.sh（或 install.sh）等脚本文件。
2.3 校验脚本：用 cat deploy.sh 查看脚本内容，确认不会执行危险操作并记录所需参数。

3. 配置脚本前的准备工作

3.1 修改配置文件：若仓库有 .env 或 config.yaml，按说明设置模型路径、端口、GPU 参数（如 CUDA_VISIBLE_DEVICES）。
3.2 下载模型与资源：若脚本不自动下载，手动将模型文件放到指定目录（例如 ./models），建议检查 md5 或文件大小以确认完整性。
3.3 端口与防火墙：确认所用端口（默认 8000/8080 等）未被占用，配置 ufw/iptables 允许访问。

4. 给脚本执行权限并执行

4.1 添加可执行权限：chmod +x deploy.sh 或 chmod +x install.sh。
4.2 运行脚本：sudo ./deploy.sh 或 sudo ./install.sh，若脚本需要参数按说明传入（如 --model /path/to/model --gpu 0）。
4.3 观察输出：脚本会安装依赖、拉取容器或启动服务，注意终端输出的错误提示并记录日志路径。

5. Docker / Docker-Compose 部署说明

5.1 使用 docker-compose：若仓库包含 docker-compose.yml，运行 docker-compose up -d 启动服务。
5.2 GPU 支持：docker-compose.yml 中 service 下加 deploy.resources 或使用环境变量 NVIDIA_VISIBLE_DEVICES=all，并确保运行时使用 --gpus all。
5.3 常用诊断：docker ps 查看容器状态，docker logs <容器名> 查看日志，docker-compose logs -f 实时跟踪。

6. Python 虚拟环境与依赖安装（可选）

6.1 创建 venv：python3 -m venv venv；激活 source venv/bin/activate。
6.2 安装依赖：pip install -r requirements.txt，若有编译错误检查系统依赖（如 build-essential、libssl-dev）。
6.3 启动服务：一般为 python app.py 或 uvicorn main:app --host 0.0.0.0 --port 8000。

7. 常见问题与快速排错命令

7.1 端口被占用：sudo lsof -i :8000 或 sudo netstat -tulpn | grep 8000，找到进程并处理。
7.2 权限问题：遇到 permission denied，检查文件权限并使用 sudo 或 chown 调整所有者。
7.3 GPU 不可见：运行 nvidia-smi 若报错重装驱动，检查 docker run --gpus 支持并重启 docker 服务（sudo systemctl restart docker）。

8. 日志与服务管理

8.1 查看日志：docker logs -f <容器>，或 tail -f /var/log/<服务>.log。
8.2 开机自启：可将 docker-compose 服务配置成 systemd 服务或将启动脚本加入 crontab @reboot。
8.3 回滚与卸载：若需卸载，先 docker-compose down、删除镜像与容器并清理模型缓存。

9. 优化与安全建议

9.1 内存与并发：调低并发请求数或限制 batch size，避免 OOM；可在模型推理代码设定线程数。
9.2 网络安全：若需公网访问，建议放在反向代理（nginx）后并启用 HTTPS，或仅在内网使用。
9.3 更新策略：定期拉取仓库更新前先备份模型与配置，测试环境验证无误再推到生产。

10. 问：一键部署脚本运行报 “permission denied” 怎么办？

10.1 答：先使用 ls -l 查看脚本权限，执行 chmod +x deploy.sh；若仍报错，用 sudo ./deploy.sh 或检查文件系统是否为只读（mount 信息）。
10.2 若脚本内部调用需要写入的目录无权限，使用 sudo chown -R $(whoami):$(whoami) <目录> 或调整目录权限。

11. 问：模型下载过程太慢或失败，有替代方案吗？

11.1 答：可手动在另一台网络更好的机器上下载模型后通过 scp/sftp/外接硬盘拷贝到部署机器，或配置镜像加速（如国内镜像站）。
11.2 另外可修改脚本中下载 URL 为你自己已缓存的地址，并校验文件完整性。

12. 问：部署后访问接口超时或返回模型加载失败如何排查？

12.1 答：先查看服务日志（docker logs 或应用日志）确定是模型加载阶段 OOM、路径错误还是权限问题；确认模型文件完整且内存足够。
12.2 使用 top/htop/nvidia-smi 实时监控资源占用，必要时减小模型 batch 或启用 CPU 推理作为临时方案。

来源：快速上手教程_小龙虾ai本地部署怎么用 一键部署脚本与常见问题解答