前言
咱们的企业智能知识库系统已经开发了一套完整的 Go 后端,包含用户认证、团队空间、文档管理、文件管理、搜索、AI 助手、RAG、KAG、知识图谱、统计和通知等核心功能。
今天这篇文章,专门介绍如何在一台新的开发机上把 Go 后端和前端完整运行起来。
1. 环境准备
开始之前,请确保本地环境已经安装以下软件:
- Go:1.26
- Git:用于拉取代码
- MySQL:8.0+
- Neo4j:5.x
- Node.js:18+
- npm:9+
- Docker Desktop:推荐,用于快速启动本地 MySQL 和 Neo4j
- IDE:IntelliJ IDEA 或 GoLand,可选
项目当前的 .env 已经配置了以下基础设施地址。MySQL 和 Neo4j 是本地服务,其余中间件使用项目现有远程环境:
| 中间件 | 项目当前配置 | 本地是否必须安装 |
|---|---|---|
| MySQL | localhost:3306 | 是 |
| Neo4j | bolt://localhost:7687 | 是 |
| Redis | 117.72.88.11:6379,DB 2 | 否,远程连接 |
| Elasticsearch | http://117.72.88.11:9200 | 否,远程连接 |
| RabbitMQ | 117.72.88.11:5672 | 否,远程连接 |
| MongoDB | 117.72.88.11:27017 | 否,远程连接 |
| RustFS | 117.72.88.11:9091 | 否,远程连接 |
MySQL 保存用户、角色、团队和文档元数据;Neo4j 保存知识图谱。两者是核心数据服务,本地开发时必须启动。
1.1 安装 Go
macOS:
brew install goWindows:
访问 https://go.dev/dl/ 下载安装包。安装时勾选自动配置 PATH。
验证:
go version当前 go.mod 要求 Go 1.26。
1.2 配置 Go Module 代理
国内网络建议配置:
go env -w GOPROXY=https://goproxy.cn,direct验证:
go env GOPROXY1.3 安装并启动 Docker Desktop
推荐使用 Docker Desktop 启动本地 MySQL 和 Neo4j。
下载地址:
https://www.docker.com/products/docker-desktop/安装后启动 Docker Desktop,并检查:
docker info输出包含 Server Version 表示 Docker 已启动。
1.4 不用 Docker 时
如果本机已经直接安装 MySQL 和 Neo4j,只需要确认它们运行在 .env 配置的地址:
MySQL localhost:3306
Neo4j bolt://localhost:7687MySQL 官方下载:
https://dev.mysql.com/downloads/mysql/Neo4j Community 下载:
https://neo4j.com/deployment-center/安装后版本必须满足 MySQL 8.0+、Neo4j 5.x。
2. 获取代码
2.1 一次性获取三个项目
mkdir -p ~/projects/enterprise-knowledge-base
cd ~/projects/enterprise-knowledge-base
git clone https://gitcode.com/dv-susan/knowledge-base-go.git
git clone https://gitcode.com/dv-susan/knowledge-base-frontend.git
git clone https://gitcode.com/dv-susan/knowledge-base-backend.git
cd knowledge-base-goGo 后端本身不包含 SQL 初始化文件,因此全新环境还需要克隆 Java 后端,仅用于 knowledge-base-backend/sql/ 下的 MySQL 脚本。
如果本地代码已经来自当前企业知识库聚合仓库,则直接进入:
cd project/knowledge-base-go验证 Go Module:
go list -m正常输出:
knowledgebase2.2 项目结构
enterprise-knowledge-base/
├── knowledge-base-go/ # Go 后端
│ ├── cmd/server/ # 服务入口
│ ├── cmd/routedump/ # 路由清单工具
│ ├── internal/config/ # 配置
│ ├── internal/infra/ # MySQL/Redis/ES/Mongo/Neo4j/RustFS
│ ├── internal/middleware/ # JWT、CORS、日志、限流
│ ├── internal/modules/ # 业务模块
│ ├── docker-compose.local.yml # 本地 MySQL + Neo4j
│ ├── .env # 本地运行配置
│ ├── .env.example # 配置模板
│ └── run.sh / run.bat # 启动脚本
│
├── knowledge-base-frontend/ # React 前端
│
└── knowledge-base-backend/ # Java 后端,提供 SQL 初始化文件
└── sql/ # Go 复用的 MySQL 初始化脚本2.3 安装MySQL
之前为了防止一些核心数据,比如:用户账号密码,手机号,或者商品数据等,被随意篡改。
在本地开发环境中,没有给大家提供专门的远程数据库,因为数据库保存的是我们的核心数据,每个人可能都不一样。
如果一个人修改了admin的密码,可能会导致,其他的所有人都正常登录。
而像一些保存非核心数据的中间件,比如:Redis、RabbitMQ、ElasticSearch等,我给大家提供了远程的服务。
这些环境,大家不必重新搭建一遍。
因此,我们需要在本地安装MySQL。
MySQL的版本是8以上。
下载地址:https://dev.mysql.com/downloads/mysql/
你可以根据你操作系统的版本,选择下载不同的MySQL数据库。
具体安装过程,可以参考这篇文章:https://blog.csdn.net/z18769643585/article/details/134186070
2.4 安装Neo4j
Neo4j是图数据库,用来保存数据直接关系的数据库,也是核心数据之一,用来保存企业知识库项目中知识图谱数据的。
因此,也需要在本地部署。
Neo4j下载和安装教程:https://cloud.tencent.com/developer/article/2537036
3. 数据库初始化
Go 后端没有单独实现数据库 Migration,它直接复用 Java 版知识库的 MySQL 表结构和初始化数据。
3.1 数据库清单
Go 后端连接 7 个 MySQL 库:
kb_user
kb_document
kb_file
kb_foundation
kb_search
kb_statistics
kb_aiNeo4j 数据保存在图数据库中,不使用 kb_graph MySQL 库。
3.2 推荐方式:导入全量 SQL
进入 Java 项目的 SQL 目录:
cd ../knowledge-base-backend/sql当前完整的全量导出文件:
knowledge_base_export_2026-06-23.sql先读取 Go 项目现有的 .env:
set -a
source ../../knowledge-base-go/.env
set +a导入:
MYSQL_PWD="$MYSQL_PASSWORD" mysql \
-h "$MYSQL_HOST" \
-P "$MYSQL_PORT" \
-u "$MYSQL_USERNAME" \
< knowledge_base_export_2026-06-23.sqlWindows PowerShell:
Get-Content ..\..\knowledge-base-go\.env |
Where-Object { $_ -match '^[^#].+=' } |
ForEach-Object {
$name, $value = $_ -split '=', 2
Set-Item -Path "Env:$name" -Value $value
}
Get-Content knowledge_base_export_2026-06-23.sql |
mysql -h $env:MYSQL_HOST -P $env:MYSQL_PORT -u $env:MYSQL_USERNAME --password=$env:MYSQL_PASSWORD全量文件包含 DROP TABLE,只能用于全新的本地数据库。已有数据库不要直接执行,否则可能覆盖现有数据。3.3 确认数据库
MYSQL_PWD="$MYSQL_PASSWORD" mysql \
-h "$MYSQL_HOST" \
-P "$MYSQL_PORT" \
-u "$MYSQL_USERNAME" \
-e "SHOW DATABASES LIKE 'kb_%';"确认关键表:
MYSQL_PWD="$MYSQL_PASSWORD" mysql \
-h "$MYSQL_HOST" \
-P "$MYSQL_PORT" \
-u "$MYSQL_USERNAME" \
-e "SHOW TABLES FROM kb_user; SHOW TABLES FROM kb_document;"默认测试账号以导入 SQL 为准:
| 用户名 | 密码 |
|---|---|
| admin | admin123 |
| developer | admin123 |
| editor | admin123 |
如果当前数据库修改过密码,请使用实际密码登录。
4. 项目配置
4.1 检查 .env
进入 Go 项目:
cd ../../knowledge-base-go
ls -l .env当前项目已经有 .env,直接使用,不要用 .env.example 覆盖。
如果 .env 丢失,才执行:
cp .env.example .env复制后必须补充 Redis、MongoDB、RustFS 等服务的真实账号和密码。
4.2 服务端口
SERVER_PORT=8080
SERVER_MODE=debugGo 后端默认使用 8080。
Java 网关也默认使用 8080。如果两边需要同时运行,将 Go 改为:
SERVER_PORT=180804.3 MySQL
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USERNAME=root
MYSQL_PASSWORD=123456如果修改了本地 MySQL 密码,需要同步修改 .env。
5. 中间件配置
5.1 Redis(必须,远程连接)
- 远程地址:
117.72.88.11:6379 - 密码:
susan123 - 数据库编号:
2
Redis 已部署在远程服务器上,本地无需安装。如果你的网络无法连接远程 Redis,可以在本地安装 Redis 并修改所有模块的application.yml中的spring.data.redis.host为localhost。
5.2 Nacos(必须,远程连接)
- 远程地址:
117.72.88.11:8848 - 命名空间:
knowledge - 账户:
nacos/susan123
Nacos 用于服务注册发现和配置管理。所有模块启动时会自动注册到 Nacos。本地无需安装 Nacos。
5.3 Elasticsearch(可选,远程连接)
- 远程地址:
117.72.88.11:9200 - 账户:
elastic/susan123
搜索服务(kb-search)需要 Elasticsearch。如果不使用搜索功能,可以暂时不启动 kb-search 服务。
5.4 RabbitMQ(可选,远程连接)
- 远程地址:
117.72.88.11:5672 - 账户:
admin/susan123
用于服务间的异步消息通信。部分模块(如 kb-ai、kb-search)会使用 RabbitMQ。
5.5 大模型(可选,远程API调用)
系统的 AI 助手、AI 写作、知识图谱(RAG + KAG)等功能需要大模型支持。
目前配置了两种大模型:
| 模型 | API地址 | 说明 |
|---|---|---|
| 通义千问(Qwen) | https://dashscope.aliyuncs.com/compatible-mode/v1 | 默认模型,同时用于 Embedding 和 Chat |
| DeepSeek | https://api.deepseek.com/v1 | 备选模型,仅用于 Chat |
大模型通过远程 API 调用,本地无需安装任何模型运行环境,只需要有可用的 API Key。
5.5.1 获取 API Key
通义千问(推荐):
- 访问 阿里云百炼平台
- 注册/登录阿里云账号
- 进入「模型广场」→ 选择「通义千问-Max」→ 点击「API调用」
- 在「API Key」页面创建新的 API Key
- 复制保存 API Key
DeepSeek(备选):
- 访问 DeepSeek 开放平台
- 注册/登录账号
- 进入「API Keys」页面创建新的 API Key
- 复制保存 API Key
5.5.2 配置 API Key
在使用 AI 功能的 IDE 中设置环境变量(IDEA → Run/Debug Configurations → Environment variables):
# 通义千问(必填,至少配置一个)
QWEN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# DeepSeek(可选,备选模型)
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5.5.3 AI 相关配置说明
kb-ai 模块的 application.yml 中的关键配置:
# 通义千问配置
qwen:
api-key: ${QWEN_API_KEY:} # 从环境变量读取
base-url: ${QWEN_BASE_URL:https://dashscope.aliyuncs.com/compatible-mode/v1}
chat:
options:
model: ${QWEN_MODEL:qwen3-max} # 模型名称
temperature: 0.3 # 创造性控制(0-1)
max-tokens: 4000 # 单次最大输出token数
# DeepSeek 配置
deepseek:
api-key: ${DEEPSEEK_API_KEY:}
model: deepseek-chat
base-url: https://api.deepseek.com/v1
max-tokens: 4096
temperature: 0.7
# 默认使用的模型
ai:
default-model: qwen # qwen 或 deepseek
# RAG 检索增强配置
rag:
enabled: ${RAG_ENABLED:true} # 是否启用RAG
chunking:
chunk-size: ${RAG_CHUNK_SIZE:512} # 文档分块大小
chunk-overlap: ${RAG_CHUNK_OVERLAP:64} # 分块重叠大小
embedding:
model: ${RAG_EMBEDDING_MODEL:text-embedding-v3} # Embedding模型
dimension: 1024
retrieval:
default-top-k: 5 # 默认返回Top-K文档
# KAG 知识增强配置
kag:
enabled: ${KAG_ENABLED:true} # 是否启用KAG
extraction:
model: qwen # 实体关系抽取模型
max-entities-per-chunk: 10
max-relations-per-chunk: 15
graph:
database: neo4j # 知识图谱存储提示:如果不配置 API Key,AI 相关功能(AI助手、AI写作、知识图谱)将不可用,但不影响文档管理、用户认证等其他核心功能。启动时会输出 warn 日志,可以安全忽略。
5.5.4 模型切换
系统默认使用通义千问(Qwen),如需切换到 DeepSeek:
ai:
default-model: deepseek或在启动时通过环境变量覆盖:AI_DEFAULT_MODEL=deepseek。
5.6 邮件(可选)
系统的注册账号邮件激活、密码重置验证码等功能需要邮件服务。
5.6.1 获取 SMTP 授权码
系统默认使用 163邮箱 SMTP 服务:
- 登录 mail.163.com
- 点击「设置」→「POP3/SMTP/IMAP」
- 开启「SMTP服务」(IMAP/SMTP服务 或 POP3/SMTP服务)
- 按提示发送短信验证后,获取授权码(非邮箱登录密码)
- 复制保存授权码
也可以使用 QQ邮箱(smtp.qq.com,端口 465)或其他支持 SMTP 的邮箱服务。
5.6.2 配置邮件参数
在 IDEA 中设置环境变量(Run/Debug Configurations → Environment variables):
# 邮件发送账号(163邮箱地址)
MAIL_USERNAME=your_email@163.com
# SMTP授权码(非邮箱密码)
MAIL_PASSWORD=XXXXXXXXXXXX或者直接修改 kb-user-auth 模块的 application.yml:
spring:
mail:
host: ${MAIL_HOST:smtp.163.com}
port: ${MAIL_PORT:465}
username: ${MAIL_USERNAME:your_email@163.com} # 你的163邮箱
password: ${MAIL_PASSWORD:XXXXXXXXXXXX} # 你的SMTP授权码
properties:
mail:
smtp:
auth: true
ssl:
enable: true5.6.3 使用其他邮箱服务
QQ邮箱:
spring:
mail:
host: smtp.qq.com
port: 465
username: your_email@qq.com
password: XXXXXXXXXXXX # QQ邮箱SMTP授权码企业微信邮箱:
spring:
mail:
host: smtp.exmail.qq.com
port: 465
username: your_email@company.com
password: XXXXXXXXXXXX提示:如果不配置邮件,注册功能仍然可以正常使用,只是用户注册后不会收到激活邮件,需要管理员在后台手动激活账号。密码重置功能将不可用。
6. 启动后端
6.1 下载依赖
cd ~/projects/enterprise-knowledge-base/knowledge-base-go
go mod download国内网络较慢时:
go env -w GOPROXY=https://goproxy.cn,direct
go mod download6.2 编译和检查
go build ./...
go vet ./...
go test ./...当前项目这三个命令均已实际执行并通过。
6.3 查看接口路由
go run ./cmd/routedump当前输出:
TOTAL ROUTES: 2896.4 启动
macOS / Linux:
chmod +x run.sh
./run.shWindows:
run.batrun.sh 会自动:
- 定位 Go。
- 设置 GOPROXY。
- 加载
.env。 - 检查端口。
- 执行
go run ./cmd/server。
看到以下日志表示启动成功:
知识库 Go 后端启动中,监听 :80806.5 与 Java 后端同时运行
SERVER_PORT=18080 ./run.sh此时 Go 后端地址为:
http://localhost:18080不要将 Go 后端和 Java 网关同时设置为 8080。
6.6 不经过启动脚本
go run ./cmd/server指定端口:
SERVER_PORT=18080 go run ./cmd/server6.7 启动检查
curl http://localhost:8080/health正常返回:
{"status":"UP"}如果使用 18080:
curl http://localhost:18080/health7. 在 IDEA 中运行
7.1 打开项目
使用 IDEA 或 GoLand 打开:
enterprise-knowledge-base/knowledge-base-go不要打开整个仓库根目录。
7.2 配置 Go SDK
Settings → Languages & Frameworks → Go → GOROOT,选择本机 Go 安装目录。
在 Go Modules 中确认 GOPROXY:
https://goproxy.cn,direct7.3 使用项目已有运行配置
项目已有:
.run/kb-go-server (脚本 run.sh)在右上角运行配置中选择该项即可。
7.4 手动配置
| 参数 | 值 |
|---|---|
| Run kind | Package |
| Package path | knowledgebase/cmd/server |
| Working directory | project/knowledge-base-go |
| Environment | 加载 .env |
入口:
cmd/server/main.go8. 启动前端
进入前端项目:
cd ../knowledge-base-frontend安装依赖:
npm install启动:
npm run dev终端会显示:
http://localhost:3002/前端 /api 代理需要指向当前后端:
- Java 网关:
http://localhost:8080 - Go 后端:
http://localhost:8080 - Go 使用其他端口:
http://localhost:18080
不要同时启动两个占用 8080 的后端。
9. 访问系统
浏览器访问:
http://localhost:3002登录页:
http://localhost:3002/login登录页面:http://localhost:3002/login

账号:admin 密码:123456
登录成功之后,主页面如下:

如果数据库初始化时使用过其他密码,以实际数据库为准。
主要页面:
| 页面 | 地址 |
|---|---|
| 首页 | /dashboard |
| 文档中心 | /documents |
| AI 助手 | /ai |
| AI 写作 | /ai-writing |
| 知识图谱 | /knowledge-graph |
| 文件管理 | /files |
| 最近访问 | /recent-access |
| 系统管理 | /admin |
Go 后端不提供 Java Knife4j 页面。接口检查使用:
go run ./cmd/routedump或直接调用 /health、登录和业务接口。
10. 常用启动命令
# Go 依赖和检查
go mod download
go build ./...
go vet ./...
go test ./...
# 路由
go run ./cmd/routedump
# 启动
./run.sh
# 使用 18080
SERVER_PORT=18080 ./run.sh
# 停止 Go
./run.sh stop