Windows 配置 GopherPaper 开发环境

如何在 Win 上配置 Agent 开发常见环境#

本文记录在 Windows 上配置 GopherPaper 本地开发环境的过程。需要准备四类内容：

语言运行：Go（编译跑后端）
容器：Docker Desktop（一键起 MySQL / Redis / RabbitMQ / Milvus）
本地向量化模型：Ollama + bge-m3（RAG 检索要用）
三个密钥：大模型 API key、MinerU 解析 token、网易邮箱 SMTP 授权码

先确认运行时、容器、模型和密钥四件事，后面基本就是按步骤检查。

1. 安装 Go#

到官网 go.dev/dl 下载 Windows 安装包，认准 goX.Y.Z.windows-amd64.msi。项目要求 Go 1.26 及以上（go.mod 写的是 go 1.26.3），别装太旧的版本。

截止 2026 年 6 月 9 日

下载链接是有效的

双击 .msi 安装即可，安装器会自动把 Go 加入 PATH。安装完成后，重新打开 PowerShell 验证：

go version

看到 go version go1.26.x windows/amd64 就对了。

国内拉依赖慢的话，配一下模块代理（一次就够，全局生效）：

go env -w GOPROXY=https://goproxy.cn,direct

强烈建议开启喵喵工具的虚拟网卡或者TUN模式，方便在终端使用，镜像还是不方便，下文的docker、ollama拉取模型和go的依赖(类似于Java中的Maven)下载时都默认你在国外。

2. 安装 Docker Desktop#

后端依赖 MySQL、Redis、RabbitMQ、Milvus 等中间件，统一通过 Docker Compose 启动。

如果你已经有有了WSL，直接安装docker即可。

Windows 上的 Docker Desktop 推荐使用 WSL2。先用管理员身份打开 PowerShell，执行：

wsl --install

这条命令会自动开启所需的 Windows 功能并装上一个 Ubuntu 子系统，装完重启电脑。

然后到 docker.com/products/docker-desktop 下载 Docker Desktop 安装包，安装时勾选 Use WSL 2 instead of Hyper-V。装完启动 Docker Desktop，等右下角小鲸鱼图标不再转圈，验证：

docker version
docker compose version

两条都能打印出版本号，说明容器环境就绪了。

3. 拉起基础设施#

进入项目目录，使用仓库内的 Compose 编排启动基础设施：

docker compose -f deploy/docker-compose.yml up -d

该命令会启动 MySQL / Redis / RabbitMQ / Milvus（含 etcd、MinIO）以及 Milvus 可视化界面 Attu。第一次拉取镜像耗时较长，等待容器启动完成后访问：

Milvus 可视化 Attu：http://localhost:8000
RabbitMQ 管理台：http://localhost:15672（账号密码都是 gopher）

用 docker ps 看一眼，所有容器状态是 Up / healthy 就没问题。

第一次拉镜像慢是正常的，等容器健康后再继续启动后端。

4. 安装 Ollama 并拉 embedding 模型#

RAG 检索需要把文本向量化，这里使用本地 Ollama 运行 bge-m3 模型。

到 ollama.com/download 下载 Windows 版安装包，装完它会常驻后台（任务栏有个羊驼图标）。然后在 PowerShell 拉模型：

ollama pull bge-m3

bge-m3 大概 1～2 GB，拉完验证服务在跑：

ollama list

能看到 bge-m3 这一行就行。Ollama 默认监听 http://localhost:11434，正好对上配置里的 [embedding].base_url。

5. 拿三个密钥#

项目需要三个外部服务凭据，分别是大模型 API key、MinerU token 和邮箱 SMTP 授权码。

5.1 大模型 API key#

项目使用 OpenAI 兼容接口。到中转站或者官方的模型平台的「API Keys」页面新建 key，记录 api_key、base_url 和模型名。意图模型和下游问答模型可以共用同一个 key，也可以分别配置不同模型。

5.2 MinerU 解析 token#

PDF 解析走 MinerU 在线 API。

到 mineru.net 注册并登录
进个人中心，找到 API / 申请 API 使用（开放平台页面）
申请通过后会给你一个 API Token，复制下来

这个 token 填到配置的 [parser].token，base_url 保持默认的 https://mineru.net/api/v4 即可。

5.3 网易邮箱 SMTP 授权码#

注意：这里要的不是邮箱登录密码，而是一串单独的「客户端授权码」。以 163 邮箱为例：

浏览器登录 mail.163.com
顶部进入 设置 → POP3/SMTP/IMAP
开启 SMTP 服务（和 IMAP/POP3 一起开）
按提示用手机发一条短信做验证
验证通过后弹出的那串字符，就是 授权码，只显示一次，立刻复制保存

对应配置里的 [mail]：

smtp_host = smtp.163.com
smtp_port = 465（SSL 端口）
server_mail = 你的 163 邮箱地址
key = 刚拿到的授权码

如果用的是 126 邮箱就把 host 换成 smtp.126.com，QQ 邮箱同理换成 smtp.qq.com，流程都是「开服务 → 拿授权码」。

6. 写配置文件#

项目使用 TOML 配置。先从示例文件复制一份本地配置：

copy config\config.example.toml config\config.toml

config.toml 已被 gitignore，不会误提交。然后打开 config\config.toml，填写前面获取的密钥。关键配置如下：

[models.intent]      # 意图路由小模型
api_key = "sk-xxxx"
model = "gpt-4o-mini"

[models.chat]        # 下游问答/抽取/报告大模型
api_key = "sk-xxxx"
model = "gpt-4o-mini"

[parser]             # MinerU
token = "你申请到的-mineru-token"

[mail]               # 网易 SMTP
smtp_host = "smtp.163.com"
smtp_port = 465
server_mail = "你的邮箱@163.com"
key = "网易授权码"

[mysql] / [redis] / [mq] / [milvus] 保持默认即可，它们对应第 3 步启动的本地容器。[embedding] 也保持默认，指向本地 Ollama。

7. 跑起来#

依赖装好、密钥填好，最后启动后端：

go run ./cmd/server

第一次启动会自动下载 Go 依赖并建表（AutoMigrate）。看到服务监听 :8080 且没有报错，说明后端启动成功。

完整流程可以按以下顺序验证：

注册账号，确认邮箱验证码可以正常发送
上传一篇 PDF
查看解析状态是否从 parsing 推进到 ready
打开 RabbitMQ 管理台和 Attu，确认消息与向量数据是否正常写入

验证清单#

配置完成后检查：

go version 是 1.26+
docker ps 里 MySQL / Redis / RabbitMQ / Milvus 全是 Up
ollama list 里有 bge-m3
config\config.toml 里三个密钥都填了，没有残留 xxxx
go run ./cmd/server 启动无报错，监听 :8080
注册能收到验证码邮件，上传 PDF 能解析到 ready

清单全部通过后，Windows 本地开发环境就配置完成了。