humanus.cpp/.devops/DOCKER_README.md

# 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"错误，不要尝试修改容器内的只读文件，而是通过环境变量配置