deepsearch/docs/zh/2.安装指导/DeepSearch_SDK/Docker方式安装/Windows系统安装.md-代码预览-deepsearch:基于 openJiuwen agent-core 的深度检索与研究引擎项目 - AtomGit

OopenJiuwen-botdoc:update version in doc

1b8c44b2创建于 14 天前历史提交

本指南介绍在 Windows 系统采用 Docker 方式安装 DeepSearch。

一、环境准备

请确保机器满足以下要求：

硬件：
- CPU：最低 2 核，推荐 4 核及以上
- RAM：最低 4GB，推荐 8GB 及以上
操作系统：Windows10及以上
软件
- Git：点击下载链接进行下载并安装
- Docker：推荐使用 Docker Desktop 进行安装，安装方法详见下文

安装Docker Desktop

Windows 上运行 Docker Desktop 推荐使用 WSL 2（Windows Subsystem for Linux 2）作为虚拟化后端，相比 LinuxKit 兼容性更好、资源占用更低，且能避免已知的僵尸容器 Bug。

1. 启用 WSL 2

对于符合条件的 Windows 系统（Windows 10 版本 2004 及更高版本<内部版本 19041 及更高版本>或 Windows 11），仅运行 wsl --install就能一键配置、下载并安装默认的 Linux 发行版。

按下 Windows + S，输入 PowerShell 进行搜索。
在搜索结果中，右键点击 Windows PowerShell，选择「以管理员身份运行」。
在 PowerShell 执行如下命令，然后重新启动计算机。
```
wsl --install
```

而旧版本 Windows 不支持这个一键命令的完整自动化功能，可能需要补充操作，具体请参考如何使用 WSL 在 Windows 上安装 Linux

2. 安装 Docker Desktop

下载：前往 Docker 官网下载 Windows 版本安装包（X86 机器请选择 AMD64 版本）；
运行安装包：仅勾选「Use WSL 2 instead of Hyper-V」、「Add shortcut to desktop」选项，点击「OK」开始安装；
安装完成后，请重启电脑；
重启后，打开 Docker Desktop，等待加载完成（首次启动可能需要 5-10 分钟）；
Docker Desktop 启动后：
- 若临时试用，可点击欢迎界面的 Continue without signing in 直接进入；
- 长期使用请参考官方指导。
至此，Docker Desktop 安装完成。

说明：若安装过程中出现报错，或了解官方安装过程，请参考 Docker Desktop 官方安装指导。

安装 MySQL（可选组件）

SQLite vs MySQL：
- SQLite 无需额外安装和配置，适合开发和测试环境，但功能受限（如不支持高并发写入、无用户权限管理等）。
- MySQL 功能更完善，能够满足复杂场景的需求，因此在实际工程和生产环境中更推荐使用。

MySQL

说明：若需使用 MySQL，请在传入参数中将 DB_TYPE 设置为 mysql，并按照下列步骤完成 MySQL 的安装和配置。启动命令参考数据库配置。
下载 MySQL 8.4 安装包。
双击下载完成的安装包，跟随安装向导完成安装流程；建议选择 Typical 模式。

注意：在安装 MySQL 时如遇到 “This application requires Visual Studio 2019 x64 Redistributable”，请下载 Microsoft Visual C++ 官网最新受支持的 Visual C++ x64 版本安装包。
安装完成后，配置 MySQL 的 root 密码，请记住该密码。
按下 Win+R → 输入以下命令，打开「环境变量」窗口：
```
rundll32.exe sysdm.cpl,EditEnvironmentVariables
```
将 MySQL 的 bin 目录添加至系统环境变量（MySQL 的默认 bin 路径：C:\Program Files\MySQL\MySQL Server 8.4\bin）
安装完成后，打开 “PowerShell”，登录 MySQL（输入安装时设置的 root 密码）：
```
mysql -u root -p
```

在 MySQL 中执行以下命令创建数据库：

说明：your_user_name、your_password 需自行设置，后续启动命令将会用到。

# 新建数据库
CREATE DATABASE openjiuwen_deepsearch;
# 新建 MySQL 用户
CREATE USER 'your_user_name'@'localhost' IDENTIFIED BY 'your_password';
# 用户授权并刷新
GRANT ALL PRIVILEGES ON openjiuwen_deepsearch.* TO 'your_user_name'@'localhost';
FLUSH PRIVILEGES;

二、DeepSearch 服务安装

1. 下载版本包

运行以下命令下载版本包：

# 下载 x86_64 架构版本包：
docker pull swr.cn-north-4.myhuaweicloud.com/openjiuwen/deepsearch-studio-server-amd64:0.1.6

# 下载 ARM64 架构版本包：
docker pull swr.cn-north-4.myhuaweicloud.com/openjiuwen/deepsearch-studio-server-arm64:0.1.6

本地构建镜像：若无法拉取 SWR 或需与仓库源码一致，在 DeepSearch 源码根目录执行
docker build -t deepsearch-full -f docker/Dockerfile .
其中 deepsearch-full 仅为示例标签（-t 可改为任意名称），须与 docker run 最后一行镜像名一致。

2. 启动 DeepSearch 服务（以 x86_64 架构为例）

最小化可运行的启动命令如下（以SQLite作为数据库）：

docker run \
  -p 8000:8000 \ 
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \ 
  -e DB_TYPE=sqlite \ 
  swr.cn-north-4.myhuaweicloud.com/openjiuwen/deepsearch-studio-server-amd64:0.1.6

当出现如下信息时，表示服务已成功启动：

INFO:     Application startup complete.

更多参数配置信息请参考拓展参数。

3. 拓展参数

端口映射

服务可以通过端口映射将其暴露到宿主机的指定端口。端口映射参数格式如下：

-p <宿主机端口>:<容器端口>

示例：

-p 8000:8000

表示将容器内部的 8000 端口映射到宿主机的 8000 端口，服务可通过 http://localhost:8000 访问。

如宿主机端口已被占用，也可使用不同端口进行映射，例如：

-p 9000:8000

数据库 / 存储配置

数据库相关参数通过环境变量传入（-e），用于控制数据存储方式及连接信息。

`DB_TYPE`

作用：选择数据库类型
可选值：sqlite / mysql

MySQL 相关参数（`DB_TYPE=mysql` 时生效）

参数	说明
`DB_HOST`	MySQL 服务地址
`DB_PORT`	MySQL 服务端口
`DB_USER`	数据库用户名
`DB_PASSWORD`	数据库密码
`DEEPSEARCH_DB_NAME`	数据库名称

注意：在 Docker 部署环境下，需要显式配置容器访问宿主机的网络地址 host.docker.internal 从而访问 MySQL 服务。使用示例：

docker run \
  -p 8000:8000 \
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \
  -e DB_TYPE=mysql \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=3306 \
  -e DB_USER=your_user_name \
  -e DB_PASSWORD=your_password \
  -e DEEPSEARCH_DB_NAME=openjiuwen_deepsearch \
  swr.cn-north-4.myhuaweicloud.com/openjiuwen/deepsearch-studio-server-amd64:0.1.6

SQLite 相关参数（`DB_TYPE=sqlite` 时生效）

参数	说明
`SQLITE_DB_PATH`	SQLite 数据文件存储目录，默认`data/databases`
`DEEPSEARCH_SQLITE_DB`	SQLite 数据库文件名，默认`agent.db`

Milvus（知识库向量索引）

本地知识库依赖向量存储时，需设置 INDEX_MANAGER_TYPE=milvus 并配置 Milvus 连接。DeepSearch 服务镜像内不包含 Milvus，需要在宿主机或其他容器中单独部署并启动 Milvus（例如 Milvus 单机 Docker 说明、自写 docker-compose，或 Agent Studio 等环境中已提供的 Milvus 容器）。

Milvus 相关参数（`INDEX_MANAGER_TYPE=milvus` 时生效）

参数	说明	默认值
`INDEX_MANAGER_TYPE`	向量索引类型，当前为 `milvus`	`milvus`
`MILVUS_HOST`	Milvus 服务地址（运行 DeepSearch 的容器内须能解析）	见下文
`MILVUS_PORT`	Milvus 端口（gRPC，一般为 `19530`）	`19530`
`MILVUS_TOKEN`	启用 Milvus 认证时填写；无认证可留空	留空

网络说明：

Milvus 在 WSL2 / 宿主机本机进程监听 19530：DeepSearch 若在 Docker Desktop 的 Linux 容器内，可设 MILVUS_HOST=host.docker.internal、MILVUS_PORT=19530（或实际监听端口）。
DeepSearch 与 Milvus 在同一 Docker 自定义网络：将 MILVUS_HOST 设为 Milvus 的 Compose 服务名或容器名，MILVUS_PORT 填 Milvus 容器内监听端口（通常为 19530），无需使用 host.docker.internal。
Milvus 在另一个 Docker 容器，且已将端口映射到宿主机（例如 docker run -p 19530:19530 ... 或 Compose 中 ports: "19530:19530"）：DeepSearch 容器内仍使用 MILVUS_HOST=host.docker.internal，MILVUS_PORT 填宿主机上映射的端口（未改映射时即为 19530）。

Checkpointer 配置

Checkpointer 用于管理 Agent 工作流的会话状态，支持工作流的暂停、恢复和状态持久化。

`CHECKPOINTER_TYPE`

作用：选择 Checkpointer 类型
可选值：in_memory / persistence / redis
默认值：in_memory

Persistence 模式相关参数（`CHECKPOINTER_TYPE=persistence` 时生效）

参数	说明	默认值
`CHECKPOINTER_DB_TYPE`	数据库类型（sqlite / shelve）	`sqlite`
`CHECKPOINTER_DB_PATH`	数据库文件路径	`data/databases/checkpointer.db`

Redis 模式相关参数（`CHECKPOINTER_TYPE=redis` 时生效）

参数	说明	默认值
`REDIS_URL`	Redis 连接 URL	`redis://localhost:6379`
`REDIS_CLUSTER_MODE`	是否启用 Redis Cluster 模式	`false`
`REDIS_TTL`	会话状态过期时间	`7200`
`REDIS_REFRESH_ON_READ`	每次读取时是否刷新 TTL	`true`

对象存储 OBS（`CHECKPOINTER_TYPE=redis` 时必填）

分布式（Redis）部署时，知识库文档须写入共享对象存储；下列变量须完整配置，否则服务无法启动。in_memory / persistence 模式下知识库仅本地存储，无需配置 OBS。

参数	说明	默认值
`OBS_SERVER`	S3 兼容 Endpoint URL	（须配置）
`OBS_REGION`	区域（`region_name`，如华为云 `cn-north-4`）	（须配置）
`OBS_BUCKET`	桶名	（须配置）
`OBS_ACCESS_KEY_ID`	访问密钥 ID	（须配置）
`OBS_SECRET_ACCESS_KEY`	访问密钥 Secret	（须配置）

镜像说明：

官方镜像：从华为云 SWR 拉取，启动命令最后一行使用已 docker pull 的完整镜像名，例如
swr.cn-north-4.myhuaweicloud.com/openjiuwen/deepsearch-studio-server-arm64:0.1.6（ARM64）或
swr.cn-north-4.myhuaweicloud.com/openjiuwen/deepsearch-studio-server-amd64:0.1.6（x86_64）。拉取失败多为网络或权限问题，可检查代理、镜像加速或改用本地构建。
本地构建 deepsearch-full：在 DeepSearch 源码仓库根目录执行
docker build -t deepsearch-full -f docker/Dockerfile .
其中 deepsearch-full 仅为示例标签（-t 可改为任意名称）。

下文示例以 deepsearch-full 为例；使用官方镜像时，将每条命令最后一行替换为对应的 SWR 镜像地址。请先单独启动 Milvus 与（若使用 redis 模式）Redis，并保证端口可从 DeepSearch 容器访问（配置方式见上文「Milvus（知识库向量索引）」与「Redis 模式相关参数」）。

使用示例：

# 开发测试环境（默认配置，无需额外参数）
# MySQL
docker run -p 8000:8000 \
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \
  -e DB_TYPE=mysql \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=3306 \
  -e DB_USER=your_user_name \
  -e DB_PASSWORD=your_password \
  -e INDEX_MANAGER_TYPE=milvus \
  -e MILVUS_HOST=host.docker.internal \
  -e MILVUS_PORT=19530 \
  -e DEEPSEARCH_DB_NAME=openjiuwen_deepsearch \
  deepsearch-full

# SQLite
docker run -p 8000:8000 \
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \
  -e DB_TYPE=sqlite \
  -e SQLITE_DB_PATH=data/databases \
  -e DEEPSEARCH_SQLITE_DB=agent.db \
  -e INDEX_MANAGER_TYPE=milvus \
  -e MILVUS_HOST=host.docker.internal \
  -e MILVUS_PORT=19530 \
  deepsearch-full

# 单机生产环境（persistence 模式）
# MySQL
docker run -p 8000:8000 \
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \
  -e DB_TYPE=mysql \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=3306 \
  -e DB_USER=your_user_name \
  -e DB_PASSWORD=your_password \
  -e INDEX_MANAGER_TYPE=milvus \
  -e MILVUS_HOST=host.docker.internal \
  -e MILVUS_PORT=19530 \
  -e DEEPSEARCH_DB_NAME=openjiuwen_deepsearch \
  -e CHECKPOINTER_TYPE=persistence \
  -e CHECKPOINTER_DB_TYPE=sqlite \
  -e CHECKPOINTER_DB_PATH=data/databases/checkpointer.db \
  deepsearch-full

# SQLite
docker run -p 8000:8000 \
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \
  -e DB_TYPE=sqlite \
  -e SQLITE_DB_PATH=data/databases \
  -e DEEPSEARCH_SQLITE_DB=agent.db \
  -e INDEX_MANAGER_TYPE=milvus \
  -e MILVUS_HOST=host.docker.internal \
  -e MILVUS_PORT=19530 \
  -e CHECKPOINTER_TYPE=persistence \
  -e CHECKPOINTER_DB_TYPE=sqlite \
  -e CHECKPOINTER_DB_PATH=data/databases/checkpointer.db \
  deepsearch-full

# 分布式生产环境（redis 模式）
# MySQL
docker run -p 8000:8000 \
  -e LLM_SSL_VERIFY=False \
  -e TOOL_SSL_VERIFY=False \
  -e EMBEDDING_SSL_VERIFY=False \
  -e DB_TYPE=mysql \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=3306 \
  -e DB_USER=your_user_name \
  -e DB_PASSWORD=your_password \
  -e DEEPSEARCH_DB_NAME=openjiuwen_deepsearch \
  -e INDEX_MANAGER_TYPE=milvus \
  -e MILVUS_HOST=host.docker.internal \
  -e MILVUS_PORT=19530 \
  -e CHECKPOINTER_TYPE=redis \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e REDIS_CLUSTER_MODE=false \
  -e REDIS_TTL=7200 \
  -e REDIS_REFRESH_ON_READ=true \
  -e OBS_SERVER=https://your-obs-endpoint \
  -e OBS_REGION=cn-north-4 \
  -e OBS_BUCKET=your-bucket \
  -e OBS_ACCESS_KEY_ID=your_access_key \
  -e OBS_SECRET_ACCESS_KEY=your_secret_key \
  deepsearch-full

注意事项：

in_memory 模式：无需额外配置，适用于开发测试环境，不支持分布式部署；知识库文档仅存容器/数据卷本地，不使用对象存储
persistence 模式：需要确保数据目录有写权限，适用于单机生产环境；知识库文档同样仅存本地，不使用对象存储
redis 模式：需要先部署 Redis 服务，适用于分布式生产环境；还须通过环境变量完整配置 OBS（见上文「对象存储 OBS」），否则服务无法启动。仅在此模式下知识库上传会写入对象存储以供多实例共享。Redis 若在宿主机或其它容器且端口已映射到宿主机，可使用 REDIS_URL=redis://host.docker.internal:6379（或实际端口）。使用本地知识库时，Milvus 须单独部署，见上文「Milvus（知识库向量索引）」。多实例时 DB_TYPE 必须为 mysql 且连接同一 MySQL（知识库等元数据存于应用数据库；SQLite 为容器内本地文件，实例间不共享，会导致一端创建知识库、另一端查询不到）。