SproutGate 后端文档

技术栈

业务数据与配置均保存在 MySQL 中，不再使用 data/users/*.json 与 data/config/*.json 作为运行时数据源。仓库中的 data/ 仅可作迁移脚本输入或本地备份参考。

连接字符串优先级：DB_DSN > 内置规则。

若设置 DB_DSN：直接使用该完整 DSN（适合 CI、容器或临时切换）。
否则：根据 APP_ENV 选择内置库：
- APP_ENV=production 或 prod → 生产库：192.168.1.100:3306 / 库名 sproutgate / 用户 sproutgate
- 未设置或其它值 → 开发/测试库：10.1.1.100:3306 / 库名 sproutgate-test / 用户 sproutgate-test

其它常用环境变量：

变量	说明	默认
`PORT`	HTTP 监听端口	`8080`
`APP_ENV`	影响默认 MySQL 选择与 `/api/health` 返回的 `env`	空则 health 中为 `development`
`GIN_MODE`	`release` 时 GORM 日志级别更安静（警告级）	debug 模式
`DB_DSN`	完整 MySQL DSN，覆盖上述内置地址	未设置
`GEO_LOOKUP_URL`	`GET /api/auth/me` 未带 `X-Visit-Location` 时，服务端按 IP 请求该基址反查展示地理位置（实现见 `internal/clientgeo`，会拼接 `?ip=`）	默认 `https://cf-ip-geo.smyhub.com/api`

建议：生产部署时设置 APP_ENV=production，并确保 MySQL 防火墙与账号权限正确；敏感连接信息也可只通过 DB_DSN 注入，无需改代码。

应用启动与 migrate 工具均会同步下列表结构（GORM AutoMigrate）：

表名	用途
`users`	用户主数据；签到/访问时间列表、`auth_clients` 等以 JSON 文本列存储
`pending_users`	注册邮箱验证流程中的待激活用户
`password_resets`	忘记密码验证码
`secondary_email_verifications`	绑定辅助邮箱验证码
`app_configs`	键值配置：`admin`、`auth`、`email`、`checkin`、`registration`（JSON）
`invite_codes`	注册邀请码
`profile_likes`	公开用户主页点赞明细（点赞者、被赞者、自然日等）
`profile_like_daily_quota`	点赞者当日已用额度（与代码常量 `MaxProfileLikesPerDay` 配合）

管理员令牌、JWT Secret、邮件 SMTP、签到奖励、是否强制邀请码等，均从 app_configs / invite_codes 读写，首次无记录时由 Store 按逻辑补全默认项。

在 sproutgate-backend 目录下：

# 导入到当前环境对应的库（默认开发库，除非设置 APP_ENV 或 DB_DSN）
go run ./cmd/migrate --data-dir ./data

Windows PowerShell 示例（写入生产库）：

$env:APP_ENV = "production"
go run ./cmd/migrate --data-dir ./data
Remove-Item Env:APP_ENV   # 可选：清除变量，避免影响本机其它命令

迁移内容：data/config/*.json（写入 app_configs 与 invite_codes）、data/users/*.json（写入 users）。对已存在主键执行 UPSERT：同账号、同配置键会更新为迁移文件中的值。

GET /、GET /api：API 简要说明 JSON（main.go 内嵌字段，含 version、routePrefixes 等）。当前未注册单独返回 Markdown 的 /api/docs 路由；对外长文档见仓库根目录 萌芽账户认证中心-第三方应用API接入文档.md。
GET /api/health：{ "status": "ok", "env": "<APP_ENV 或 development>" }。
/api/auth/*：登录、注册、邮箱验证、忘记/重置密码、辅助邮箱、令牌校验、/me、签到、更新资料等；可选请求头 X-Auth-Client、X-Auth-Client-Name（记录第三方应用接入）。
/api/public/*：
- GET /api/public/users：公开用户目录（未封禁；默认按 createdAt 升序）。
- GET /api/public/users/:account：公开资料 + 累计赞数；若带合法 Bearer，可附加「是否已赞今日」「当日剩余可点赞人数」等浏览者上下文。
- POST /api/public/users/:account/like：登录用户给指定主页点赞（不能赞自己；每人每主页每日一次；每自然日每名用户最多给 5 位不同用户点赞，常量见 internal/storage/profile_likes.go）。
- GET /api/public/registration-policy：是否强制邀请码等。
/api/admin/*：需 X-Admin-Token（或 Query token）：用户 CRUD、签到配置、注册策略与邀请码管理。

允许的 CORS 自定义头包含：Authorization、X-Admin-Token、X-Visit-Ip、X-Visit-Location、X-Auth-Client、X-Auth-Client-Name 等。

cd sproutgate-backend
go mod tidy
go run .

默认监听 :8080。前端开发时请将 VITE_API_BASE 指向本服务（详见仓库根目录下 sproutgate-frontend/前端文档.md）。