快速开始

对于首次部署 MOVO，Docker Compose 完整部署是首选方式。仓库根目录的 docker-compose.yml 会启动用户端、管理端、DSH Runtime、文档处理、数据库、缓存、向量库和统一网关。

推荐通过 ./movo 启动。它是 Docker Compose 的轻量封装，会检查 Docker 环境、启动完整服务、等待健康检查，并输出首次初始化地址。

1. 准备环境

只需准备：

Git
Docker Engine 或 Docker Desktop
Docker Compose v2

确认 Docker 已启动，并检查 Compose：

bash

docker compose version
docker info

首次启动需要下载容器镜像，耗时取决于网络和机器性能。官方预构建镜像已经包含项目依赖和文档处理模型，普通用户无需在本机重复构建。

Windows：必须进入 Ubuntu，而不是 `docker-desktop`

Windows 用户推荐使用 Docker Desktop、WSL 2 与 Ubuntu。以管理员身份打开 PowerShell 安装 Ubuntu：

powershell

wsl --install -d Ubuntu

重启并完成 Ubuntu 首次用户创建后，检查发行版：

powershell

wsl -l -v
wsl --set-default Ubuntu
wsl -d Ubuntu

在 Docker Desktop 的 Settings → Resources → WSL Integration 中开启 Ubuntu，然后在 Ubuntu 中确认：

bash

docker version
docker compose version

不要进入 Docker Desktop 内部发行版

如果提示符以 docker-desktop: 开头，说明进入了 Docker Desktop 的内部系统，其中通常没有 Bash。请执行 exit 返回 Windows，再使用 wsl -d Ubuntu 进入真正的 Ubuntu 环境。

也可以安装 Git for Windows，在 MOVO 目录中打开 Git Bash 运行启动器。完整说明见 GitHub 仓库的 Windows 安装指南。

2. 获取并启动 MOVO

bash

git clone https://github.com/himovo/movo.git
cd movo
chmod +x movo
./movo --lang zh-CN up

./movo 适用于 macOS、Linux 和 Windows WSL 等 Bash 环境。

默认会从 ghcr.io/himovo/movo-* 串行拉取官方 latest 镜像；网络中断时会持续重试，直到成功或用户按 Ctrl+C 停止。无需创建或修改 .env。

启动器会：

检查 Docker 与 Docker Compose v2。
为内部服务自动生成并持久化随机安全密钥。
启动 MongoDB、Redis、Weaviate、DSH Runtime、文档服务、用户端和管理端。
等待各服务通过健康检查。
输出首次初始化地址。

默认地址为：

text

http://localhost:3000/admin/setup

也可以直接使用原生 Compose 命令：

bash

docker compose up -d

在 Windows PowerShell 中不使用 WSL 时，可以直接执行上述原生 Compose 命令，服务就绪后手动打开初始化地址。

原生 Compose 同样默认拉取 ghcr.io/himovo/movo-* 官方镜像，不需要配置 .env。只有需要固定生产版本、修改端口或切换私有镜像仓库时才需要创建 .env。

但首次部署更推荐 ./movo up，因为它会完成健康等待、兼容迁移并给出下一步地址。

开发人员需要从源码构建全部本地镜像时，执行：

bash

./movo up --build

3. 完成首次初始化

在浏览器打开：

text

http://localhost:3000/admin/setup

初始化向导与当前产品代码一致，共包含以下步骤：

部署检测

确认 MongoDB、Redis、持久化存储、Chat API 与 DSH Runtime、文档处理服务和 Weaviate 均已就绪。

组织与账号

设置企业名称、初始管理员和员工账号、企业 Token 总配额、员工默认 Token 配额，以及配额周期与时区。管理员账号和员工账号不能相同。

基础对话模型

配置企业默认对话模型，包括供应商、模型名称、Base URL 和 API Key。

基础对话模型是必填项，必须通过连接测试才能继续。API Key 会加密保存，不需要写入项目代码或预置为固定环境变量。

其他模型（可选）

可以在初始化时配置，也可以稍后在管理后台补充：

Embedding：企业知识库向量学习和语义检索所需。
Rerank：改善知识检索候选内容的相关性排序。
Vision：用于图片、截图、扫描件和图表理解。
Image：用于图片、插图和视觉素材生成。

不配置这些专项模型不会影响基础文字对话，但对应能力暂不可用或会采用可用的降级路径。

联网搜索（可选）

可选择并测试一个联网搜索服务。跳过后仍可使用普通对话，但网页搜索和多源研究暂不可用。

完成

初始化完成页会显示员工 Web、管理后台、MOVO Desktop 企业服务连接地址，并提供可下载的连接配置文件。

4. 登录并开始使用

默认端口下：

入口	地址	用途
员工 Web	`http://localhost:3000/`	对话、研究、知识、文件和内容生成
管理后台	`http://localhost:3000/admin/`	组织、账号、模型、知识、Skill、工具和治理配置
初始化向导	`http://localhost:3000/admin/setup`	仅用于首次企业初始化

完成初始化后，使用刚刚创建的管理员账号登录管理后台，使用员工账号登录用户端。

建议先完成以下验证：

在用户端发起一次普通对话。
在管理后台确认默认模型处于启用状态。
如已配置 Embedding，上传一份测试文档并等待学习完成，再进行内部知识问答。
如已配置联网搜索，发起一次需要最新公开信息的搜索任务。

5. 连接 MOVO Desktop（可选）

Docker Compose 部署的是 MOVO 服务端与 Web 产品。普通对话、研究、知识和内容生成可直接在 Web 端使用；需要访问本地浏览器、代码目录、项目终端和 Git 工作区的浏览器 Agent 与 Code Agent 仅在 MOVO Desktop 中提供。

下载并安装

打开 MOVO Desktop 下载页。
Windows 10/11（x64）：下载 .exe 安装程序并运行。当前 Windows 安装包暂未签名，系统可能提示“未知发布者”或 SmartScreen 警告；请仅从本官网下载并确认来源。
Mac：在苹果菜单的“关于本机”中查看“芯片”或“处理器”，选择 Apple 芯片版或 Intel 芯片版。打开下载的 .dmg，将 MOVO 拖入“应用程序”后启动。Mac 安装包已完成开发者签名和 Apple 公证。

连接自己的 MOVO 服务

确保已完成第 2–3 节的服务端部署和首次初始化。
在 MOVO Desktop 的登录页或“设置”中，填写初始化完成页给出的企业服务地址。
使用初始化时创建的员工账号登录。

如果 Desktop 和 MOVO 服务端在同一台电脑上，可使用：

text

http://localhost:3000

如果服务端部署在其他设备或云服务器上，请填写 Desktop 所在电脑能够访问的 IP 或 HTTPS 域名，不要使用服务器自身的 localhost。

连接成功后，浏览器 Agent 会使用 Desktop 管理的本地 Chromium 及其登录状态；Code Agent 则会在你于 Desktop 中选择的本地代码 Workspace 中访问项目终端和 Git。

Desktop 会根据企业服务地址自动连接服务端 API 与本地 Agent，不需要单独填写 WebSocket 地址。

6. 修改端口或部署到企业域名

本机默认无需创建 .env 文件。如果需要修改公开端口或设置企业访问地址：

bash

cp .env.example .env

例如：

env

MOVO_PORT=8080
PUBLIC_BASE_URL=https://ai.company.com

MOVO_PORT 控制宿主机公开端口。
PUBLIC_BASE_URL 用于生成用户端、管理端和 Desktop 连接地址。
DNS、HTTPS 证书和外部反向代理由企业部署环境负责。

模型 API Key 应优先在初始化向导或管理后台中配置，不要写入代码，也不需要预置某一家模型供应商的固定密钥。

7. 日常运维命令

bash

# 查看全部容器状态
./movo status

# 查看所有服务最近日志
./movo logs

# 查看指定服务日志
./movo logs chat-api
./movo logs admin-api
./movo logs document-api
./movo logs dsh-runtime-host

# 重启完整平台并重新等待健康检查
./movo restart

# 停止服务，保留数据库、知识文档和其他数据卷
./movo down

更新官方预构建镜像并重新创建服务：

bash

./movo update

使用原生 Compose 时执行：

bash

docker compose pull
docker compose up -d

只有在开发 MOVO 源码时，才需要拉取代码后重新构建：

bash

git pull
./movo up --build

删除全部数据

./movo down -v 会删除 MOVO 的持久化数据卷和初始化状态。除非明确需要清空部署，否则不要执行。

8. 常见问题

Docker 未运行

如果启动器提示 Docker 不可用，请先启动 Docker Engine 或 Docker Desktop，再重新执行 ./movo --lang zh-CN up。

Windows 提示没有 Bash 或没有执行权限

出现 env: can't execute 'bash': No such file or directory 时，先检查提示符是否以 docker-desktop: 开头；如果是，请退出并执行 wsl -d Ubuntu。如果代码位于 Windows 磁盘且提示 Permission denied，可改用：

bash

bash ./movo --lang zh-CN up

镜像拉取出现 EOF

这通常是 Docker Hub 或 GitHub Container Registry 的网络波动，不表示 MOVO 镜像不存在。最新版启动器会串行拉取并持续重试，已经完成的镜像和镜像层会继续复用。

服务长时间未就绪

bash

./movo status
./movo logs

首次下载体积较大的文档处理镜像时可能需要较长时间。重点检查未通过健康检查的服务及其日志。

端口 3000 被占用

在仓库根目录创建 .env：

env

MOVO_PORT=8080

然后重新执行 ./movo up，访问 http://localhost:8080/admin/setup。

初始化后无法再次打开向导

初始化是一次性流程。完成后访问 /admin/setup 会转到管理后台登录页，这是正常行为。

9. 源码开发模式

只有在开发或调试 MOVO 本身时，才建议使用源码模式：

bash

# 完整源码开发环境（推荐）
./dev_dsh.sh

dev_dsh.sh 会先启动固定版本的 DSH Runtime Host（默认端口 8101），再调用 dev.sh 启动用户端、管理端、API 和文档处理服务。

./dev.sh 仍然可用，但它只启动平台服务，不负责启动 DSH Runtime Host。仅当你只调试 Web/API，或已经在 DSH_RUNTIME_HOST_URL 配置的地址运行了 DSH Runtime Host 时，才建议单独使用它。

源码模式需要 Node.js 22.19+ 或 24+、pnpm、Python 3.10+、Redis 和各模块依赖。它不替代 Docker Compose 的完整自托管部署。

快速开始 ​

1. 准备环境 ​

Windows：必须进入 Ubuntu，而不是 docker-desktop ​

2. 获取并启动 MOVO ​

3. 完成首次初始化 ​

部署检测 ​

组织与账号 ​

基础对话模型 ​

其他模型（可选） ​

联网搜索（可选） ​

完成 ​

4. 登录并开始使用 ​

5. 连接 MOVO Desktop（可选） ​

下载并安装 ​

连接自己的 MOVO 服务 ​

6. 修改端口或部署到企业域名 ​

7. 日常运维命令 ​

8. 常见问题 ​

Docker 未运行 ​

Windows 提示没有 Bash 或没有执行权限 ​

镜像拉取出现 EOF ​

服务长时间未就绪 ​

端口 3000 被占用 ​

初始化后无法再次打开向导 ​

9. 源码开发模式 ​

快速开始

1. 准备环境

Windows：必须进入 Ubuntu，而不是 `docker-desktop`

2. 获取并启动 MOVO

3. 完成首次初始化

部署检测

组织与账号

基础对话模型

其他模型（可选）

联网搜索（可选）

完成

4. 登录并开始使用

5. 连接 MOVO Desktop（可选）

下载并安装

连接自己的 MOVO 服务

6. 修改端口或部署到企业域名

7. 日常运维命令

8. 常见问题

Docker 未运行

Windows 提示没有 Bash 或没有执行权限

镜像拉取出现 EOF

服务长时间未就绪

端口 3000 被占用

初始化后无法再次打开向导

9. 源码开发模式