企业官网建设流程全解析

PilotDeck Docker部署指南：从零搭建生产级AI智能体平台的完整配置清单

【免费下载链接】PilotDeckTask-oriented AI Agent productivity platform项目地址: https://gitcode.com/OpenBMB/PilotDeck

PilotDeck 是 OpenBMB 社区开源的任务型 AI Agent 生产力平台，支持 WorkSpace 项目级隔离、白盒记忆与智能模型路由。本篇 Docker 部署指南带你从零搭建生产级 PilotDeck 服务，覆盖环境检查、一键启动、模型配置与数据持久化——无需在宿主机安装 Node.js、无需手工调环境，3 条命令即可拉起你的 AI 智能体平台。

📦 一、为什么选 Docker：运行 PilotDeck 最省事的方式

容器内，PilotDeck 以两个协作的 Node.js 进程运行：

• UI Server：Web 前端 + REST/WebSocket 适配层，监听3001端口
• Gateway：AI Agent 智能体运行时，监听18789端口

浏览器 (localhost:3001) ──► UI Server (3001) ──► Gateway (18789)

运行时 supervisor 会先启动 UI Server，待模型配置就绪后再启动 Gateway（见 webRuntimeSupervisor.js），因此首次配置可以直接在浏览器中完成。相比源码安装，Docker 方式有三个明显优势：

• 零宿主依赖：镜像内置 Node.js 22，按仓库锁文件安装依赖，不依赖宿主机的 Node 版本与 CPU 架构；
• 一键可复现：Dockerfile 采用多阶段构建产出生产级运行时镜像，任何服务器执行相同命令得到相同结果；
• 数据不丢：Compose 将全部状态持久化到pilotdeck-home卷，会话、记忆、技能在重启后原样保留。

✅ 二、动手之前：30 秒环境检查

前置条件只有两项：Docker v20+ 与 Docker Compose v2+。macOS/Windows 请先启动 Docker Desktop 并等待引擎就绪，然后确认守护进程正在运行：

docker info

首次构建有两个常见情况要提前知道：

• 拉取镜像慢或报context deadline exceeded：构建需拉取node:22-bookworm等基础镜像。建议在 Docker Desktop（Settings → Docker Engine）或 Linux 的/etc/docker/daemon.json中配置 registry mirror 后重试；
• 临时办法：先从可访问的镜像源拉取所需 Node 镜像，并打成本仓库 Dockerfile 使用的名称：

docker pull mirror.gcr.io/library/node:22-bookworm docker pull mirror.gcr.io/library/node:22-bookworm-slim docker tag mirror.gcr.io/library/node:22-bookworm node:22-bookworm docker tag mirror.gcr.io/library/node:22-bookworm-slim node:22-bookworm-slim

另外注意：构建过程还会在镜像内下载 Debian 与 npm 软件包，网络受限时建议同时配置代理（见第五节配置清单）。

🚀 三、一键启动：从代码到生产只要 3 步

第 1 步：获取代码

git clone https://gitcode.com/OpenBMB/PilotDeck cd PilotDeck

第 2 步：声明模型（配置方式见第四节，任选其一）

第 3 步：构建并启动

docker compose up -d --build

打开浏览器访问http://localhost:3001：

• 若第 2 步已提供 API Key，保存后 Gateway 自动启动，可直接开始对话；
• 若未提供 Key，页面会进入onboarding引导流程：在浏览器里选择模型服务商、粘贴 API Key、测试连接并保存。PilotDeck 会自动写入配置并启动 Gateway，全程无需手工改文件（接口细节可参考 onboarding-api.md）。

🔑 四、模型配置：两种方式二选一

方式 A：环境变量配置（新手推荐）

在 docker-compose.yml 的 environment 中（或.env文件）设置三个变量。首次启动时，docker-entrypoint.sh 会自动生成一份完整的配置文件，无需手写 YAML：

PILOTDECK_MODEL=openai/gpt-4.1 PILOTDECK_API_KEY=sk-your-api-key PILOTDECK_API_URL=https://api.openai.com/v1

如果想让智能路由的"轻量模型"走另一个服务商，可再补充PILOTDECK_LIGHT_MODEL与PILOTDECK_LIGHT_API_KEY/PILOTDECK_LIGHT_API_URL。

方式 B：YAML 文件配置（生产推荐）

先在宿主机创建配置文件，再取消 docker-compose.yml 中以pilotdeck.yaml:ro结尾的只读挂载行注释：

schemaVersion: 1 agent: model: openai/gpt-4.1 model: providers: openai: protocol: openai url: https://api.openai.com/v1 apiKey: sk-your-api-key

配置显式可见、可纳入版本管理，多实例部署时更方便统一维护。

📋 五、生产级配置清单

以下是 Docker 部署支持的核心环境变量与默认值，建议对照检查后再上线：

三条额外生产建议：

1. 开启登录认证：取消注释PILOTDECK_DISABLE_LOCAL_AUTH=0，要求用户登录后才能访问，避免内网被匿名使用；
2. 保留重启策略：docker-compose.yml 中默认的restart: unless-stopped可让服务在崩溃后自动恢复，生产环境不要删除；
3. 配好代理：如需出网代理，设置PILOTDECK_PROXY，启动脚本会自动转发到http_proxy等标准变量。

🗂️ 六、把宿主机项目挂进容器：让智能体操作你的代码

智能体默认运行在容器内。若希望它直接读写宿主机上的项目，取消 docker-compose.yml 中/workspace一行的注释：

volumes: - pilotdeck-home:/root/.pilotdeck - ${PILOTDECK_WORKSPACE:-${PWD}}:/workspace

也可以在启动前设置PILOTDECK_WORKSPACE=/path/to/project指定项目路径。启动后，可在 Web 控制台的 Files 页面浏览和管理文件：

图中即~/.pilotdeck状态目录，包含projects、memory、router、skills、config.yaml、permissions.json等子项。它们连同认证数据库、会话与路由统计一起，全部由pilotdeck-home卷持久化——重建容器或升级镜像后数据不会丢失，可放心长期运行。

🔧 七、进阶：手动构建运行与常见问题排查

不想用 Compose 时，也可以手动构建镜像并运行：

docker build -t pilotdeck:latest . docker run -d --name pilotdeck -p 3001:3001 \ -v pilotdeck-home:/root/.pilotdeck \ -e PILOTDECK_MODEL=openai/gpt-4.1 \ -e PILOTDECK_API_KEY=sk-your-api-key \ -e PILOTDECK_API_URL=https://api.openai.com/v1 \ pilotdeck:latest

配置文件挂载、工作区挂载与代理参数与 Compose 版一一对应：卷改用-v传入，环境变量改用-e传入。

常见问题速查

📚 八、延伸资料

• Docker 部署官方文档：README_DOCKER.zh.md
• 镜像构建定义：Dockerfile · 容器编排配置：docker-compose.yml
• 配置自动生成逻辑：docker-entrypoint.sh
• 项目总览与核心能力：README.zh.md

一次搭好，长期受益。把生产级 PilotDeck 跑起来之后，不妨给它一个真实任务，看看这个任务型 AI 智能体平台还能为你做什么。

【免费下载链接】PilotDeckTask-oriented AI Agent productivity platform项目地址: https://gitcode.com/OpenBMB/PilotDeck