Bunker Web Backend

基于 Go、Gin 和 GORM/MySQL 的用户中心后端，提供网页 API、OpenAPI 和 Phoenix 客户端接口。 前端仓库：Cynic158/Bunker-Web。

本地运行

使用 go.mod 指定的 Go 版本（目前为 1.27.3），并准备 MySQL。 项目通过 Go workspace 引用同级 bunker-core：

bunker-dev/
  go.work
  bunker-core/
  bunker-web/

如果上级已有 go.work，沿用即可；不要覆盖它。新环境可在上级目录执行：

go work init ./bunker-core ./bunker-web

在后端目录准备个人配置，文件不会提交到 Git：

cp .env.example local.env
# 编辑 local.env，填写本地数据库和服务凭据
set -a
source ./local.env
set +a
go run .

应用不会自动读取 env 文件；生产环境可继续使用 systemd 的 EnvironmentFile。 示例默认端口为 2333，与前端 http://localhost:5173 的开发代理匹配。

配置

配置项	作用
GIN_MODE	debug、release 或 test
HTTP_PORT	HTTP监听端口，未指定时为8080
CURRENT_WEB_DOMAIN	前端完整origin，用于Cookie域及WebAuthn RPID/origin
CORS_ALLOWED_ORIGINS	逗号分隔的完整origin，精确匹配协议、域名和端口
DB_TYPE / DB_HOST / DB_USER / DB_PASSWORD / DB_NAME	MySQL连接配置，仅支持mysql
GORM_LOGGER_MODE	GORM日志级别；生产建议2（Error）或1（Silent）
CAPTCHA_SECRET_KEY	服务端Turnstile密钥，不能使用前端site key代替
USER_PSW_SALT	既有账户密码盐，不可直接更换
FBTOKEN_KEY / FBTOKEN_IV	Base64编码的既有32字节密钥、16字节IV
GMAIL_ACCOUNT / GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET / GMAIL_REFRESH_TOKEN	Gmail SMTP OAuth配置

release 模式要求显式提供数据库账户/密码/库名、密码盐、FBToken密钥/IV及CAPTCHA密钥。 配置无效时在监听HTTP之前退出。已有部署必须沿用原来的密码盐、Token密钥与域名， 否则账户登录、客户端Token或通行密钥会失效；不要为了通过启动检查随意生成替代值。

未设置CORS列表时包含当前前端origin、https://liliya233.uk 和 http://localhost:5173。 生产环境建议显式设置所需列表。CORS只控制浏览器跨域读取，不代替鉴权或反向代理访问控制。

代码结构

main.go                 配置校验、数据库、后台任务、HTTP及退出流程
configs/                环境配置
routers/                web/openapi/phoenix路由注册，按业务划分的handler
routers/api/account/    Bot/游戏账号共用绑定流程
middlewares/            会话、权限、CORS、deadline、错误响应及日志
services/               数据库查询和业务操作
services/gameaccount/   MPay平台账号的事务化替换与解绑
models/                 GORM模型、关联读取、显式数据库生命周期
pkg/gins/               Gin响应及公开/内部错误；不是通用工具包
pkg/requestctx/         请求身份和类型化session访问
pkg/sessions/           进程内会话和Cookie
pkg/accountlock/        可取消的按账户串行化
pkg/email/              SMTP/OAuth、验证码发行与原子消费
pkg/g79/                游戏接口适配和客户端缓存
docs/                   生成的Swagger文件

• 认证后每个请求读取最新用户资料，session不保存可变User对象或权限快照。
• 同账户请求串行执行，防止游戏账号令牌、绑定和持久化互相覆盖；不同账户可并行。
• 普通字段使用定向更新；MPay关联更新使用事务，不依赖User保存钩子的隐式级联。
• 会话、验证码和游戏缓存仍为进程内状态，当前适用于单实例；多副本部署需另行设计共享会话、分布式串行化和数据库约束。
• Web登录维持单网页会话；Phoenix登录不会挤掉网页会话。密码修改保留当前网页会话，撤销其他会话；密码重置及删除账户撤销全部会话。
• 现有业务失败保持HTTP200及success=false；鉴权失败401/403；panic返回500及安全的JSON错误。
• 业务错误可携带data.verify_url，内部错误只向客户端显示安全消息，底层原因由日志记录。

超时与外部服务

Web层请求context上限120秒，HTTP写超时130秒；Phoenix版本协商自身上限100秒、最多三次。 CAPTCHA/OAuth HTTP请求10秒超时，SMTP有TLS、连接deadline和请求取消处理。

这些上限不能覆盖Nginx、Cloudflare或core内部更短的超时。 core的部分Android官方信息请求自身为30秒；绑定接口中部分旧MPay方法没有context参数。 core仅修正了资源版本为空时的提示文案，未改其超时或协议逻辑， 也没有通过后台goroutine把无法取消的操作“假装”变为可取消。 外部游戏资源未准备好时仍可启动HTTP服务，后台继续尝试更新。

格式、检查与测试

make fmt          # gofmt
make imports      # goimports，统一项目导入分组
make modernize    # go fix，使用当前Go版本推荐的新写法
make check        # vet、gofmt、现代化建议检查、构建
make swagger      # 根据handler注释生成Swagger

VS Code可使用Go扩展在保存时格式化并整理imports；项目不包含个人编辑器配置。 本次没有在项目中保留额外的_test.go、测试框架或测试快照。 验证期间使用仓库外的临时检查，并在独立的bunker_web_qa_*MySQL数据库中联调，结束后删除测试库， 未操作业务数据库中的真实账号。验证覆盖登录、权限更新、会话替换、API Key撤销、公告、 平台账号事务、失败回滚和并发字段更新，并进行了race检查。 外部游戏登录、真实邮件/SMS/验证码服务仍需专用测试环境验证。

现有Web依赖已统一升级到本次可用的最新稳定版本，并验证了WebAuthn 0.18的接口迁移。 安全扫描未发现可达漏洞。依赖模块中的已弃用openpgp包仍有模块级告警，项目未导入或调用该包。

数据与部署

启动时继续执行原有模型的AutoMigrate，但现在会检查并报告失败；没有自动新增唯一索引、 更改密码算法或轮换Token密钥。上线前仍需备份，并在数据副本检查迁移行为。

部署时沿用现有密码盐、FBToken密钥和WebAuthn域名，核对release配置及反向代理超时； 重启后进程内会话和缓存会清空，用户需要重新登录。