121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# SproutGate（萌芽账户认证中心）
|
||
|
||
前后端分离的统一账户与轻量用户中心：注册登录、邮箱验证、找回密码、副邮箱、签到与资料管理；管理员可维护用户与签到配置。数据以 JSON 文件落盘，适合自建与小规模部署。
|
||
|
||
## 架构一览
|
||
|
||
| 部分 | 技术栈 | 目录 | 说明 |
|
||
|------|--------|------|------|
|
||
| 前端 | React 18 + Vite 5 | [`sproutgate-frontend/`](./sproutgate-frontend/) | 用户门户、公开用户页、管理后台；`VITE_API_BASE` 指向后端 |
|
||
| 后端 | Go + Gin | [`sproutgate-backend/`](./sproutgate-backend/) | REST API、JWT、CORS；默认端口 `8080` |
|
||
| 数据 | JSON 文件 | [`sproutgate-backend/data/`](./sproutgate-backend/data/) | `config/`（管理员、认证、邮件等）、`users/`（用户记录） |
|
||
|
||
### 前端路由与模块
|
||
|
||
- **`/`** — [`UserPortal`](./sproutgate-frontend/src/components/UserPortal.jsx)：登录、注册、验证邮件、OAuth 式 `redirect_uri` 回跳等流程。
|
||
- **`/user` / `/user/:account`** — [`PublicUserPage`](./sproutgate-frontend/src/components/PublicUserPage.jsx)：公开资料展示（Markdown 等）。
|
||
- **`/admin`** — [`AdminPanel`](./sproutgate-frontend/src/components/AdminPanel.jsx)：用户 CRUD、签到配置；请求头携带管理员 Token（见下文配置）。
|
||
|
||
启动页与全局壳层见 [`App.jsx`](./sproutgate-frontend/src/App.jsx)、[`SplashScreen`](./sproutgate-frontend/src/components/SplashScreen.jsx)。
|
||
|
||
### 后端能力摘要
|
||
|
||
- **认证**：登录、注册、邮箱验证、忘记/重置密码、副邮箱申请与验证、JWT 校验、`/api/auth/me`、签到、资料更新。
|
||
- **公开接口**：按账号获取公开用户信息；`GET /api/public/registration-policy` 查询是否强制邀请码注册。
|
||
- **管理接口**：`/api/admin/*`（需 `X-Admin-Token`），用户管理、签到与**注册策略/邀请码**（`data/config/registration.json`）。
|
||
- **运维**：`GET /` 与 `GET /api`（JSON 服务说明）、`GET /api/health`、`GET /api/docs`（返回 [`API_DOCS.md`](./sproutgate-backend/API_DOCS.md)）。
|
||
|
||
完整契约见 [`sproutgate-backend/API_DOCS.md`](./sproutgate-backend/API_DOCS.md)（文内 **「统一登录前端：查询参数」**、**「回跳 URL」**、**`POST /api/auth/login` / `verify` / `me`** 等章节为第三方接入主参考）。
|
||
|
||
## 环境要求
|
||
|
||
- **后端**：Go 1.21+（以 `go.mod` 为准）
|
||
- **前端**：Node.js 18+（建议 LTS）
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：根目录脚本（推荐本地开发）
|
||
|
||
**Windows**
|
||
|
||
```bat
|
||
sproutgate.bat dev
|
||
```
|
||
|
||
**macOS / Linux**
|
||
|
||
```bash
|
||
chmod +x sproutgate.sh
|
||
./sproutgate.sh dev
|
||
```
|
||
|
||
会启动后端 `go run .` 与前端 `npm run dev`（前端默认 `5173`，后端默认 `8080`）。
|
||
|
||
仅构建前端：
|
||
|
||
```bat
|
||
sproutgate.bat build
|
||
```
|
||
|
||
```bash
|
||
./sproutgate.sh build
|
||
```
|
||
|
||
### 方式二：手动分别启动
|
||
|
||
**后端**
|
||
|
||
```bash
|
||
cd sproutgate-backend
|
||
go mod tidy
|
||
go run .
|
||
```
|
||
|
||
**前端**
|
||
|
||
```bash
|
||
cd sproutgate-frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### 前端连接后端
|
||
|
||
在 `sproutgate-frontend/.env`（自行创建）中设置：
|
||
|
||
```env
|
||
VITE_API_BASE=http://localhost:8080
|
||
```
|
||
|
||
生产环境改为实际 API 地址即可。
|
||
|
||
### 配置与安全
|
||
|
||
- 管理员 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` 目录：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认将容器内 `8080` 映射到主机 `28080`（可通过环境变量 `AUTH_API_PORT` 修改）。数据目录通过卷挂载到 `./data`。
|
||
|
||
## 环境变量（后端）
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `PORT` | 监听端口，默认 `8080` |
|
||
| `DATA_DIR` | 数据根目录；不设置时使用仓库内默认 `data` 布局 |
|
||
|
||
## 仓库维护说明
|
||
|
||
更细的目录约定、代码风格与 PR 建议见 **[`AGENTS.md`](./AGENTS.md)**。
|
||
|
||
## 许可证
|
||
|
||
若仓库未包含 `LICENSE` 文件，使用前请与维护者确认授权方式。
|