初始化项目：基础设施 + 用户认证 + 后台管理系统 + AGPL 3.0 许可
This commit is contained in:
531
docs/development.md
Normal file
531
docs/development.md
Normal file
@ -0,0 +1,531 @@
|
||||
# 开发记录 — 阶段一：基础设施 + 用户认证（含"记住我"与令牌刷新）
|
||||
|
||||
> 最后更新：2026-05-24
|
||||
|
||||
## 一、已完成事项
|
||||
|
||||
### 1. 数据库配置与连接
|
||||
|
||||
**问题**：PostgreSQL 使用 `peer` 认证，Go 进程以系统用户 `victor_jay` 运行，无法连接数据库用户 `metazone`。
|
||||
|
||||
**解决**：
|
||||
- 为 `metazone` 数据库用户设置密码（`MetalabDev2026!`）
|
||||
- 连接方式从 Unix socket（`/var/run/postgresql`）改为 TCP（`127.0.0.1:5432`），触发 `scram-sha-256` 密码认证
|
||||
- 数据库名称：`metalab_dev`
|
||||
|
||||
**涉及文件**：`config.yaml`（`database.host` 改为 `127.0.0.1`）、`.env`（`DATABASE_PASSWORD`）
|
||||
|
||||
---
|
||||
|
||||
### 2. 配置加载架构修复
|
||||
|
||||
**问题**：Viper 的 `SetConfigFile(".env")` 会**覆盖**之前设置的 `config.yaml` 路径，导致所有 YAML 配置被清空，数据库名称为空。
|
||||
|
||||
**根本原因**：Viper 不支持同时加载多个不同类型的配置文件。
|
||||
|
||||
**解决方案**：
|
||||
|
||||
`internal/config/config.go` 中的加载流程：
|
||||
```
|
||||
1. loadEnvFile(".env") → 逐行读取，通过 os.Setenv() 注入环境变量
|
||||
2. viper 只读取 config.yaml
|
||||
3. bindEnvOverride() → 将 DATABASE_PASSWORD、JWT_SECRET 显式绑定到对应配置键
|
||||
4. viper.AutomaticEnv() → 自动读取其余环境变量
|
||||
```
|
||||
|
||||
环境变量优先级：**系统环境变量 > .env 文件**（`.env` 仅在对应环境变量未设置时生效）
|
||||
|
||||
**涉及文件**：`internal/config/config.go`（重写 `Load()` 函数）
|
||||
|
||||
---
|
||||
|
||||
### 3. 数据模型设计
|
||||
|
||||
#### 3.1 公共基础模型 (`common.go`)
|
||||
|
||||
| 字段 | 类型 | GORM 标签 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `ID` | `uint` | `primarykey;column:uid` | 主键，数据库列名为 `uid`，自增 bigint（非 UUID） |
|
||||
| `CreatedAt` | `time.Time` | — | 自动管理 |
|
||||
| `UpdatedAt` | `time.Time` | — | 自动管理 |
|
||||
| `DeletedAt` | `gorm.DeletedAt` | `index;json:"-"` | 软删除，JSON 不暴露 |
|
||||
|
||||
#### 3.2 用户模型 (`user.go`)
|
||||
|
||||
| 字段 | 类型 | 约束 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `Email` | `varchar(255)` | `uniqueIndex; not null` | 注册和登录的唯一凭证 |
|
||||
| `PasswordHash` | `varchar(255)` | `not null; json:"-"` | bcrypt(12)，JSON 永不暴露 |
|
||||
| `Username` | `varchar(16)` | `uniqueIndex; not null` | 全局唯一，10 位随机 `[a-z0-9]` 自动生成 |
|
||||
| `Avatar` | `varchar(500)` | `default:''` | 预留头像字段 |
|
||||
| `Bio` | `text` | — | 预留个人简介 |
|
||||
| `Role` | `varchar(20)` | `default:user; index` | `user` / `moderator` / `admin` |
|
||||
| `Status` | `varchar(20)` | `default:active; index` | `active` / `banned` |
|
||||
|
||||
**关键设计决策：**
|
||||
|
||||
| 决策项 | 选择 | 原因 |
|
||||
|---|---|---|
|
||||
| 主键方案 | 自增 bigint（`uid` 列）而非 UUID | 社区应用，索引性能更好，URL 简洁 `/users/42`，`JOIN` 体积小 |
|
||||
| 角色控制 | `role string` 而非 `is_admin bool` | 可扩展（已有 user/moderator/admin 三级），符合最佳实践 |
|
||||
| 用户名生成 | `crypto/rand` 生成 10 位 `[a-z0-9]` | 3,656 万亿种组合，千万用户碰撞概率 < 0.01% |
|
||||
| 用户名长度 | `varchar(16)` | 作为最大长度限制（暂未支持中文字符名） |
|
||||
| 密码哈希 | bcrypt(12) | 行业标准，成本 12 平衡安全与性能 |
|
||||
| 软删除 | GORM `DeletedAt` | 保留数据，误删可恢复 |
|
||||
|
||||
---
|
||||
|
||||
### 4. 用户注册
|
||||
|
||||
**流程**：
|
||||
```
|
||||
POST /api/auth/register
|
||||
→ 验证 Email/Password/ConfirmPassword（binding 标签）
|
||||
→ Service.Register()
|
||||
→ validatePassword()：≥8位 + 含字母 + 含数字
|
||||
→ userRepo.FindByEmail()：邮箱查重
|
||||
→ bcrypt.GenerateFromPassword(,12)：密码哈希
|
||||
→ generateUsername()：生成 10 位随机用户名，重试 20 次去重
|
||||
→ userRepo.Create()：写入数据库
|
||||
→ buildToken()：生成 access JWT（HS256，15 分钟）
|
||||
→ 如果 req.RememberMe → buildRefreshToken()：生成 refresh JWT（HS256，30 天）
|
||||
→ SetAuthCookies(accessToken, refreshToken) → 设置 Cookie
|
||||
→ 返回 JSON { success, message, data: user }
|
||||
```
|
||||
|
||||
**关键点**：注册即登录，Cookie 自动设置，前端无需额外操作。勾选"记住我"则下发 refresh token + 标记 Cookie，未勾选则不下发。
|
||||
|
||||
**涉及文件**：
|
||||
- `internal/controller/auth_controller.go` — `Register()` POST handler
|
||||
- `internal/service/auth_service.go` — `Register()`、`validatePassword()`、`generateUsername()`、`buildToken()`、`buildRefreshToken()`
|
||||
- `internal/repository/user_repo.go` — `Create()`、`FindByEmail()`
|
||||
- `internal/model/dto.go` — `RegisterRequest`（binding 校验标签 + `remember_me`）
|
||||
|
||||
---
|
||||
|
||||
### 5. 用户登录
|
||||
|
||||
**流程**：
|
||||
```
|
||||
POST /api/auth/login
|
||||
→ 验证 Email/Password
|
||||
→ Service.Login()
|
||||
→ userRepo.FindByEmail()：查找用户
|
||||
→ 检查 Status != banned（封禁用户拒绝登录）
|
||||
→ bcrypt.CompareHashAndPassword()：密码校验
|
||||
→ buildToken()：生成 access JWT
|
||||
→ 如果 req.RememberMe → buildRefreshToken()：生成 refresh JWT
|
||||
→ SetAuthCookies(accessToken, refreshToken)
|
||||
→ 返回 JSON { success, message, data: user }
|
||||
```
|
||||
|
||||
**错误处理**：根据错误类型返回不同 HTTP 状态码和消息：
|
||||
- 401：邮箱不存在 / 密码错误
|
||||
- 403：用户已封禁
|
||||
- 500：服务器内部错误
|
||||
|
||||
**涉及文件**：`auth_controller.go`（`Login()`）、`auth_service.go`（`Login()`、`ErrUserBanned`、`buildRefreshToken()`）
|
||||
|
||||
---
|
||||
|
||||
### 6. JWT 认证中间件
|
||||
|
||||
| 中间件 | 用途 | 注入上下文的值 |
|
||||
|---|---|---|
|
||||
| `AuthRequired` | 严格认证，失败返回 401 | `uid`、`email`、`username`、`role` |
|
||||
| `AuthOptional` | 可选认证，有 token 就注入，没有也放行 | 同上（无 token 时不注入） |
|
||||
|
||||
**Cookie 配置**：
|
||||
|
||||
| Cookie | 名称 | HttpOnly | Secure | SameSite | 过期 |
|
||||
|---|---|---|---|---|---|
|
||||
| Access token | `mlb_token` | ✅ | ✅（debug 模式 HTTP） | Lax | 15 min |
|
||||
| Refresh token | `mlb_refresh` | ✅ | ✅ | Lax | 30 day（记住我时） |
|
||||
| 记住我标记 | `mlb_rm` | ❌ | ✅ | — | 30 day（记住我时） |
|
||||
|
||||
**中间件公开函数**：
|
||||
|
||||
| 函数 | 用途 |
|
||||
|---|---|
|
||||
| `SetAuthCookies(c, accessToken, refreshToken, cfg)` | 设置 access + refresh（+ mlb_rm 标记） |
|
||||
| `SetAccessCookie(c, accessToken, cfg)` | 仅刷新 access cookie（续期调用） |
|
||||
| `ClearAuthCookies(c, cfg)` | 清除全部三个 Cookie（登出/过期） |
|
||||
|
||||
**涉及文件**：`internal/middleware/auth.go`
|
||||
|
||||
---
|
||||
|
||||
### 7. 登录状态注入（SSR 模板渲染）
|
||||
|
||||
`internal/common/helper.go` 中的 `BuildPageData()`：
|
||||
|
||||
```go
|
||||
func BuildPageData(c *gin.Context, extra gin.H) gin.H
|
||||
```
|
||||
|
||||
- 将 `extra` 键值对复制到 `gin.H`
|
||||
- 若 Gin 上下文中存在 `username`（由 `AuthOptional` 中间件注入），自动添加：
|
||||
- `IsLoggedIn: true`
|
||||
- `Username: "..."`
|
||||
- 所有页面 Controller 通过此函数构建模板数据
|
||||
|
||||
---
|
||||
|
||||
### 8. 页面路由与模板
|
||||
|
||||
| 路由 | 方法 | 中间件 | 模板 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `/` | GET | `AuthOptional` | `home/index.html` | 已登录显示首页，未登录重定向 `/auth/login` |
|
||||
| `/auth/register` | GET | `AuthOptional` | `auth/register.html` | 已登录重定向 `/` |
|
||||
| `/auth/login` | GET | `AuthOptional` | `auth/login.html` | 已登录重定向 `/` |
|
||||
|
||||
---
|
||||
|
||||
### 9. NAV 导航栏逻辑
|
||||
|
||||
```html
|
||||
{{if .IsLoggedIn}}
|
||||
→ 显示用户名链接（指向 /settings）+ "退出"按钮
|
||||
{{else}}
|
||||
→ 显示"登录"按钮（指向 /auth/login）
|
||||
{{end}}
|
||||
```
|
||||
|
||||
**设计决策**：NAV 只显示"登录"按钮，不显示独立"注册"按钮。注册入口在登录页面内部提供（作为开发者社区，用户应能理解）。已登录用户可通过"退出"按钮清除所有 Cookie 并返回首页。
|
||||
|
||||
---
|
||||
|
||||
### 10. 模板加载器重构
|
||||
|
||||
**问题**：原加载器使用 `info.Name()`（纯文件名），导致 `home/index.html` 注册为 `index.html`，与路由引用的 `home_index.html` 不匹配，模板渲染失败。
|
||||
|
||||
**解决**：改为使用相对路径作为模板名：
|
||||
|
||||
```
|
||||
layout/header.html
|
||||
layout/nav.html
|
||||
layout/footer.html
|
||||
auth/register.html
|
||||
auth/login.html
|
||||
home/index.html
|
||||
```
|
||||
|
||||
`{{template}}` 引用全部更新为这些相对路径名。
|
||||
|
||||
**涉及文件**：`internal/theme/loader.go`、所有 `.html` 模板文件中的 `{{template}}` 引用
|
||||
|
||||
---
|
||||
|
||||
### 11. "记住我" + 刷新令牌（Refresh Token）
|
||||
|
||||
#### 11.1 设计目标
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 用户勾选"记住我" | 双 Cookie：`mlb_token`(15min) + `mlb_refresh`(30d) |
|
||||
| 用户未勾选 | 单 Cookie：`mlb_token`(15min)，过期需重新登录 |
|
||||
| 页面持续开着 | 前端每 10 分钟静默调用 `/api/auth/refresh` 续期 access token |
|
||||
| 关闭浏览器 15+ min 后回来 | access token 过期 → JS 自动刷新 → 页面 reload 恢复登录态 |
|
||||
| 30 天内任意时间回来 | refresh token 仍有效，自动静默恢复登录 |
|
||||
|
||||
#### 11.2 Cookie 架构
|
||||
|
||||
| Cookie 名 | 作用 | HttpOnly | JS 可读 | 过期时间 | 说明 |
|
||||
|---|---|---|---|---|---|
|
||||
| `mlb_token` | access token | ✅ | ❌ | 15 min | JWT，含 `uid/email/username/role/exp/iat` |
|
||||
| `mlb_refresh` | refresh token | ✅ | ❌ | 30 day（勾选记住我时） | JWT，含 `uid/email/username/role/exp/iat/purpose:"refresh"` |
|
||||
| `mlb_rm` | 记住我标记 | ❌ | ✅ | 30 day（勾选记住我时） | 值为 `"1"`，仅标记位，非凭据 |
|
||||
|
||||
**设计决策 — `mlb_rm` 标记 Cookie**：
|
||||
- 本质是**非安全标记位**（not a credential），用于 JS 判断"是否该尝试刷新"
|
||||
- 如果不存在（未勾选记住我），`common.js` 跳过所有刷新逻辑 → **不会产生 401 控制台报错**
|
||||
- 值仅为 `"1"`，即使被 XSS 读取也无法用于任何认证操作
|
||||
|
||||
#### 11.3 配置 (`config.yaml` + `config.go`)
|
||||
|
||||
```yaml
|
||||
jwt:
|
||||
access_expire: 15 # 分钟
|
||||
refresh_expire: 168 # 小时 (7 天) — 备用字段，当前未启用
|
||||
remember_expire: 720 # 小时 (30 天) — refresh token 有效期
|
||||
```
|
||||
|
||||
`JWTConfig` 新增字段：
|
||||
```go
|
||||
RememberExpire int `mapstructure:"remember_expire"` // 小时
|
||||
```
|
||||
**关键**：`mapstructure` 标签**不可省略**，否则 Viper 无法将 YAML 键映射到结构体字段，导致过期时间全为 0。
|
||||
|
||||
#### 11.4 请求 DTO (`dto.go`)
|
||||
|
||||
`LoginRequest` 和 `RegisterRequest` 都新增了 `RememberMe` 字段：
|
||||
```go
|
||||
RememberMe bool `json:"remember_me"`
|
||||
```
|
||||
|
||||
#### 11.5 后端业务逻辑 (`auth_service.go`)
|
||||
|
||||
**变更的方法：**
|
||||
|
||||
| 方法 | 旧返回值 | 新返回值 |
|
||||
|---|---|---|
|
||||
| `Register()` | `(token, user, error)` | `(accessToken, refreshToken, user, error)` |
|
||||
| `Login()` | `(token, user, error)` | `(accessToken, refreshToken, user, error)` |
|
||||
|
||||
当 `req.RememberMe == false` 时，`refreshToken` 返回空字符串 `""`。
|
||||
|
||||
**新增方法：**
|
||||
|
||||
| 方法 | 签名 | 说明 |
|
||||
|---|---|---|
|
||||
| `buildRefreshToken(user)` | `(string, error)` | 构建 30 天过期 JWT，`purpose` claim 为 `"refresh"` |
|
||||
| `RefreshAccessToken(refreshTokenStr)` | `(string, error)` | 校验 refresh token → 返回新 access token |
|
||||
|
||||
**`RefreshAccessToken` 校验流程**：
|
||||
```
|
||||
1. 解析 refresh token JWT
|
||||
→ 失败：ErrTokenExpired（登录已过期）
|
||||
2. 校验 claims["purpose"] == "refresh"
|
||||
→ 不匹配：ErrTokenInvalid（防止 access token 被用于刷新）
|
||||
3. 从 claims 提取 uid/email/username/role → 构建新 access token
|
||||
```
|
||||
|
||||
**安全点**：`purpose: "refresh"` 声明确保**access token 无法充当 refresh token**，防止短生命周期令牌被滥用为长期凭据。
|
||||
|
||||
#### 11.6 Session 恢复实现（前端 JS）
|
||||
|
||||
`common.js` 中的自动刷新逻辑：
|
||||
|
||||
```
|
||||
页面加载（非 /auth/* 路径）
|
||||
→ 检查 document.cookie 是否存在 mlb_rm
|
||||
→ 不存在 → 跳过所有刷新（无 401 报错）
|
||||
→ 存在 → fetch POST /api/auth/refresh
|
||||
→ 成功：
|
||||
1. 启动 10 分钟定时器
|
||||
2. 页面未显示登录态（无 logoutBtn）？
|
||||
→ sessionStorage 防重 → window.location.reload()
|
||||
重载后 access token 存在 → SSR 正确渲染登录状态
|
||||
→ 失败 → 停止定时器（用户需手动重新登录）
|
||||
```
|
||||
|
||||
**关键实现细节**：
|
||||
- 用 `fetch()` 而非 `XMLHttpRequest`：`fetch` 对 HTTP 非 2xx 不会触发浏览器控制台静默日志
|
||||
- `sessionStorage` 防无限循环：`mlb_refreshed` 标志确保 reload 只执行一次
|
||||
- 不在认证页面执行：`/auth/login`、`/auth/register` 路径直接跳过
|
||||
|
||||
#### 11.7 界面
|
||||
|
||||
登录页和注册页各增加一个复选框：
|
||||
```html
|
||||
<div class="form-group remember-group">
|
||||
<label class="remember-label">
|
||||
<input type="checkbox" id="rememberMe">
|
||||
保持登录 30 天
|
||||
</label>
|
||||
<span class="remember-hint">非共享设备推荐</span>
|
||||
</div>
|
||||
```
|
||||
**默认不勾选**——公共环境（教室、网吧、共享电脑）不会意外留下长期凭据。
|
||||
|
||||
---
|
||||
|
||||
### 12. 登出功能
|
||||
|
||||
#### 12.1 后端 API
|
||||
|
||||
**路由**：`POST /api/auth/logout`
|
||||
|
||||
**处理流程**（`auth_controller.go` → `Logout()`）：
|
||||
```
|
||||
1. middleware.ClearAuthCookies(c, cfg)
|
||||
→ 清除 mlb_token、mlb_refresh、mlb_rm 三个 Cookie（MaxAge=-1）
|
||||
2. 返回 JSON { success: true, message: "已退出登录" }
|
||||
```
|
||||
|
||||
#### 12.2 前端
|
||||
|
||||
**NAV 导航栏**（`nav.html`）：
|
||||
```html
|
||||
{{if .IsLoggedIn}}
|
||||
<li><a href="/settings" class="nav-user">{{.Username}}</a></li>
|
||||
<li><a href="javascript:void(0)" class="nav-logout" id="logoutBtn">退出</a></li>
|
||||
{{end}}
|
||||
```
|
||||
|
||||
**JS 处理**（`common.js`）：
|
||||
```
|
||||
点击"退出" → POST /api/auth/logout → Cookie 清除完毕 → 跳转首页
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 13. 刷新令牌 API
|
||||
|
||||
**路由**：`POST /api/auth/refresh`
|
||||
|
||||
**处理流程**（`auth_controller.go` → `RefreshToken()`）：
|
||||
```
|
||||
1. 从 Cookie 读取 mlb_refresh
|
||||
→ 为空：401 "请重新登录"
|
||||
2. 调用 authService.RefreshAccessToken(refreshToken)
|
||||
→ 失败：ClearAuthCookies() + 401 "登录已过期"
|
||||
3. 成功：SetAccessCookie() → 下发新 access token
|
||||
→ 返回 200 { success: true }
|
||||
```
|
||||
|
||||
**注意**：此端点**只刷新 access token**，不刷新 refresh token。refresh token 有 30 天固定有效期，到期后用户需手动登录。这避免了无限续期带来的安全隐患（长期不活跃的 refresh token 最终会自然过期）。
|
||||
|
||||
---
|
||||
|
||||
## 二、解决方案建议
|
||||
|
||||
### 2.1 PostgreSQL 密码认证（问题一记录）
|
||||
|
||||
**系统信息**：
|
||||
- 分布：Linux Mint
|
||||
- 数据库用户：`metazone`
|
||||
- 连接方式：TCP `127.0.0.1:5432`（非 Unix socket）
|
||||
- 认证方式：`scram-sha-256`
|
||||
- 密码：`MetalabDev2026!`（存储于 `.env` → `DATABASE_PASSWORD`）
|
||||
- 数据库：`metalab_dev`
|
||||
|
||||
**验证命令**：
|
||||
```bash
|
||||
# 测试连接
|
||||
PGPASSWORD='MetalabDev2026!' psql -h 127.0.0.1 -U metazone -d metalab_dev -c "SELECT current_user, version();"
|
||||
```
|
||||
|
||||
### 2.2 .env 文件结构
|
||||
|
||||
```bash
|
||||
# 必填
|
||||
DATABASE_PASSWORD=MetalabDev2026!
|
||||
JWT_SECRET=p2BVUsELbny4W4sYNvoyFesyglD2TlPRT+bzpDk8Dq/E2s9tZFzT6jC8N3AvQpzE
|
||||
```
|
||||
|
||||
`.env` 已加入 `.gitignore`，提供 `.env.example` 模板文件。
|
||||
|
||||
---
|
||||
|
||||
## 三、代码规范新增/修改
|
||||
|
||||
### 3.1 新增规范
|
||||
|
||||
| 编号 | 规范 | 说明 |
|
||||
|---|---|---|
|
||||
| C01 | **`BuildPageData()` 统一模板数据注入** | 所有页面 Controller 必须通过此函数构建 `gin.H`，禁止手动拼装 `IsLoggedIn`/`Username` |
|
||||
| C02 | **Cookie 认证优先** | 使用 HttpOnly Cookie（`mlb_token`）传递 JWT，而非 `Authorization` Header，兼顾安全与 SSR |
|
||||
| C03 | **主键列名：`uid`** | Go 侧字段名 `ID`，GORM 标签 `column:uid`，JSON 序列化 `"uid"` |
|
||||
| C04 | **用户名：10 位随机 `[a-z0-9]`** | 使用 `crypto/rand`（非 `math/rand`），20 次重试去重 |
|
||||
| C05 | **配置 env 注入模式** | `.env` 文件通过 `os.Setenv()` 注入环境变量，Viper 通过 `BindEnv` + `AutomaticEnv` 读取。不再使用 viper 的 `.env` 文件加载 |
|
||||
| C06 | **模板名：相对路径** | `layout/header.html`、`auth/register.html` 等。禁止用纯文件名避免冲突 |
|
||||
|
||||
### 3.2 修改的已有规范
|
||||
|
||||
| 编号 | 变更 | 旧 | 新 |
|
||||
|---|---|---|---|
|
||||
| M01 | 用户标识字段 | `nickname`（非唯一） | `username`（全局唯一，varchar(16)） |
|
||||
| M02 | JSON 序列化字段名 | `"id"` | `"uid"` |
|
||||
| M03 | `BaseModel.ID` GORM 列名 | `id`（默认） | `uid`（`column:uid`） |
|
||||
|
||||
---
|
||||
|
||||
## 四、当前文件清单
|
||||
|
||||
### 后端（Go）
|
||||
|
||||
```
|
||||
internal/
|
||||
├── config/
|
||||
│ └── config.go # Config 结构体 + Load() + loadEnvFile() + DSN()
|
||||
│ # JWTConfig 含 AccessExpire/RefreshExpire/RememberExpire
|
||||
├── model/
|
||||
│ ├── common.go # BaseModel（uid 主键 + 时间戳 + 软删除）
|
||||
│ ├── user.go # User 结构体 + Role/Status 常量
|
||||
│ └── dto.go # RegisterRequest / LoginRequest 含 RememberMe
|
||||
├── repository/
|
||||
│ └── user_repo.go # UserRepo（Create/FindByEmail/FindByID/FindByUsername/ExistsByEmail/ExistsByUsername）
|
||||
├── service/
|
||||
│ └── auth_service.go # AuthService（Login/Register/RefreshAccessToken + buildToken/buildRefreshToken + 8 个错误哨兵）
|
||||
├── controller/
|
||||
│ └── auth_controller.go # AuthController（RegisterPage/LoginPage/Register/Login/Logout/RefreshToken/CheckEmail）
|
||||
├── middleware/
|
||||
│ └── auth.go # AuthRequired/AuthOptional/SetAuthCookies/SetAccessCookie/ClearAuthCookies/parseToken
|
||||
│ # 三个 Cookie：mlb_token / mlb_refresh / mlb_rm
|
||||
├── router/
|
||||
│ └── router.go # Setup() — 路由注册 + 依赖注入链（含 /auth/logout、/auth/refresh）
|
||||
├── common/
|
||||
│ └── helper.go # BuildPageData() — SSR 登录状态注入
|
||||
└── theme/
|
||||
└── loader.go # LoadTemplates() — 相对路径模板加载 + LoadContent()
|
||||
```
|
||||
|
||||
### 前端（模板 + 静态资源）
|
||||
|
||||
```
|
||||
templates/MetaLab-2026/
|
||||
├── html/
|
||||
│ ├── layout/
|
||||
│ │ ├── header.html # HTML head（title/meta/CSS 引入）
|
||||
│ │ ├── nav.html # 导航栏（已登录显示用户名+退出按钮 / 未登录显示登录按钮）
|
||||
│ │ └── footer.html # 页脚
|
||||
│ ├── auth/
|
||||
│ │ ├── register.html # 注册页（含准则模态框 + 60s 倒计时 + 记住我复选框）
|
||||
│ │ └── login.html # 登录页（简洁表单 + 记住我复选框）
|
||||
│ └── home/
|
||||
│ └── index.html # 首页（Hero 区域 + 欢迎信息）
|
||||
├── static/
|
||||
│ ├── css/
|
||||
│ │ ├── common.css # 全局样式 + NAV 样式（含 .nav-logout）
|
||||
│ │ └── auth.css # 认证页样式（表单、模态框、Toast、.remember-group/.remember-label/.remember-hint）
|
||||
│ └── js/
|
||||
│ ├── common.js # 通用工具（Toast + 登出 + 自动令牌刷新 + mlb_rm 检测）
|
||||
│ ├── register.js # 注册页逻辑（表单验证/AJAX 提交/准则模态框/倒计时/记住我）
|
||||
│ └── login.js # 登录页逻辑（表单验证/AJAX 提交/Toast/记住我）
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
|
||||
```
|
||||
config.yaml # 主配置（服务/数据库/JWT 含 remember_expire/BCrypt）
|
||||
.env # 敏感信息（密码/JWT密钥）→ .gitignore
|
||||
.env.example # 敏感信息模板（无真实值）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、待做事项
|
||||
|
||||
按优先级排序：
|
||||
|
||||
| 优先级 | 功能 | 状态 | 说明 |
|
||||
|---|---|---|---|
|
||||
| **P0** | 邮箱验证码 | 待做 | 注册时发送验证码（`auth/verify-email`），预留了路由和接口 |
|
||||
| ~~**P0**~~ | ~~登出功能~~ | ✅ 已完成 | `POST /api/auth/logout` → 清除三个 Cookie + 跳转首页 |
|
||||
| **P1** | 首页完善 | 待做 | 当前仅有 Hero 区域，需添加帖子列表、话题导航等 |
|
||||
| **P1** | 帖子系统 | 待做 | CRUD + 话题分类 + Markdown 编辑 |
|
||||
| **P1** | 用户设置页 | 待做 | `/settings` — 修改用户名/头像/密码/个人简介 |
|
||||
| **P2** | 管理后台 | 待做 | `/admin` — 用户管理、内容审核、主题切换 |
|
||||
| ~~**P2**~~ | ~~刷新令牌~~ | ✅ 已完成 | 记住我 + access/refresh 双 Token + 自动续期 + 登出 |
|
||||
| **P3** | 多主题支持 | 待做 | `MetaLab-2026` → `MetaLab-2027` 切换 |
|
||||
|
||||
---
|
||||
|
||||
## 六、约定速查
|
||||
|
||||
| 类别 | 约定 |
|
||||
|---|---|
|
||||
| 数据库主键 | Go: `ID uint`，DB: `uid`（bigint 自增），JSON: `"uid"` |
|
||||
| Access Token Cookie | `mlb_token`，JWT(HS256)，15 min，HttpOnly + Secure + SameSite=Lax |
|
||||
| Refresh Token Cookie | `mlb_refresh`，JWT(HS256)，30 day（记住我时），HttpOnly + Secure + SameSite=Lax，含 `purpose:"refresh"` 声明 |
|
||||
| 记住我标记 Cookie | `mlb_rm`，值 `"1"`，30 day（记住我时），非 HttpOnly（JS 可读），非凭据 |
|
||||
| 密码哈希 | bcrypt(12)，Go 字段 `PasswordHash`，JSON 不暴露 |
|
||||
| 用户名 | 10 位 `[a-z0-9]`，`crypto/rand` 生成，全局唯一 |
|
||||
| 角色 | `user` / `moderator` / `admin`（string，非 bool） |
|
||||
| 配置 | `.env` → `os.Setenv` → viper `BindEnv` + `AutomaticEnv` |
|
||||
| 模板名 | 相对路径：`layout/header.html`、`auth/register.html` |
|
||||
| API 响应 | `common.Ok(ctx, data)` / `common.Error(ctx, code, msg)` |
|
||||
| 页面数据 | `common.BuildPageData(c, extra)` — 自动注入 `IsLoggedIn` / `Username` |
|
||||
| 包依赖方向 | Router → Controller → Service → Repository → Model（不可反向） |
|
||||
| 令牌刷新 | `POST /api/auth/refresh`，前端每 10 min 静默调用 |
|
||||
Reference in New Issue
Block a user