Files
nexus/Project/fonrey/PRD/系统管理/系统管理模块PRD.md
2026-04-24 16:52:36 +08:00

26 KiB
Raw Blame History

PRD:系统管理模块(Admin & System Management)

Status: Draft
Author: Alex (Product Manager)
Last Updated: 2026-04-24
Version: 1.0
Stakeholders: 工程负责人、运营团队、安全合规、客户成功团队


0. 模块定位与背景

Fonrey 是一套面向房产经纪公司的 B2B SaaS 平台,采用 django-tenants 实现 PostgreSQL Schema 级别的多租户隔离。随着平台商业化推进,运营团队需要一套独立的管理后台(Admin Console)来管理租户生命周期、系统升级、备份恢复及合规审计。

核心问题:平台运营团队当前缺乏统一的工具来:

  1. 管理数百家经纪公司(租户)的开通、暂停、注销流程
  2. 在不中断服务的前提下对平台进行版本升级与灰度发布
  3. 应对数据灾难场景(数据误删、升级失败)时快速恢复
  4. 满足合规要求,对所有高危操作留存完整审计轨迹

本模块不解决:

  • 租户内部的业务功能(房源、客源、楼盘管理)——已在各自 PRD 中覆盖
  • 移动端管理能力——v2 规划
  • 财务收费与发票系统——独立财务模块
  • 自动化客服与工单系统——独立支持模块

1. 问题陈述

1.1 核心痛点

痛点 影响方 当前代价
无统一租户管理界面,开通/暂停操作依赖人工脚本 运营团队 高错误风险,操作耗时
版本升级需停机维护,影响所有租户 所有用户 SLA 违约风险
数据备份无策略,灾难恢复依赖人工 平台稳定性 数据丢失风险
高危操作无审计日志,合规风险暴露 管理层/合规 法律与客户信任风险

1.2 目标用户

角色 使用场景 频率
超级管理员(Platform Super Admin) 全局配置、高危操作授权 低频(每周)
运维人员(Ops Operator) 日常租户管理、监控巡检 高频(每日)
只读审计员(Read-only Auditor) 日志查询、合规报告导出 中频(每周)

2. 目标与成功指标

目标 指标 当前基线 目标值 测量窗口
租户管理效率提升 新租户开通耗时 人工脚本 ~30 分钟 < 5 分钟(含自动初始化) 上线后 30 天
平台升级零停机 升级期间受影响租户数 全量中断 灰度阶段受影响 ≤ 5% 租户 每次升级
数据恢复能力建立 RTO(恢复时间目标) 无标准流程 单租户恢复 < 2 小时 v1 上线即达标
操作合规覆盖 高危操作审计日志覆盖率 0% 100% 上线后 30 天
管理员安全 MFA 启用率 0% 100%(强制) 上线即达标

3. 非目标(Non-Goals)

  • 不在 v1 实现:自动化账单计费、多币种支持、Webhook 自定义集成市场
  • 不在本模块:租户内业务权限的细粒度配置(见权限管理模块 PRD)
  • 不在本模块:客服工单系统、SLA 自动赔付
  • 不支持:移动端浏览器(管理后台仅面向桌面,运营人员使用场景明确)

4. 用户角色与核心故事

Persona A:运营人员 Lily(日常租户管理)

负责 Fonrey 平台的日常运营,每天需要处理新客户开通、异常租户处理、客户咨询的数据导出请求,使用 PC 浏览器访问管理后台。

Story 1:新租户开通

作为运营人员,我希望通过填写表单快速完成租户开通,并由系统自动完成数据库初始化与欢迎邮件,无需手动执行脚本。

验收标准:

  • 表单提交后,系统在后台自动创建 PostgreSQL Schema 并注入默认配置,完成时间 < 60 秒
  • 新租户创建后,管理员收到系统通知,租户联系人收到欢迎邮件
  • 子域名创建成功后在租户详情中显示可访问链接
  • 创建失败时回滚所有已创建资源,并显示明确的错误原因

Story 2:挂起问题租户

作为运营人员,我希望能快速冻结欠费租户的访问,同时保证数据不丢失,并在欠费解决后一键恢复。

验收标准:

  • 挂起操作执行后,该租户所有用户登录跳转至"账号已暂停"提示页,管理后台数据访问不受影响
  • 支持设置到期时间,到期后系统自动恢复租户状态,并发送通知邮件
  • 所有挂起/恢复操作记录于操作审计日志,包含操作人、时间、原因

Story 3:响应客户数据导出请求

作为运营人员,我希望能为指定租户触发数据导出,并在完成后通过邮件通知对方下载,无需手动操作数据库。

验收标准:

  • 导出任务异步执行(Celery),提交后界面不阻塞
  • 导出完成后邮件通知管理员,邮件包含加密下载链接,有效期 24 小时
  • 支持按模块选择导出内容(客户数据、房源数据、交易记录、系统配置)
  • 导出格式支持:CSV、JSON、SQL Dump

Persona B:超级管理员 David(系统升级与回滚)

负责平台技术运维,周期性执行版本升级,关注升级稳定性与租户影响面,有权执行所有高危操作。

Story 4:灰度系统升级

作为超级管理员,我希望先对内测租户升级新版本,验证稳定后再全量推送,避免一次性影响所有客户。

验收标准:

  • 升级前自动执行健康检查,存在异常服务时阻断升级并提示
  • 支持指定目标租户进行灰度升级,灰度租户名单可编辑
  • 升级过程实时展示进度(每个租户的升级状态),支持查看升级日志
  • 升级失败时系统自动告警,并提供一键回滚入口

Story 5:升级失败回滚

作为超级管理员,我希望在升级出现问题时能立即回滚至上一稳定版本,并生成事件报告。

验收标准:

  • 回滚操作触发前自动保存当前状态快照
  • 支持全量回滚或单租户回滚
  • 回滚完成后生成事件报告:失败原因、回滚耗时、影响范围
  • 回滚操作需二次身份验证确认

Persona C:只读审计员 Carol(合规审计)

负责平台合规审查,定期导出操作日志供法务或客户审查,无任何写权限。

Story 6:审计日志查询与导出

作为审计员,我希望能按操作人、时间范围、操作类型筛选操作日志,并导出为报告格式。

验收标准:

  • 日志列表支持多维度筛选:操作人、时间范围、操作对象、操作类型(创建/修改/删除/高危操作)
  • 日志条目包含:操作人、操作时间、操作对象(租户/用户ID)、操作内容摘要、操作结果(成功/失败)、操作来源 IP
  • 支持导出筛选结果为 CSV 格式

5. 功能规格

5.1 租户管理(Tenant Management)

5.1.1 租户生命周期

新建租户

字段 类型 必填 说明
公司名称 Text ✅ 最大 100 字符
联系人 Text ✅ 租户主联系人姓名
联系邮箱 Email ✅ 用于发送欢迎邮件及系统通知
所在地区 Select ✅ 省市两级
订阅套餐 Select ✅ Basic / Professional / Enterprise
子域名 Text ✅ 格式:{slug}.platform.com,唯一,创建后不可修改

创建流程:

  1. 表单校验通过后,后台 Celery 任务执行:
    • 创建 PostgreSQL Schema(tenant_{id})
    • 执行 Migrate 初始化表结构
    • 注入默认系统配置
    • 发送欢迎邮件至联系邮箱
  2. 任务完成后更新租户状态为 active,失败则全量回滚并标记为 failed
  3. 生成唯一 Tenant ID(UUID),记录创建时间、创建人

挂起(Suspend)

  • 操作触发条件:运营人员手动触发,选择挂起原因(欠费 / 违规 / 主动申请 / 其他)
  • 可设置挂起到期时间(留空表示永久挂起直至手动恢复)
  • 挂起效果:该租户所有用户请求返回 HTTP 403,重定向至暂停提示页;管理后台数据仍可访问
  • 到期自动恢复:Celery Beat 定时检查到期挂起记录,自动切换状态为 active
  • 通知:挂起与恢复均向租户联系邮箱发送通知邮件

删除(Delete)

模式 说明
软删除(Soft Delete) 标记删除状态,数据保留 30 天(默认,可配置)后由 Celery 定时任务清除
硬删除(Hard Delete) 立即清除所有数据、Schema、存储资源及子域名授权;仅超级管理员可操作

删除前置条件:

  1. 操作人必须确认数据导出已完成(勾选确认框)
  2. 硬删除需二次身份验证(MFA 确认)
  3. 软删除冷静期内(默认 30 天),可在租户列表中对已删除租户执行"撤销删除"

删除完成后:释放子域名、Cloudflare R2 存储桶、License 席位

5.1.2 数据管理

数据导出

  • 触发方式:管理员手动触发,选择目标租户 + 导出模块 + 格式
  • 异步执行:Celery 任务,任务状态实时刷新(Pending → In Progress → Done / Failed)
  • 导出包内容:结构化数据(CSV / JSON / SQL Dump)+ 文件资产 URL 清单,不打包文件实体
  • 导出模块选项:客户数据 / 房源数据 / 交易记录 / 系统配置 / 全量
  • 导出包存储:压缩后存于 Cloudflare R2 临时目录,生成带签名下载链接,有效期 24 小时

文件资产(图片/附件)的导出处理规则

设计决策:v1 不打包文件实体,文件以 CDN 持久 URL 形式内嵌于导出数据中。 依据:R2 Bucket 配置为 public read,文件通过 Cloudflare CDN 对外提供持久访问; 在租户账号未被硬删除的情况下,CDN URL 始终有效,满足合规/审计场景需求。 迁移场景(需要文件实体)走"完整备份"流程,不走"数据导出"流程。

各导出格式的文件字段表达方式:

导出格式 图片字段示例 附件字段示例
CSV photos 列:多个 CDN URL 以英文分号分隔 attachments 列:文件名|CDN URL 以分号分隔
JSON "photos": [{"url": "https://cdn.../xxx.jpg", "filename": "封面.jpg", "created_at": "..."}] "attachments": [{"url": "...", "filename": "合同.pdf"}]
SQL Dump 文件元数据表原样导出,file_url 字段为 CDN URL 同左

导出包内附说明文件(README.txt),注明:

"图片与附件以 Cloudflare CDN 链接形式提供,链接在账号有效期内持续可访问。账号注销后链接将在 30 天冷静期结束时失效。如需迁移文件本体,请联系平台支持发起完整数据备份(Backup)。"

数据导出 vs 完整备份的边界

维度 数据导出(Export) 完整备份(Backup)
用途 合规审计、数据核查、业务分析 灾难恢复、租户迁移
文件资产 CDN URL 清单,不含文件实体 含 R2 文件实体(完整同步)
完成时间 分钟级 小时级(取决于文件总量)
触发方式 运营人员手动触发 手动触发 / 系统自动触发(升级前)
存储成本 极低(仅压缩包) 较高(完整文件副本)

数据备份(Snapshot)

  • 自动触发:升级前系统自动触发该租户全量备份
  • 手动触发:管理员可在租户详情页手动发起备份
  • 备份内容:数据库 Schema(pg_dump)+ Cloudflare R2 文件存储(附件、图片)
  • 备份记录展示字段:备份时间、触发方式(自动/手动)、备份大小、状态(进行中/成功/失败)
  • 保留策略:默认保留最近 10 个版本,可在系统全局配置中调整
  • 存储:加密存储,支持目标存储配置(本地 / S3 / Cloudflare R2 / GCS)

数据恢复(Restore)

恢复流程:

选择目标备份版本
  → 二次确认弹窗(显示将覆盖的当前数据版本信息)
  → 自动对当前数据生成临时快照(防止恢复失误)
  → 租户切换为维护模式(用户访问显示"维护中"提示)
  → 执行数据恢复(Celery 任务)
  → 恢复完成 → 自动恢复服务 → 生成恢复操作报告

恢复操作报告包含:操作人、操作时间、恢复前数据版本、恢复后数据版本、耗时、结果

5.1.3 套餐与升级管理

Plan 升级

  • 支持升级路径:Basic → Professional → Enterprise
  • 升级前展示差异对比表(功能项、用户数上限、存储空间、API 调用额度)
  • 生效模式:立即生效 / 按账期生效(下一个账期开始时生效)
  • 升级前自动触发数据备份
  • 升级失败:提供一键回滚至备份版本
  • 升级历史记录:时间、操作人、升级前套餐、升级后套餐

5.1.4 用户与权限管理

Tenant Admin 管理

  • 每个租户可设置 1 至多名 Tenant Admin(超级用户)
  • 平台管理员可直接在后台创建新用户并赋予 Tenant Admin 角色,或从租户现有用户中指定
  • 支持查看当前 Tenant Admin 列表,执行:新增 / 替换 / 撤销权限

Tenant Admin 权限配置(RBAC)

可配置权限项:

权限项 说明
创建/删除子用户 是否允许 Tenant Admin 管理租户内部用户
修改系统配置 是否允许修改租户级系统设置(字段标签、规则等)
查看账单与套餐 是否允许查看订阅信息和费用详情
数据导出 是否允许在租户端触发数据导出

权限基于 RBAC 模型,支持自定义角色(角色名称 + 权限集合),可在多 Tenant Admin 间复用。

密码重置

  • 平台管理员可为任意租户的任意用户发起密码重置
  • 方式一:发送重置链接至注册邮箱(用户自助重置)
  • 方式二:管理员直接设置临时密码(用户首次登录后强制修改)
  • 所有重置操作记录于操作审计日志

5.1.5 租户监控与统计

资源监控

实时展示指标(基于 Grafana + 自定义数据采集):

指标 展示维度
CPU / 内存占用 实时折线图
存储用量 当前值 vs 套餐上限
API 调用次数 当日 / 本月累计
活跃用户数 当日活跃数
当日登录次数 累计折线图
异常请求数 4xx / 5xx 分类
慢查询数量 > 500ms 查询次数

告警配置:支持为每个关键指标设置阈值,超限时触发邮件 / Webhook 通知。

可用性统计(Availability / SLA)

  • 服务可用率(Uptime)统计:支持日 / 周 / 月维度
  • 故障事件记录:开始时间、恢复时间、持续时长、影响描述
  • SLA 达标率报告:可导出供客户成功团队使用

5.2 系统管理(System Management)

5.2.1 版本升级与回滚

系统升级流程

上传/拉取升级包(制品库 Artifact Registry)
  → 系统自动健康检查(所有服务状态正常才允许继续)
  → 配置升级策略:全量 / 灰度(指定内测租户列表)
  → 升级前自动备份(对所有参与本次升级的租户)
  → 执行升级
  → 实时展示升级进度(租户维度状态列表)
  → 升级完成通知(成功/失败详情)

灰度升级策略:

  • 维护"内测租户组"列表,由超级管理员配置
  • 灰度阶段仅对内测租户执行升级,其余租户保持原版本
  • 内测租户验证通过(手动确认)后,触发全量升级

升级回滚

  • 触发条件:手动触发(管理员判断)或自动触发(监控检测到错误率超阈值)
  • 回滚范围:全量回滚(所有租户)/ 单租户回滚
  • 回滚前:自动保存当前状态快照
  • 回滚后:生成事件报告(失败原因、回滚耗时、受影响租户列表)
  • 执行回滚需二次身份验证

5.2.2 定时备份策略

全局备份计划

配置项 选项
备份频率 每小时 / 每日 / 每周
执行时间 可配置时间窗口(默认每日 02:00)
保留数量 最近 N 个版本(默认 10)
存储目标 本地 / AWS S3 / Cloudflare R2 / GCS
  • 支持为单个租户配置独立备份计划,覆盖全局策略
  • 备份任务执行记录:开始时间、完成时间、备份大小、状态
  • 备份失败:自动告警 + 支持手动重试

5.3 管理控制台(Admin Console)

5.3.1 核心页面规格

仪表盘(Dashboard)

模块 展示内容
全局概览 总租户数、活跃租户数、本月新增租户数
系统健康 各核心服务状态(Django / PostgreSQL / Redis / Celery / R2)
近期告警 最近 24 小时告警列表,按严重程度分类
资源概览 平台整体存储用量、API 调用量趋势图
最近操作 最近 10 条高危操作审计记录

租户列表

  • 分页展示(默认 20 条/页)
  • 搜索:按公司名称、子域名、联系邮箱关键词搜索
  • 筛选:按状态(Active / Suspended / Deleted)、套餐(Basic/Pro/Enterprise)、注册时间范围
  • 列表字段:公司名称、子域名、套餐、状态、注册时间、活跃用户数
  • 快捷操作:查看详情、挂起、发起备份、数据导出

租户详情

标签页结构:

标签 内容
基本信息 公司信息、联系人、子域名、套餐、状态,支持编辑部分字段
用户管理 Tenant Admin 列表、普通用户列表、密码重置入口
套餐信息 当前套餐详情、用量统计、升级入口
监控数据 该租户资源使用图表、SLA 统计
备份记录 该租户备份列表、手动触发备份、恢复操作入口
操作历史 该租户相关的所有管理员操作日志

系统版本管理

  • 当前运行版本信息
  • 历史版本列表(版本号、发布时间、状态:Current / Previous / Archived)
  • 升级入口(上传/拉取升级包)
  • 回滚入口(选择目标版本)

备份管理

  • 全局备份计划配置
  • 备份任务列表(支持按租户、状态、时间筛选)
  • 手动触发备份(选择租户)
  • 恢复操作入口

监控与告警

  • 租户级 / 系统级监控图表(基于 Grafana iframe 嵌入或自定义实现)
  • 告警规则配置(指标 + 阈值 + 通知渠道)
  • 告警历史列表

审计日志

  • 全平台操作日志,支持多维度筛选与导出
  • 每条日志包含:操作人、时间、操作对象、内容摘要、结果、来源 IP

管理员设置

  • 管理员账号管理(创建、编辑、停用)
  • 角色配置(超级管理员 / 运营人员 / 只读审计员)
  • MFA 设置(强制启用,支持 TOTP)
  • IP 白名单配置
  • 登录会话管理(查看活跃会话、强制登出)

5.3.2 访问控制与安全

强制要求(不可降级):

安全要求 实现方式
MFA 强制启用 所有管理员账号首次登录强制配置 TOTP;无法跳过
IP 白名单 仅允许指定 IP 范围访问管理控制台 URL(Nginx 层或应用层限制)
高危操作二次验证 删除租户、数据恢复、系统回滚操作触发 MFA 二次确认弹窗
会话超时 无操作 30 分钟后自动登出,Token 失效
强制登出 超级管理员可在"管理员设置"中强制终止指定管理员的所有会话

与租户应用隔离:

  • 管理控制台部署在独立子域名(如 admin.platform.com),与租户应用域名体系分离
  • 管理控制台不共享租户应用的 Session / Cookie 机制

5.3.3 操作审计日志规范

所有写操作(Create / Update / Delete)及高危操作必须记录审计日志,字段规范如下:

{
    "id": "UUID",
    "operator_id": "管理员用户 ID",
    "operator_name": "管理员显示名",
    "action_type": "CREATE_TENANT | SUSPEND_TENANT | DELETE_TENANT | RESTORE_DATA | SYSTEM_UPGRADE | ROLLBACK | RESET_PASSWORD | ...",
    "target_type": "Tenant | User | System | Backup",
    "target_id": "操作对象 ID",
    "target_name": "操作对象可读名称",
    "payload_summary": "操作内容摘要(非敏感字段)",
    "result": "SUCCESS | FAILED",
    "error_message": "失败原因(如有)",
    "ip_address": "操作来源 IP",
    "created_at": "ISO 8601 时间戳"
}

6. 技术考量

6.1 系统架构定位

基于 Fonrey 技术栈(Django + django-tenants + PostgreSQL + Celery + Cloudflare R2),管理控制台在同一 Django 项目中通过独立 App (apps/admin_console/) 实现,利用 Django 的 public Schema 作为管理控制台的数据层。

6.2 关键依赖

依赖 用途 风险等级
django-tenants Schema 创建/销毁、租户切换 高 — 核心依赖,需确认 Schema 创建并发安全性
Celery + Celery Beat 异步备份、导出、状态同步任务 中 — 需监控任务队列积压
PostgreSQL pg_dump 数据备份与恢复 高 — 需测试大 Schema 备份耗时与锁表影响
Cloudflare R2 备份文件与导出文件存储 中 — 需评估大文件上传/下载带宽成本
Grafana 监控图表展示 低 — 已在技术栈中规划
TOTP(如 django-otp) MFA 实现 低 — 成熟库,接入成本低

6.3 已知风险

风险 可能性 影响 缓解措施
大租户 Schema 备份耗时超长(>1 小时) 中 高 异步执行 + 进度追踪;评估流式备份方案
系统升级过程中新请求涌入导致数据不一致 低 高 升级期间租户切换维护模式;使用数据库事务
软删除数据保留期间存储成本积累 中 低 合理设置默认保留期,提供平台级存储用量监控
管理控制台 IP 白名单配置错误导致运营团队被锁定 低 高 提供紧急访问恢复流程(通过服务器直接访问),文档化

6.4 待解决问题(开发启动前必须确认)

  • 数据库备份方案:pg_dump 直接执行还是基于 WAL 的增量备份(如 pgBackRest)?— Owner: 工程负责人 — Deadline: 技术评审前
  • 监控数据来源:Grafana 直接对接 PostgreSQL 指标还是通过 Prometheus Exporter?— Owner: 运维团队
  • MFA 库选型:django-otp + TOTP 还是集成第三方认证(如 Okta)?— Owner: 工程负责人
  • 子域名管理机制:Cloudflare DNS API 自动创建还是手动配置?— Owner: 运维团队
  • 审计日志存储:写入 public Schema 还是独立日志服务(如 Elasticsearch)?— Owner: 工程负责人

7. 发布计划

阶段 时间 范围 通过标准
内部 Alpha Week 1–4 平台内部团队使用 核心租户 CRUD 流程无 P0 Bug;MFA 可用
封闭 Beta Week 5–6 运营团队日常使用 备份/恢复流程完整可用;审计日志 100% 覆盖
正式上线 Week 7 全量运营团队 升级/回滚流程验证通过;监控告警规则配置完成

回滚标准:若正式上线后 72 小时内发现租户数据隔离漏洞或审计日志丢失,立即回滚并进入 P0 修复流程。


8. 不构建清单(What We're NOT Building)

请求/功能 原因 重新评估条件
自动化账单与发票生成 超出本模块范围,财务模块独立立项 财务模块 PRD 完成后接入
租户端自助迁移工具 当前用户规模不需要,运营团队手动处理即可 租户数 > 500 时重新评估
移动端管理界面 运营团队使用场景明确为 PC,移动端收益低 v2 规划,用户调研支持时推进
Webhook 事件推送市场 集成复杂度高,当前无客户需求驱动 有 3+ 客户明确需求时评估
多语言管理界面 运营团队为内部人员,中文已满足需求 国际化扩张时规划

9. 附录

9.1 租户状态机

[新建中 Creating]
      ↓ 成功
[活跃 Active] ←──────────────────┐
      ↓ 手动挂起                  │ 到期自动恢复 / 手动恢复
[已挂起 Suspended] ───────────────┘
      ↓ 删除操作(软删除)
[待清除 Pending Delete](冷静期 30 天)
      ↓ 冷静期到期 / 硬删除
[已删除 Deleted]

9.2 管理员角色权限矩阵

操作 超级管理员 运营人员 只读审计员
创建租户 ✅ ✅ ❌
挂起 / 恢复租户 ✅ ✅ ❌
软删除租户 ✅ ✅ ❌
硬删除租户 ✅ ❌ ❌
数据导出 ✅ ✅ ❌
手动触发备份 ✅ ✅ ❌
数据恢复 ✅ ❌ ❌
系统升级 ✅ ❌ ❌
系统回滚 ✅ ❌ ❌
配置告警规则 ✅ ✅ ❌
查看审计日志 ✅ ✅ ✅
导出审计日志 ✅ ✅ ✅
管理员账号管理 ✅ ❌ ❌
强制登出管理员 ✅ ❌ ❌
配置 IP 白名单 ✅ ❌ ❌

9.3 页面路由规划(管理控制台)

/admin/                          # 仪表盘
/admin/tenants/                  # 租户列表
/admin/tenants/new/              # 新建租户
/admin/tenants/{id}/             # 租户详情(信息)
/admin/tenants/{id}/users/       # 租户用户管理
/admin/tenants/{id}/plan/        # 套餐信息与升级
/admin/tenants/{id}/monitoring/  # 监控数据
/admin/tenants/{id}/backups/     # 备份记录
/admin/tenants/{id}/history/     # 操作历史
/admin/system/versions/          # 版本管理
/admin/system/backups/           # 备份管理
/admin/monitoring/               # 全局监控与告警
/admin/audit-logs/               # 审计日志
/admin/settings/admins/          # 管理员设置