快速开始

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

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

1. 准备环境

只需准备：

• Git
• Docker Engine 或 Docker Desktop
• Docker Compose v2

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

docker compose version
docker info

首次构建需要下载容器镜像、项目依赖和文档处理模型，耗时取决于网络和机器性能。

2. 获取并启动 MOVO

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

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

启动器会：

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

默认地址为：

http://localhost:3000/admin/setup

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

docker compose up -d

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

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

3. 完成首次初始化

在浏览器打开：

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	仅用于首次企业初始化

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

建议先完成以下验证：

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

5. 连接 MOVO Desktop（可选）

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

下载并安装

1. 打开 MOVO Desktop 下载页。
2. 在苹果菜单的“关于本机”中查看“芯片”或“处理器”，选择 Apple 芯片版或 Intel 芯片版。
3. 打开下载的 .dmg 文件，将 MOVO 拖入“应用程序”后启动。安装包已完成开发者签名和 Apple 公证。

连接自己的 MOVO 服务

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

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

http://localhost:3000

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

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

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

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

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

cp .env.example .env

例如：

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

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

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

7. 日常运维命令

# 查看全部容器状态
./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

升级代码后重新构建并启动：

git pull
./movo up --build

删除全部数据

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

8. 常见问题

Docker 未运行

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

服务长时间未就绪

./movo status
./movo logs

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

端口 3000 被占用

在仓库根目录创建 .env：

MOVO_PORT=8080

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

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

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

9. 源码开发模式

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

# 完整源码开发环境（推荐）
./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 的完整自托管部署。