system-design/IT服务平台/ICT服务平台/对MkDoc构建用户系统.md

# MkDocs 用户阅读管理系统 — 规划设计及实施方案

## 一、概述

### 1.1 目标

针对以 MkDocs 生成的静态文档站点（如 docs.writech.cn），构建一套**用户阅读管理系统**，实现用户登记与身份识别、文档分级权限控制、阅读次数与有效期管理、防爬虫保护和阅读行为统计分析。系统在保障文档安全可控的同时，为大部分公开文档提供**免登录流畅阅读**体验，仅在访问受控文档时才触发轻量认证。

### 1.2 与现有平台的关系

本系统基于 [ICT 服务平台](ICT服务平台概要.md) 已有基础设施构建，复用以下底座能力：

| 已有组件 | 本系统中的角色 |
|---------|-------------|
| Keycloak（SSO） | 登录用户的 OIDC 认证中心，对接微信开放平台 Social IdP |
| OpenLDAP（身份源） | 企业员工账户存储 |
| DocForge（渲染引擎） | MkDocs 构建触发与权限元数据解析 |
| Umami（统计分析） | 页面级阅读埋点与看板 |
| PostgreSQL（数据库） | 用户注册信息、权限策略、阅读记录持久化 |
| Nginx（反向代理） | 请求拦截、静态资源分发、SSL 终止 |

### 1.3 设计原则

1. **静态站点不改造**：MkDocs 仍按标准流程生成静态 HTML，用户系统以**反向代理网关层**注入，不侵入 MkDocs 构建产物
2. **最小摩擦登录**：公开文档免登录访问；受控文档首次需认证后自动记住，不逐页弹登录框
3. **双通道注册**：支持微信扫码和手机短信验证码两种轻量注册方式，适配 PC 和移动端
4. **颗粒度可粗可细**：权限可设置到单篇文档，也可按目录/标签/仓库整体授权
5. **全栈开源**：核心组件均采用开源方案，数据自托管

---

## 二、系统架构

### 2.1 整体架构图

```plantuml
@startuml
skinparam componentStyle rectangle
skinparam nodesep 10
skinparam ranksep 25
title MkDocs 用户阅读管理系统 - 整体架构

actor "PC 浏览器" as PCUser
actor "手机浏览器" as MobileUser

rectangle "互联网应用服务器" {

  package "接入层" as P_Access {
    [Nginx\n反向代理] as Nginx
    [MkDocs Guard\n认证网关] as Guard
  }

  package "认证服务" as P_Auth {
    [Keycloak SSO] as KC
    [微信扫码服务] as WxAuth
    [短信验证服务] as SMS
  }

  package "用户管理" as P_User {
    [用户注册中心] as UC
    [权限引擎] as Perm
    [反爬虫模块] as AntiBot
  }

  package "文档服务" as P_Doc {
    [MkDocs\n静态站点] as MkDocs
    [DocForge\n渲染引擎] as Forge
  }

  package "数据与分析" as P_Data {
    database "PostgreSQL" as DB
    [Redis\n会话/限流] as Redis
    [Umami 统计] as Umami
  }
}

' === 分层布局控制 ===
P_Access -[hidden]down-> P_Auth
P_Access -[hidden]down-> P_User
P_Auth -[hidden]right-> P_User
P_Auth -[hidden]down-> P_Doc
P_User -[hidden]down-> P_Data
P_Doc -[hidden]right-> P_Data

' === 用户入口 ===
PCUser -down-> Nginx
MobileUser -down-> Nginx
Nginx -down-> Guard : 文档请求

' === Guard 请求分发 ===
Guard -down-> KC : OIDC 认证
Guard -down-> Perm : 查询权限
Guard -down-> AntiBot : 请求检测
Guard -down-> MkDocs : 放行静态页面

' === 注册中心 ===
UC --> WxAuth : 微信登录
UC --> SMS : 短信验证

' === 数据持久化 ===
UC -down-> DB : 用户数据
Perm -down-> DB : 权限策略
Perm -down-> Redis : 缓存
Forge -down-> DB : 文档元数据
Umami -down-> DB : 阅读埋点
@enduml
```

### 2.2 核心组件清单

| 组件 | 技术方案 | 用途 | 许可证 |
|------|---------|------|--------|
| 认证网关 | **MkDocs Guard**（自研，Go / Node.js） | Nginx 子请求认证，拦截文档请求并校验权限 | — |
| 用户注册中心 | **UserCenter**（自研，Node.js + Express） | 微信扫码、短信验证码注册/登录，用户管理 | — |
| 权限引擎 | **PermEngine**（自研，Node.js） | 文档 - 用户权限匹配、次数/期限校验 | — |
| 反爬虫 | **AntiBot**（自研 + 开源中间件） | 频率限制、浏览器指纹、行为检测 | — |
| 微信 OAuth | **微信开放平台** + Keycloak Social IdP | 微信扫码登录/注册 | — |
| 短信网关 | **阿里云短信服务** / **腾讯云短信** | 验证码发送 | — |
| 会话缓存 | **Redis** | 登录会话、验证码、频率计数器 | BSD |
| 浏览器指纹 | **FingerprintJS**（开源版） | 匿名用户标识、反爬辅助 | MIT |
| 静态站点 | **MkDocs** + **Material 主题** | Markdown 文档构建为静态 HTML | BSD |
| 统计分析 | **Umami**（已有） | 页面访问量、阅读时长、用户来源 | MIT |
| 数据库 | **PostgreSQL**（已有） | 用户、权限、阅读记录持久化 | PostgreSQL |

### 2.3 请求处理流程

```plantuml
@startuml
skinparam componentStyle rectangle
title 文档请求处理流程

start
:用户请求 MkDocs 文档页面;

:Nginx 转发至 MkDocs Guard;

:AntiBot 检测;
if (疑似爬虫 ?) then (是)
  :返回 429 / 验证码挑战;
  stop
else (否)
endif

:Guard 查询文档权限级别;

if (文档为 open 级别 ?) then (是)
  :直接放行, 返回静态页面;
  :Umami 记录匿名访问;
  stop
else (否)
endif

if (用户已持有有效会话 ?) then (是)
  :从 Redis 读取用户身份;
else (否)
  :展示登录浮层;
  note right
    PC - 微信扫码 / 短信验证码
    手机 - 微信授权 / 短信验证码
  end note
  :完成认证, 建立会话;
endif

:PermEngine 校验用户权限;
if (用户有权访问 ?) then (是)
  if (阅读次数/有效期已超限 ?) then (是)
    :提示 "使用权已到期, 请联系管理员";
    stop
  else (否)
    :放行, 返回静态页面;
    :记录阅读日志;
    :Umami 记录实名访问;
    stop
  endif
else (否)
  :返回 403 无权限页面;
  stop
endif

@enduml
```

---

## 三、用户注册与登录

### 3.1 注册方式

系统支持两种轻量注册方式，用户无需设置密码：

#### 3.1.1 微信扫码注册/登录

```plantuml
@startuml
skinparam componentStyle rectangle
title 微信扫码注册/登录流程

start
:用户在 PC 浏览器访问受控文档;
:Guard 弹出登录浮层;
:浮层展示微信登录二维码;
note right: 调用微信开放平台生成临时二维码

:用户使用微信扫码;
:微信弹出授权确认;
:用户点击确认授权;

:微信回调 Keycloak 携带 code;
:Keycloak 换取微信 OpenID + 用户信息;

if (OpenID 已绑定系统用户 ?) then (是)
  :直接登录, 建立会话;
else (否)
  :自动创建用户;
  note right
    昵称 - 微信昵称
    头像 - 微信头像
    标识 - 微信 OpenID
    角色 - 默认读者
  end note
  :登录并建立会话;
endif

:回到文档页面, 自动刷新;
stop
@enduml
```

**技术实现要点**：

- Keycloak 配置微信开放平台作为 Social Identity Provider
- 使用微信开放平台「网站应用」的扫码登录能力（非公众号）
- PC 端展示二维码供手机扫描；手机端直接调起微信授权页面
- 微信 OpenID 与系统用户 1:1 绑定，存储于 PostgreSQL

#### 3.1.2 手机短信验证码注册/登录

```plantuml
@startuml
skinparam componentStyle rectangle
title 短信验证码注册/登录流程

start
:用户在浮层选择 "手机号登录";
:输入手机号;

:UserCenter 检查发送频率;
if (60 秒内已发送 ?) then (是)
  :提示 "请稍后重试";
  stop
else (否)
endif

:生成 6 位随机验证码;
:验证码存入 Redis (有效期 5 分钟);
:调用短信网关发送;

:用户输入验证码;

if (验证码正确 ?) then (是)
  if (手机号已注册 ?) then (是)
    :直接登录, 建立会话;
  else (否)
    :自动创建用户;
    note right
      标识 - 手机号
      角色 - 默认读者
    end note
    :登录并建立会话;
  endif
else (否)
  :提示 "验证码错误";
  stop
endif

:回到文档页面;
stop
@enduml
```

**技术实现要点**：

| 配置项 | 值 |
|-------|-----|
| 验证码长度 | 6 位纯数字 |
| 有效期 | 5 分钟 |
| 发送间隔 | 60 秒 |
| 单手机号日上限 | 10 次 |
| 短信模板 | 「您的 Writech 文档验证码为 {code}，5 分钟内有效。」 |
| 频率计数器 | Redis INCR + TTL |

### 3.2 PC 浏览器认证体验

PC 端用户访问受控文档时，页面内弹出**半透明遮罩 + 居中登录浮层**（非跳转），浮层包含两个标签页：

| 标签页 | 内容 |
|-------|------|
| 微信扫码 | 显示动态二维码，扫码后自动完成登录并关闭浮层 |
| 短信验证 | 手机号输入框 + 发送按钮 + 验证码输入框 |

浮层设计原则：
- 背景半透明可窥见文档内容（制造阅读意愿）
- 登录成功后浮层自动消失，无页面跳转
- 会话有效期 7 天，有效期内不再弹出

### 3.3 手机浏览器认证体验

- **微信内打开**：直接调起微信授权（静默授权 + 头像/昵称），无需扫码
- **其他浏览器**：展示短信验证码登录界面，微信扫码二维码作为备选

### 3.4 会话管理

| 参数 | 值 | 说明 |
|------|-----|------|
| 会话存储 | Redis | key = `session:{token}`，value = 用户信息 JSON |
| 会话有效期 | 7 天 | 自最后一次请求起滑动续期 |
| 会话 Token | HttpOnly Cookie | `mkdocs_session`，Secure + SameSite=Lax |
| 并发会话 | 不限 | 同一用户可在多设备同时登录 |

---

## 四、用户管理

### 4.1 用户数据模型

```
users
├── id              UUID        主键
├── phone           VARCHAR(20) 手机号（唯一，可为空）
├── wechat_openid   VARCHAR(64) 微信 OpenID（唯一，可为空）
├── wechat_unionid  VARCHAR(64) 微信 UnionID（可为空）
├── nickname        VARCHAR(50) 昵称
├── avatar_url      TEXT        头像 URL
├── role            ENUM        角色：reader / reviewer / blocked
├── list_type       ENUM        名单类型：normal / whitelist / blacklist
├── group_id        UUID        所属用户组（外键）
├── registered_at   TIMESTAMP   注册时间
├── last_login_at   TIMESTAMP   最后登录时间
└── status          ENUM        状态：active / suspended / deleted
```

### 4.2 用户角色

| 角色 | 标识 | 权限说明 |
|------|------|---------|
| 读者 | reader | 默认角色，可阅读被授权的文档，可提交反馈 |
| 审阅者 | reviewer | 受邀审阅指定文档，可阅读、评论并提交修改建议 |
| 被封禁 | blocked | 黑名单用户，禁止访问所有受控文档 |
| 管理员 | admin | 管理用户、权限策略、查看统计（复用 Keycloak 管理员角色） |

> 说明：「作者」角色由 Gitea 仓库写权限定义，不在本系统管理范围内。

### 4.3 白名单与黑名单

#### 白名单机制

- 白名单用户可访问**所有 `login` 级别文档**，无需逐文档授权
- 适用场景：VIP 客户、长期合作伙伴、内部测试人员
- 管理方式：管理员在后台设置 `list_type = whitelist`

#### 黑名单机制

- 黑名单用户访问任何受控文档均返回 403
- 触发条件：
  - 管理员手动加入
  - AntiBot 检测到恶意爬取行为自动加入
  - 用户连续提交违规反馈内容
- 管理方式：管理员在后台设置 `list_type = blacklist`

#### 名单优先级

```
黑名单 > 文档级 restricted > 白名单 > 文档级 login > 普通用户
```

### 4.4 用户分组

用户可归入多个组，方便按组授权：

```
user_groups
├── id          UUID        主键
├── name        VARCHAR(50) 组名（如"经销商"、"教育局客户"）
├── description TEXT        说明
└── created_at  TIMESTAMP

user_group_members
├── user_id     UUID        外键 → users
├── group_id    UUID        外键 → user_groups
└── joined_at   TIMESTAMP
```

授权时可指定用户组，该组全部成员自动获得对应权限。

---

## 五、文档权限模型

### 5.1 权限分级

在现有 DocPortal 权限体系基础上，MkDocs 用户系统使用以下**五级访问控制**：

| 级别 | 标识 | 说明 | 是否需要登录 |
|------|------|------|-------------|
| 完全公开 | `open` | 任何人可无限次阅读，不触发任何认证 | 否 |
| 试读公开 | `open_once` | 匿名用户首次可阅读，再次访问需登录 | 首次否，再次是 |
| 登录可读 | `login` | 登录用户（含白名单）可阅读 | 是 |
| 指定可读 | `restricted` | 仅授权用户/用户组可阅读 | 是 |
| 内部机密 | `confidential` | 仅管理员和显式授权用户，额外审计日志 | 是 + 审计 |

### 5.2 文档操作权限

每篇文档可独立配置以下操作权限：

| 权限 | 标识 | 说明 |
|------|------|------|
| 只读 | `read` | 仅可在线阅读，不可复制/下载 |
| 反馈 | `feedback` | 可提交反馈意见（文字/评分），不可修改文档 |
| 评论 | `comment` | 可在文档段落级别发表评论 |
| 下载 | `download` | 可下载 Markdown 原文或 PDF |
| 修改建议 | `suggest` | 可提交修改建议（生成 Git PR），需作者审核 |

### 5.3 权限配置方式

#### 方式一：Front Matter 声明（文档级）

在 Markdown 文件头部的 YAML Front Matter 中声明权限：

```yaml
---
title: "智能笔 BLE 通信协议"
access: restricted
permissions:
  read: true
  feedback: true
  comment: true
  download: false
  suggest: false
allowed_users:
  - "138****1234"
  - "group:经销商"
allowed_groups:
  - "经销商"
  - "教育局客户"
usage:
  max_views: 50
  expires_at: "2027-03-31"
---
```

#### 方式二：目录级继承（`.access.yml` 配置文件）

在 MkDocs 目录下放置 `.access.yml` 文件，该目录及子目录下所有文档继承此权限配置：

```yaml
# docs/技术方案/.access.yml
default_access: login
default_permissions:
  read: true
  feedback: true
  comment: false
  download: false
  suggest: false
overrides:
  - pattern: "公开简介.md"
    access: open
  - pattern: "机密/**"
    access: confidential
```

#### 方式三：管理后台配置（全局策略）

管理员在 Web 后台按**仓库、目录路径通配符、标签**维度设置批量策略：

| 策略维度 | 示例 | 说明 |
|---------|------|------|
| 仓库 | `com-shware-doc` | 整个仓库默认 `login` |
| 目录通配符 | `*/对外文档/**` | 所有仓库的「对外文档」目录 `open` |
| 标签 | `tag:机密` | 含「机密」标签的文档 `confidential` |
| 单文档 | `SmartPen/硬件设计/xxx.md` | 指定文档覆盖策略 |

### 5.4 权限优先级（从高到低）

```
1. 黑名单 → 403 拒绝（最高优先）
2. 单文档 Front Matter 声明
3. 管理后台单文档策略
4. 目录级 .access.yml
5. 管理后台目录通配符策略
6. 管理后台标签策略
7. 管理后台仓库默认策略
8. 系统默认（open）
```

### 5.5 避免登录繁杂的设计策略

为满足"颗粒度到单文档但不逐页登录"的要求，采用以下策略：

| 策略 | 机制 |
|------|------|
| 会话全站有效 | 登录一次后 7 天内访问同站点任何受控文档均免再次登录 |
| 目录级继承 | 同目录下文档共享权限配置，无需逐文件设置 |
| 公开文档零感知 | `open` 级文档不注入任何认证逻辑，加载速度等同纯静态页 |
| 延迟认证 | 用户浏览目录/搜索时不触发登录，点击具体受控文档才弹浮层 |
| 渐进式体验 | 受控文档先展示标题+摘要（前 3 段），余下内容模糊化并提示登录 |

---

## 六、文档使用控制

### 6.1 阅读次数限制

通过 Front Matter 或管理后台配置 `max_views` 参数：

```yaml
usage:
  max_views: 50         # 该文档最多可被在线阅读 50 次
  max_views_per_user: 5  # 每个用户最多阅读 5 次
```

**计数规则**：

| 规则 | 说明 |
|------|------|
| 计数触发 | 用户打开文档页面并停留超过 5 秒才计为 1 次有效阅读 |
| 去重窗口 | 同一用户 30 分钟内多次打开同一文档仅计 1 次 |
| 存储位置 | PostgreSQL `doc_view_logs` 表 |
| 缓存加速 | Redis 缓存当前计数，每 10 分钟同步至数据库 |

### 6.2 有效期限制

```yaml
usage:
  expires_at: "2027-03-31"    # 到期后文档不可访问
  available_from: "2026-06-01" # 生效日期（可选）
```

**到期处理策略**：

| 场景 | 行为 |
|------|------|
| 到期后匿名访问 | 返回"文档已过期"提示页 |
| 到期后登录访问 | 返回"文档已过有效期，请联系管理员"提示页 |
| 管理员访问 | 不受限制，可正常查看 |
| 即将到期提醒 | 到期前 7 天向管理员发送 MsgHub 通知 |

### 6.3 使用控制数据表

```
doc_usage_config
├── doc_id          VARCHAR     文档唯一标识（仓库 + 路径）
├── max_views       INT         总阅读次数上限（NULL = 不限）
├── max_views_user  INT         单用户阅读次数上限（NULL = 不限）
├── available_from  DATE        生效日期（NULL = 即时生效）
├── expires_at      DATE        到期日期（NULL = 永不过期）
└── updated_at      TIMESTAMP

doc_view_logs
├── id              UUID        主键
├── doc_id          VARCHAR     文档标识
├── user_id         UUID        用户 ID（匿名用户为 NULL）
├── fingerprint     VARCHAR     浏览器指纹（匿名用户标识）
├── ip_address      INET        访问 IP
├── user_agent      TEXT        浏览器 UA
├── duration_sec    INT         停留时长（秒）
├── viewed_at       TIMESTAMP   访问时间
└── is_counted      BOOLEAN     是否计入有效阅读
```

---

## 七、防爬虫策略

### 7.1 多层防护体系

```plantuml
@startuml
title 防爬虫多层防护体系

start
:外部请求;

partition "第一层 - Nginx 基础防护" {
  :IP 频率限制;
  :User-Agent 黑名单;
  :robots.txt 声明;
}

if (命中拦截?) then (是)
  :返回 429 / 403;
  stop
else (否)
endif

partition "第二层 - AntiBot 行为检测" {
  :浏览器指纹验证;
  :JS 执行检测;
  :鼠标/滚动行为分析;
}

if (疑似爬虫?) then (是)
  :验证码挑战;
  stop
else (否)
endif

partition "第三层 - 内容保护" {
  :关键内容异步加载;
  :文本防选择/防复制;
  :动态水印注入;
}

:返回受保护的文档内容;

partition "第四层 - 智能封禁（后台异步）" {
  :分析访问行为模式;
  if (触发封禁条件?) then (是)
    :自动加入黑名单;
  else (否)
  endif
}

stop
@enduml
```

### 7.2 各层策略详情

#### 第一层：Nginx 基础防护

| 策略 | 配置 | 说明 |
|------|------|------|
| IP 频率限制 | `limit_req_zone` 10 次/秒 | 单 IP 超限返回 429 |
| 并发连接限制 | `limit_conn` 20 连接/IP | 超限返回 503 |
| User-Agent 黑名单 | 拦截 curl/wget/scrapy/python-requests 等 | 返回 403 |
| robots.txt | 仅允许搜索引擎索引 `open` 级文档路径 | 受控文档 Disallow |

#### 第二层：AntiBot 行为检测

| 策略 | 实现 | 说明 |
|------|------|------|
| JS 执行检测 | 页面注入一段 JS，执行后生成 Token 回传 | 无 JS 执行能力的爬虫无法通过 |
| 浏览器指纹 | FingerprintJS 生成指纹，与 User-Agent 交叉验证 | 指纹缺失或矛盾判定为爬虫 |
| 行为分析 | 监测鼠标移动、页面滚动、停留时长 | 零行为数据判定为爬虫 |

#### 第三层：内容保护

| 策略 | 实现 | 适用级别 |
|------|------|---------|
| 关键内容异步加载 | 受控文档正文通过 AJAX 请求获取，HTML 源码不含全文 | login / restricted / confidential |
| CSS 防选择 | `user-select: none` + 右键菜单拦截 | restricted / confidential |
| 动态水印 | 用户昵称 + 手机号后 4 位半透明水印 | confidential |

#### 第四层：智能封禁

| 触发条件 | 处置 |
|---------|------|
| 同一 IP 10 分钟内访问 > 100 个不同文档 | 自动加入 IP 黑名单 24 小时 |
| 同一用户 1 小时内访问 > 50 个文档 | 账户临时冻结 + 管理员通知 |
| 被 JS 检测拦截 > 3 次 | IP + 指纹 永久封禁 |

---

## 八、阅读统计

### 8.1 统计维度

基于 Umami 埋点和系统自有日志，提供以下统计维度：

| 维度 | 数据来源 | 说明 |
|------|---------|------|
| 页面访问量 (PV) | Umami | 每篇文档的总访问次数 |
| 独立访客数 (UV) | Umami + 指纹 | 去重后的独立用户数 |
| 平均阅读时长 | Umami | 用户在文档页面的平均停留时间 |
| 阅读完成率 | 前端 JS 埋点 | 滚动到文档底部的用户占比 |
| 用户阅读清单 | doc_view_logs | 每个登录用户阅读过的文档列表 |
| 文档热度排行 | 聚合计算 | 按 PV / UV 排序的文档热度榜 |
| 时段分布 | Umami | 按小时/日/周分布的访问趋势 |
| 来源渠道 | Umami (Referrer) | 文档从哪些渠道/页面被引流 |

### 8.2 管理看板

管理员可在 Web 后台查看以下看板：

| 看板 | 内容 |
|------|------|
| 文档总览 | 各级别文档数量、总 PV/UV、活跃用户数 |
| 文档详情 | 单篇文档的访问趋势、用户列表、阅读时长分布 |
| 用户画像 | 单用户阅读历史、偏好标签、活跃时段 |
| 权限使用 | 各文档的已用/剩余阅读次数、即将到期提醒 |
| 安全日志 | 爬虫拦截记录、黑名单触发记录、异常访问报警 |

### 8.3 自定义埋点

在 MkDocs 主题模板中注入以下自定义事件：

```javascript
// 页面加载时
umami.track('doc_view', {
  doc_id: '{{ doc_id }}',
  access_level: '{{ access_level }}',
  user_type: '{{ user_type }}'  // anonymous / registered / whitelist
});

// 阅读完成时（滚动到底部）
window.addEventListener('scroll', function() {
  if (isScrolledToBottom()) {
    umami.track('doc_complete', { doc_id: '{{ doc_id }}' });
  }
});

// 反馈提交时
function onFeedbackSubmit(rating, content) {
  umami.track('doc_feedback', {
    doc_id: '{{ doc_id }}',
    rating: rating
  });
}
```

---

## 九、MkDocs Guard 技术实现

### 9.1 架构模式：Nginx auth_request

MkDocs Guard 采用 **Nginx `auth_request` 子请求模式**，不修改 MkDocs 静态文件：

```
# Nginx 配置片段
location /docs/ {
    auth_request /auth/check;
    auth_request_set $auth_user $upstream_http_x_auth_user;
    auth_request_set $auth_role $upstream_http_x_auth_role;

    # 认证通过后，代理到 MkDocs 静态文件
    proxy_pass http://127.0.0.1:8001;

    # 注入用户信息到响应头（供前端 JS 使用）
    add_header X-Auth-User $auth_user;
    add_header X-Auth-Role $auth_role;
}

location = /auth/check {
    internal;
    proxy_pass http://127.0.0.1:3100/guard/check;
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header Cookie $http_cookie;
}
```

### 9.2 Guard 服务端逻辑

```
MkDocs Guard (Node.js, 端口 3100)
├── GET /guard/check          — Nginx auth_request 回调
│     ├─ 解析 X-Original-URI 获取文档路径
│     ├─ 查询文档权限级别（Redis 缓存 → PostgreSQL）
│     ├─ open 级别 → 200 放行
│     ├─ 检查 Cookie 中的会话 Token
│     ├─ 有效会话 → 调用 PermEngine 校验 → 200/403
│     └─ 无会话 + 非 open → 401（触发前端弹登录浮层）
├── POST /guard/login/wechat  — 微信扫码登录回调
├── POST /guard/login/sms     — 短信验证码登录
├── POST /guard/logout        — 登出
└── GET  /guard/session       — 查询当前会话状态
```

### 9.3 PermEngine 权限引擎

```
PermEngine (Node.js 模块)
├── checkAccess(userId, docPath)
│     ├─ 检查用户黑名单 → blocked 则拒绝
│     ├─ 加载文档权限配置（优先级链）
│     ├─ open → 放行
│     ├─ open_once → 查浏览器指纹记录
│     ├─ login → 已登录即放行；白名单用户放行
│     ├─ restricted → 检查 allowed_users / allowed_groups
│     ├─ confidential → 检查显式授权 + 写审计日志
│     └─ 检查 usage 限制（次数 + 日期）
├── loadDocConfig(docPath)
│     ├─ 查 Redis 缓存
│     ├─ 缓存未命中 → 查 PostgreSQL
│     ├─ 合并优先级链（Front Matter > 单文档 > 目录 > 仓库）
│     └─ 写入 Redis 缓存（TTL 5 分钟）
└── getPermissions(userId, docPath)
      └─ 返回用户在该文档上的操作权限集合
```

### 9.4 数据库完整设计

```plantuml
@startuml
skinparam componentStyle rectangle
title 用户阅读管理系统 - 数据表关系

rectangle "users\n用户表" as Users {
  rectangle "id, phone, wechat_openid\nnickname, role, list_type\ngroup_id, status" as UF
}

rectangle "user_groups\n用户组表" as Groups {
  rectangle "id, name, description" as GF
}

rectangle "user_group_members\n组成员表" as Members {
  rectangle "user_id, group_id" as MF
}

rectangle "doc_access_policies\n文档权限策略表" as Policies {
  rectangle "id, doc_pattern, access_level\npermissions, allowed_users\nallowed_groups, priority" as PF
}

rectangle "doc_usage_config\n使用控制表" as Usage {
  rectangle "doc_id, max_views\nmax_views_user\navailable_from, expires_at" as UGF
}

rectangle "doc_view_logs\n阅读日志表" as Logs {
  rectangle "id, doc_id, user_id\nfingerprint, ip, duration\nviewed_at" as LF
}

rectangle "antibot_blocklist\n封禁记录表" as Block {
  rectangle "id, ip, fingerprint\nuser_id, reason\nblocked_until" as BF
}

Users -right-> Members
Groups -down-> Members
Users -down-> Logs
Policies -down-> Usage
@enduml
```

---

## 十、管理后台

### 10.1 功能模块

管理后台作为 MkDocs Guard 的 Web 管理界面，提供以下功能：

| 模块 | 功能 |
|------|------|
| 用户管理 | 查看用户列表、搜索、设置白名单/黑名单、编辑用户组 |
| 权限管理 | 配置文档访问策略、目录级/标签级批量授权、授权用户/组 |
| 使用控制 | 设置文档阅读次数上限、有效期、查看用量 |
| 阅读统计 | 文档热度排行、用户阅读画像、渠道来源分析 |
| 安全中心 | 爬虫拦截日志、封禁记录管理、异常告警配置 |
| 系统配置 | 短信网关配置、微信开放平台参数、会话策略调整 |

### 10.2 管理后台技术栈

| 组件 | 技术 |
|------|------|
| 前端框架 | React + Ant Design |
| 后端 API | Node.js + Express（与 Guard 同进程） |
| 认证 | Keycloak SSO（admin 角色） |
| 部署 | 与 MkDocs Guard 同容器，路由 `/admin/` |

---

## 十一、部署方案

### 11.1 服务清单

| 服务 | 端口 | 部署位置 | 说明 |
|------|------|---------|------|
| Nginx | 443 | 互联网应用服务器 | SSL 终止 + auth_request |
| MkDocs 静态站 | 8001 | 互联网应用服务器 | 由 DocForge 自动构建 |
| MkDocs Guard | 3100 | 互联网应用服务器 | 认证网关 + 权限引擎 + 管理后台 |
| Keycloak | 8080 | 互联网应用服务器（已有） | SSO 认证中心 |
| Redis | 6379 | 互联网应用服务器 | 会话 + 缓存 + 限流 |
| PostgreSQL | 5432 | 私有云（已有） | 用户数据 + 权限策略 + 日志 |
| Umami | 3000 | 互联网应用服务器（已有） | 统计分析 |

### 11.2 Docker Compose 部署

```yaml
services:
  mkdocs-guard:
    image: node:20-alpine
    ports:
      - "3100:3100"
    environment:
      - DATABASE_URL=postgresql://guard:***@db:5432/mkdocs_guard
      - REDIS_URL=redis://redis:6379/2
      - KEYCLOAK_URL=https://sso.writech.cn
      - KEYCLOAK_REALM=writech
      - WECHAT_APP_ID=${WECHAT_APP_ID}
      - WECHAT_APP_SECRET=${WECHAT_APP_SECRET}
      - SMS_ACCESS_KEY=${SMS_ACCESS_KEY}
      - SMS_ACCESS_SECRET=${SMS_ACCESS_SECRET}
    depends_on:
      - redis

  mkdocs-site:
    image: nginx:alpine
    ports:
      - "8001:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:
```

---

## 十二、实施路线图

| 阶段 | 时间 | 任务 | 交付物 |
|------|------|------|--------|
| **一期：基础认证** | 第 1-3 周 | MkDocs Guard + Nginx auth_request 集成；微信扫码登录；短信验证码登录；会话管理 | 用户可通过微信/短信登录访问受控文档 |
| **二期：权限引擎** | 第 4-6 周 | PermEngine 开发；Front Matter 权限解析；目录级 `.access.yml` 继承；白名单/黑名单管理 | 文档可按级别和用户/组授权 |
| **三期：使用控制** | 第 7-8 周 | 阅读次数限制；有效期管理；渐进式体验（摘要预览 + 模糊化） | 文档使用可按次数和时间控制 |
| **四期：防爬虫** | 第 9-10 周 | AntiBot 四层防护部署；智能封禁规则；内容异步加载 | 爬虫有效拦截 |
| **五期：统计与后台** | 第 11-13 周 | Umami 自定义埋点；管理后台开发；阅读统计看板；安全日志 | 管理员可视化管理全部功能 |
| **六期：优化上线** | 第 14-15 周 | 性能调优；安全审计；用户体验打磨；正式上线 | 系统全功能投入运营 |