跳到主要内容
AI教程

SkyDot 自托管教程：从零搭建多 Dot AI 工作台

本文将介绍 SkyDot 的架构与核心能力，并带你完成本地安装、模型配置、Host 或 Docker 执行模式、桌面端连接及多 Dot 协作设置。

AI我搜编辑部阅读约 12 分钟
SkyDot 自托管教程：从零搭建多 Dot AI 工作台

SkyDot 是什么

SkyDot 是一个基于 Pi Agent Runtime 的开源、自托管多用户 Agent 工作台。你可以创建多个可命名、可配置的 Dot，让它们分别承担不同职责；也可以把多个 Dot 放入群聊，通过定时任务、Skills、MCP、Plugins 和 Memory 扩展长期工作能力。

它并不只是一个聊天页面。Workspace 负责划分文件、会话、记忆与执行边界，Backend 处理认证、权限、队列、调度、Provider 和消息渠道，Host 或 Docker Runner 则负责真正执行 Agent。需要用户确认的工具授权、设备请求和任务进度，也会返回同一个工作台。

SkyDot 系统架构

核心架构与执行边界

SkyDot 将界面、控制面和执行面分离，适合个人使用，也适合团队自托管部署。

  • Backend：基于 Node.js、TypeScript、Hono、SQLite 和 WebSocket，负责认证、持久化、队列、调度、Provider、渠道与授权。
  • Runner：使用 Pi Agent Runtime 执行实际 Agent 任务，可选择本机 Host 模式或非 root Docker 容器。
  • Workspace：决定文件、Session、Memory、渠道绑定和运行边界。
  • Web、PWA 与 Electron：共用 React 业务前端，Electron Renderer 只负责界面，不直接接触数据库、文件系统、凭证、Docker 或 shell/process 权限。

权限不会因为某一层通过就自动越过其他边界。部署团队环境前，建议阅读权限矩阵与安全策略。

主要功能

个人 Dot 与会话

每个 Dot 都可以独立设置名称、头像、Prompt、模型、思考级别、Skills、MCP 和执行策略。对话支持流式输出、Markdown、代码块、文件附件、中止、后续消息与会话恢复。

SkyDot 个人 Dot 对话

不同 Workspace 之间相互隔离，文件、会话、记忆、渠道绑定和执行权限不会因为进入同一个界面而混用。执行时可以选择 Host 模式，也可以选择 Container 模式。

多 Dot 群聊与协作

开启原生群聊后，可以在同一时间线中查看多个 Dot 的消息、任务回执、进度和结果。明确提及与受控委派用于控制协作范围；重新连接或重新打开页面只会读取状态，不会自动提交新任务。

SkyDot 多 Dot 协作

群聊默认关闭。启用原生群聊需要设置 SKYDOT_BOT_GROUPS=true；如果还要允许 Bot 之间执行协作，则需要额外设置 SKYDOT_BOT_HANDOFFS=true，并由管理员配置运行权限和调用预算。

定时任务、Skills 与 Memory

Scheduler 支持 Cron、固定间隔和一次性任务，并提供立即运行、暂停、取消、运行历史和结果投递。Skills、MCP 与 Plugins 可以集中管理，再按 Dot 配置启用范围。

Memory 以 Workspace 为单位保存事实、偏好、决策、经验和待跟进事项，支持搜索、新建、编辑、忘记和版本历史。Session 保存具体对话上下文，Workspace Memory 保存可跨 Session 复用的知识，两者彼此独立。

安装前准备

  • Node.js：22.19 或更高版本，推荐 Node.js 24 LTS。Pi Durable 存储需要 Node.js 内置 SQLite。
  • npm：随 Node.js 安装，用于安装各子项目依赖。
  • Docker：仅在 Container 执行模式下需要。
  • Model Provider：真实 AI 对话需要可用的模型 Provider；没有 API Key 时仍可以先启动界面。
  • GNU Make：可选，用于类型检查、备份和运维命令。

从零安装 SkyDot

1. 克隆仓库并安装依赖

在终端执行以下命令，分别安装主项目、Web 前端和 Agent Runner 的依赖：

git clone https://github.com/2SinceJuly/SkyDot.git
cd SkyDot

npm install
npm --prefix web install
npm --prefix container/agent-runner install

2. 构建并启动服务

完成依赖安装后，构建全部组件并启动 Backend：

npm run build:all
npm start

打开 http://127.0.0.1:3000，按照页面完成管理员初始化。Provider 和消息渠道可以选择稍后配置，但没有模型配置时，真实 AI 对话无法运行。

3. 启动开发环境

开发时可以同时启动 Backend 和 Vite Web Client：

npm run dev:all

开发页面默认地址为 http://127.0.0.1:5173。如果只是希望在本机快速浏览界面，可以使用回环地址免登录 Demo：

SKYDOT_DEMO_OPEN=true PROVIDER_SETUP_SKIPPED=true npm start

不要在公网或不可信网络中启用 Demo 模式。该模式的完整限制请参考仓库中的 DEMO.md。

配置模型 Provider

SkyDot 允许先完成界面初始化，再到设置中补齐 Provider。接入真实模型时，需要准备对应的 API Key、Session Cookie 或其他凭证，并避免将凭证写入截图、命令行历史或 Git 仓库。

如果使用第三方 OpenAI Completions 接口，可以在 Provider 的自定义环境变量中设置：

SKYDOT_MODEL_API=openai-completions

默认协议为 anthropic-messages，该设置同时用于普通 Dot 对话的 Host 和 Container Runner。

选择 Agent 执行模式

Host 模式

Host 模式直接使用本机 Runner，不需要 Docker，适合本地开发和快速验证。执行权限仍受 Workspace、用户和运行策略限制。

Container 模式

Container 模式需要 Docker 可用，并准备 Agent Runner 镜像。默认镜像为 2sincejuly/skydot-agent:latest，也可以从当前源码构建：

docker build --pull -t 2sincejuly/skydot-agent:latest container

如需使用其他镜像，可设置 SKYDOT_CONTAINER_IMAGE，兼容配置项为 CONTAINER_IMAGE。服务与镜像构建必须连接到同一个 Docker daemon。make start 或 make dev 会优先使用本地镜像，缺失时尝试拉取。

运行桌面端 Electron

如果 Backend 与 Vite 已经启动，可以在另一个终端运行 Electron：

SKYDOT_RENDERER_URL=http://127.0.0.1:5173 npm run desktop:dev

如果 Backend 已提供构建后的页面，也可以直接执行：

npm run desktop:dev

Electron 还可以连接远程 Backend：

SKYDOT_SERVER_URL=https://your-skydot.example.com npm run desktop:dev

本地打包可使用以下命令：

npm run desktop:package:dir
npm run desktop:package

项目默认提供 macOS arm64 打包配置，同时保留 Windows 和 Linux 目标。正式发布前，需要针对目标平台配置签名和公证。

关键环境变量

  • WEB_PORT：Backend 监听端口，默认值为 3000。
  • SKYDOT_SERVER_URL：Electron 连接的 Backend 地址，默认值为 http://127.0.0.1:3000。
  • SKYDOT_RENDERER_URL：Electron 加载的 Renderer 地址。
  • SKYDOT_CONTAINER_IMAGE：Agent Runner 容器镜像。
  • PROVIDER_SETUP_SKIPPED：没有系统设置文件时跳过 Provider 引导。
  • SKYDOT_BOT_GROUPS：启用原生多 Dot 群聊。
  • SKYDOT_BOT_HANDOFFS：启用群聊中的 Bot 执行协作。
  • SKYDOT_PERSONAL_GOALS：启用个人 Goal 实验能力。

个人 Goal 和 Durable Runtime 默认关闭。普通定时任务不依赖这些开关，具体运行前提请查看 Goals and Tasks 文档。

一个基础使用流程

  1. 登录 SkyDot 并完成管理员初始化。
  2. 在设置中配置可用的 Model Provider。
  3. 创建一个 Dot，为它设置名称、Prompt、模型和执行策略。
  4. 为 Dot 选择 Workspace，确保文件和记忆边界符合预期。
  5. 在对话中发送任务，观察流式输出、工具授权和执行结果。
  6. 如果需要长期运行，再创建 Cron、固定间隔或一次性任务。
  7. 当需要多角色协作时，开启群聊功能并明确配置 Bot 协作权限。

例如，可以创建一个负责代码分析的 Dot 和一个负责资料整理的 Dot，再把它们加入同一群聊。通过明确提及或受控委派分配任务，用户可以在共享时间线中查看进度和结果，同时保持各自 Workspace 的权限边界。

运维与安全建议

运行时数据默认保存在仓库的 data/ 目录，其中包括 SQLite、Workspace、Session、Memory 和运行配置。该目录不会进入 Git，但备份可能包含敏感配置和数据库，应当与原始数据同等保护。

  • 使用 make status 查看 Backend、日志和 Docker 状态。
  • 使用 make stop 停止当前端口上的 SkyDot 服务。
  • 使用 make backup 创建运行时数据备份。
  • 使用 make restore FILE=... 恢复指定备份。
  • 使用 make typecheck 执行 Backend、Web、Agent Runner 与文档检查。
  • 使用 npm test -- --run 运行 Vitest 测试。

远程部署时应使用 HTTPS 和 WSS，并正确配置反向代理、Cookie 与访问控制。不要把 Renderer、数据库或 Docker daemon 直接暴露给不可信用户，也不要为了省事开启公网 Demo。

进一步扩展

SkyDot 的能力库支持内置、宿主机、项目、用户、Workspace 和 Plugin 等来源。Agent 运行前会生成有效能力清单，并根据策略注入 Prompt、资源和上下文。项目还支持 Plugin 版本快照、Subagents，以及 Host 与 Container 一致的能力边界。

消息入口方面，Web、PWA 和 Electron 共用同一套业务前端，并可接入飞书、Telegram、QQ、钉钉、微信、Discord、WhatsApp 等渠道。渠道可以绑定到指定 Workspace 或 Session。

总结

SkyDot 将多 Dot 对话、Workspace 隔离、Agent 执行、定时任务、扩展能力和团队权限整合到一个自托管工作台中。按照本文完成 Node.js 环境准备、依赖安装、构建启动和 Provider 配置后，你就可以先运行个人 Dot，再逐步启用 Docker、Electron、群聊、Scheduler、Skills、MCP 与 Memory 等能力。

由于项目仍在持续开发，真实模型、Docker、外部渠道和远程部署都依赖各自的凭证与运行环境。Goal、Durable 或 Cloud Runtime 等实验能力也不应被视为默认启用的功能。