feat(admin): owner 端用户管理 API + 页面

- 后端新增 /admin/users 路由(仅 owner): - GET /admin/users 列出全部用户 - POST /admin/users 创建新用户(固定 role=member,API 层禁止提权) - PATCH /admin/users/{id} 重置密码 / 启停 / 改昵称 / 改邮箱 (role 永远不可改,owner 不能禁用自己) - DELETE /admin/users/{id} 软删除(is_active=False,保留外键完整性) - 用户管理用软删除而非硬删除,理由: bookmarks / subscriptions / api_tokens / article_reads 都有 user_id 外键, 硬删会污染历史数据;禁用后用户登不上,效果等同删除且可恢复 - 后端永远不返回 password_hash(UserOut 不含该字段) - 前端 AdminUsers.vue + 路由 /admin/users + 侧栏菜单'用户管理(Admin)' 操作按钮对自己 / owner 自动隐藏(自锁 + 防误改,后端兜底拒绝) - main.py 注册 admin_users 路由 - schemas/user.py 提供 UserOut/UserCreate/UserUpdate/UserDeleteResult - articles.ts adminApi 加 listUsers / createUser / updateUser / deleteUser + UserOut 类型无 alembic 迁移(user 表 role / is_active / email / display_name 字段早就有)
2026-06-17 07:34:57 +08:00
parent b20fcb9c3c
commit 43bae9b1ea
7 changed files with 590 additions and 1 deletions
--- a/backend/app/api/admin_users.py
+++ b/backend/app/api/admin_users.py
@@ -0,0 +1,197 @@
+"""Owner 端用户管理 API。
+
+- GET    /admin/users           - 列出全部用户
+- POST   /admin/users           - 创建 member(固定角色,不允许创建 owner)
+- PATCH  /admin/users/{id}      - 重置密码 / 启停 / 改昵称 / 改邮箱(role 永远不可改)
+- DELETE /admin/users/{id}      - 软删除(置 is_active=False;保留外键完整性)
+
+设计原则:
+- 软删除而非硬删除:用户有 bookmarks / subscriptions / api_tokens / article_reads 等外键,
+  硬删会污染历史数据(收藏的"作者"凭空消失)。禁用后无法登录,效果等同删除,可恢复。
+- 不允许 owner 把自己禁用/删除,避免自锁。
+- API 层禁止提权:不能创建 owner,不能修改 role。
+- 列表/详情绝不返回 password_hash。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import require_owner
+from app.core.security import hash_password
+from app.database import get_session
+from app.models.user import User, UserRole
+from app.schemas.user import UserCreate, UserDeleteResult, UserOut, UserUpdate
+
+router = APIRouter(
+    prefix="/admin/users",
+    tags=["admin"],
+    dependencies=[Depends(require_owner)],
+)
+
+logger = logging.getLogger("news.admin.users")
+
+
+def _to_out(u: User) -> UserOut:
+    return UserOut.model_validate(u)
+
+
+@router.get("", response_model=list[UserOut])
+async def list_users(session: AsyncSession = Depends(get_session)):
+    """列出全部用户(含已禁用)。按 id 升序。"""
+    result = await session.execute(select(User).order_by(User.id))
+    return [_to_out(u) for u in result.scalars()]
+
+
+@router.post(
+    "",
+    response_model=UserOut,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_user(
+    body: UserCreate,
+    session: AsyncSession = Depends(get_session),
+    actor: User = Depends(require_owner),
+):
+    """创建 member。role 固定为 member,前端不需要传(后端兜底)。"""
+    # 防御性兜底:即便 schemas 接受 owner,这里也强制锁住 member
+    u = User(
+        username=body.username,
+        email=body.email,
+        password_hash=hash_password(body.password),
+        role=UserRole.MEMBER,
+        is_active=True,
+        display_name=body.display_name,
+    )
+    session.add(u)
+    try:
+        await session.commit()
+    except IntegrityError as e:
+        await session.rollback()
+        # username 或 email 唯一冲突
+        msg = str(e.orig).lower()
+        if "username" in msg:
+            raise HTTPException(
+                status.HTTP_409_CONFLICT,
+                f"用户名 '{body.username}' 已存在",
+            ) from e
+        if "email" in msg:
+            raise HTTPException(
+                status.HTTP_409_CONFLICT,
+                f"邮箱 '{body.email}' 已被使用",
+            ) from e
+        raise HTTPException(status.HTTP_409_CONFLICT, "用户已存在") from e
+
+    await session.refresh(u)
+    logger.info(
+        "user created: id=%s username=%s by owner_id=%s",
+        u.id, u.username, actor.id,
+    )
+    return _to_out(u)
+
+
+@router.patch("/{user_id}", response_model=UserOut)
+async def update_user(
+    user_id: int,
+    body: UserUpdate,
+    session: AsyncSession = Depends(get_session),
+    actor: User = Depends(require_owner),
+):
+    """修改用户:重置密码 / 启停 / 改昵称 / 改邮箱。
+    - role 永远不能改(防越权)
+    - owner 不能禁用自己(防自锁)
+    """
+    result = await session.execute(select(User).where(User.id == user_id))
+    u = result.scalar_one_or_none()
+    if not u:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "用户不存在")
+
+    data = body.model_dump(exclude_unset=True)
+
+    # 自锁保护
+    if data.get("is_active") is False and u.id == actor.id:
+        raise HTTPException(
+            status.HTTP_400_BAD_REQUEST,
+            "不能禁用自己",
+        )
+
+    # 永远不接收 role 字段(就算有人塞进来也忽略)
+    data.pop("role", None)
+
+    if "password" in data and data["password"]:
+        u.password_hash = hash_password(data.pop("password"))
+    elif "password" in data:
+        # 空串 = 不改
+        data.pop("password")
+
+    for k, v in data.items():
+        setattr(u, k, v)
+
+    try:
+        await session.commit()
+    except IntegrityError as e:
+        await session.rollback()
+        msg = str(e.orig).lower()
+        if "email" in msg:
+            raise HTTPException(
+                status.HTTP_409_CONFLICT,
+                f"邮箱 '{data.get('email')}' 已被使用",
+            ) from e
+        raise HTTPException(status.HTTP_409_CONFLICT, "更新冲突") from e
+
+    await session.refresh(u)
+    logger.info(
+        "user updated: id=%s username=%s fields=%s by owner_id=%s",
+        u.id, u.username, sorted(data.keys()), actor.id,
+    )
+    return _to_out(u)
+
+
+@router.delete("/{user_id}", response_model=UserDeleteResult)
+async def delete_user(
+    user_id: int,
+    session: AsyncSession = Depends(get_session),
+    actor: User = Depends(require_owner),
+):
+    """软删除用户(置 is_active=False)。
+
+    - owner 不能删除自己
+    - 已经是 inactive 的:返回 200 + already_inactive=True
+    - 不删除 owner(防止误删唯一管理员导致失联)
+    """
+    result = await session.execute(select(User).where(User.id == user_id))
+    u = result.scalar_one_or_none()
+    if not u:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "用户不存在")
+
+    if u.id == actor.id:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "不能删除自己")
+    if u.role == UserRole.OWNER:
+        raise HTTPException(
+            status.HTTP_400_BAD_REQUEST,
+            "不能删除 owner(防失联;请直接在服务器上调整)",
+        )
+    if not u.is_active:
+        return UserDeleteResult(
+            id=u.id,
+            username=u.username,
+            is_active=False,
+            detail="用户已经是禁用状态",
+        )
+
+    u.is_active = False
+    await session.commit()
+    logger.info(
+        "user soft-deleted (deactivated): id=%s username=%s by owner_id=%s",
+        u.id, u.username, actor.id,
+    )
+    return UserDeleteResult(
+        id=u.id,
+        username=u.username,
+        is_active=False,
+        detail=f"已禁用用户 '{u.username}'(可重新启用)",
+    )
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -16,7 +16,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from starlette.exceptions import HTTPException as StarletteHTTPException

-from app.api import admin, admin_llm, articles, auth, bookmarks, ingest, me, search, sources, subscriptions
+from app.api import admin, admin_llm, admin_users, articles, auth, bookmarks, ingest, me, search, sources, subscriptions
 from app.config import settings
 from app.database import engine
 from app.redis_client import close_redis, get_redis
@@ -103,6 +103,7 @@ app.include_router(ingest.router, prefix=API_PREFIX)
 app.include_router(search.router, prefix=API_PREFIX)
 app.include_router(admin.router, prefix=API_PREFIX)
 app.include_router(admin_llm.router, prefix=API_PREFIX)
+app.include_router(admin_users.router, prefix=API_PREFIX)


 # === 健康检查 ===
--- a/backend/app/schemas/user.py
+++ b/backend/app/schemas/user.py
@@ -0,0 +1,64 @@
+"""User schemas(用于 owner 端管理用户)。"""
+from __future__ import annotations
+
+import re
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
+
+from app.models.user import UserRole
+
+# 用户名规则:3-32 字符,小写字母 / 数字 / 下划线 / 连字符;首字符必须为字母或数字
+# 与 create_user.py 的 CLI 行为保持一致(允许任意大小写),但前端界面化时引导用小写
+_USERNAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{2,31}$")
+
+
+class UserOut(BaseModel):
+    """用户列表 / 详情(永远不返回 password_hash)。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    username: str
+    email: str | None = None
+    role: UserRole
+    is_active: bool
+    display_name: str | None = None
+    created_at: datetime
+    last_login_at: datetime | None = None
+
+
+class UserCreate(BaseModel):
+    """owner 创建新用户。固定 role=member(不允许提权)。"""
+
+    username: str = Field(min_length=3, max_length=32)
+    password: str = Field(min_length=6, max_length=128)
+    email: EmailStr | None = None
+    display_name: str | None = Field(default=None, max_length=128)
+
+    @field_validator("username")
+    @classmethod
+    def _v_username(cls, v: str) -> str:
+        if not _USERNAME_RE.match(v):
+            raise ValueError(
+                "用户名只能包含小写字母、数字、下划线、连字符,且首字符必须为字母或数字(3-32 字符)"
+            )
+        return v
+
+
+class UserUpdate(BaseModel):
+    """owner 修改用户。重置密码 / 启停 / 改昵称 / 改邮箱。role 永远不可改(防越权)。"""
+
+    password: str | None = Field(default=None, min_length=6, max_length=128)
+    is_active: bool | None = None
+    email: EmailStr | None = None
+    display_name: str | None = Field(default=None, max_length=128)
+
+
+class UserDeleteResult(BaseModel):
+    """软删除响应 — 实际是禁用,user_id 用于前端确认。"""
+
+    id: int
+    username: str
+    is_active: bool
+    detail: str
--- a/frontend/src/api/articles.ts
+++ b/frontend/src/api/articles.ts
@@ -260,6 +260,42 @@ export const adminApi = {
      `/admin/ingest-tokens/${tokenId}`
    ).then((r) => r.data)
  },
+  // === 用户管理(仅 owner)===
+  listUsers() {
+    return http.get<UserOut[]>('/admin/users').then((r) => r.data)
+  },
+  createUser(body: {
+    username: string
+    password: string
+    email?: string
+    display_name?: string
+  }) {
+    return http.post<UserOut>('/admin/users', body).then((r) => r.data)
+  },
+  updateUser(id: number, body: {
+    password?: string
+    is_active?: boolean
+    email?: string | null
+    display_name?: string | null
+  }) {
+    return http.patch<UserOut>(`/admin/users/${id}`, body).then((r) => r.data)
+  },
+  deleteUser(id: number) {
+    return http.delete<{ id: number; username: string; is_active: boolean; detail: string }>(
+      `/admin/users/${id}`
+    ).then((r) => r.data)
+  },
+}
+
+export interface UserOut {
+  id: number
+  username: string
+  email?: string | null
+  role: 'owner' | 'member'
+  is_active: boolean
+  display_name?: string | null
+  created_at: string
+  last_login_at?: string | null
 }

 export interface IngestTokenOut {
--- a/frontend/src/components/AppLayout.vue
+++ b/frontend/src/components/AppLayout.vue
@@ -37,6 +37,7 @@ const menu = computed(() => [
  { key: '/bookmarks', label: '收藏', icon: () => '⭐' },
  ...(auth.isOwner ? [
    { key: '/admin/sources', label: '源管理(Admin)', icon: () => '🛠' },
+    { key: '/admin/users', label: '用户管理(Admin)', icon: () => '👥' },
    { key: '/admin/llm', label: 'LLM 智能增强', icon: () => '🤖' },
  ] : []),
 ])
--- a/frontend/src/router.ts
+++ b/frontend/src/router.ts
@@ -13,6 +13,7 @@ const routes: RouteRecordRaw[] = [
      { path: 'sources', component: () => import('@/views/Sources.vue') },
      { path: 'bookmarks', component: () => import('@/views/Bookmarks.vue') },
      { path: 'admin/sources', component: () => import('@/views/AdminSources.vue'), meta: { ownerOnly: true } },
+      { path: 'admin/users', component: () => import('@/views/AdminUsers.vue'), meta: { ownerOnly: true } },
      { path: 'admin/llm', component: () => import('@/views/AdminLlmSettings.vue'), meta: { ownerOnly: true } },
    ],
  },
--- a/frontend/src/views/AdminUsers.vue
+++ b/frontend/src/views/AdminUsers.vue
@@ -0,0 +1,289 @@
+<script setup lang="ts">
+import { onMounted, ref, h, computed } from 'vue'
+import {
+  NCard, NDataTable, NButton, NTag, NSpace, useMessage, useDialog,
+  NModal, NForm, NFormItem, NInput, NAlert,
+} from 'naive-ui'
+import { adminApi, type UserOut } from '@/api/articles'
+import { useAuthStore } from '@/stores/auth'
+
+const message = useMessage()
+const dialog = useDialog()
+const auth = useAuthStore()
+
+const users = ref<UserOut[]>([])
+const loading = ref(false)
+
+async function load() {
+  loading.value = true
+  try {
+    users.value = await adminApi.listUsers()
+  } catch (e: any) {
+    message.error(e?.response?.data?.title || '加载用户列表失败')
+  } finally {
+    loading.value = false
+  }
+}
+
+// === 新增用户 ===
+const showCreate = ref(false)
+const createForm = ref({
+  username: '',
+  password: '',
+  email: '',
+  display_name: '',
+})
+const creating = ref(false)
+
+function openCreate() {
+  createForm.value = { username: '', password: '', email: '', display_name: '' }
+  showCreate.value = true
+}
+
+async function doCreate() {
+  const u = createForm.value.username.trim()
+  const p = createForm.value.password
+  if (!u || !p) {
+    message.error('请填写用户名和密码')
+    return
+  }
+  if (p.length < 6) {
+    message.error('密码至少 6 位')
+    return
+  }
+  creating.value = true
+  try {
+    const out = await adminApi.createUser({
+      username: u,
+      password: p,
+      email: createForm.value.email.trim() || undefined,
+      display_name: createForm.value.display_name.trim() || undefined,
+    })
+    message.success(`已创建用户 ${out.username}`)
+    showCreate.value = false
+    await load()
+  } catch (e: any) {
+    message.error(e?.response?.data?.title || '创建失败')
+  } finally {
+    creating.value = false
+  }
+}
+
+// === 重置密码 ===
+const showResetPwd = ref(false)
+const resetTarget = ref<UserOut | null>(null)
+const newPassword = ref('')
+const resetting = ref(false)
+
+function openResetPwd(u: UserOut) {
+  resetTarget.value = u
+  newPassword.value = ''
+  showResetPwd.value = true
+}
+
+async function doResetPwd() {
+  if (!resetTarget.value) return
+  if (newPassword.value.length < 6) {
+    message.error('密码至少 6 位')
+    return
+  }
+  resetting.value = true
+  try {
+    await adminApi.updateUser(resetTarget.value.id, { password: newPassword.value })
+    message.success(`已重置 ${resetTarget.value.username} 的密码`)
+    showResetPwd.value = false
+  } catch (e: any) {
+    message.error(e?.response?.data?.title || '重置失败')
+  } finally {
+    resetting.value = false
+  }
+}
+
+// === 启停 / 删除 ===
+async function toggleActive(u: UserOut) {
+  const action = u.is_active ? '禁用' : '启用'
+  dialog.warning({
+    title: `确认${action}`,
+    content: `${action}用户 "${u.username}"?${u.is_active ? '\n禁用后该用户无法登录,但保留其历史数据(收藏/订阅)。' : ''}`,
+    positiveText: action,
+    negativeText: '取消',
+    onPositiveClick: async () => {
+      try {
+        await adminApi.updateUser(u.id, { is_active: !u.is_active })
+        message.success(`已${action}`)
+        await load()
+      } catch (e: any) {
+        message.error(e?.response?.data?.title || `${action}失败`)
+      }
+    },
+  })
+}
+
+async function del(u: UserOut) {
+  dialog.warning({
+    title: '确认禁用',
+    content: `禁用用户 "${u.username}"?\n\n该用户将无法登录,但其历史数据(收藏/订阅)会被保留。如需彻底清除,请到服务器手动操作数据库。`,
+    positiveText: '禁用',
+    negativeText: '取消',
+    onPositiveClick: async () => {
+      try {
+        const out = await adminApi.deleteUser(u.id)
+        message.success(out.detail)
+        await load()
+      } catch (e: any) {
+        message.error(e?.response?.data?.title || '删除失败')
+      }
+    },
+  })
+}
+
+// === 表格列 ===
+const columns = computed(() => [
+  { title: 'ID', key: 'id', width: 60 },
+  {
+    title: '用户名', key: 'username', width: 180,
+    render: (r: UserOut) => h(NSpace, { size: 6, align: 'center' }, () => [
+      h('span', { style: 'font-weight: 600' }, r.username),
+      h(NTag, {
+        size: 'small', type: 'success',
+        ...(r.id !== auth.user?.id ? { round: true } : {}),
+      }, () => r.id === auth.user?.id ? '我' : ''),
+    ]),
+  },
+  { title: '昵称', key: 'display_name', width: 140, render: (r: UserOut) => r.display_name || '—' },
+  { title: '邮箱', key: 'email', width: 200, render: (r: UserOut) => r.email || '—' },
+  {
+    title: '角色', key: 'role', width: 80,
+    render: (r: UserOut) => h(NTag, {
+      size: 'small', type: r.role === 'owner' ? 'warning' : 'default',
+    }, () => r.role === 'owner' ? 'owner' : 'member'),
+  },
+  {
+    title: '状态', key: 'is_active', width: 80,
+    render: (r: UserOut) => h(NTag, {
+      size: 'small',
+      type: r.is_active ? 'success' : 'default',
+    }, () => r.is_active ? '启用' : '禁用'),
+  },
+  { title: '最后登录', key: 'last_login_at', width: 170, render: (r: UserOut) => r.last_login_at || '从未' },
+  { title: '创建时间', key: 'created_at', width: 170 },
+  {
+    title: '操作', key: 'action', width: 280, fixed: 'right' as const,
+    render: (r: UserOut) => {
+      const isMe = r.id === auth.user?.id
+      const isOwner = r.role === 'owner'
+      return h(NSpace, { size: 6 }, () => {
+        // 重置密码:owner 也允许(虽然意义不大)
+        const items: any[] = [
+          h(NButton, {
+            size: 'small',
+            onClick: () => openResetPwd(r),
+          }, () => '重置密码'),
+        ]
+        // 启停:不允许 owner 操作自己(会自锁);不允许对 owner 操作(防误改)
+        if (!isOwner && !isMe) {
+          items.push(h(NButton, {
+            size: 'small',
+            ghost: true,
+            type: r.is_active ? 'warning' : 'success',
+            onClick: () => toggleActive(r),
+          }, () => r.is_active ? '禁用' : '启用'))
+        }
+        // 删除:不允许 owner / 不允许自己
+        if (!isOwner && !isMe) {
+          items.push(h(NButton, {
+            size: 'small', type: 'error', ghost: true,
+            onClick: () => del(r),
+          }, () => '删除'))
+        }
+        return items
+      })
+    },
+  },
+])
+
+onMounted(load)
+</script>
+
+<template>
+  <NSpace vertical>
+    <NAlert type="info" :show-icon="true" title="用户管理说明">
+      所有通过此页面创建的用户均为 <strong>member</strong> 角色(只能查看文章 / 收藏 / 订阅)。
+      "删除"是<strong>软删除</strong>:禁用登录,保留历史数据(收藏 / 订阅 / API token),
+      防止破坏外键。需要彻底清除请到服务器上操作数据库。
+    </NAlert>
+
+    <NSpace justify="end">
+      <NButton type="primary" @click="openCreate">+ 新增用户</NButton>
+    </NSpace>
+
+    <NCard title="用户列表">
+      <NDataTable
+        :columns="columns"
+        :data="users"
+        :loading="loading"
+        :bordered="false"
+        :pagination="{ pageSize: 20 }"
+        :row-key="(r: UserOut) => r.id"
+      />
+    </NCard>
+
+    <!-- 新增用户弹窗 -->
+    <NModal v-model:show="showCreate" preset="card" title="新增用户" style="width: 520px">
+      <NForm label-placement="left" label-width="100">
+        <NFormItem label="用户名">
+          <NInput
+            v-model:value="createForm.username"
+            placeholder="3-32 字符,小写字母/数字/下划线/连字符"
+          />
+        </NFormItem>
+        <NFormItem label="密码">
+          <NInput
+            v-model:value="createForm.password"
+            type="password"
+            show-password-on="click"
+            placeholder="至少 6 位"
+          />
+        </NFormItem>
+        <NFormItem label="邮箱">
+          <NInput
+            v-model:value="createForm.email"
+            placeholder="可选"
+          />
+        </NFormItem>
+        <NFormItem label="昵称">
+          <NInput
+            v-model:value="createForm.display_name"
+            placeholder="可选,显示用"
+          />
+        </NFormItem>
+      </NForm>
+      <template #footer>
+        <NSpace justify="end">
+          <NButton @click="showCreate = false">取消</NButton>
+          <NButton type="primary" :loading="creating" @click="doCreate">创建</NButton>
+        </NSpace>
+      </template>
+    </NModal>
+
+    <!-- 重置密码弹窗 -->
+    <NModal v-model:show="showResetPwd" preset="card" :title="`重置密码 · ${resetTarget?.username || ''}`" style="width: 460px">
+      <NForm label-placement="left" label-width="80">
+        <NFormItem label="新密码">
+          <NInput
+            v-model:value="newPassword"
+            type="password"
+            show-password-on="click"
+            placeholder="至少 6 位"
+          />
+        </NFormItem>
+      </NForm>
+      <template #footer>
+        <NSpace justify="end">
+          <NButton @click="showResetPwd = false">取消</NButton>
+          <NButton type="primary" :loading="resetting" @click="doResetPwd">重置</NButton>
+        </NSpace>
+      </template>
+    </NModal>
+  </NSpace>
+</template>