shumengya/mengyastore

Fork 0

Files

树萌芽 63781358b2 refactor: 重构项目结构，迁移后端至 mengyastore-backend-go，新增 Java 后端、前端功能更新及部署文档

2026-03-27 15:10:53 +08:00

9.4 KiB

Raw Blame History

萌芽小店 · 生产环境部署指南

本指南覆盖从零开始将萌芽小店完整部署到生产服务器的全部步骤，包括后端 Docker 部署与前端静态文件托管。

1. 环境要求

组件	最低版本	说明
服务器 OS	Linux (Ubuntu 22.04 / Debian 12 推荐)	也支持 CentOS / AlmaLinux
Docker	24.x	`docker --version` 确认
Docker Compose	v2.x	`docker compose version` 确认
MySQL	8.x	可使用内网 MySQL 实例
Nginx	1.20+	用于前端静态托管 + API 反向代理
Node.js（构建时）	18+	仅前端打包时需要

2. 准备 MySQL 数据库

表结构无需手动创建，后端启动时 GORM 会自动执行 AutoMigrate 建表。

2.1 创建数据库和用户

在 MySQL 服务器上执行：

CREATE DATABASE IF NOT EXISTS `mengyastore`
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'mengyastore'@'%'
  IDENTIFIED BY 'your_strong_password';

GRANT ALL PRIVILEGES ON `mengyastore`.* TO 'mengyastore'@'%';

FLUSH PRIVILEGES;

或者使用项目提供的初始化脚本：

mysql -u root -p < mengyastore-backend/init.sql

2.2 验证连接

mysql -h 192.168.1.100 -P 3306 -u mengyastore -p mengyastore
# 出现 mysql> 提示符即表示连接成功

3. 部署后端（Docker）

3.1 将代码上传到服务器

# 方式一：git clone（推荐）
git clone https://your-repo-url/mengyastore.git
cd mengyastore/mengyastore-backend

# 方式二：scp 上传
scp -r mengyastore-backend/ user@your-server:/opt/mengyastore/

3.2 创建 `config.json`

在 mengyastore-backend/ 目录下创建配置文件（此文件不会被提交到 Git，需手动创建）：

cat > /opt/mengyastore/mengyastore-backend/config.json << 'EOF'
{
  "adminToken": "your_strong_admin_token",
  "databaseDsn": "mengyastore:your_password@tcp(192.168.1.100:3306)/mengyastore?charset=utf8mb4&parseTime=True&loc=Local"
}
EOF

⚠️ adminToken 请设置为足够强的随机字符串（建议 16 位以上），这是进入管理后台的唯一凭证。

3.3 检查 `docker-compose.yml`

确认 mengyastore-backend/docker-compose.yml 中的 DATABASE_DSN 与你的生产数据库匹配：

services:
  backend:
    build:
      context: .
    container_name: mengyastore-backend
    ports:
      - "28081:8080"          # 宿主机端口:容器端口，可按需修改
    environment:
      GIN_MODE: release
      TZ: Asia/Shanghai
      DATABASE_DSN: "mengyastore:your_password@tcp(192.168.1.100:3306)/mengyastore?charset=utf8mb4&parseTime=True&loc=Local"
    volumes:
      - ./config.json:/app/config.json:ro    # 挂载配置文件（只读）
    restart: unless-stopped

DATABASE_DSN 环境变量优先级高于 config.json，两者保持一致即可。

3.4 构建并启动容器

cd /opt/mengyastore/mengyastore-backend

# 首次部署
docker compose up -d --build

# 查看启动日志
docker compose logs -f

# 预期看到：
# [DB] 数据库连接成功，表结构已同步
# 萌芽小店后端启动于 http://localhost:8080

3.5 验证后端

curl http://localhost:28081/api/health
# 应返回：{"status":"ok"}

curl http://localhost:28081/api/products
# 应返回：{"data":[...]}（空数组或商品列表）

4. 构建并部署前端

4.1 本地构建（推荐在本地完成后上传 dist）

cd mengyastore-frontend

# 安装依赖
npm install

# 生产构建
npm run build
# 输出目录：dist/

4.2 配置 API 地址

前端通过 Vite 的 VITE_API_BASE_URL 环境变量指定后端地址。如果前端与后端同域（通过 Nginx 代理），也可以不配置，默认会使用当前站点域名。

如果前后端跨域，在 mengyastore-frontend/ 目录创建 .env.production：

VITE_API_BASE_URL=https://store.api.shumengya.top

然后重新 npm run build。

4.3 上传 dist 到服务器

# 假设静态文件托管在 /var/www/mengyastore/
scp -r dist/* user@your-server:/var/www/mengyastore/

# 或使用 rsync（增量同步更快）
rsync -avz --delete dist/ user@your-server:/var/www/mengyastore/

5. Nginx 反向代理配置

5.1 安装 Nginx

# Ubuntu / Debian
sudo apt update && sudo apt install -y nginx

# CentOS / AlmaLinux
sudo yum install -y nginx

5.2 创建站点配置

sudo nano /etc/nginx/sites-available/mengyastore

写入以下内容（替换 your-domain.com 为你的实际域名）：

server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    root /var/www/mengyastore;
    index index.html;

    # Vue Router History 模式：所有路由回退到 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 反向代理后端 API
    location /api/ {
        proxy_pass http://127.0.0.1:28081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 30s;
        proxy_read_timeout 60s;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2|webmanifest)$ {
        expires 7d;
        add_header Cache-Control "public, immutable";
    }
}

5.3 启用配置并重启

sudo ln -s /etc/nginx/sites-available/mengyastore /etc/nginx/sites-enabled/
sudo nginx -t          # 测试配置语法
sudo systemctl reload nginx

5.4 （可选）配置 HTTPS（Let's Encrypt）

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
# 按提示操作，certbot 会自动修改 Nginx 配置并续签证书

6. 验证部署

6.1 检查列表

https://your-domain.com 能正常打开首页
商品列表加载正常（若为空请先登录后台添加商品）
登录 SproutGate 账号后，收藏夹/聊天等功能正常
Logo 点击 5 次弹出管理员登录框，输入 adminToken 能进入后台
后台可以新建/编辑/删除商品
下单流程（自动发货）能正常获取卡密
PWA：在 Chrome 地址栏点击安装图标，可添加到桌面

6.2 后端日志查看

docker compose -f /opt/mengyastore/mengyastore-backend/docker-compose.yml logs -f

7. 常见问题排查

问题：前端白屏 / 控制台报 CORS 错误

原因：Nginx 未正确代理 /api/ 请求，或后端未启动。

排查：

curl http://127.0.0.1:28081/api/health
docker compose ps   # 确认容器正在运行

问题：管理员登录失败（"验证失败，无法连接服务器"）

原因：后端容器未运行，或 Nginx /api/ 代理配置有误。

排查：

docker compose ps
curl http://127.0.0.1:28081/api/health

问题：管理员登录失败（"令牌错误，请重试"）

原因：输入的令牌与 config.json 中的 adminToken 不一致。

排查：检查服务器上的 config.json：

cat /opt/mengyastore/mengyastore-backend/config.json

问题：商品列表为空

原因：数据库为空，需要通过管理后台添加商品。

步骤：

登录管理后台
点击"商品管理" → "新增商品"
填写商品名称、价格、卡密（自动发货）或选择手动发货模式

问题：数据库连接失败（启动时报错）

原因：DATABASE_DSN 配置错误，或 MySQL 服务不可达。

排查：

# 在宿主机上测试数据库连接
mysql -h 192.168.1.100 -P 3306 -u mengyastore -p

# 查看后端详细日志
docker compose logs backend | head -50

问题：`record not found` 日志警告

说明：这是 GORM 的正常行为，表示某些站点设置（如维护模式）在数据库中尚未有记录。不影响功能，首次设置后会自动写入。

8. 升级与回滚

升级

cd /opt/mengyastore/mengyastore-backend

# 拉取最新代码（如果使用 git）
git pull

# 重新构建并重启
docker compose up -d --build

# 查看新版本日志
docker compose logs -f

回滚

# 查看历史镜像
docker images | grep mengyastore

# 停止当前容器，启动旧版本
docker compose down
docker tag mengyastore-backend-backend:previous mengyastore-backend-backend:latest
docker compose up -d

附：目录结构参考

/opt/mengyastore/
  mengyastore-backend/
    config.json          ← 生产配置（不要提交到 Git！）
    docker-compose.yml
    Dockerfile
    ...（Go 源码）

/var/www/mengyastore/    ← 前端 dist 文件
  index.html
  assets/
  ...

如遇到本指南未覆盖的问题，请查看后端实时日志：
docker compose -f /opt/mengyastore/mengyastore-backend/docker-compose.yml logs -f

部署完成 🎉 访问 https://your-domain.com 即可看到萌芽小店正式上线。

9.4 KiB Raw Blame History Unescape Escape