windows本地部署AgentDesk

下面给你一套适合小白的"Windows 本地运行 AgentDesk + 远程服务器 Docker 运行 Qdrant"的完整流程。

我建议采用这个结构：

python 复制代码

你的 Windows 电脑
├─ AgentDesk 后端（Go，8083）
├─ AgentDesk 前端（Next.js，3000）
├─ SQLite 数据库（本机 data/app.db）
└─ 连接远程 Qdrant（服务器:6334）

远程 Linux 服务器
└─ Docker 中运行 Qdrant

1、准备 Windows 本地环境

打开 PowerShell，逐项检查：

python 复制代码

git --version
go version
node -v
pnpm -v

你需要满足：

Git：任意较新版本
Go：1.26 或更高
Node.js：20 或更高
pnpm：已安装
如果 pnpm -v 报错，先执行：

python 复制代码

corepack enable
corepack prepare pnpm@latest --activate

如果上述命令也不可用，可以安装 pnpm：

python 复制代码

npm install -g pnpm

然后重新打开 PowerShell，再执行：

python 复制代码

pnpm -v

安装Go，官网下载地址如下：

python 复制代码

https://go.dev/dl/

找到 Windows 对应的安装包，下载类似 go1.xx.x.windows-amd64.msi 的文件。

amd64：适用于大多数 Intel、AMD 64 位电脑。
arm64：适用于 ARM 架构的 Windows 电脑。

双击下载的 .msi 文件。

按照安装向导操作，保持默认配置即可。

然后重新打开 PowerShell，再执行如下指令：

2、准备远程服务器上的 Qdrant

以下假设远程服务器是 Linux，并且已经安装 Docker。先登录服务器：

确认 Docker 可用：

python 复制代码

docker version

如果能显示 Client / Server 信息，说明 Docker 正常。

1. 创建 Qdrant 持久化存储卷

python 复制代码

cd /data_4/googosoft_file/AAA_agent/
docker volume create qdrant-storage

这一步很重要：Qdrant 的知识向量会存到这个 Volume 中。没有它，删除并重建容器后可能丢失知识库向量。

查看卷的详细信息：

python 复制代码

docker volume inspect qdrant-storage

输出如下：

2. 生成并保存一个 API Key

在服务器上执行：

python 复制代码

openssl rand -base64 48
# XgrPnZzZK6lcozGO3rK63zn5Ox5sl6Oq0YxtefB7/tWAV2Hq0gS0PyTwEhCVS0/5

复制输出的一整段内容，保存到密码管理器。下面用它替代你的高强度密钥。

3. 启动 Qdrant

如果你通过公司内网、WireGuard、Tailscale 等 VPN 连接服务器，可以先使用下面这个较易操作的方案：

python 复制代码

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 127.0.0.1:6333:6333 \
  -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY='你的高强度密钥' \
  qdrant/qdrant:<固定版本号>

请把 <固定版本号> 换成你准备使用的具体版本，例如 v1.17.0；不要长期使用 latest。

具体：

python 复制代码

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 127.0.0.1:6333:6333 \
  -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY='XgrPnZzZK6lcozGO3rK63zn5Ox5sl6Oq0YxtefB7/tWAV2Hq0gS0PyTwEhCVS0/5' \
  qdrant/qdrant:v1.17.0

或者：

python 复制代码

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 127.0.0.1:6333:6333 \
  -p 6334:6334 \
  -v /data_4/googosoft_file/AAA_agent/qdrant-storage:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY='你的真实API密钥' \
  qdrant/qdrant:v1.17.0

参数含义：

6334：AgentDesk 实际连接的 Qdrant gRPC 端口。
127.0.0.1:6333:6333：REST/API/Web UI 只允许在服务器本机访问，不暴露到公网。
qdrant-storage：Qdrant 持久化数据卷。
QDRANT__SERVICE__API_KEY：要求所有请求携带密钥。
--restart unless-stopped：服务器重启后自动恢复。

检查容器：

python 复制代码

docker ps

在服务器本机验证 REST 服务和 API Key：

python 复制代码

curl -H "api-key: 你的高强度密钥" http://127.0.0.1:6333/collections

python 复制代码

# 例如：curl -H "api-key: XgrPnZzZK6lcozGO3rK63zn5Ox5sl6Oq0YxtefB7/tWAV2Hq0gS0PyTwEhCVS0/5" http://127.0.0.1:6333/collections

正常时会返回 JSON，而不是 Unauthorized 或连接失败。

3、处理远程访问安全

3、下载并配置 Windows 本地项目

进入项目目录：

python 复制代码

Set-Location E:\googosoft\agent-desk-main

先检查配置文件是否已存在：

python 复制代码

Test-Path .\config\config.yaml

如果输出 False，复制模板：

python 复制代码

Copy-Item '.\config\config.example copy.yaml' '.\config\config.yaml'

然后用 VS Code 或记事本打开：

python 复制代码

code .\config\config.yaml

找到并修改 vectorDB 部分。

VPN / 内网 Qdrant 配置示例：

python 复制代码

vectorDB:
  type: qdrant
  qdrant:
    host: 10.10.10.20
    grpcPort: 6334
    apiKey: "填写你刚才保存的 API Key"
    useTls: false

把 10.10.10.20 换成远程 Qdrant 服务器的内网或 VPN IP。

公网 + TLS Qdrant 配置示例

python 复制代码

vectorDB:
  type: qdrant
  qdrant:
    host: qdrant.example.com
    grpcPort: 6334
    apiKey: "填写你刚才保存的 API Key"
    useTls: true

这里建议使用域名和受 Windows 信任的 TLS 证书。项目当前只暴露 useTls 开关，并没有提供单独配置自签名证书 CA 文件的位置；初次部署不建议使用自签名证书。

同时确认本地 SQLite 保持如下设置即可：

python 复制代码

db:
  type: sqlite
  dsn: file:./data/app.db?_busy_timeout=5000

这样本地会自动创建：

python 复制代码

data/app.db
data/storage/

4、先测试 Windows 到 Qdrant 的网络

在 Windows PowerShell 中执行：

python 复制代码

Test-NetConnection 10.10.10.20 -Port 6334

把 IP 换成实际 Qdrant 地址。

如果是 False，先不要启动 AgentDesk，优先检查：

host 是否正确；
Docker 容器是否运行；
远程服务器是否开放 6334；
云安全组是否允许访问；
VPN 是否已连接；
Windows 是否被公司网络策略限制出站连接。

5、安装前端依赖

仍在项目根目录时执行：

python 复制代码

Set-Location .\web
pnpm install

首次安装会比较久。成功后应出现 node_modules，且命令正常结束。

然后返回项目根目录：

python 复制代码

Set-Location ..

6、启动后端

在第一个 PowerShell 窗口中，确保当前目录是项目根目录：

python 复制代码

Set-Location E:\googosoft\agent-desk-main

执行：

python 复制代码

go run -tags dev ./cmd/server

看到类似"服务启动于 8083 端口"的日志后，不要关闭此窗口。

浏览器访问：

python 复制代码

http://127.0.0.1:8083/api/health