# 容器部署

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本指南将介绍如何在Quectel Pi H1设备上安装和使用Docker，以便进行容器化应用的部署。

# 简介

Docker是一种轻量级的容器化技术，具有以下特点：

- **易管理**：使用Docker命令管理容器和镜像，依赖隔离，简化部署流程。

- **跨平台**：支持Windows、macOS和Linux系统，可在多种平台上运行和部署容器。

- **可移植性**：通过Dockerfile和镜像实现环境一致性，便于在不同机器或服务器上快速迁移和部署。

- **高效资源利用**：基于容器化技术，共享主机内核，资源占用低，启动速度快，适合微服务架构。

# 准备工作

在开始安装Docker之前，请确保满足以下条件：

**系统要求**：

- Quectel Pi H1设备已正常启动

- 已连接到网络（用于下载Docker镜像）

- 具有root权限或sudo权限

**网络准备**：

- 确保设备可以访问互联网（用于从Docker Hub拉取镜像）

- 如果在中国大陆地区，可能需要配置Docker镜像源以加速下载

**磁盘空间**：

- 确保有足够的磁盘空间用于存储Docker镜像和容器（建议至少2GB可用空间）

# 安装步骤

## 更新软件包列表并安装Docker

```bash
sudo apt update
sudo apt install docker.io
```

## 配置iptables

Docker需要配置iptables才能正常工作，执行以下命令：

```bash
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
```

执行上述命令后，需要重启系统以使配置生效：

```bash
sudo reboot
```

## 验证安装

系统重启后，验证Docker是否安装成功：

```bash
docker --version
```

若终端输出类似以下信息，则表示安装成功：

```plaintext
Docker version 26.1.5+dfsg1, build a72d7cd
```

## 添加用户权限

为了在不使用 *sudo* 的情况下运行Docker命令，可以将当前用户添加到Docker用户组：

```bash
sudo usermod -aG docker $USER
```

添加后，需要启动Docker服务并重新登录或重启系统以使配置生效：

```bash
# 启动Docker服务sudo systemctl start docker

# 设置Docker服务开机自启sudo systemctl enable docker
```

重新登录后，可以使用以下命令验证：

```bash
docker ps
```

如果不需要使用 *sudo* 即可执行，说明配置成功。

## 配置Docker镜像源（可选）

如果在中国大陆地区，访问Docker Hub可能较慢，可以配置国内镜像源加速下载。使用以下命令创建 */etc/docker/daemon.json* 文件：

```bash
sudo mkdir -p /etc/docker
sudo sh -c 'echo "{
  \"registry-mirrors\": [
    \"https://docker.mirrors.ustc.edu.cn\",
    \"https://hub-mirror.c.163.com\"
  ]
}" > /etc/docker/daemon.json'
```

配置完成后重启Docker服务：

```bash
sudo systemctl restart docker
```

# 功能使用

**提示**：

- **镜像（Image）**：包含应用程序及其运行环境（包括依赖、库、配置文件等）的只读模板。

- **容器（Container）**：镜像的运行实例，提供基于镜像的可执行环境，包含应用程序和所有依赖，但与主机系统隔离。

## 查看帮助

使用Docker内置的帮助命令查看所有命令的使用方法：

```bash
docker --help
docker <command> --help
```

```{image} images/image_IjyJb9IRzoF4xTxTNcUc8HPRnHg.webp
:width: 901px
:height: 809px
```

例如：

```bash
docker run --help
docker ps --help
```

## 查看Docker系统信息

使用 *docker info* 命令查看Docker系统信息，包括版本、系统配置、存储驱动、网络配置等：

```bash
docker info
```

```{image} images/image_Bl4sbz14Ao6OIdx8ip5cd4qNnid.webp
:width: 945px
:height: 766px
```

## 基本操作

### 拉取Docker镜像

使用 *docker pull* 命令从Docker Hub拉取所需的应用镜像：

```bash
docker pull <image_name># 示例：拉取hello-world最新镜像
docker pull hello-world
```

```{image} images/image_BIlwbtp9Ho3ETrxDeZ4cja1enbf.webp
:width: 733px
:height: 132px
```

### 运行Docker容器

使用 *docker run* 命令基于拉取的镜像运行容器：

```bash
# 运行hello-world容器（运行后会立即退出）
docker run hello-world

# 运行并指定容器名称
docker run --name my-hello hello-world
```

```{image} images/image_IoeebT3qsojevwxhnQMc57tEn8e.webp
:width: 933px
:height: 426px
```

**注意**：*hello-world* 镜像是一个演示镜像，运行后会打印欢迎信息然后退出。如果需要交互式操作或持续运行的容器，可以使用其他镜像，例如：

```bash
# 交互式运行容器（使用ubuntu镜像）
docker run -it ubuntu:20.04 /bin/bash

# 后台运行容器（使用ubuntu镜像）
docker run -d --name mycontainer ubuntu:20.04 tail -f /dev/null
```

### 查看容器和镜像

```bash
# 查看运行中的容器
docker ps# 查看所有容器（包括已停止的）
docker ps -a

# 查看本地镜像
docker images
```

### 停止和删除容器

```bash
# 停止容器
docker stop <container_id># 删除容器
docker rm <container_id># 删除镜像
docker rmi <image_id>
```

### 保存容器为新镜像

如果对容器进行了修改，可以使用 *docker commit* 命令将容器保存为新的镜像：

```bash
docker commit <container_id> <new_image_name>
```

例如：

```bash
# 查看容器ID
docker ps -a

# 将容器保存为新镜像
docker commit <container_id> my-hello-world:v1
```

## 数据卷（Volumes）

数据卷用于在容器和主机之间共享数据，即使容器被删除，数据卷中的数据仍然保留。

### 创建数据卷

```bash
docker volume create myvolume
```

### 使用数据卷运行容器

```bash
# 使用hello-world镜像（注意：hello-world运行后会立即退出）
docker run -v myvolume:/data hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d -v myvolume:/data ubuntu:20.04 tail -f /dev/null
```

上述命令将数据卷 *myvolume* 挂载到容器的 */data* 目录。

### 直接挂载主机目录

```bash
# 使用hello-world镜像
docker run -v /host/path:/container/path hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d -v /host/path:/container/path ubuntu:20.04 tail -f /dev/null
```

将主机的 */host/path* 目录挂载到容器的 */container/path* 目录。

### 管理数据卷

```bash
# 查看数据卷列表
docker volume ls# 查看数据卷详情
docker volume inspect myvolume

# 删除数据卷
docker volume rm myvolume
```

## 端口映射

端口映射允许将容器内的端口映射到主机的端口，以便从外部访问容器内的服务。

### 基本端口映射

```bash
docker run -d -p 8080:80 nginx
```

将容器的80端口映射到主机的8080端口。

### 指定主机IP的端口映射

```bash
docker run -d -p 127.0.0.1:8080:80 nginx
```

只允许通过主机的127.0.0.1访问。

### 查看端口映射

```bash
docker port <container_id>
```

## 环境变量

环境变量可以在运行容器时传递给容器内的应用程序。

### 使用-e参数设置环境变量

```bash
docker run -d -e MYSQL_ROOT_PASSWORD=password mysql:5.7
```

### 从文件读取环境变量

```bash
# 使用hello-world镜像
docker run --env-file .env hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d --env-file .env ubuntu:20.04 tail -f /dev/null
```

## 容器网络

Docker提供了多种网络模式，用于容器之间的通信。

### 创建自定义网络

```bash
docker network create mynetwork
```

### 将容器连接到网络

```bash
# 使用hello-world镜像
docker run --network mynetwork --name container1 hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d --network mynetwork --name container2 ubuntu:20.04 tail -f /dev/null
```

连接到同一网络的容器可以通过容器名称相互通信。

### 管理网络

```bash
# 查看网络列表
docker network ls# 查看网络详情
docker network inspect mynetwork

# 断开容器网络连接
docker network disconnect mynetwork container1
```

## 容器重启策略

可以设置容器的重启策略，使容器在退出后自动重启：

```bash
# 使用hello-world镜像（注意：hello-world运行后会立即退出）
docker run --restart=always --name my-hello hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d --restart=always --name mycontainer ubuntu:20.04 tail -f /dev/null
```

重启策略选项：

- *no*：不自动重启（默认）

- *always*：总是重启

- *on-failure*：仅在非正常退出时重启

- *unless-stopped*：除非手动停止，否则总是重启

## 容器资源限制

可以限制容器使用的CPU和内存资源：

### 限制内存使用

```bash
# 使用hello-world镜像
docker run -m 512m hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d -m 512m ubuntu:20.04 tail -f /dev/null
```

限制容器最多使用512MB内存。

### 限制CPU使用

```bash
# 使用hello-world镜像
docker run --cpus="1.5" hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d --cpus="1.5" ubuntu:20.04 tail -f /dev/null
```

限制容器最多使用1.5个CPU核心。

## 其他常用命令

- **查看容器日志**：

```bash
docker logs <container_id>
docker logs -f <container_id>  # 实时查看
```

- **进入运行中的容器**：

```bash
docker exec -it <container_id> /bin/bash
```

- **查看容器资源使用情况**：

```bash
docker stats
docker stats <container_id>  # 查看特定容器
```

- **查看容器详细信息**：

```bash
docker inspect <container_id>
```

- **复制文件**：

```bash
docker cp /host/path/file.txt <container_id>:/container/path/  # 复制到容器
docker cp <container_id>:/container/path/file.txt /host/path/  # 从容器复制
```

- **暂停/恢复容器**：

```bash
docker pause <container_id>
docker unpause <container_id>
```

- **清理未使用的资源**：

```bash
docker system prune -a
```

# 常见问题

## 无法访问Docker Hub，拉取镜像失败

**问题描述**：在中国大陆地区，直接访问Docker Hub可能较慢或失败。

**解决方案**：

- 配置Docker镜像源（参考安装步骤中的"配置Docker镜像源"部分）

- 使用代理服务器

- 使用国内镜像仓库，如阿里镜像源、腾讯镜像源等

## 执行docker命令时提示权限不足

**问题描述**：执行 *docker ps* 等命令时提示 *permission denied*。

**解决方案**：

- 确保已将用户添加到Docker用户组：

```bash
sudo usermod -aG docker $USER
```

- 重新登录或重启系统

- 如果仍然不行，可以使用 *sudo* 执行命令（不推荐）

## Docker服务无法启动

**问题描述**：执行 *docker ps* 时提示 *Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?*

**解决方案**：

- **检查Docker服务状态**：

```bash
sudo systemctl status docker
```

- 如果服务未运行，会显示 *inactive (dead)* 状态。

- **启动Docker服务**：

```bash
sudo systemctl start docker
```

- 启动后再次检查状态确认服务已运行。

- **设置Docker服务开机自启**：

```bash
sudo systemctl enable docker
```

- 确保系统重启后Docker服务自动启动。

- **检查Docker socket文件权限**：

```bash
ls -l /var/run/docker.sock
```

- 如果文件不存在或权限不正确，重启Docker服务：

```bash
sudo systemctl restart docker
```

- **检查用户是否在docker组中**：

```bash
groups
```

- 如果输出中没有 *docker*，需要将用户添加到docker组（参考安装步骤中的"添加用户权限"部分）。

- **确保iptables已正确配置**：  
如果Docker服务启动失败，可能是iptables配置问题，参考安装步骤中的"配置iptables"部分。

- **查看Docker服务日志**：

```bash
sudo journalctl -u docker -n 50
```

- 查看详细的错误信息，帮助定位问题。

## 容器启动后立即退出

**问题描述**：使用 *docker run* 启动容器后，容器立即退出。

**解决方案**：

- 检查容器日志：

```bash
docker logs <container_id>
```

- 使用交互式模式运行容器：

```bash
docker run -it ubuntu:20.04 /bin/bash
```

- 确保容器内有持续运行的进程，或使用 *tail -f /dev/null* 保持容器运行

## 如何清理未使用的Docker资源

**问题描述**：Docker占用了大量磁盘空间。

**解决方案**：

- 清理未使用的容器、网络、镜像：

```bash
docker system prune -a
```

- 清理未使用的数据卷：

```bash
docker volume prune
```

- 手动删除不需要的镜像和容器

## 容器无法访问外部网络

**问题描述**：容器内无法访问互联网。

**解决方案**：

- 检查主机的网络连接

- 检查Docker网络配置：

```bash
docker network ls
docker network inspect bridge
```

- 重启Docker服务：

```bash
sudo systemctl restart docker
```

## 端口映射不生效

**问题描述**：配置了端口映射，但无法从外部访问容器服务。

**解决方案**：

- 检查端口映射是否正确：

```bash
docker port <container_id>
```

- 检查防火墙设置，确保端口未被阻止

- 检查容器内的服务是否正常运行：

```bash
docker exec -it <container_id> ps aux
```

## 数据卷中的数据丢失

**问题描述**：删除容器后，数据卷中的数据丢失了。

**解决方案**：

- 确保使用命名数据卷而不是匿名卷：

```bash
docker run -v myvolume:/data hello-world
```

- 删除容器时不要使用 *-v* 参数（会同时删除关联的数据卷）

- 定期备份重要数据

## 如何查看容器的资源使用情况

**解决方案**：

```bash
# 实时查看所有容器的资源使用
docker stats

# 查看特定容器的资源使用
docker stats <container_id>
```

## 系统重启后容器未自动启动

**问题描述**：系统重启后，之前运行的容器没有自动启动。

**解决方案**：

- 使用 *--restart=always* 参数运行容器：

```bash
# 使用hello-world镜像
docker run --restart=always --name my-hello hello-world

# 对于需要持续运行的容器，可以使用其他镜像
docker run -d --restart=always --name mycontainer ubuntu:20.04 tail -f /dev/null
```

- 对于已存在的容器，更新重启策略：

```bash
docker update --restart=always <container_id>
```

通过上述步骤和问题解答，您可以在Quectel Pi H1设备上成功安装和使用Docker，方便地进行容器化应用的部署和管理。