5.1 KiB

Raw Blame History

Humanus.cpp Docker 开发环境使用指南

本文档提供了使用Docker环境来构建和运行Humanus.cpp项目的指南。

环境配置

Docker环境采用多阶段构建方式，包含以下组件：

Ubuntu 20.04 作为基础操作系统
C++ 编译工具链 (GCC, G++, CMake)
OpenSSL 开发库支持
Python3 开发环境
Node.js 18.x 和 npm 支持
预安装的npm包:
- @modelcontextprotocol/server-puppeteer
- @modelcontextprotocol/server-filesystem
- @kevinwatt/shell-mcp
- @modelcontextprotocol/server-everything

多阶段构建的优势

我们的Dockerfile采用了多阶段构建方法，具有以下优点：

优化镜像大小：最终镜像只包含运行时必要的组件
简化依赖管理：所有依赖都在构建阶段解决，运行阶段不需要网络连接
提高构建成功率：通过分离构建和运行环境，减少构建失败的风险
加快开发速度：预构建的工具链减少每次容器启动的准备时间

使用方法

构建并启动开发环境

使用提供的脚本最为简便：

# 使用便捷脚本启动开发环境
./.devops/scripts/start-dev.sh

此脚本会:

构建Docker镜像（使用多阶段构建）
启动容器
询问是否进入容器

也可以手动执行这些步骤：

# 进入项目根目录
cd /path/to/humanus.cpp

# 构建并启动容器
docker-compose -f .devops/docker-compose.yml build
docker-compose -f .devops/docker-compose.yml up -d

# 进入容器的交互式终端
docker-compose -f .devops/docker-compose.yml exec humanus bash

在容器内编译项目

使用提供的脚本：

# 使用便捷脚本构建项目
./.devops/scripts/build-project.sh

或者手动执行：

# 进入容器
docker-compose -f .devops/docker-compose.yml exec humanus bash

# 在容器内执行以下命令
cd /app/build
cmake ..
make -j$(nproc)

编译完成后，二进制文件将位于 /app/build/bin/ 目录下。

运行项目

可以通过以下方式运行编译后的项目：

# 从容器外运行
docker-compose -f .devops/docker-compose.yml exec humanus /app/build/bin/humanus_cli

# 或者在容器内运行
# 先进入容器
docker-compose -f .devops/docker-compose.yml exec humanus bash
# 然后在容器内运行
/app/build/bin/humanus_cli

开发工作流

在宿主机上修改代码
代码会通过挂载卷自动同步到容器内
在容器内重新编译项目
在容器内测试运行

注意事项

项目的构建文件存储在Docker卷humanus_build中，不会影响宿主机的构建目录
Node.js和npm已在镜像中预先安装，无需额外设置
默认暴露了8818端口，如果需要其他端口，请修改docker-compose.yml文件

网络问题解决方案

如果您在构建过程中仍然遇到网络连接问题，可以尝试以下解决方案：

解决EOF错误

如果遇到类似以下的EOF错误：

failed to solve: ubuntu:20.04: failed to resolve source metadata for docker.io/library/ubuntu:20.04: failed to authorize: failed to fetch anonymous token: Get "https://auth.docker.io/token?scope=repository%3Alibrary%2Fubuntu%3Apull&service=registry.docker.io": EOF

这通常是网络连接不稳定或Docker的DNS解析问题导致的。解决方法：

配置Docker镜像加速：

在Docker Desktop设置中添加以下配置：

{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

使用构建参数和标志：

# 使用选项3在start-dev.sh脚本中
# 或手动执行
docker-compose -f .devops/docker-compose.yml build --build-arg BUILDKIT_INLINE_CACHE=1 --network=host

尝试拉取基础镜像：

有时先单独拉取基础镜像可以解决问题：

docker pull ubuntu:20.04

设置代理

在终端中设置HTTP代理后再运行构建命令：

# 设置HTTP代理环境变量
export HTTP_PROXY=http://your-proxy-server:port
export HTTPS_PROXY=http://your-proxy-server:port
export NO_PROXY=localhost,127.0.0.1

# 然后运行构建
docker-compose -f .devops/docker-compose.yml build

使用Docker镜像加速器

在Docker Desktop设置中添加镜像加速器：

打开Docker Desktop
进入Settings -> Docker Engine
添加以下配置：

{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

点击"Apply & Restart"

问题排查

如果遇到问题，请尝试以下步骤：

检查容器日志：docker-compose -f .devops/docker-compose.yml logs humanus
重新构建镜像：docker-compose -f .devops/docker-compose.yml build --no-cache
重新创建容器：docker-compose -f .devops/docker-compose.yml up -d --force-recreate
网络问题：确认Docker可以正常访问互联网，或设置适当的代理
磁盘空间：确保有足够的磁盘空间用于构建和运行容器
如果看到"Read-only file system"错误，不要尝试修改容器内的只读文件，而是通过环境变量配置

5.1 KiB Raw Blame History Unescape Escape