core — 游戏社区平台后端

Go 模块化单体后端，为游戏社区平台提供全部业务逻辑与 REST API。

技术栈

• 语言 / 框架：Go 1.23 + Gin
• ORM：GORM + PostgreSQL 16（启用 pg_trgm 扩展）
• 缓存 / 队列：Redis 7（AOF 持久化）
• 认证：JWT HS256（双令牌）+ bcrypt
• 邮件：gomail（SMTP）
• 内容安全：bluemonday（Markdown 入库前净化）

架构

模块化单体（Modular Monolith）。所有业务模块在同一进程内通过函数调用通信，模块间通过接口（ports）解耦，禁止跨模块 import 包，依赖注入统一在 internal/app/app.go 完成。

游戏服务器通过统一的 HTTP 长轮询协议（/api/srv/*）直连 core，无中间层。

Nginx
  ├── /api/*        → core:8080（本项目）
  └── /uploads/*    → 静态文件（Nginx 直出）

游戏服务器插件（MC Java / Bedrock / DST / Terraria）
  └── HTTP /api/srv/*  →  core:8080

项目结构

core/
├── cmd/server/main.go
├── internal/
│   ├── modules/
│   │   ├── auth/         # 注册 / 登录 / 双令牌 / 邮箱验证码
│   │   ├── user/         # 用户信息
│   │   ├── forum/        # 论坛分区 / 帖子 / 评论 / 标签
│   │   ├── checkin/      # 每日签到
│   │   ├── donation/     # 捐赠榜
│   │   ├── attachment/   # 附件上传
│   │   ├── server/       # 游戏服务器管理 + 玩家绑定 + 排行
│   │   ├── player/       # 玩家统计 / PK
│   │   ├── admin/        # 后台管理接口
│   │   ├── log/          # 操作日志
│   │   ├── audit/        # Bedrock 行为日志
│   │   ├── config/       # 运行时配置（Redis hash 热更）
│   │   └── serverlink/   # 游戏服务器接入层（长轮询调度）
│   ├── shared/
│   │   ├── db/           # GORM 实例 + 迁移
│   │   ├── redis/        # go-redis 封装
│   │   ├── auth/         # JWT 签发/解析 + bcrypt
│   │   ├── email/        # SMTP 客户端 + 模板
│   │   ├── middleware/   # AuthRequired / AdminRequired / RateLimit / ServerTokenAuth
│   │   └── response/     # 统一响应 envelope
│   └── app/app.go        # 依赖组装 + 路由挂载
├── migrations/
├── configs/
├── Dockerfile
└── go.mod

API 概览

所有接口使用统一 envelope：

{ "code": "OK", "data": { ... } }          // 成功
{ "code": "USER_NOT_FOUND", "data": null } // 失败

用户侧 (/api/*)：JWT Bearer 鉴权

分组	路径前缀
认证	/api/auth/*
用户	/api/users/*
签到	/api/checkins
捐赠	/api/donations/*
服务器	/api/servers/*
论坛	/api/forums/* /api/posts/* /api/tags
搜索	/api/search
管理	/api/admin/*

游戏服务器侧 (/api/srv/*)：Server Token 鉴权（?token= query 参数）

端点	说明
GET /api/srv/poll	长轮询拉取下行事件（最多挂起 25-30s）
POST /api/srv/reply	回复事件
POST /api/srv/heartbeat	心跳上报（刷新在线状态 TTL）
POST /api/srv/player.joined	玩家加入通知
POST /api/srv/player.left	玩家离开通知
POST /api/srv/binding.request	绑定验证码核验
POST /api/srv/leaderboard.update	批量上报排行榜
POST /api/srv/audit.log	Bedrock 行为日志上报
GET /api/srv/config	拉取本服配置

本地运行

依赖：PostgreSQL 16、Redis 7。

cp configs/config.example.yaml configs/config.yaml
# 编辑 config.yaml 填写 DB / Redis / JWT secret / SMTP 等配置

go run ./cmd/server

环境变量

主要配置项（也可通过 configs/config.yaml 提供，环境变量优先）：

DATABASE_URL=postgres://user:pass@localhost:5432/core
REDIS_URL=redis://localhost:6379
JWT_SECRET=<随机长字符串>
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_USER=noreply@example.com
SMTP_PASS=<password>

部署

通过 Docker Compose 与 web、postgres、redis、nginx 容器一同编排。Nginx 将 /api/* 和 /uploads/* 反代到本容器 :8080，其余请求转发到 web:3000。

docker compose up -d

数据库迁移

迁移文件位于 migrations/，应用启动时自动执行。