Docker 容器化运行与集成指南 · Dylan AI Agent Nexus

定位与价值

Docker 通过镜像（Image）与容器（Container）提供一致、可移植的运行环境，是本地化部署 AI 服务（LLM、向量库、可视化工具、自动化平台）的基础设施。我们在私有网络与 AI 主机/服务器上运行容器，可获得更好的安全性、可控性与可维护性。

核心概念

• Image：只读模板，包含运行所需的文件与依赖；可分层、可缓存、可复用。
• Container：镜像的运行时实例；短生命周期、可随时销毁重建。
• Registry：镜像仓库（Docker Hub/私有仓库）；镜像以 name:tag 标识。
• 网络与存储：通过 -p 暴露端口、通过 Volume/绑定挂载持久化数据。
• Compose：以 docker compose 声明多服务应用的编排。
• GPU 支持：NVIDIA Container Toolkit 赋能 --gpus 参数进行 GPU 调度。

常用命令（单行示例）

docker pull nginx:alpine

docker run -d --name web -p 8080:80 nginx:alpine

docker ps -a

docker logs -f web

docker exec -it web sh

docker stop web && docker rm web

docker images && docker rmi nginx:alpine

端口、网络与数据持久化

• 端口：-p HOST:CONTAINER 进行端口映射（如 -p 8080:80）。
• 网络：使用 docker network create ai-net 创建网络，容器以服务名互访。
• Volume：-v named_volume:/data 或 -v /host/path:/data 挂载数据。
• 备份策略：优先使用命名卷，定期 tar/快照备份；重要目录只读挂载。

GPU 与资源限制

• GPU：安装 NVIDIA Container Toolkit 后可使用 --gpus all 或 --gpus \"device=0\"。
• 内存/CPU：--memory 8g --cpus 4 控制资源上限。
• 重启策略：--restart unless-stopped 保证异常退出后自动拉起。
• 健康检查：通过 Dockerfile HEALTHCHECK 或 Compose healthcheck 做存活探测。

构建与镜像管理

• Dockerfile：使用多阶段构建减小镜像体积；固定基础镜像与依赖版本。
• BuildKit：默认启用缓存并行；可用 docker buildx build 做多架构构建。
• 标签与版本：采用语义化标签（如 1.2.3、2025-08-30）；避免仅用 latest。

docker build -t registry.local/ai/service:1.0.0 .

Compose 多服务编排

使用 docker compose 管理依赖服务（数据库、向量库、LLM、网关）。

docker compose up -d

# docker-compose.yml 片段
version: "3.9"
services:
  api:
    image: registry.local/ai/api:1.0.0
    ports: ["8080:8080"]
    depends_on: [db]
    restart: unless-stopped
  db:
    image: mariadb:11
    environment:
      - MARIADB_ROOT_PASSWORD=changeit
    volumes:
      - dbdata:/var/lib/mysql
volumes:
  dbdata:

私有镜像仓库与推送

• 登录：docker login registry.local；CI 中使用凭据安全存储。
• 打标与推送：docker tag app:1.0 registry.local/team/app:1.0；docker push registry.local/team/app:1.0。
• 合规：定期清理未使用镜像；开启拉取/推送审计与保留策略。

安全与合规要点

• 最小权限：容器内使用非 root 用户；仅开放必要端口与能力。
• 敏感配置：环境变量与机密分离；建议使用外部配置中心或 Compose secrets。
• 镜像扫描：在 CI 里加入镜像漏洞扫描与合规检查；定期重建更新。
• 网络边界：放置在内网/零信任网段；对外暴露走反向代理与访问控制。

可观察性与日志

• 日志：docker logs 仅用于排障；生产应集中收集（如 Loki/ELK）。
• 指标：导出容器与主机指标（cAdvisor/Node Exporter），接入 Prometheus/Grafana。
• 事件：docker events 订阅容器生命周期事件以做自动化响应。

AI 典型场景（思路）

• 大模型推理：以容器运行 LLM 服务（如 Ollama/OpenAI 兼容服务），结合 --gpus 调度。
• 向量检索：部署向量库（Milvus/FAISS 服务化）并挂载持久卷。
• 可视化工作流：ComfyUI/Workflow 引擎容器化，暴露 API 给平台编排。

故障排查（思路）

• 无法访问：检查端口映射、防火墙、反向代理规则与容器状态。
• 性能抖动：确认主机资源瓶颈（CPU/内存/IO）与容器资源限制。
• 数据丢失：确保关键目录使用卷持久化并建立备份计划。
• GPU 不可见：核对 NVIDIA 驱动/Toolkit 版本匹配与 --gpus 参数。

与本平台的集成

• 服务注册：在平台配置中登记容器服务的地址/端口与鉴权方式。
• 网络与安全：统一使用私网与反向代理；启用 TLS 与访问控制。
• 自动化：结合 n8n/CI 脚本进行镜像构建、推送与滚动更新。