企业官网建设流程全解析

windows本地部署AgentDesk

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

我建议采用这个结构：

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

1、准备 Windows 本地环境

打开 PowerShell，逐项检查：

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

你需要满足：

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

corepack enable corepack prepare pnpm@latest--activate

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

npm install-g pnpm

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

pnpm-v

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

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 可用：

docker version

如果能显示 Client / Server 信息，说明 Docker 正常。
1. 创建 Qdrant 持久化存储卷

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

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

查看卷的详细信息：

docker volume inspect qdrant-storage

输出如下：

2. 生成并保存一个 API Key
在服务器上执行：

openssl rand-base6448# XgrPnZzZK6lcozGO3rK63zn5Ox5sl6Oq0YxtefB7/tWAV2Hq0gS0PyTwEhCVS0/5

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

3. 启动 Qdrant

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

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

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

具体：

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

或者：

docker run-d \--name qdrant \--restart unless-stopped \-p127.0.0.1:6333:6333\-p6334: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：服务器重启后自动恢复。

检查容器：

docker ps

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

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

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

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

3、处理远程访问安全

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

进入项目目录：

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

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

Test-Path.\config\config.yaml

如果输出 False，复制模板：

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

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

code.\config\config.yaml

找到并修改 vectorDB 部分。
VPN / 内网 Qdrant 配置示例：

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

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

公网 + TLS Qdrant 配置示例

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

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

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

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

这样本地会自动创建：

data/app.db data/storage/

4、先测试 Windows 到 Qdrant 的网络

在 Windows PowerShell 中执行：

Test-NetConnection10.10.10.20-Port6334

把 IP 换成实际 Qdrant 地址。

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

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

5、安装前端依赖

仍在项目根目录时执行：

Set-Location.\web pnpm install

首次安装会比较久。成功后应出现 node_modules，且命令正常结束。
然后返回项目根目录：

Set-Location..

6、启动后端

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

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

执行：

go run-tags dev./cmd/server

看到类似“服务启动于 8083 端口”的日志后，不要关闭此窗口。
浏览器访问：

http://127.0.0.1:8083/api/health