server/docs/BUILD.md

部署文档

编译

本地编译（当前平台）

# 生产环境推荐使用静态编译
go build --ldflags "-extldflags -static -s -w" -o main .

Linux 服务器交叉编译（Windows/Mac 编译 Linux 版本）

# Windows PowerShell:
$env:CGO_ENABLED="0"; $env:GOOS="linux"; $env:GOARCH="amd64"; go build --ldflags "-extldflags -static -s -w" -o main .

# Windows CMD (需要分开执行):
set GOOS=linux
set GOARCH=amd64
go build --ldflags "-extldflags -static -s -w" -o main .
SET GOOS=windows
SET GOARCH=amd64

# Linux/Mac:
GOOS=linux GOARCH=amd64 go build --ldflags "-extldflags -static -s -w" -o main .

重要提示：

• 如果在 Windows 上编译，但要在 Linux 服务器上运行，必须使用交叉编译
• 使用 GOOS=linux GOARCH=amd64 指定目标平台
• 如果服务器是 ARM 架构，使用 GOARCH=arm64
• 推荐使用静态编译：添加 --ldflags "-extldflags -static -s -w" 参数，生成独立可执行文件

---

方案一：单服务部署（端口 3000）

步骤 1：准备部署文件

在服务器上创建应用目录并上传必要文件：

# 在服务器上创建应用目录
sudo mkdir -p /www/goravel-admin
sudo chown -R www-data:www-data /www/goravel-admin

# 上传二进制文件
scp main user@server:/www/goravel-admin/

# 上传配置文件和其他必要文件
scp .env user@server:/www/goravel-admin/.env
scp -r storage/ user@server:/www/goravel-admin/
scp -r resources/ user@server:/www/goravel-admin/
scp -r public/ user@server:/www/goravel-admin/

步骤 2：配置 systemd 服务

# 上传服务文件
scp scripts/systemd/goravel-admin-3000.service user@server:/tmp/

# 在服务器上安装服务文件
sudo cp /tmp/goravel-admin-3000.service /etc/systemd/system/goravel-admin.service
sudo systemctl daemon-reload

编辑服务文件，根据实际情况修改路径和用户：

sudo nano /etc/systemd/system/goravel-admin.service

主要配置项：

• User 和 Group：运行服务的用户和组（如 www-data）
• WorkingDirectory：应用工作目录（如 /www/goravel-admin）
• ExecStart：二进制文件路径（如 /www/goravel-admin/main）
• ReadWritePaths：需要写入权限的目录（如 /www/goravel-admin/storage）

步骤 3：设置文件权限

# 设置二进制文件权限
sudo chmod +x /www/goravel-admin/main

# 设置存储目录权限
sudo chmod -R 775 /www/goravel-admin/storage
sudo chown -R www-data:www-data /www/goravel-admin/storage

# 设置配置文件权限（保护敏感信息）
sudo chmod 600 /www/goravel-admin/.env
sudo chown www-data:www-data /www/goravel-admin/.env

步骤 4：初始化应用

# 生成应用密钥
cd /www/goravel-admin
./main artisan key:generate

# 数据库迁移
./main artisan migrate

# 数据库填充（可选）
./main artisan db:seed

步骤 5：启动和管理服务

# 启动服务
sudo systemctl start goravel-admin

# 设置开机自启
sudo systemctl enable goravel-admin

# 查看服务状态
sudo systemctl status goravel-admin

# 停止服务
sudo systemctl stop goravel-admin

# 重启服务（⚠️ 会有短暂中断 1-3 秒）
sudo systemctl restart goravel-admin

步骤 6：查看日志

# 实时查看日志
sudo journalctl -u goravel-admin -f

# 查看最近 100 行日志
sudo journalctl -u goravel-admin -n 100

# 查看今天的日志
sudo journalctl -u goravel-admin --since today

步骤 7：验证部署

# 检查服务是否运行
sudo systemctl is-active goravel-admin

# 检查端口是否监听
sudo netstat -tlnp | grep 3000
# 或使用 ss 命令
sudo ss -tlnp | grep 3000

配置外部访问

如果无法从外部 IP 访问，需要修改 .env 文件：

# 修改为 0.0.0.0 允许所有网络接口访问
APP_HOST=0.0.0.0
APP_PORT=3000

然后重启服务：

sudo systemctl restart goravel-admin

检查防火墙设置：

# CentOS/RHEL 系统
sudo firewall-cmd --list-ports
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

# Ubuntu/Debian 系统
sudo ufw status
sudo ufw allow 3000/tcp
sudo ufw reload

---

方案二：双目录双端口零停机部署（蓝绿部署 + Nginx 切换）⭐ 推荐

这是生产环境最可靠的零停机部署方案，通过双目录双端口 + Nginx 切换实现真正的零停机。

工作原理

• 使用两个版本目录：v1（端口 3000）和 v2（端口 3001）
• 两个实例可以同时运行
• Nginx 负载均衡在两个端口之间切换
• 部署新版本时：
  1. 部署新版本到备用目录（如 v2，端口 3001）
  2. 启动新版本服务
  3. 健康检查通过后，Nginx 切换流量到新端口
  4. 停止旧版本服务
  5. 实现真正的零停机，且可以快速回滚

目录结构

/www/goravel-admin/
├── v1/                    # 版本 1 目录（端口 3000）
│   ├── main              # 可执行文件
│   ├── .env              # 配置文件（APP_PORT=3000）
│   ├── storage/          # 存储目录
│   └── ...
└── v2/                    # 版本 2 目录（端口 3001）
    ├── main              # 可执行文件
    ├── .env              # 配置文件（APP_PORT=3001）
    ├── storage/          # 存储目录
    └── ...

步骤 1：准备部署文件

在服务器上创建应用目录结构：

# 在服务器上创建应用目录
sudo mkdir -p /www/goravel-admin/{v1,v2}
sudo chown -R www-data:www-data /www/goravel-admin

# 上传第一个版本到 v1 目录
scp main user@server:/www/goravel-admin/v1/
scp .env user@server:/www/goravel-admin/v1/.env
scp -r storage/ user@server:/www/goravel-admin/v1/
scp -r resources/ user@server:/www/goravel-admin/v1/
scp -r public/ user@server:/www/goravel-admin/v1/

重要提示：.env 文件配置

• 每个版本目录（v1、v2）都有独立的 .env 文件
• v1 目录的 .env 文件中配置 APP_PORT=3000
• v2 目录的 .env 文件中配置 APP_PORT=3001
• 其他配置（如数据库连接）可以不同版本不同配置

步骤 2：配置双实例 systemd 服务

项目已提供两个服务文件：

• scripts/systemd/goravel-admin-v1.service - v1 目录，端口 3000
• scripts/systemd/goravel-admin-v2.service - v2 目录，端口 3001

服务文件特点：

• WorkingDirectory=/www/goravel-admin/v1 或 /www/goravel-admin/v2
• ExecStart=/www/goravel-admin/v1/main 或 /www/goravel-admin/v2/main
• 端口由各自目录的 .env 文件中的 APP_PORT 配置管理

在服务器上安装：

# 上传服务文件
scp scripts/systemd/goravel-admin-v1.service user@server:/tmp/
scp scripts/systemd/goravel-admin-v2.service user@server:/tmp/

# 在服务器上安装
sudo cp /tmp/goravel-admin-v1.service /etc/systemd/system/
sudo cp /tmp/goravel-admin-v2.service /etc/systemd/system/
sudo systemctl daemon-reload

编辑服务文件，根据实际情况修改路径和用户：

sudo nano /etc/systemd/system/goravel-admin-v1.service
sudo nano /etc/systemd/system/goravel-admin-v2.service

主要配置项：

• User 和 Group：运行服务的用户和组（如 www-data）
• WorkingDirectory：应用工作目录（如 /www/goravel-admin/v1 或 /www/goravel-admin/v2）
• ExecStart：二进制文件路径（如 /www/goravel-admin/v1/main 或 /www/goravel-admin/v2/main）
• ReadWritePaths：需要写入权限的目录（如 /www/goravel-admin/v1/storage 或 /www/goravel-admin/v2/storage）

步骤 3：设置文件权限

# 设置 v1 目录权限
sudo chmod +x /www/goravel-admin/v1/main
sudo chmod -R 775 /www/goravel-admin/v1/storage
sudo chown -R www-data:www-data /www/goravel-admin/v1/storage
sudo chmod 600 /www/goravel-admin/v1/.env
sudo chown www-data:www-data /www/goravel-admin/v1/.env

# 设置 v2 目录权限（如果已上传）
sudo chmod +x /www/goravel-admin/v2/main 2>/dev/null || true
sudo chmod -R 775 /www/goravel-admin/v2/storage 2>/dev/null || true
sudo chown -R www-data:www-data /www/goravel-admin/v2/storage 2>/dev/null || true
sudo chmod 600 /www/goravel-admin/v2/.env 2>/dev/null || true
sudo chown www-data:www-data /www/goravel-admin/v2/.env 2>/dev/null || true

步骤 4：初始化应用

# 生成应用密钥（在 v1 目录）
cd /www/goravel-admin/v1
./main artisan key:generate

# 数据库迁移
./main artisan migrate

# 数据库填充（可选）
./main artisan db:seed

# 试运行
./main

步骤 5：配置 Nginx 负载均衡

项目已提供 Nginx 配置文件：scripts/nginx/goravel-admin.conf

在服务器上安装：

# 上传 Nginx 配置
scp scripts/nginx/goravel-admin.conf user@server:/tmp/

# 在服务器上安装
sudo cp /tmp/goravel-admin.conf /etc/nginx/sites-available/goravel-admin
sudo ln -s /etc/nginx/sites-available/goravel-admin /etc/nginx/sites-enabled/
sudo nginx -t
sudo nginx -s reload

Nginx 配置说明： nginx.conf 参考 编辑 /etc/nginx/sites-available/goravel-admin，修改 server_name 为你的域名：

步骤 6：启动第一个实例

# 启动 v1 实例（端口 3000）
sudo systemctl start goravel-admin-v1
# 开机自启
sudo systemctl enable goravel-admin-v1

# 检查状态
sudo systemctl status goravel-admin-v1

查看日志

# 查看 v1 服务日志
sudo journalctl -u goravel-admin-v1 -f

# 查看 v2 服务日志
sudo journalctl -u goravel-admin-v2 -f

# 查看最近 100 行日志
sudo journalctl -u goravel-admin-v1 -n 100
sudo journalctl -u goravel-admin-v2 -n 100

验证部署

# 检查服务状态
sudo systemctl status goravel-admin-v1
sudo systemctl status goravel-admin-v2

# 检查端口监听
sudo ss -tlnp | grep 3000
sudo ss -tlnp | grep 3001

（蓝绿部署 + Nginx 切换）

# 启动服务
sudo systemctl start goravel-admin-v1
sudo systemctl start goravel-admin-v2

# 停止服务
sudo systemctl stop goravel-admin-v1
sudo systemctl stop goravel-admin-v2

# 重启服务
sudo systemctl restart goravel-admin-v1
sudo systemctl restart goravel-admin-v2


# 查看状态
sudo systemctl status goravel-admin-v1
sudo systemctl status goravel-admin-v2

# 查看日志
sudo journalctl -u goravel-admin-v1 -f
sudo journalctl -u goravel-admin-v2 -f

# 设置开机自启
sudo systemctl enable goravel-admin-v1
sudo systemctl enable goravel-admin-v2

# 检查端口监听
sudo ss -tlnp | grep 3000
sudo ss -tlnp | grep 3001

清理所有服务

# 停止所有服务
sudo systemctl stop goravel-admin-v1 goravel-admin-v2 2>/dev/null

# 禁用所有服务
sudo systemctl disable goravel-admin-v1 goravel-admin-v2 2>/dev/null

# 删除服务文件
sudo rm -f /etc/systemd/system/goravel-admin*.service

# 重新加载 systemd
sudo systemctl daemon-reload

# 重置失败状态
sudo systemctl reset-failed goravel-admin* 2>/dev/null

# 如果还有进程在运行，强制停止
sudo pkill -f 'goravel-admin' || true
sudo pkill -f '/www/goravel-admin' || true

---

方案三：Docker Compose 蓝绿部署（零停机）⭐ 推荐容器化方案

这是使用 Docker 容器化的零停机部署方案，适合本地没有 Docker 环境，但服务器有 Docker 的场景。

工作原理

• 使用两个 Docker Compose 配置：blue（端口 3000）和 green（端口 3001）
• 两个容器可以同时运行
• 部署新版本时：
  1. 在备用环境（如 green）构建并启动新版本
  2. 健康检查通过后，切换流量到新版本
  3. 停止旧版本容器
  4. 实现真正的零停机，且可以快速回滚

前置要求

• 服务器已安装 Docker 和 Docker Compose
• 服务器可以访问 Git 仓库（或手动上传代码）
• 已配置 .env 文件

步骤 1：在服务器上初始化

# SSH 登录服务器
ssh user@your-server.com

# 创建部署目录
sudo mkdir -p /www/goravel-admin
sudo chown -R $USER:$USER /www/goravel-admin
cd /www/goravel-admin

# 克隆仓库（首次）
git clone https://github.com/your-username/goravel-admin.git .

# 或者如果已经克隆过
git pull origin main

步骤 2：配置环境变量

# 确保 .env 文件存在
cd /www/goravel-admin
cp .env.example .env  # 如果存在
# 编辑 .env 文件，设置数据库等配置
vim .env

步骤 3：执行部署

方式一：从 Git 拉取并部署（推荐）

# 设置环境变量（可选）
export GIT_REPO_URL="https://github.com/your-username/goravel-admin.git"
export GIT_BRANCH="main"
export DEPLOY_DIR="/www/goravel-admin"

# 执行部署脚本
chmod +x scripts/deploy/git-deploy.sh
./scripts/deploy/git-deploy.sh

方式二：手动部署（已拉取代码）

cd /www/goravel-admin
git pull origin main  # 拉取最新代码

# 执行部署脚本
chmod +x scripts/deploy/docker-blue-green.sh
./scripts/deploy/docker-blue-green.sh

部署流程说明

脚本会自动执行以下步骤：

1. 检测当前版本 - 自动检测运行的是 blue 还是 green
2. 构建新版本 - 在备用环境构建新 Docker 镜像
3. 启动新版本 - 启动新版本容器（使用不同端口）
4. 健康检查 - 等待新版本通过健康检查（最多 30 次，每次 2 秒）
5. 切换 Nginx 流量 - 如果存在 Nginx 配置，自动更新并重载
6. 停止旧版本 - 停止旧版本容器

查看部署状态

# 查看运行中的容器
docker ps | grep goravel-admin

# 查看容器日志
docker logs -f goravel-admin-blue
docker logs -f goravel-admin-green

# 查看容器健康状态
docker inspect --format='{{.State.Health.Status}}' goravel-admin-blue
docker inspect --format='{{.State.Health.Status}}' goravel-admin-green

回滚方案

如果需要回滚到上一个版本：

cd /www/goravel-admin

# 方式一：手动切换
# 如果当前运行的是 green，切换到 blue
docker-compose -f docker-compose.blue.yml up -d
# 然后停止 green
docker-compose -f docker-compose.green.yml down

# 方式二：使用 Git 回滚代码后重新部署
git checkout <previous-commit>
./scripts/deploy/docker-blue-green.sh

配置文件说明

• docker-compose.blue.yml - 蓝环境配置（端口 3000）
• docker-compose.green.yml - 绿环境配置（端口 3001）
• scripts/deploy/docker-blue-green.sh - 蓝绿部署主脚本
• scripts/deploy/git-deploy.sh - 从 Git 拉取并部署的脚本

健康检查

应用已配置 /health 端点（在 routes/web.go 中），用于部署时的健康检查。

故障处理

如果部署过程中健康检查失败，脚本会自动：

• 停止新版本容器
• 保持旧版本继续运行
• 退出并报告错误

本地开发流程

1. 本地开发 - 在本地修改代码（无需 Docker）
2. 提交代码 - git add . && git commit -m "更新" && git push
3. 服务器部署 - SSH 到服务器执行 ./scripts/deploy/git-deploy.sh

优势

• ✅ 零停机部署 - 新版本就绪后再切换流量
• ✅ 快速回滚 - 可以快速切换回旧版本
• ✅ 本地无需 Docker - 本地开发环境简单
• ✅ 自动化 - 一键部署脚本
• ✅ 健康检查 - 自动验证新版本是否正常

---

部署方案对比

方案	复杂度	零停机	适用场景	推荐度
单服务部署	⭐	❌	开发/测试环境	⭐⭐
蓝绿部署 + Nginx	⭐⭐⭐	✅	生产环境（非容器）	⭐⭐⭐⭐
Docker Compose 蓝绿	⭐⭐	✅	生产环境（容器化）	⭐⭐⭐⭐⭐