John/system-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新

Browse Source
This commit is contained in:
jiahong
2026-03-25 22:52:11 +08:00
parent 2b1cceb669
commit 6333cf1091
1 changed files with 925 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
IT服务平台/ICT服务平台/对MkDoc构建用户系统.md
+925
View File
@@ -0,0 +1,925 @@
# 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 周 | 性能调优；安全审计；用户体验打磨；正式上线 | 系统全功能投入运营 |