Files

树萌芽 90590c7cb0 update: 2026-03-28 21:00

2026-03-28 21:00:27 +08:00

7.4 KiB

Raw Blame History

SproutGate（萌芽账户认证中心）

前后端分离的统一账户与轻量用户中心：注册登录、邮箱验证、找回密码、副邮箱、签到与资料管理；管理员可维护用户、签到与注册/邀请码策略。数据以 JSON 文件落盘（无传统数据库），适合自建与小规模部署。第三方站点（如万象口袋）通过 OAuth 式查询参数 与 JWT / 校验接口 接入，详见 sproutgate-backend/API_DOCS.md。

架构总览

flowchart LR
  subgraph client [浏览器]
    FE[React + Vite SPA]
  end
  subgraph api [sproutgate-backend]
    Gin[Gin HTTP]
    H[handlers]
    S[storage JSON]
    J[auth JWT]
    Gin --> H --> S
    H --> J
  end
  FE -->|HTTPS /api| Gin
  S --> FS[(data/config + data/users)]

部分	技术栈	目录	说明
前端	React 18 + Vite 5	`sproutgate-frontend/`	无 `react-router`；由 `App.jsx` 按 `pathname` 切换视图；`VITE_API_BASE` 指向后端
后端	Go 1.20 + Gin	`sproutgate-backend/`	单体 REST；默认端口 `8080`；CORS 放行常用头（含 `Authorization`、`X-Admin-Token`、`X-Auth-Client*`）
数据	JSON 文件	`sproutgate-backend/data/`	`config/`（`admin.json`、`auth.json` 含 JWT 密钥、`email.json`、`checkin.json`、`registration.json` 等）、`users/`（用户记录）

后端代码结构（`sproutgate-backend/`）

包 / 目录	职责
`main.go`	初始化 `storage.Store`、注册路由、监听 `PORT`
`internal/handlers/`	HTTP 处理：`auth_login`、`auth_password`、`profile`、`checkin`、`admin`、`public_registration`、`registration_admin`、`secondary_email`、`auth_client` 等；`handler.go` 聚合依赖
`internal/storage/`	数据目录布局、读写 JSON、待验证/重置令牌等
`internal/models/`	`User`、`Activity`、待审核、副邮箱、接入方元数据等结构体
`internal/auth/jwt.go`	JWT 签发与解析（HS256）
`internal/email/mailer.go`	SMTP 发信（配置来自 `data/config/email.json`）
`internal/clientgeo/`	与访问来源等辅助逻辑配合（请求头见 `main.go` CORS）

API 前缀（与 main.go 一致）

前缀	说明
`/api/auth/*`	登录、注册、邮箱验证、忘记/重置密码、副邮箱、`POST /verify`、`GET /me`、签到、`PUT /profile`；可带 `X-Auth-Client` / `X-Auth-Client-Name` 记录第三方应用
`/api/public/*`	公开用户资料、注册策略（是否强制邀请码等）
`/api/admin/*`	需 `AdminMiddleware`：请求头 `X-Admin-Token` 或 Query `token`，与用户 JWT 分离

运维与文档：GET /、GET /api（JSON 服务说明）、GET /api/health、GET /api/docs（返回仓库内 API_DOCS.md）。

前端代码结构（`sproutgate-frontend/`）

路径	说明
`src/App.jsx`	根组件：根据路径渲染门户 / 公开用户页 / 管理端；顶栏连点 Logo 进入管理员流程
`src/config.js`	`VITE_API_BASE`、开发与生产默认 API 地址
`src/components/UserPortal.jsx`	`/`：登录、注册、邮件验证、`redirect_uri` 统一登录回跳等
`src/components/PublicUserPage.jsx`	`/user`、`/user/:account`：公开资料
`src/components/AdminPanel.jsx`	`/admin`：用户与签到、注册策略管理

认证与安全（摘要）

用户会话：登录成功后签发 JWT（Authorization: Bearer）；受保护接口解析 JWT 后按 account 加载用户；封禁等状态见 handlers 内校验。
令牌校验：POST /api/auth/verify 供第三方后端校验用户 token（见 API 文档）。
管理员：与业务 JWT 独立，使用 X-Admin-Token（或 Query token）与 data/config/admin.json 比对。
第三方统一登录门户：入口 URL 查询参数 redirect_uri、client_id、client_name 等；前端通过 sessionStorage 与请求头 X-Auth-Client / X-Auth-Client-Name 与后端协同（CORS 已允许上述头）。

部署到公网前：修改默认 JWT 密钥、管理员 Token、SMTP 密码，且勿将含真实密钥的 data/config 提交到公开仓库。

环境要求

后端：Go 1.20+（以 sproutgate-backend/go.mod 为准）
前端：Node.js 18+（建议 LTS）

快速开始

方式一：根目录脚本（推荐本地开发）

Windows

sproutgate.bat dev

macOS / Linux

chmod +x sproutgate.sh
./sproutgate.sh dev

会启动后端 go run . 与前端 npm run dev（前端默认 5173，后端默认 8080）。

仅构建前端：

sproutgate.bat build

./sproutgate.sh build

方式二：手动分别启动

后端

cd sproutgate-backend
go mod tidy
go run .

前端

cd sproutgate-frontend
npm install
npm run dev

前端连接后端

在 sproutgate-frontend/.env（自行创建）中设置：

VITE_API_BASE=http://localhost:8080

生产环境改为实际 API 地址（如 https://auth.api.example.com）。

配置与安全

管理员 Token、JWT 密钥、邮件 SMTP 等位于 sproutgate-backend/data/config/（如 admin.json、auth.json、email.json）。部署到公网前请务必修改默认值，且不要将真实密钥提交到仓库。
进入管理员后台：在任意页面顶栏 连续点击 Logo 五次（约 2.6 秒内），在弹窗中输入与 admin.json 一致的 Token；也可直接使用 http://localhost:5173/admin?token=<Token>（Token 会写入本地后再请求接口）。

可选：Docker 仅跑后端 API

在 sproutgate-backend 目录：

docker compose up -d --build

默认将容器内 8080 映射到主机 28080（可通过环境变量 AUTH_API_PORT 修改）。数据目录通过卷挂载到 ./data。

环境变量（后端）

变量	说明
`PORT`	监听端口，默认 `8080`
`DATA_DIR`	数据根目录；不设置时使用仓库内相对路径下的 `data` 布局

文档	内容
`sproutgate-backend/API_DOCS.md`	HTTP 接口契约（第三方接入主参考）
`AGENTS.md`	目录约定、协作与 PR 建议

许可证

若仓库未包含 LICENSE 文件，使用前请与维护者确认授权方式。

7.4 KiB Raw Blame History Unescape Escape