AI GO ADMIN 项目从零跑起来踩坑实录（Windows 环境）

最近把开源后台管理系统 AI GO ADMIN（Go + Gin + GORM + PostgreSQL 后端，Vue3 + Element Plus + Vite 前端）在本地 Windows 机器上完整跑了起来，前后端 + 数据库迁移一次成功。这里把完整流程和踩过的坑记录一下，给同样想上手的朋友参考。

项目要求

• 后端：Go ≥ 1.25（实际 go.mod 要求 1.26.x）
• 数据库：PostgreSQL
• 前端：Node.js + pnpm

我的环境：Windows 10/11，Node v22，本机已装 PostgreSQL 18（Windows 服务方式运行）。

坑一：Go 没装 / 版本不对

机器上没有 Go，直接去官网下载 zip 包解压即可，不用跑安装器：

https://golang.google.cn/dl/go1.25.4.windows-amd64.zip

解压后把 bin 目录加入 PATH。第一个坑来了：项目 go.mod 要求 go 1.26.6，而本地装的低于这个版本。其实不用重新下载，Go 1.21+ 支持自动下载工具链（GOTOOLCHAIN=auto），缺哪个版本自动拉取。

但自动下载默认走 proxy.golang.org，国内直接 Bad Gateway。解决：

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

之后 go version 会自动下载 go1.26.6 工具链，顺利通过。

坑二：别把开发环境全堆 C 盘

我习惯把 Go、模块缓存这些全部放到 D 盘，一条命令搞定：

go env -w GOPATH=D:\software\gopath
go env -w GOMODCACHE=D:\software\gopath\pkg\mod
go env -w GOCACHE=D:\software\gocache

GOPATH\bin（放 go install 装的工具）记得也加入 PATH。

另外一个小插曲：go mod tidy 过程中报过一个 Access is denied（partial 缓存文件被锁），删掉对应的 .partial 文件重新 tidy 即可。

坑三：数据库密码

项目 config/config.yaml 默认连 127.0.0.1:5432，用户 postgres，密码 123456，库名 aigo。本机 PostgreSQL 密码当然不是这个，而且我不建议改仓库里的 config.yaml（它是要入库的）。项目支持 .env.yaml 环境配置文件覆盖默认配置，且已被 gitignore，把真实密码写在这里最合适：

database:
  write:
    host: 127.0.0.1
    port: 5432
    user: postgres
    password: "你的密码"
    dbname: aigo
    sslmode: disable

然后建库：

CREATE DATABASE aigo;

坑四：pnpm 拦截构建脚本

前端 pnpm i 后报错：

ERR_PNPM_IGNORED_BUILDS
Ignored build scripts: @parcel/watcher, esbuild

pnpm 10+ 出于安全默认不执行依赖的安装脚本，需要在 pnpm-workspace.yaml（注意：不是 package.json，新版优先读这个文件）里声明白名单：

onlyBuiltDependencies:
  - '@parcel/watcher'
  - esbuild
  - vue-demi

再执行一次 pnpm i。不过实践发现 esbuild 新版其实是靠 optionalDependencies 分发平台二进制（@esbuild/win32-x64），即使不跑 postinstall 也能正常用，vite dev 不受影响。

启动

# 后端：先迁移，再启动
go run cmd/main.go migrate up
go run cmd/main.go          # 默认 8080 端口

# 后端热重载（推荐）
go install github.com/air-verse/air@latest
air                         # 项目自带 .air.toml

# 前端
cd web
pnpm i
pnpm dev                    # 1818 端口

浏览器访问 http://localhost:1818/#/admin，默认账号 admin，密码 admin888。

坑五：本机代理导致的 502

如果系统挂了代理（很多开发机都挂），curl 或某些情况下浏览器访问 localhost 会被代理劫持返回 502。命令行测试时记得：

curl --noproxy "*" http://localhost:1818/

浏览器如果访问 localhost 异常，检查代理软件的"绕过本地地址"设置。

顺便补两个 PostgreSQL 小知识

用 pgAdmin 连接后可以看到每个数据库下面有"表空间"（Tablespace）节点，默认有 pg_default 和 pg_global 两个：

• 表空间本质是"数据文件落盘目录的别名"。逻辑上的表、索引最终都要写成磁盘文件，表空间决定写到哪。
• pg_default 存所有用户库的数据（aigo 的表都在这），pg_global 存实例级共享的系统元数据。
• 日常开发完全不用动它。唯一有用的场景是把大表/大库分散到不同物理磁盘。

总结

整个流程真正卡人的只有三处：Go 工具链国内下载（goproxy.cn 解决）、pnpm 构建脚本白名单（pnpm-workspace.yaml）、数据库配置（用 .env.yaml 而不是改仓库配置）。其余都是照着 README 走即可。这类前后端分离 + 数据库迁移的开源项目，跑通一次之后，代码结构和工程化设计都值得细读——AI GO ADMIN 的泛型四层架构（handler → service → repository → model）写得很规整，后续我会再写一篇源码阅读笔记。