PilotDeck ReadyKit: Windows + Docker 一键起飞包
July 2, 2026 · View on GitHub
PilotDeck 生态共创挑战赛 / 赛道一：部署赛道 —— 极客部署与生态拓展
作品定位
PilotDeck 官方一键安装脚本主要面向 macOS / Linux。Windows 用户虽然可以使用 Docker 或 WSL2，但常见阻塞点包括：
- 不知道应该走 Docker、WSL2 还是 Windows 原生源码启动。
~/.pilotdeck/pilotdeck.yaml配置门槛高，主模型/轻模型/智能路由关系不直观。- 启动后缺少一套可复制的健康检查和排错路径。
- 国内网络、代理、OpenAI 兼容服务、OpenRouter / DeepSeek / Qwen 等组合容易写错。
ReadyKit 的目标是把 Windows 用户从“看懂项目”推进到“可验证跑通”，并把 PilotDeck 的三大核心能力（白盒记忆、智能路由、Always-on）放进默认配置说明里。
交付内容
| 文件 | 作用 |
|---|---|
scripts/start-pilotdeck-docker.ps1 | Windows PowerShell 一键检查 Docker、生成 .env.local、启动 PilotDeck。 |
scripts/verify-pilotdeck.ps1 | 健康检查 UI /health、容器状态、关键日志。 |
docker-compose.readykit.yml | 独立 Compose 文件，避免官方 Compose 的本地 YAML 挂载与 env 自动配置冲突。 |
templates/.env.example | 用环境变量方式配置主模型、轻模型、代理和端口。 |
templates/pilotdeck.yaml.example | 完整 YAML 配置示例，含智能路由、白盒记忆、Always-on。 |
docs/windows-docker-guide.md | 面向新手的 Windows + Docker 分步教程。 |
docs/troubleshooting.md | 常见失败原因与定位命令。 |
docs/local-models.md | Ollama、vLLM、llama.cpp / MiniCPM 本地模型接入说明。 |
docs/submission-copy.md | 报名表、作品登记表、技术博客可复制文案。 |
快速开始
在 PilotDeck 仓库根目录执行：
Set-ExecutionPolicy -Scope Process Bypass -Force
.\contest\pilotdeck-readykit\scripts\start-pilotdeck-docker.ps1
首次运行会在本目录生成 .env.local。把其中的 PILOTDECK_API_KEY 改成你的模型服务 API Key 后再次执行脚本。
启动成功后访问：
http://localhost:3001
然后执行验证：
.\contest\pilotdeck-readykit\scripts\verify-pilotdeck.ps1
本地模型接入
ReadyKit 支持任何 OpenAI 兼容接口，不一定需要外部云端 API Key。Docker 容器访问宿主机本地服务时不要写 localhost，要写 host.docker.internal。
Ollama 示例：
PILOTDECK_MODEL=ollama/qwen2.5-coder:7b
PILOTDECK_LIGHT_MODEL=ollama/qwen2.5-coder:7b
PILOTDECK_API_URL=http://host.docker.internal:11434/v1
PILOTDECK_API_KEY=ollama
vLLM 示例：
PILOTDECK_MODEL=local/<served-model-name>
PILOTDECK_LIGHT_MODEL=local/<served-model-name>
PILOTDECK_API_URL=http://host.docker.internal:8000/v1
PILOTDECK_API_KEY=EMPTY
如果容器已经启动过，/root/.pilotdeck/pilotdeck.yaml 不会自动被 .env.local 覆盖。切换模型后执行：
docker exec pilotdeck-readykit-pilotdeck-1 sh -lc 'rm -f /root/.pilotdeck/pilotdeck.yaml'
.\contest\pilotdeck-readykit\scripts\start-pilotdeck-docker.ps1
更多说明见 docs/local-models.md。
推荐模型组合
| 场景 | 主模型 | 轻模型 / Judge | 说明 |
|---|---|---|---|
| 国内低成本 | deepseek/deepseek-chat | qwen/qwen3-8b | 适合 OpenAI 兼容网关或聚合平台。 |
| OpenRouter | openrouter/deepseek/deepseek-v4-flash | openrouter/qwen/qwen3-8b | Docker entrypoint 默认接近该路径。 |
| 高质量创作 | anthropic/claude-sonnet-4.6 | openrouter/qwen/qwen3-8b | 复杂任务质量更高，成本也更高。 |
核心验证点
- Docker 容器正常运行。
- UI Server
/health返回 200。 - 浏览器可打开
http://localhost:3001。 - Onboarding 或 YAML 配置可识别模型 Provider。
- 新建 WorkSpace 后能发起一次简单会话。
- 开启智能路由后，
~/.pilotdeck/router/stats.jsonl能记录模型调用。
Compose 解析验证
不启动容器也可以先验证 Compose 文件：
docker compose `
-f .\contest\pilotdeck-readykit\docker-compose.readykit.yml `
--env-file .\contest\pilotdeck-readykit\templates\.env.example `
config
在没有系统 Docker Desktop 的机器上，可参考 docs/troubleshooting.md 中的 portable Docker CLI 方式。
国内网络构建
ReadyKit 默认在 Docker 构建阶段把 Debian APT 源切到国内 HTTP 镜像源，避免 deb.debian.org 在部分网络下返回 502 Bad Gateway，也避开 slim 基础镜像缺少 CA 证书时的 HTTPS 校验问题。可在 .env.local 中覆盖为公司内网源或其他镜像：
PILOTDECK_DEBIAN_MIRROR=http://mirrors.tuna.tsinghua.edu.cn/debian
PILOTDECK_DEBIAN_SECURITY_MIRROR=http://mirrors.tuna.tsinghua.edu.cn/debian-security
适合提交的作品标题
PilotDeck ReadyKit：把 Windows 用户从 0 带到可验证运行的 Docker 部署包
官方链接
作品发布时请显眼附带 PilotDeck 官方 GitHub：
https://github.com/OpenBMB/PilotDeck