shiyong.qin/EPEEAIKit

Fork 0

Files

Shin@HOME 47c0863bab 用户系统

2026-04-15 00:21:43 +08:00

16 KiB

Raw Blame History

EPEEKit 用户系统

本文档覆盖用户系统的技术架构、API 参考和日常使用指南。

架构概览

┌─────────────────────────────────────────────────────────┐
│  前端 (Next.js)                                          │
│                                                          │
│  AuthProvider → AuthGuard → AppProvider → 页面组件        │
│       │              │            │                       │
│  localStorage    /login 白名单   按 user_id 隔离存储      │
│  ├ epeekit-auth-token                                    │
│  ├ epeekit-refresh-token                                 │
│  └ epeekit-{userId}-sessions / tags / assets             │
└──────────────────────┬──────────────────────────────────┘
                       │ Authorization: Bearer <token>
                       ▼
┌─────────────────────────────────────────────────────────┐
│  后端 (FastAPI)                                          │
│                                                          │
│  /api/auth/*     ← 登录、刷新、改密（无需 token）          │
│  /api/admin/*    ← 用户管理（需管理员 token）              │
│  /api/chat       ← 对话（需 token，user_id 注入 Mem0）    │
│  /api/models     ← 模型列表（需 token）                   │
│  /api/upload-*   ← 上传（需 token）                       │
│                                                          │
│  存储：                                                   │
│  ├ data/epeekit.db   ← SQLite，users 表                  │
│  └ data/qdrant/      ← Mem0 向量库，按 user_id 隔离       │
└─────────────────────────────────────────────────────────┘

技术选型

组件	技术	说明
数据库	SQLite (SQLModel)	零部署，单文件 `data/epeekit.db`
密码哈希	Argon2id (pwdlib)	密码哈希竞赛冠军，抗 GPU/ASIC，兼容旧 bcrypt 哈希
令牌	JWT (python-jose)	无状态认证，HS256 签名
前端状态	React Context	AuthProvider + AuthGuard

令牌机制

Access Token：有效期 30 分钟，每个 API 请求携带
Refresh Token：有效期 7 天，用于在 access token 过期后无感刷新
JWT Payload 结构：{ sub: user_id, exp: timestamp, type: "access" | "refresh" }

快速开始

1. 配置环境变量

在 art-agent/backend/.env 中添加：

# 必填：JWT 签名密钥（随机字符串，建议 32+ 位）
JWT_SECRET=你的随机密钥

# 可选：首次启动时的管理员密码（不设则随机生成并打印到控制台）
# ADMIN_DEFAULT_PASSWORD=changeme123

2. 安装依赖

cd art-agent/backend
pip install -r requirements.txt

3. 启动后端

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

首次启动时，控制台会输出：

==================================================
  默认管理员账号已创建
  用户名: admin
  密码:   <随机生成的密码>
  请登录后尽快修改密码！
==================================================

请立即记录这个密码。 如果设置了 ADMIN_DEFAULT_PASSWORD，则使用该值，不会打印。

4. 登录

打开前端 http://localhost:3000，会自动跳转到登录页，使用 admin 账号登录。

5. 创建团队成员账号

登录后，使用管理员 API 创建其他用户（见用户管理操作手册）。

环境配置

后端环境变量

变量	必填	默认值	说明
`JWT_SECRET`	是	(无)	JWT 签名密钥，未设置时启动报错
`ADMIN_DEFAULT_PASSWORD`	否	(随机)	首次启动创建管理员时的密码

数据文件

路径	说明
`art-agent/backend/data/epeekit.db`	SQLite 数据库，包含 users 表
`art-agent/backend/data/qdrant/`	Mem0 向量数据，按 user_id 隔离

备份提示：定期备份 data/ 目录即可保全用户数据和记忆数据。

API 参考

所有接口基础路径为 http://localhost:8000。

认证接口

POST /api/auth/login

用户登录，获取令牌。

请求体 (JSON)：

{
  "username": "admin",
  "password": "your-password"
}

成功响应 (200)：

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user": {
    "id": "a1b2c3...",
    "username": "admin",
    "display_name": "管理员",
    "is_admin": true
  }
}

错误响应：

401 — 用户名或密码错误
403 — 账号已禁用

POST /api/auth/refresh

用 refresh token 换取新的 access token。

请求体 (JSON)：

{
  "refresh_token": "eyJ..."
}

成功响应 (200)：

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

POST /api/auth/change-password

修改当前用户密码。需要 Bearer Token。

请求体 (JSON)：

{
  "old_password": "current-password",
  "new_password": "new-password-min-6"
}

成功响应 (200)：

{
  "message": "密码已修改"
}

错误响应：

400 — 旧密码错误 / 新密码少于 6 位

GET /api/auth/me

获取当前登录用户的信息。需要 Bearer Token。

成功响应 (200)：

{
  "id": "a1b2c3...",
  "username": "admin",
  "display_name": "管理员",
  "is_admin": true
}

管理员接口

以下接口均需要管理员的 Bearer Token，普通用户调用返回 403。

POST /api/admin/users

创建新用户。

请求体 (JSON)：

{
  "username": "zhangsan",
  "password": "123456",
  "display_name": "张三",
  "is_admin": false
}

成功响应 (200)：

{
  "id": "d4e5f6...",
  "username": "zhangsan",
  "display_name": "张三",
  "is_admin": false,
  "is_active": true,
  "created_at": "2026-04-14T23:00:00"
}

错误响应：

409 — 用户名已存在
400 — 密码少于 6 位

GET /api/admin/users

获取所有用户列表。

成功响应 (200)：

[
  {
    "id": "a1b2c3...",
    "username": "admin",
    "display_name": "管理员",
    "is_admin": true,
    "is_active": true,
    "created_at": "2026-04-14T22:00:00"
  },
  ...
]

DELETE /api/admin/users/{user_id}

禁用指定用户（软删除，不物理删除）。

成功响应 (200)：

{
  "message": "用户 zhangsan 已禁用"
}

错误响应：

404 — 用户不存在
400 — 不能禁用自己

业务接口鉴权

以下已有接口现在需要 Bearer Token：

方法	路径	说明
POST	`/api/chat`	对话（user_id 自动从 token 注入）
POST	`/api/upload-ref-image`	上传参考图
GET	`/api/models`	获取模型列表

请求示例：

curl -X POST http://localhost:8000/api/chat \
  -H "Authorization: Bearer eyJ..." \
  -F "messages=[{\"role\":\"user\",\"content\":\"画一个图标\"}]"

未携带或令牌无效时返回 401。

前端认证流程

组件层级

<AuthProvider>        ← 管理 token、user 状态
  <AuthGuard>         ← 路由保护，未登录跳 /login
    <AppProvider>     ← 业务数据（按用户隔离的 localStorage）
      {children}      ← 页面内容
    </AppProvider>
  </AuthGuard>
</AuthProvider>

流程图

页面加载
  │
  ├─ 有 token？
  │    ├─ 调用 GET /api/auth/me 验证
  │    │    ├─ 200 → 认证通过，加载用户数据
  │    │    ├─ 401 → 尝试 refresh token
  │    │    │    ├─ 成功 → 获得新 access token，认证通过
  │    │    │    └─ 失败 → 清除 token，跳转 /login
  │    │    └─ 网络错误 → 保留本地缓存，允许离线查看
  │    └─ token 不存在 → 跳转 /login
  │
  └─ /login 页面
       └─ 提交用户名+密码
            ├─ 成功 → 保存 token，跳转 /
            └─ 失败 → 显示错误信息

Token 存储

localStorage Key	内容
`epeekit-auth-token`	JWT access token
`epeekit-refresh-token`	JWT refresh token
`epeekit-auth-user`	用户信息 JSON (id, username, display_name, is_admin)

401 自动处理

所有 API 请求（fetch 和 XMLHttpRequest）在收到 401 响应时，自动跳转到 /login。

数据隔离机制

后端（Mem0 记忆）

Mem0 的 user_id 参数从 JWT 中解析的真实用户 ID 传入：

# 之前（所有人共享）
search_kwargs = {"user_id": "default_user", ...}

# 现在（按用户隔离）
search_kwargs = {"user_id": current_user.id, ...}

每个用户的对话记忆完全独立，互不可见。

前端（localStorage）

所有 localStorage 键名加上用户 ID 前缀：

之前: epeekit-sessions
现在: epeekit-{userId}-sessions

完整键名表：

Key 模式	内容
`epeekit-{userId}-sessions`	对话会话列表
`epeekit-{userId}-tags`	自定义标签
`epeekit-{userId}-assets`	图片资源元数据
`epeekit-{userId}-selected-image-model`	模型选择偏好

登出时数据不清除，下次登录同一账号时自动恢复。切换用户时自动加载对应用户的数据。

用户管理操作手册

场景一：为新团队成员创建账号

使用管理员账号登录获取 token：

# 登录
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-admin-password"}'

# 记录返回的 access_token

创建用户：

curl -X POST http://localhost:8000/api/admin/users \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "zhangsan",
    "password": "initial-password",
    "display_name": "张三"
  }'

将用户名和初始密码告知成员，建议登录后立即修改密码。

场景二：查看所有用户

curl http://localhost:8000/api/admin/users \
  -H "Authorization: Bearer <admin-access-token>"

场景三：禁用一个用户

curl -X DELETE http://localhost:8000/api/admin/users/<user-id> \
  -H "Authorization: Bearer <admin-access-token>"

被禁用的用户：

无法登录
已有的 token 在下次请求时被拒绝
数据保留（不物理删除）

场景四：用户修改自己的密码

curl -X POST http://localhost:8000/api/auth/change-password \
  -H "Authorization: Bearer <user-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "current-password",
    "new_password": "new-secure-password"
  }'

场景五：使用 FastAPI 交互式文档

后端启动后，访问 http://localhost:8000/docs 可以看到 Swagger UI：

点击右上角 "Authorize" 按钮
输入用户名和密码进行认证
之后可以直接在页面上调试所有 API

安全说明

已实施的安全措施

Argon2id 密码哈希：密码哈希竞赛冠军算法，抗 GPU/ASIC 攻击，即使数据库泄露也无法直接获取密码
JWT 签名：令牌使用 HS256 签名，无法伪造
令牌过期：access token 30 分钟过期，refresh token 7 天过期
不开放注册：只有管理员可以创建账号
软删除：禁用用户而非删除，保留审计轨迹

当前限制

CORS 全开 (allow_origins=["*"])：适合内部使用和开发阶段，生产部署时应改为具体域名
无速率限制：登录接口没有防暴力破解的限流机制，内部网络可接受
SQLite 单写：高并发写入时可能遇到锁，内部团队规模不会触及
无审计日志：未记录登录/操作日志，可后续添加

JWT_SECRET 安全

必须使用足够长的随机字符串（建议 32+ 字符）
不要提交到 Git（.env 文件应在 .gitignore 中）
更换 JWT_SECRET 会使所有已发放的令牌失效，所有用户需要重新登录

故障排除

启动报错 "JWT_SECRET 环境变量未设置"

在 .env 中添加 JWT_SECRET=<随机字符串> 后重启。

忘记管理员密码

删除数据库文件后重启，会重新创建默认管理员：

rm art-agent/backend/data/epeekit.db
# 重启后端，新密码会打印到控制台

注意：这会丢失所有用户数据。如果只想重置管理员密码，可以用 Python 脚本直接更新：

from app.db import engine, User
from app.auth import hash_password
from sqlmodel import Session, select

with Session(engine) as s:
    admin = s.exec(select(User).where(User.username == "admin")).first()
    admin.hashed_password = hash_password("new-password")
    s.add(admin)
    s.commit()

前端一直跳转到登录页

检查后端是否正常运行（curl http://localhost:8000/health）
检查浏览器控制台是否有 CORS 或网络错误
清除浏览器 localStorage 中的 epeekit-auth-* 键后重试

登录后看不到之前的对话

用户系统上线后，localStorage 的键名格式变为 epeekit-{userId}-sessions。之前无用户系统时的数据存在旧键名 epeekit-sessions 下。如需迁移：

打开浏览器开发者工具 → Application → Local Storage
找到 epeekit-sessions 的值并复制
创建新键 epeekit-<你的userId>-sessions，粘贴值
刷新页面

多人使用同一浏览器

每个用户登录后，对话数据按 user_id 隔离存储在 localStorage 中。切换账号时自动加载对应用户的数据，互不影响。退出登录不会清除数据，下次登录仍可恢复。

源码结构

art-agent/backend/
├── app/
│   ├── db.py              ← SQLite 连接、User 模型、建表、默认管理员
│   ├── auth.py            ← Argon2id 密码哈希、JWT 编解码、FastAPI 依赖
│   ├── api/
│   │   ├── auth.py        ← 登录/刷新/改密/me 路由
│   │   ├── admin.py       ← 创建/列表/禁用用户路由
│   │   └── chat.py        ← 已有对话路由（已加鉴权）
│   ├── agent/
│   │   └── loop.py        ← Agent Loop（user_id 透传 Mem0）
│   └── main.py            ← 应用入口、路由注册、启动初始化
└── data/
    ├── epeekit.db          ← 用户数据库
    └── qdrant/             ← Mem0 向量存储

art-agent/frontend/src/
├── lib/
│   ├── auth-context.tsx    ← AuthProvider：token 管理、login/logout
│   ├── auth-guard.tsx      ← AuthGuard：路由保护
│   ├── app-context.tsx     ← AppProvider：按用户加载业务数据
│   ├── api.ts              ← API 封装（自动带 Authorization 头）
│   └── store.ts            ← localStorage 封装（按 user_id 隔离键名）
├── app/
│   ├── layout.tsx          ← AuthProvider → AuthGuard → AppProvider
│   └── login/
│       └── page.tsx        ← 登录页面
└── components/layout/
    └── top-nav.tsx         ← 顶部导航（含用户菜单 + 退出登录）

16 KiB Raw Blame History Unescape Escape

EPEEKit 用户系统

目录

架构概览

技术选型

令牌机制

快速开始

1. 配置环境变量

2. 安装依赖

3. 启动后端

4. 登录

5. 创建团队成员账号

环境配置

后端环境变量

数据文件

API 参考

认证接口

POST /api/auth/login

POST /api/auth/refresh

POST /api/auth/change-password

GET /api/auth/me

管理员接口

POST /api/admin/users

GET /api/admin/users

DELETE /api/admin/users/{user_id}

业务接口鉴权

前端认证流程

组件层级

流程图

Token 存储

401 自动处理

数据隔离机制

后端（Mem0 记忆）

前端（localStorage）

用户管理操作手册

场景一：为新团队成员创建账号

场景二：查看所有用户

场景三：禁用一个用户

场景四：用户修改自己的密码

场景五：使用 FastAPI 交互式文档

安全说明

已实施的安全措施

当前限制

JWT_SECRET 安全

故障排除

启动报错 "JWT_SECRET 环境变量未设置"

忘记管理员密码

前端一直跳转到登录页

登录后看不到之前的对话

多人使用同一浏览器

源码结构

16 KiB

Raw Blame History