feat: 新增用户管理（用户增删改查、密码重置、角色权限、会话认证）与 API 指南

- 新增 app/api/deps.py、app/core/users.py、app/core/sessions.py：会话鉴权依赖、用户存储（PBKDF2-HMAC-SHA256 + 随机 salt，Redis/内存降级）、会话签发与校验（TTL 12h） - auth.py 新增用户管理端点（列表/创建/重置密码/删除）与 admin/user 角色权限边界， user 访问用户管理返回 1006，禁删自己与最后一个 admin - admin.html 新增用户管理面板（仅 admin 挂载）与 API 指南在线测试台 - Dockerfile 将 uv 放入 PATH；docker-compose 调整 qdrant 依赖为 service_started 并移除依赖 curl 的 healthcheck（官方镜像不含 curl） - 新增用户管理测试（users/sessions/auth_api/auth_integration），全量 461 项测试通过 Co-Authored-By: WorkBuddy <workbuddy@tencent.com>
2026-07-31 21:29:02 +08:00
parent 2ab8b56a01
commit 92b062c048
24 changed files with 2771 additions and 350 deletions
@@ -1,62 +1,192 @@
-"""认证 API：POST /auth/login、POST /auth/register、GET /auth/me"""
+"""认证与用户管理 API：/api/v1/auth 下的登录/退出/改密与用户管理端点

-from typing import Any
+会话制认证：登录签发 session token（存储见 app/core/sessions.py，TTL 12h），
+请求经 Authorization: Bearer <token> 携带，鉴权依赖见 app/api/deps.py。
+用户管理端点（/users*）全部要求 admin 角色；/logout 与 /password 对
+must_change_password 用户放行（改密是被拦截用户唯一能用的接口）。
+"""
+
+from typing import Any, Literal

 import structlog
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Header
+from pydantic import BaseModel

+from app.api import deps
 from app.api.response import ApiError, ok
-from app.config import settings
-from app.core.auth import (
-    ERR_REGISTER_DISABLED,
-    UserStore,
-    create_access_token,
-    get_current_user,
-    get_user_store,
-)
-from app.models.auth import (
-    AuthUser,
-    LoginRequest,
-    RegisterRequest,
-    TokenResponse,
-)
+from app.core.sessions import SessionStoreError
+from app.core.users import UserExistsError, UserRecord, UserStoreError

 logger = structlog.get_logger()

-router = APIRouter(prefix="/api/v1", tags=["auth"])
+router = APIRouter(prefix="/api/v1/auth", tags=["auth"])


-def _build_token_response(user, store: UserStore) -> dict[str, Any]:
-    """签发 token 并构造统一响应 data"""
-    token, expires_in = create_access_token(user.username, user.role)
-    auth_user = AuthUser(username=user.username, role=user.role, created_at=user.created_at)
-    resp = TokenResponse(access_token=token, expires_in=expires_in, user=auth_user)
-    return resp.model_dump(mode="json")
+class LoginRequest(BaseModel):
+    """登录请求"""
+
+    username: str
+    password: str


-@router.post("/auth/login")
+class PasswordChangeRequest(BaseModel):
+    """修改自己的密码"""
+
+    old_password: str
+    new_password: str
+
+
+class UserCreateRequest(BaseModel):
+    """管理员创建用户"""
+
+    username: str
+    password: str
+    role: Literal["admin", "user"] = "user"
+
+
+class PasswordResetRequest(BaseModel):
+    """管理员重置他人密码"""
+
+    new_password: str
+
+
+def _public_user(user: UserRecord) -> dict[str, Any]:
+    """用户记录脱敏：剔除 password_hash/salt"""
+    return {
+        "username": user.username,
+        "role": user.role,
+        "must_change_password": user.must_change_password,
+        "created_at": user.created_at,
+    }
+
+
+@router.post("/login")
 async def login(req: LoginRequest) -> dict[str, Any]:
-    """用户名密码登录，返回 JWT access_token"""
-    store = get_user_store()
-    user = await store.authenticate(req.username, req.password)
+    """用户名密码登录：成功签发 session token（must_change_password 用户也可登录）"""
+    try:
+        user = await deps._get_user_store().verify_password(req.username, req.password)
+    except UserStoreError as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    if user is None:
+        raise ApiError(1005, "用户名或密码错误")
+    try:
+        token = await deps._get_session_store().create(user.username, user.role)
+    except SessionStoreError as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
    logger.info("用户登录成功", username=user.username)
-    return ok(_build_token_response(user, store))
+    return ok(
+        {
+            "token": token,
+            "username": user.username,
+            "role": user.role,
+            "must_change_password": user.must_change_password,
+        }
+    )


-@router.post("/auth/register")
-async def register(req: RegisterRequest) -> dict[str, Any]:
-    """注册新用户（role=user），注册后自动签发 token
+@router.get("/me")
+async def me(user: UserRecord = Depends(deps.get_current_user)) -> dict[str, Any]:
+    """返回当前登录用户信息（脱敏），供管理页面校验登录态"""
+    return ok(_public_user(user))

-    受 settings.auth_register_enabled 控制，关闭时返回 ERR_REGISTER_DISABLED。
+
+@router.post("/logout")
+async def logout(authorization: str | None = Header(None)) -> dict[str, Any]:
+    """退出登录：删除当前 session（自解析 Bearer，不拦截 must_change_password）"""
+    _, token = await deps._resolve_user(authorization)
+    try:
+        await deps._get_session_store().delete(token)
+    except SessionStoreError as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    return ok({"logged_out": True})
+
+
+@router.post("/password")
+async def change_password(
+    req: PasswordChangeRequest, authorization: str | None = Header(None)
+) -> dict[str, Any]:
+    """修改自己的密码（自解析 Bearer，不拦截 must_change_password——这是被拦截用户唯一可用接口）
+
+    旧密码错误 1005；新密码不足 8 位 1001。改密不清除既有 session（Task1 语义）。
    """
-    if not settings.auth_register_enabled:
-        raise ApiError(ERR_REGISTER_DISABLED, "注册已关闭")
-    store = get_user_store()
-    user = await store.create(req.username, req.password, role="user")
-    return ok(_build_token_response(user, store))
+    user, _ = await deps._resolve_user(authorization)
+    store = deps._get_user_store()
+    try:
+        verified = await store.verify_password(user.username, req.old_password)
+        if verified is None:
+            raise ApiError(1005, "旧密码错误")
+        await store.set_password(user.username, req.new_password)
+    except (UserStoreError, SessionStoreError) as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    except ValueError as exc:
+        raise ApiError(1001, str(exc)) from exc
+    logger.info("用户修改密码", username=user.username)
+    return ok({"username": user.username})


-@router.get("/auth/me")
-async def me(user: AuthUser = Depends(get_current_user)) -> dict[str, Any]:
-    """返回当前登录用户信息"""
-    return ok(user.model_dump(mode="json"))
+@router.get("/users")
+async def list_users(admin: UserRecord = Depends(deps.require_admin)) -> dict[str, Any]:
+    """列出全部用户（脱敏：不含 password_hash/salt）"""
+    try:
+        users = await deps._get_user_store().list()
+    except UserStoreError as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    return ok([_public_user(user) for user in users])
+
+
+@router.post("/users")
+async def create_user(
+    req: UserCreateRequest, admin: UserRecord = Depends(deps.require_admin)
+) -> dict[str, Any]:
+    """创建用户：重名/非法用户名/弱密码 1001；成功返回脱敏后的创建记录"""
+    try:
+        user = await deps._get_user_store().create(req.username, req.password, role=req.role)
+    except UserExistsError as exc:
+        raise ApiError(1001, str(exc)) from exc
+    except ValueError as exc:
+        raise ApiError(1001, str(exc)) from exc
+    except UserStoreError as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    logger.info("管理员创建用户", username=user.username, role=user.role, operator=admin.username)
+    return ok(_public_user(user))
+
+
+@router.post("/users/{username}/password")
+async def reset_user_password(
+    username: str, req: PasswordResetRequest, admin: UserRecord = Depends(deps.require_admin)
+) -> dict[str, Any]:
+    """重置指定用户密码：用户不存在 1004；成功后清除该用户全部 session"""
+    store = deps._get_user_store()
+    try:
+        if await store.get(username) is None:
+            raise ApiError(1004, "用户不存在")
+        await store.set_password(username, req.new_password)
+        await deps._get_session_store().delete_by_username(username)
+    except (UserStoreError, SessionStoreError) as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    except ValueError as exc:
+        raise ApiError(1001, str(exc)) from exc
+    logger.info("管理员重置用户密码", username=username, operator=admin.username)
+    return ok({"username": username})
+
+
+@router.delete("/users/{username}")
+async def delete_user(
+    username: str, admin: UserRecord = Depends(deps.require_admin)
+) -> dict[str, Any]:
+    """删除用户：不存在 1004；删除自己 1001；最后一个 admin 禁止删除 1001；成功后清除其 session"""
+    store = deps._get_user_store()
+    try:
+        target = await store.get(username)
+        if target is None:
+            raise ApiError(1004, "用户不存在")
+        if target.username == admin.username:
+            raise ApiError(1001, "不能删除当前登录账号")
+        if target.role == "admin" and await store.count_admins() <= 1:
+            raise ApiError(1001, "禁止删除最后一个管理员")
+        await store.delete(username)
+        await deps._get_session_store().delete_by_username(username)
+    except (UserStoreError, SessionStoreError) as exc:
+        raise ApiError(2001, "认证服务暂不可用") from exc
+    logger.info("管理员删除用户", username=username, operator=admin.username)
+    return ok({"username": username})