194 lines
5.1 KiB
Markdown
194 lines
5.1 KiB
Markdown
# 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采用了多阶段构建方法，具有以下优点：
|
||
1. **优化镜像大小**：最终镜像只包含运行时必要的组件
|
||
2. **简化依赖管理**：所有依赖都在构建阶段解决，运行阶段不需要网络连接
|
||
3. **提高构建成功率**：通过分离构建和运行环境，减少构建失败的风险
|
||
4. **加快开发速度**：预构建的工具链减少每次容器启动的准备时间
|
||
|
||
## 使用方法
|
||
|
||
### 构建并启动开发环境
|
||
|
||
使用提供的脚本最为简便：
|
||
|
||
```bash
|
||
# 使用便捷脚本启动开发环境
|
||
./.devops/scripts/start-dev.sh
|
||
```
|
||
|
||
此脚本会:
|
||
1. 构建Docker镜像（使用多阶段构建）
|
||
2. 启动容器
|
||
3. 询问是否进入容器
|
||
|
||
也可以手动执行这些步骤：
|
||
|
||
```bash
|
||
# 进入项目根目录
|
||
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
|
||
```
|
||
|
||
### 在容器内编译项目
|
||
|
||
使用提供的脚本：
|
||
|
||
```bash
|
||
# 使用便捷脚本构建项目
|
||
./.devops/scripts/build-project.sh
|
||
```
|
||
|
||
或者手动执行：
|
||
|
||
```bash
|
||
# 进入容器
|
||
docker-compose -f .devops/docker-compose.yml exec humanus bash
|
||
|
||
# 在容器内执行以下命令
|
||
cd /app/build
|
||
cmake ..
|
||
make -j$(nproc)
|
||
```
|
||
|
||
编译完成后，二进制文件将位于 `/app/build/bin/` 目录下。
|
||
|
||
### 运行项目
|
||
|
||
可以通过以下方式运行编译后的项目：
|
||
|
||
```bash
|
||
# 从容器外运行
|
||
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
|
||
```
|
||
|
||
## 开发工作流
|
||
|
||
1. 在宿主机上修改代码
|
||
2. 代码会通过挂载卷自动同步到容器内
|
||
3. 在容器内重新编译项目
|
||
4. 在容器内测试运行
|
||
|
||
## 注意事项
|
||
|
||
- 项目的构建文件存储在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解析问题导致的。解决方法：
|
||
|
||
1. **配置Docker镜像加速**：
|
||
|
||
在Docker Desktop设置中添加以下配置：
|
||
|
||
```json
|
||
{
|
||
"registry-mirrors": [
|
||
"https://registry.docker-cn.com",
|
||
"https://docker.mirrors.ustc.edu.cn",
|
||
"https://hub-mirror.c.163.com"
|
||
]
|
||
}
|
||
```
|
||
|
||
2. **使用构建参数和标志**：
|
||
|
||
```bash
|
||
# 使用选项3在start-dev.sh脚本中
|
||
# 或手动执行
|
||
docker-compose -f .devops/docker-compose.yml build --build-arg BUILDKIT_INLINE_CACHE=1 --network=host
|
||
```
|
||
|
||
3. **尝试拉取基础镜像**：
|
||
|
||
有时先单独拉取基础镜像可以解决问题：
|
||
|
||
```bash
|
||
docker pull ubuntu:20.04
|
||
```
|
||
|
||
### 设置代理
|
||
|
||
在终端中设置HTTP代理后再运行构建命令：
|
||
|
||
```bash
|
||
# 设置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设置中添加镜像加速器：
|
||
|
||
1. 打开Docker Desktop
|
||
2. 进入Settings -> Docker Engine
|
||
3. 添加以下配置：
|
||
```json
|
||
{
|
||
"registry-mirrors": [
|
||
"https://registry.docker-cn.com",
|
||
"https://docker.mirrors.ustc.edu.cn",
|
||
"https://hub-mirror.c.163.com"
|
||
]
|
||
}
|
||
```
|
||
4. 点击"Apply & Restart"
|
||
|
||
## 问题排查
|
||
|
||
如果遇到问题，请尝试以下步骤：
|
||
|
||
1. 检查容器日志：`docker-compose -f .devops/docker-compose.yml logs humanus`
|
||
2. 重新构建镜像：`docker-compose -f .devops/docker-compose.yml build --no-cache`
|
||
3. 重新创建容器：`docker-compose -f .devops/docker-compose.yml up -d --force-recreate`
|
||
4. 网络问题：确认Docker可以正常访问互联网，或设置适当的代理
|
||
5. 磁盘空间：确保有足够的磁盘空间用于构建和运行容器
|
||
6. 如果看到"Read-only file system"错误，不要尝试修改容器内的只读文件，而是通过环境变量配置 |