二维码链路教学 Demo 代码拆解

1. 先看整体：这个 Demo 到底在演示什么

它不是一个普通下载页，而是在演示“二维码背后的完整链路”。学生扫码看到的只是一个入口，真正复杂的是入口后面的服务端和浏览器脚本配合。

小白记忆法：二维码只是门牌号，真正的系统在门后面。门后面有线路调度、环境校验、下载授权和审计记录。

2. 文件地图：每个文件负责什么

3. 请求怎么流转：从浏览器到 Node

浏览器每次访问一个 URL，Node 的 server.js 都会进入同一个入口：

const server = http.createServer((req, res) => {
  const url = new URL(req.url, 'http://localhost:' + PORT);
  const pathname = safeDecodeURIComponent(url.pathname);
  ...
});

这段代码的意思是：

主要路由如下：

4. server.js 逐块拆解

4.1 引入模块

const crypto = require("crypto");
const http = require("http");
const fs = require("fs");
const path = require("path");

4.2 配置读取

DEFAULT_CONFIG 是默认配置。readJsonConfig() 负责读取 JSON 文件，normalizeConfig() 负责把字段统一成字符串或数组。

const legacyConfig = readJsonConfig("config.json") || {};
const realConfig = readJsonConfig("real-download-config.json");
config = normalizeConfig(Object.assign({}, legacyConfig, realConfig || {}), ...);

意思是：先读仓库里的安全配置 config.json，如果部署服务器上有真实配置 real-download-config.json，就用真实配置覆盖。

为什么真实配置不提交？因为真实下载地址、真实渠道、真实来源属于课堂现场数据，迭代代码不应该夹带现场配置。

4.3 通用工具函数

4.4 线路健康评分

真实线路调度不是简单随机。Demo 里给三类父域设置基础权重和延迟：

const LINE_PROFILES = [
  { parentDomain: "hglive.org", weight: 96, baseLatencyMs: 420 },
  { parentDomain: "jtyw.org", weight: 86, baseLatencyMs: 640 },
  { parentDomain: "imagesworks.com.youfenfa.shop", weight: 78, baseLatencyMs: 780 }
];

课堂一句话：随机子域名解决“每次入口不同”，健康评分解决“选哪条线路更合理”。

4.5 动态路径 token

function generatePathTokens(userId) {
  const campaignToken = randomHex(32);
  const landingToken = randomHex(8);
  return {
    landingPath: "/" + campaignToken + "/" + landingToken + "/index.html"
  };
}

它模拟真实案例中的动态路径：

/53fe1a6f75cbee41564222f9e81f59de/825517ba/index.html?userId=25888

每次访问都变，学生看到“二维码固定但后面路径不固定”，原因就在这里。

升级后，路径 token 不只是展示。入口页生成 token 时，后台会把它登记到 pathTokenStore，并绑定：

所以现在后台处理动态路径分两步：

第一步：用正则解析 /_line/32位token/8位token/index.html
第二步：去 pathTokenStore 校验它是不是后台签发、是否过期、是否重放、userId/lineHost 是否匹配

随便编一个路径会返回 403 unknown_path_token；同一个路径成功落地后再次访问会返回 403 replayed_path_token。

4.6 Guard Challenge

小白理解：

服务端：我给你一道题
浏览器：我用 JS 算答案
服务端：答案正确，放行；答案错误，403

5. Guard.js 拆解：为什么不是“前端摆设”

项目里有两种 Guard：

动态 Guard 脚本的核心动作：

1. 读取 guard cookie
2. 拿 cid、nonce、exp
3. 用浏览器 Web Crypto 算 SHA-256
4. 写入 guardret 和 guard_pass cookie
5. 跳回原页面

重点：如果只有前端 JS，学生可以关掉或改掉；但这里服务端还会验 Cookie，所以它不是简单摆设。

6. 下载与 token：为什么错误链接会 403

下载配置接口 /share/landingConfig.html 会返回普通配置，也会返回签名下载地址：

{
  "androidDownload": "...",
  "signedAndroidDownload": "/download/signed?token=...&sig=...",
  "signedDownloadTtlSeconds": 300
}

签名 token 的组成

验证顺序

7. 审计和线路评分：老师如何拿证据说话

项目里有一个内存审计队列 auditEvents，关键动作都会记录：

打开 /audit.html 可以看到这些事件。它的价值是：学生问“真的实现了吗”，老师可以让学生自己看审计记录。

线路健康评分也在这里展示，包含 score、generated、selected、success、avgLatencyMs。

8. 测试脚本：一条命令证明核心功能

scripts/verify-teaching-flow.js 是老师的“验收老师”。它会自己启动临时服务，然后自动访问接口。

npm test

它验证这些事：

9. 配置文件：为什么有 config.json 和 real-download-config.json

这种做法叫“代码和环境配置分离”。代码可以公开迭代，真实环境值留在服务器。

小白不要把数据库密码、SSH 密钥、证书私钥、真实 API Key 提交到 Git。

10. 课堂讲法：怎么让学生听懂

先讲一句话

这个 Demo 不是为了把跳转做得神秘，而是为了把二维码背后的工程链路讲透明。

再讲三层

最后给学生的总结

二维码只是入口。
真正专业的是入口后面的系统：
能动态调度、能校验访问、能保护下载、能记录审计、能自动验收。

11. 生产化演进：从单机教学到分布式系统

现在 Demo 又补了一层生产化底座，但老师要诚实说明：这叫“朝生产靠近”，不是一夜之间变成完整生产平台。

下一步真正分布式要把文件持久化替换成 Redis：路径 token 用 Redis TTL，下载 nonce 用 SETNX，审计日志进 Redis Stream、Kafka 或 ClickHouse。

12. 学生 Node 原版：哪里做得对，哪里被老师补强

学生原版不是简单页面，它已经具备一个完整下载链路的雏形。老师验收时不能只看“页面能不能打开”，还要看前端和后端有没有约定、状态有没有校验、别人能不能复现。

12.1 学生原版页面协议

学生原版前端 homework/src/download-app.js 会请求：

GET /share/landingConfig.html

然后按这个格式读取后端配置：

{
  "m_istatus": 1,
  "m_strMessage": "success",
  "m_object": {
    "shareUserId": "25888",
    "channelCode": "classroom",
    "androidDownload": "/download/signed?token=...&sig=...",
    "iosDownload": "/download/signed?token=...&sig=...",
    "androidDownloadMirrors": []
  }
}

这就是“页面不变，后端迁移”的关键：前端继续读 m_istatus/m_object，后端从 Node 换成 Java。

12.2 学生作业的优点

12.3 老师补强点

13. Java 21 企业级工程：老师改造版怎么讲

homework-java/ 不是把 Node 代码逐行翻译成 Java，而是把同一条二维码下载链路拆成企业后端常见分层。页面仍然是学生原版“蝶衣官方下载”，服务端能力由 Java 接管。

13.1 Java 工程目录地图

13.2 Java 版真实链路

13.3 页面一致性怎么证明

老师改造后不是打开一个“老师自制页面”，而是让 Java 返回学生原版页面需要的资源和字段：

13.4 Java 版怎么验收

cd homework-java
JAVA_HOME=/Users/zm/Downloads/codex-jdk/zulu21 PATH=/Users/zm/Downloads/codex-jdk/zulu21/bin:$PATH mvn test

BASE_URL=https://wi2w.dmbdz.com AUDIT_TOKEN=<服务器审计令牌> npm run test:remote

测试覆盖：未知动态路径拒绝、Guard challenge、Guard 放行、路径重放拒绝、pageToken 保护、签名下载首次 302、下载重放 403、metrics 鉴权、课堂讲解页可访问。

13.5 给学生的结论

学生 Node 原版解决“能跑和能演示”。
老师 Java 改造解决“能部署、能审计、能防重放、能多实例共享、能生产配置兜底”。
专业不是把页面改得不一样，而是在页面不变的前提下，把后端工程能力补上。

14. 参考二维码增强链路：多级中转、归因 SDK、Scheme

后面这个参考二维码不是单纯“二维码入口到下载页”，它更像三段式链路：入口页先执行一段 JS，再跳第二个中转页，最后到真正落地页。现在 Java 主扫码入口也已接入两级中转：/yyq/share/jumpShare.html 会先进入 /_relay/.../r1.html，再进入 /_relay/.../r2.html，最后回到原来的 /_line/.../index.html、Guard 和签名下载链路。

14.1 老师补的三块

14.2 和参考二维码怎么对应

14.3 小白版流程

这就能严谨回答学生：我们没有照抄第三方混淆脚本，而是把它背后的工程结构拆出来，并补上透明归因、pageToken 保护、签名下载和审计记录。比原案例更适合教学，也更合规。