本文主要介绍基于Docker Compose完成 Determined AI 核心组件（Master/Agent）的单节点部署，同时搭配 Postgres 数据库实现 Master 数据持久化，为后续训练任务调度打下核心基础。

部署适配小团队、单 Master、非 HA的轻量化使用场景，全程基于 Docker 实现，无需复杂的 K8s/Slurm 集群，贴合小算力规模的使用需求。

一、部署前置说明

1.1 官方部署建议与本次选型原因

  Determined 官方更推荐 Kubernetes/Slurm 等部署方式，能更好地支持持久化、集群扩展、高可用等生产级需求，Docker 部署因多机网络、权限隔离等组合复杂，未作为官方主要安装路径。

本次选型 Docker 部署的核心原因：

• 适配小团队单节点 / 小规模算力的使用场景，无需过重的架构投入；
• 团队对 Docker 生态更熟悉，运维成本更低；
• 先实现单节点跑通核心功能，后续可基于此平滑扩展为多节点集群。

1.2 节点环境要求

  本次部署为单服务器合布 Master+Agent，后续会单独讲解多服务器 Agent 扩展，不同节点的环境要求如下：

• Master 节点：仅运行调度控制服务，无需安装nvidia-container-toolkit（安装也不影响，仅增加无意义复杂度）；
• Agent 节点：运行实际 GPU 训练任务，必须提前安装并配置 nvidia-container-toolkit（仅跑 CPU 任务可忽略）；
• 版本统一：Master 和 Agent 需使用相同版本的 Determined 镜像，本次使用0.38.1版本（推荐固定版本，避免版本兼容问题）。

1.3 核心组件依赖

  Determined Master 并非无状态服务，需依赖数据库持久化控制面信息（任务状态、实验配置、资源池信息等），本次选用Postgres 15作为底层数据库，与 Master/Agent 一起通过 Docker Compose 编排部署。

二、核心配置文件编写

本次部署需准备 3 个核心配置文件，统一放在同一目录下（建议新建专属目录如/home/determined/），分别是docker-compose.yml（组件编排）、master.yam（Master 配置）、agent.yaml（Agent 配置），以下为完整配置与关键说明。

2.1 docker-compose.yml：组件编排核心

  实现 Postgres、Master、Agent 的容器化编排，指定镜像、端口、挂载、依赖关系等，默认端口 8080 修改为 8008（避免端口冲突），关键配置如下：

services:
  # Postgres数据库服务
  pgsql:
    image: postgres:15
    container_name: determined-pgsql
    environment:
      POSTGRES_USER: determined
      POSTGRES_PASSWORD: determined
      POSTGRES_DB: determined
    volumes:
      # 数据持久化，避免容器重启数据丢失
      - ./pgdata:/var/lib/postgresql/data  
    restart: unless-stopped

  # Determined Master服务
  master:
    image: determinedai/determined-master:${DET_TAG:-0.38.1}
    container_name: determined-master
    depends_on:
      - pgsql  # 依赖postgres，先启动数据库
    ports:
      - "8008:8080"
    volumes:
      # 只读挂载Master配置
      - ./master.yaml:/etc/determined/master.yaml:ro 
      - checkpoints:/determined/checkpoints
    command: ["--config-file", "/etc/determined/master.yaml"]
    environment:
      # 开启debug日志，方便问题排查
      DET_LOG_LEVEL: debug  
    restart: unless-stopped

  # Determined Agent服务
  agent:
    image: determinedai/determined-agent:${DET_TAG:-0.38.1}
    container_name: determined-agent
    depends_on:
      - master
    # 挂载宿主机所有GPU，仅CPU任务可删除此行
    gpus: all  
    volumes:
      # 只读挂载Agent配置
      - ./agent.yaml:/etc/determined/agent.yaml:ro  
      # 挂载Docker套接字，让Agent创建训练容器
      - /var/run/docker.sock:/var/run/docker.sock  
      - checkpoints:/determined/checkpoints
    command: ["run", "--config-file","/etc/determined/agent.yaml"]
    environment:
      DET_LOG_LEVEL: debug
    restart: unless-stopped

# 自定义卷，用于训练检查点持久化
volumes:
  checkpoints:
    driver: local
    driver_opts:
      type: none
      o: bind
      # 宿主机实际存储路径，需提前创建
      device: /home/xxxx/xxxx/determined/checkpoints  

关键注意点：

1. 宿主机检查点目录需提前创建，执行mkdir -p /home/xxxx/xxxx/determined/checkpoints；
2. 若服务器开启防火墙，需开放 8008 端口（ufw allow 8008/tcp），否则后续多节点 Agent 无法连接；
3. gpus: all仅适用于 Docker Compose v2 及以上版本，本次环境为 v2.40.3，可直接使用。

2.2 master.yaml：Master 服务配置

  配置数据库连接、检查点存储、资源池、调度策略等核心参数，是 Master 的核心配置文件，完整配置如下：

# 数据库连接配置，与docker-compose中postgres的环境变量保持一致
db:
  host: pgsql
  port: 5432
  user: determined
  password: determined
  name: determined

# 检查点存储配置，使用本地共享文件系统
checkpoint_storage:
  type: shared_fs
  host_path: /home/xxxx/xxxx/determined/checkpoints

# 集群名称，自定义即可
cluster_name: my scheduling center

# 资源池配置，支持多资源池划分，适配不同GPU型号/任务类型
resource_pools:
  - pool_name: default
    description: "默认资源池"
    max_aux_containers_per_agent: 100
    scheduler:
      type: priority  # 优先级调度策略
  - pool_name: gpu-2080ti
    description: "RTX 2080 Ti 资源池"
    max_aux_containers_per_agent: 100
    scheduler:
      type: priority

# 任务容器默认配置，挂载自定义数据目录
resource_manager:
  task_container_defaults:
    type: agent
    bind_mounts:
      - host_path: /home/xxx/xxx/xxx/outputs/clas_code
        container_path: /mnt/output
        read_only: false  # 可读写，支持训练产物写入

关键说明：

1. db.host: pgsql直接使用 Docker Compose 的服务名，容器内可自动解析域名；
2. resource_pools可根据实际 GPU 型号 / 业务需求划分，本次配置默认池和 2080Ti 池，后续 Agent 可指定接入对应池；
3. bind_mounts实现宿主机目录与训练容器目录的映射，方便训练任务读取 / 写入数据。

2.3 agent.yaml：Agent 服务配置

  配置 Agent 与 Master 的连接信息、容器运行时、所属资源池等，完整配置如下：

# Master节点地址与端口，宿主机内网IP+docker-compose映射的8008端口
master_host: your ip
master_port: 8008

# 训练容器连接Master的地址与端口，与上面保持一致即可
container_master_host: your ip
container_master_port: 8008

# 容器运行时，指定为docker
container_runtime: docker

# 所属资源池，与master.yaml中的资源池名称对应
resource_pool: gpu-2080ti

# 插槽类型，CUDA对应GPU任务，CPU任务可改为cpu
slot_type: cuda

# 可选配置：指定AgentID和可见GPU
# agent_id: det-gpu-2080ti-01
# visible_gpus: "0,1,2,3"  # 仅暴露指定GPU，逗号分隔

关键说明：

1. master_host必须填写宿主机内网 IP，不可填 127.0.0.1（否则容器内无法访问 Master）；
2. resource_pool需与master.yaml中定义的资源池名称完全一致，否则 Agent 无法注册；
3. 可选配置visible_gpus可限制 Agent 使用的 GPU，适合单服务器多 GPU 需划分的场景。

2.4 配置文件参考来源

  本次部署所使用的docker-compose.yml、master.yaml、agent.yaml核心配置，均有官方及开源项目参考依据，根据自身需求调整修改：

1. 实战化配置示例可参考Determined AI 官方 GitHub 项目，包含不同部署场景下的配置文件样例；

2. 基础配置模板可参考Determined AI 官方文档，包含各配置字段的详细释义、取值范围及默认值;首次安装登录 webui 后，点击 Docs 跳转。

3. 本次的定制化配置（如端口修改、资源池划分、目录挂载）均基于上述参考配置，结合小团队单节点部署的实际需求调整。

  同时，Determined Master 和 Agent 的启动参数也可通过容器内命令查询，作为配置修改的补充参考，相关命令将在下文介绍。

三、启动 Determined Master/Agent

  所有配置文件编写完成后，在配置文件所在目录执行以下命令，完成组件启动与验证。

3.1 启动容器集群

使用 Docker Compose 后台启动所有服务，执行命令：

sudo docker-compose up -d

• 首次启动会自动拉取 Postgres、Determined Master/Agent 镜像，需等待镜像拉取完成；
• 启动成功后，执行sudo docker-compose ps可查看容器状态，所有容器状态为Up即说明启动正常。

3.2 查看启动日志

开启 debug 日志后，可通过日志排查启动问题，实时查看日志命令：

sudo docker-compose logs -f

• 若出现连接失败、配置错误等信息，可根据日志提示修改配置文件后，执行sudo docker-compose restart重启服务。

3.3 验证服务运行状态

3.3.1 WebUI 访问验证

  打开浏览器，访问地址http://<宿主机IP>:8008，即可进入 Determined Master 可视化管理界面：

1. 首次登录无密码，使用默认用户名admin或determined直接登录；
2. 可在Clusters → Resource Pools页面查看已配置的资源池，确认与master.yaml配置一致。

3.3.2 命令行参数查询（可选）

若需自定义启动参数，可进入容器查询 Master/Agent 支持的所有启动参数，命令如下：

# 查询Agent启动参数
docker exec -it determined-agent determined-agent --help

# 查询Master启动参数
docker exec -it determined-master determined-master --help

参数查询结果可作为后续配置修改的参考，适配更多个性化需求。

agent 执行结果：

run the Determined agent

Usage:
  determined-agent run [flags]

Flags:
      --agent-id string                        Unique ID of this Determined agent
      --agent-reconnect-attempts int           Max attempts agent has to reconnect (default 5)
      --agent-reconnect-backoff int            Time between agent reconnect attempts (default 5)
      --api-enabled                            Enable agent API endpoints
      --bind-ip string                         IP address to listen on for API requests (default "0.0.0.0")
      --bind-port int                          Port to listen on for API requests (default 9090)
      --config-file string                     Path to agent configuration file
      --container-master-host string           Master hostname that containers started by this agent will connect to
      --container-master-port int              Master port that containers started by this agent will connect to
      --container-runtime string               The container runtime to use (default "docker")
      --debug                                  Enable verbose script output
      --ftp-proxy string                       THe FTP proxy address for the agent's containers
  -h, --help                                   help for run
      --http-proxy string                      The HTTP proxy address for the agent's containers
      --https-proxy string                     The HTTPS proxy address for the agent's containers
      --master-host string                     Hostname of the master
      --master-port int                        Port of the master
      --no-proxy string                        Addresses that the agent's containers should not proxy
      --resource-pool string                   Resource Pool the agent belongs to (default "default")
      --security-tls-enabled                   Whether to use TLS to connect to the master
      --security-tls-master-cert string        CA cert file for the master
      --security-tls-master-cert-name string   expected address in the master TLS certificate (if different than the one used for connecting)
      --security-tls-skip-verify               Whether to skip verifying the master certificate when TLS is on (insecure!)
      --slot-type string                       slot type to expose (default "auto")
      --tls                                    Use TLS for the API server
      --tls-cert string                        Path to TLS certification file
      --tls-key string                         Path to TLS key file
      --visible-gpus string                    GPUs to expose as slots

Global Flags:
      --log-color          disable colored output (default true)
  -l, --log-level string   set the logging level (can be one of: debug, info, warn, error, or fatal) (default "info")

master 执行结果：

Usage:
  determined-master [flags]
  determined-master [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  migrate     migrate the db
  populate    populate metrics with given number of batches. 
                trivial is an optional arg for trivial metrics rather than more complex ones.

Flags:
      --config-file string                      location of config file
      --db-host string                          database host
      --db-name string                          database name
      --db-password string                      database password
      --db-port string                          database port
      --db-ssl-mode string                      database ssl mode (disable, verify-ca, ...) (default "disable")
      --db-ssl-root-cert string                 database ssl root cert path
      --db-user string                          database username
  -h, --help                                    help for determined-master
      --log-color                               output logs in color (default true)
      --log-level string                        choose logging level from [trace, debug, info, warn, error, fatal] (default "info")
      --port int                                server port
      --root string                             static file root directory (default "/usr/share/determined/master")
      --security-default-task-gid int           security default task GID
      --security-default-task-group string      security default task group name (default "root")
      --security-default-task-uid int           security default task UID
      --security-default-task-user string       security default task username (default "root")
      --security-initial-user-password string   initial password for the built-in 'determined' and 'admin' users
      --security-tls-cert string                TLS cert file
      --security-tls-key string                 TLS key file
      --telemetry-enabled                       enable telemetry (default true)
      --telemetry-otel-enabled                  enable otel
      --telemetry-otel-endpoint string          set otel endpoint (default "localhost:4317")
      --telemetry-segment-master-key string     the Segment write key for the master (default "4ZQ38oSKl4tV5JSWkbjv6ziijHY1SrE7")
      --telemetry-segment-webui-key string      the Segment write key for the WebUI (default "Ryn8Uh9BYKJ4m9irA3MCzxcfHuB3CaaF")
  -v, --version                                 version for determined-master
      --webhooks-base-url string                Base URL to access Determined Web Application
      --webhooks-signing-key string             Webhook Signing Key

Use "determined-master [command] --help" for more information about a command.

四、常见问题排查

部署过程中，出现以下 3 类问题，整理了对应的排查方案，快速定位解决：

4.1 Compose 不支持 gpus: 字段报错

报错信息：services.agent Additional property gpus is not allowed原因：

1. 使用的非 Docker 官方 Compose v2 插件（如旧版 docker-compose standalone）；
2. Compose 版本过低，未支持gpus配置项。解决方案：升级为 Docker 官方 Compose v2 版本，本次环境为 v2.40.3，可直接使用，升级命令参考：

4.2 配置文件字段错误

报错信息：日志中出现config error、field not found等关键词解决方案：

1. 核对配置文件的字段缩进与格式（YAML 格式对缩进敏感，必须用 2 个空格）；
2. 对照 Determined 官方文档和配置参数，确认字段名称与取值合法；
3. 简化配置，先保留核心字段（如数据库连接、Master 地址）跑通，再逐步添加个性化配置。

4.3 登录与服务连接问题

4.3.1 首次登录密码问题

首次登录无密码，输入默认用户名admin或determined即可直接登录，登录后可在系统内修改密码；也可在 Master 配置中增加--security-initial-user-password参数，提前初始化默认密码。

4.3.2 Agent 无法注册到 Master

常见原因：防火墙未开放 8008 端口、agent.yaml中master_host填写为 127.0.0.1、Master 容器未正常运行；解决方案：

1. 检查并放行 8008 端口，执行ufw allow 8008/tcp；
2. 将master_host修改为宿主机内网 IP，重新启动 Agent 容器；
3. 查看 Master 容器日志，排查服务启动问题，执行sudo docker-compose restart master重启 Master。

五、本文小结

  本次实战基于 Docker Compose 完成了Determined Master/Agent+Postgres的单节点一体化部署，核心完成了以下工作：

1. 编写了组件编排、Master、Agent 三大核心配置文件，适配小团队轻量化使用场景；
2. 实现了 Master 数据持久化、训练检查点挂载、GPU 透传等核心功能；
3. 完成了服务启动、日志排查、WebUI 验证的全流程操作，确认 Master 与 Agent 正常通信。

  Determined AI 算力调度平台的核心调度底座已搭建完成，下一篇我们将讲解如何将训练项目构建为 Docker 镜像，制作可被 Determined 调度的训练容器，为后续提交训练任务做好准备。