1. 整体架构

1. 核心流程：
   • 无感刷新：通过 Refresh Token 自动获取新的 Access Token。
   • 黑名单机制：将需要失效的 Token（如用户主动登出后的旧 Token）存入 Redis，并在验证时检查黑名单。

2. 技术栈：
   • JWT（Access Token + Refresh Token）
   • Redis（存储黑名单和 Refresh Token）
   • 后端框架（如 Node.js/Express、Spring Boot 等）

2. 实现步骤

2.1 服务器端设计

(1) 登录接口

用户登录成功后，生成并返回 Access Token 和 Refresh Token，同时将 Refresh Token 存入 Redis。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// Node.js + Express 示例
app.post("/login", async (req, res) => {
  const { username, password } = req.body
  // 1. 验证用户身份
  const user = await validateUser(username, password)
  if (!user) return res.status(401).json({ error: "Invalid credentials" })

  // 2. 生成 Access Token（有效期短）
  const accessToken = jwt.sign({ userId: user.id }, "ACCESS_TOKEN_SECRET", {
    expiresIn: "15m",
  })

  // 3. 生成 Refresh Token（有效期长）
  const refreshToken = jwt.sign({ userId: user.id }, "REFRESH_TOKEN_SECRET", {
    expiresIn: "7d",
  })

  // 4. 存储 Refresh Token 到 Redis（关联用户ID）
  await redisClient.set(
    `refresh_token:${user.id}`,
    refreshToken,
    "EX",
    7 * 24 * 60 * 60
  )

  res.json({ accessToken, refreshToken })
})

(2) 刷新接口

通过 Refresh Token 获取新的 Access Token，并验证 Redis 中的有效性。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

app.post("/refresh-token", async (req, res) => {
  const { refreshToken } = req.body
  try {
    // 1. 验证 Refresh Token 是否有效
    const decoded = jwt.verify(refreshToken, "REFRESH_TOKEN_SECRET")
    const userId = decoded.userId

    // 2. 检查 Redis 中是否存在该用户的 Refresh Token
    const storedRefreshToken = await redisClient.get(`refresh_token:${userId}`)
    if (refreshToken !== storedRefreshToken) {
      return res.status(401).json({ error: "Invalid refresh token" })
    }

    // 3. 生成新的 Access Token
    const newAccessToken = jwt.sign({ userId }, "ACCESS_TOKEN_SECRET", {
      expiresIn: "15m",
    })

    res.json({ accessToken: newAccessToken })
  } catch (error) {
    res.status(401).json({ error: "Refresh token expired or invalid" })
  }
})

(3) 黑名单机制

用户登出或需要撤销 Token 时，将旧 Access Token 加入 Redis 黑名单。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

app.post("/logout", async (req, res) => {
  const { accessToken } = req.body
  // 1. 解码 Access Token 获取过期时间
  const decoded = jwt.decode(accessToken)
  const exp = decoded.exp

  // 2. 计算剩余有效期（秒）
  const ttl = exp - Math.floor(Date.now() / 1000)

  // 3. 将 Token 加入黑名单（过期后自动删除）
  if (ttl > 0) {
    await redisClient.set(`blacklist:${accessToken}`, "revoked", "EX", ttl)
  }

  // 4. 删除该用户的 Refresh Token（可选）
  const userId = decoded.userId
  await redisClient.del(`refresh_token:${userId}`)

  res.json({ message: "Logged out successfully" })
})

(4) 中间件：验证 Access Token

在每次请求中验证 Access Token 是否在黑名单中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

const authMiddleware = async (req, res, next) => {
  const authHeader = req.headers.authorization
  const accessToken = authHeader?.split(" ")[1]

  if (!accessToken) {
    return res.status(401).json({ error: "No token provided" })
  }

  try {
    // 1. 检查 Token 是否在黑名单
    const isBlacklisted = await redisClient.exists(`blacklist:${accessToken}`)
    if (isBlacklisted) {
      return res.status(401).json({ error: "Token revoked" })
    }

    // 2. 验证 Token 有效性
    const decoded = jwt.verify(accessToken, "ACCESS_TOKEN_SECRET")
    req.userId = decoded.userId
    next()
  } catch (error) {
    res.status(401).json({ error: "Invalid or expired token" })
  }
}

2.2 客户端设计

客户端需在 Access Token 过期前自动刷新，并在登出时触发黑名单机制。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// 示例：Axios 请求拦截器（React/Vue）
axios.interceptors.request.use(async (config) => {
  const accessToken = localStorage.getItem("accessToken")
  const refreshToken = localStorage.getItem("refreshToken")

  // 1. 检查 Access Token 是否即将过期
  const decoded = jwt.decode(accessToken)
  const isExpired = decoded.exp * 1000 < Date.now() + 5 * 60 * 1000 // 过期前5分钟

  if (isExpired) {
    try {
      // 2. 自动刷新 Token
      const response = await axios.post("/refresh-token", { refreshToken })
      const newAccessToken = response.data.accessToken
      localStorage.setItem("accessToken", newAccessToken)
      config.headers.Authorization = `Bearer ${newAccessToken}`
    } catch (error) {
      // 刷新失败，跳转登录页
      window.location.href = "/login"
    }
  }

  return config
})

3. Redis 黑名单优化

1. 自动清理：通过设置 EX 参数，让 Redis 自动删除过期的黑名单 Token。
2. 内存管理：定期清理无效数据，避免内存占用过多。
3. 分片存储：使用 blacklist:${token} 的键名格式，避免单个 Key 过大。

4. 安全性增强

1. Refresh Token 存储：
   • 使用 httpOnly Cookie 存储 Refresh Token，防止 XSS 攻击。
   • 每次刷新后生成新的 Refresh Token，旧 Token 立即失效（需更新 Redis）。
2. Token 轮换：
   • 每次刷新 Access Token 时，生成新的 Refresh Token 并替换 Redis 中的旧值。
3. 密钥管理：
   • 使用强随机密钥（如 ACCESS_TOKEN_SECRET 和 REFRESH_TOKEN_SECRET）。
   • 定期轮换密钥，降低泄露风险。

5. 流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

用户登录
  │
  ├─ 生成 Access Token（15分钟）和 Refresh Token（7天）
  │
  ├─ 存储 Refresh Token 到 Redis（关联用户ID）
  │
  └─ 返回 Token 给客户端

用户请求受保护接口
  │
  ├─ 验证 Access Token 是否在黑名单
  │
  ├─ 若在黑名单 → 拒绝请求
  │
  └─ 若有效 → 允许访问

Access Token 过期前
  │
  ├─ 客户端自动调用刷新接口
  │
  ├─ 验证 Refresh Token（检查 Redis）
  │
  ├─ 生成新 Access Token
  │
  └─ 更新客户端存储

用户登出
  │
  ├─ 将当前 Access Token 加入 Redis 黑名单
  │
  └─ 删除 Redis 中的 Refresh Token

GitHub Actions 升级与部署问题解决

在使用 GitHub Actions 部署项目时，遇到了构建和部署相关的问题。本文记录了问题的原因、解决方案以及升级后的配置。

问题描述

1. 构建报错

• 时间：2025 年 1 月 14 日

• 错误信息：

  1 2	Install Dependencies Process completed with exit code 1.

• 详细信息：

  1 2 3

  Your workflow is using a version of actions/cache that is scheduled for deprecation, actions/cache@v2. Please update your workflow to use either v3 or v4 of actions/cache to avoid interruptions. Learn more: https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions/#actions-cache-v1-v2-and-actions-toolkit-cache-package-closing-down

2. 环境警告

• 警告信息：

  1 2	ubuntu-latest pipelines will use ubuntu-24.04 soon. For more details, see https://github.com/actions/runner-images/issues/10636

问题分析

1. actions/cache 版本过时：

   • 当前使用的是 actions/cache@v2，但该版本即将被弃用，需要升级到 v3 或 v4。

2. Node.js 版本过低：

   • 使用的 Node.js 版本为 16，建议升级到更高版本（如 20）以获得更好的支持。

3. GitHub Actions 部署插件版本过时：

   • 使用的 actions/deploy-pages@v2 版本较旧，建议升级到 v4。

解决方案

1. 升级构建脚本

修改前

1
2
3

node-version: "16"
uses: actions/cache@v2
uses: actions/upload-pages-artifact@v2

修改后

1
2
3

node-version: "20"
uses: actions/cache@v4
uses: actions/upload-pages-artifact@v3

2. 升级部署脚本

修改前

1
2
3
4

steps:
  - name: Deploy to GitHub Pages
    id: deployment
    uses: actions/deploy-pages@v2

修改后

1
2
3
4

steps:
  - name: Deploy to GitHub Pages
    id: deployment
    uses: actions/deploy-pages@v4

结果

• 构建成功：升级后，build 阶段顺利完成。
• 部署成功：actions/deploy-pages@v4 成功将静态文件部署到 GitHub Pages。

总结

通过升级 GitHub Actions 的相关插件和配置文件，解决了构建和部署失败的问题。以下是关键点：

1. 定期检查 GitHub Actions 插件的版本更新。
2. 使用最新的 Node.js 和 Ubuntu 环境以避免兼容性问题。
3. 参考官方文档和变更日志，及时调整工作流配置。

参考链接

• GitHub Actions 官方文档
• actions/cache 更新公告
• Ubuntu 24.04 更新详情

1
2

---

一、快速入门：MySQL 基础（1-2 周）

目标

掌握 MySQL 核心概念、基础 SQL 语法，能独立完成简单的 CRUD 和数据查询。

学习路径

1. 安装与配置
   • 下载 MySQL Community Server 或使用 Docker 快速部署。
   • 学习使用 mysql 命令行工具或 MySQL Workbench（图形化界面）。

2. 核心概念
   • 关系型数据库基础：表（Table）、行（Row）、列（Column）、主键（Primary Key）、外键（Foreign Key）。
   • SQL 分类：DDL（建表）、DML（增删改查）、DQL（查询）、TCL（事务）。

3. 基础 SQL 语法

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   -- 创建数据库和表 CREATE DATABASE myapp; USE myapp; CREATE TABLE users ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE ); -- CRUD 操作 INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com'); SELECT * FROM users WHERE id = 1; UPDATE users SET name = 'Bob' WHERE id = 1; DELETE FROM users WHERE id = 1;

4. 必学重点
   • JOIN 操作：INNER JOIN, LEFT JOIN。
   • 聚合函数：COUNT(), SUM(), GROUP BY, HAVING。
   • 事务控制：BEGIN, COMMIT, ROLLBACK。

推荐资源

• 交互式练习：SQLBolt（免费在线 SQL 练习）
• 书籍：《MySQL 必知必会》（适合快速入门）
• 文档：MySQL 8.0 官方文档

二、进阶：数据库设计与优化（2-3 周）

目标

设计规范的数据库结构，理解索引和性能优化，避免“写代码一时爽，上线后火葬场”。

学习路径

1. 数据库设计原则
   • 三范式（3NF）：消除冗余，保证数据一致性。
   • ER 图工具：使用 Draw.io 或 dbdiagram.io 设计表关系。

2. 索引优化
   • 理解 B+Tree 索引原理。
   • 何时创建索引？高频查询字段、WHERE/JOIN/ORDER BY 涉及的字段。
   • 使用 EXPLAIN 分析查询性能。

3. 常见问题与优化
   • 慢查询：开启慢查询日志，定位性能瓶颈。
   • 分页优化：避免 LIMIT 100000, 10，改用游标分页或覆盖索引。
   • 避免全表扫描：合理使用索引和 WHERE 条件。

4. 安全与备份
   • SQL 注入防护：永远不要拼接 SQL 字符串！
   • 备份工具：mysqldump 或 xtrabackup。

推荐资源

• 书籍：《高性能 MySQL》（第 4 章索引、第 5 章优化）
• 工具：Percona Toolkit（诊断数据库性能）

三、工程化整合：Node.js + MySQL（1 周）

目标

将 MySQL 集成到 Node.js 后端，掌握 ORM 和 SQL 安全实践。

学习路径

1. 原生驱动连接
   • 使用 mysql2 或 mysql 库（推荐 mysql2/promise 支持 Promise）：

   1 2 3 4 5 6 7 8 9 10 11

   const mysql = require("mysql2/promise") const pool = mysql.createPool({ host: "localhost", user: "root", database: "myapp", waitForConnections: true, connectionLimit: 10, }) // 查询示例 const [rows] = await pool.query("SELECT * FROM users WHERE id = ?", [1])

2. ORM 框架（可选）
   • Sequelize：主流 ORM，适合复杂业务逻辑。
   • Knex.js：轻量级 SQL 查询构建器，更接近原生 SQL。

3. 关键实践
   • 连接池管理：避免频繁创建连接。
   • 防 SQL 注入：永远使用参数化查询（如 ? 占位符）。
   • 事务处理：保证数据一致性。

4. 项目实战
   • 用 React + Node.js + MySQL 实现一个 Todo List 或 博客系统：
   ◦ 前端（React）：展示数据、提交表单。
   ◦ 后端（Express/Koa）：提供 RESTful API。
   ◦ 数据库（MySQL）：存储用户、文章等数据。

四、学习建议与避坑指南

1. 不要死记语法
   • 多用 SHOW CREATE TABLE、DESCRIBE table 查看表结构。
   • 善用 ChatGPT 辅助写复杂 SQL（但要理解原理）。

2. 避免新手陷阱
   • 不要把所有字段设为 NULL（用 NOT NULL 约束）。
   • 不要滥用 SELECT *（明确指定字段）。
   • 不要忽视索引，但也不要过度索引。

3. 学习节奏
   • 每天 1-2 小时，边学边写代码。
   • 优先掌握常用功能（80%场景用 20%的语法）。

五、延伸学习（可选）

• 云数据库：尝试阿里云 RDS 或 AWS RDS。
• NoSQL 对比：了解 MongoDB 的适用场景。
• TypeORM：如果你在用 TypeScript，可学习 TypeORM。

通过这个方案，你可以在 1-2 个月内掌握 MySQL 的核心技能，并直接应用于现有技术栈中。