Home-Vue-Go/BUILD.md

构建说明

本项目支持打包为单一可执行文件，包含前后端。启动后通过一个端口同时提供前端、API和上传文件，默认端口为 1552。

所有前端文件已嵌入到二进制文件中，无需额外文件。

构建方式

使用 Makefile（推荐）

本项目使用 Makefile 进行跨平台构建，支持 Windows、Linux 和 macOS。

前置要求：

• 安装 Node.js 和 npm
• 安装 Go 1.23+
• 安装 make 工具
  • Windows: 可通过 Git for Windows、Chocolatey 或 WSL 安装
  • Linux/macOS: 通常已预装

Windows 上使用 Make

如果你安装了 Git for Windows，make 工具通常已经包含在内，但可能不在 PATH 中。

方式1：将 Git 的 make 添加到 PATH

1. 找到 Git 安装目录（通常是 C:\Program Files\Git）
2. 将 C:\Program Files\Git\usr\bin 添加到系统 PATH 环境变量
3. 重启终端后即可直接使用 make 命令

方式2：使用 Chocolatey 安装 make

choco install make

方式3：使用 WSL 在 WSL 中运行 make 命令。

构建命令

构建全部平台版本（默认）

make build

该命令会生成 Windows、Linux 和 macOS 的 amd64 可执行文件。

构建 Linux 版本（用于服务器部署）

make build-linux

构建 Windows 版本

make build-windows

构建 macOS 版本

make build-darwin

其他 Makefile 命令

只构建前端：

make frontend

只构建后端（当前平台）：

make backend

只构建后端（指定平台）：

make backend-linux    # Linux
make backend-windows  # Windows
make backend-darwin   # macOS

生成 Ent 代码（仅修改 Schema 后需要）：

make generate

清理构建文件：

make clean

运行开发服务器：

make run

构建输出

执行 make build 后，dist 目录将包含三个平台包：

dist/
├── home-vue-go-windows-amd64.exe
├── home-vue-go-linux-amd64
└── home-vue-go-darwin-amd64

所有前端文件（HTML、CSS、JavaScript等）都会分别嵌入三个二进制文件中，构建脚本会自动清理 dist 中的前端源文件。

运行服务器

Windows

cd dist
home-vue-go.exe

Linux/macOS

cd dist
./home-vue-go

访问地址

启动后，服务器通过统一端点提供完整服务：

• 访问端点: http://localhost:1552
  • 主页：http://localhost:1552
  • 管理界面：http://localhost:1552/admin
  • 登录页面：http://localhost:1552/login
  • API接口：http://localhost:1552/api

1Panel 配置

在1Panel中配置非常简单：

1. 上传文件：将 home-vue-go（Linux版本）上传到服务器

2. 配置端口：只需放行统一服务端口 1552

3. 运行命令：

   ./home-vue-go
   

4. 完成：无需其他配置，单一文件即可运行完整服务

配置说明

• 统一服务端口：默认 1552，可通过环境变量 PORT 修改
• 数据目录：运行时会自动在二进制文件同目录下创建 data 目录
• 默认管理员账号：admin / admin123（首次启动时显示）

修改端口示例

Windows:

set PORT=8080
home-vue-go.exe

Linux/macOS:

export PORT=8080
./home-vue-go

注意事项

1. SQLite驱动：使用纯 Go SQLite 驱动，构建无需 CGO 或 GCC
2. 前端构建：构建时必须先运行 npm run build 生成dist目录，Go编译时会嵌入这些文件
3. Go版本：需要Go 1.23或更高版本（支持embed功能）
4. 端口占用：确保统一服务端口（默认1552）未被占用
5. 单一文件：构建完成后，只需一个可执行文件即可运行，无需其他依赖
6. Make工具：Windows用户需要安装make工具（Git for Windows自带，或使用Chocolatey安装）
7. 跨平台编译：Windows、Linux 和 macOS amd64 目标均可直接交叉编译

Windows 上使用 Make

方式1：将 Git 的 make 添加到 PATH（推荐）

Git for Windows 自带 make 工具，通常位于：

• C:\Program Files\Git\usr\bin\make.exe
• C:\Program Files (x86)\Git\usr\bin\make.exe

添加步骤：

1. 右键"此电脑" → "属性" → "高级系统设置" → "环境变量"
2. 在"系统变量"中找到 Path，点击"编辑"
3. 添加 Git 的 bin 目录：C:\Program Files\Git\usr\bin
4. 点击"确定"保存
5. 重启终端后即可直接使用 make 命令

方式2：使用 Chocolatey 安装 make

choco install make

方式3：使用 WSL

在 WSL 中运行 make 命令。

方式4：手动下载 make for Windows

从 https://sourceforge.net/projects/gnuwin32/files/make/ 下载并安装

架构说明

单一可执行文件架构

┌─────────────────────────────────┐
│   home-vue-go (单一可执行文件)   │
│   包含: 后端代码 + 前端文件(嵌入) │
├─────────────────────────────────┤
│                                  │
│                                  │
│        统一 HTTP 服务 :1552       │
│   /api  /uploads  /assets  SPA   │
└─────────────────────────────────┘

• 统一服务（1552）：直接提供 API、上传文件、嵌入的前端静态文件和 SPA 路由

完整构建流程示例

在 Windows 上构建 Linux 版本（用于1Panel）

方式1：使用WSL（推荐）

前提条件： 确保WSL中已安装Go和Node.js

安装Go（如果未安装）：

# 在WSL中运行
# 下载Go（替换版本号为最新版本，当前需要Go 1.23+）
wget https://go.dev/dl/go1.23.0.linux-amd64.tar.gz

# 删除旧版本（如果存在）
sudo rm -rf /usr/local/go

# 解压到/usr/local
sudo tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz

# 添加到PATH（添加到~/.bashrc或~/.zshrc）
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# 验证安装
go version

安装Node.js（如果未安装）：

# 使用nvm安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

# 或使用apt安装
sudo apt update
sudo apt install nodejs npm

构建步骤：

# 在WSL中运行（不需要再运行wsl命令，如果已经在WSL中）
cd /mnt/d/Desktop/Home-Vue-go
make build-linux
# 构建完成后，dist/home-vue-go 就是Linux可执行文件

方式2：直接在 Windows 上交叉构建

make build-linux

方式3：在Linux服务器上直接构建（最简单，推荐）

这是最推荐的方式，无需交叉编译工具链，构建速度快且稳定。

前提条件：

• Linux服务器已安装 Go 1.23+ 和 Node.js 16.16.0+
• 已安装 make 工具（通常已预装）

构建步骤：

# 1. 克隆项目到服务器
git clone <your-repo>
cd Home-Vue-go

# 2. 确保环境已安装（如果未安装）
# 安装Go（示例，根据你的发行版调整）
# wget https://go.dev/dl/go1.23.0.linux-amd64.tar.gz
# sudo tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz
# echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
# source ~/.bashrc

# 安装Node.js（示例，使用nvm）
# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# source ~/.bashrc
# nvm install 18

# 3. 构建Linux版本
make build-linux

# 4. 构建完成后，可执行文件位于 dist/home-vue-go
# 可以直接运行，或配置到1Panel
./dist/home-vue-go

1Panel配置：

• 运行命令：./home-vue-go（或完整路径）
• 端口映射：1552（统一服务端口）
• 工作目录：可执行文件所在目录

注意：SQLite 使用纯 Go 驱动，因此从 Windows 交叉构建 Linux 版本不需要额外的 C 工具链。

在 Linux 上构建 Windows 版本

make build-windows
# 输出: dist/home-vue-go.exe

在 macOS 上构建 Linux 版本

make build-linux
# 输出: dist/home-vue-go

清理构建文件

make clean

这会删除：

• dist/ 目录
• node_modules/ 目录
• 可执行文件

开发模式

开发时，可以分别运行前后端：

终端1 - 统一服务：

make run
# 前端和 API 均运行在 http://localhost:1552

终端2 - 前端：

npm run dev
# 热更新页面运行在 http://localhost:5173，API代理到统一服务端口

部署优势

✅ 单一可执行文件：前后端一体化，所有文件嵌入在二进制中
✅ 无需依赖：不需要Node.js、npm或其他运行时
✅ 单端口服务：前端、API和上传文件共用一个端口 ✅ 1Panel友好：只需配置一个端口，运行一个命令即可 ✅ 部署简单：上传一个文件，配置端口，即可运行
✅ 跨平台构建：使用make统一构建流程，支持多平台