126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# 用户账号系统设计
|
||
|
||
**日期：** 2026-06-15
|
||
**状态：** 已批准
|
||
|
||
## 背景
|
||
|
||
项目现状：Vue 前端 + Hono/Bun 后端 + SQLite，所有数据对任何人开放访问，无任何认证。目标是加入登录门禁，防止陌生人访问，但所有登录用户共享同一份数据。
|
||
|
||
## 核心决策
|
||
|
||
- 多用户账号，存数据库，管理员创建账号（不开放注册）
|
||
- access token（JWT，15分钟）+ refresh token（随机UUID入库，7天）双 token 方案
|
||
- refresh token hash 后存库，支持撤销
|
||
|
||
---
|
||
|
||
## 一、数据库 Schema
|
||
|
||
在现有 `books` 表旁新增两张表，在 `server/db.ts` 的 `SCHEMA` 中追加：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS users (
|
||
id TEXT PRIMARY KEY,
|
||
username TEXT NOT NULL UNIQUE,
|
||
password_hash TEXT NOT NULL,
|
||
role TEXT NOT NULL DEFAULT 'user',
|
||
created_at TEXT NOT NULL
|
||
);
|
||
|
||
CREATE TABLE IF NOT EXISTS refresh_tokens (
|
||
id TEXT PRIMARY KEY,
|
||
user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||
token_hash TEXT NOT NULL,
|
||
expires_at TEXT NOT NULL,
|
||
created_at TEXT NOT NULL
|
||
);
|
||
```
|
||
|
||
**初始 admin 账号：** 服务启动时读取环境变量 `ADMIN_USERNAME` / `ADMIN_PASSWORD`，若 users 表中不存在该用户名则自动写入。密码用 bcrypt hash 存储。
|
||
|
||
---
|
||
|
||
## 二、服务端 API
|
||
|
||
### 新增文件
|
||
|
||
- `server/auth.ts` — JWT 签发/验证、bcrypt、token CRUD 的纯函数
|
||
- `server/middleware/auth.ts` — Hono 中间件（验证 Bearer token，注入 user 到 context）
|
||
- `server/routes/auth.ts` — `/api/auth/*` 路由
|
||
- `server/routes/admin.ts` — `/api/admin/*` 路由
|
||
|
||
### 端点列表
|
||
|
||
| 方法 | 路径 | 说明 | 认证要求 |
|
||
|------|------|------|----------|
|
||
| POST | `/api/auth/login` | 登录，返回 access + refresh token | 无 |
|
||
| POST | `/api/auth/refresh` | 换新 access token | 无（带 refresh token） |
|
||
| POST | `/api/auth/logout` | 撤销当前 refresh token | Bearer |
|
||
| GET | `/api/auth/me` | 返回当前用户信息 | Bearer |
|
||
| GET | `/api/admin/users` | 列出所有用户 | Admin only |
|
||
| POST | `/api/admin/users` | 创建新用户 | Admin only |
|
||
| DELETE | `/api/admin/users/:id` | 删除用户 | Admin only |
|
||
|
||
### 现有路由保护
|
||
|
||
`/api/books/*` 和 `/api/generate/*` 全部加上 auth 中间件，未认证返回 401。
|
||
|
||
### Token 规格
|
||
|
||
- **access token**：JWT，HS256，payload `{ userId, role, exp: now+15min }`，密钥来自环境变量 `JWT_SECRET`
|
||
- **refresh token**：`crypto.randomUUID()`，SHA-256 hash 后存 `refresh_tokens` 表，原始值返回给客户端
|
||
|
||
---
|
||
|
||
## 三、前端
|
||
|
||
### 新增文件
|
||
|
||
- `src/composables/useAuth.ts` — token 管理、登录/登出/刷新逻辑
|
||
- `src/components/LoginPage.vue` — 登录表单
|
||
- `src/components/AdminPage.vue` — 用户管理页（admin 专属）
|
||
|
||
### 修改文件
|
||
|
||
- `src/App.vue` — 根据登录状态切换渲染 LoginPage 或主应用
|
||
- `src/services/booksApi.ts` — 所有请求加 `Authorization` header，401 时触发 refresh
|
||
|
||
### useAuth composable 行为
|
||
|
||
- localStorage 存 `access_token` 和 `refresh_token`
|
||
- 导出：`isLoggedIn`（computed）、`user`（ref）、`login()`、`logout()`
|
||
- 提供 `authedFetch()` 封装：自动带 token，遇 401 先尝试 refresh，refresh 失败则清除 token 跳登录页
|
||
|
||
### AdminPage
|
||
|
||
- 仅当 `user.role === 'admin'` 时在主界面显示入口
|
||
- 功能：列出所有用户、创建账号（用户名+密码）、删除账号（不能删除自己）
|
||
|
||
---
|
||
|
||
## 四、环境变量
|
||
|
||
`.env` 新增：
|
||
|
||
```
|
||
JWT_SECRET=<随机长字符串>
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=<初始密码>
|
||
```
|
||
|
||
---
|
||
|
||
## 五、依赖
|
||
|
||
- `jsonwebtoken` 或 Hono 自带的 `hono/jwt` — JWT 操作
|
||
- `bcryptjs` — 密码 hash（纯 JS，兼容 Bun）
|
||
|
||
---
|
||
|
||
## 六、不在本次范围内
|
||
|
||
- 修改密码功能
|
||
- 邮件验证
|
||
- 多 admin 角色权限细分
|