random-api-go/DOCKER_DEPLOYMENT.md

Docker 部署说明

概述

本项目现在使用单一Docker镜像部署，包含前端（Next.js）和后端（Go）。前端被构建为静态文件并由后端服务器提供服务。

架构变更

之前的架构

• 前端：独立的Next.js开发服务器
• 后端：Go API服务器
• 部署：需要分别处理前后端

现在的架构

• 前端：构建为静态文件（Next.js export）
• 后端：Go服务器同时提供API和静态文件服务
• 部署：单一Docker镜像包含完整应用

构建流程

多阶段Docker构建

1. 前端构建阶段

   FROM node:20-alpine AS frontend-builder
   # 安装依赖并构建前端静态文件
   RUN npm run build
   

2. 后端构建阶段

   FROM golang:1.23-alpine AS backend-builder
   # 构建Go二进制文件
   RUN go build -o random-api .
   

3. 运行阶段

   FROM alpine:latest
   # 复制后端二进制文件和前端静态文件
   COPY --from=backend-builder /app/random-api .
   COPY --from=frontend-builder /app/web/out ./web/out
   

路由处理

静态文件优先级

后端路由器现在按以下优先级处理请求：

1. API路径 (/api/*) → 后端API处理器
2. 静态文件 (包含文件扩展名) → 静态文件服务
3. 前端路由 (/, /admin/*) → 返回index.html
4. 动态API端点 (其他路径) → 后端API处理器

路由判断逻辑

func (r *Router) shouldServeStatic(path string) bool {
    // API路径不由静态文件处理
    if strings.HasPrefix(path, "/api/") {
        return false
    }
    
    // 根路径和前端路由
    if path == "/" || strings.HasPrefix(path, "/admin") {
        return true
    }
    
    // 静态资源文件
    if r.hasFileExtension(path) {
        return true
    }
    
    return false
}

部署配置

GitHub Actions

• 自动构建多架构镜像 (amd64/arm64)
• 推送到Docker Hub
• 自动部署到服务器

Docker Compose

services:
  random-api-go:
    container_name: random-api-go
    image: woodchen/random-api-go:latest
    ports:
      - "5003:5003"
    volumes:
      - ./data:/root/data
    environment:
      - TZ=Asia/Shanghai
      - BASE_URL=https://random-api.czl.net
    restart: unless-stopped

访问地址

部署完成后，可以通过以下地址访问：

• 前端首页: http://localhost:5003/
• 管理后台: http://localhost:5003/admin
• API统计: http://localhost:5003/api/stats
• 动态API端点: http://localhost:5003/{endpoint-name}

开发环境

本地开发

在开发环境中，前端仍然可以使用开发服务器：

# 启动后端
go run main.go

# 启动前端（另一个终端）
cd web
npm run dev

前端的next.config.ts会在开发环境中自动代理API请求到后端。

生产构建测试

# 构建前端
cd web
npm run build

# 启动后端（会自动服务静态文件）
cd ..
go run main.go

注意事项

1. 前端路由: 所有前端路由都会返回index.html，由前端路由器处理
2. API端点冲突: 确保动态API端点名称不与静态文件路径冲突
3. 缓存: 静态文件会被适当缓存，API响应不会被缓存
4. 错误处理: 404错误会根据路径类型返回相应的错误页面