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 Schematenant_{id}
    • 执行 Migrate 初始化表结构
    • 注入默认系统配置
    • 发送欢迎邮件至联系邮箱
  2. 任务完成后更新租户状态为 active,失败则全量回滚并标记为 failed
  3. 生成唯一 Tenant IDUUID记录创建时间、创建人

挂起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

  • 自动触发:升级前系统自动触发该租户全量备份
  • 手动触发:管理员可在租户详情页手动发起备份
  • 备份内容:数据库 Schemapg_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 范围访问管理控制台 URLNginx 层或应用层限制)
高危操作二次验证 删除租户、数据恢复、系统回滚操作触发 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 监控图表展示 低 — 已在技术栈中规划
TOTPdjango-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 14 平台内部团队使用 核心租户 CRUD 流程无 P0 BugMFA 可用
封闭 Beta Week 56 运营团队日常使用 备份/恢复流程完整可用;审计日志 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/          # 管理员设置