<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog</id>
    <title>Software Tech Notebook Blog</title>
    <updated>2026-11-06T00:00:00.000Z</updated>
    <generator>https://github.com/jpmonette/feed</generator>
    <link rel="alternate" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog"/>
    <subtitle>Software Tech Notebook Blog</subtitle>
    <icon>https://software-tech-notebook.lovefreedom1128.workers.dev/img/favicon.svg</icon>
    <entry>
        <title type="html"><![CDATA[API 网关笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API网关原理与选型笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API网关原理与选型笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[由旧稿重写。原笔记仅有 2 个外部链接，本笔记系统介绍网关的定位、能力、与反向代理的区别，并给出一个可运行的 FastAPI 网关 Demo（4 个中间件 + 路由转发 + 完整流程图）。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>由旧稿重写。原笔记仅有 2 个外部链接，本笔记<strong>系统介绍网关的定位、能力、与反向代理的区别</strong>，并<strong>给出一个可运行的 FastAPI 网关 Demo</strong>（4 个中间件 + 路由转发 + 完整流程图）。</p>
<p>鉴权与登录见 <code>[[鉴权与登录笔记]]</code>；权限模型（Casbin / RBAC / ReBAC）见 <code>[[权限模型与Casbin实践笔记]]</code>。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录">目录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#%E7%9B%AE%E5%BD%95" class="hash-link" aria-label="目录的直接链接" title="目录的直接链接" translate="no">​</a></h2>
<ol>
<li class="">什么是网关 + 为什么需要</li>
<li class="">网关核心能力清单</li>
<li class="">网关 vs 反向代理 vs Ingress vs Sidecar</li>
<li class="">网关选型（Kong / APISIX / Spring Cloud Gateway / 自研）</li>
<li class="">Python FastAPI 网关 Demo 流程图</li>
<li class="">关键中间件实现要点</li>
<li class="">生产部署清单</li>
<li class="">网关常见坑</li>
<li class="">关联笔记</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-什么是网关--为什么需要">1. 什么是网关 + 为什么需要<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#1-%E4%BB%80%E4%B9%88%E6%98%AF%E7%BD%91%E5%85%B3--%E4%B8%BA%E4%BB%80%E4%B9%88%E9%9C%80%E8%A6%81" class="hash-link" aria-label="1. 什么是网关 + 为什么需要的直接链接" title="1. 什么是网关 + 为什么需要的直接链接" translate="no">​</a></h2>
<p><strong>API 网关（API Gateway）</strong> 是系统的<strong>唯一对外入口</strong>，所有外部流量先经过网关，再到内部的具体服务。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-为什么需要网关">1.1 为什么需要网关<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#11-%E4%B8%BA%E4%BB%80%E4%B9%88%E9%9C%80%E8%A6%81%E7%BD%91%E5%85%B3" class="hash-link" aria-label="1.1 为什么需要网关的直接链接" title="1.1 为什么需要网关的直接链接" translate="no">​</a></h3>
<p>没有网关时：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[客户端 A] ──┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[客户端 B] ──┼──► [用户服务]   各自要处理：鉴权、限流、CORS、日志…</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[客户端 C] ──┼──► [订单服务]   重复代码散落在每个服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">             └──► [商品服务]</span><br></div></code></pre></div></div>
<p>有网关后：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[所有客户端] ──► [网关]  ──► [用户服务 / 订单服务 / 商品服务]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                       └─ 统一处理：鉴权 / 限流 / 路由 / 日志</span><br></div></code></pre></div></div>
<p><strong>核心价值</strong>：</p>
<ul>
<li class=""><strong>统一入口</strong>：客户端只需对接网关</li>
<li class=""><strong>集中治理</strong>：鉴权、限流、日志、安全策略<strong>一处实现</strong></li>
<li class=""><strong>解耦</strong>：客户端不感知后端服务的拆分 / 合并 / 替换</li>
<li class=""><strong>安全</strong>：隐藏内部服务拓扑、过滤恶意请求</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-网关的常见别名">1.2 网关的常见别名<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#12-%E7%BD%91%E5%85%B3%E7%9A%84%E5%B8%B8%E8%A7%81%E5%88%AB%E5%90%8D" class="hash-link" aria-label="1.2 网关的常见别名的直接链接" title="1.2 网关的常见别名的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>Edge Service</strong>（边缘服务）</li>
<li class=""><strong>BFF</strong>（Backend For Frontend，为特定前端定制的网关层）</li>
<li class=""><strong>API Gateway</strong>（最常见）</li>
<li class=""><strong>Ingress</strong>（K8s 术语）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-网关核心能力清单">2. 网关核心能力清单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#2-%E7%BD%91%E5%85%B3%E6%A0%B8%E5%BF%83%E8%83%BD%E5%8A%9B%E6%B8%85%E5%8D%95" class="hash-link" aria-label="2. 网关核心能力清单的直接链接" title="2. 网关核心能力清单的直接链接" translate="no">​</a></h2>





















































<table><thead><tr><th>能力</th><th>说明</th></tr></thead><tbody><tr><td><strong>路由</strong></td><td>按 path / host / header / query 把请求分发到不同下游</td></tr><tr><td><strong>鉴权</strong></td><td>JWT 校验、OAuth2 introspection、API Key 校验</td></tr><tr><td><strong>限流</strong></td><td>按 IP / 用户 / 路径 / 租户维度限流</td></tr><tr><td><strong>熔断</strong></td><td>下游超时或 5xx 比例超阈值时快速失败，避免拖垮</td></tr><tr><td><strong>缓存</strong></td><td>缓存 GET 响应（Redis / 内存）</td></tr><tr><td><strong>日志</strong></td><td>结构化访问日志、请求 ID 链路追踪</td></tr><tr><td><strong>监控</strong></td><td>QPS / 延迟 / 错误率指标暴露（Prometheus）</td></tr><tr><td><strong>协议转换</strong></td><td>HTTP → gRPC / WebSocket / GraphQL</td></tr><tr><td><strong>CORS</strong></td><td>跨域统一处理</td></tr><tr><td><strong>请求改写</strong></td><td>path 重写、header 注入、请求/响应体转换</td></tr><tr><td><strong>安全</strong></td><td>WAF、防 SQL 注入、防爬虫、黑白名单</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-网关-vs-反向代理-vs-ingress-vs-sidecar">3. 网关 vs 反向代理 vs Ingress vs Sidecar<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#3-%E7%BD%91%E5%85%B3-vs-%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86-vs-ingress-vs-sidecar" class="hash-link" aria-label="3. 网关 vs 反向代理 vs Ingress vs Sidecar的直接链接" title="3. 网关 vs 反向代理 vs Ingress vs Sidecar的直接链接" translate="no">​</a></h2>






























<table><thead><tr><th>类型</th><th>定位</th><th>典型</th></tr></thead><tbody><tr><td><strong>反向代理</strong></td><td>转发请求 + 负载均衡，<strong>运维层</strong></td><td>nginx / HAProxy</td></tr><tr><td><strong>API 网关</strong></td><td>反向代理 + <strong>业务层能力</strong>（鉴权/限流/灰度）</td><td>Kong / APISIX / Spring Cloud Gateway</td></tr><tr><td><strong>Ingress</strong></td><td>K8s 中的网关抽象（标准 + 多种实现）</td><td>Ingress-NGINX / Traefik / Contour</td></tr><tr><td><strong>服务网格 Sidecar</strong></td><td>每个服务实例旁的代理（<strong>东西向流量</strong>）</td><td>Envoy + Istio / Linkerd</td></tr></tbody></table>
<p><strong>关系</strong>：</p>
<ul>
<li class=""><strong>反向代理 ⊂ API 网关</strong>（网关 = 反向代理 + 业务能力）</li>
<li class=""><strong>Ingress ⊂ API 网关</strong>（Ingress 是 K8s 生态的网关实现）</li>
<li class=""><strong>Sidecar ≠ 网关</strong>（一个管南北向出口，一个管东西向内部通信，但都用 Envoy）</li>
</ul>
<p><strong>架构位置</strong>：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">客户端 ──► [反向代理/LB] ──► [API 网关] ──► [微服务 A, B, C]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  └──► [鉴权/限流/路由]</span><br></div></code></pre></div></div>
<blockquote>
<p>网关通常<strong>不和</strong>反向代理合并（除非追求极致简单）：nginx 终止 TLS + 网关做业务，
是生产标配。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-网关选型">4. 网关选型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#4-%E7%BD%91%E5%85%B3%E9%80%89%E5%9E%8B" class="hash-link" aria-label="4. 网关选型的直接链接" title="4. 网关选型的直接链接" translate="no">​</a></h2>








































<table><thead><tr><th>场景</th><th>推荐</th><th>说明</th></tr></thead><tbody><tr><td><strong>小团队 / 学习 / 内部工具</strong></td><td>FastAPI 自研（见本文 demo）</td><td>灵活、贴合业务、Python 全栈</td></tr><tr><td><strong>中大型 / 多语言后端</strong></td><td><strong>APISIX</strong> / <strong>Kong</strong></td><td>Lua 插件丰富、高性能、社区活跃</td></tr><tr><td><strong>Spring 体系</strong></td><td>Spring Cloud Gateway</td><td>集成 Spring 全家桶</td></tr><tr><td><strong>K8s 流量入口</strong></td><td>Ingress-NGINX / Traefik</td><td>标准 Ingress</td></tr><tr><td><strong>云原生全功能</strong></td><td>Envoy + Istio Gateway</td><td>服务网格统一</td></tr><tr><td><strong>Serverless</strong></td><td>AWS API Gateway / 阿里云 API 网关</td><td>托管、免运维</td></tr></tbody></table>
<p><strong>自研网关的边界</strong>：流量不大 + 业务简单 + Python 技术栈 → 自研够用。
流量大 + 多团队 + 复杂路由 → 上 APISIX。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-python-fastapi-网关-demo-流程图">5. Python FastAPI 网关 Demo 流程图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#5-python-fastapi-%E7%BD%91%E5%85%B3-demo-%E6%B5%81%E7%A8%8B%E5%9B%BE" class="hash-link" aria-label="5. Python FastAPI 网关 Demo 流程图的直接链接" title="5. Python FastAPI 网关 Demo 流程图的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-整体架构">5.1 整体架构<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#51-%E6%95%B4%E4%BD%93%E6%9E%B6%E6%9E%84" class="hash-link" aria-label="5.1 整体架构的直接链接" title="5.1 整体架构的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">                    ┌────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │      Client        │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    └──────────┬─────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                               │ HTTPS</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    ┌──────────▼─────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │  TLS Termination   │  ← nginx / 云 LB</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    └──────────┬─────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                               │ HTTP</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    ┌──────────▼─────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │      Gateway (FastAPI)               │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │                                       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │  [Middleware 链]                      │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │   ① TrustedHostMiddleware              │  防 Host 注入</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │   ② RequestContextMiddleware            │  生成 X-Request-ID</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │   ③ RateLimitMiddleware                │  滑动窗口限流</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │   ④ AuthMiddleware                     │  JWT 校验</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │   ⑤ ReverseProxyMiddleware             │  路由转发</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │                                       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    └──────┬──────────┬──────────┬─────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                           │          │          │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  /api/users      /api/orders  /api/products</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                           │          │          │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    ┌──────▼──┐  ┌────▼───┐  ┌────▼────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │  User   │  │ Order  │  │Product  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │ Service │  │Service │  │ Service │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    │ :9001   │  │ :9002  │  │ :9003   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    └─────────┘  └────────┘  └─────────┘</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-中间件顺序为什么重要">5.2 中间件顺序为什么重要<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#52-%E4%B8%AD%E9%97%B4%E4%BB%B6%E9%A1%BA%E5%BA%8F%E4%B8%BA%E4%BB%80%E4%B9%88%E9%87%8D%E8%A6%81" class="hash-link" aria-label="5.2 中间件顺序为什么重要的直接链接" title="5.2 中间件顺序为什么重要的直接链接" translate="no">​</a></h3>
<p><strong>先 <code>add_middleware</code> 的在外层</strong>（请求从外到内经过，响应反过来）：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">请求流：  Client → ①TrustedHost → ②RequestContext → ③RateLimit → ④Auth → ⑤ReverseProxy → Downstream</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">响应流：  Downstream → ⑤ → ④ → ③ → ② → ① → Client</span><br></div></code></pre></div></div>
<p><strong>错误顺序示例</strong>：</p>
<ul>
<li class="">❌ <code>Auth</code> 在 <code>RateLimit</code> 内：未鉴权的请求也消耗限流名额</li>
<li class="">❌ <code>ReverseProxy</code> 在 <code>Auth</code> 内：未鉴权就转发到下游，下游要重复鉴权</li>
<li class="">✅ 正确：限流在最外（早期丢弃）、鉴权居中（带 user 上下文）、转发在最内</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-关键路径">5.3 关键路径<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#53-%E5%85%B3%E9%94%AE%E8%B7%AF%E5%BE%84" class="hash-link" aria-label="5.3 关键路径的直接链接" title="5.3 关键路径的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">1. TrustedHostMiddleware</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 检查 Host 头，拒绝恶意构造（如 Host: evil.com）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 防 Host Header 注入</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">2. RequestContextMiddleware</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 生成/透传 X-Request-ID（链路追踪）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 记录访问日志（method, path, status, latency）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 请求耗时埋点</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">3. RateLimitMiddleware</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 按 (client_ip, path_prefix) 做滑动窗口</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 超限返回 429 + Retry-After</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 防止恶意刷接口</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">4. AuthMiddleware</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 解析 Authorization: Bearer xxx</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 校验 JWT 签名 / 过期 / 黑名单</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 把 user 信息挂到 request.state.user</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">5. ReverseProxyMiddleware</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 根据 path 前缀匹配 ROUTES 表</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 用 httpx 转发到下游</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   - 透传 X-Request-ID / X-User-Id / X-Forwarded-For</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-关键中间件实现要点">6. 关键中间件实现要点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#6-%E5%85%B3%E9%94%AE%E4%B8%AD%E9%97%B4%E4%BB%B6%E5%AE%9E%E7%8E%B0%E8%A6%81%E7%82%B9" class="hash-link" aria-label="6. 关键中间件实现要点的直接链接" title="6. 关键中间件实现要点的直接链接" translate="no">​</a></h2>
<p>完整代码见 <code>example/gateway/gateway.py</code>。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-requestcontextmiddleware请求上下文">6.1 RequestContextMiddleware（请求上下文）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#61-requestcontextmiddleware%E8%AF%B7%E6%B1%82%E4%B8%8A%E4%B8%8B%E6%96%87" class="hash-link" aria-label="6.1 RequestContextMiddleware（请求上下文）的直接链接" title="6.1 RequestContextMiddleware（请求上下文）的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">class</span><span class="token plain"> </span><span class="token class-name">RequestContextMiddleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">BaseHTTPMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">async</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">dispatch</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        request_id </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"X-Request-ID"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">or</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">uuid</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">uuid4</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">state</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">request_id </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> request_id</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        start </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">perf_counter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        response </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        elapsed_ms </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">perf_counter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token plain"> start</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1000</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        response</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"X-Request-ID"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> request_id</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        logger</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">info</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"[%s] %s %s -&gt; %s (%.1fms)"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    request_id</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">method</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">url</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">path</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    response</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">status_code</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> elapsed_ms</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> response</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-ratelimitmiddleware滑动窗口限流">6.2 RateLimitMiddleware（滑动窗口限流）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#62-ratelimitmiddleware%E6%BB%91%E5%8A%A8%E7%AA%97%E5%8F%A3%E9%99%90%E6%B5%81" class="hash-link" aria-label="6.2 RateLimitMiddleware（滑动窗口限流）的直接链接" title="6.2 RateLimitMiddleware（滑动窗口限流）的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">class</span><span class="token plain"> </span><span class="token class-name">RateLimitMiddleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">BaseHTTPMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    WINDOW_SEC </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">60</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    MAX_REQS </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">100</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">__init__</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> app</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token builtin">super</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">__init__</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">buckets </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> defaultdict</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">deque</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">async</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">dispatch</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        key </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">client</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">host</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">url</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">path</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">split</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"/"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">[</span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        now </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">time</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        bucket </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">buckets</span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain">key</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">while</span><span class="token plain"> bucket </span><span class="token keyword" style="color:#00009f">and</span><span class="token plain"> bucket</span><span class="token punctuation" style="color:#393A34">[</span><span class="token number" style="color:#36acaa">0</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">&lt;</span><span class="token plain"> now </span><span class="token operator" style="color:#393A34">-</span><span class="token plain"> self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">WINDOW_SEC</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            bucket</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">popleft</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token builtin">len</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">bucket</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">&gt;=</span><span class="token plain"> self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">MAX_REQS</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> JSONResponse</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"detail"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Too Many Requests"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                status_code</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">429</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                headers</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"Retry-After"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">WINDOW_SEC</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        bucket</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">append</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">now</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<blockquote>
<p>⚠️ 这是<strong>单进程内存版</strong>，多 worker / 多机要换 Redis（用 INCR + EXPIRE 实现）。</p>
</blockquote>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-authmiddlewarejwt-校验">6.3 AuthMiddleware（JWT 校验）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#63-authmiddlewarejwt-%E6%A0%A1%E9%AA%8C" class="hash-link" aria-label="6.3 AuthMiddleware（JWT 校验）的直接链接" title="6.3 AuthMiddleware（JWT 校验）的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">class</span><span class="token plain"> </span><span class="token class-name">AuthMiddleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">BaseHTTPMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    PUBLIC_PATHS </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"/health"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/login"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">async</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">dispatch</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">url</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">path </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">PUBLIC_PATHS</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        auth </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"Authorization"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">""</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> auth</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">startswith</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"Bearer "</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> JSONResponse</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"detail"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Missing bearer token"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                status_code</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">401</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">try</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            payload </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">decode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">auth</span><span class="token punctuation" style="color:#393A34">[</span><span class="token number" style="color:#36acaa">7</span><span class="token punctuation" style="color:#393A34">:</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                 algorithms</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                 options</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"require"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">state</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">user </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> payload</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">except</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">InvalidTokenError </span><span class="token keyword" style="color:#00009f">as</span><span class="token plain"> e</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> JSONResponse</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"detail"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:#e3116c">f"Invalid token: </span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">e</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                status_code</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">401</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="64-reverseproxymiddleware路由转发">6.4 ReverseProxyMiddleware（路由转发）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#64-reverseproxymiddleware%E8%B7%AF%E7%94%B1%E8%BD%AC%E5%8F%91" class="hash-link" aria-label="6.4 ReverseProxyMiddleware（路由转发）的直接链接" title="6.4 ReverseProxyMiddleware（路由转发）的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">class</span><span class="token plain"> </span><span class="token class-name">ReverseProxyMiddleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">BaseHTTPMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">__init__</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> app</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> routes</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">[</span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token builtin">super</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">__init__</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">routes </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> routes</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">async</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">dispatch</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">self</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        upstream </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> self</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">_match</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">url</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">path</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> upstream</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> call_next</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">             </span><span class="token comment" style="color:#999988;font-style:italic"># 网关自身路由</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        headers </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        headers</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"X-Real-IP"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">client</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">host</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        headers</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"X-Request-ID"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">state</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">request_id</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token builtin">hasattr</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">state</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"user"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            headers</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"X-User-Id"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">state</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">user</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        body </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">                     </span><span class="token comment" style="color:#999988;font-style:italic"># body 只能读一次</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">async</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">with</span><span class="token plain"> httpx</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">AsyncClient</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">timeout</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">30.0</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">as</span><span class="token plain"> client</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">try</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                upstream_resp </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    method</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">method</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    url</span><span class="token operator" style="color:#393A34">=</span><span class="token string-interpolation string" style="color:#e3116c">f"</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">upstream</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">request</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">.</span><span class="token string-interpolation interpolation">url</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">.</span><span class="token string-interpolation interpolation">path</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    params</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">query_params</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    headers</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> content</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">body</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            </span><span class="token keyword" style="color:#00009f">except</span><span class="token plain"> httpx</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">RequestError </span><span class="token keyword" style="color:#00009f">as</span><span class="token plain"> e</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> JSONResponse</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"detail"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:#e3116c">f"Upstream error: </span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">e</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                    status_code</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">502</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token comment" style="color:#999988;font-style:italic"># 过滤 hop-by-hop headers（防双重压缩）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        excluded </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"content-encoding"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"content-length"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    </span><span class="token string" style="color:#e3116c">"transfer-encoding"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"connection"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        resp_headers </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">k</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> v </span><span class="token keyword" style="color:#00009f">for</span><span class="token plain"> k</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> v </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> upstream_resp</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">items</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                       </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> k</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">lower</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> excluded</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> Response</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">content</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">upstream_resp</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">content</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                        status_code</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">upstream_resp</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">status_code</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                        headers</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">resp_headers</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                        media_type</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">upstream_resp</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"content-type"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="65-中间件装配">6.5 中间件装配<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#65-%E4%B8%AD%E9%97%B4%E4%BB%B6%E8%A3%85%E9%85%8D" class="hash-link" aria-label="6.5 中间件装配的直接链接" title="6.5 中间件装配的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">app </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> FastAPI</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">ROUTES </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token string" style="color:#e3116c">"/api/users"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9001"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token string" style="color:#e3116c">"/api/orders"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:9002"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_middleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">RequestContextMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic"># 最外层：request_id</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_middleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">RateLimitMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">          </span><span class="token comment" style="color:#999988;font-style:italic"># 限流</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_middleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">AuthMiddleware</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">               </span><span class="token comment" style="color:#999988;font-style:italic"># 鉴权</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_middleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">ReverseProxyMiddleware</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># 转发</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                    routes</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">ROUTES</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-生产部署清单">7. 生产部署清单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#7-%E7%94%9F%E4%BA%A7%E9%83%A8%E7%BD%B2%E6%B8%85%E5%8D%95" class="hash-link" aria-label="7. 生产部署清单的直接链接" title="7. 生产部署清单的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-必备">7.1 必备<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#71-%E5%BF%85%E5%A4%87" class="hash-link" aria-label="7.1 必备的直接链接" title="7.1 必备的直接链接" translate="no">​</a></h3>
<ul>
<li class="">✅ TLS 终止：nginx / 云 LB</li>
<li class="">✅ <code>ProxyHeadersMiddleware</code>（在 nginx 后取真实客户端 IP）
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> uvicorn</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">middleware</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">proxy_headers </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> ProxyHeadersMiddleware</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_middleware</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">ProxyHeadersMiddleware</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> trusted_hosts</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"*"</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
</li>
<li class="">✅ 健康检查端点 <code>/health</code>（给 LB / k8s 用）</li>
<li class="">✅ 优雅关闭（uvicorn 自带 SIGTERM 处理）</li>
<li class="">✅ 多 worker（<code>uvicorn --workers 4</code>）—— <strong>注意</strong>：内存版限流 / ConnectionManager 在 worker 间不共享</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-推荐">7.2 推荐<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#72-%E6%8E%A8%E8%8D%90" class="hash-link" aria-label="7.2 推荐的直接链接" title="7.2 推荐的直接链接" translate="no">​</a></h3>
<ul>
<li class="">限流改 Redis（<code>aioredis</code> + 滑动窗口 Lua）</li>
<li class="">熔断（<code>tenacity</code> + <code>pybreaker</code>，下游超时 / 5xx 自动隔离）</li>
<li class="">Prometheus 指标暴露（<code>prometheus-fastapi-instrumentator</code>）</li>
<li class="">链路追踪（<code>opentelemetry-instrumentation-fastapi</code>）</li>
<li class="">限流 / 鉴权策略热加载（不用重启网关）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="73-网关也要高可用">7.3 网关也要高可用<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#73-%E7%BD%91%E5%85%B3%E4%B9%9F%E8%A6%81%E9%AB%98%E5%8F%AF%E7%94%A8" class="hash-link" aria-label="7.3 网关也要高可用的直接链接" title="7.3 网关也要高可用的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">        ┌─ Gateway 1 ─┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">LB ───► │             │ ──► 下游服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        └─ Gateway 2 ─┘</span><br></div></code></pre></div></div>
<ul>
<li class="">多实例 + 健康检查</li>
<li class="">蓝绿 / 灰度发布（按权重切流量）</li>
<li class="">配置中心统一管理（Consul / Nacos）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-网关常见坑">8. 网关常见坑<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#8-%E7%BD%91%E5%85%B3%E5%B8%B8%E8%A7%81%E5%9D%91" class="hash-link" aria-label="8. 网关常见坑的直接链接" title="8. 网关常见坑的直接链接" translate="no">​</a></h2>




























































<table><thead><tr><th>坑</th><th>现象</th><th>修法</th></tr></thead><tbody><tr><td><strong>中间件顺序写反</strong></td><td>鉴权在限流前 → 未鉴权请求消耗限流名额</td><td>按 5.2 顺序调整</td></tr><tr><td><strong>没加 <code>ProxyHeadersMiddleware</code></strong></td><td>网关看到的 IP 都是 <code>127.0.0.1</code></td><td>nginx 后必须加</td></tr><tr><td><strong>body 读两次</strong></td><td><code>await request.body()</code> 调两次，第二次空</td><td>转发前缓存到局部变量</td></tr><tr><td><strong>没过滤 hop-by-hop headers</strong></td><td>content-encoding 双重压缩 → 客户端解压失败</td><td>过滤 <code>content-encoding</code> / <code>transfer-encoding</code> / <code>connection</code></td></tr><tr><td><strong>限流是内存版但多 worker</strong></td><td>单 worker 限流 100，整体可能是 400</td><td>改 Redis 分布式限流</td></tr><tr><td><strong>网关同步调用下游，下游慢拖垮网关</strong></td><td>网关全在等</td><td>加超时 + 熔断 + 异步</td></tr><tr><td><strong>忘记 CORS</strong></td><td>浏览器 OPTIONS 预检失败</td><td><code>CORSMiddleware</code></td></tr><tr><td><strong>网关无认证 / 公开 health 被攻击</strong></td><td><code>/health</code> 等被恶意刷</td><td>限流 + 只监听内网</td></tr><tr><td><strong>路由冲突</strong></td><td>两个服务都用 <code>/api/v1/users</code></td><td>path 前缀必须唯一</td></tr><tr><td><strong>网关自身没限流</strong></td><td>网关被 DDoS 拖垮</td><td>网关也要限流 + 入口 LB 抗 DDoS</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关联笔记">关联笔记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#%E5%85%B3%E8%81%94%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="关联笔记的直接链接" title="关联笔记的直接链接" translate="no">​</a></h2>
<ul>
<li class="">鉴权流程（JWT / OAuth2 / 扫码）：<code>[[鉴权与登录笔记]]</code></li>
<li class="">权限模型（拿到 token 后能做什么）：<code>[[权限模型与Casbin实践笔记]]</code></li>
<li class="">反向代理 / TLS：<code>[[nginx]]</code>（如已收录）</li>
<li class="">容器编排（Ingress）：<code>[[I_Kubernetes基础笔记]]</code></li>
<li class="">服务网格（Sidecar 形态的网关）：<code>[[DevOps基础与文化笔记]]</code></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="demo">Demo<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/API%E7%BD%91%E5%85%B3%E5%8E%9F%E7%90%86%E4%B8%8E%E9%80%89%E5%9E%8B%E7%AC%94%E8%AE%B0#demo" class="hash-link" aria-label="Demo的直接链接" title="Demo的直接链接" translate="no">​</a></h2>
<p>完整可运行代码（FastAPI 网关 + 2 个模拟下游服务 + JWT 鉴权 + Casbin 权限检查 + 扫码登录）：</p>
<ul>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/gateway.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/gateway.py</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/service_users.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/service_users.py</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/service_orders.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/service_orders.py</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/auth_demo.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/auth_demo.py</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/scan_login_demo.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/scan_login_demo.py</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/tree/main/example/gateway/policy" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/policy/</code></a>（Casbin 模型 + 策略）</li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/README.md" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/README.md</code></a></li>
</ul>
<p>标签：#fastapi</p>]]></content>
        <category label="FastAPI" term="FastAPI"/>
        <category label="Nginx" term="Nginx"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[DevOps 基础与文化]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps基础与文化笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps基础与文化笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[由旧稿重新整理版本。DevOps 系列共 3 篇：本文是概念与文化；小企业DevOps方案笔记 是50~500 人企业主流方案；DevOps工具链选型对比笔记 是工具链横向选型参考。旧稿目录已清理，当前以本文为准。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>由旧稿重新整理版本。DevOps 系列共 3 篇：本文是<strong>概念与文化</strong>；<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0">小企业DevOps方案笔记</a> 是<strong>50~500 人企业主流方案</strong>；<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0">DevOps工具链选型对比笔记</a> 是<strong>工具链横向选型参考</strong>。旧稿目录已清理，当前以本文为准。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-devops-是什么">1. DevOps 是什么<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#1-devops-%E6%98%AF%E4%BB%80%E4%B9%88" class="hash-link" aria-label="1. DevOps 是什么的直接链接" title="1. DevOps 是什么的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-定义">1.1 定义<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#11-%E5%AE%9A%E4%B9%89" class="hash-link" aria-label="1.1 定义的直接链接" title="1.1 定义的直接链接" translate="no">​</a></h3>
<p><strong>DevOps</strong> 是 Development（开发）+ Operations（运维）的合并缩写，是一套<strong>文化、实践与工具</strong>的组合，目标是<strong>缩短系统变更从提交到上线的时间，同时保证质量与稳定性</strong>。</p>
<p>核心思想：</p>
<ul>
<li class="">打破开发与运维之间的「墙」</li>
<li class="">把交付过程<strong>自动化、可重复</strong></li>
<li class="">用<strong>反馈回路</strong>持续改进</li>
<li class="">把<strong>可靠性</strong>当成产品的一部分（而非事后靠运维救火）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-不是什么">1.2 不是什么<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#12-%E4%B8%8D%E6%98%AF%E4%BB%80%E4%B9%88" class="hash-link" aria-label="1.2 不是什么的直接链接" title="1.2 不是什么的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ 不是某种职位（「DevOps 工程师」）— DevOps 是文化与实践，单设一个职位意味着 DevOps 失败</li>
<li class="">❌ 不是某个工具（Jenkins / Docker / K8s 都只是支撑）</li>
<li class="">❌ 不是只搞 CI/CD（CI/CD 只是其中一环）</li>
<li class="">❌ 不是运维工程师 + 几个脚本</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-一句话总结">1.3 一句话总结<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#13-%E4%B8%80%E5%8F%A5%E8%AF%9D%E6%80%BB%E7%BB%93" class="hash-link" aria-label="1.3 一句话总结的直接链接" title="1.3 一句话总结的直接链接" translate="no">​</a></h3>
<blockquote>
<p>DevOps = <strong>让交付从「靠人堆」变成「靠系统自动化」，把责任从运维单独背变成开发从始至终一起承担</strong>。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-devops-的核心价值">2. DevOps 的核心价值<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#2-devops-%E7%9A%84%E6%A0%B8%E5%BF%83%E4%BB%B7%E5%80%BC" class="hash-link" aria-label="2. DevOps 的核心价值的直接链接" title="2. DevOps 的核心价值的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="21-三大指标westrum-指标--dora">2.1 三大指标（Westrum 指标 / DORA）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#21-%E4%B8%89%E5%A4%A7%E6%8C%87%E6%A0%87westrum-%E6%8C%87%E6%A0%87--dora" class="hash-link" aria-label="2.1 三大指标（Westrum 指标 / DORA）的直接链接" title="2.1 三大指标（Westrum 指标 / DORA）的直接链接" translate="no">​</a></h3>
<p>Google DORA 团队对软件交付效能的多年研究总结出 4 个指标：</p>



































<table><thead><tr><th>指标</th><th>Elite</th><th>Low</th><th>含义</th></tr></thead><tbody><tr><td><strong>部署频率（Deployment Frequency）</strong></td><td>按需（一天多次）</td><td>几个月一次</td><td>发布节奏</td></tr><tr><td><strong>变更前置时间（Lead Time for Changes）</strong></td><td>&lt; 1h</td><td>&gt; 1 month</td><td>从 commit 到 production</td></tr><tr><td><strong>变更失败率（Change Failure Rate）</strong></td><td>0~15%</td><td>46~60%</td><td>上线后回滚或修复的比例</td></tr><tr><td><strong>故障恢复时间（MTTR）</strong></td><td>&lt; 1h</td><td>&gt; 1 month</td><td>出问题到恢复</td></tr></tbody></table>
<blockquote>
<p>Elite vs Low 的企业，运营表现有 30~50 倍差距（事故数、可用性、业务连续性）。</p>
</blockquote>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="22-商业价值">2.2 商业价值<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#22-%E5%95%86%E4%B8%9A%E4%BB%B7%E5%80%BC" class="hash-link" aria-label="2.2 商业价值的直接链接" title="2.2 商业价值的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>更快交付</strong>：小步快跑，缩短 idea-to-prod 周期</li>
<li class=""><strong>更高稳定性</strong>：自动化测试 + 灰度发布 + 快速回滚</li>
<li class=""><strong>更低成本</strong>：减少救火 SLA、减少返工</li>
<li class=""><strong>更高研发幸福感</strong>：开发者不再怕上线、值班更有方向</li>
<li class=""><strong>组织敏捷</strong>：应对市场变化更快</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-calms-框架">3. CALMS 框架<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#3-calms-%E6%A1%86%E6%9E%B6" class="hash-link" aria-label="3. CALMS 框架的直接链接" title="3. CALMS 框架的直接链接" translate="no">​</a></h2>
<p>CALMS 是 Damon Edwards 提出的 DevOps 文化框架：</p>



































<table><thead><tr><th>字母</th><th>含义</th><th>体现</th></tr></thead><tbody><tr><td><strong>C</strong>ulture</td><td>文化</td><td>跨职能合作、无指责复盘、共享 oncall</td></tr><tr><td><strong>A</strong>utomation</td><td>自动化</td><td>CI/CD、IaC、测试自动化、监控告警自动化</td></tr><tr><td><strong>L</strong>ean</td><td>精益</td><td>减少浪费（小批量、限制在制品 WIP）</td></tr><tr><td><strong>M</strong>easurement</td><td>度量</td><td>DORA 指标、SLI/SLO、用户业务指标</td></tr><tr><td><strong>S</strong>haring</td><td>共享</td><td>共享库、Wiki、复盘文档、内部技术会议</td></tr></tbody></table>
<blockquote>
<p>文化先行（C），技术与工具是支撑（ALMS）。<strong>只买工具不改文化 → 工具用不起来</strong>。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-devops-成熟度模型">4. DevOps 成熟度模型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#4-devops-%E6%88%90%E7%86%9F%E5%BA%A6%E6%A8%A1%E5%9E%8B" class="hash-link" aria-label="4. DevOps 成熟度模型的直接链接" title="4. DevOps 成熟度模型的直接链接" translate="no">​</a></h2>
<p>按阶段划分（0~5）：</p>








































<table><thead><tr><th>级别</th><th>名称</th><th>特征</th></tr></thead><tbody><tr><td><strong>L0</strong></td><td>手动时代</td><td>手动部署、手动测试、FTP 推代码</td></tr><tr><td><strong>L1</strong></td><td>脚本化</td><td>Bash 脚本、cron、基础监控</td></tr><tr><td><strong>L2</strong></td><td>CI/CD</td><td>Jenkins/GitHub Actions 自动化构建+测试</td></tr><tr><td><strong>L3</strong></td><td>IaC + 可观测</td><td>Terraform/Ansible；Prometheus + Grafana；ELK</td></tr><tr><td><strong>L4</strong></td><td>GitOps + 服务网格 + SLO</td><td>ArgoCD/Flux；Istio；SLO 管理；灰度发布</td></tr><tr><td><strong>L5</strong></td><td>自服务 IDP + AIOps</td><td>Backstage 内部开发者平台；自动扩缩容；AIOps 异常检测</td></tr></tbody></table>
<blockquote>
<p><strong>小企业（50~500 技术人员）目标</strong>：<strong>稳定 L3，争取 L4</strong>。L5 是巨型企业的游戏。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-devops-vs-sre-vs-platform-engineering">5. DevOps vs SRE vs Platform Engineering<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#5-devops-vs-sre-vs-platform-engineering" class="hash-link" aria-label="5. DevOps vs SRE vs Platform Engineering的直接链接" title="5. DevOps vs SRE vs Platform Engineering的直接链接" translate="no">​</a></h2>
<p>近年来兴起的几个相邻概念容易混淆：</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-devops">5.1 DevOps<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#51-devops" class="hash-link" aria-label="5.1 DevOps的直接链接" title="5.1 DevOps的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>范围</strong>：文化 + 工具 + 实践</li>
<li class=""><strong>关注点</strong>：整个交付链路</li>
<li class=""><strong>组织意义</strong>：跨职能合作</li>
<li class=""><strong>负责人</strong>：人人（不是某个团队）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-sresite-reliability-engineering源自-google">5.2 SRE（Site Reliability Engineering，源自 Google）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#52-sresite-reliability-engineering%E6%BA%90%E8%87%AA-google" class="hash-link" aria-label="5.2 SRE（Site Reliability Engineering，源自 Google）的直接链接" title="5.2 SRE（Site Reliability Engineering，源自 Google）的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>范围</strong>：生产环境的<strong>可靠性</strong>工程</li>
<li class=""><strong>关注点</strong>：SLO/SLA、错误预算（Error Budget）、oncall、事后复盘（Postmortem）</li>
<li class=""><strong>角色</strong>：SRE Engineer（实际岗位）</li>
<li class=""><strong>经典指标</strong>：可用性 MTTR MTBF</li>
<li class=""><strong>典型实践</strong>：
<ul>
<li class="">SLO 定义（99.9% 可用 = 每月允许 43 分钟宕机）</li>
<li class="">Error Budget 消耗 100% 后，冻结发布</li>
<li class="">Toil（手动工作）控制</li>
</ul>
</li>
<li class=""><strong>与 DevOps 的关系</strong>：SRE 是 DevOps 在「运营可靠性」方向的<strong>具体落地</strong></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-platform-engineering平台工程2022-兴起">5.3 Platform Engineering（平台工程，2022+ 兴起）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#53-platform-engineering%E5%B9%B3%E5%8F%B0%E5%B7%A5%E7%A8%8B2022-%E5%85%B4%E8%B5%B7" class="hash-link" aria-label="5.3 Platform Engineering（平台工程，2022+ 兴起）的直接链接" title="5.3 Platform Engineering（平台工程，2022+ 兴起）的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>范围</strong>：搭建<strong>内部开发者平台</strong>（IDP）</li>
<li class=""><strong>关注点</strong>：让开发者<strong>自助</strong>完成常见任务（新服务创建、CI 模板、部署、监控接入）</li>
<li class=""><strong>代表工具</strong>：<strong>Backstage</strong>（Spotify 开源 IDP）</li>
<li class=""><strong>与 DevOps 的关系</strong>：当 DevOps 文化成熟后，组织会自然演化出"平台团队"专门搭建 IDP</li>
<li class=""><strong>与 SRE 关系</strong>：平台工程给开发者<strong>自助工具</strong>，SRE 确保<strong>生产可靠性</strong></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="54-三者关系图">5.4 三者关系图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#54-%E4%B8%89%E8%80%85%E5%85%B3%E7%B3%BB%E5%9B%BE" class="hash-link" aria-label="5.4 三者关系图的直接链接" title="5.4 三者关系图的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">                ┌──────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │      DevOps（文化层）      │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     跨职能协作 / 反馈       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └──────────┬───────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">              ┌────────────┴────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">              ▼                         ▼</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ┌──────────────────┐        ┌──────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    │ SRE（可靠性层）    │        │ Platform Eng（平台层）│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    │ SLO / oncall /   │        │ Backstage / IDP /    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    │ postmortem       │        │ 自服务化              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    └──────────────────┘        └──────────────────────┘</span><br></div></code></pre></div></div>
<blockquote>
<p><strong>实际分工</strong>：DevOps 是思想，SRE 把「可靠性」做到极致，Platform Eng 把「自助化」做到极致。一个组织往往三者都有。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-devops-与周边概念的关系">6. DevOps 与周边概念的关系<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#6-devops-%E4%B8%8E%E5%91%A8%E8%BE%B9%E6%A6%82%E5%BF%B5%E7%9A%84%E5%85%B3%E7%B3%BB" class="hash-link" aria-label="6. DevOps 与周边概念的关系的直接链接" title="6. DevOps 与周边概念的关系的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-agile敏捷">6.1 Agile（敏捷）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#61-agile%E6%95%8F%E6%8D%B7" class="hash-link" aria-label="6.1 Agile（敏捷）的直接链接" title="6.1 Agile（敏捷）的直接链接" translate="no">​</a></h3>
<ul>
<li class="">关注<strong>需求与产品迭代</strong>（Scrum / Kanban）</li>
<li class="">DevOps 关注<strong>开发到上线</strong>的链路</li>
<li class="">二者<strong>互补</strong>：Agile 解决「做正确的事」，DevOps 解决「正确地做事」</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-lean精益">6.2 Lean（精益）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#62-lean%E7%B2%BE%E7%9B%8A" class="hash-link" aria-label="6.2 Lean（精益）的直接链接" title="6.2 Lean（精益）的直接链接" translate="no">​</a></h3>
<ul>
<li class="">起源于丰田生产方式</li>
<li class="">DevOps 的"L"（Lean）：减少浪费（WIP）、缩短反馈</li>
<li class="">核心观点：<strong>构建质量（Build Quality In）</strong>，而非事后检测</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-持续集成ci">6.3 持续集成（CI）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#63-%E6%8C%81%E7%BB%AD%E9%9B%86%E6%88%90ci" class="hash-link" aria-label="6.3 持续集成（CI）的直接链接" title="6.3 持续集成（CI）的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>频繁合并代码</strong>到主干，每次合并自动跑构建+测试</li>
<li class="">目标：早发现集成问题</li>
<li class="">是 DevOps 的"A"（Automation）层的一环</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="64-持续交付--持续部署cd">6.4 持续交付 / 持续部署（CD）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#64-%E6%8C%81%E7%BB%AD%E4%BA%A4%E4%BB%98--%E6%8C%81%E7%BB%AD%E9%83%A8%E7%BD%B2cd" class="hash-link" aria-label="6.4 持续交付 / 持续部署（CD）的直接链接" title="6.4 持续交付 / 持续部署（CD）的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>Continuous Delivery</strong>：代码任何时候都可发布（人工决定何时发布）</li>
<li class=""><strong>Continuous Deployment</strong>：自动化通过所有测试后<strong>自动发布</strong>到生产</li>
<li class="">与 CI 是同源概念</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="65-gitops详见-ii_jenkins_cicd实战笔记--小企业devops方案笔记">6.5 GitOps（详见 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/jenkins/02-jenkins-cicd-practice">II_Jenkins_CICD实战笔记</a> / <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0">小企业DevOps方案笔记</a>）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#65-gitops%E8%AF%A6%E8%A7%81-ii_jenkins_cicd%E5%AE%9E%E6%88%98%E7%AC%94%E8%AE%B0--%E5%B0%8F%E4%BC%81%E4%B8%9Adevops%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="65-gitops详见-ii_jenkins_cicd实战笔记--小企业devops方案笔记的直接链接" title="65-gitops详见-ii_jenkins_cicd实战笔记--小企业devops方案笔记的直接链接" translate="no">​</a></h3>
<ul>
<li class="">以 Git 为单一真相源</li>
<li class="">通过 PR/MR 改动生产环境</li>
<li class="">ArgoCD/Flux 是事实标准工具</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-小企业50500-人做-devops-的现实路径">7. 小企业（50~500 人）做 DevOps 的现实路径<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#7-%E5%B0%8F%E4%BC%81%E4%B8%9A50500-%E4%BA%BA%E5%81%9A-devops-%E7%9A%84%E7%8E%B0%E5%AE%9E%E8%B7%AF%E5%BE%84" class="hash-link" aria-label="7. 小企业（50~500 人）做 DevOps 的现实路径的直接链接" title="7. 小企业（50~500 人）做 DevOps 的现实路径的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-当前痛点">7.1 当前痛点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#71-%E5%BD%93%E5%89%8D%E7%97%9B%E7%82%B9" class="hash-link" aria-label="7.1 当前痛点的直接链接" title="7.1 当前痛点的直接链接" translate="no">​</a></h3>
<ul>
<li class="">产品迭代快，部署频率赶不上</li>
<li class="">服务一多，环境/版本混乱</li>
<li class="">故障定位慢，SLA 压力大</li>
<li class="">团队各自为政，没有标准化</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-落地顺序按-roi-由高到低">7.2 落地顺序（按 ROI 由高到低）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#72-%E8%90%BD%E5%9C%B0%E9%A1%BA%E5%BA%8F%E6%8C%89-roi-%E7%94%B1%E9%AB%98%E5%88%B0%E4%BD%8E" class="hash-link" aria-label="7.2 落地顺序（按 ROI 由高到低）的直接链接" title="7.2 落地顺序（按 ROI 由高到低）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">阶段 1（基础）：</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - Git 工作流规范化（trunk-based 或规范化的 GitFlow）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - CI 流水线（PR 触发自动测试 + 自动化单测）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 基础监控（接入 APM、链路追踪）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">阶段 2（演进）：</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 镜像化所有服务 + K8s 容器化</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - CD 流水线（自动推镜像、自动部署）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - IaC（Terraform 管理云资源）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">阶段 3（治理）：</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - GitOps（ArgoCD + App-of-Apps）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - SLO 管理 + Error Budget 流程</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 安全门禁（Trivy、OPA、镜像签名）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">阶段 4（平台化）：</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - Backstage IDP</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 内部共享库、模板化新服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - AIOps、混沌工程、灰度发布</span><br></div></code></pre></div></div>
<blockquote>
<p><strong>不要一上来就上服务网格 + IDP</strong>，从最痛点（部署慢 / 故障多）切入。</p>
</blockquote>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="73-关键组织变化">7.3 关键组织变化<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#73-%E5%85%B3%E9%94%AE%E7%BB%84%E7%BB%87%E5%8F%98%E5%8C%96" class="hash-link" aria-label="7.3 关键组织变化的直接链接" title="7.3 关键组织变化的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>运维团队转型</strong>：从「纯救火」变「平台建设 + SRE 兼 SRE 思路」</li>
<li class=""><strong>开发承担 oncall</strong>：共同对生产负责</li>
<li class=""><strong>建立 blameless postmortem 文化</strong>：复盘不追责，找系统问题</li>
<li class=""><strong>共享指标</strong>：DORA 4 指标透明、考核按团队而非个人</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-组织团队模型">8. 组织/团队模型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#8-%E7%BB%84%E7%BB%87%E5%9B%A2%E9%98%9F%E6%A8%A1%E5%9E%8B" class="hash-link" aria-label="8. 组织/团队模型的直接链接" title="8. 组织/团队模型的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-反向康威定律">8.1 反向康威定律<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#81-%E5%8F%8D%E5%90%91%E5%BA%B7%E5%A8%81%E5%AE%9A%E5%BE%8B" class="hash-link" aria-label="8.1 反向康威定律的直接链接" title="8.1 反向康威定律的直接链接" translate="no">​</a></h3>
<p><strong>康威定律</strong>："系统结构反映组织沟通结构"。</p>
<p>DevOps 时代常<strong>反向</strong>：先决定系统/团队结构，反过来调整组织：</p>
<ul>
<li class=""><strong>微服务 = 小团队 + 全栈</strong>：每个服务由一个 5~9 人小队全权负责（含 oncall）</li>
<li class=""><strong>平台团队</strong>：构建 CI/CD 模板、可观测性、镜像仓库</li>
<li class=""><strong>产品团队</strong>：聚焦业务，平台能力由平台团队提供</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-经典模型">8.2 经典模型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#82-%E7%BB%8F%E5%85%B8%E6%A8%A1%E5%9E%8B" class="hash-link" aria-label="8.2 经典模型的直接链接" title="8.2 经典模型的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>模型</th><th>来源</th><th>适用</th></tr></thead><tbody><tr><td><strong>Spotify 模型</strong></td><td>Spotify</td><td>大型、矩阵化、产品线多</td></tr><tr><td><strong>Team Topologies</strong></td><td>Skelton &amp; Pais</td><td>演化出 4 种团队类型：业务流、平台、赋能、复杂子系统</td></tr><tr><td><strong>SRE 拓扑</strong></td><td>Google</td><td>强 oncall 流程</td></tr><tr><td><strong>Platform Engineering</strong></td><td>2022+ 兴起</td><td>自服务化优先</td></tr></tbody></table>
<blockquote>
<p>Team Topologies 4 类：</p>
<ul>
<li class=""><strong>Stream-aligned team</strong>：业务流团队（按业务价值流）</li>
<li class=""><strong>Platform team</strong>：提供 IDP</li>
<li class=""><strong>Enabling team</strong>：传帮带</li>
<li class=""><strong>Complicated-subsystem team</strong>：复杂专门系统（如 ML 平台）</li>
</ul>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-一句话总结">9. 一句话总结<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0#9-%E4%B8%80%E5%8F%A5%E8%AF%9D%E6%80%BB%E7%BB%93" class="hash-link" aria-label="9. 一句话总结的直接链接" title="9. 一句话总结的直接链接" translate="no">​</a></h2>
<ul>
<li class="">DevOps = 文化（CALMS）+ 自动化 + 度量 + 共享</li>
<li class="">目标：DORA 4 指标达到 Elite（部署频率高 / 前置时间短 / 变更失败率低 / MTTR 短）</li>
<li class="">区分 DevOps / SRE / Platform Engineering：文化 / 可靠性 / 自服务</li>
<li class="">小企业落地分阶段，从痛点切入（CI + 监控），再演进到 L3~L4（IaC + GitOps）</li>
</ul>
<p>标签：#docker #kubernetes #jenkins #git</p>]]></content>
        <category label="Docker" term="Docker"/>
        <category label="Kubernetes" term="Kubernetes"/>
        <category label="Jenkins" term="Jenkins"/>
        <category label="Git" term="Git"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[DevOps 工具链对比笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps工具链选型对比笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps工具链选型对比笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[来自 小企业DevOps方案笔记 的延伸：按领域横向对比 8 个细分赛道的开源与商业选型。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>来自 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0">小企业DevOps方案笔记</a> 的延伸：按领域横向对比 8 个细分赛道的开源与商业选型。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-代码托管source-code-management">1. 代码托管（Source Code Management）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#1-%E4%BB%A3%E7%A0%81%E6%89%98%E7%AE%A1source-code-management" class="hash-link" aria-label="1. 代码托管（Source Code Management）的直接链接" title="1. 代码托管（Source Code Management）的直接链接" translate="no">​</a></h2>



























































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th><th>适用</th></tr></thead><tbody><tr><td><strong>GitHub</strong></td><td>商业/SaaS + 自托管 EE</td><td>最广泛的代码托管 + PR + Actions</td><td>几乎全员</td></tr><tr><td><strong>GitLab CE</strong></td><td>开源</td><td>自托管"一体化平台"</td><td>数据本地化、自托管</td></tr><tr><td><strong>GitLab EE</strong></td><td>商业</td><td>CE + 安全/合规等高级能力</td><td>大企业、有预算</td></tr><tr><td><strong>Gitea</strong></td><td>开源/轻量</td><td>用 Go 写的迷你 GitHub</td><td>资源受限、要轻量</td></tr><tr><td><strong>Forgejo</strong></td><td>开源</td><td>Gitea 的社区分叉</td><td>同上、避免 Gitea 商业化</td></tr><tr><td><strong>Bitbucket</strong></td><td>商业/SaaS</td><td>Atlassian 生态</td><td>已用 Jira 的团队</td></tr><tr><td><strong>Codeberg</strong></td><td>开源/SaaS</td><td>公益型 Forgejo</td><td>个人/小团队</td></tr><tr><td><strong>Sourcehut</strong></td><td>开源/SaaS</td><td>无 JS、邮件驱动</td><td>极简主义者</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">主流 SaaS 团队 → <strong>GitHub</strong></li>
<li class="">自托管 / 数据本地化 → <strong>GitLab CE</strong> 或 <strong>Gitea</strong></li>
<li class="">阿里云/腾讯云生态 → <strong>CodeUp / TAPD</strong></li>
<li class="">已用 Jira → <strong>Bitbucket</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-ci持续集成">2. CI（持续集成）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#2-ci%E6%8C%81%E7%BB%AD%E9%9B%86%E6%88%90" class="hash-link" aria-label="2. CI（持续集成）的直接链接" title="2. CI（持续集成）的直接链接" translate="no">​</a></h2>







































































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th><th>适用</th></tr></thead><tbody><tr><td><strong>GitHub Actions</strong></td><td>SaaS + 自托管 runner</td><td>内置</td><td>GitHub 生态</td></tr><tr><td><strong>GitLab CI</strong></td><td>内置</td><td>自托管 / SaaS</td><td>GitLab 生态</td></tr><tr><td><strong>Jenkins</strong></td><td>开源/Java</td><td>最老牌、插件最多</td><td>高度可定制</td></tr><tr><td><strong>Drone</strong></td><td>开源/Go</td><td>容器化、易上手</td><td>中小项目</td></tr><tr><td><strong>Woodpecker</strong></td><td>开源</td><td>Drone 的社区分叉</td><td>同上</td></tr><tr><td><strong>Tekton</strong></td><td>开源/Cloud Native</td><td>K8s 原生、CIDR</td><td>K8s 重度用户</td></tr><tr><td><strong>CircleCI</strong></td><td>SaaS</td><td>老牌、性能好</td><td>大 monorepo</td></tr><tr><td><strong>Buildkite</strong></td><td>SaaS + 自托管 agent</td><td>灵活、CI as Code</td><td>私有化</td></tr><tr><td><strong>Argo Workflows</strong></td><td>开源</td><td>K8s 原生工作流</td><td>不只是 CI</td></tr><tr><td><strong>TeamCity</strong></td><td>商业</td><td>JetBrains 出品</td><td>Kotlin/Java 团队</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">已用 GitHub → <strong>GitHub Actions</strong>（小项目）</li>
<li class="">已用 GitLab → <strong>GitLab CI</strong></li>
<li class="">K8s 重度 + 复杂流水线 → <strong>Tekton</strong> / <strong>Argo Workflows</strong></li>
<li class="">复杂自定义 + 大量 plugin → <strong>Jenkins</strong></li>
<li class="">中小团队 + 简单 + 容器原生 → <strong>Drone</strong> / <strong>Woodpecker</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-cd持续部署">3. CD（持续部署）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#3-cd%E6%8C%81%E7%BB%AD%E9%83%A8%E7%BD%B2" class="hash-link" aria-label="3. CD（持续部署）的直接链接" title="3. CD（持续部署）的直接链接" translate="no">​</a></h2>





















































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th><th>适用</th></tr></thead><tbody><tr><td><strong>ArgoCD</strong></td><td>开源</td><td>K8s GitOps 事实标准</td><td><strong>K8s 首选</strong></td></tr><tr><td><strong>Flux CD</strong></td><td>开源</td><td>GitOps Toolkit，比 ArgoCD 轻</td><td>同上</td></tr><tr><td><strong>Spinnaker</strong></td><td>开源/Netflix 出品</td><td>多云部署、复杂发布策略</td><td>大型多云</td></tr><tr><td><strong>Harness</strong></td><td>商业</td><td>一站式 CD</td><td>中大型</td></tr><tr><td><strong>Codefresh</strong></td><td>商业</td><td>K8s CD</td><td>K8s 中型</td></tr><tr><td><strong>Octopus Deploy</strong></td><td>商业</td><td>传统应用部署</td><td>.NET / 老系统</td></tr><tr><td><strong>Flagger</strong></td><td>开源</td><td>ArgoCD 配套、灰度发布</td><td>K8s + Argo</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">用 K8s → <strong>ArgoCD</strong>（最稳）</li>
<li class="">K8s + 需要轻量 → <strong>Flux</strong></li>
<li class="">多云 + 复杂发布 → <strong>Spinnaker</strong></li>
<li class="">商业、省心 → <strong>Harness</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-iac基础设施即代码">4. IaC（基础设施即代码）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#4-iac%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD%E5%8D%B3%E4%BB%A3%E7%A0%81" class="hash-link" aria-label="4. IaC（基础设施即代码）的直接链接" title="4. IaC（基础设施即代码）的直接链接" translate="no">​</a></h2>

































































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th><th>适用</th></tr></thead><tbody><tr><td><strong>Terraform</strong></td><td>商业（MPL）</td><td>行业标准</td><td>多云</td></tr><tr><td><strong>OpenTofu</strong></td><td>开源</td><td>Terraform 1.5+ 的开源分叉</td><td>避免 HashiCorp 许可变更</td></tr><tr><td><strong>Pulumi</strong></td><td>开源/商业</td><td>用编程语言（TS/Go/Python）写 IaC</td><td>程序员友好</td></tr><tr><td><strong>Ansible</strong></td><td>开源</td><td>配置管理 / 简单编排</td><td>配置管理、轻 IaC</td></tr><tr><td><strong>CloudFormation</strong></td><td>商业（AWS 专）</td><td>AWS 原生</td><td>AWS 单一云</td></tr><tr><td><strong>ARM Template</strong></td><td>商业（Azure 专）</td><td>Azure 原生</td><td>Azure 单一云</td></tr><tr><td><strong>CDK</strong></td><td>商业</td><td>CloudFormation 的编程版本</td><td>程序员</td></tr><tr><td><strong>Crossplane</strong></td><td>开源</td><td>K8s 原生管理云资源</td><td>K8s 生态</td></tr><tr><td><strong>Helm</strong></td><td>开源</td><td>K8s 应用打包</td><td>K8s 部署</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">多云 → <strong>Terraform</strong> / <strong>OpenTofu</strong></li>
<li class="">单一云（AWS） → <strong>CloudFormation</strong> / <strong>CDK</strong></li>
<li class="">程序员团队 → <strong>Pulumi</strong></li>
<li class="">配置管理、运维自动化 → <strong>Ansible</strong></li>
<li class="">K8s 应用 → <strong>Helm</strong> + <strong>Kustomize</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-容器镜像与制品库artifacts">5. 容器镜像与制品库（Artifacts）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#5-%E5%AE%B9%E5%99%A8%E9%95%9C%E5%83%8F%E4%B8%8E%E5%88%B6%E5%93%81%E5%BA%93artifacts" class="hash-link" aria-label="5. 容器镜像与制品库（Artifacts）的直接链接" title="5. 容器镜像与制品库（Artifacts）的直接链接" translate="no">​</a></h2>



























































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th><th>适用</th></tr></thead><tbody><tr><td><strong>Harbor</strong></td><td>开源/CNCF</td><td>容器镜像 + 漏洞扫描 + 复制</td><td><strong>首选</strong>（见 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/harbor">Harbor笔记</a>）</td></tr><tr><td><strong>AWS ECR</strong></td><td>商业</td><td>AWS 容器镜像</td><td>AWS 单云</td></tr><tr><td><strong>Azure ACR</strong></td><td>商业</td><td>Azure 容器镜像</td><td>Azure 单云</td></tr><tr><td><strong>GCP Artifact Registry</strong></td><td>商业</td><td>GCP 镜像</td><td>GCP 单云</td></tr><tr><td><strong>Docker Hub</strong></td><td>SaaS</td><td>公有</td><td>公开镜像</td></tr><tr><td><strong>Nexus Repository</strong></td><td>商业/OSS</td><td>容器 + Maven + npm + PyPI 全能</td><td>多语言</td></tr><tr><td><strong>Artifactory</strong></td><td>商业</td><td>最全</td><td>商业重型</td></tr><tr><td><strong>GitHub Packages</strong></td><td>SaaS</td><td>与 GitHub 集成</td><td>GitHub 用户</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">多语言、大企业 → <strong>Nexus Repository</strong> / <strong>Artifactory</strong></li>
<li class="">纯容器镜像 → <strong>Harbor</strong></li>
<li class="">单一云 → 用云厂商的（ECR/ACR）</li>
<li class="">GitHub 项目 → <strong>GitHub Container Registry</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-可观测性observability">6. 可观测性（Observability）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#6-%E5%8F%AF%E8%A7%82%E6%B5%8B%E6%80%A7observability" class="hash-link" aria-label="6. 可观测性（Observability）的直接链接" title="6. 可观测性（Observability）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-metrics">6.1 Metrics<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#61-metrics" class="hash-link" aria-label="6.1 Metrics的直接链接" title="6.1 Metrics的直接链接" translate="no">​</a></h3>

































































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Prometheus</strong></td><td>开源</td><td>K8s 监控事实标准</td></tr><tr><td><strong>VictoriaMetrics</strong></td><td>开源</td><td>高性能 Prometheus 替代</td></tr><tr><td><strong>Thanos</strong></td><td>开源</td><td>Prometheus 长期存储</td></tr><tr><td><strong>Cortex</strong></td><td>开源</td><td>Prometheus 集群方案</td></tr><tr><td><strong>InfluxDB</strong></td><td>开源</td><td>时序数据库</td></tr><tr><td><strong>Datadog</strong></td><td>SaaS</td><td>SaaS 一体化</td></tr><tr><td><strong>New Relic</strong></td><td>SaaS</td><td>老牌 APM</td></tr><tr><td><strong>Dynatrace</strong></td><td>SaaS</td><td>企业级自动化</td></tr><tr><td><strong>Splunk Observability</strong></td><td>SaaS</td><td>来自 Splunk</td></tr><tr><td><strong>CloudWatch</strong></td><td>商业</td><td>AWS 原生</td></tr><tr><td><strong>Azure Monitor</strong></td><td>商业</td><td>Azure 原生</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-logs">6.2 Logs<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#62-logs" class="hash-link" aria-label="6.2 Logs的直接链接" title="6.2 Logs的直接链接" translate="no">​</a></h3>








































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Loki</strong></td><td>开源</td><td>Grafana 全家桶</td></tr><tr><td><strong>ELK Stack</strong></td><td>开源</td><td>经典（Elasticsearch + Logstash + Kibana）</td></tr><tr><td><strong>OpenSearch</strong></td><td>开源</td><td>ES 分叉（合规）</td></tr><tr><td><strong>Grafana Enterprise Logs</strong></td><td>商业</td><td>Grafana 商业版</td></tr><tr><td><strong>Splunk</strong></td><td>商业</td><td>商业重型</td></tr><tr><td><strong>Datadog Logs</strong></td><td>SaaS</td><td>商业</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-traces">6.3 Traces<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#63-traces" class="hash-link" aria-label="6.3 Traces的直接链接" title="6.3 Traces的直接链接" translate="no">​</a></h3>








































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Jaeger</strong></td><td>开源</td><td>CNCF 毕业</td></tr><tr><td><strong>Tempo</strong></td><td>开源</td><td>Grafana 出品</td></tr><tr><td><strong>Zipkin</strong></td><td>开源</td><td>老牌（Twitter）</td></tr><tr><td><strong>OpenTelemetry</strong></td><td>开源/CNCF</td><td>标准化采集 SDK</td></tr><tr><td><strong>Datadog APM</strong></td><td>SaaS</td><td>商业</td></tr><tr><td><strong>New Relic APM</strong></td><td>SaaS</td><td>商业</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="64-整合方案">6.4 整合方案<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#64-%E6%95%B4%E5%90%88%E6%96%B9%E6%A1%88" class="hash-link" aria-label="6.4 整合方案的直接链接" title="6.4 整合方案的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>Grafana Stack（LGTM + Prometheus）</strong>：最常见的自建</li>
<li class=""><strong>Datadog</strong>：一体化 SaaS</li>
<li class=""><strong>New Relic</strong>：一体化 SaaS</li>
<li class=""><strong>Dynatrace</strong>：企业级</li>
</ul>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">完全自建、Grafana + Loki + Tempo + Prometheus</li>
<li class="">省心、大预算 → Datadog</li>
<li class="">多云混合 → Dynatrace</li>
<li class="">Java 重 → New Relic</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-告警alerting">7. 告警（Alerting）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#7-%E5%91%8A%E8%AD%A6alerting" class="hash-link" aria-label="7. 告警（Alerting）的直接链接" title="7. 告警（Alerting）的直接链接" translate="no">​</a></h2>


















































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Alertmanager</strong></td><td>开源</td><td>Prometheus 标配</td></tr><tr><td><strong>Grafana Alerting</strong></td><td>开源</td><td>Grafana 内置</td></tr><tr><td><strong>Grafana OnCall</strong></td><td>开源/商业</td><td>值班调度</td></tr><tr><td><strong>PagerDuty</strong></td><td>SaaS</td><td>值班调度之王</td></tr><tr><td><strong>OpsGenie</strong></td><td>SaaS</td><td>现被 Atlassian 收，集成 Jira</td></tr><tr><td><strong>钉钉 / 飞书 / 企微 机器人</strong></td><td>SaaS</td><td>国内常用 webhook</td></tr><tr><td><strong>Telegram / Slack</strong></td><td>SaaS</td><td>国际常用</td></tr><tr><td><strong>Pager</strong></td><td>开源</td><td>老牌，PagerDuty 替代品</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-安全security-toolchain">8. 安全（Security Toolchain）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#8-%E5%AE%89%E5%85%A8security-toolchain" class="hash-link" aria-label="8. 安全（Security Toolchain）的直接链接" title="8. 安全（Security Toolchain）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-代码-sast">8.1 代码 SAST<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#81-%E4%BB%A3%E7%A0%81-sast" class="hash-link" aria-label="8.1 代码 SAST的直接链接" title="8.1 代码 SAST的直接链接" translate="no">​</a></h3>













































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>CodeQL</strong></td><td>开源/商业</td><td>GitHub 内置</td></tr><tr><td><strong>Snyk Code</strong></td><td>商业</td><td>多语言</td></tr><tr><td><strong>SonarQube</strong></td><td>开源/商业</td><td>自托管经典</td></tr><tr><td><strong>Semgrep</strong></td><td>开源</td><td>轻量规则引擎</td></tr><tr><td><strong>Bandit</strong></td><td>开源</td><td>Python 专用</td></tr><tr><td><strong>gosec</strong></td><td>开源</td><td>Go 专用</td></tr><tr><td><strong>Checkov</strong></td><td>开源</td><td>IaC 安全（Terraform）</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-镜像--容器">8.2 镜像 / 容器<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#82-%E9%95%9C%E5%83%8F--%E5%AE%B9%E5%99%A8" class="hash-link" aria-label="8.2 镜像 / 容器的直接链接" title="8.2 镜像 / 容器的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Trivy</strong></td><td>开源</td><td>全能扫描器（见前文）</td></tr><tr><td><strong>Snyk Container</strong></td><td>商业</td><td>商业加固</td></tr><tr><td><strong>Clair</strong></td><td>开源/CNCF</td><td>静态分析</td></tr><tr><td><strong>Anchore</strong></td><td>开源/商业</td><td>深度合规</td></tr><tr><td><strong>Docker Scout</strong></td><td>SaaS</td><td>Docker 官方</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="83-运行时">8.3 运行时<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#83-%E8%BF%90%E8%A1%8C%E6%97%B6" class="hash-link" aria-label="8.3 运行时的直接链接" title="8.3 运行时的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Falco</strong></td><td>开源/CNCF</td><td>运行时安全（syscall）</td></tr><tr><td><strong>Tracee</strong></td><td>开源</td><td>eBPF 运行时安全</td></tr><tr><td><strong>Tetragon</strong></td><td>开源</td><td>Cilium 出品 eBPF</td></tr><tr><td><strong>Aqua Security</strong></td><td>商业</td><td>重型商业</td></tr><tr><td><strong>Prisma Cloud</strong></td><td>商业</td><td>Palo Alto</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="84-策略--合规">8.4 策略 / 合规<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#84-%E7%AD%96%E7%95%A5--%E5%90%88%E8%A7%84" class="hash-link" aria-label="8.4 策略 / 合规的直接链接" title="8.4 策略 / 合规的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>OPA</strong></td><td>开源</td><td>策略引擎（Rego）</td></tr><tr><td><strong>Gatekeeper</strong></td><td>开源</td><td>OPA in K8s</td></tr><tr><td><strong>Kyverno</strong></td><td>开源</td><td>K8s 策略，YAML 友好</td></tr><tr><td><strong>Conftest</strong></td><td>开源</td><td>OPA CLI 测试</td></tr><tr><td><strong>Falco Rules</strong></td><td>开源</td><td>Falco 默认规则</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="85-密钥--secret">8.5 密钥 / Secret<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#85-%E5%AF%86%E9%92%A5--secret" class="hash-link" aria-label="8.5 密钥 / Secret的直接链接" title="8.5 密钥 / Secret的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>HashiCorp Vault</strong></td><td>开源</td><td>业界标准</td></tr><tr><td><strong>Sealed Secrets</strong></td><td>开源</td><td>Bitnami 出品</td></tr><tr><td><strong>External Secrets Operator</strong></td><td>开源</td><td>集成云厂商 Secrets</td></tr><tr><td><strong>AWS Secrets Manager</strong></td><td>商业</td><td>AWS 集成</td></tr><tr><td><strong>Azure Key Vault</strong></td><td>商业</td><td>Azure 集成</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="86-依赖">8.6 依赖<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#86-%E4%BE%9D%E8%B5%96" class="hash-link" aria-label="8.6 依赖的直接链接" title="8.6 依赖的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Dependabot</strong></td><td>SaaS</td><td>GitHub 内置</td></tr><tr><td><strong>Renovate</strong></td><td>开源</td><td>自托管 / SaaS</td></tr><tr><td><strong>Snyk Open Source</strong></td><td>商业</td><td>含已知漏洞库</td></tr><tr><td><strong>OWASP Dependency-Check</strong></td><td>开源</td><td>Java/Node/.NET</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">小企业最小集：<strong>Trivy</strong> + <strong>Renovate/Dependabot</strong> + <strong>Vault</strong> + <strong>Kyverno</strong></li>
<li class="">中型：+ <strong>Snyk</strong> + <strong>Falco</strong> + <strong>OPA</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-服务网格service-mesh">9. 服务网格（Service Mesh）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#9-%E6%9C%8D%E5%8A%A1%E7%BD%91%E6%A0%BCservice-mesh" class="hash-link" aria-label="9. 服务网格（Service Mesh）的直接链接" title="9. 服务网格（Service Mesh）的直接链接" translate="no">​</a></h2>








































<table><thead><tr><th>工具</th><th>类型</th><th>数据面</th></tr></thead><tbody><tr><td><strong>Istio</strong></td><td>开源/Envoy</td><td>Envoy（功能最强）</td></tr><tr><td><strong>Linkerd</strong></td><td>开源/Conduit</td><td>Linkerd-proxy（轻量）</td></tr><tr><td><strong>Consul Connect</strong></td><td>商业/HashiCorp</td><td>Envoy</td></tr><tr><td><strong>Cilium Service Mesh</strong></td><td>开源</td><td>eBPF（内核）</td></tr><tr><td><strong>Kuma</strong></td><td>开源</td><td>Envoy</td></tr><tr><td><strong>AWS App Mesh</strong></td><td>商业</td><td>Envoy</td></tr></tbody></table>
<p><strong>选型建议</strong>：</p>
<ul>
<li class="">中小规模 → <strong>Linkerd</strong>（轻量） 或 <strong>Cilium</strong>（性能）</li>
<li class="">大规模 + 复杂 → <strong>Istio</strong></li>
<li class="">单云 + 已用 ASM → <strong>AWS App Mesh</strong></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="10-多集群管理multi-cluster-orchestration">10. 多集群管理（Multi-Cluster Orchestration）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#10-%E5%A4%9A%E9%9B%86%E7%BE%A4%E7%AE%A1%E7%90%86multi-cluster-orchestration" class="hash-link" aria-label="10. 多集群管理（Multi-Cluster Orchestration）的直接链接" title="10. 多集群管理（Multi-Cluster Orchestration）的直接链接" translate="no">​</a></h2>








































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Rancher</strong></td><td>开源/商业</td><td>见 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/kubernetes/04-rancher">IV_Rancher笔记</a></td></tr><tr><td><strong>Cluster API</strong></td><td>开源/K8s sig</td><td>声明式 K8s 集群生命周期</td></tr><tr><td><strong>Clusterpedia</strong></td><td>开源</td><td>跨集群查询</td></tr><tr><td><strong>ArgoCD ApplicationSet</strong></td><td>开源</td><td>ArgoCD 多集群部署</td></tr><tr><td><strong>Rafay</strong></td><td>SaaS/商业</td><td>企业级</td></tr><tr><td><strong>Nirmata</strong></td><td>SaaS/商业</td><td>企业级</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-平台工程--idp">11. 平台工程 / IDP<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#11-%E5%B9%B3%E5%8F%B0%E5%B7%A5%E7%A8%8B--idp" class="hash-link" aria-label="11. 平台工程 / IDP的直接链接" title="11. 平台工程 / IDP的直接链接" translate="no">​</a></h2>



































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Backstage</strong></td><td>开源/CNCF</td><td>Spotify 出品，事实标准</td></tr><tr><td><strong>Compass</strong></td><td>SaaS</td><td>Atlassian</td></tr><tr><td><strong>Port</strong></td><td>SaaS</td><td>商业</td></tr><tr><td><strong>Cortex</strong></td><td>SaaS</td><td>商业</td></tr><tr><td><strong>Roadmap.sh</strong></td><td>开源/Wiki</td><td>简单</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-混沌工程chaos-engineering">12. 混沌工程（Chaos Engineering）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#12-%E6%B7%B7%E6%B2%8C%E5%B7%A5%E7%A8%8Bchaos-engineering" class="hash-link" aria-label="12. 混沌工程（Chaos Engineering）的直接链接" title="12. 混沌工程（Chaos Engineering）的直接链接" translate="no">​</a></h2>



































<table><thead><tr><th>工具</th><th>类型</th><th>简介</th></tr></thead><tbody><tr><td><strong>Chaos Monkey</strong></td><td>开源/Netflix</td><td>杀实例</td></tr><tr><td><strong>Chaos Mesh</strong></td><td>开源/PingCAP</td><td>K8s 混沌</td></tr><tr><td><strong>LitmusChaos</strong></td><td>开源/CNCF</td><td>K8s 混沌</td></tr><tr><td><strong>Gremlin</strong></td><td>SaaS</td><td>商业</td></tr><tr><td><strong>ChaosBlade</strong></td><td>开源/阿里</td><td>国内通用</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-选型速查按主题一图一表">13. 选型速查（按主题一图一表）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#13-%E9%80%89%E5%9E%8B%E9%80%9F%E6%9F%A5%E6%8C%89%E4%B8%BB%E9%A2%98%E4%B8%80%E5%9B%BE%E4%B8%80%E8%A1%A8" class="hash-link" aria-label="13. 选型速查（按主题一图一表）的直接链接" title="13. 选型速查（按主题一图一表）的直接链接" translate="no">​</a></h2>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">代码：   GitHub / GitLab CE / Gitea</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">CI：     GitHub Actions / GitLab CI / Tekton / Jenkins</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">CD：     ArgoCD / Flux / Harness</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">IaC：   Terraform / OpenTofu / Pulumi</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">镜像：   Harbor / ECR / Nexus</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">日志：   Loki / ELK</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">指标：   Prometheus + Grafana</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">链路：   Tempo / Jaeger / OpenTelemetry</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">告警：   Alertmanager + PagerDuty / 飞书</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">镜像扫描：Trivy / Snyk</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">运行时：Falco / Tetragon</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">策略：  Kyverno / OPA</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">密钥：   Vault</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Mesh：  Linkerd / Istio / Cilium</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">多集群：Rancher / ClusterAPI</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">IDP：   Backstage</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">混沌：  Chaos Mesh / Litmus</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="14-一句话总结">14. 一句话总结<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%B7%A5%E5%85%B7%E9%93%BE%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#14-%E4%B8%80%E5%8F%A5%E8%AF%9D%E6%80%BB%E7%BB%93" class="hash-link" aria-label="14. 一句话总结的直接链接" title="14. 一句话总结的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>小企业</strong>：开源工具够用，重点在<strong>整合</strong>而非单一工具好坏</li>
<li class=""><strong>17 个细分领域</strong>只是参考，实际企业只用到 5~8 个核心</li>
<li class="">选型原则：
<ol>
<li class="">先用主流（Jenkins / ArgoCD / Trivy / Prometheus），少创新</li>
<li class="">自托管 vs SaaS 看团队规模与合规</li>
<li class="">工具要<strong>统一生态</strong>（如 Grafana 全家桶 / Datadog 一体化）</li>
<li class=""><strong>可替换性</strong>：每层解耦，避免绑死某家</li>
</ol>
</li>
</ul>
<p>标签：#git #docker #kubernetes #jenkins</p>]]></content>
        <category label="Git" term="Git"/>
        <category label="Docker" term="Docker"/>
        <category label="Kubernetes" term="Kubernetes"/>
        <category label="Jenkins" term="Jenkins"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[Django + FastAPI 秒杀系统课程]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/Django+FastAPI秒杀系统课程</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/Django+FastAPI秒杀系统课程"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[由旧稿整理而来，内容未改，仅做结构与排版优化。旧稿目录已清理，当前以本文为准。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>由旧稿整理而来，<strong>内容未改</strong>，仅做结构与排版优化。旧稿目录已清理，当前以本文为准。</p>
<p>本笔记是网课资料汇总：<strong>课程观看入口</strong> + <strong>配套课件</strong>（语雀文档）+ <strong>课程代码</strong>（百度网盘）。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-课程观看">1. 课程观看<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/Django+FastAPI%E7%A7%92%E6%9D%80%E7%B3%BB%E7%BB%9F%E8%AF%BE%E7%A8%8B#1-%E8%AF%BE%E7%A8%8B%E8%A7%82%E7%9C%8B" class="hash-link" aria-label="1. 课程观看的直接链接" title="1. 课程观看的直接链接" translate="no">​</a></h2>













<table><thead><tr><th>项</th><th>链接</th></tr></thead><tbody><tr><td>网易云课堂</td><td><a href="https://study.163.com/course/courseMain.htm?courseId=1213775829&amp;_trace_c_p_k2_=a0edcec470e944d58a10b7445ae6e84e" target="_blank" rel="noopener noreferrer" class="">https://study.163.com/course/courseMain.htm?courseId=1213775829&amp;_trace_c_p_k2_=a0edcec470e944d58a10b7445ae6e84e</a></td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-配套课件语雀">2. 配套课件（语雀）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/Django+FastAPI%E7%A7%92%E6%9D%80%E7%B3%BB%E7%BB%9F%E8%AF%BE%E7%A8%8B#2-%E9%85%8D%E5%A5%97%E8%AF%BE%E4%BB%B6%E8%AF%AD%E9%9B%80" class="hash-link" aria-label="2. 配套课件（语雀）的直接链接" title="2. 配套课件（语雀）的直接链接" translate="no">​</a></h2>
<blockquote>
<p>全部为知了传课 / 知了课堂的语雀文档，对应模块密码见表格。</p>
</blockquote>















































<table><thead><tr><th>#</th><th>模块</th><th>课件链接</th><th>文档标题</th><th>访问密码</th></tr></thead><tbody><tr><td>1</td><td>异步 Django</td><td><a href="https://www.yuque.com/hynever/async-django" target="_blank" rel="noopener noreferrer" class="">https://www.yuque.com/hynever/async-django</a></td><td>异步 Django 课件</td><td><code>ra32</code></td></tr><tr><td>2</td><td>微服务</td><td><a href="https://www.yuque.com/hynever/micro-service" target="_blank" rel="noopener noreferrer" class="">https://www.yuque.com/hynever/micro-service</a></td><td>知了传课 - 微服务</td><td><code>ancc</code></td></tr><tr><td>3</td><td>FastAPI</td><td><a href="https://www.yuque.com/hynever/wms8gi" target="_blank" rel="noopener noreferrer" class="">https://www.yuque.com/hynever/wms8gi</a></td><td>知了传课 - FastAPI</td><td><code>puvz</code></td></tr><tr><td>4</td><td>uniapp</td><td><a href="https://www.yuque.com/hynever/uniapp" target="_blank" rel="noopener noreferrer" class="">https://www.yuque.com/hynever/uniapp</a></td><td>知了课堂 - uniapp 课件</td><td><code>kri4</code></td></tr><tr><td>5</td><td>电商秒杀项目实战</td><td><a href="https://www.yuque.com/hynever/shtqfp" target="_blank" rel="noopener noreferrer" class="">https://www.yuque.com/hynever/shtqfp</a></td><td>知了课堂 - 电商系统实战</td><td><code>zy6l</code></td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-课程代码百度网盘">3. 课程代码（百度网盘）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/Django+FastAPI%E7%A7%92%E6%9D%80%E7%B3%BB%E7%BB%9F%E8%AF%BE%E7%A8%8B#3-%E8%AF%BE%E7%A8%8B%E4%BB%A3%E7%A0%81%E7%99%BE%E5%BA%A6%E7%BD%91%E7%9B%98" class="hash-link" aria-label="3. 课程代码（百度网盘）的直接链接" title="3. 课程代码（百度网盘）的直接链接" translate="no">​</a></h2>

















<table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody><tr><td>链接</td><td><a href="https://pan.baidu.com/s/19Pg3LWTjoqYhjRl1kWcjpw?pwd=gxem" target="_blank" rel="noopener noreferrer" class="">https://pan.baidu.com/s/19Pg3LWTjoqYhjRl1kWcjpw?pwd=gxem</a></td></tr><tr><td>提取码</td><td><code>gxem</code></td></tr></tbody></table>
<p>标签：#django #fastapi #redis #celery</p>]]></content>
        <category label="Django" term="Django"/>
        <category label="FastAPI" term="FastAPI"/>
        <category label="Redis" term="Redis"/>
        <category label="Celery" term="Celery"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[LLM 评测框架对比笔记（OpenCompass vs EvalScope）]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM评测框架对比笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM评测框架对比笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[场景化选型决策树 + 标准生产评测流程 + 自定义数据集流程 + 报告指标清单 + 常见踩坑。覆盖两框架差异、共同点、互操作，以及业界最佳实践。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p><strong>本文目的</strong>：作为 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/llm-evaluation/opencompass">OpenCompass笔记</a> 和 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/llm-evaluation/evalscope">EvalScope笔记</a> 的对比与汇总文档，避免内容重复。本笔记专注于<strong>横向对比 + 选型决策 + 生产流程模板</strong>。
单框架细节请直接查阅两份单框架笔记。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="阅读地图">阅读地图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#%E9%98%85%E8%AF%BB%E5%9C%B0%E5%9B%BE" class="hash-link" aria-label="阅读地图的直接链接" title="阅读地图的直接链接" translate="no">​</a></h2>

































































<table><thead><tr><th>§</th><th>主题</th><th>一句话定位</th></tr></thead><tbody><tr><td>1</td><td>定位差异</td><td>学术权威 vs 一站式</td></tr><tr><td>2</td><td>共同点</td><td>5 项基础能力两框架均支持</td></tr><tr><td>3</td><td>差异表（核心）</td><td>10 维度 × 2 框架对比</td></tr><tr><td>4</td><td>选型决策树</td><td>8 类场景 → 推荐框架</td></tr><tr><td>5</td><td>互操作与混合部署</td><td>EvalScope 把 OpenCompass 封装为后端</td></tr><tr><td>6</td><td>标准生产评测流程</td><td>7 步流水线（通用模板）</td></tr><tr><td>7</td><td>自定义数据集的标准化流程</td><td>JSONL / prompt template / 后处理</td></tr><tr><td>8</td><td>报告关键指标清单</td><td>8 项必备字段</td></tr><tr><td>9</td><td>常见踩坑</td><td>6 类典型问题</td></tr><tr><td>10</td><td>业界生产实践</td><td>HF Leaderboard / LMSYS Arena / HELM / Llama / Qwen</td></tr><tr><td>11</td><td>来源链接</td><td>全部参考链接按章节分组</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-定位差异">1. 定位差异<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#1-%E5%AE%9A%E4%BD%8D%E5%B7%AE%E5%BC%82" class="hash-link" aria-label="1. 定位差异的直接链接" title="1. 定位差异的直接链接" translate="no">​</a></h2>























<table><thead><tr><th>框架</th><th>厂商</th><th>定位</th><th>关键差异</th></tr></thead><tbody><tr><td><strong>OpenCompass</strong></td><td>上海 AI Lab / 书生·浦语</td><td><strong>学术权威纯文本评测</strong></td><td>CompassKit + CompassHub + CompassRank + CompassAcademic 四件套；学术榜单（C-Eval / SuperBench）官方维护</td></tr><tr><td><strong>EvalScope</strong></td><td>阿里魔搭（ModelScope）</td><td><strong>一站式：评测 + 压测 + Arena + 可视化</strong></td><td>把能力评测与推理性能压测整合到同一工具链；与 ms-swift 训练链路深度整合</td></tr></tbody></table>
<blockquote>
<p>一句话：<strong>学术榜单用 OpenCompass，生产一体化用 EvalScope</strong>。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-共同点">2. 共同点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#2-%E5%85%B1%E5%90%8C%E7%82%B9" class="hash-link" aria-label="2. 共同点的直接链接" title="2. 共同点的直接链接" translate="no">​</a></h2>
<p>两份框架都具备以下基础能力：</p>























































<table><thead><tr><th>能力</th><th>OpenCompass</th><th>EvalScope</th></tr></thead><tbody><tr><td>本地模型评测</td><td>✅ HF / LMDeploy / vLLM backend</td><td>✅ <code>--eval-type llm_ckpt</code></td></tr><tr><td>远程 API 模型评测</td><td>✅ OpenAI 兼容</td><td>✅ openai_api / anthropic_api / litellm / custom</td></tr><tr><td>OpenAI 兼容协议</td><td>✅</td><td>✅（强项，5 种 eval-type）</td></tr><tr><td>LLM-as-Judge</td><td>✅</td><td>✅（4 种 judge-strategy）</td></tr><tr><td>自定义数据集</td><td>✅ BaseDataset + yaml</td><td>✅ 4 种模板 + CollectionSchema</td></tr><tr><td>分布式评测</td><td>✅ Slurm / DLC</td><td>✅ 依赖底层推理后端（vLLM TP）</td></tr><tr><td>与 vLLM / SGLang 集成</td><td>✅ 通过 backend / API</td><td>✅ 通过 <code>--api-url</code></td></tr><tr><td>断点续跑</td><td>✅ <code>-r</code></td><td>✅ <code>--use-cache</code></td></tr><tr><td>报告格式</td><td>CSV / Markdown / 雷达图</td><td>JSON / HTML / Web Dashboard / Wandb</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-差异表核心">3. 差异表（核心）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#3-%E5%B7%AE%E5%BC%82%E8%A1%A8%E6%A0%B8%E5%BF%83" class="hash-link" aria-label="3. 差异表（核心）的直接链接" title="3. 差异表（核心）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-能力覆盖">3.1 能力覆盖<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#31-%E8%83%BD%E5%8A%9B%E8%A6%86%E7%9B%96" class="hash-link" aria-label="3.1 能力覆盖的直接链接" title="3.1 能力覆盖的直接链接" translate="no">​</a></h3>























































<table><thead><tr><th>维度</th><th>OpenCompass</th><th>EvalScope</th></tr></thead><tbody><tr><td><strong>内置 benchmark 数</strong></td><td>60+</td><td><strong>191</strong></td></tr><tr><td><strong>多模态支持</strong></td><td>❌ 纯文本（需配合 VLMEvalKit）</td><td>✅ <strong>Native 后端开箱支持 40+ VLM</strong></td></tr><tr><td><strong>Function Calling / Agent</strong></td><td>❌ 需自定义</td><td>✅ Native Agent + 沙箱</td></tr><tr><td><strong>性能压测（TTFT/TPOT）</strong></td><td>❌</td><td>✅ <strong><code>evalscope perf</code></strong>（与 vllm bench 一致）</td></tr><tr><td><strong>Arena 对战</strong></td><td>❌</td><td>✅ <strong><code>general_arena</code></strong> + WinRate + Elo</td></tr><tr><td><strong>Web Dashboard</strong></td><td>❌ 离线报告</td><td>✅ <strong><code>evalscope service</code> 端口 9000</strong></td></tr><tr><td><strong>权重采样多数据集混合</strong></td><td>❌ 需手动配置</td><td>✅ <strong>CollectionSchema</strong>（Weighted / Stratified / Uniform）</td></tr><tr><td><strong>服务化（REST API）</strong></td><td>❌</td><td>✅ <strong><code>evalscope service</code></strong></td></tr><tr><td><strong>可视化后端集成</strong></td><td>❌</td><td>✅ Wandb / SwanLab / Clearml</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-工程能力">3.2 工程能力<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#32-%E5%B7%A5%E7%A8%8B%E8%83%BD%E5%8A%9B" class="hash-link" aria-label="3.2 工程能力的直接链接" title="3.2 工程能力的直接链接" translate="no">​</a></h3>













































<table><thead><tr><th>维度</th><th>OpenCompass</th><th>EvalScope</th></tr></thead><tbody><tr><td><strong>后端选择</strong></td><td>HF / LMDeploy / vLLM / OpenAI API</td><td>HF / vLLM / OpenAI API / Anthropic API / LiteLLM / Custom</td></tr><tr><td><strong>CLI 参数丰富度</strong></td><td>中（run.py + 20 参数）</td><td><strong>高</strong>（<code>evalscope eval</code> + 30+ 参数）</td></tr><tr><td><strong>Python SDK</strong></td><td>Config-driven（yaml/python）</td><td><code>TaskConfig</code> 对象 + dict + YAML + JSON 四种</td></tr><tr><td><strong>集成 OpenCompass 作为后端</strong></td><td>—</td><td>✅ <code>ms-opencompass</code></td></tr><tr><td><strong>集成 VLMEvalKit 作为后端</strong></td><td>❌</td><td>✅</td></tr><tr><td><strong>集成 RAGEval（MTEB/RAGAS）</strong></td><td>❌</td><td>✅</td></tr><tr><td><strong>集成 ms-swift 训练链路</strong></td><td>❌</td><td>✅ 官方 best_practice</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-生态与社区">3.3 生态与社区<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#33-%E7%94%9F%E6%80%81%E4%B8%8E%E7%A4%BE%E5%8C%BA" class="hash-link" aria-label="3.3 生态与社区的直接链接" title="3.3 生态与社区的直接链接" translate="no">​</a></h3>













































<table><thead><tr><th>维度</th><th>OpenCompass</th><th>EvalScope</th></tr></thead><tbody><tr><td><strong>GitHub Star</strong></td><td><strong>7.1k</strong></td><td>3k+</td></tr><tr><td><strong>主导厂商</strong></td><td>上海 AI Lab（学术派）</td><td>阿里魔搭（工业派）</td></tr><tr><td><strong>主流用户</strong></td><td>InternLM 系列、Llama 官方推荐</td><td>Qwen 系列发版、阿里云百炼</td></tr><tr><td><strong>学术榜单</strong></td><td>CompassRank、C-Eval、SuperBench</td><td>—</td></tr><tr><td><strong>国内可达性</strong></td><td>✅（国内源友好）</td><td>✅（默认走 ModelScope）</td></tr><tr><td><strong>国际学术引用</strong></td><td>中等（HF Open LLM Leaderboard 引用少）</td><td>中等</td></tr><tr><td><strong>Meta Llama 官方背书</strong></td><td>✅ 推荐</td><td>—</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="34-文档与上手">3.4 文档与上手<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#34-%E6%96%87%E6%A1%A3%E4%B8%8E%E4%B8%8A%E6%89%8B" class="hash-link" aria-label="3.4 文档与上手的直接链接" title="3.4 文档与上手的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>维度</th><th>OpenCompass</th><th>EvalScope</th></tr></thead><tbody><tr><td><strong>官方文档完整度</strong></td><td>高（中文 doc.opencompass.org.cn + 英文 docs/en）</td><td>高（docs/zh + docs/en 双语，README 详细）</td></tr><tr><td><strong>配置文件方式</strong></td><td><strong>YAML / Python Config</strong>（Config-driven）</td><td>YAML / JSON / Python Dict / TaskConfig 对象</td></tr><tr><td><strong>典型配置行数</strong></td><td>30~60 行（model + dataset + 评测方式分开）</td><td><strong>10~20 行</strong>（TaskConfig 一站式）</td></tr><tr><td><strong>debug 模式</strong></td><td><code>--debug</code>（每个 dataset 取前 N）</td><td><code>--debug</code> / <code>--dry-run</code> / <code>--limit</code></td></tr><tr><td><strong>可视化报表</strong></td><td><code>viz_multi_model.py</code> 雷达图</td><td>HTML / Web Dashboard / Wandb</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-选型决策树">4. 选型决策树<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#4-%E9%80%89%E5%9E%8B%E5%86%B3%E7%AD%96%E6%A0%91" class="hash-link" aria-label="4. 选型决策树的直接链接" title="4. 选型决策树的直接链接" translate="no">​</a></h2>
<p>按场景给推荐（结合两份框架的实际能力）：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">你测什么模型？测什么场景？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 中文 Qwen 系列发版评测</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope（官方 best_practice，ms-swift 集成）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 英文 / 多语 Llama 系列发版评测</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → OpenCompass（Meta 官方推荐，学术权威）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    或 EvalScope（如果需要 perf 压测 + Arena）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 中文 InternLM / DeepSeek 系列</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → OpenCompass（学术榜单）或 EvalScope（国内友好）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 通用学术榜单对比（C-Eval / MMLU / SuperBench）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → OpenCompass（CompassRank 一键发布）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 多模态（VLM）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope Native 后端（40+ VLM benchmark 开箱）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    或 EvalScope + VLMEvalKit 后端</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ Function Calling / Agent 评测</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope（BFCL / ACEBench / τ-bench / GAIA）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 推理性能压测（TTFT/TPOT）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope perf（与 vllm bench 一致）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    或 vllm bench serve（更直接）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ Arena 双盲对战</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope general_arena</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    或 LMSYS Chatbot Arena（公开数据）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ RAG / Embedding 评测</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope RAGEVal 后端（MTEB / RAGAS）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 国内离线环境</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    → EvalScope（默认 ModelScope Hub，国内可达性最好）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└─ 纯文本 / 简单基座评测</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">     → OpenCompass（轻量、学术权威）</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-选择清单">4.1 选择清单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#41-%E9%80%89%E6%8B%A9%E6%B8%85%E5%8D%95" class="hash-link" aria-label="4.1 选择清单的直接链接" title="4.1 选择清单的直接链接" translate="no">​</a></h3>






































































<table><thead><tr><th>场景</th><th>推荐框架</th><th>理由</th></tr></thead><tbody><tr><td>阿里 Qwen 系列发版</td><td><strong>EvalScope</strong></td><td>官方 best_practice，ms-swift 闭环</td></tr><tr><td>Meta Llama 系列发版</td><td><strong>OpenCompass</strong></td><td>Meta 推荐，学术权威</td></tr><tr><td>InternLM 系列</td><td>OpenCompass / EvalScope</td><td>都可，OpenCompass 学术榜单加分</td></tr><tr><td>中文 VLM 模型</td><td><strong>EvalScope</strong></td><td>Native 后端开箱 40+ 多模态 benchmark</td></tr><tr><td>Function Calling 模型</td><td><strong>EvalScope</strong></td><td>BFCL / ACEBench / τ-bench 完整覆盖</td></tr><tr><td>Agent 类应用（GAIA / SWE-bench）</td><td><strong>EvalScope</strong></td><td>Docker 沙箱 + ReAct 全套</td></tr><tr><td>推理服务压测</td><td><strong>EvalScope perf</strong></td><td>与 vllm bench 一致，输出指标语义对齐</td></tr><tr><td>内部模型竞品对比</td><td><strong>EvalScope general_arena</strong></td><td>WinRate + Elo + 双盲</td></tr><tr><td>RAG 系统评估</td><td><strong>EvalScope RAGEVal</strong></td><td>MTEB / RAGAS 内置</td></tr><tr><td>C-Eval / SuperBench 上榜</td><td><strong>OpenCompass</strong></td><td>CompassRank 一键发布</td></tr><tr><td>纯文本基座快筛</td><td>OpenCompass（HF / LMDeploy backend）</td><td>轻量、配置直观</td></tr><tr><td>纯英文开源模型对标</td><td>OpenCompass（学术）或 EvalScope（生产）</td><td>看使用场景</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-互操作与混合部署">5. 互操作与混合部署<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#5-%E4%BA%92%E6%93%8D%E4%BD%9C%E4%B8%8E%E6%B7%B7%E5%90%88%E9%83%A8%E7%BD%B2" class="hash-link" aria-label="5. 互操作与混合部署的直接链接" title="5. 互操作与混合部署的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-evalscope-把-opencompass-封装为后端">5.1 EvalScope 把 OpenCompass 封装为后端<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#51-evalscope-%E6%8A%8A-opencompass-%E5%B0%81%E8%A3%85%E4%B8%BA%E5%90%8E%E7%AB%AF" class="hash-link" aria-label="5.1 EvalScope 把 OpenCompass 封装为后端的直接链接" title="5.1 EvalScope 把 OpenCompass 封装为后端的直接链接" translate="no">​</a></h3>
<p>EvalScope 通过 <code>--eval-backend OpenCompass</code> + <code>--eval-config &lt;yaml&gt;</code> 直接复用 OpenCompass 的所有配置：</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 用 OpenCompass 的 yaml 跑 EvalScope</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">evalscope </span><span class="token builtin class-name">eval</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--model</span><span class="token plain"> Qwen/Qwen2.5-7B-Instruct </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  --eval-backend OpenCompass </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  --eval-config configs/opencompass_eval.py </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--datasets</span><span class="token plain"> mmlu ceval gsm8k</span><br></div></code></pre></div></div>
<p>来源：<a href="https://github.com/modelscope/evalscope/blob/main/docs/en/user_guides/backend/opencompass_backend.md" target="_blank" rel="noopener noreferrer" class="">opencompass_backend.md</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-opencompass-也能调-openai-兼容远程服务">5.2 OpenCompass 也能调 OpenAI 兼容远程服务<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#52-opencompass-%E4%B9%9F%E8%83%BD%E8%B0%83-openai-%E5%85%BC%E5%AE%B9%E8%BF%9C%E7%A8%8B%E6%9C%8D%E5%8A%A1" class="hash-link" aria-label="5.2 OpenCompass 也能调 OpenAI 兼容远程服务的直接链接" title="5.2 OpenCompass 也能调 OpenAI 兼容远程服务的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># OpenCompass 用 OpenAI backend 接 vLLM 起的服务</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">models </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">(</span><span class="token builtin">type</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">'openai'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> abbr</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">'vllm-qwen'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> model</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">'qwen2.5'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">               key</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">'EMPTY'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> api_base</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">'http://127.0.0.1:8801/v1'</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">]</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-指标口径差异">5.3 指标口径差异<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#53-%E6%8C%87%E6%A0%87%E5%8F%A3%E5%BE%84%E5%B7%AE%E5%BC%82" class="hash-link" aria-label="5.3 指标口径差异的直接链接" title="5.3 指标口径差异的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>维度</th><th>OpenCompass</th><th>EvalScope</th></tr></thead><tbody><tr><td>输出主表</td><td><code>summary_*.csv</code></td><td><code>reports/*.json</code></td></tr><tr><td>可视化</td><td><code>viz_multi_model.py</code> 雷达图</td><td>HTML / Web Dashboard / Wandb</td></tr><tr><td>子指标细分</td><td>自动按子集分桶</td><td><code>subset_list</code> 选 / 五层聚合视角</td></tr><tr><td>Judge 模型配置</td><td><code>LLMJudgeEvaluator</code></td><td><code>--judge-model-args</code> JSON</td></tr><tr><td>Arena 模式</td><td>❌</td><td><code>general_arena</code> + WinRate + Elo</td></tr></tbody></table>
<blockquote>
<p>实操建议：<strong>两框架产出的指标可以并存</strong>（同一份数据集跑两遍，分别看 OpenCompass 的学术报告 + EvalScope 的工程报告）。不要试图做"指标换算"，直接以报告为准。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-标准生产评测流程通用模板">6. 标准生产评测流程（通用模板）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#6-%E6%A0%87%E5%87%86%E7%94%9F%E4%BA%A7%E8%AF%84%E6%B5%8B%E6%B5%81%E7%A8%8B%E9%80%9A%E7%94%A8%E6%A8%A1%E6%9D%BF" class="hash-link" aria-label="6. 标准生产评测流程（通用模板）的直接链接" title="6. 标准生产评测流程（通用模板）的直接链接" translate="no">​</a></h2>
<p>适用于两个框架的 7 步流水线：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">┌──────────────────────────────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 1. 模型准备                                           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 本地：HF / vLLM / LMDeploy / ms-swift 部署     │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ 远程：OpenAI 兼容 API（vLLM / SGLang / DashScope）│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├──────────────────────────────────────────────────────┤</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 2. 数据集准备                                         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 内置 benchmark（OpenCompass 60+ / EvalScope 191）│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 自定义 JSONL                                    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ HF / ModelScope Hub 直接复用                    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├──────────────────────────────────────────────────────┤</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 3. 评测执行                                           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 并发：--max-num-workers / --eval-batch-size    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 超时：框架默认 + 自定义 retry                   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ 容错：--ignore-errors / --use-cache            │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├──────────────────────────────────────────────────────┤</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 4. 结果汇总                                           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 框架内置 metric                                 │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 子集分析：按学科 / 任务 / 语言切分             │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ 失败样本回写 raw JSONL（便于二次分析）         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├──────────────────────────────────────────────────────┤</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 5. 报告产出                                           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ CSV / JSON / Markdown                          │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ HTML / Web Dashboard / Wandb                   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ 可视化对比（雷达图 / 柱状图）                   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├──────────────────────────────────────────────────────┤</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 6. 对比分析                                           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 与 baseline（同系列旧模型 / 竞品 / 闭源对照）  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ 历史回归（防止新版本回退）                     │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├──────────────────────────────────────────────────────┤</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ 7. 归档与回溯                                         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ 评测快照：commit id + dataset hash + model rev │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    ├─ temperature / max_tokens / prompt hash 锁定   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│    └─ 可复现命令归档                                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└──────────────────────────────────────────────────────┘</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-推荐落地的最小可用模板">6.1 推荐落地的最小可用模板<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#61-%E6%8E%A8%E8%8D%90%E8%90%BD%E5%9C%B0%E7%9A%84%E6%9C%80%E5%B0%8F%E5%8F%AF%E7%94%A8%E6%A8%A1%E6%9D%BF" class="hash-link" aria-label="6.1 推荐落地的最小可用模板的直接链接" title="6.1 推荐落地的最小可用模板的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>时间</th><th>数据集组合</th><th>框架</th></tr></thead><tbody><tr><td><strong>第一周（baseline）</strong></td><td>MMLU + GSM8K + IFEval + HumanEval pass@1（每个 ~500 条子样本）</td><td>OpenCompass 或 EvalScope</td></tr><tr><td><strong>第二周（扩展）</strong></td><td>加 HellaSwag / ARC / C-Eval / LiveCodeBench / MT-Bench</td><td>EvalScope（数据齐全）</td></tr><tr><td><strong>第三周（生产化）</strong></td><td>Bad Case 抽样 / 评测快照（commit 锁定）/ CI 化回归</td><td>EvalScope（service 模式）+ CI</td></tr><tr><td><strong>第四周（对比与文档）</strong></td><td>Arena 评测（多模型对比）/ Wandb 可视化 / 报告沉淀</td><td>EvalScope general_arena</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-自定义数据集的标准化流程">7. 自定义数据集的标准化流程<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#7-%E8%87%AA%E5%AE%9A%E4%B9%89%E6%95%B0%E6%8D%AE%E9%9B%86%E7%9A%84%E6%A0%87%E5%87%86%E5%8C%96%E6%B5%81%E7%A8%8B" class="hash-link" aria-label="7. 自定义数据集的标准化流程的直接链接" title="7. 自定义数据集的标准化流程的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-格式选型">7.1 格式选型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#71-%E6%A0%BC%E5%BC%8F%E9%80%89%E5%9E%8B" class="hash-link" aria-label="7.1 格式选型的直接链接" title="7.1 格式选型的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>格式</th><th>优点</th><th>缺点</th><th>适用</th></tr></thead><tbody><tr><td><strong>JSONL</strong></td><td>流式评测、错误隔离、字段灵活</td><td>文件大、需手工切分</td><td><strong>绝大多数场景首选</strong></td></tr><tr><td><strong>CSV</strong></td><td>表型结构清晰</td><td>仅扁平字段、嵌套困难</td><td>MCQ 等扁平结构</td></tr><tr><td><strong>HF Dataset</strong></td><td>复用 HF 预处理流水线</td><td>依赖 datasets 库</td><td>已有 HF 流水线</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-prompt-template-设计">7.2 Prompt Template 设计<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#72-prompt-template-%E8%AE%BE%E8%AE%A1" class="hash-link" aria-label="7.2 Prompt Template 设计的直接链接" title="7.2 Prompt Template 设计的直接链接" translate="no">​</a></h3>

























<table><thead><tr><th>类型</th><th>示例</th><th>适用</th></tr></thead><tbody><tr><td><strong>Zero-shot</strong></td><td><code>请回答：{question}</code></td><td>模型默认能力测试</td></tr><tr><td><strong>Few-shot</strong></td><td>固定 n-shot 例子（C-Eval / MMLU 默认 5-shot）</td><td>标准化榜单</td></tr><tr><td><strong>CoT</strong></td><td><code>让我们一步步思考：...</code></td><td>推理类（GSM8K / MATH 显著）</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="73-ground-truth-字段设计">7.3 Ground Truth 字段设计<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#73-ground-truth-%E5%AD%97%E6%AE%B5%E8%AE%BE%E8%AE%A1" class="hash-link" aria-label="7.3 Ground Truth 字段设计的直接链接" title="7.3 Ground Truth 字段设计的直接链接" translate="no">​</a></h3>
<p>必须显式定义：</p>

























<table><thead><tr><th>字段</th><th>含义</th><th>示例</th></tr></thead><tbody><tr><td><code>answer</code> / <code>label</code></td><td>唯一正确答案</td><td><code>"3"</code> / <code>"A"</code></td></tr><tr><td><code>reference</code></td><td>参考答案（开放式）</td><td><code>"法国是欧洲国家"</code></td></tr><tr><td><code>response</code></td><td>标准回复（教学场景）</td><td><code>"巴黎是法国的首都"</code></td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="74-后处理extract-then-compare">7.4 后处理（extract-then-compare）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#74-%E5%90%8E%E5%A4%84%E7%90%86extract-then-compare" class="hash-link" aria-label="7.4 后处理（extract-then-compare）的直接链接" title="7.4 后处理（extract-then-compare）的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># EvalScope 内置 xFinder 提取器</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># OpenCompass 通过 --reuse / 自定义 extract 函数</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 典型抽取：\boxed{...}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> re</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">extract_boxed</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">text</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    m </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> re</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">search</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">r'\\boxed\{([^}]+)\}'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> text</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> m</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">group</span><span class="token punctuation" style="color:#393A34">(</span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> m </span><span class="token keyword" style="color:#00009f">else</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">None</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="75-完整示例从原始数据到可评测数据集">7.5 完整示例：从原始数据到可评测数据集<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#75-%E5%AE%8C%E6%95%B4%E7%A4%BA%E4%BE%8B%E4%BB%8E%E5%8E%9F%E5%A7%8B%E6%95%B0%E6%8D%AE%E5%88%B0%E5%8F%AF%E8%AF%84%E6%B5%8B%E6%95%B0%E6%8D%AE%E9%9B%86" class="hash-link" aria-label="7.5 完整示例：从原始数据到可评测数据集的直接链接" title="7.5 完整示例：从原始数据到可评测数据集的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">原始 JSON / 数据库</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">标准化 JSONL（统一字段：question / answer / category / meta）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">注册进框架（OpenCompass configs/datasets/ 或 EvalScope custom_eval/）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">写 TaskConfig / dataset_args（声明 prompt_template / evaluator）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">烟雾测试（5 条 --limit 5）→ 调通</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">全量跑 + 结果回写</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-报告关键指标清单">8. 报告关键指标清单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#8-%E6%8A%A5%E5%91%8A%E5%85%B3%E9%94%AE%E6%8C%87%E6%A0%87%E6%B8%85%E5%8D%95" class="hash-link" aria-label="8. 报告关键指标清单的直接链接" title="8. 报告关键指标清单的直接链接" translate="no">​</a></h2>
<p>生产报告必备 8 项字段：</p>


















































<table><thead><tr><th>字段</th><th>说明</th><th>框架对应</th></tr></thead><tbody><tr><td><strong>总分（overall）</strong></td><td>加权或简单平均，注明权重</td><td>OpenCompass summary csv / EvalScope reports JSON</td></tr><tr><td><strong>子维度分数</strong></td><td>按学科 / 任务 / 语言切分</td><td>两框架都支持</td></tr><tr><td><strong>置信区间 / 标准差</strong></td><td>多次跑的标准差，或 BT 拟合的 95% CI</td><td>EvalScope Arena 自带</td></tr><tr><td><strong>失败 case 抽样</strong></td><td>每数据集随机抽 5~10 条 bad case</td><td>需手动抽样</td></tr><tr><td><strong>评测耗时与成本</strong></td><td>总 GPU 小时 / 总 token 数 / API 调用金额</td><td>框架不直接提供</td></tr><tr><td><strong>评测元数据</strong></td><td>模型 commit id / framework 版本 / dataset hash / temperature / max_tokens / prompt hash</td><td>需手动记录</td></tr><tr><td><strong>可复现命令 / 配置</strong></td><td>开箱即可 <code>git checkout</code> + 重跑</td><td>OpenCompass run.py / EvalScope TaskConfig</td></tr><tr><td><strong>可视化</strong></td><td>雷达图 / 柱状图 / Dashboard</td><td>OpenCompass viz / EvalScope HTML+WebUI</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-报告模板示例">8.1 报告模板示例<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#81-%E6%8A%A5%E5%91%8A%E6%A8%A1%E6%9D%BF%E7%A4%BA%E4%BE%8B" class="hash-link" aria-label="8.1 报告模板示例的直接链接" title="8.1 报告模板示例的直接链接" translate="no">​</a></h3>
<div class="language-markdown codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-markdown codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token title important punctuation" style="color:#393A34">#</span><span class="token title important"> 模型 X 评测报告 — YYYY-MM-DD</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> 总分</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 综合：68.4（加权平均）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 置信区间：[67.2, 69.6]（N=3 跑）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> 子维度</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 学科知识（MMLU / C-Eval）：72.1</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 推理（GSM8K / MATH）：58.3</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 代码（HumanEval pass@1）：65.0</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 中文（C-Eval / C-MMLU）：71.5</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 指令遵循（IFEval）：75.2</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> Bad Case（每类 3 条）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> GSM8K: 模型在多步减法上犯粗心错误</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> HumanEval: 边界条件 missing</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> ...</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> 评测元数据</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 模型：Qwen/Qwen2.5-7B-Instruct (commit: abc123)</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 框架：EvalScope v1.8.1</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> 数据集 hash：mmlu@ef456、gsm8k@789abc</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> temperature: 0.0</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> max_tokens: 2048</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token list punctuation" style="color:#393A34">-</span><span class="token plain"> prompt template hash: a1b2c3</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token title important punctuation" style="color:#393A34">##</span><span class="token title important"> 可复现命令</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">evalscope eval --model Qwen/Qwen2.5-7B-Instruct \</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  --datasets mmlu gsm8k humaneval --temperature 0.0 \</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  --judge-strategy rule --work-dir outputs/20260702_qwen25</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-常见踩坑">9. 常见踩坑<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#9-%E5%B8%B8%E8%A7%81%E8%B8%A9%E5%9D%91" class="hash-link" aria-label="9. 常见踩坑的直接链接" title="9. 常见踩坑的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="91-数据集污染">9.1 数据集污染<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#91-%E6%95%B0%E6%8D%AE%E9%9B%86%E6%B1%A1%E6%9F%93" class="hash-link" aria-label="9.1 数据集污染的直接链接" title="9.1 数据集污染的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>HF Leaderboard 教训</strong>：DROP 曾因污染下架（<a href="https://huggingface.co/blog/open-llm-leaderboard-drop" target="_blank" rel="noopener noreferrer" class="">HF 复盘</a>）</li>
<li class=""><strong>缓解</strong>：
<ul>
<li class="">用「近期题」或「动态题库」（LiveCodeBench 持续更新、IFEval 包含新型格式）</li>
<li class="">公开 canary string（GPQA 含 BigBench canary）</li>
<li class="">评测前做 decontamination：在训练数据上跑 n-gram 重叠检测</li>
</ul>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="92-prompt-不一致">9.2 Prompt 不一致<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#92-prompt-%E4%B8%8D%E4%B8%80%E8%87%B4" class="hash-link" aria-label="9.2 Prompt 不一致的直接链接" title="9.2 Prompt 不一致的直接链接" translate="no">​</a></h3>
<ul>
<li class="">同一份 MMLU + 同一份 5-shot，原始 / HELM / Harness 实现之间最大差 <strong>30%</strong>（<a href="https://huggingface.co/blog/open-llm-leaderboard-mmlu" target="_blank" rel="noopener noreferrer" class="">HF MMLU 复盘</a>）</li>
<li class=""><strong>缓解</strong>：固定 prompt 版本 + commit hash + prompt template hash 归档到报告</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="93-评测随机性">9.3 评测随机性<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#93-%E8%AF%84%E6%B5%8B%E9%9A%8F%E6%9C%BA%E6%80%A7" class="hash-link" aria-label="9.3 评测随机性的直接链接" title="9.3 评测随机性的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><code>temperature &gt; 0</code> 时单次评测不稳</li>
<li class=""><strong>缓解</strong>：
<ul>
<li class="">能确定性评测的（选择题 / 抽取）用 <code>temperature=0</code> greedy</li>
<li class="">开放式评测用 <code>temperature=0</code> + 多次重采平均，或采样一次 + 把方差记入报告</li>
<li class="">MT-Bench 的 multi-turn 也要确保 same seed</li>
</ul>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="94-llm-as-judge-的偏差">9.4 LLM-as-Judge 的偏差<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#94-llm-as-judge-%E7%9A%84%E5%81%8F%E5%B7%AE" class="hash-link" aria-label="9.4 LLM-as-Judge 的偏差的直接链接" title="9.4 LLM-as-Judge 的偏差的直接链接" translate="no">​</a></h3>
<p>MT-Bench 已识别 4 种偏差（<a href="https://arxiv.org/abs/2306.05685" target="_blank" rel="noopener noreferrer" class="">MT-Bench 论文</a>）：</p>






























<table><thead><tr><th>偏差</th><th>表现</th><th>缓解</th></tr></thead><tbody><tr><td><strong>Position bias</strong></td><td>偏好先出现的回答</td><td>交换顺序</td></tr><tr><td><strong>Verbosity bias</strong></td><td>偏好长回答</td><td>AlpacaEval LC 剥离长度</td></tr><tr><td><strong>Self-enhancement bias</strong></td><td>GPT-4 偏好 GPT-4 输出</td><td>用不同系列 judge</td></tr><tr><td><strong>推理能力受限</strong></td><td>judge 不擅长推理判断</td><td>用 Qwen2.5-72B / Claude-Opus 等强模型</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="95-长文本评测截断">9.5 长文本评测截断<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#95-%E9%95%BF%E6%96%87%E6%9C%AC%E8%AF%84%E6%B5%8B%E6%88%AA%E6%96%AD" class="hash-link" aria-label="9.5 长文本评测截断的直接链接" title="9.5 长文本评测截断的直接链接" translate="no">​</a></h3>
<ul>
<li class="">NIAH 经典失败模式是「中间遗忘」</li>
<li class="">RULER 强化了对 mid-context 的检索与聚合</li>
<li class=""><strong>缓解</strong>：强制满上下文扫描 + length × depth 二维热力图</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="96-多轮对话状态管理">9.6 多轮对话状态管理<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#96-%E5%A4%9A%E8%BD%AE%E5%AF%B9%E8%AF%9D%E7%8A%B6%E6%80%81%E7%AE%A1%E7%90%86" class="hash-link" aria-label="9.6 多轮对话状态管理的直接链接" title="9.6 多轮对话状态管理的直接链接" translate="no">​</a></h3>
<ul>
<li class="">MT-Bench 用两轮问题检验模型记忆 / 修正能力</li>
<li class=""><strong>缓解</strong>：评测框架需保证 chat template 一致（system prompt、history 注入）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="10-业界生产实践">10. 业界生产实践<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#10-%E4%B8%9A%E7%95%8C%E7%94%9F%E4%BA%A7%E5%AE%9E%E8%B7%B5" class="hash-link" aria-label="10. 业界生产实践的直接链接" title="10. 业界生产实践的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="101-huggingface-open-llm-leaderboard">10.1 HuggingFace Open LLM Leaderboard<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#101-huggingface-open-llm-leaderboard" class="hash-link" aria-label="10.1 HuggingFace Open LLM Leaderboard的直接链接" title="10.1 HuggingFace Open LLM Leaderboard的直接链接" translate="no">​</a></h3>




















<table><thead><tr><th>版本</th><th>数据集</th><th>经验</th></tr></thead><tbody><tr><td><strong>v1</strong></td><td>ARC、HellaSwag、MMLU、TruthfulQA、Winogrande、GSM8K、DROP</td><td>后两者曾因标准化问题被争议</td></tr><tr><td><strong>v2</strong></td><td>IFEval、BBH、MATH Level 5、GPQA、MGSM、MuSR</td><td>均为「持续动态 / 更难 / 更不易饱和」集合</td></tr></tbody></table>
<p>评测基于 EleutherAI LM Evaluation Harness，强制固定 commit id + 5-shot example 顺序来保证可比性。</p>
<p>来源：<a href="https://huggingface.co/spaces/open-llm-leaderboard/blog" target="_blank" rel="noopener noreferrer" class="">Leaderboard v2 启动 blog</a> · <a href="https://github.com/EleutherAI/lm-evaluation-harness" target="_blank" rel="noopener noreferrer" class="">lm-evaluation-harness README</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="102-lmsys-chatbot-arena">10.2 LMSYS Chatbot Arena<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#102-lmsys-chatbot-arena" class="hash-link" aria-label="10.2 LMSYS Chatbot Arena的直接链接" title="10.2 LMSYS Chatbot Arena的直接链接" translate="no">​</a></h3>
<p>匿名两两对战 → Bradley-Terry 模型 + style control + 95% CI。</p>
<p>数据沉淀：<a href="https://huggingface.co/datasets/lmsys/lmsys-chat-1m" target="_blank" rel="noopener noreferrer" class="">LMSYS-Chat-1M</a>（1M 真实对话 / 25 LLM / 154 语种）。</p>
<p>来源：<a href="https://arxiv.org/abs/2403.04132" target="_blank" rel="noopener noreferrer" class="">Chatbot Arena 论文</a> · <a href="https://arena.ai/faq" target="_blank" rel="noopener noreferrer" class="">Arena FAQ</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="103-stanford-helm">10.3 Stanford HELM<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#103-stanford-helm" class="hash-link" aria-label="10.3 Stanford HELM的直接链接" title="10.3 Stanford HELM的直接链接" translate="no">​</a></h3>
<ul>
<li class="">7 类指标（accuracy / calibration / robustness / fairness / bias / toxicity / efficiency）× 16 个核心场景</li>
<li class="">覆盖率从原 17.9% 提升至 96.0%</li>
<li class="">评测规模：~4900 evaluations，12B tokens，17M 模型调用</li>
</ul>
<p>来源：<a href="https://crfm.stanford.edu/2022/11/17/helm.html" target="_blank" rel="noopener noreferrer" class="">HELM 论文</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="104-meta-llama-系列发版评测">10.4 Meta Llama 系列发版评测<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#104-meta-llama-%E7%B3%BB%E5%88%97%E5%8F%91%E7%89%88%E8%AF%84%E6%B5%8B" class="hash-link" aria-label="10.4 Meta Llama 系列发版评测的直接链接" title="10.4 Meta Llama 系列发版评测的直接链接" translate="no">​</a></h3>
<p>来源：<a href="https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/MODEL_CARD.md" target="_blank" rel="noopener noreferrer" class="">Llama 3.1 Model Card</a></p>
<p><strong>Pretrain benchmark set</strong>：MMLU、MMLU-Pro (CoT)、AGIEval、CommonSenseQA、Winogrande、BBH (CoT)、ARC-C、TriviaQA-Wiki、SQuAD、QuAC、BoolQ、DROP。</p>
<p><strong>Instruct benchmark set</strong>：追加 IFEval、ARC-C、GPQA、HumanEval/MBPP++/Multipl-E、GSM8K (CoT)、MATH (CoT)、API-Bank/BFCL/Gorilla/Nexus、多语言 MGSM。</p>
<p>发版前必做红队 + 关键风险测试（CBRNE、儿童安全、cyber uplift），并通过 Llama Guard 3 / Prompt Guard / Code Shield 做输入输出过滤。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="105-阿里-qwen-系列发版评测">10.5 阿里 Qwen 系列发版评测<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#105-%E9%98%BF%E9%87%8C-qwen-%E7%B3%BB%E5%88%97%E5%8F%91%E7%89%88%E8%AF%84%E6%B5%8B" class="hash-link" aria-label="10.5 阿里 Qwen 系列发版评测的直接链接" title="10.5 阿里 Qwen 系列发版评测的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>Qwen2 / Qwen2.5</strong>：覆盖 MMLU、HumanEval、MATH，与 Llama / Mistral / Claude / GPT-4o 对比，分「base vs base」「instruct vs instruct」两轨</li>
<li class=""><strong>Qwen2.5-Max</strong>：MMLU-Pro、LiveCodeBench、LiveBench、Arena-Hard、GPQA-Diamond，明显向「动态 / 更难 / Arena 偏好」倾斜</li>
<li class=""><strong>Qwen3</strong>：开启 thinking / non-thinking 双模式评测，强调推理预算可控</li>
</ul>
<p>「Friends of Qwen」标注外部评测方：LMSys、OpenCompass、Open LLM Leaderboard。</p>
<p>来源：<a href="https://qwenlm.github.io/blog/qwen2.5-max/" target="_blank" rel="noopener noreferrer" class="">Qwen2.5-Max blog</a> · <a href="https://qwenlm.github.io/blog/qwen3/" target="_blank" rel="noopener noreferrer" class="">Qwen3 blog</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="106-openai--anthropic-内部评测公开资料">10.6 OpenAI / Anthropic 内部评测（公开资料）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#106-openai--anthropic-%E5%86%85%E9%83%A8%E8%AF%84%E6%B5%8B%E5%85%AC%E5%BC%80%E8%B5%84%E6%96%99" class="hash-link" aria-label="10.6 OpenAI / Anthropic 内部评测（公开资料）的直接链接" title="10.6 OpenAI / Anthropic 内部评测（公开资料）的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>OpenAI GPT-4 技术报告</strong>：列出多类对抗性 / 准确性评测（<a href="https://arxiv.org/abs/2303.08774" target="_blank" rel="noopener noreferrer" class="">arXiv:2303.08774</a>）</li>
<li class=""><strong>Anthropic</strong>：在 <a href="https://www.anthropic.com/news/core-views-on-ai-safety" target="_blank" rel="noopener noreferrer" class="">Core Views on AI Safety</a> 公开承诺 capability 跨越安全门槛前不发版，由外部独立组织评估能力 + 安全</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-来源链接">11. 来源链接<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#11-%E6%9D%A5%E6%BA%90%E9%93%BE%E6%8E%A5" class="hash-link" aria-label="11. 来源链接的直接链接" title="11. 来源链接的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="111-框架官方">11.1 框架官方<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#111-%E6%A1%86%E6%9E%B6%E5%AE%98%E6%96%B9" class="hash-link" aria-label="11.1 框架官方的直接链接" title="11.1 框架官方的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://github.com/open-compass/opencompass" target="_blank" rel="noopener noreferrer" class="">OpenCompass GitHub</a> / <a href="https://github.com/modelscope/evalscope" target="_blank" rel="noopener noreferrer" class="">EvalScope GitHub</a></li>
<li class=""><a href="https://opencompass.org.cn/" target="_blank" rel="noopener noreferrer" class="">OpenCompass 官网</a> / <a href="https://rank.opencompass.org.cn/" target="_blank" rel="noopener noreferrer" class="">CompassRank 排行榜</a></li>
<li class=""><a href="https://pypi.org/project/evalscope/" target="_blank" rel="noopener noreferrer" class="">EvalScope PyPI</a> / <a href="https://github.com/modelscope/evalscope/releases" target="_blank" rel="noopener noreferrer" class="">EvalScope Releases</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="112-业界实践">11.2 业界实践<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#112-%E4%B8%9A%E7%95%8C%E5%AE%9E%E8%B7%B5" class="hash-link" aria-label="11.2 业界实践的直接链接" title="11.2 业界实践的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://huggingface.co/spaces/open-llm-leaderboard/blog" target="_blank" rel="noopener noreferrer" class="">HF Open LLM Leaderboard v2 启动 blog</a></li>
<li class=""><a href="https://huggingface.co/blog/open-llm-leaderboard-drop" target="_blank" rel="noopener noreferrer" class="">HF Leaderboard DROP 复盘</a></li>
<li class=""><a href="https://huggingface.co/blog/open-llm-leaderboard-mmlu" target="_blank" rel="noopener noreferrer" class="">HF Leaderboard MMLU 复盘</a></li>
<li class=""><a href="https://github.com/EleutherAI/lm-evaluation-harness" target="_blank" rel="noopener noreferrer" class="">lm-evaluation-harness README</a></li>
<li class=""><a href="https://arxiv.org/abs/2403.04132" target="_blank" rel="noopener noreferrer" class="">Chatbot Arena 论文</a></li>
<li class=""><a href="https://arena.ai/faq" target="_blank" rel="noopener noreferrer" class="">Arena FAQ</a></li>
<li class=""><a href="https://crfm.stanford.edu/2022/11/17/helm.html" target="_blank" rel="noopener noreferrer" class="">HELM 论文</a></li>
<li class=""><a href="https://huggingface.co/datasets/lmsys/lmsys-chat-1m" target="_blank" rel="noopener noreferrer" class="">LMSYS-Chat-1M</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="113-原始-benchmark-论文">11.3 原始 benchmark 论文<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#113-%E5%8E%9F%E5%A7%8B-benchmark-%E8%AE%BA%E6%96%87" class="hash-link" aria-label="11.3 原始 benchmark 论文的直接链接" title="11.3 原始 benchmark 论文的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://arxiv.org/abs/1905.07830" target="_blank" rel="noopener noreferrer" class="">HellaSwag</a> · <a href="https://arxiv.org/abs/2009.03300" target="_blank" rel="noopener noreferrer" class="">MMLU</a> · <a href="https://arxiv.org/abs/2110.14168" target="_blank" rel="noopener noreferrer" class="">GSM8K</a></li>
<li class=""><a href="https://arxiv.org/abs/2103.03874" target="_blank" rel="noopener noreferrer" class="">MATH</a> · <a href="https://github.com/openai/human-eval" target="_blank" rel="noopener noreferrer" class="">HumanEval</a> · <a href="https://arxiv.org/abs/2210.09261" target="_blank" rel="noopener noreferrer" class="">BBH</a></li>
<li class=""><a href="https://arxiv.org/abs/2308.14508" target="_blank" rel="noopener noreferrer" class="">LongBench</a> · <a href="https://arxiv.org/abs/2306.05685" target="_blank" rel="noopener noreferrer" class="">MT-Bench</a> · <a href="https://arxiv.org/abs/2311.07911" target="_blank" rel="noopener noreferrer" class="">IFEval</a></li>
<li class=""><a href="https://github.com/gkamradt/LLMTest_NeedleInAHaystack" target="_blank" rel="noopener noreferrer" class="">Needle-in-a-Haystack</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="114-厂商发版评测">11.4 厂商发版评测<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#114-%E5%8E%82%E5%95%86%E5%8F%91%E7%89%88%E8%AF%84%E6%B5%8B" class="hash-link" aria-label="11.4 厂商发版评测的直接链接" title="11.4 厂商发版评测的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/MODEL_CARD.md" target="_blank" rel="noopener noreferrer" class="">Llama 3.1 Model Card</a></li>
<li class=""><a href="https://qwenlm.github.io/blog/qwen2.5-max/" target="_blank" rel="noopener noreferrer" class="">Qwen2.5-Max blog</a> · <a href="https://qwenlm.github.io/blog/qwen3/" target="_blank" rel="noopener noreferrer" class="">Qwen3 blog</a></li>
<li class=""><a href="https://arxiv.org/abs/2303.08774" target="_blank" rel="noopener noreferrer" class="">GPT-4 Technical Report</a></li>
<li class=""><a href="https://www.anthropic.com/news/core-views-on-ai-safety" target="_blank" rel="noopener noreferrer" class="">Anthropic Core Views on AI Safety</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="115-配套-demo">11.5 配套 demo<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/LLM%E8%AF%84%E6%B5%8B%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#115-%E9%85%8D%E5%A5%97-demo" class="hash-link" aria-label="11.5 配套 demo的直接链接" title="11.5 配套 demo的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/llm-demo/03_eval_frameworks/README.md" target="_blank" rel="noopener noreferrer" class="">example/llm-demo/03_eval_frameworks</a> — OpenCompass + EvalScope 双框架 mock 演示</li>
</ul>
<p>标签：#llm-eval</p>]]></content>
        <category label="OpenCompass" term="OpenCompass"/>
        <category label="EvalScope" term="EvalScope"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[直出设计图的UI工具]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/UI设计工具与灵感资源笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/UI设计工具与灵感资源笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[figma make]]></summary>
        <content type="html"><![CDATA[<p>figma make</p>
<p>google stitch</p>



































<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Curated Design</td><td><a href="https://curated.design/" target="_blank" rel="noopener noreferrer" class="">https://curated.design</a></td><td>高质量极简 UI 灵感，提供精选案例</td></tr><tr><td>Godly Website</td><td><a href="https://godly.website/" target="_blank" rel="noopener noreferrer" class="">https://godly.website</a></td><td>展示大胆、视觉惊艳的网页设计</td></tr><tr><td>Seesaw Website</td><td><a href="https://seesaw.design/" target="_blank" rel="noopener noreferrer" class="">https://seesaw.design</a></td><td>优雅极简 UI 设计灵感</td></tr><tr><td>SiteInspire</td><td><a href="https://www.siteinspire.com/" target="_blank" rel="noopener noreferrer" class="">https://www.siteinspire.com</a></td><td>优雅精致的网页设计灵感</td></tr><tr><td>Httpster</td><td><a href="https://httpster.net/" target="_blank" rel="noopener noreferrer" class="">https://httpster.net</a></td><td>古怪非传统的网页设计示例</td></tr></tbody></table>




















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>CSS Design Awards</td><td><a href="https://cssdesignawards.com/" target="_blank" rel="noopener noreferrer" class="">https://cssdesignawards.com</a></td><td>获奖前沿 UI 设计展示</td></tr><tr><td>Awwwards</td><td><a href="https://www.awwwards.com/" target="_blank" rel="noopener noreferrer" class="">https://www.awwwards.com</a></td><td>全球最佳网页设计展示平台</td></tr></tbody></table>




















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Saaspo</td><td><a href="https://saaspo.com/" target="_blank" rel="noopener noreferrer" class="">https://saaspo.com</a></td><td>SaaS 仪表盘与 B2B 产品设计参考</td></tr><tr><td>Website Vice</td><td><a href="https://websitevice.com/" target="_blank" rel="noopener noreferrer" class="">https://websitevice.com</a></td><td>AI、SaaS 及 27 + 设计类资源库</td></tr></tbody></table>




















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Mobbin</td><td><a href="https://mobbin.com/" target="_blank" rel="noopener noreferrer" class="">https://mobbin.com</a></td><td>顶级 App 真实移动 UI 模式参考</td></tr><tr><td>Handheld Design</td><td><a href="https://handheld.design/" target="_blank" rel="noopener noreferrer" class="">https://handheld.design</a></td><td>移动 App 与响应式 UI 灵感</td></tr></tbody></table>















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Bento Grids</td><td><a href="https://bentogrids.com/" target="_blank" rel="noopener noreferrer" class="">https://bentogrids.com</a></td><td>结构化网格 UI 设计灵感</td></tr></tbody></table>















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Rebrand Gallery</td><td><a href="https://rebrand.gallery/" target="_blank" rel="noopener noreferrer" class="">https://rebrand.gallery</a></td><td>品牌重塑与转型视觉案例展示</td></tr></tbody></table>

























<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Landing Ninja</td><td><a href="https://landingninja.com/" target="_blank" rel="noopener noreferrer" class="">https://landingninja.com</a></td><td>高转化导向的落地页合集</td></tr><tr><td>One Page Love</td><td><a href="https://onepagelove.com/" target="_blank" rel="noopener noreferrer" class="">https://onepagelove.com</a></td><td>最佳单页网站设计灵感</td></tr><tr><td>Call to Inspiration</td><td><a href="https://callinspiration.com/" target="_blank" rel="noopener noreferrer" class="">https://callinspiration.com</a></td><td>高转化营销落地页案例</td></tr></tbody></table>















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Collect UI</td><td><a href="https://collectui.com/" target="_blank" rel="noopener noreferrer" class="">https://collectui.com</a></td><td>UI 组件与模式库</td></tr></tbody></table>















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>UI Movement</td><td><a href="https://uimovement.com/" target="_blank" rel="noopener noreferrer" class="">https://uimovement.com</a></td><td>交互动画 UI 设计合集</td></tr></tbody></table>















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Brutalist Websites</td><td><a href="https://brutalistwebsites.com/" target="_blank" rel="noopener noreferrer" class="">https://brutalistwebsites.com</a></td><td>大胆非传统的原始网页设计</td></tr></tbody></table>















<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Muzli</td><td><a href="https://muz.li/" target="_blank" rel="noopener noreferrer" class="">https://muz.li</a></td><td>实时设计灵感与 UI 趋势</td></tr></tbody></table>

























<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>Prettyfolio</td><td><a href="https://prettyfolio.co/" target="_blank" rel="noopener noreferrer" class="">https://prettyfolio.co</a></td><td>惊艳作品集设计中心</td></tr><tr><td>UI8</td><td><a href="https://ui8.net/" target="_blank" rel="noopener noreferrer" class="">https://ui8.net</a></td><td>设计师高级 UI 套件与模板</td></tr><tr><td>Pafolios</td><td><a href="https://pafolios.com/" target="_blank" rel="noopener noreferrer" class="">https://pafolios.com</a></td><td>创意人作品集设计灵感</td></tr></tbody></table>






































































<table><thead><tr><th>网站名称</th><th>网址</th><th>简单介绍</th></tr></thead><tbody><tr><td>21st.dev</td><td><a href="https://21st.dev/" target="_blank" rel="noopener noreferrer" class="">https://21st.dev</a></td><td>AI 驱动的 UI 组件工具</td></tr><tr><td><a href="https://tweak.cn/" target="_blank" rel="noopener noreferrer" class="">Tweak.cn</a></td><td><a href="https://tweak.cn/" target="_blank" rel="noopener noreferrer" class="">https://tweak.cn</a></td><td>shadcn/ui 主题编辑器与生成器</td></tr><tr><td>Magic UI Pro</td><td><a href="https://magicui.design/" target="_blank" rel="noopener noreferrer" class="">https://magicui.design</a></td><td>高级动画 UI 组件与模板</td></tr><tr><td>A11Y UI Design System</td><td><a href="https://a11yui.design/" target="_blank" rel="noopener noreferrer" class="">https://a11yui.design</a></td><td>无障碍 UI 设计系统</td></tr><tr><td>1000+ Gradients</td><td><a href="https://gradients.ac/" target="_blank" rel="noopener noreferrer" class="">https://gradients.ac</a></td><td>渐变与 AI 生成背景</td></tr><tr><td>Aceternity UI</td><td><a href="https://aceternity.com/" target="_blank" rel="noopener noreferrer" class="">https://aceternity.com</a></td><td>Tailwind + React 动画 UI 组件</td></tr><tr><td>Radix Primitives</td><td><a href="https://www.radix-ui.com/" target="_blank" rel="noopener noreferrer" class="">https://www.radix-ui.com</a></td><td>低可访问 UI 基元</td></tr><tr><td>shadcn/ui</td><td><a href="https://ui.shadcn.com/" target="_blank" rel="noopener noreferrer" class="">https://ui.shadcn.com</a></td><td>可自定义的 React 组件库</td></tr><tr><td>Curated UI</td><td><a href="https://curated.design/" target="_blank" rel="noopener noreferrer" class="">https://curated.design</a></td><td>无障碍 React 组件库</td></tr><tr><td>HeroUI</td><td><a href="https://heroui.com/" target="_blank" rel="noopener noreferrer" class="">https://heroui.com</a></td><td>美丽、快速、现代的 React UI 库</td></tr><tr><td>Tailwind CSS Component Library</td><td><a href="https://tailwindcss.com/" target="_blank" rel="noopener noreferrer" class="">https://tailwindcss.com</a></td><td>Tailwind CSS 组件库</td></tr><tr><td>MUI</td><td><a href="https://mui.com/" target="_blank" rel="noopener noreferrer" class="">https://mui.com</a></td><td>流行的 React 组件库</td></tr></tbody></table>
<p>颜色风格账号
<a href="https://www.xiaohongshu.com/user/profile/5ef858ba0000000001003dc7?xsec_token=ABj8LU-J-9AQilEH7bb3_gygAmii8En2mdVS7JYQ1krQk=&amp;xsec_source=pc_note&amp;tab=note&amp;subTab=note" target="_blank" rel="noopener noreferrer" class="">HHDesign - 小红书</a></p>
<p>常见中西文字体
<a href="https://blog.csdn.net/bigbear00007/article/details/102173641" target="_blank" rel="noopener noreferrer" class="">常用中西文字体概览-CSDN博客</a></p>
<p>色彩配色
高级配色搭配1</p>
<div class="language-shell codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-shell codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">hex</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">背景色调：070707</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">其他可选颜色：40a3cc、128c9f、574433、0e63a3</span><br></div></code></pre></div></div>
<p>你是一个资深的UI设计师，在色彩搭配上给人一种舒服且高级的感觉，当前我需要一个博客网站，我会给你excalidraw的线图，图中给出了ui元素的大致布局和一些基本信息，你需要借鉴线图进行设计，同时我会给出允许使用的中文字体和西文字体以及允许使用的颜色，你只能在允许的范围内进行设计：
中文字体：宋体
西文字体：times new roman
允许使用的颜色（hex值）：
背景色调：070707
其他可选颜色：40a3cc、128c9f、574433、0e63a3</p>
<p>标签：#ai-coding #model-serving</p>]]></content>
        <category label="AI Coding Assistants" term="AI Coding Assistants"/>
        <category label="Model & Inference Platform" term="Model & Inference Platform"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[上下文工程与 Agent 笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/上下文工程与Agent笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/上下文工程与Agent笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[2026 年工业级 Context Engineering + Agent 系统：Prompt Engineering vs Context Engineering 边界、四大策略（Write/Select/Compress/Isolate）、Manus 六条工程经验、Anthropic Building Effective Agents 五种 Workflow、8 大 Agent 框架对比（LangGraph / CrewAI / AutoGen / Smolagents / Letta / Pydantic AI / Mastra / Agno）、Memory 系统（Mem0 / Letta / Zep）、MCP 生态、20 类上下文工程常见问题精炼。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p><strong>本文目的</strong>：替换 <code>上下文工程异常问题总结</code> 原笔记（原 557 行 20 类问题，内容质量尚可但缺 Prompt Engineering vs Context Engineering 边界、Manus 经验、Agent 框架对比、Memory 系统、MCP，已删除）。覆盖 2026 年工业级 Context Engineering + Agent 全栈。
配套笔记：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/rag/rag-industrial-solutions">RAG工业方案笔记</a>、<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/prompt-engineering">Prompt工程笔记</a>、<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/rag/rerank">Rerank笔记</a>
配套 demo：<a href="https://github.com/HiRidgewalker/soft-tech-notebook/tree/main/example/llm-demo/04_rag_evaluation" target="_blank" rel="noopener noreferrer" class="">example/llm-demo/04_rag_evaluation</a></p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="阅读地图">阅读地图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#%E9%98%85%E8%AF%BB%E5%9C%B0%E5%9B%BE" class="hash-link" aria-label="阅读地图的直接链接" title="阅读地图的直接链接" translate="no">​</a></h2>























































<table><thead><tr><th>§</th><th>主题</th><th>一句话定位</th></tr></thead><tbody><tr><td>1</td><td>Prompt Engineering vs Context Engineering</td><td>Karpathy 定义 + 4 维度对比</td></tr><tr><td>2</td><td>Context Engineering 四大策略</td><td>Write / Select / Compress / Isolate</td></tr><tr><td>3</td><td>Manus 六条工程经验</td><td>KV-cache / Mask / 文件系统 / Recitation / 保留错误 / 反模式化</td></tr><tr><td>4</td><td>Anthropic Building Effective Agents</td><td>5 种 Workflow + Tool = ACI + 透明性 &gt; 智能</td></tr><tr><td>5</td><td>Agent 框架对比</td><td>8 大框架（LangGraph / CrewAI / AutoGen / Smolagents / Letta / Pydantic AI / Mastra / Agno）</td></tr><tr><td>6</td><td>记忆系统</td><td>Mem0 / Letta / Zep 对比 + 向量 vs 结构化</td></tr><tr><td>7</td><td>上下文工程常见问题（精炼原 20 类）</td><td>Context Rot / Pollution / Missing / Conflict / Overload / Lost-in-the-Middle 等</td></tr><tr><td>8</td><td>MCP 与工具调用</td><td>Model Context Protocol 生态 + 与 Function Calling 差异</td></tr><tr><td>9</td><td>来源链接</td><td>全部 GitHub 链接按章节分组</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-prompt-engineering-vs-context-engineering">1. Prompt Engineering vs Context Engineering<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#1-prompt-engineering-vs-context-engineering" class="hash-link" aria-label="1. Prompt Engineering vs Context Engineering的直接链接" title="1. Prompt Engineering vs Context Engineering的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-karpathy-的定义">1.1 Karpathy 的定义<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#11-karpathy-%E7%9A%84%E5%AE%9A%E4%B9%89" class="hash-link" aria-label="1.1 Karpathy 的定义的直接链接" title="1.1 Karpathy 的定义的直接链接" translate="no">​</a></h3>
<blockquote>
<p>"Context engineering is the delicate art and science of filling the context window with just the right information for the next step." — Andrej Karpathy（2025）</p>
</blockquote>
<p>Cognition（Devin 团队）补充："构建 AI agent 工程师的 #1 工作"。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-4-维度对比">1.2 4 维度对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#12-4-%E7%BB%B4%E5%BA%A6%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="1.2 4 维度对比的直接链接" title="1.2 4 维度对比的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>维度</th><th>Prompt Engineering</th><th>Context Engineering</th></tr></thead><tbody><tr><td><strong>关注对象</strong></td><td>system / user 指令本身</td><td>整个 context window：instructions + knowledge + tools + 历史 + 反馈</td></tr><tr><td><strong>时间尺度</strong></td><td>写一次</td><td>每次推理都在动态管理</td></tr><tr><td><strong>典型动作</strong></td><td>改写 prompt、加 few-shot</td><td>write / select / compress / isolate 四类策略</td></tr><tr><td><strong>适用对象</strong></td><td>单次 LLM 调用</td><td>长链路 Agent（Manus 平均 50 次工具调用）</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-演进关系">1.3 演进关系<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#13-%E6%BC%94%E8%BF%9B%E5%85%B3%E7%B3%BB" class="hash-link" aria-label="1.3 演进关系的直接链接" title="1.3 演进关系的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">Prompt Engineering（写指令）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Context Engineering（管理整个 context window）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Agent Engineering（编排多步推理 + 工具调用 + 记忆 + 多 agent 协作）</span><br></div></code></pre></div></div>
<p><strong>结论</strong>：Prompt Engineering 是基础；Context Engineering 是中间层；Agent Engineering 是工业级落地的全集。三者层层递进，不是替代关系。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-context-engineering-四大策略langchain-总结">2. Context Engineering 四大策略（LangChain 总结）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#2-context-engineering-%E5%9B%9B%E5%A4%A7%E7%AD%96%E7%95%A5langchain-%E6%80%BB%E7%BB%93" class="hash-link" aria-label="2. Context Engineering 四大策略（LangChain 总结）的直接链接" title="2. Context Engineering 四大策略（LangChain 总结）的直接链接" translate="no">​</a></h2>
<p>参考：<a href="https://www.langchain.com/blog/context-engineering-for-agents" target="_blank" rel="noopener noreferrer" class="">Context Engineering for Agents</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="21-write写">2.1 Write（写）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#21-write%E5%86%99" class="hash-link" aria-label="2.1 Write（写）的直接链接" title="2.1 Write（写）的直接链接" translate="no">​</a></h3>
<p>把信息写进 context window，让模型"看到"。</p>






























<table><thead><tr><th>手段</th><th>作用</th><th>何时用</th></tr></thead><tbody><tr><td><strong>Scratchpad</strong>（轮内笔记）</td><td>Agent 在每步写 notes，沉淀当前推理</td><td>ReAct / Plan-and-Execute</td></tr><tr><td><strong>Memory</strong>（跨会话笔记）</td><td>长期记忆用户偏好 / 项目状态</td><td>ChatGPT / Cursor / Windsurf 都用</td></tr><tr><td><strong>todo.md recitation</strong></td><td>每步重写 todo，把目标朗诵到 context 末端</td><td>Manus 风格长任务</td></tr><tr><td><strong>文件系统当 context</strong></td><td>128K 不够用 → 文件系统 = 无限、持久、可操作</td><td>Manus / Claude Code</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="22-select选">2.2 Select（选）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#22-select%E9%80%89" class="hash-link" aria-label="2.2 Select（选）的直接链接" title="2.2 Select（选）的直接链接" translate="no">​</a></h3>
<p>从大量候选中选出当前需要的，喂给模型。</p>






























<table><thead><tr><th>手段</th><th>作用</th><th>数据</th></tr></thead><tbody><tr><td><strong>Tool-RAG</strong></td><td>工具太多时，先 RAG 出当前需要的工具</td><td>LangChain 实测：工具选择准确率提升 <strong>3×</strong></td></tr><tr><td><strong>Memory retrieval</strong></td><td>从长期记忆库 RAG 出相关记忆</td><td>Mem0 / Letta</td></tr><tr><td><strong>Context RAG</strong></td><td>从文档库 RAG 出相关 context</td><td>RAG 完整链路</td></tr><tr><td><strong>Episodic / Procedural / Semantic memory</strong></td><td>三类记忆分层检索</td><td>Letta / Zep</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="23-compress压">2.3 Compress（压）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#23-compress%E5%8E%8B" class="hash-link" aria-label="2.3 Compress（压）的直接链接" title="2.3 Compress（压）的直接链接" translate="no">​</a></h3>
<p>当 context 接近上限时，压缩信息以腾出空间。</p>






























<table><thead><tr><th>手段</th><th>作用</th><th>何时用</th></tr></thead><tbody><tr><td><strong>Summarization</strong></td><td>长对话压缩成摘要</td><td>Claude Code 在 95% 容量自动 compact</td></tr><tr><td><strong>Trimming</strong></td><td>直接裁掉不重要的历史 token</td><td>滑动窗口</td></tr><tr><td><strong>LLM-based compression</strong></td><td>用 LLM 重新组织 context</td><td>关键信息提取</td></tr><tr><td><strong>Token-level pruning</strong></td><td>按 attention 权重剪枝</td><td>实验性</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="24-isolate隔">2.4 Isolate（隔）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#24-isolate%E9%9A%94" class="hash-link" aria-label="2.4 Isolate（隔）的直接链接" title="2.4 Isolate（隔）的直接链接" translate="no">​</a></h3>
<p>把上下文隔离到不同 agent / sandbox，避免互相污染。</p>






























<table><thead><tr><th>手段</th><th>作用</th><th>何时用</th></tr></thead><tbody><tr><td><strong>Multi-agent</strong></td><td>主 agent + sub-agent，每个只看自己的 context</td><td>Anthropic research 用并行 sub-agent</td></tr><tr><td><strong>Sandbox</strong></td><td>Agent 工具调用隔离在 sandbox</td><td>HuggingFace CodeAgent 用 e2b</td></tr><tr><td><strong>Per-node selection</strong></td><td>LangGraph 每个 node 独立选择 context</td><td>复杂 workflow</td></tr><tr><td><strong>Thread state</strong></td><td>每个 thread 独立 state</td><td>LangGraph thread</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="25-四大策略与-langgraph--claude-code-的对应">2.5 四大策略与 LangGraph / Claude Code 的对应<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#25-%E5%9B%9B%E5%A4%A7%E7%AD%96%E7%95%A5%E4%B8%8E-langgraph--claude-code-%E7%9A%84%E5%AF%B9%E5%BA%94" class="hash-link" aria-label="2.5 四大策略与 LangGraph / Claude Code 的对应的直接链接" title="2.5 四大策略与 LangGraph / Claude Code 的对应的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>策略</th><th>LangGraph 实现</th><th>Claude Code 实现</th></tr></thead><tbody><tr><td><strong>Write</strong></td><td>thread state + 持久化</td><td>scratchpad + memory</td></tr><tr><td><strong>Select</strong></td><td>per-node selection</td><td>tool-RAG</td></tr><tr><td><strong>Compress</strong></td><td>built-in 摘要 / trimming</td><td>95% 自动 compact</td></tr><tr><td><strong>Isolate</strong></td><td>multi-agent / sandbox</td><td>sub-agent</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-manus-六条工程经验">3. Manus 六条工程经验<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#3-manus-%E5%85%AD%E6%9D%A1%E5%B7%A5%E7%A8%8B%E7%BB%8F%E9%AA%8C" class="hash-link" aria-label="3. Manus 六条工程经验的直接链接" title="3. Manus 六条工程经验的直接链接" translate="no">​</a></h2>
<p>参考：<a href="https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus" target="_blank" rel="noopener noreferrer" class="">Manus: Context Engineering for AI Agents</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-kv-cache-设计最重要的指标">3.1 KV-cache 设计（最重要的指标）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#31-kv-cache-%E8%AE%BE%E8%AE%A1%E6%9C%80%E9%87%8D%E8%A6%81%E7%9A%84%E6%8C%87%E6%A0%87" class="hash-link" aria-label="3.1 KV-cache 设计（最重要的指标）的直接链接" title="3.1 KV-cache 设计（最重要的指标）的直接链接" translate="no">​</a></h3>
<blockquote>
<p><strong>缓存命中率 = 生产 agent 最重要指标</strong></p>
</blockquote>

























<table><thead><tr><th>指标</th><th>数值</th></tr></thead><tbody><tr><td>Manus 平均输入输出比</td><td>100:1</td></tr><tr><td>Cached input（Claude Sonnet）</td><td>$0.30 / MTok</td></tr><tr><td>Uncached input</td><td>$3 / MTok</td></tr><tr><td>价格差</td><td><strong>10×</strong></td></tr></tbody></table>
<p><strong>核心原则</strong>：</p>
<ul>
<li class="">稳定 prompt prefix → 提高 cache 命中率</li>
<li class="">避免在 prompt 中插入时间戳 / 随机 ID（破坏 cache）</li>
<li class="">把可变部分放在 prompt 末尾</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-mask-而不是-remove">3.2 Mask 而不是 Remove<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#32-mask-%E8%80%8C%E4%B8%8D%E6%98%AF-remove" class="hash-link" aria-label="3.2 Mask 而不是 Remove的直接链接" title="3.2 Mask 而不是 Remove的直接链接" translate="no">​</a></h3>
<p>动态增删 tool 会废掉 KV-cache。改用：</p>
<ul>
<li class=""><strong>State machine</strong>：固定 tool 列表，通过状态控制是否可用</li>
<li class=""><strong>Logit masking</strong>：在生成阶段 mask 掉非法 token</li>
<li class=""><strong>Response prefill</strong>：assistant 消息前缀引导生成方向</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-文件系统当-context">3.3 文件系统当 Context<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#33-%E6%96%87%E4%BB%B6%E7%B3%BB%E7%BB%9F%E5%BD%93-context" class="hash-link" aria-label="3.3 文件系统当 Context的直接链接" title="3.3 文件系统当 Context的直接链接" translate="no">​</a></h3>
<ul>
<li class="">128K 不够用 → 文件系统 = 无限、持久、可操作的外部记忆</li>
<li class="">Agent 可以 read / write / search 文件，突破 context window 限制</li>
<li class="">Claude Code / Manus / Devin 都重度依赖文件系统</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="34-recitation-对抗注意力漂移">3.4 Recitation 对抗注意力漂移<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#34-recitation-%E5%AF%B9%E6%8A%97%E6%B3%A8%E6%84%8F%E5%8A%9B%E6%BC%82%E7%A7%BB" class="hash-link" aria-label="3.4 Recitation 对抗注意力漂移的直接链接" title="3.4 Recitation 对抗注意力漂移的直接链接" translate="no">​</a></h3>
<ul>
<li class="">每步重写 <code>todo.md</code>，把目标朗诵到 context 末端</li>
<li class="">防止"lost in the middle"——长 context 末尾信息更容易被关注</li>
<li class="">与 Anthropic 的 extended thinking 同源</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="35-保留错误">3.5 保留错误<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#35-%E4%BF%9D%E7%95%99%E9%94%99%E8%AF%AF" class="hash-link" aria-label="3.5 保留错误的直接链接" title="3.5 保留错误的直接链接" translate="no">​</a></h3>
<blockquote>
<p>删除失败记录 = 抹掉模型需要用来纠错的证据</p>
</blockquote>
<ul>
<li class="">错误日志、stacktrace、failed patches 都要保留</li>
<li class="">Agent 需要"知道自己哪里错了"才能调整</li>
<li class="">完整 DECISIONS.md / FAILED_ATTEMPTS.md / KNOWN_ISSUES.md</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="36-不要-few-shot-出模式化">3.6 不要 Few-shot 出模式化<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#36-%E4%B8%8D%E8%A6%81-few-shot-%E5%87%BA%E6%A8%A1%E5%BC%8F%E5%8C%96" class="hash-link" aria-label="3.6 不要 Few-shot 出模式化的直接链接" title="3.6 不要 Few-shot 出模式化的直接链接" translate="no">​</a></h3>
<ul>
<li class="">注入结构化变化（不同序列化、不同措辞、轻微噪声）打破模仿</li>
<li class="">否则模型会机械模仿示例，失去泛化能力</li>
<li class="">与 Anthropic 原则"示例胜于描述"形成互补</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-anthropic-building-effective-agents">4. Anthropic Building Effective Agents<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#4-anthropic-building-effective-agents" class="hash-link" aria-label="4. Anthropic Building Effective Agents的直接链接" title="4. Anthropic Building Effective Agents的直接链接" translate="no">​</a></h2>
<p>参考：<a href="https://www.anthropic.com/engineering/building-effective-agents" target="_blank" rel="noopener noreferrer" class="">Building Effective Agents</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-workflow--agent">4.1 Workflow &gt; Agent<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#41-workflow--agent" class="hash-link" aria-label="4.1 Workflow > Agent的直接链接" title="4.1 Workflow > Agent的直接链接" translate="no">​</a></h3>
<blockquote>
<p>能用 workflow 解决的，就不要上 Agent。</p>
</blockquote>
<p>5 种 Workflow（按复杂度递增）：</p>



































<table><thead><tr><th>Workflow</th><th>模式</th><th>何时用</th></tr></thead><tbody><tr><td><strong>Prompt chaining</strong></td><td>串行：步骤 1 → 步骤 2 → ... → 步骤 N</td><td>流水线任务，每步确定性强</td></tr><tr><td><strong>Routing</strong></td><td>分类后分流到不同子流程</td><td>多类型 query 分类处理</td></tr><tr><td><strong>Parallelization</strong></td><td>多任务并行 → 聚合结果</td><td>多个独立子问题</td></tr><tr><td><strong>Orchestrator-workers</strong></td><td>主 agent 拆解 → 多 worker 并行 → 聚合</td><td>复杂任务并行处理</td></tr><tr><td><strong>Evaluator-optimizer</strong></td><td>生成 → 评分 → 反馈 → 重生成</td><td>答案质量优先场景</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="42-tool--aciagent-computer-interface">4.2 Tool = ACI（Agent-Computer Interface）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#42-tool--aciagent-computer-interface" class="hash-link" aria-label="4.2 Tool = ACI（Agent-Computer Interface）的直接链接" title="4.2 Tool = ACI（Agent-Computer Interface）的直接链接" translate="no">​</a></h3>
<blockquote>
<p>Tool 描述要像产品 docstring，不是 API 签名。</p>
</blockquote>



































<table><thead><tr><th>维度</th><th>差的 tool 描述</th><th>好的 tool 描述</th></tr></thead><tbody><tr><td><strong>签名</strong></td><td><code>get_user(id)</code></td><td><code>get_user(id: str) → User</code></td></tr><tr><td><strong>示例</strong></td><td>无</td><td><code>get_user("u_123") → User(name="李雷", age=30)</code></td></tr><tr><td><strong>边界</strong></td><td>无</td><td>"id 必须是 string，若用户不存在抛 NotFoundError"</td></tr><tr><td><strong>错误处理</strong></td><td>无</td><td>"返回的 User 可能为 None，调用方需检查"</td></tr><tr><td><strong>Poka-yoke（防呆）</strong></td><td>无</td><td>"id 不能为空字符串，否则抛 ValueError"</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="43-透明性--智能">4.3 透明性 &gt; 智能<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#43-%E9%80%8F%E6%98%8E%E6%80%A7--%E6%99%BA%E8%83%BD" class="hash-link" aria-label="4.3 透明性 > 智能的直接链接" title="4.3 透明性 > 智能的直接链接" translate="no">​</a></h3>
<ul>
<li class="">让 agent 把计划显式写出来，用户能看见</li>
<li class="">不要让 agent 在暗处决策</li>
<li class="">Claude Code 的 todo list / Manus 的 todo.md 都是这个原则的体现</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="44-tool-投资回报率">4.4 Tool 投资回报率<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#44-tool-%E6%8A%95%E8%B5%84%E5%9B%9E%E6%8A%A5%E7%8E%87" class="hash-link" aria-label="4.4 Tool 投资回报率的直接链接" title="4.4 Tool 投资回报率的直接链接" translate="no">​</a></h3>
<blockquote>
<p>投资 tool 描述和工具测试的回报率，比调 prompt 高。</p>
</blockquote>
<ul>
<li class="">调 prompt 提升 5<del>10%，调 tool 描述提升 20</del>50%</li>
<li class="">每个 tool 都要有单元测试 + 集成测试</li>
<li class="">Anthropic 建议把 tool 视为产品来打磨</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-agent-框架对比">5. Agent 框架对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#5-agent-%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="5. Agent 框架对比的直接链接" title="5. Agent 框架对比的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-8-大框架">5.1 8 大框架<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#51-8-%E5%A4%A7%E6%A1%86%E6%9E%B6" class="hash-link" aria-label="5.1 8 大框架的直接链接" title="5.1 8 大框架的直接链接" translate="no">​</a></h3>













































































<table><thead><tr><th>框架</th><th>仓库</th><th>Stars</th><th>最新版本</th><th>定位</th><th>何时用</th></tr></thead><tbody><tr><td><strong>LangGraph</strong></td><td><a href="https://github.com/langchain-ai/langgraph" target="_blank" rel="noopener noreferrer" class="">langchain-ai/langgraph</a></td><td>—</td><td>持续发布</td><td>LangChain 主力 stateful graph；thread state + checkpoint</td><td>复杂 Agent + 多步推理</td></tr><tr><td><strong>CrewAI</strong></td><td><a href="https://github.com/crewAIInc/crewAI" target="_blank" rel="noopener noreferrer" class="">crewAIInc/crewAI</a></td><td>—</td><td>持续发布</td><td>Role-playing 多 agent 协作（Captain / Engineer / Researcher）</td><td>多 agent 角色扮演场景</td></tr><tr><td><strong>AutoGen</strong></td><td><a href="https://github.com/microsoft/autogen" target="_blank" rel="noopener noreferrer" class="">microsoft/autogen</a></td><td>—</td><td>v0.4+（重写后）</td><td>Microsoft 出品；群聊式 multi-agent</td><td>研究 / 多 agent 群聊</td></tr><tr><td><strong>Smolagents</strong></td><td><a href="https://github.com/huggingface/smolagents" target="_blank" rel="noopener noreferrer" class="">huggingface/smolagents</a></td><td>—</td><td>持续发布</td><td>HuggingFace 出品；极简 + code agent + sandbox (e2b)</td><td>轻量 code agent</td></tr><tr><td><strong>Letta</strong>（原 MemGPT）</td><td><a href="https://github.com/letta-ai/letta" target="_blank" rel="noopener noreferrer" class="">letta-ai/letta</a></td><td>—</td><td>持续发布</td><td>带长期记忆的 agent；core memory + archival memory</td><td>需要持久记忆的 agent</td></tr><tr><td><strong>Pydantic AI</strong></td><td><a href="https://github.com/pydantic/pydantic-ai" target="_blank" rel="noopener noreferrer" class="">pydantic/pydantic-ai</a></td><td>—</td><td>持续发布</td><td>Pydantic 官方；FastAPI 风格；强类型</td><td>Python 后端 + 强类型</td></tr><tr><td><strong>Mastra</strong></td><td><a href="https://github.com/mastra-ai/mastra" target="_blank" rel="noopener noreferrer" class="">mastra-ai/mastra</a></td><td>—</td><td>持续发布</td><td>TypeScript Agent 框架；workflow + RAG + MCP</td><td>Node.js / TS 技术栈</td></tr><tr><td><strong>Agno</strong>（原 Fixpoint）</td><td><a href="https://github.com/agno-agi/agno" target="_blank" rel="noopener noreferrer" class="">agno-agi/agno</a></td><td>—</td><td>持续发布</td><td>高性能多模态 agent；速度比 LangGraph 快 10×</td><td>高性能 + 多模态场景</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-各框架核心差异">5.2 各框架核心差异<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#52-%E5%90%84%E6%A1%86%E6%9E%B6%E6%A0%B8%E5%BF%83%E5%B7%AE%E5%BC%82" class="hash-link" aria-label="5.2 各框架核心差异的直接链接" title="5.2 各框架核心差异的直接链接" translate="no">​</a></h3>













































































<table><thead><tr><th>框架</th><th>核心抽象</th><th>多 agent</th><th>记忆系统</th><th>Tool 生态</th><th>学习曲线</th></tr></thead><tbody><tr><td><strong>LangGraph</strong></td><td>StateGraph + Node + Edge</td><td>✅ subgraph</td><td>外部（MemoryStore / Zep）</td><td>LangChain 全套</td><td>中（要理解 graph 概念）</td></tr><tr><td><strong>CrewAI</strong></td><td>Crew + Agent + Task</td><td>✅ 内建（role-based）</td><td>外部</td><td>自定义 + LangChain</td><td>低（role 直观）</td></tr><tr><td><strong>AutoGen</strong></td><td>UserProxyAgent + AssistantAgent</td><td>✅ 内建（群聊）</td><td>外部</td><td>自定义</td><td>中（要理解群聊协议）</td></tr><tr><td><strong>Smolagents</strong></td><td>CodeAgent + Tool</td><td>⚠️ 简单</td><td>无（自带 file system）</td><td>自定义</td><td>低（极简）</td></tr><tr><td><strong>Letta</strong></td><td>Agent + Memory Blocks</td><td>✅ 内建</td><td>✅ 内建（core + archival）</td><td>自定义</td><td>中（记忆模型特殊）</td></tr><tr><td><strong>Pydantic AI</strong></td><td>Agent + Deps + Result</td><td>⚠️ 简单</td><td>外部</td><td>自定义 + MCP</td><td>低（Pydantic 风格）</td></tr><tr><td><strong>Mastra</strong></td><td>Agent + Workflow + Tool</td><td>✅ 内建</td><td>外部</td><td>MCP + 自定义</td><td>低（TS 友好）</td></tr><tr><td><strong>Agno</strong></td><td>Agent + Team + Workflow</td><td>✅ 内建（Team）</td><td>外部</td><td>MCP + 自定义</td><td>中</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-选型决策">5.3 选型决策<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#53-%E9%80%89%E5%9E%8B%E5%86%B3%E7%AD%96" class="hash-link" aria-label="5.3 选型决策的直接链接" title="5.3 选型决策的直接链接" translate="no">​</a></h3>









































<table><thead><tr><th>场景</th><th>推荐</th></tr></thead><tbody><tr><td><strong>Python + LangChain 生态</strong></td><td>LangGraph（首选）</td></tr><tr><td><strong>多 agent 角色扮演</strong></td><td>CrewAI（直观）</td></tr><tr><td><strong>群聊式 multi-agent</strong></td><td>AutoGen（学术 / 研究）</td></tr><tr><td><strong>轻量 code agent</strong></td><td>Smolagents（极简）</td></tr><tr><td><strong>需要长期记忆</strong></td><td>Letta（自带 memory）</td></tr><tr><td><strong>强类型 + FastAPI 后端</strong></td><td>Pydantic AI</td></tr><tr><td><strong>TypeScript / Node.js</strong></td><td>Mastra</td></tr><tr><td><strong>高性能 + 多模态</strong></td><td>Agno</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-记忆系统">6. 记忆系统<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#6-%E8%AE%B0%E5%BF%86%E7%B3%BB%E7%BB%9F" class="hash-link" aria-label="6. 记忆系统的直接链接" title="6. 记忆系统的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-三大记忆框架对比">6.1 三大记忆框架对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#61-%E4%B8%89%E5%A4%A7%E8%AE%B0%E5%BF%86%E6%A1%86%E6%9E%B6%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="6.1 三大记忆框架对比的直接链接" title="6.1 三大记忆框架对比的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>框架</th><th>仓库</th><th>核心机制</th><th>何时用</th></tr></thead><tbody><tr><td><strong>Mem0</strong></td><td><a href="https://github.com/mem0ai/mem0" target="_blank" rel="noopener noreferrer" class="">mem0ai/mem0</a></td><td>向量 + 结构化双层记忆；自动 extract / update / delete</td><td>通用 agent 记忆；生产稳定</td></tr><tr><td><strong>Letta</strong>（原 MemGPT）</td><td><a href="https://github.com/letta-ai/letta" target="_blank" rel="noopener noreferrer" class="">letta-ai/letta</a></td><td>Core memory（in-context）+ Archival memory（向量）；core memory 会自动压缩 + 滚动</td><td>长对话 + 角色一致性</td></tr><tr><td><strong>Zep</strong></td><td><a href="https://github.com/getzep/zep" target="_blank" rel="noopener noreferrer" class="">getzep/zep</a></td><td>生产级长期记忆服务；Graphiti 时序知识图谱 + 语义搜索</td><td>企业级 + 多用户记忆</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-向量记忆-vs-结构化记忆">6.2 向量记忆 vs 结构化记忆<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#62-%E5%90%91%E9%87%8F%E8%AE%B0%E5%BF%86-vs-%E7%BB%93%E6%9E%84%E5%8C%96%E8%AE%B0%E5%BF%86" class="hash-link" aria-label="6.2 向量记忆 vs 结构化记忆的直接链接" title="6.2 向量记忆 vs 结构化记忆的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>维度</th><th>向量记忆</th><th>结构化记忆</th></tr></thead><tbody><tr><td><strong>存储</strong></td><td>Embedding + metadata</td><td>表 / KV / 知识图谱</td></tr><tr><td><strong>检索</strong></td><td>相似度</td><td>精确查询 / 关系查询</td></tr><tr><td><strong>可解释性</strong></td><td>低（黑盒）</td><td>高（可读）</td></tr><tr><td><strong>更新成本</strong></td><td>中（重建索引）</td><td>低（直接改）</td></tr><tr><td><strong>适用场景</strong></td><td>模糊匹配 / 语义搜索</td><td>精确状态 / 关系推理</td></tr></tbody></table>
<p><strong>2026 主流</strong>：<strong>向量 + 结构化双层</strong>（Mem0 模式）。语义记忆走向量，状态 / 关系走结构化。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-memory-设计模式">6.3 Memory 设计模式<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#63-memory-%E8%AE%BE%E8%AE%A1%E6%A8%A1%E5%BC%8F" class="hash-link" aria-label="6.3 Memory 设计模式的直接链接" title="6.3 Memory 设计模式的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>Tier 1：Core / Working Memory</strong>：放 context window 内；用户偏好、当前任务状态</li>
<li class=""><strong>Tier 2：Episodic Memory</strong>：历史事件；按时间序列存储</li>
<li class=""><strong>Tier 3：Semantic Memory</strong>：事实知识；走向量 RAG</li>
<li class=""><strong>Tier 4：Procedural Memory</strong>：技能 / 工具调用模板</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-上下文工程常见问题精炼原-20-类">7. 上下文工程常见问题（精炼原 20 类）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#7-%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E7%B2%BE%E7%82%BC%E5%8E%9F-20-%E7%B1%BB" class="hash-link" aria-label="7. 上下文工程常见问题（精炼原 20 类）的直接链接" title="7. 上下文工程常见问题（精炼原 20 类）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-核心问题清单按影响排序">7.1 核心问题清单（按影响排序）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#71-%E6%A0%B8%E5%BF%83%E9%97%AE%E9%A2%98%E6%B8%85%E5%8D%95%E6%8C%89%E5%BD%B1%E5%93%8D%E6%8E%92%E5%BA%8F" class="hash-link" aria-label="7.1 核心问题清单（按影响排序）的直接链接" title="7.1 核心问题清单（按影响排序）的直接链接" translate="no">​</a></h3>



































































































































<table><thead><tr><th>#</th><th>问题</th><th>核心含义</th><th>解决方案</th></tr></thead><tbody><tr><td>1</td><td><strong>Context Rot</strong> 上下文腐烂</td><td>上下文长期积累后变旧、变乱、变矛盾</td><td>定期 compact；维护 CURRENT_STATE.md</td></tr><tr><td>2</td><td><strong>Context Pollution</strong> 上下文污染</td><td>错误、无关、过期信息进入上下文</td><td>输入过滤 + 来源标注</td></tr><tr><td>3</td><td><strong>Context Missing</strong> 上下文缺失</td><td>模型没拿到完成任务所需信息</td><td>提供 SPEC.md + DATABASE_SCHEMA.md 等结构化文档</td></tr><tr><td>4</td><td><strong>Context Conflict</strong> 上下文冲突</td><td>多个信息源互相矛盾</td><td>明确优先级：用户最新指令 &gt; CURRENT_STATE.md &gt; SPEC.md &gt; README &gt; 历史对话</td></tr><tr><td>5</td><td><strong>Context Overload</strong> 上下文过载</td><td>信息太多，模型有效利用能力下降</td><td>任务级裁剪 + 摘要 + 分层</td></tr><tr><td>6</td><td><strong>Lost in the Middle</strong></td><td>长上下文中间信息被忽略</td><td>关键信息放开头 / 末尾；用 XML tags 标记</td></tr><tr><td>7</td><td><strong>State Drift</strong> 状态漂移</td><td>模型理解和真实项目状态不一致</td><td>Agent 重新扫描文件 + git worktree 隔离</td></tr><tr><td>8</td><td><strong>Requirement Drift</strong> 需求漂移</td><td>实现逐渐偏离最初目标</td><td>维护 requirements.md / out_of_scope.md / change_log.md</td></tr><tr><td>9</td><td><strong>RAG Pollution</strong> 检索污染</td><td>检索到错误或过期资料</td><td>区分 docs/archived 与 docs/current + 过滤</td></tr><tr><td>10</td><td><strong>Summary Distortion</strong> 摘要失真</td><td>长上下文压缩后丢失关键约束</td><td>人工校验摘要 + 保留原始 + 元数据标记</td></tr><tr><td>11</td><td><strong>Tool-State Desync</strong> 工具状态不同步</td><td>Agent 看到的文件/分支/环境和真实执行环境不一致</td><td>patch 验证 + git worktree + 状态文件</td></tr><tr><td>12</td><td><strong>Memory Pollution</strong> 记忆污染</td><td>长期记忆保存了不再准确的信息</td><td>记忆加 TTL + 定期审计 + 来源标注</td></tr><tr><td>13</td><td><strong>Prompt Bloat</strong> Prompt 膨胀</td><td>不断往 prompt 加规则，最后臃肿</td><td>定期清理 + 分场景 prompt + 动态加载</td></tr><tr><td>14</td><td><strong>Format Collapse</strong> 格式崩坏</td><td>上下文复杂后开始破坏格式</td><td>结构化输出（Instructor）+ schema 校验</td></tr><tr><td>15</td><td><strong>Task Boundary Leakage</strong> 任务边界失控</td><td>模型把当前任务以外的事情也一起做</td><td>明确 Allowed Changes / Forbidden Changes</td></tr><tr><td>16</td><td><strong>Source of Truth Missing</strong> 事实源不明确</td><td>没有告诉模型哪个文件是事实源</td><td>明确优先级：CURRENT_STATE.md &gt; SPEC.md &gt; ...</td></tr><tr><td>17</td><td><strong>Failed Attempt Residue</strong> 历史失败残留</td><td>之前失败的实现路径留在上下文里，模型重复尝试</td><td>维护 DECISIONS.md / FAILED_ATTEMPTS.md</td></tr><tr><td>18</td><td><strong>Multi-Agent Context Inconsistency</strong> 多 Agent 上下文不一致</td><td>多 agent 协作时各自拿到的上下文不一致</td><td>共享状态文件 + 主 agent 同步</td></tr><tr><td>19</td><td><strong>Instruction Hierarchy Confusion</strong> 指令层级混乱</td><td>模型不知道哪些指令优先级最高</td><td>明确规则：安全 &gt; 用户最新 &gt; spec &gt; 任务 &gt; 历史</td></tr><tr><td>20</td><td><strong>Implicit Assumption Accumulation</strong> 隐式假设累积</td><td>模型在没有确认的情况下做了假设，后续沿用</td><td>假设必须落到 spec 文件，不允许隐式</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-核心原则">7.2 核心原则<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#72-%E6%A0%B8%E5%BF%83%E5%8E%9F%E5%88%99" class="hash-link" aria-label="7.2 核心原则的直接链接" title="7.2 核心原则的直接链接" translate="no">​</a></h3>
<blockquote>
<p><strong>不要依赖对话历史维持项目状态，要把项目状态沉淀到结构化文档里，并明确事实源、优先级、当前任务和变更记录。</strong></p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-mcp-与工具调用">8. MCP 与工具调用<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#8-mcp-%E4%B8%8E%E5%B7%A5%E5%85%B7%E8%B0%83%E7%94%A8" class="hash-link" aria-label="8. MCP 与工具调用的直接链接" title="8. MCP 与工具调用的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-mcp-概述">8.1 MCP 概述<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#81-mcp-%E6%A6%82%E8%BF%B0" class="hash-link" aria-label="8.1 MCP 概述的直接链接" title="8.1 MCP 概述的直接链接" translate="no">​</a></h3>
<p><a href="https://modelcontextprotocol.io/" target="_blank" rel="noopener noreferrer" class="">Model Context Protocol（MCP）</a> 是 Anthropic 2024 年开源的开放标准，让 LLM 应用与外部工具 / 数据源标准化连接。</p>





























<table><thead><tr><th>项目信息</th><th>数值</th></tr></thead><tbody><tr><td>发布时间</td><td>2024-11</td></tr><tr><td>当前版本</td><td>持续演进（2026 已是事实标准）</td></tr><tr><td>官方 server 数</td><td>100+</td></tr><tr><td>生态 server 数</td><td>1000+（社区贡献）</td></tr><tr><td>支持客户端</td><td>Claude Desktop / Claude Code / Cursor / Windsurf / Cline / Continue / ...</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-mcp-vs-openai-function-calling-vs-anthropic-tool-use">8.2 MCP vs OpenAI Function Calling vs Anthropic Tool Use<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#82-mcp-vs-openai-function-calling-vs-anthropic-tool-use" class="hash-link" aria-label="8.2 MCP vs OpenAI Function Calling vs Anthropic Tool Use的直接链接" title="8.2 MCP vs OpenAI Function Calling vs Anthropic Tool Use的直接链接" translate="no">​</a></h3>















































<table><thead><tr><th>维度</th><th>OpenAI Function Calling</th><th>Anthropic Tool Use</th><th>MCP</th></tr></thead><tbody><tr><td><strong>定位</strong></td><td>模型能力</td><td>模型能力</td><td><strong>协议标准</strong></td></tr><tr><td><strong>范围</strong></td><td>单次调用</td><td>单次调用</td><td><strong>跨工具、跨应用、跨模型</strong></td></tr><tr><td><strong>生态</strong></td><td>OpenAI 独占</td><td>Anthropic 独占</td><td><strong>开放，任何人都能实现 server/client</strong></td></tr><tr><td><strong>Tool 定义</strong></td><td>JSON Schema</td><td>JSON Schema</td><td>JSON Schema + MCP 协议</td></tr><tr><td><strong>状态管理</strong></td><td>无</td><td>无</td><td>✅ session / progress / cancellation</td></tr><tr><td><strong>多模态</strong></td><td>⚠️ 部分</td><td>⚠️ 部分</td><td>✅ 完整支持</td></tr></tbody></table>
<p><strong>结论</strong>：MCP 是工业级 Tool Use 的标准协议，2026 年已成为事实标准。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="83-mcp-生态2026">8.3 MCP 生态（2026）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#83-mcp-%E7%94%9F%E6%80%812026" class="hash-link" aria-label="8.3 MCP 生态（2026）的直接链接" title="8.3 MCP 生态（2026）的直接链接" translate="no">​</a></h3>









































<table><thead><tr><th>类别</th><th>代表 server</th></tr></thead><tbody><tr><td><strong>文件 / 代码</strong></td><td>Filesystem / Git / GitHub / GitLab</td></tr><tr><td><strong>数据库</strong></td><td>PostgreSQL / SQLite / MySQL / MongoDB</td></tr><tr><td><strong>搜索</strong></td><td>Brave Search / Tavily / Google</td></tr><tr><td><strong>协作</strong></td><td>Slack / Notion / Linear / Jira / Confluence</td></tr><tr><td><strong>云</strong></td><td>AWS / GCP / Azure / Cloudflare</td></tr><tr><td><strong>浏览器</strong></td><td>Playwright / Puppeteer</td></tr><tr><td><strong>AI / ML</strong></td><td>HuggingFace / Replicate</td></tr><tr><td><strong>生产工具</strong></td><td>Sentry / Datadog / Grafana</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="84-mcp-适用场景">8.4 MCP 适用场景<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#84-mcp-%E9%80%82%E7%94%A8%E5%9C%BA%E6%99%AF" class="hash-link" aria-label="8.4 MCP 适用场景的直接链接" title="8.4 MCP 适用场景的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>场景</th><th>是否用 MCP</th></tr></thead><tbody><tr><td><strong>Claude Desktop / Claude Code 集成第三方工具</strong></td><td>✅ 强烈推荐</td></tr><tr><td><strong>多模型统一接入一套工具</strong></td><td>✅ 强烈推荐</td></tr><tr><td><strong>企业内部工具标准化</strong></td><td>✅ 强烈推荐</td></tr><tr><td><strong>简单一次性工具调用</strong></td><td>❌ 直接用 Function Calling</td></tr><tr><td><strong>OpenAI-only 场景</strong></td><td>❌ 用 Function Calling</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-来源链接按章节分组">9. 来源链接（按章节分组）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#9-%E6%9D%A5%E6%BA%90%E9%93%BE%E6%8E%A5%E6%8C%89%E7%AB%A0%E8%8A%82%E5%88%86%E7%BB%84" class="hash-link" aria-label="9. 来源链接（按章节分组）的直接链接" title="9. 来源链接（按章节分组）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="91-context-engineering-概念">9.1 Context Engineering 概念<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#91-context-engineering-%E6%A6%82%E5%BF%B5" class="hash-link" aria-label="9.1 Context Engineering 概念的直接链接" title="9.1 Context Engineering 概念的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://www.anthropic.com/engineering/building-effective-agents" target="_blank" rel="noopener noreferrer" class="">Anthropic: Building Effective Agents</a></li>
<li class=""><a href="https://www.langchain.com/blog/context-engineering-for-agents" target="_blank" rel="noopener noreferrer" class="">LangChain: Context Engineering for Agents</a></li>
<li class=""><a href="https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus" target="_blank" rel="noopener noreferrer" class="">Manus: Context Engineering for AI Agents</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="92-agent-框架">9.2 Agent 框架<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#92-agent-%E6%A1%86%E6%9E%B6" class="hash-link" aria-label="9.2 Agent 框架的直接链接" title="9.2 Agent 框架的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://github.com/langchain-ai/langgraph" target="_blank" rel="noopener noreferrer" class="">LangGraph</a></li>
<li class=""><a href="https://github.com/crewAIInc/crewAI" target="_blank" rel="noopener noreferrer" class="">CrewAI</a></li>
<li class=""><a href="https://github.com/microsoft/autogen" target="_blank" rel="noopener noreferrer" class="">AutoGen (Microsoft)</a></li>
<li class=""><a href="https://github.com/huggingface/smolagents" target="_blank" rel="noopener noreferrer" class="">Smolagents (HuggingFace)</a></li>
<li class=""><a href="https://github.com/letta-ai/letta" target="_blank" rel="noopener noreferrer" class="">Letta（原 MemGPT）</a></li>
<li class=""><a href="https://github.com/pydantic/pydantic-ai" target="_blank" rel="noopener noreferrer" class="">Pydantic AI</a></li>
<li class=""><a href="https://github.com/mastra-ai/mastra" target="_blank" rel="noopener noreferrer" class="">Mastra</a></li>
<li class=""><a href="https://github.com/agno-agi/agno" target="_blank" rel="noopener noreferrer" class="">Agno（原 Fixpoint）</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="93-记忆系统">9.3 记忆系统<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#93-%E8%AE%B0%E5%BF%86%E7%B3%BB%E7%BB%9F" class="hash-link" aria-label="9.3 记忆系统的直接链接" title="9.3 记忆系统的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://github.com/mem0ai/mem0" target="_blank" rel="noopener noreferrer" class="">Mem0</a></li>
<li class=""><a href="https://github.com/letta-ai/letta" target="_blank" rel="noopener noreferrer" class="">Letta</a></li>
<li class=""><a href="https://github.com/getzep/zep" target="_blank" rel="noopener noreferrer" class="">Zep</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="94-mcp">9.4 MCP<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#94-mcp" class="hash-link" aria-label="9.4 MCP的直接链接" title="9.4 MCP的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><a href="https://modelcontextprotocol.io/" target="_blank" rel="noopener noreferrer" class="">Model Context Protocol 官网</a></li>
<li class=""><a href="https://github.com/modelcontextprotocol/servers" target="_blank" rel="noopener noreferrer" class="">MCP Servers 仓库</a></li>
<li class=""><a href="https://github.com/modelcontextprotocol/python-sdk" target="_blank" rel="noopener noreferrer" class="">MCP Python SDK</a></li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="95-历史归档">9.5 历史归档<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E4%B8%8A%E4%B8%8B%E6%96%87%E5%B7%A5%E7%A8%8B%E4%B8%8EAgent%E7%AC%94%E8%AE%B0#95-%E5%8E%86%E5%8F%B2%E5%BD%92%E6%A1%A3" class="hash-link" aria-label="9.5 历史归档的直接链接" title="9.5 历史归档的直接链接" translate="no">​</a></h3>
<ul>
<li class="">原 <code>上下文工程异常问题总结.md</code>（项目根目录）已删除，核心 20 类问题提炼到本笔记 §7</li>
</ul>
<p>标签：#agent #mcp #prompt-engineering</p>]]></content>
        <category label="Agent" term="Agent"/>
        <category label="MCP" term="MCP"/>
        <category label="Prompt Engineering" term="Prompt Engineering"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[关系型数据库对比与选型笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/关系型数据库选型对比笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/关系型数据库选型对比笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[横向对比 MySQL / PostgreSQL / SQLite 三种主流关系型数据库，并给出按场景的选型决策。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>横向对比 MySQL / PostgreSQL / SQLite 三种主流关系型数据库，并给出按场景的选型决策。
单库详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/mysql">MySQL笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/postgresql">PostgreSQL笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/sqlite">SQLite笔记</a>。
本笔记旧稿 / 旧稿 / 旧稿 均旧稿目录已清理，当前以本文为准。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录">目录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#%E7%9B%AE%E5%BD%95" class="hash-link" aria-label="目录的直接链接" title="目录的直接链接" translate="no">​</a></h2>
<ol>
<li class="">一句话定位</li>
<li class="">维度对比表</li>
<li class="">关键差异化能力</li>
<li class="">场景选型决策</li>
<li class="">反向场景（什么时候<strong>不</strong>选）</li>
<li class="">迁移注意</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-一句话定位">1. 一句话定位<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#1-%E4%B8%80%E5%8F%A5%E8%AF%9D%E5%AE%9A%E4%BD%8D" class="hash-link" aria-label="1. 一句话定位的直接链接" title="1. 一句话定位的直接链接" translate="no">​</a></h2>





















<table><thead><tr><th>数据库</th><th>一句话</th></tr></thead><tbody><tr><td><strong>SQLite</strong></td><td>单文件、嵌入式、零配置的 SQL 引擎，跟随应用程序运行</td></tr><tr><td><strong>MySQL</strong></td><td>最流行的通用 OLTP 数据库，生态最广、运维工具最多</td></tr><tr><td><strong>PostgreSQL</strong></td><td>功能最强大的开源关系库，强类型 + 丰富类型 + 扩展机制</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-维度对比表">2. 维度对比表<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#2-%E7%BB%B4%E5%BA%A6%E5%AF%B9%E6%AF%94%E8%A1%A8" class="hash-link" aria-label="2. 维度对比表的直接链接" title="2. 维度对比表的直接链接" translate="no">​</a></h2>





























































































































<table><thead><tr><th>维度</th><th>SQLite</th><th>MySQL</th><th>PostgreSQL</th></tr></thead><tbody><tr><td>架构</td><td>嵌入式（进程内库）</td><td>C/S（默认服务端）</td><td>C/S（默认服务端）</td></tr><tr><td>单文件</td><td>✅ 一库一文件</td><td>❌</td><td>❌</td></tr><tr><td>零配置</td><td>✅</td><td>❌（要装服务、初始化）</td><td>❌（要装服务、初始化）</td></tr><tr><td>网络访问</td><td>❌（无内置协议）</td><td>✅</td><td>✅</td></tr><tr><td>事务</td><td>ACID</td><td>ACID（InnoDB）</td><td>ACID，MVCC</td></tr><tr><td>默认隔离级别</td><td>SERIALIZABLE（事实）</td><td>REPEATABLE READ</td><td>READ COMMITTED</td></tr><tr><td>并发写</td><td>全局写锁串行化</td><td>行锁 + MVCC（InnoDB）</td><td>行锁 + MVCC</td></tr><tr><td>数据类型</td><td>5 种动态类型</td><td>严格标量类型</td><td>严格 + 丰富（JSONB/数组/范围/枚举/自定义）</td></tr><tr><td>JSON 支持</td><td>文本函数（<code>json_extract</code>）</td><td>JSON 类型（5.7+）</td><td><strong>JSON / JSONB</strong>（推荐后者）</td></tr><tr><td>索引</td><td>B-tree</td><td>B-tree / Hash / FullText</td><td>B-tree / Hash / GIN / GiST / BRIN / SP-GiST</td></tr><tr><td>全文检索</td><td>FTS5 扩展</td><td>FULLTEXT（InnoDB）</td><td>内置 <code>tsvector</code> + <code>tsquery</code></td></tr><tr><td>GIS</td><td>❌</td><td>✅（基础）</td><td>✅ <strong>PostGIS</strong>（业界标杆）</td></tr><tr><td>扩展机制</td><td>编译期 / 运行时加载扩展</td><td>插件 / UDF</td><td><strong>Extension</strong>（生态庞大）</td></tr><tr><td>主从复制</td><td>❌</td><td>✅ 成熟（异步/半同步/组复制）</td><td>✅ 流复制 / 逻辑复制</td></tr><tr><td>典型上限</td><td>几十 GB；并发写 ~ 100 QPS 级</td><td>几百 GB ~ 数 TB；高并发 OLTP 主流</td><td>几 TB；复杂查询能力强</td></tr><tr><td>许可证</td><td>Public Domain</td><td>GPL（社区版）</td><td>PostgreSQL License（类 BSD）</td></tr><tr><td>云厂商支持</td><td>几乎不直供</td><td>✅ 全部主流</td><td>✅ 全部主流</td></tr><tr><td>ORM 生态</td><td>✅</td><td>✅（最广）</td><td>✅</td></tr><tr><td>适合部署</td><td>单机/端上</td><td>中大规模 Web</td><td>中大规模 + 复杂业务</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-关键差异化能力">3. 关键差异化能力<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#3-%E5%85%B3%E9%94%AE%E5%B7%AE%E5%BC%82%E5%8C%96%E8%83%BD%E5%8A%9B" class="hash-link" aria-label="3. 关键差异化能力的直接链接" title="3. 关键差异化能力的直接链接" translate="no">​</a></h2>
<p>每种数据库都有自己最值得拿出来说的"招牌能力"：</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-sqlite--嵌入式--单文件">3.1 SQLite — 嵌入式 + 单文件<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#31-sqlite--%E5%B5%8C%E5%85%A5%E5%BC%8F--%E5%8D%95%E6%96%87%E4%BB%B6" class="hash-link" aria-label="3.1 SQLite — 嵌入式 + 单文件的直接链接" title="3.1 SQLite — 嵌入式 + 单文件的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>零运维</strong>：拷贝文件 = 备份；删文件 = 删除数据库</li>
<li class=""><strong>跨平台一致</strong>：iOS / Android / Windows / macOS / Linux 都自带或一键可用</li>
<li class="">适合：移动 App、桌面工具、CI 临时库、单用户小工具</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-mysql--生态最成熟">3.2 MySQL — 生态最成熟<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#32-mysql--%E7%94%9F%E6%80%81%E6%9C%80%E6%88%90%E7%86%9F" class="hash-link" aria-label="3.2 MySQL — 生态最成熟的直接链接" title="3.2 MySQL — 生态最成熟的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>复制生态最丰富</strong>：异步复制、半同步、组复制、MHA、Orchestrator、读写分离中间件</li>
<li class=""><strong>运维工具最多</strong>：Percona Toolkit、pt-online-schema-change、gh-ost（在线 DDL）、MySQL Shell</li>
<li class=""><strong>云厂商支持最广</strong>：RDS / Aurora / TiDB（兼容 MySQL 协议）</li>
<li class="">适合：典型 Web 后端、读写分离架构、需要大量运维和迁移工具</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-postgresql--功能天花板">3.3 PostgreSQL — 功能天花板<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#33-postgresql--%E5%8A%9F%E8%83%BD%E5%A4%A9%E8%8A%B1%E6%9D%BF" class="hash-link" aria-label="3.3 PostgreSQL — 功能天花板的直接链接" title="3.3 PostgreSQL — 功能天花板的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>类型系统</strong>：JSONB / 数组 / 范围 / 自定义类型 / ENUM，能在不引入 NoSQL 的情况下做混合建模</li>
<li class=""><strong>索引选择最多</strong>：GIN（JSONB / 数组 / 全文）、GiST（GIS / 范围）、BRIN（大表时间序列）</li>
<li class=""><strong>扩展生态</strong>：PostGIS（GIS）、pgvector（向量）、pg_trgm（模糊）、timescaledb（时序）</li>
<li class=""><strong>SQL 标准贴合度</strong>：窗口函数、CTE、<code>MERGE</code>、物化视图、<code>LATERAL JOIN</code> 等新特性都很早就支持</li>
<li class="">适合：复杂数据模型、强一致性需求、GIS / AI / 时序场景</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-场景选型决策">4. 场景选型决策<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#4-%E5%9C%BA%E6%99%AF%E9%80%89%E5%9E%8B%E5%86%B3%E7%AD%96" class="hash-link" aria-label="4. 场景选型决策的直接链接" title="4. 场景选型决策的直接链接" translate="no">​</a></h2>
<p>按业务场景给一个<strong>默认推荐</strong>，再加备选。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-决策流程图">4.1 决策流程图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#41-%E5%86%B3%E7%AD%96%E6%B5%81%E7%A8%8B%E5%9B%BE" class="hash-link" aria-label="4.1 决策流程图的直接链接" title="4.1 决策流程图的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">你的数据要不要跨进程/跨机访问？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 不要 → 单机/端上工具？ ── 是 ──→ ✅ SQLite</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│                  └── 否（但服务仍在单进程）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│                       ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└── 要（多人/多服务访问）→ 业务对 SQL 标准和扩展能力要求高吗？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          ├── 高（复杂类型、JSON、GIS、AI）→ ✅ PostgreSQL</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          └── 一般 → 是典型 Web 后端 OLTP？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                       ├── 是 → ✅ MySQL</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                       └── 否 → ✅ PostgreSQL（默认更安全）</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="42-按场景列表">4.2 按场景列表<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#42-%E6%8C%89%E5%9C%BA%E6%99%AF%E5%88%97%E8%A1%A8" class="hash-link" aria-label="4.2 按场景列表的直接链接" title="4.2 按场景列表的直接链接" translate="no">​</a></h3>






































































<table><thead><tr><th>场景</th><th>推荐</th><th>备选 / 理由</th></tr></thead><tbody><tr><td>移动 App / 桌面软件本地存储</td><td><strong>SQLite</strong></td><td>单文件、零配置、跨平台</td></tr><tr><td>浏览器端 / Electron / Tauri</td><td><strong>SQLite</strong></td><td>跨端一致，WASM 版本可跑在浏览器</td></tr><tr><td>单用户小工具脚本 / CLI</td><td><strong>SQLite</strong></td><td>文件即数据库，无需安装服务</td></tr><tr><td>集成测试临时库</td><td><strong>SQLite</strong>（memory 或 file）</td><td>起停快，无外部依赖</td></tr><tr><td>典型 Web 后端（CRUD 为主，读多写少）</td><td><strong>MySQL</strong></td><td>生态成熟，云厂商 RDS / Aurora 完备</td></tr><tr><td>已有团队 / 项目大量用 MySQL</td><td><strong>MySQL</strong></td><td>迁移成本大于收益</td></tr><tr><td>复杂业务模型（金额、约束、JSON 混合、GIS）</td><td><strong>PostgreSQL</strong></td><td>强类型、严格约束、扩展丰富</td></tr><tr><td>AI / RAG（向量检索）</td><td><strong>PostgreSQL + pgvector</strong></td><td>一个库搞定元数据 + 向量</td></tr><tr><td>地理信息系统</td><td><strong>PostgreSQL + PostGIS</strong></td><td>业界事实标准</td></tr><tr><td>时序数据</td><td><strong>PostgreSQL + TimescaleDB</strong></td><td>关系模型 + 时序优化</td></tr><tr><td>OLAP / 大数据查询</td><td>（专用数仓）</td><td>Doris / ClickHouse / StarRocks</td></tr><tr><td>超大规模 OLTP（&gt; 10 TB 单库）</td><td>谨慎评估分库分表</td><td>TiDB / CockroachDB / Aurora</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-反向场景什么时候不选">5. 反向场景（什么时候<strong>不</strong>选）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#5-%E5%8F%8D%E5%90%91%E5%9C%BA%E6%99%AF%E4%BB%80%E4%B9%88%E6%97%B6%E5%80%99%E4%B8%8D%E9%80%89" class="hash-link" aria-label="5-反向场景什么时候不选的直接链接" title="5-反向场景什么时候不选的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-不要选-sqlite">5.1 不要选 SQLite<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#51-%E4%B8%8D%E8%A6%81%E9%80%89-sqlite" class="hash-link" aria-label="5.1 不要选 SQLite的直接链接" title="5.1 不要选 SQLite的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ 多客户端通过网络同时访问（无服务端）</li>
<li class="">❌ 高并发写入（全局写锁）</li>
<li class="">❌ 单库 &gt; 几十 GB</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-不要选-mysql">5.2 不要选 MySQL<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#52-%E4%B8%8D%E8%A6%81%E9%80%89-mysql" class="hash-link" aria-label="5.2 不要选 MySQL的直接链接" title="5.2 不要选 MySQL的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ 业务大量依赖 JSON / 复杂类型 / GIS / 向量检索（PG 更合适）</li>
<li class="">❌ 数据完整性要求极高（PG 的约束、CHECK、外键实现更严格）</li>
<li class="">❌ 需要高级 SQL 特性（<code>MERGE</code>、递归 CTE 性能、<code>LATERAL JOIN</code>、窗口函数）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-不要选-postgresql">5.3 不要选 PostgreSQL<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#53-%E4%B8%8D%E8%A6%81%E9%80%89-postgresql" class="hash-link" aria-label="5.3 不要选 PostgreSQL的直接链接" title="5.3 不要选 PostgreSQL的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ 团队完全没接触过、运维人才稀缺（MySQL 运维人手多）</li>
<li class="">❌ 现有系统强依赖 MySQL 特性（如特定 SQL_MODE、utf8mb3 行为）</li>
<li class="">❌ 极简单文件场景（SQLite 装它都嫌重）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-迁移注意">6. 迁移注意<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#6-%E8%BF%81%E7%A7%BB%E6%B3%A8%E6%84%8F" class="hash-link" aria-label="6. 迁移注意的直接链接" title="6. 迁移注意的直接链接" translate="no">​</a></h2>

























<table><thead><tr><th>迁移方向</th><th>主要差异</th></tr></thead><tbody><tr><td>MySQL → PostgreSQL</td><td>占位符 <code>%s</code> → <code>%s</code>（一致）；<code>AUTO_INCREMENT</code> → <code>SERIAL</code>；<code>TINYINT(1)</code> → <code>BOOLEAN</code>；<code>utf8</code> → <code>utf8</code> 含义不同；事务默认隔离级别不同</td></tr><tr><td>PostgreSQL → MySQL</td><td>去掉 JSONB（用 JSON）；慎用 ENUM / 数组 / 自定义类型；CASCADE 行为差异</td></tr><tr><td>SQLite → MySQL / PG</td><td>升级动态类型为严格类型；删除 <code>INTEGER PRIMARY KEY</code> 自带 rowid 行为；用真实 <code>AUTO_INCREMENT</code> / <code>SERIAL</code>；<code>WITHOUT ROWID</code> / <code>VACUUM</code> 等特有命令消失</td></tr><tr><td>MySQL / PG → SQLite（测试 / 迁移）</td><td>不支持网络协议，需要数据导出导入；并发模型完全不同</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关联笔记">关联笔记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#%E5%85%B3%E8%81%94%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="关联笔记的直接链接" title="关联笔记的直接链接" translate="no">​</a></h2>
<ul>
<li class="">MySQL 详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/mysql">MySQL笔记</a></li>
<li class="">PostgreSQL 详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/postgresql">PostgreSQL笔记</a></li>
<li class="">SQLite 详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/sqlite">SQLite笔记</a></li>
<li class="">向量数据库：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/qdrant">Qdrant笔记</a></li>
<li class="">数据库设计相关：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0">数据库设计与索引优化笔记</a></li>
<li class="">Demo：<code>example/db/sql-tools-demo/</code>（三种库 Python 连接示例）</li>
</ul>
<p>标签：#mysql #postgres #sqlite #mongodb</p>]]></content>
        <category label="MySQL" term="MySQL"/>
        <category label="PostgreSQL" term="PostgreSQL"/>
        <category label="SQLite" term="SQLite"/>
        <category label="MongoDB" term="MongoDB"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[前端工程笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/前端工程化笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/前端工程化笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[本篇覆盖前端工程化中的常见问题与判断标准：静态资源放在 public/ 还是 src/assets/、资源加载策略等。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>本篇覆盖前端工程化中的常见问题与判断标准：静态资源放在 <code>public/</code> 还是 <code>src/assets/</code>、资源加载策略等。
关联笔记：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/css/01-css-overview">I_CSS笔记</a>、<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/css/04-css-layout">IV_CSS布局笔记</a>
配套资料：<a href="https://cn.vitejs.dev/guide/assets.html" target="_blank" rel="noopener noreferrer" class="">Vite 静态资源</a>、<a href="https://webpack.js.org/guides/asset-modules/" target="_blank" rel="noopener noreferrer" class="">Webpack asset modules</a></p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-静态资源放-public-还是-srcassets">1. 静态资源放 <code>public/</code> 还是 <code>src/assets/</code>？<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#1-%E9%9D%99%E6%80%81%E8%B5%84%E6%BA%90%E6%94%BE-public-%E8%BF%98%E6%98%AF-srcassets" class="hash-link" aria-label="1-静态资源放-public-还是-srcassets的直接链接" title="1-静态资源放-public-还是-srcassets的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-核心判断标准">1.1 核心判断标准<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#11-%E6%A0%B8%E5%BF%83%E5%88%A4%E6%96%AD%E6%A0%87%E5%87%86" class="hash-link" aria-label="1.1 核心判断标准的直接链接" title="1.1 核心判断标准的直接链接" translate="no">​</a></h3>
<blockquote>
<p><strong>不是"图片还是字体"，而是"这个资源要不要进入模块打包系统"。</strong></p>
</blockquote>






























<table><thead><tr><th>维度</th><th><code>public/</code></th><th><code>src/assets/</code></th></tr></thead><tbody><tr><td>是否被构建工具处理</td><td>❌ 直接拷贝到产物</td><td>✅ 被 import，被处理</td></tr><tr><td>文件名</td><td>保持原名</td><td>带 hash 指纹</td></tr><tr><td>引用方式</td><td>写死绝对路径 <code>/xxx.png</code></td><td><code>import</code> 进来</td></tr><tr><td>适合</td><td>公开固定文件</td><td>源码模块引用</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-放-public-的场景">1.2 放 <code>public/</code> 的场景<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#12-%E6%94%BE-public-%E7%9A%84%E5%9C%BA%E6%99%AF" class="hash-link" aria-label="12-放-public-的场景的直接链接" title="12-放-public-的场景的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>需要固定 URL 直接访问</strong>：<code>/favicon.svg</code>、<code>/robots.txt</code>、<code>/manifest.webmanifest</code></li>
<li class=""><strong>不想经过 Vite/Webpack 打包</strong></li>
<li class=""><strong>希望文件名保持不变</strong>，方便外部系统或浏览器按约定读取</li>
<li class=""><strong>运行时动态拼接路径</strong>（后端返回 <code>/images/a.png</code> 这类静态地址）</li>
</ul>
<p><strong>典型例子</strong>：</p>
<ul>
<li class=""><code>favicon.ico</code> / <code>favicon.svg</code></li>
<li class=""><code>robots.txt</code></li>
<li class=""><code>sitemap.xml</code></li>
<li class=""><code>manifest.json</code> / <code>manifest.webmanifest</code></li>
<li class="">第三方要求固定文件名的验证文件（如百度站长验证、Google Search Console 验证）</li>
<li class="">很大的静态素材库，且不想让它们被 import 进构建图</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-放-srcassets-的场景">1.3 放 <code>src/assets/</code> 的场景<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#13-%E6%94%BE-srcassets-%E7%9A%84%E5%9C%BA%E6%99%AF" class="hash-link" aria-label="13-放-srcassets-的场景的直接链接" title="13-放-srcassets-的场景的直接链接" translate="no">​</a></h3>
<ul>
<li class="">资源会<strong>被组件 import</strong></li>
<li class="">希望打包器帮你做<strong>指纹文件名、缓存优化、路径重写</strong></li>
<li class="">资源和某个页面/组件<strong>强关联</strong>，属于源码的一部分</li>
<li class="">希望未使用资源能被更好地<strong>跟随源码管理</strong></li>
</ul>
<p><strong>典型例子</strong>：</p>
<ul>
<li class="">组件里引用的图片、图标、插图</li>
<li class="">本地字体文件</li>
<li class="">页面背景图</li>
<li class="">某个模块专用的音频、视频、svg</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="14-代码示例">1.4 代码示例<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#14-%E4%BB%A3%E7%A0%81%E7%A4%BA%E4%BE%8B" class="hash-link" aria-label="1.4 代码示例的直接链接" title="1.4 代码示例的直接链接" translate="no">​</a></h3>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// ✅ src/assets/ 写法：被打包处理，文件名带 hash</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword module" style="color:#00009f">import</span><span class="token plain"> </span><span class="token imports">heroImage</span><span class="token plain"> </span><span class="token keyword module" style="color:#00009f">from</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">'./assets/hero.png'</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword module" style="color:#00009f">export</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#d73a49">Hero</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#00009f">return</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#393A34">&lt;</span><span class="token tag" style="color:#00009f">img</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">src</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#393A34">=</span><span class="token tag script language-javascript punctuation" style="color:#393A34">{</span><span class="token tag script language-javascript" style="color:#00009f">heroImage</span><span class="token tag script language-javascript punctuation" style="color:#393A34">}</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">alt</span><span class="token tag attr-value punctuation attr-equals" style="color:#393A34">=</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag attr-value" style="color:#e3116c">hero</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag" style="color:#00009f"> </span><span class="token tag punctuation" style="color:#393A34">/&gt;</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></div></code></pre></div></div>
<div class="language-html codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-html codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">&lt;!-- ✅ public/ 写法：路径写死，构建时原样拷贝 --&gt;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token tag punctuation" style="color:#393A34">&lt;</span><span class="token tag" style="color:#00009f">link</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">rel</span><span class="token tag attr-value punctuation attr-equals" style="color:#393A34">=</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag attr-value" style="color:#e3116c">icon</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">href</span><span class="token tag attr-value punctuation attr-equals" style="color:#393A34">=</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag attr-value" style="color:#e3116c">/favicon.svg</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag" style="color:#00009f"> </span><span class="token tag punctuation" style="color:#393A34">/&gt;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token tag punctuation" style="color:#393A34">&lt;</span><span class="token tag" style="color:#00009f">img</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">src</span><span class="token tag attr-value punctuation attr-equals" style="color:#393A34">=</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag attr-value" style="color:#e3116c">/static/hero.png</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag" style="color:#00009f"> </span><span class="token tag attr-name" style="color:#00a4db">alt</span><span class="token tag attr-value punctuation attr-equals" style="color:#393A34">=</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag attr-value" style="color:#e3116c">logo</span><span class="token tag attr-value punctuation" style="color:#393A34">"</span><span class="token tag" style="color:#00009f"> </span><span class="token tag punctuation" style="color:#393A34">/&gt;</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="15-一句话速记">1.5 一句话速记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#15-%E4%B8%80%E5%8F%A5%E8%AF%9D%E9%80%9F%E8%AE%B0" class="hash-link" aria-label="1.5 一句话速记的直接链接" title="1.5 一句话速记的直接链接" translate="no">​</a></h3>
<blockquote>
<ul>
<li class=""><code>public/</code>：<strong>面向"网站公开目录"的静态文件</strong></li>
<li class=""><code>src/assets/</code>：<strong>面向"源码模块引用"的静态文件</strong></li>
</ul>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-常见坑">2. 常见坑<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#2-%E5%B8%B8%E8%A7%81%E5%9D%91" class="hash-link" aria-label="2. 常见坑的直接链接" title="2. 常见坑的直接链接" translate="no">​</a></h2>



































<table><thead><tr><th>坑</th><th>说明</th><th>解决</th></tr></thead><tbody><tr><td>把图标放到 <code>public/</code> 然后 import</td><td>拿不到 hash，无法做缓存优化</td><td>改放 <code>src/assets/</code></td></tr><tr><td>业务图片放 <code>src/assets/</code> 但不 import</td><td>不会被任何模块引用，构建时可能被 tree-shake 掉</td><td>改放 <code>public/</code></td></tr><tr><td><code>public/</code> 里的文件路径加 <code>./</code> 或 <code>../</code></td><td>路径在子路由下会失效</td><td>必须用<strong>绝对路径</strong>（<code>/xxx.png</code>）</td></tr><tr><td>把很大的视频文件放 <code>src/assets/</code></td><td>拖慢构建、增加 bundle 体积</td><td>改放 <code>public/</code> 或 CDN</td></tr><tr><td>改 <code>public/</code> 里文件后浏览器没更新</td><td>浏览器缓存</td><td>加查询参数 <code>&lt;img src="/a.png?v=2"&gt;</code></td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-进阶vite-vs-webpack-的差异">3. 进阶：Vite vs Webpack 的差异<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#3-%E8%BF%9B%E9%98%B6vite-vs-webpack-%E7%9A%84%E5%B7%AE%E5%BC%82" class="hash-link" aria-label="3. 进阶：Vite vs Webpack 的差异的直接链接" title="3. 进阶：Vite vs Webpack 的差异的直接链接" translate="no">​</a></h2>

















<table><thead><tr><th>工具</th><th>静态资源默认行为</th></tr></thead><tbody><tr><td><strong>Vite</strong></td><td><code>&lt; 4KB</code> 资源内联成 base64；<code>&gt;= 4KB</code> 单独输出</td></tr><tr><td><strong>Webpack 5+</strong></td><td>用 <code>asset/resource</code> 输出单独文件，<code>asset/inline</code> 转 base64，<code>asset</code> 自动选</td></tr></tbody></table>
<blockquote>
<p>如果想精细控制，构建工具的资源处理模块都支持按类型/大小自定义规则。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-工具与扩展">4. 工具与扩展<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%89%8D%E7%AB%AF%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%AC%94%E8%AE%B0#4-%E5%B7%A5%E5%85%B7%E4%B8%8E%E6%89%A9%E5%B1%95" class="hash-link" aria-label="4. 工具与扩展的直接链接" title="4. 工具与扩展的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>图标库</strong>：<a href="https://iconify.design/" target="_blank" rel="noopener noreferrer" class="">iconify</a>、<a href="https://lucide.dev/" target="_blank" rel="noopener noreferrer" class="">lucide</a> — 推荐按需 import，避免全量打包</li>
<li class=""><strong>雪碧图 / SVG Symbol</strong>：小图标用 SVG <code>&lt;use&gt;</code> 引用，减少 HTTP 请求</li>
<li class=""><strong>CDN</strong>：大文件（视频、字体包）放 CDN，不占构建产物</li>
<li class=""><strong>图片优化</strong>：<a href="https://sharp.pixelplumbing.com/" target="_blank" rel="noopener noreferrer" class="">sharp</a>（构建时转 webp/avif）</li>
</ul>
<p>标签：#javascript #css #nextjs</p>]]></content>
        <category label="JavaScript" term="JavaScript"/>
        <category label="CSS" term="CSS"/>
        <category label="Next.js" term="Next.js"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[小企业 DevOps 方案笔记（50~500 技术人员）]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/小企业DevOps方案笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/小企业DevOps方案笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[来自 DevOps基础与文化笔记 的延伸。这一规模比前面 K3s+Rancher 笔记里提到的"10~30 节点"小企业大了一档——通常有 3~10 个产品线、多团队、多环境。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>来自 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/DevOps%E5%9F%BA%E7%A1%80%E4%B8%8E%E6%96%87%E5%8C%96%E7%AC%94%E8%AE%B0">DevOps基础与文化笔记</a> 的延伸。这一规模比前面 K3s+Rancher 笔记里提到的"10<del>30 节点"小企业大了一档——通常有 3</del>10 个产品线、多团队、多环境。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-典型画像">1. 典型画像<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#1-%E5%85%B8%E5%9E%8B%E7%94%BB%E5%83%8F" class="hash-link" aria-label="1. 典型画像的直接链接" title="1. 典型画像的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-规模指标">1.1 规模指标<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#11-%E8%A7%84%E6%A8%A1%E6%8C%87%E6%A0%87" class="hash-link" aria-label="1.1 规模指标的直接链接" title="1.1 规模指标的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">技术人员：        50~500 人</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">业务产品线：       3~10 个</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">服务数量：        50~500 个（含微服务 / 单体服务）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">迭代并行：        多个产品线同时推进</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">环境数量：        dev / staging / pre-prod / prod 至少 4 套</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">发布频率：        一日多次（小变更）/ 一天一两次（中等变更）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">可用性要求：      99.5%~99.95%（SLA 4~9 个 9 / 月宕机分钟数）</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-典型组织">1.2 典型组织<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#12-%E5%85%B8%E5%9E%8B%E7%BB%84%E7%BB%87" class="hash-link" aria-label="1.2 典型组织的直接链接" title="1.2 典型组织的直接链接" translate="no">​</a></h3>
<ul>
<li class="">多个产品研发小组：每组 5~15 人</li>
<li class="">公共团队：平台组 / SRE 组 / 安全组 / QA 组</li>
<li class="">业务职能：售前、售后、市场、法务</li>
<li class="">基础设施：1~3 个公有云（多云） + 自建机房（部分公司）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-典型痛点">1.3 典型痛点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#13-%E5%85%B8%E5%9E%8B%E7%97%9B%E7%82%B9" class="hash-link" aria-label="1.3 典型痛点的直接链接" title="1.3 典型痛点的直接链接" translate="no">​</a></h3>
<ul>
<li class="">服务一多，环境/版本/CI 配置不一致</li>
<li class="">多个团队重复造轮子（各建各的 CI、各写各的发布脚本）</li>
<li class="">故障定位慢，链路长</li>
<li class="">安全合规靠人工审计，漏洞响应慢</li>
<li class="">新员工 oncall 成本高，制度不清晰</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-主流方案对比">2. 主流方案对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#2-%E4%B8%BB%E6%B5%81%E6%96%B9%E6%A1%88%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="2. 主流方案对比的直接链接" title="2. 主流方案对比的直接链接" translate="no">​</a></h2>
<p>按"代码托管 + CI/CD + 部署"三大支柱，分为三大流派：</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="21-全栈商业平台最快上手预算敏感度低时考虑">2.1 全栈商业平台（最快上手，预算敏感度低时考虑）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#21-%E5%85%A8%E6%A0%88%E5%95%86%E4%B8%9A%E5%B9%B3%E5%8F%B0%E6%9C%80%E5%BF%AB%E4%B8%8A%E6%89%8B%E9%A2%84%E7%AE%97%E6%95%8F%E6%84%9F%E5%BA%A6%E4%BD%8E%E6%97%B6%E8%80%83%E8%99%91" class="hash-link" aria-label="2.1 全栈商业平台（最快上手，预算敏感度低时考虑）的直接链接" title="2.1 全栈商业平台（最快上手，预算敏感度低时考虑）的直接链接" translate="no">​</a></h3>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-github-一栈式">A. GitHub 一栈式<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#a-github-%E4%B8%80%E6%A0%88%E5%BC%8F" class="hash-link" aria-label="A. GitHub 一栈式的直接链接" title="A. GitHub 一栈式的直接链接" translate="no">​</a></h4>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">GitHub              ← 代码托管 / PR / Issue</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">GitHub Actions      ← CI/CD（内置）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">ArgoCD              ← K8s GitOps 部署</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">EKS / AKS / GKE     ← K8s 托管</span><br></div></code></pre></div></div>

























<table><thead><tr><th>优势</th><th>劣势</th></tr></thead><tbody><tr><td>开发者最熟，文档生态最丰富</td><td>GitHub Actions 成本高（大 monorepo）</td></tr><tr><td>PR/Code Review/Issue 流程完善</td><td>数据出企业，自托管困难</td></tr><tr><td>Actions marketplace 插件多</td><td>多区域同步差</td></tr><tr><td>适合 IT 投资 &lt; 团队规模，devops &lt; 2 人</td><td>大型 monorepo 速度下降</td></tr></tbody></table>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="b-gitlab-ceee-自托管">B. GitLab CE/EE 自托管<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#b-gitlab-ceee-%E8%87%AA%E6%89%98%E7%AE%A1" class="hash-link" aria-label="B. GitLab CE/EE 自托管的直接链接" title="B. GitLab CE/EE 自托管的直接链接" translate="no">​</a></h4>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">GitLab (CE / EE)      ← 代码 + Issue + Wiki + CI + Registry (内置)</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">ArgoCD                 ← K8s GitOps（可选）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">K8s</span><br></div></code></pre></div></div>





















<table><thead><tr><th>优势</th><th>劣势</th></tr></thead><tbody><tr><td>全部能力一个平台：CI / Registry / 安全扫描 / Issue</td><td>升级痛苦（每版本都"半成品升级"）</td></tr><tr><td>自托管：数据在自己手里</td><td>EE 收费，CE 缺高级功能（多租户等）</td></tr><tr><td>适合喜欢"少技术栈"团队</td><td>性能比专用工具稍差</td></tr></tbody></table>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="c-azure-devops微软生态">C. Azure DevOps（微软生态）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#c-azure-devops%E5%BE%AE%E8%BD%AF%E7%94%9F%E6%80%81" class="hash-link" aria-label="C. Azure DevOps（微软生态）的直接链接" title="C. Azure DevOps（微软生态）的直接链接" translate="no">​</a></h4>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">Azure DevOps Repos   ← Git</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Azure DevOps Pipelines</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Azure DevOps Artifacts</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Azure Kubernetes Service + ArgoCD</span><br></div></code></pre></div></div>





















<table><thead><tr><th>优势</th><th>劣势</th></tr></thead><tbody><tr><td>与 Azure / .NET 生态无缝</td><td>跨云弱</td></tr><tr><td>自带测试管理 / 制品库 / Wiki</td><td>配置较复杂</td></tr><tr><td>Build 分钟数对微软内部免费</td><td>商业版价格高</td></tr></tbody></table>
<hr>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="22-全开源--自托管推荐给小规模技术团队">2.2 全开源 / 自托管（推荐给小规模技术团队）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#22-%E5%85%A8%E5%BC%80%E6%BA%90--%E8%87%AA%E6%89%98%E7%AE%A1%E6%8E%A8%E8%8D%90%E7%BB%99%E5%B0%8F%E8%A7%84%E6%A8%A1%E6%8A%80%E6%9C%AF%E5%9B%A2%E9%98%9F" class="hash-link" aria-label="2.2 全开源 / 自托管（推荐给小规模技术团队）的直接链接" title="2.2 全开源 / 自托管（推荐给小规模技术团队）的直接链接" translate="no">​</a></h3>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="方案-d-gitea--jenkins--tekton--argocd--k3s">方案 D. "Gitea + Jenkins + Tekton + ArgoCD + K3s"<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#%E6%96%B9%E6%A1%88-d-gitea--jenkins--tekton--argocd--k3s" class="hash-link" aria-label="方案 D. &quot;Gitea + Jenkins + Tekton + ArgoCD + K3s&quot;的直接链接" title="方案 D. &quot;Gitea + Jenkins + Tekton + ArgoCD + K3s&quot;的直接链接" translate="no">​</a></h4>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">Gitea (代码托管)                       ↘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Drone / Jenkins (CI)  ─────────► Harbor (镜像仓库) ──► ArgoCD ──► K8s</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Tekton (云原生 CI 可选)              ↗</span><br></div></code></pre></div></div>





















<table><thead><tr><th>优势</th><th>劣势</th></tr></thead><tbody><tr><td>完全可控、所有数据自持</td><td>运维成本（要管多个组件）</td></tr><tr><td>工具都是顶流开源</td><td>需要有平台工程团队（2~5 人）</td></tr><tr><td>灵活：可换组件</td><td>文档相对不如商业产品一致</td></tr></tbody></table>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="方案-e-github--jenkins--argocd--k8s混合">方案 E. "GitHub + Jenkins + ArgoCD + K8s（混合）"<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#%E6%96%B9%E6%A1%88-e-github--jenkins--argocd--k8s%E6%B7%B7%E5%90%88" class="hash-link" aria-label="方案 E. &quot;GitHub + Jenkins + ArgoCD + K8s（混合）&quot;的直接链接" title="方案 E. &quot;GitHub + Jenkins + ArgoCD + K8s（混合）&quot;的直接链接" translate="no">​</a></h4>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">GitHub               ← 代码托管（不放心企业用公网的可考虑 Gitea 替代）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Jenkins              ← CI（Jenkins on K8s）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">ArgoCD               ← K8s GitOps</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">K8s</span><br></div></code></pre></div></div>
<blockquote>
<p>详细配置见前面 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/jenkins/01-jenkins-basics">I_Jenkins基础笔记</a> ~ <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88">小企业运维生产方案总览</a>。</p>
</blockquote>
<hr>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="23-决策树">2.3 决策树<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#23-%E5%86%B3%E7%AD%96%E6%A0%91" class="hash-link" aria-label="2.3 决策树的直接链接" title="2.3 决策树的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">Q1: 必须数据私有 / 合规要求本地部署？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 是 → Q2</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└─ 否 → Q3</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Q2: 是否有 2~5 人专职平台工程团队？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 是 → 方案 D（全开源）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└─ 否 → 方案 B（GitLab 自托管）+ ArgoCD</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Q3: 是否依赖 Azure / 微软生态？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 是 → Azure DevOps</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└─ 否 → Q4</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Q4: 团队是否熟悉 GitHub？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├─ 是 → GitHub + ArgoCD</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└─ 否 → GitLab 一栈式</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-落地架构">3. 落地架构<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#3-%E8%90%BD%E5%9C%B0%E6%9E%B6%E6%9E%84" class="hash-link" aria-label="3. 落地架构的直接链接" title="3. 落地架构的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-经典分层视图">3.1 经典分层视图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#31-%E7%BB%8F%E5%85%B8%E5%88%86%E5%B1%82%E8%A7%86%E5%9B%BE" class="hash-link" aria-label="3.1 经典分层视图的直接链接" title="3.1 经典分层视图的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">                ┌──────────────────────────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     业务交付层（Developer Experience）              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  Backstage / 内部门户 / 新服务脚手架                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └──────────────────────────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  ↑</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                ┌─────────────────┴──────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     持续交付层（CD）                              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  ArgoCD / Flux / Spinnaker + 灰度发布                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  + 制品签名（Cosign）+ 安全门禁（Kyverno/OPA）         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └─────────────────┬──────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  ↑</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                ┌─────────────────┴──────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     持续集成层（CI）                              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  Jenkins / GitHub Actions / Tekton                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  + 单元测试 + 集成测试 + 镜像构建 + 漏洞扫描         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └─────────────────┬──────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  ↑</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                ┌─────────────────┴──────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     源代码层（SC）                                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  GitHub / GitLab / Gitea                          │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  + 评审流程 + 分支策略                            │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └──────────────────────────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                ┌──────────────────────────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     平台底层（Platform）                            │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  K8s / 服务网格 / 存储 / 网络 / 证书管理               │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └──────────────────────────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                ┌──────────────────────────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │     可观测性层（Observability）                     │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  Metrics（Prometheus）+ Logs（Loki）+ Traces（Jaeger）│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                │  + 告警（Alertmanager / PagerDuty）                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                └──────────────────────────────────────────────────┘</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-典型组合a-方案github-一栈式">3.2 典型组合（A 方案：GitHub 一栈式）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#32-%E5%85%B8%E5%9E%8B%E7%BB%84%E5%90%88a-%E6%96%B9%E6%A1%88github-%E4%B8%80%E6%A0%88%E5%BC%8F" class="hash-link" aria-label="3.2 典型组合（A 方案：GitHub 一栈式）的直接链接" title="3.2 典型组合（A 方案：GitHub 一栈式）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">代码：   GitHub Enterprise（自托管 GitHub Connect）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">CI：     GitHub Actions（含 self-hosted runner）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">镜像：   AWS ECR / Azure ACR / Harbor</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">CD：     ArgoCD（K8s GitOps）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">集群：   EKS / AKS</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">可观测：Datadog 或 New Relic（商业）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">或：     Grafana Cloud（含 LGTM 栈）</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-多环境与多集群">4. 多环境与多集群<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#4-%E5%A4%9A%E7%8E%AF%E5%A2%83%E4%B8%8E%E5%A4%9A%E9%9B%86%E7%BE%A4" class="hash-link" aria-label="4. 多环境与多集群的直接链接" title="4. 多环境与多集群的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-环境分层">4.1 环境分层<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#41-%E7%8E%AF%E5%A2%83%E5%88%86%E5%B1%82" class="hash-link" aria-label="4.1 环境分层的直接链接" title="4.1 环境分层的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>环境</th><th>用途</th><th>数据</th><th>谁能部署</th></tr></thead><tbody><tr><td><strong>dev</strong></td><td>开发者自测</td><td>假数据</td><td>任何人</td></tr><tr><td><strong>staging</strong></td><td>QA 测试 / 集成测试</td><td>假数据或脱敏生产数据</td><td>QA + 研发</td></tr><tr><td><strong>pre-prod</strong></td><td>上线前最终验证</td><td>脱敏数据</td><td>Release Manager</td></tr><tr><td><strong>prod</strong></td><td>生产</td><td>真实数据</td><td>自动化或人工审批</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="42-多集群">4.2 多集群<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#42-%E5%A4%9A%E9%9B%86%E7%BE%A4" class="hash-link" aria-label="4.2 多集群的直接链接" title="4.2 多集群的直接链接" translate="no">​</a></h3>
<p>50<del>500 人通常 1</del>5 个生产集群：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">- dev cluster（开发）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">- staging cluster（QA）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">- prod-east cluster（生产主）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">- prod-west cluster（生产灾备/灰度）</span><br></div></code></pre></div></div>
<p>管理方式：</p>

























<table><thead><tr><th>工具</th><th>特性</th></tr></thead><tbody><tr><td><strong>Rancher</strong></td><td>多集群 UI / 应用商店 / GitOps 引擎 Fleet</td></tr><tr><td><strong>Cluster API</strong></td><td>声明式集群生命周期</td></tr><tr><td><strong>Clusterpedia</strong></td><td>跨集群资源查询</td></tr><tr><td><strong>ArgoCD ApplicationSet</strong></td><td>跨集群同一应用同步</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-分支策略">5. 分支策略<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#5-%E5%88%86%E6%94%AF%E7%AD%96%E7%95%A5" class="hash-link" aria-label="5. 分支策略的直接链接" title="5. 分支策略的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-trunk-based推荐小企业">5.1 trunk-based（推荐小企业）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#51-trunk-based%E6%8E%A8%E8%8D%90%E5%B0%8F%E4%BC%81%E4%B8%9A" class="hash-link" aria-label="5.1 trunk-based（推荐小企业）的直接链接" title="5.1 trunk-based（推荐小企业）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">main（主干，受保护）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ├── feature/xxx（短命分支，1~3 天合并）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  └── hotfix/xxx（紧急修复）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">策略：</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 小批量合并，频繁集成</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 配合 feature flag 控制风险</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 不需要 release 分支</span><br></div></code></pre></div></div>
<p><strong>优势</strong>：CI/CD 简单、减少分支冲突</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-gitflow复杂产品--严格管控">5.2 GitFlow（复杂产品 / 严格管控）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#52-gitflow%E5%A4%8D%E6%9D%82%E4%BA%A7%E5%93%81--%E4%B8%A5%E6%A0%BC%E7%AE%A1%E6%8E%A7" class="hash-link" aria-label="5.2 GitFlow（复杂产品 / 严格管控）的直接链接" title="5.2 GitFlow（复杂产品 / 严格管控）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">main（生产）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ├── develop（集成）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │    ├── feature/xxx</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │    ├── release/x.x（冻结）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │    └── bugfix/xxx</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  └── hotfix/xxx（生产紧急修复）</span><br></div></code></pre></div></div>
<p><strong>适用</strong>：版本化产品（如 SDK、桌面软件）或者严格管控的金融场景</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-github-flow互联网产品">5.3 GitHub Flow（互联网产品）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#53-github-flow%E4%BA%92%E8%81%94%E7%BD%91%E4%BA%A7%E5%93%81" class="hash-link" aria-label="5.3 GitHub Flow（互联网产品）的直接链接" title="5.3 GitHub Flow（互联网产品）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">main</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  └── feature/xxx（提交 → PR → review → merge → 自动部署）</span><br></div></code></pre></div></div>
<p><strong>适用</strong>：互联网产品、SaaS、CD 工具链成熟</p>
<blockquote>
<p><strong>决策</strong>：</p>
<ul>
<li class="">持续交付 + 单一版本 → trunk-based</li>
<li class="">多版本并存 → GitFlow</li>
<li class="">团队只想用最简单的 → GitHub Flow</li>
</ul>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-服务网格与服务治理">6. 服务网格与服务治理<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#6-%E6%9C%8D%E5%8A%A1%E7%BD%91%E6%A0%BC%E4%B8%8E%E6%9C%8D%E5%8A%A1%E6%B2%BB%E7%90%86" class="hash-link" aria-label="6. 服务网格与服务治理的直接链接" title="6. 服务网格与服务治理的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-服务网格适用场景">6.1 服务网格适用场景<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#61-%E6%9C%8D%E5%8A%A1%E7%BD%91%E6%A0%BC%E9%80%82%E7%94%A8%E5%9C%BA%E6%99%AF" class="hash-link" aria-label="6.1 服务网格适用场景的直接链接" title="6.1 服务网格适用场景的直接链接" translate="no">​</a></h3>
<p>服务网格（Service Mesh）= 把服务间通信从应用层抽到基础设施层（sidecar）。</p>
<p><strong>适用</strong>：</p>
<ul>
<li class="">服务数量 &gt; 30</li>
<li class="">多语言（Java / Go / Python / Node 混用）</li>
<li class="">需要 mTLS、流量管理、可观测性而不改应用代码</li>
</ul>
<p><strong>不适用</strong>：</p>
<ul>
<li class="">&lt; 10 个服务</li>
<li class="">单一语言已经能搞定</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-选型">6.2 选型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#62-%E9%80%89%E5%9E%8B" class="hash-link" aria-label="6.2 选型的直接链接" title="6.2 选型的直接链接" translate="no">​</a></h3>

























<table><thead><tr><th>网格</th><th>优势</th><th>适用</th></tr></thead><tbody><tr><td><strong>Istio</strong></td><td>功能最全</td><td>大型、复杂需求</td></tr><tr><td><strong>Linkerd</strong></td><td>轻量、rust 数据面</td><td>中小企业首选</td></tr><tr><td><strong>Cilium Service Mesh</strong></td><td>内核层、eBPF、性能好</td><td>云原生 + 网络要求高</td></tr></tbody></table>
<blockquote>
<p>中小企业推荐从 <strong>Linkerd</strong> 起步；规模上去再考虑 Istio。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-团队模型与组织">7. 团队模型与组织<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#7-%E5%9B%A2%E9%98%9F%E6%A8%A1%E5%9E%8B%E4%B8%8E%E7%BB%84%E7%BB%87" class="hash-link" aria-label="7. 团队模型与组织的直接链接" title="7. 团队模型与组织的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-team-topologies推荐">7.1 Team Topologies（推荐）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#71-team-topologies%E6%8E%A8%E8%8D%90" class="hash-link" aria-label="7.1 Team Topologies（推荐）的直接链接" title="7.1 Team Topologies（推荐）的直接链接" translate="no">​</a></h3>
<p>4 类团队：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">┌───────────────────────────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ Stream-aligned team（业务流团队）                      │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│   - 直接交付业务价值（5~9 人）                          │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│   - 包含：PM + 后端 + 前端 + QA（可能 oncall）         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└───────────────────────────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            │                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">            ▼                ▼</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">┌──────────────────┐  ┌──────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│ Platform team    │  │ Enabling team            │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│  - 提供 IDP      │  │  - 帮业务团队能力建设       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│  - Backstage     │  │  - 教练 / SRE             │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">│  - CI/CD 模板    │  └──────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└──────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">特殊：Complicated-subsystem team</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 处理复杂专门系统（ML、密码学、搜索引擎等）</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-sre-团队规模">7.2 SRE 团队规模<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#72-sre-%E5%9B%A2%E9%98%9F%E8%A7%84%E6%A8%A1" class="hash-link" aria-label="7.2 SRE 团队规模的直接链接" title="7.2 SRE 团队规模的直接链接" translate="no">​</a></h3>
<p>依据 Google《Site Reliability Engineering》：</p>
<blockquote>
<p>SRE 团队 = 50% ~ 100% × 研发团队总人数（业务复杂、可靠性要求高时更多）</p>
</blockquote>
<p>50<del>500 人技术团队，建议 SRE / 平台团队 5</del>15 人。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-监控与-slo">8. 监控与 SLO<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#8-%E7%9B%91%E6%8E%A7%E4%B8%8E-slo" class="hash-link" aria-label="8. 监控与 SLO的直接链接" title="8. 监控与 SLO的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-slislo-框架">8.1 SLI/SLO 框架<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#81-slislo-%E6%A1%86%E6%9E%B6" class="hash-link" aria-label="8.1 SLI/SLO 框架的直接链接" title="8.1 SLI/SLO 框架的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">SLI（指标）：例如「请求延迟 P99」</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">SLO（目标）：例如「99.9% 请求延迟 P99 &lt; 200ms」</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">SLA（协议）：对客户的承诺，含后果</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Error Budget = 1 - SLO</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  → 错误预算消耗完时，冻结新功能发布，专注稳定性</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-推荐目标">8.2 推荐目标<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#82-%E6%8E%A8%E8%8D%90%E7%9B%AE%E6%A0%87" class="hash-link" aria-label="8.2 推荐目标的直接链接" title="8.2 推荐目标的直接链接" translate="no">​</a></h3>

























<table><thead><tr><th>场景</th><th>SLO 建议</th></tr></thead><tbody><tr><td><strong>Web API</strong></td><td>可用性 99.9% / 延迟 P95 &lt; 200ms</td></tr><tr><td><strong>Web API（强 SLA）</strong></td><td>可用性 99.95% / 延迟 P95 &lt; 100ms</td></tr><tr><td><strong>后台 Job</strong></td><td>完成率 99.5%（含重试）</td></tr><tr><td><strong>数据 Pipeline</strong></td><td>当日完成率 &gt; 95%</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="83-监控维度">8.3 监控维度<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#83-%E7%9B%91%E6%8E%A7%E7%BB%B4%E5%BA%A6" class="hash-link" aria-label="8.3 监控维度的直接链接" title="8.3 监控维度的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>RED</strong>（服务）：Rate / Errors / Duration</li>
<li class=""><strong>USE</strong>（资源）：Utilization / Saturation / Errors</li>
<li class=""><strong>Four Golden Signals</strong>：Latency / Traffic / Errors / Saturation</li>
</ul>
<p>工具：Prometheus + Grafana + Alertmanager（成熟自建）；Datadog / New Relic / Grafana Cloud（商业 SaaS）</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-安全与合规">9. 安全与合规<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#9-%E5%AE%89%E5%85%A8%E4%B8%8E%E5%90%88%E8%A7%84" class="hash-link" aria-label="9. 安全与合规的直接链接" title="9. 安全与合规的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="91-软件供应链安全slsa">9.1 软件供应链安全（SLSA）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#91-%E8%BD%AF%E4%BB%B6%E4%BE%9B%E5%BA%94%E9%93%BE%E5%AE%89%E5%85%A8slsa" class="hash-link" aria-label="9.1 软件供应链安全（SLSA）的直接链接" title="9.1 软件供应链安全（SLSA）的直接链接" translate="no">​</a></h3>

























<table><thead><tr><th>级别</th><th>含义</th></tr></thead><tbody><tr><td><strong>SLSA 1</strong></td><td>基础 CI、签名镜像</td></tr><tr><td><strong>SLSA 2</strong></td><td>受控构建环境、签名证明</td></tr><tr><td><strong>SLSA 3</strong></td><td>防篡改构建</td></tr><tr><td><strong>SLSA 4</strong></td><td>双人审计、最高保障</td></tr></tbody></table>
<p>建议小企业先到 SLSA 2。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="92-安全工具链">9.2 安全工具链<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#92-%E5%AE%89%E5%85%A8%E5%B7%A5%E5%85%B7%E9%93%BE" class="hash-link" aria-label="9.2 安全工具链的直接链接" title="9.2 安全工具链的直接链接" translate="no">​</a></h3>

































<table><thead><tr><th>阶段</th><th>工具</th></tr></thead><tbody><tr><td>代码</td><td>Snyk / CodeQL / GitGuardian（密钥检测）</td></tr><tr><td>镜像</td><td>Trivy / Anchore / Clair</td></tr><tr><td>运行</td><td>Falco / Tracee（运行时异常）</td></tr><tr><td>策略</td><td>OPA / Kyverno / Gatekeeper</td></tr><tr><td>依赖</td><td>Dependabot / Renovate</td></tr><tr><td>网络</td><td>Cilium / Calico NetworkPolicy</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="93-合规模型">9.3 合规模型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#93-%E5%90%88%E8%A7%84%E6%A8%A1%E5%9E%8B" class="hash-link" aria-label="9.3 合规模型的直接链接" title="9.3 合规模型的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>标准</th><th>适用</th></tr></thead><tbody><tr><td><strong>SOC 2</strong></td><td>通用 SaaS</td></tr><tr><td><strong>ISO 27001</strong></td><td>行业通用</td></tr><tr><td><strong>等保</strong></td><td>国内强制（按等级）</td></tr><tr><td><strong>GDPR / CCPA</strong></td><td>涉及欧盟 / 加州用户</td></tr><tr><td><strong>PCI-DSS</strong></td><td>涉及支付</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="10-成本管理">10. 成本管理<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#10-%E6%88%90%E6%9C%AC%E7%AE%A1%E7%90%86" class="hash-link" aria-label="10. 成本管理的直接链接" title="10. 成本管理的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="101-finops云财务">10.1 FinOps（云财务）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#101-finops%E4%BA%91%E8%B4%A2%E5%8A%A1" class="hash-link" aria-label="10.1 FinOps（云财务）的直接链接" title="10.1 FinOps（云财务）的直接链接" translate="no">​</a></h3>
<p>3 大能力：</p>
<ol>
<li class=""><strong>Inform</strong>：成本可见（每服务、每团队）</li>
<li class=""><strong>Optimize</strong>：节省成本（Spot 实例、预留实例、自动关停）</li>
<li class=""><strong>Operate</strong>：组织流程（成本问责）</li>
</ol>
<p>工具：</p>
<ul>
<li class=""><strong>云原生</strong>：KubeCost / OpenCost（开源）</li>
<li class=""><strong>商业</strong>：CloudHealth / Vantage / Harness CCM</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="102-常见节省手段">10.2 常见节省手段<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#102-%E5%B8%B8%E8%A7%81%E8%8A%82%E7%9C%81%E6%89%8B%E6%AE%B5" class="hash-link" aria-label="10.2 常见节省手段的直接链接" title="10.2 常见节省手段的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>手段</th><th>节省</th></tr></thead><tbody><tr><td>Spot 实例</td><td>60%~90%</td></tr><tr><td>预留 / Saving Plan</td><td>30%~60%</td></tr><tr><td>自动关停 dev/staging</td><td>60%~80%</td></tr><tr><td>镜像瘦身</td><td>镜像分发时间 ↓</td></tr><tr><td>HPA + VPA</td><td>弹性避免过度配置</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-演进路线24-个月建议">11. 演进路线（24 个月建议）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#11-%E6%BC%94%E8%BF%9B%E8%B7%AF%E7%BA%BF24-%E4%B8%AA%E6%9C%88%E5%BB%BA%E8%AE%AE" class="hash-link" aria-label="11. 演进路线（24 个月建议）的直接链接" title="11. 演进路线（24 个月建议）的直接链接" translate="no">​</a></h2>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">Month 1~3：基线</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - Git 流程规范化</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - CI 覆盖率达到 80%</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 接入基础监控（APM）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Month 4~6：标准化</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 镜像化所有服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 公共 Helm Chart / 模板</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - IaC（Terraform）管云资源</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Month 7~12：治理</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - GitOps（ArgoCD）+ App-of-Apps</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - SLO 全面定义</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 安全门禁（Trivy + Kyverno）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - Harbor 漏洞门禁</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Month 13~18：平台化</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - Backstage IDP</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 自服务化</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 共享 oncall 流程</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Month 19~24：精进</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 混沌工程（Chaos Mesh / Litmus）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - 服务网格（如需要）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - AIOps / 容量规划</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  - DORA 指标达到 Elite</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-一句话总结">12. 一句话总结<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9ADevOps%E6%96%B9%E6%A1%88%E7%AC%94%E8%AE%B0#12-%E4%B8%80%E5%8F%A5%E8%AF%9D%E6%80%BB%E7%BB%93" class="hash-link" aria-label="12. 一句话总结的直接链接" title="12. 一句话总结的直接链接" translate="no">​</a></h2>
<ul>
<li class="">50~500 人企业目标：<strong>稳 L3，进 L4</strong></li>
<li class="">主流方案：<strong>GitHub / GitLab / 自托管全开源</strong> 三选一</li>
<li class="">架构关键：CI + 制品 + CD + 可观测 + SLO 五件套</li>
<li class="">组织关键：业务流团队 + 平台团队 + SRE 文化</li>
<li class="">演进路径：从痛点切入，不一上来就上服务网格 + IDP</li>
</ul>
<p>标签：#docker #kubernetes #jenkins</p>]]></content>
        <category label="Docker" term="Docker"/>
        <category label="Kubernetes" term="Kubernetes"/>
        <category label="Jenkins" term="Jenkins"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[运维生产方案总览（小企业级架构师视角）]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/小企业运维生产方案总览</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/小企业运维生产方案总览"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[来自 IKubernetes基础笔记 ~ IIJenkins_CICD实战笔记 的综合：架构选型、拓扑、部署顺序、容量估算、备份与安全。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>来自 <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/kubernetes/01-kubernetes-basics">I_Kubernetes基础笔记</a> ~ <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/jenkins/02-jenkins-cicd-practice">II_Jenkins_CICD实战笔记</a> 的综合：<strong>架构选型、拓扑、部署顺序、容量估算、备份与安全</strong>。</p>
</blockquote>
<p>适用规模：<strong>1<del>50 个业务服务 / 节点 10</del>30 台 / 日请求 100w ~ 1000w</strong>。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-整体拓扑屋顶图">1. 整体拓扑（屋顶图）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#1-%E6%95%B4%E4%BD%93%E6%8B%93%E6%89%91%E5%B1%8B%E9%A1%B6%E5%9B%BE" class="hash-link" aria-label="1. 整体拓扑（屋顶图）的直接链接" title="1. 整体拓扑（屋顶图）的直接链接" translate="no">​</a></h2>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">                  ┌───────────────────────────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │              内网办公网                        │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                                               │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  ┌──────────┐         ┌──────────────────┐   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │  Gitea   │         │   Harbor 镜像库   │   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │  (Git)   │         │  harbor.example  │   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  └────┬─────┘         └────────┬─────────┘   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │       │ push/PR              │ pull         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │       ▼                       ▼              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  ┌──────────────────────────────────────┐    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │        Jenkins Controller            │    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │  （jenkins.example.com, K3s 上跑）       │    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  └────────────────┬─────────────────────┘    │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                   │ 调度                       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                   ▼ （临时 Agent Pod）         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         ┌────────────────────────┐           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   业务 K3s 集群           │           │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   ┌─────────────────────┐│         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   │ web / api / frontend  ││         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   │ worker / jobs        ││         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   └─────────────────────┘│         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   ┌─────────────────────┐│         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   │ postgresql / redis   ││         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   │ (StatefulSet)         ││         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         │   └─────────────────────┘│         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │         └──────────────┬────────────┘         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                        │ Longhorn                │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                        ▼                        │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │               ┌──────────────────┐              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │               │  块存储节点        │              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │               └──────────────────┘              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                                                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │            ┌───────────────────────┐              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │            │  Rancher 管理控制台    │              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │            │  rancher.example.com │              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │            └───────────────────────┘              │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                                                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  ┌──────────┐           ┌──────────────┐         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │  Prometheus│          │    Grafana    │         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │  + Alertmgr│          │  (含仪表盘)    │         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  └──────────┘           └──────────────┘         │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │                                                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  ┌──────────────────────────────────────┐        │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  │   Loki + Promtail（日志）             │        │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  └──────────────────────────────────────┘        │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  └───────────────────────────────────────────┘</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                            │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                            ▼ 公网（按需）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  ┌──────────────────────┐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │   外部 DNS / LB       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  │  + cert-manager       │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  └──────────────────────┘</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-组件选型小结">2. 组件选型小结<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#2-%E7%BB%84%E4%BB%B6%E9%80%89%E5%9E%8B%E5%B0%8F%E7%BB%93" class="hash-link" aria-label="2. 组件选型小结的直接链接" title="2. 组件选型小结的直接链接" translate="no">​</a></h2>

































































<table><thead><tr><th>组件</th><th>选型</th><th>引用</th></tr></thead><tbody><tr><td>K8s 发行版</td><td>K3s（HA，3 server）</td><td><a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/kubernetes/03-k3s">III_K3s笔记</a></td></tr><tr><td>集群管理</td><td>Rancher（Helm on K3s）</td><td><a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/kubernetes/04-rancher">IV_Rancher笔记</a></td></tr><tr><td>镜像仓库</td><td>Harbor（Helm on K3s）</td><td><a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/harbor">Harbor笔记</a></td></tr><tr><td>CI/CD</td><td>Jenkins（Helm on K3s）+ K8s plugin</td><td><a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/jenkins/01-jenkins-basics">I_Jenkins基础笔记</a> / <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/jenkins/02-jenkins-cicd-practice">II_Jenkins_CICD实战笔记</a></td></tr><tr><td>存储</td><td>Longhorn</td><td>单独文档（可选）</td></tr><tr><td>负载均衡</td><td>servicelb（小）/ MetalLB（生产）</td><td>单独文档</td></tr><tr><td>Ingress</td><td>Nginx Ingress Controller</td><td>单独文档</td></tr><tr><td>监控</td><td>Prometheus + Grafana（kube-prometheus-stack）</td><td>单独文档</td></tr><tr><td>日志</td><td>Loki + Promtail</td><td>单独文档</td></tr><tr><td>证书</td><td>cert-manager + Let's Encrypt</td><td>单独文档</td></tr><tr><td>GitOps（可选）</td><td>ArgoCD</td><td>单独文档</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-服务器规划小企业典型">3. 服务器规划（小企业典型）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#3-%E6%9C%8D%E5%8A%A1%E5%99%A8%E8%A7%84%E5%88%92%E5%B0%8F%E4%BC%81%E4%B8%9A%E5%85%B8%E5%9E%8B" class="hash-link" aria-label="3. 服务器规划（小企业典型）的直接链接" title="3. 服务器规划（小企业典型）的直接链接" translate="no">​</a></h2>
<blockquote>
<p>**10 台机器（中型）**为示例。可视规模缩减/扩展。</p>
</blockquote>

































































<table><thead><tr><th>角色</th><th>数量</th><th>机器规格（建议）</th><th>备注</th></tr></thead><tbody><tr><td>Rancher 控制台</td><td>3 (HA)</td><td>4C8G x3</td><td>跑 Rancher + 内置数据库或外部 DB</td></tr><tr><td>K3s server (HA)</td><td>3</td><td>4C8G x3</td><td>业务集群 master</td></tr><tr><td>K3s worker</td><td>3</td><td>8C16G x3</td><td>跑 Pod</td></tr><tr><td>存储节点</td><td>3</td><td>8C16G + 100G SSD x3</td><td>Longhorn 卷副本</td></tr><tr><td>Harbor</td><td>2 (主+备份)</td><td>4C16G + 500G SSD x2</td><td>跑 Harbor + 数据库</td></tr><tr><td>Jenkins</td><td>2 (主备)</td><td>4C8G x2</td><td>跑 Jenkins + 调度 agent pod</td></tr><tr><td>Gitea</td><td>1</td><td>2C4G x1</td><td>Git 仓库</td></tr><tr><td>监控 + 日志</td><td>2</td><td>4C16G x2</td><td>Prometheus + Grafana + Loki</td></tr><tr><td><strong>合计</strong></td><td><strong>~19 台</strong></td><td>-</td><td>含冗余</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-容量估算">3.1 容量估算<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#31-%E5%AE%B9%E9%87%8F%E4%BC%B0%E7%AE%97" class="hash-link" aria-label="3.1 容量估算的直接链接" title="3.1 容量估算的直接链接" translate="no">​</a></h3>
<ul>
<li class="">每业务服务 K8s Pod 资源约：0.5<del>2C / 1</del>4G</li>
<li class="">50 服务 × 3 副本 = 150 pod</li>
<li class="">假设平均 1C/2G → 总需求 150C / 300G</li>
<li class="">worker 10 台每台预留 8C/16G → 足够</li>
<li class="">存储需求：约 1T（DB）+ 500G（应用 logs）→ Longhorn 1.5T 起</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-网络规划">3.2 网络规划<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#32-%E7%BD%91%E7%BB%9C%E8%A7%84%E5%88%92" class="hash-link" aria-label="3.2 网络规划的直接链接" title="3.2 网络规划的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>用途</th><th>CIDR</th></tr></thead><tbody><tr><td>节点管理网</td><td>192.168.1.0/24</td></tr><tr><td>存储网</td><td>192.168.2.0/24</td></tr><tr><td>Service 网段（K3s 默认）</td><td>10.43.0.0/16</td></tr><tr><td>Pod 网段</td><td>10.42.0.0/16</td></tr><tr><td>MetalLB IP 池</td><td>192.168.10.0/24</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-部署顺序">4. 部署顺序<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#4-%E9%83%A8%E7%BD%B2%E9%A1%BA%E5%BA%8F" class="hash-link" aria-label="4. 部署顺序的直接链接" title="4. 部署顺序的直接链接" translate="no">​</a></h2>
<blockquote>
<p>严格按以下顺序，<strong>前一阶段不稳别进下一阶段</strong>。</p>
</blockquote>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">① 安装 K3s 集群（HA，3 server）              ←  半天</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">② 安装 Helm、kubectl、配置镜像加速            ←  1h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">③ 安装 Rancher（Helm on K3s）                ←  2h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">④ 导入已有 K3s（如有）                         ←  1h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑤ 安装 cert-manager（Helm）                   ←  1h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑥ 安装 Longhorn（Helm）                      ←  2h + 副本验证</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑦ 安装 MetalLB（可选，Helm）                   ←  1h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑧ 安装 Nginx Ingress Controller（Helm）       ←  1h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑨ 安装 Harbor（Helm，持久化用 Longhorn）        ←  2h + 推拉验证</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑩ 安装 Gitea / 对接外部 Git                    ←  1h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑪ 安装 Jenkins（Helm，K8s plugin）            ←  3h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑫ 安装 kube-prometheus-stack                  ←  3h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑬ 安装 Loki + Promtail                       ←  2h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑭ 安装 ArgoCD（可选，开启 GitOps）            ←  2h</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">⑮ 业务系统逐个迁移                            ←  持续</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-安全规范必须">5. 安全规范（必须）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#5-%E5%AE%89%E5%85%A8%E8%A7%84%E8%8C%83%E5%BF%85%E9%A1%BB" class="hash-link" aria-label="5. 安全规范（必须）的直接链接" title="5. 安全规范（必须）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-镜像安全">5.1 镜像安全<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#51-%E9%95%9C%E5%83%8F%E5%AE%89%E5%85%A8" class="hash-link" aria-label="5.1 镜像安全的直接链接" title="5.1 镜像安全的直接链接" translate="no">​</a></h3>
<ul>
<li class="">✅ 业务镜像全部推 Harbor（不直接用 Docker Hub）</li>
<li class="">✅ Trivy 漏洞扫描：CRITICAL/HIGH 失败则门禁</li>
<li class="">✅ 关键服务（生产）使用 Cosign 签名</li>
<li class="">✅ 镜像镜像签名验证（Kyverno 策略）</li>
<li class="">❌ 禁止 <code>--privileged</code> 容器</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-rbac">5.2 RBAC<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#52-rbac" class="hash-link" aria-label="5.2 RBAC的直接链接" title="5.2 RBAC的直接链接" translate="no">​</a></h3>
<ul>
<li class="">✅ 业务 namespace 加 <code>pod-security.kubernetes.io/enforce: restricted</code></li>
<li class="">✅ 默认用户（Dashboard 默认 SA）不能直接用</li>
<li class="">✅ Rancher 用 LDAP/OIDC 集成</li>
<li class="">✅ Jenkins 用机器人账号（不用真实用户）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-网络隔离">5.3 网络隔离<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#53-%E7%BD%91%E7%BB%9C%E9%9A%94%E7%A6%BB" class="hash-link" aria-label="5.3 网络隔离的直接链接" title="5.3 网络隔离的直接链接" translate="no">​</a></h3>
<ul>
<li class="">✅ 启用 NetworkPolicy（用 Calico/Cilium）</li>
<li class="">✅ namespace 之间默认隔离；显式白名单</li>
<li class="">✅ 内部服务不暴露 NodePort；走 Ingress</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="54-凭据管理">5.4 凭据管理<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#54-%E5%87%AD%E6%8D%AE%E7%AE%A1%E7%90%86" class="hash-link" aria-label="5.4 凭据管理的直接链接" title="5.4 凭据管理的直接链接" translate="no">​</a></h3>
<ul>
<li class="">✅ 所有凭据走 Vault / ExternalSecrets</li>
<li class="">✅ Jenkins 凭据走 JCasC + Credentials plugin</li>
<li class="">✅ kubeconfig 最小权限：只为对应 namespace</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-备份与恢复">6. 备份与恢复<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#6-%E5%A4%87%E4%BB%BD%E4%B8%8E%E6%81%A2%E5%A4%8D" class="hash-link" aria-label="6. 备份与恢复的直接链接" title="6. 备份与恢复的直接链接" translate="no">​</a></h2>





















































<table><thead><tr><th>对象</th><th>方法</th><th>频率</th><th>备注</th></tr></thead><tbody><tr><td>K3s etcd</td><td><code>k3s etcd-snapshot</code> → S3</td><td>每 6h</td><td>自动</td></tr><tr><td>Harbor 数据</td><td><code>backup.sh</code> → S3</td><td>每天</td><td>含镜像 + 元数据 + 配置</td></tr><tr><td>Jenkins 数据</td><td>ThinBackup → S3</td><td>每天</td><td>含 job + 凭据（加密）</td></tr><tr><td>Gitea</td><td>pg dump + 备份目录</td><td>每天</td><td>全量</td></tr><tr><td>业务数据库</td><td>pg_dump / mysqldump</td><td>每 1h + 全量每天</td><td>与 Longhorn 快照结合</td></tr><tr><td>K8s manifests</td><td>Git（GitOps）</td><td>持续</td><td>真理之源</td></tr><tr><td>Longhorn 卷</td><td>内置 Snapshot + S3</td><td>每天</td><td>防勒索</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-演练">6.1 演练<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#61-%E6%BC%94%E7%BB%83" class="hash-link" aria-label="6.1 演练的直接链接" title="6.1 演练的直接链接" translate="no">​</a></h3>
<p>每季度做一次<strong>灾备演练</strong>：</p>
<ul>
<li class="">从零搭一个 K3s 集群</li>
<li class="">导入最新 etcd snapshot → 集群数据恢复</li>
<li class="">验证 Harbor / Jenkins / 业务服务的状态</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-监控告警">7. 监控告警<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#7-%E7%9B%91%E6%8E%A7%E5%91%8A%E8%AD%A6" class="hash-link" aria-label="7. 监控告警的直接链接" title="7. 监控告警的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-关键仪表盘grafana">7.1 关键仪表盘（Grafana）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#71-%E5%85%B3%E9%94%AE%E4%BB%AA%E8%A1%A8%E7%9B%98grafana" class="hash-link" aria-label="7.1 关键仪表盘（Grafana）的直接链接" title="7.1 关键仪表盘（Grafana）的直接链接" translate="no">​</a></h3>
<ul>
<li class="">K8s cluster overview</li>
<li class="">Node CPU/内存/磁盘/网络</li>
<li class="">Pod / Namespace 资源使用</li>
<li class="">关键业务 QPS / 延迟 / 错误率</li>
<li class="">镜像仓库容量 / 拉取速率</li>
<li class="">Jenkins Job 运行状态</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-告警项alertmanager">7.2 告警项（Alertmanager）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#72-%E5%91%8A%E8%AD%A6%E9%A1%B9alertmanager" class="hash-link" aria-label="7.2 告警项（Alertmanager）的直接链接" title="7.2 告警项（Alertmanager）的直接链接" translate="no">​</a></h3>

















































<table><thead><tr><th>指标</th><th>阈值</th></tr></thead><tbody><tr><td>节点 CPU &gt; 80%</td><td>5min 持续 → 报警</td></tr><tr><td>节点内存 &gt; 90%</td><td>5min 持续</td></tr><tr><td>节点磁盘 &gt; 85%</td><td>立即</td></tr><tr><td>K8s Pod CrashLoopBackOff</td><td>立即</td></tr><tr><td>K8s Pod OOMKilled</td><td>立即</td></tr><tr><td>节点 NotReady</td><td>2min 持续</td></tr><tr><td>镜像扫描 CRITICAL</td><td>立即</td></tr><tr><td>Jenkins Job 失败</td><td>立即</td></tr><tr><td>Longhorn 卷副本丢失</td><td>立即</td></tr><tr><td>证书 7 天内过期</td><td>1 天前提前通知</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="73-通知通道">7.3 通知通道<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#73-%E9%80%9A%E7%9F%A5%E9%80%9A%E9%81%93" class="hash-link" aria-label="7.3 通知通道的直接链接" title="7.3 通知通道的直接链接" translate="no">​</a></h3>
<ul>
<li class="">飞书 / 钉钉（工作群）</li>
<li class="">邮件（次要）</li>
<li class="">值班 oncall 机器（PagerDuty / 自建系统）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-日志聚合">8. 日志聚合<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#8-%E6%97%A5%E5%BF%97%E8%81%9A%E5%90%88" class="hash-link" aria-label="8. 日志聚合的直接链接" title="8. 日志聚合的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-loki--promtail-替代-elk-的理由">8.1 Loki + Promtail 替代 ELK 的理由<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#81-loki--promtail-%E6%9B%BF%E4%BB%A3-elk-%E7%9A%84%E7%90%86%E7%94%B1" class="hash-link" aria-label="8.1 Loki + Promtail 替代 ELK 的理由的直接链接" title="8.1 Loki + Promtail 替代 ELK 的理由的直接链接" translate="no">​</a></h3>
<ul>
<li class="">资源占用小（10x）</li>
<li class="">与 Grafana / Prometheus 集成天然</li>
<li class="">适合「按 label 筛选」</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-落地">8.2 落地<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#82-%E8%90%BD%E5%9C%B0" class="hash-link" aria-label="8.2 落地的直接链接" title="8.2 落地的直接链接" translate="no">​</a></h3>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">helm repo </span><span class="token function" style="color:#d73a49">add</span><span class="token plain"> grafana https://grafana.github.io/helm-charts</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">helm </span><span class="token function" style="color:#d73a49">install</span><span class="token plain"> loki grafana/loki-stack </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--namespace</span><span class="token plain"> logging </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--set</span><span class="token plain"> </span><span class="token assign-left variable" style="color:#36acaa">promtail.enabled</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">true </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--set</span><span class="token plain"> </span><span class="token assign-left variable" style="color:#36acaa">loki.persistence.enabled</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">true </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--set</span><span class="token plain"> </span><span class="token assign-left variable" style="color:#36acaa">loki.persistence.storageClassName</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">longhorn </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token parameter variable" style="color:#36acaa">--set</span><span class="token plain"> </span><span class="token assign-left variable" style="color:#36acaa">loki.persistence.size</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">100Gi</span><br></div></code></pre></div></div>
<p>应用内日志标准：</p>
<div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-yaml codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">env</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">name</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> TZ</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token key atrule" style="color:#00a4db">value</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> Asia/Shanghai</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">name</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> LOG_LEVEL</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token key atrule" style="color:#00a4db">value</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> info</span><br></div></code></pre></div></div>
<p>应用写 stdout/stderr（不要写文件），Promtail 自动收集。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-持续维护清单">9. 持续维护清单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#9-%E6%8C%81%E7%BB%AD%E7%BB%B4%E6%8A%A4%E6%B8%85%E5%8D%95" class="hash-link" aria-label="9. 持续维护清单的直接链接" title="9. 持续维护清单的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="91-每周">9.1 每周<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#91-%E6%AF%8F%E5%91%A8" class="hash-link" aria-label="9.1 每周的直接链接" title="9.1 每周的直接链接" translate="no">​</a></h3>
<ul class="contains-task-list containsTaskList_mC6p">
<li class="task-list-item"><input type="checkbox" disabled=""> 看 Grafana 仪表盘，确认无异常</li>
<li class="task-list-item"><input type="checkbox" disabled=""> 看 Jenkins Job 失败列表</li>
<li class="task-list-item"><input type="checkbox" disabled=""> 看 Cert-manager 证书过期列表</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="92-每月">9.2 每月<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#92-%E6%AF%8F%E6%9C%88" class="hash-link" aria-label="9.2 每月的直接链接" title="9.2 每月的直接链接" translate="no">​</a></h3>
<ul class="contains-task-list containsTaskList_mC6p">
<li class="task-list-item"><input type="checkbox" disabled=""> K3s / Rancher / Jenkins / Harbor 升级评估</li>
<li class="task-list-item"><input type="checkbox" disabled=""> etcd snapshot 演练</li>
<li class="task-list-item"><input type="checkbox" disabled=""> 镜像仓库清理（release 过期的 tag）</li>
<li class="task-list-item"><input type="checkbox" disabled=""> 容量评估（CPU / 内存 / 磁盘）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="93-季度">9.3 季度<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#93-%E5%AD%A3%E5%BA%A6" class="hash-link" aria-label="9.3 季度的直接链接" title="9.3 季度的直接链接" translate="no">​</a></h3>
<ul class="contains-task-list containsTaskList_mC6p">
<li class="task-list-item"><input type="checkbox" disabled=""> 全量灾备演练</li>
<li class="task-list-item"><input type="checkbox" disabled=""> 安全审计（过期凭据 / 未授权 RBAC）</li>
<li class="task-list-item"><input type="checkbox" disabled=""> 备份归档到冷存储</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="10-从零到生产的-8-步实施路径">10. 从零到生产的 8 步实施路径<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#10-%E4%BB%8E%E9%9B%B6%E5%88%B0%E7%94%9F%E4%BA%A7%E7%9A%84-8-%E6%AD%A5%E5%AE%9E%E6%96%BD%E8%B7%AF%E5%BE%84" class="hash-link" aria-label="10. 从零到生产的 8 步实施路径的直接链接" title="10. 从零到生产的 8 步实施路径的直接链接" translate="no">​</a></h2>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">step 1: 学习 + 本地 minikube / k3d          [1 周]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 2: 部署 K3s 测试集群（1 server）        [1 天]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 3: 部署 Rancher + 接入 K3s 集群         [2 天]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 4: 部署 Harbor + 配置镜像推送           [1 天]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 5: 部署 Jenkins + 第一个 Pipeline       [3 天]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 6: 把一个非关键服务迁过来跑            [1 周]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 7: 优化：监控 + 日志 + 告警             [1 周]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">step 8: HA + 灾备 + 安全加固                 [1 周]</span><br></div></code></pre></div></div>
<blockquote>
<p>全过程约 6~8 周 1 人投入（含学习）。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-一句话总结">11. 一句话总结<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#11-%E4%B8%80%E5%8F%A5%E8%AF%9D%E6%80%BB%E7%BB%93" class="hash-link" aria-label="11. 一句话总结的直接链接" title="11. 一句话总结的直接链接" translate="no">​</a></h2>
<ul>
<li class="">小企业 K8s 选 <strong>K3s + Rancher</strong>，上手快、社区成熟</li>
<li class="">CI/CD 选 <strong>Jenkins（K8s plugin）+ Harbor + Kaniko + Trivy</strong>，生态最全、门禁最严</li>
<li class="">把<strong>备份 / 监控 / 安全</strong>当基础设施而不是后期补救，按"日备、周演、月审计"做</li>
<li class=""><strong>GitOps</strong> 是省事省心的进阶，强烈推荐</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-推荐参考阅读">12. 推荐参考阅读<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%B0%8F%E4%BC%81%E4%B8%9A%E8%BF%90%E7%BB%B4%E7%94%9F%E4%BA%A7%E6%96%B9%E6%A1%88%E6%80%BB%E8%A7%88#12-%E6%8E%A8%E8%8D%90%E5%8F%82%E8%80%83%E9%98%85%E8%AF%BB" class="hash-link" aria-label="12. 推荐参考阅读的直接链接" title="12. 推荐参考阅读的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><a href="https://kubernetes.io/zh-cn/docs/home/" target="_blank" rel="noopener noreferrer" class="">Kubernetes 官方文档</a></li>
<li class=""><a href="https://docs.k3s.io/" target="_blank" rel="noopener noreferrer" class="">K3s 官方文档</a></li>
<li class=""><a href="https://ranchermanager.docs.rancher.com/" target="_blank" rel="noopener noreferrer" class="">Rancher 官方文档</a></li>
<li class=""><a href="https://goharbor.io/docs/" target="_blank" rel="noopener noreferrer" class="">Harbor 官方文档</a></li>
<li class=""><a href="https://www.jenkins.io/doc/" target="_blank" rel="noopener noreferrer" class="">Jenkins 官方文档</a></li>
<li class=""><a href="https://longhorn.io/docs/" target="_blank" rel="noopener noreferrer" class="">Longhorn 官方文档</a></li>
<li class=""><a href="https://grafana.com/docs/loki/latest/" target="_blank" rel="noopener noreferrer" class="">Loki 官方文档</a></li>
<li class=""><a href="https://cert-manager.io/docs/" target="_blank" rel="noopener noreferrer" class="">cert-manager 官方文档</a></li>
<li class=""><a href="https://github.com/aquasecurity/trivy" target="_blank" rel="noopener noreferrer" class="">Trivy 漏洞扫描器</a></li>
<li class=""><a href="https://github.com/GoogleContainerTools/kaniko" target="_blank" rel="noopener noreferrer" class="">Kaniko 构建器</a></li>
</ul>
<p>标签：#docker #kubernetes #harbor #jenkins</p>]]></content>
        <category label="Docker" term="Docker"/>
        <category label="Kubernetes" term="Kubernetes"/>
        <category label="Harbor" term="Harbor"/>
        <category label="Jenkins" term="Jenkins"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[数据库设计相关笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/数据库设计与索引优化笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/数据库设计与索引优化笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[工业化生产环境下的数据库设计规范 + 慢 SQL 排查与索引优化流程（FastAPI + SQLAlchemy + Alembic），覆盖关系型数据库（MySQL / PostgreSQL / SQLite）+ Redis + MongoDB。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>工业化生产环境下的数据库设计规范 + 慢 SQL 排查与索引优化流程（FastAPI + SQLAlchemy + Alembic），覆盖关系型数据库（MySQL / PostgreSQL / SQLite）+ Redis + MongoDB。
本笔记旧稿 仅含 2 个外链 + 4 行小结，已完整重构；旧稿目录已清理，当前以本文为准。
演示代码示例在 <code>example/db-design/</code>（慢查询埋点 + Alembic 加索引完整脚本 + Redis key 模板）。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录">目录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#%E7%9B%AE%E5%BD%95" class="hash-link" aria-label="目录的直接链接" title="目录的直接链接" translate="no">​</a></h2>
<ol>
<li class="">生产环境数据库设计原则（核心原则）</li>
<li class="">关系型数据库表设计要点</li>
<li class="">Redis 键设计规范</li>
<li class="">MongoDB Schema 设计</li>
<li class="">慢 SQL 排查与索引优化</li>
<li class="">加索引：走代码层 Alembic Migration，不走裸 SQL</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-生产环境数据库设计原则">1. 生产环境数据库设计原则<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#1-%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E5%8E%9F%E5%88%99" class="hash-link" aria-label="1. 生产环境数据库设计原则的直接链接" title="1. 生产环境数据库设计原则的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-一句话原则">1.1 一句话原则<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#11-%E4%B8%80%E5%8F%A5%E8%AF%9D%E5%8E%9F%E5%88%99" class="hash-link" aria-label="1.1 一句话原则的直接链接" title="1.1 一句话原则的直接链接" translate="no">​</a></h3>
<blockquote>
<p><strong>ER 图保留表与表的关联（沟通用）；DB 层不加外键约束（性能 / 扩展性）；业务约束在代码层做。</strong></p>
</blockquote>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-db-层保留--不保留的约束">1.2 DB 层保留 / 不保留的约束<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#12-db-%E5%B1%82%E4%BF%9D%E7%95%99--%E4%B8%8D%E4%BF%9D%E7%95%99%E7%9A%84%E7%BA%A6%E6%9D%9F" class="hash-link" aria-label="1.2 DB 层保留 / 不保留的约束的直接链接" title="1.2 DB 层保留 / 不保留的约束的直接链接" translate="no">​</a></h3>















































<table><thead><tr><th>约束类型</th><th>DB 层</th><th>代码层</th><th>原因</th></tr></thead><tbody><tr><td><strong>主键（PK）</strong></td><td>✅ 必须</td><td>—</td><td>物理寻址唯一标识</td></tr><tr><td><strong>非空（NOT NULL）</strong></td><td>✅ 尽量</td><td>—</td><td>减少三值逻辑复杂度</td></tr><tr><td><strong>唯一约束（UNIQUE）</strong></td><td>✅ 保留部分</td><td>—</td><td>DB 层是 race-condition 天然防线（防止并发重复）</td></tr><tr><td><strong>外键（FK）</strong></td><td>❌ 不加</td><td>✅ Service / ORM</td><td>见 1.3</td></tr><tr><td><strong>CHECK 约束</strong></td><td>❌ 不加</td><td>✅ 代码层</td><td>不同 DB 实现差异大</td></tr><tr><td><strong>复杂业务约束</strong>（如余额 ≥ 0）</td><td>❌ 不加</td><td>✅ Service 层事务</td><td>单条 SQL 内做约束容易死锁</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-不在-db-层加外键的理由业界共识">1.3 不在 DB 层加外键的理由（业界共识）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#13-%E4%B8%8D%E5%9C%A8-db-%E5%B1%82%E5%8A%A0%E5%A4%96%E9%94%AE%E7%9A%84%E7%90%86%E7%94%B1%E4%B8%9A%E7%95%8C%E5%85%B1%E8%AF%86" class="hash-link" aria-label="1.3 不在 DB 层加外键的理由（业界共识）的直接链接" title="1.3 不在 DB 层加外键的理由（业界共识）的直接链接" translate="no">​</a></h3>
<ol>
<li class=""><strong>DDL 锁表</strong>：外键级联检查会延长 INSERT/UPDATE 持锁时间，影响并发</li>
<li class=""><strong>分库分表后失效</strong>：跨库 / 分表场景下 FK 无法落地</li>
<li class=""><strong>微服务拆分后失效</strong>：跨服务调用根本无法做 DB 层 FK</li>
<li class=""><strong>性能损耗</strong>：每次写多一次约束校验（InnoDB 即时有 <code>foreign_key_checks</code> 开关）</li>
<li class=""><strong>循环依赖</strong>：ORM 双向关系 + DB FK 容易形成导入循环</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="14-er-图怎么画">1.4 ER 图怎么画<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#14-er-%E5%9B%BE%E6%80%8E%E4%B9%88%E7%94%BB" class="hash-link" aria-label="1.4 ER 图怎么画的直接链接" title="1.4 ER 图怎么画的直接链接" translate="no">​</a></h3>
<ul>
<li class="">仍然在设计文档 / dbdiagram.io / draw.io 画出表与表关联</li>
<li class="">用虚线箭头标注「逻辑外键」，明确写「DB 层不加约束」</li>
<li class="">在 Service 层 / Repository 层做「插入前查存在性 + 事务兜底」</li>
<li class="">必要时用兜底清理 job（孤儿数据检测 / 软删除关联）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-关系型数据库表设计要点">2. 关系型数据库表设计要点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#2-%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E8%A1%A8%E8%AE%BE%E8%AE%A1%E8%A6%81%E7%82%B9" class="hash-link" aria-label="2. 关系型数据库表设计要点的直接链接" title="2. 关系型数据库表设计要点的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="21-主键策略">2.1 主键策略<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#21-%E4%B8%BB%E9%94%AE%E7%AD%96%E7%95%A5" class="hash-link" aria-label="2.1 主键策略的直接链接" title="2.1 主键策略的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>方案</th><th>适用</th><th>注意</th></tr></thead><tbody><tr><td>自增 <code>BIGINT</code></td><td>单库 OLTP 主流</td><td>分库分表要换方案</td></tr><tr><td>雪花 ID / Sonyflake</td><td>分布式、跨库</td><td>13~53 bit 信息 + 趋势递增</td></tr><tr><td>UUID v7</td><td>分布式 + 时序</td><td>PG / MySQL 8 默认不支持，需应用生成</td></tr><tr><td>UUID v4</td><td>几乎不推荐</td><td>索引页分裂、存储膨胀</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="22-必备字段按需">2.2 必备字段（按需）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#22-%E5%BF%85%E5%A4%87%E5%AD%97%E6%AE%B5%E6%8C%89%E9%9C%80" class="hash-link" aria-label="2.2 必备字段（按需）的直接链接" title="2.2 必备字段（按需）的直接链接" translate="no">​</a></h3>
<div class="language-sql codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sql codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">CREATE</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">TABLE</span><span class="token plain"> orders </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    id          </span><span class="token keyword" style="color:#00009f">BIGINT</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">PRIMARY</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">KEY</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic">-- 业务字段 ...</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    created_at  </span><span class="token keyword" style="color:#00009f">TIMESTAMP</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">NULL</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">DEFAULT</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">CURRENT_TIMESTAMP</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    updated_at  </span><span class="token keyword" style="color:#00009f">TIMESTAMP</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">NOT</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">NULL</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">DEFAULT</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">CURRENT_TIMESTAMP</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">ON</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">UPDATE</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">CURRENT_TIMESTAMP</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    deleted_at  </span><span class="token keyword" style="color:#00009f">TIMESTAMP</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">NULL</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">DEFAULT</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">NULL</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic">-- 软删除按场景</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><br></div></code></pre></div></div>
<ul>
<li class=""><code>created_at</code> / <code>updated_at</code> 必加，便于排查与排序</li>
<li class=""><code>deleted_at</code> 看业务是否需要软删除（物理删除有数据恢复 / 审计风险）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="23-字段类型选择">2.3 字段类型选择<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#23-%E5%AD%97%E6%AE%B5%E7%B1%BB%E5%9E%8B%E9%80%89%E6%8B%A9" class="hash-link" aria-label="2.3 字段类型选择的直接链接" title="2.3 字段类型选择的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>业务</th><th>类型</th><th>备注</th></tr></thead><tbody><tr><td>金额</td><td><code>DECIMAL(M, D)</code> / <code>NUMERIC</code></td><td>永远不要 <code>FLOAT</code> / <code>DOUBLE</code></td></tr><tr><td>状态字段</td><td><code>TINYINT</code> / <code>ENUM</code>（PG）</td><td>比 <code>VARCHAR</code> 索引小</td></tr><tr><td>布尔</td><td><code>TINYINT(1)</code> / <code>BOOLEAN</code></td><td>MySQL 中 <code>BOOLEAN</code> = <code>TINYINT(1)</code></td></tr><tr><td>JSON</td><td>MySQL 5.7+ <code>JSON</code> / PG <code>JSONB</code>（推荐）</td><td>JSONB 支持索引（PG）</td></tr><tr><td>时间</td><td><code>TIMESTAMP</code>（到 2038） / <code>DATETIME</code>（MySQL） / <code>TIMESTAMPTZ</code>（PG 推荐）</td><td>跨时区优先 <code>TIMESTAMPTZ</code></td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="24-not-null-原则">2.4 NOT NULL 原则<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#24-not-null-%E5%8E%9F%E5%88%99" class="hash-link" aria-label="2.4 NOT NULL 原则的直接链接" title="2.4 NOT NULL 原则的直接链接" translate="no">​</a></h3>
<ul>
<li class="">能 NOT NULL 就 NOT NULL，少用 NULL（NULL 有三值逻辑：<code>=NULL</code> 永远 false，需 <code>IS NULL</code>）</li>
<li class="">业务上「没有」就用空串 / 0 / 默认值，而不是 NULL</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-redis-键设计规范">3. Redis 键设计规范<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#3-redis-%E9%94%AE%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83" class="hash-link" aria-label="3. Redis 键设计规范的直接链接" title="3. Redis 键设计规范的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-命名约定业界主流">3.1 命名约定（业界主流）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#31-%E5%91%BD%E5%90%8D%E7%BA%A6%E5%AE%9A%E4%B8%9A%E7%95%8C%E4%B8%BB%E6%B5%81" class="hash-link" aria-label="3.1 命名约定（业界主流）的直接链接" title="3.1 命名约定（业界主流）的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>分隔符</strong>：冒号 <code>:</code>（兼容 RedisInsight、redis-cli 的展示）</li>
<li class=""><strong>模板</strong>：<code>业务:模块:业务ID:字段</code></li>
<li class=""><strong>必备规则</strong>：
<ul>
<li class="">必须设 TTL（防内存膨胀）</li>
<li class="">长度可控（不要拿 JSON 整段当 key，存 hash / json 字符串作为 value）</li>
<li class="">不用空格 / 换行 / 特殊字符</li>
<li class="">统一小写</li>
</ul>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-典型场景-key-模板">3.2 典型场景 key 模板<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#32-%E5%85%B8%E5%9E%8B%E5%9C%BA%E6%99%AF-key-%E6%A8%A1%E6%9D%BF" class="hash-link" aria-label="3.2 典型场景 key 模板的直接链接" title="3.2 典型场景 key 模板的直接链接" translate="no">​</a></h3>













































<table><thead><tr><th>场景</th><th>模板</th><th>示例</th></tr></thead><tbody><tr><td>缓存</td><td><code>cache:模块:key</code></td><td><code>cache:user:profile:1000</code></td></tr><tr><td>Session</td><td><code>sess:{sessionId}</code></td><td><code>sess:abc123def456</code></td></tr><tr><td>限流</td><td><code>ratelimit:{userId}:window</code></td><td><code>ratelimit:{1000}:1m</code></td></tr><tr><td>分布式锁</td><td><code>lock:resource:xxx</code></td><td><code>lock:order:5678</code></td></tr><tr><td>计数器</td><td><code>counter:场景:id</code></td><td><code>counter:views:homepage</code></td></tr><tr><td>Stream</td><td><code>stream:events:topic</code></td><td><code>stream:events:order_created</code></td></tr><tr><td>Pub/Sub</td><td><code>channel:notifications:{userId}</code></td><td><code>channel:notifications:{1000}</code></td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-cluster-hash-tag-关键">3.3 Cluster Hash Tag <code>{...}</code>（关键）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#33-cluster-hash-tag-%E5%85%B3%E9%94%AE" class="hash-link" aria-label="33-cluster-hash-tag-关键的直接链接" title="33-cluster-hash-tag-关键的直接链接" translate="no">​</a></h3>
<p>Redis Cluster 用整个 key 做 CRC16 分 slot；多 key 操作（<code>MGET</code> / <code>MSET</code> / 事务 / Lua）<strong>必须在同一 slot</strong>，否则报错 <code>CROSSSLOT</code>。</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain"># ❌ 不带 hash tag：key 落在不同 slot，MGET 报错</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">&gt; MGET user:1000:profile user:1000:settings</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">(error) CROSSSLOT Keys in request don't hash to the same slot</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"># ✅ 用 {userId} 强制同一 slot</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">&gt; SET user:{1000}:profile  "Alice"   OK</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">&gt; SET user:{1000}:settings "dark_mode"  OK</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">&gt; MGET user:{1000}:profile user:{1000}:settings</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">1) "Alice"</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">2) "dark_mode"</span><br></div></code></pre></div></div>
<p><strong>规则</strong>：</p>
<ul>
<li class="">只识别<strong>第一个</strong> <code>{}</code>：<code>foo{{bar}}zap</code> hash 的是 <code>{bar}zap</code></li>
<li class="">空 <code>{}</code> 忽略</li>
<li class=""><strong>禁忌</strong>：避免 <code>{global}</code> 这种全局 tag（热点 shard）；按业务 ID 散开</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="34-实际应用举例">3.4 实际应用举例<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#34-%E5%AE%9E%E9%99%85%E5%BA%94%E7%94%A8%E4%B8%BE%E4%BE%8B" class="hash-link" aria-label="3.4 实际应用举例的直接链接" title="3.4 实际应用举例的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 限流（原子 INCR + EXPIRE）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">RATE_KEY </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:#e3116c">f"ratelimit:{{</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">user_id</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">}}:1m"</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># {1000}:1m</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">pipe </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> redis</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">pipeline</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">pipe</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">incr</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">RATE_KEY</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">pipe</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">expire</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">RATE_KEY</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">60</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">count</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> _ </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> pipe</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">execute</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 分布式锁（带随机 token + Lua 释放）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">LOCK_KEY </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:#e3116c">f"lock:order:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">order_id</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">TOKEN </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> uuid4</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token builtin">hex</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">redis</span><span class="token punctuation" style="color:#393A34">.</span><span class="token builtin">set</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">LOCK_KEY</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> TOKEN</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> nx</span><span class="token operator" style="color:#393A34">=</span><span class="token boolean" style="color:#36acaa">True</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> ex</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">10</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 释放用 Lua 脚本保证「只删自己持有的锁」</span><br></div></code></pre></div></div>
<p>完整示例：<code>example/db-design/redis_key_examples.py</code></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-mongodb-schema-设计">4. MongoDB Schema 设计<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#4-mongodb-schema-%E8%AE%BE%E8%AE%A1" class="hash-link" aria-label="4. MongoDB Schema 设计的直接链接" title="4. MongoDB Schema 设计的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-嵌入-vs-引用决策矩阵">4.1 嵌入 vs 引用决策矩阵<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#41-%E5%B5%8C%E5%85%A5-vs-%E5%BC%95%E7%94%A8%E5%86%B3%E7%AD%96%E7%9F%A9%E9%98%B5" class="hash-link" aria-label="4.1 嵌入 vs 引用决策矩阵的直接链接" title="4.1 嵌入 vs 引用决策矩阵的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>关系</th><th>嵌入</th><th>引用</th></tr></thead><tbody><tr><td>1:1</td><td>✅</td><td>极少</td></tr><tr><td>1:少（few）</td><td>✅</td><td>视查询模式</td></tr><tr><td>1:多（many）</td><td>❌</td><td>✅</td></tr><tr><td>多:多</td><td>❌</td><td>✅（用 array of refs）</td></tr></tbody></table>
<p><strong>嵌入的条件</strong>：读写一起、数据有界、文档大小可控（&lt; 16 MB）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="42-mongodb-官方-6-大模式速查">4.2 MongoDB 官方 6 大模式速查<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#42-mongodb-%E5%AE%98%E6%96%B9-6-%E5%A4%A7%E6%A8%A1%E5%BC%8F%E9%80%9F%E6%9F%A5" class="hash-link" aria-label="4.2 MongoDB 官方 6 大模式速查的直接链接" title="4.2 MongoDB 官方 6 大模式速查的直接链接" translate="no">​</a></h3>








































<table><thead><tr><th>模式</th><th>用途</th><th>典型场景</th></tr></thead><tbody><tr><td><strong>Subset</strong></td><td>主文档只存最常用字段子集</td><td>商品列表只存 name / price，详细页再查</td></tr><tr><td><strong>Extended Reference</strong></td><td>引用对象 + 复制少量常用字段</td><td>订单复制 user 的 name / phone 避免 join</td></tr><tr><td><strong>Bucket</strong></td><td>时序分桶（按时间窗口）</td><td>IoT 设备 1 分钟 1 个 bucket</td></tr><tr><td><strong>Outlier</strong></td><td>异常大对象单独存</td><td>99% 帖子 &lt; 10 KB，1% 是 5 MB 长文</td></tr><tr><td><strong>Computed</strong></td><td>预计算冗余字段</td><td>评论数 +1 写入（避免每次 count）</td></tr><tr><td><strong>Tree</strong></td><td>树形结构</td><td>评论 / 分类树用 Materialized Path</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="43-反模式绝对不要做">4.3 反模式（绝对不要做）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#43-%E5%8F%8D%E6%A8%A1%E5%BC%8F%E7%BB%9D%E5%AF%B9%E4%B8%8D%E8%A6%81%E5%81%9A" class="hash-link" aria-label="4.3 反模式（绝对不要做）的直接链接" title="4.3 反模式（绝对不要做）的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ <strong>无界数组</strong>：数组持续增长 → document 持续迁移 → 性能崩塌（最常见坑）</li>
<li class="">❌ <strong>巨量 collection</strong>：一个用户 / 租户一个 collection（应该加 <code>tenantId</code> 字段 + 索引分区）</li>
<li class="">❌ <strong>缺索引</strong>：每个查询字段（外键、过滤、排序）必须有索引</li>
<li class="">❌ <strong>把 MongoDB 当关系库用</strong>：坚持 join / 事务，丢失文档库优势</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="44-索引建议">4.4 索引建议<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#44-%E7%B4%A2%E5%BC%95%E5%BB%BA%E8%AE%AE" class="hash-link" aria-label="4.4 索引建议的直接链接" title="4.4 索引建议的直接链接" translate="no">​</a></h3>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// 单字段</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">db</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">users</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">createIndex</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">email</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">unique</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">true</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// 复合索引（注意 ESR 原则：Equality → Sort → Range）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">db</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">orders</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">createIndex</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">user_id</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">status</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">created_at</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token number" style="color:#36acaa">1</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// 部分索引（只索引部分文档）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">db</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">orders</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">createIndex</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">created_at</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token number" style="color:#36acaa">1</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">partialFilterExpression</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">status</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"active"</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// TTL 索引（自动过期）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">db</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">sessions</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">createIndex</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">created_at</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token literal-property property" style="color:#36acaa">expireAfterSeconds</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3600</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-慢-sql-排查与索引优化">5. 慢 SQL 排查与索引优化<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#5-%E6%85%A2-sql-%E6%8E%92%E6%9F%A5%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96" class="hash-link" aria-label="5. 慢 SQL 排查与索引优化的直接链接" title="5. 慢 SQL 排查与索引优化的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-数据库层mysql-慢日志">5.1 数据库层：MySQL 慢日志<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#51-%E6%95%B0%E6%8D%AE%E5%BA%93%E5%B1%82mysql-%E6%85%A2%E6%97%A5%E5%BF%97" class="hash-link" aria-label="5.1 数据库层：MySQL 慢日志的直接链接" title="5.1 数据库层：MySQL 慢日志的直接链接" translate="no">​</a></h3>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># my.cnf</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">slow_query_log</span><span class="token plain">                  </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">1</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">slow_query_log_file</span><span class="token plain">             </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">/var/log/mysql/slow.log</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">long_query_time</span><span class="token plain">                 </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">2          # 秒，默认 10 太松</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">log_queries_not_using_indexes</span><span class="token plain">   </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">1          # 没走索引也记</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">min_examined_row_limit</span><span class="token plain">          </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">100        # 扫描行太少不算</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">log_output</span><span class="token plain">                      </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">FILE       # 或 TABLE（写 mysql.slow_log）</span><br></div></code></pre></div></div>
<p>运行时开启：</p>
<div class="language-sql codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sql codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">SET</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">GLOBAL</span><span class="token plain"> slow_query_log </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">SET</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">GLOBAL</span><span class="token plain"> long_query_time </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">SET</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">GLOBAL</span><span class="token plain"> log_queries_not_using_indexes </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1</span><span class="token punctuation" style="color:#393A34">;</span><br></div></code></pre></div></div>
<p>分析工具：</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 内置（最常用入门）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">mysqldumpslow </span><span class="token parameter variable" style="color:#36acaa">-s</span><span class="token plain"> c </span><span class="token parameter variable" style="color:#36acaa">-t</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">20</span><span class="token plain"> /var/log/mysql/slow.log    </span><span class="token comment" style="color:#999988;font-style:italic"># 调用次数 Top 20</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">mysqldumpslow </span><span class="token parameter variable" style="color:#36acaa">-s</span><span class="token plain"> at </span><span class="token parameter variable" style="color:#36acaa">-t</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"> /var/log/mysql/slow.log   </span><span class="token comment" style="color:#999988;font-style:italic"># 平均耗时 Top 10</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Percona Toolkit（更强，推荐生产用）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">pt-query-digest /var/log/mysql/slow.log </span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> digest.txt</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-数据库层postgresql-pg_stat_statements">5.2 数据库层：PostgreSQL pg_stat_statements<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#52-%E6%95%B0%E6%8D%AE%E5%BA%93%E5%B1%82postgresql-pg_stat_statements" class="hash-link" aria-label="5.2 数据库层：PostgreSQL pg_stat_statements的直接链接" title="5.2 数据库层：PostgreSQL pg_stat_statements的直接链接" translate="no">​</a></h3>
<p><strong>优势：无需开启慢日志</strong>，聚合等价 SQL（字面量归一为 <code>$1</code>），直接 <code>SELECT</code> 排序。</p>
<p>启用：</p>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># postgresql.conf + 重启</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">shared_preload_libraries</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">'</span><span class="token value attr-value inner-value" style="color:#e3116c">pg_stat_statements</span><span class="token value attr-value" style="color:#e3116c">'</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">pg_stat_statements.max</span><span class="token plain">   </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">10000</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">pg_stat_statements.track</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">top</span><br></div></code></pre></div></div>
<div class="language-sql codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sql codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">CREATE</span><span class="token plain"> EXTENSION pg_stat_statements</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">-- Top 5 慢查询</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">SELECT</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">round</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">(</span><span class="token number" style="color:#36acaa">100</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> total_exec_time </span><span class="token operator" style="color:#393A34">/</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">SUM</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">total_exec_time</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">OVER</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">::</span><span class="token keyword" style="color:#00009f">numeric</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">AS</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">percent</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       calls</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       </span><span class="token function" style="color:#d73a49">round</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">mean_exec_time::</span><span class="token keyword" style="color:#00009f">numeric</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">AS</span><span class="token plain"> mean_ms</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       query</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token keyword" style="color:#00009f">FROM</span><span class="token plain"> pg_stat_statements</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">ORDER</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">BY</span><span class="token plain"> total_exec_time </span><span class="token keyword" style="color:#00009f">DESC</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">LIMIT</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">5</span><span class="token punctuation" style="color:#393A34">;</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-应用层sqlalchemy-慢查询埋点fastapi-推荐">5.3 应用层：SQLAlchemy 慢查询埋点（FastAPI 推荐）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#53-%E5%BA%94%E7%94%A8%E5%B1%82sqlalchemy-%E6%85%A2%E6%9F%A5%E8%AF%A2%E5%9F%8B%E7%82%B9fastapi-%E6%8E%A8%E8%8D%90" class="hash-link" aria-label="5.3 应用层：SQLAlchemy 慢查询埋点（FastAPI 推荐）的直接链接" title="5.3 应用层：SQLAlchemy 慢查询埋点（FastAPI 推荐）的直接链接" translate="no">​</a></h3>
<p>数据库层慢日志是「事后」工具；<strong>应用层埋点能拿到业务上下文</strong>（哪个 endpoint、哪个 user、哪个 trace_id）。</p>
<p>完整示例：<code>example/db-design/slow_query_logger.py</code></p>
<p>核心思路（SQLAlchemy Core / ORM 共用 Engine event）：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> sqlalchemy </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> create_engine</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> event</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> logging</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">engine </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> create_engine</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"postgresql+psycopg2://..."</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token decorator annotation punctuation" style="color:#393A34">@event</span><span class="token decorator annotation punctuation" style="color:#393A34">.</span><span class="token decorator annotation punctuation" style="color:#393A34">listens_for</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">engine</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"before_cursor_execute"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">_before</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">conn</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> cursor</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> statement</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> parameters</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> context</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> executemany</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    context</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">_query_start_time </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">perf_counter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token decorator annotation punctuation" style="color:#393A34">@event</span><span class="token decorator annotation punctuation" style="color:#393A34">.</span><span class="token decorator annotation punctuation" style="color:#393A34">listens_for</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">engine</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"after_cursor_execute"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">_after</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">conn</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> cursor</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> statement</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> parameters</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> context</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> executemany</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    elapsed_ms </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">perf_counter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token plain"> context</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">_query_start_time</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1000</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> elapsed_ms </span><span class="token operator" style="color:#393A34">&gt;=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">200</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain">                   </span><span class="token comment" style="color:#999988;font-style:italic"># 阈值，业界常用 200ms 报警 / 1s P0</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        logging</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">warning</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"slow query (%.1f ms): %s"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> elapsed_ms</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> statement</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<p>ORM 层补充（SQLAlchemy 2.0）：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> sqlalchemy</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">orm </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> Session</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token decorator annotation punctuation" style="color:#393A34">@event</span><span class="token decorator annotation punctuation" style="color:#393A34">.</span><span class="token decorator annotation punctuation" style="color:#393A34">listens_for</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">Session</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"do_orm_execute"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">_slow_orm</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">state</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    start </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">perf_counter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    state</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">invoke_statement</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    elapsed </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">perf_counter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token plain"> start</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1000</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> elapsed </span><span class="token operator" style="color:#393A34">&gt;=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">200</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        logging</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">warning</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"slow ORM (%.1f ms): %s"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> elapsed</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> state</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">statement</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<p><strong>注意</strong>：<code>do_orm_execute</code> 不包含 flush 阶段的 SQL；flush 用 <code>before_cursor_execute</code> 兜底。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="54-阈值参考业界常用">5.4 阈值参考（业界常用）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#54-%E9%98%88%E5%80%BC%E5%8F%82%E8%80%83%E4%B8%9A%E7%95%8C%E5%B8%B8%E7%94%A8" class="hash-link" aria-label="5.4 阈值参考（业界常用）的直接链接" title="5.4 阈值参考（业界常用）的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>阈值</th><th>等级</th></tr></thead><tbody><tr><td>&gt; 100 ms</td><td>一般查询警告</td></tr><tr><td>&gt; 200 ms</td><td>慢查询埋点</td></tr><tr><td>&gt; 500 ms</td><td>性能问题</td></tr><tr><td>&gt; 1 s</td><td>P0 工单</td></tr><tr><td>&gt; 3 s</td><td>几乎一定有索引问题</td></tr></tbody></table>
<p>阈值根据业务调整（OLTP 200ms，OLAP 数秒级合理）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="55-explain-分析mysql--postgresql-通用">5.5 EXPLAIN 分析（MySQL / PostgreSQL 通用）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#55-explain-%E5%88%86%E6%9E%90mysql--postgresql-%E9%80%9A%E7%94%A8" class="hash-link" aria-label="5.5 EXPLAIN 分析（MySQL / PostgreSQL 通用）的直接链接" title="5.5 EXPLAIN 分析（MySQL / PostgreSQL 通用）的直接链接" translate="no">​</a></h3>
<p>拿到慢 SQL 后第一步是 <code>EXPLAIN</code>：</p>
<div class="language-sql codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sql codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">EXPLAIN</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">SELECT</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">FROM</span><span class="token plain"> orders </span><span class="token keyword" style="color:#00009f">WHERE</span><span class="token plain"> user_id </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">1000</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">AND</span><span class="token plain"> created_at </span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">'2026-01-01'</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">ORDER</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">BY</span><span class="token plain"> id</span><span class="token punctuation" style="color:#393A34">;</span><br></div></code></pre></div></div>
<p>关键看：</p>






























<table><thead><tr><th>字段</th><th>含义</th><th>危险信号</th></tr></thead><tbody><tr><td><code>type</code></td><td>访问类型</td><td><code>ALL</code> = 全表扫描 = 缺索引</td></tr><tr><td><code>key</code></td><td>实际使用的索引</td><td><code>NULL</code> = 没走索引</td></tr><tr><td><code>rows</code></td><td>预估扫描行数</td><td>远大于实际返回 = 索引选错</td></tr><tr><td><code>Extra</code></td><td>附加信息</td><td><code>Using filesort</code> / <code>Using temporary</code> / <code>Using where</code> 无 <code>Using index</code></td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="56-索引决策流程">5.6 索引决策流程<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#56-%E7%B4%A2%E5%BC%95%E5%86%B3%E7%AD%96%E6%B5%81%E7%A8%8B" class="hash-link" aria-label="5.6 索引决策流程的直接链接" title="5.6 索引决策流程的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">发现慢 SQL</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">EXPLAIN 看执行计划</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">判断：</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── type=ALL 且 rows 巨大 → 缺索引，加索引</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── type=range 但 Extra 有 filesort → 复合索引顺序错（排序字段加索引列末位）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── type=index 但慢 → 索引列选择性差（基数太低），考虑删除或换列</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 已用索引但仍慢 → 看是否回表过多（覆盖索引 / 索引下推 ICP）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└── 大数据量 → 考虑分库分表 / 读写分离</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-加索引走代码层-alembic-migration不走裸-sql">6. 加索引：走代码层 Alembic Migration，不走裸 SQL<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#6-%E5%8A%A0%E7%B4%A2%E5%BC%95%E8%B5%B0%E4%BB%A3%E7%A0%81%E5%B1%82-alembic-migration%E4%B8%8D%E8%B5%B0%E8%A3%B8-sql" class="hash-link" aria-label="6. 加索引：走代码层 Alembic Migration，不走裸 SQL的直接链接" title="6. 加索引：走代码层 Alembic Migration，不走裸 SQL的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-为什么必须走-alembic业界共识">6.1 为什么必须走 Alembic（业界共识）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#61-%E4%B8%BA%E4%BB%80%E4%B9%88%E5%BF%85%E9%A1%BB%E8%B5%B0-alembic%E4%B8%9A%E7%95%8C%E5%85%B1%E8%AF%86" class="hash-link" aria-label="6.1 为什么必须走 Alembic（业界共识）的直接链接" title="6.1 为什么必须走 Alembic（业界共识）的直接链接" translate="no">​</a></h3>


























<table><thead><tr><th>方式</th><th>DDL 进版本控制</th><th>团队协作</th><th>升级 / 回滚对称</th><th>生产事故</th></tr></thead><tbody><tr><td><strong>Alembic migration</strong></td><td>✅</td><td>✅</td><td>✅</td><td>可回滚</td></tr><tr><td>裸 SQL / Navicat 直接改库</td><td>❌</td><td>❌ 别人不知道</td><td>❌</td><td>上线后才发现，灾难</td></tr></tbody></table>
<p><strong>反例</strong>：开发 A 用裸 SQL 在生产加了索引，开发 B 跑 <code>alembic upgrade</code> 时会因索引已存在而失败（或反之，索引漏加导致线上慢 SQL）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-alembic-索引操作速查">6.2 Alembic 索引操作速查<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#62-alembic-%E7%B4%A2%E5%BC%95%E6%93%8D%E4%BD%9C%E9%80%9F%E6%9F%A5" class="hash-link" aria-label="6.2 Alembic 索引操作速查的直接链接" title="6.2 Alembic 索引操作速查的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># alembic/versions/xxxx_add_orders_user_created_idx.py</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> alembic </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> op</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> sqlalchemy </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> text</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">upgrade</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 单列索引</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">create_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"ix_orders_user_id"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"orders"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"user_id"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 复合索引（顺序：等值字段 → 排序字段 → 范围字段）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">create_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"ix_orders_user_created"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"orders"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"user_id"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"created_at"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 唯一索引</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">create_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"ix_users_phone"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"users"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"phone"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> unique</span><span class="token operator" style="color:#393A34">=</span><span class="token boolean" style="color:#36acaa">True</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 函数索引</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">create_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"ix_users_email_lower"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"users"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain">text</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"lower(email)"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 条件索引（PG）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># op.execute("CREATE INDEX ix_orders_active ON orders (created_at) WHERE status = 'active';")</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">downgrade</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 必须对称，否则回滚失败</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">drop_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"ix_orders_user_id"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> table_name</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"orders"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">drop_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"ix_orders_user_created"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> table_name</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"orders"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">drop_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"ix_users_phone"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> table_name</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"users"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">drop_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"ix_users_email_lower"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> table_name</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"users"</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<p><strong>SQLite 注意点</strong>：SQLite 对 <code>ALTER TABLE</code> 支持有限，DDL 用 <code>batch_alter_table</code>：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">with</span><span class="token plain"> op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">batch_alter_table</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"users"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">as</span><span class="token plain"> batch_op</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    batch_op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">create_index</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"ix_users_email"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"email"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-完整脚本示例从慢-sql-到加索引">6.3 完整脚本示例（从慢 SQL 到加索引）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#63-%E5%AE%8C%E6%95%B4%E8%84%9A%E6%9C%AC%E7%A4%BA%E4%BE%8B%E4%BB%8E%E6%85%A2-sql-%E5%88%B0%E5%8A%A0%E7%B4%A2%E5%BC%95" class="hash-link" aria-label="6.3 完整脚本示例（从慢 SQL 到加索引）的直接链接" title="6.3 完整脚本示例（从慢 SQL 到加索引）的直接链接" translate="no">​</a></h3>
<p>完整可读脚本：<code>example/db-design/alembic_add_index.py</code></p>
<p>展示真实场景：</p>
<blockquote>
<p><strong>场景</strong>：运营报障「我的订单列表加载慢」，抓到的慢 SQL：</p>
<div class="language-sql codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sql codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">SELECT</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">FROM</span><span class="token plain"> orders </span><span class="token keyword" style="color:#00009f">WHERE</span><span class="token plain"> user_id </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">12345</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">ORDER</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">BY</span><span class="token plain"> created_at </span><span class="token keyword" style="color:#00009f">DESC</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">LIMIT</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">20</span><span class="token punctuation" style="color:#393A34">;</span><br></div></code></pre></div></div>
<p>EXPLAIN 发现 <code>type=ALL</code>，扫 50 万行。决定加复合索引 <code>(user_id, created_at)</code>。</p>
</blockquote>
<p>完整 alembic revision 文件见 demo。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="64-大表在线加索引生产必备">6.4 大表在线加索引（生产必备）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#64-%E5%A4%A7%E8%A1%A8%E5%9C%A8%E7%BA%BF%E5%8A%A0%E7%B4%A2%E5%BC%95%E7%94%9F%E4%BA%A7%E5%BF%85%E5%A4%87" class="hash-link" aria-label="6.4 大表在线加索引（生产必备）的直接链接" title="6.4 大表在线加索引（生产必备）的直接链接" translate="no">​</a></h3>
<p>直接 <code>CREATE INDEX</code> 在大表上会<strong>长时间锁表</strong>（MySQL 5.6 之前 = 全程锁，PG = <code>CONCURRENTLY</code> 选项）。生产常用：</p>






























<table><thead><tr><th>数据库</th><th>工具 / 选项</th><th>原理</th></tr></thead><tbody><tr><td>MySQL</td><td><code>pt-online-schema-change</code>（Percona）</td><td>建影子表 + 触发器 + 增量拷贝</td></tr><tr><td>MySQL</td><td><code>gh-ost</code>（GitHub）</td><td>binlog + 影子表，无触发器</td></tr><tr><td>MySQL</td><td><code>ALTER TABLE ... ALGORITHM=INPLACE, LOCK=NONE</code>（5.6+）</td><td>部分索引支持在线</td></tr><tr><td>PostgreSQL</td><td><code>CREATE INDEX CONCURRENTLY</code></td><td>不锁表，但 alembic 内要特殊处理</td></tr></tbody></table>
<p><strong>Alembic + PG CONCURRENTLY</strong> 注意事项：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># Alembic 默认每个 migration 一个事务，CONCURRENTLY 不能在事务里</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># alembic.ini:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># transaction_per_ddl = False</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 或者用 op.execute("COMMIT") 切事务</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">execute</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"COMMIT"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">op</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">execute</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"CREATE INDEX CONCURRENTLY ix_orders_user_created ON orders (user_id, created_at)"</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="65-索引禁忌不要做的事">6.5 索引禁忌（不要做的事）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#65-%E7%B4%A2%E5%BC%95%E7%A6%81%E5%BF%8C%E4%B8%8D%E8%A6%81%E5%81%9A%E7%9A%84%E4%BA%8B" class="hash-link" aria-label="6.5 索引禁忌（不要做的事）的直接链接" title="6.5 索引禁忌（不要做的事）的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>反模式</th><th>后果</th><th>替代方案</th></tr></thead><tbody><tr><td>给低基数列加索引（<code>gender</code>、<code>is_deleted</code> boolean）</td><td>索引选择性差，几乎没用</td><td>用复合索引带上</td></tr><tr><td>单表索引 &gt; 5~6 个</td><td>写放大（每次 INSERT/UPDATE 维护所有索引）</td><td>看慢 SQL 按需加，定期清理未用索引</td></tr><tr><td>索引列做函数 / 类型转换</td><td>索引失效</td><td>用函数索引 / 改 SQL</td></tr><tr><td>不看 EXPLAIN 盲目加</td><td>可能加错索引 / 加重复索引</td><td>先 EXPLAIN，再决定</td></tr><tr><td>每次 release 都加索引</td><td>索引膨胀</td><td>加索引前先看是否有现成的能用</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="66-加索引-checklist">6.6 加索引 checklist<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#66-%E5%8A%A0%E7%B4%A2%E5%BC%95-checklist" class="hash-link" aria-label="6.6 加索引 checklist的直接链接" title="6.6 加索引 checklist的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 慢 SQL 已用 pt-query-digest / pg_stat_statements 确认是热点</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] EXPLAIN 已看，确认 type=ALL / rows 巨大 / 没走索引</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 复合索引顺序已按 ESR 原则（等值 → 排序 → 范围）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 唯一索引确认 DB 现有数据无重复</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 大表确认是否走在线 DDL（pt-osc / gh-ost / CONCURRENTLY）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] migration 脚本已写完整的 downgrade</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 已在测试环境跑过 upgrade + downgrade</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 已在 staging 观察索引生效、慢 SQL 消失</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[ ] 已通知 DBA / 团队 review migration</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关联笔记">关联笔记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1%E4%B8%8E%E7%B4%A2%E5%BC%95%E4%BC%98%E5%8C%96%E7%AC%94%E8%AE%B0#%E5%85%B3%E8%81%94%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="关联笔记的直接链接" title="关联笔记的直接链接" translate="no">​</a></h2>
<ul>
<li class="">关系型数据库：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/mysql">MySQL笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/postgresql">PostgreSQL笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/sqlite">SQLite笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E5%85%B3%E7%B3%BB%E5%9E%8B%E6%95%B0%E6%8D%AE%E5%BA%93%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0">关系型数据库选型对比笔记</a></li>
<li class="">NoSQL：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/mongodb">MongoDB笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/redis">Redis笔记</a></li>
<li class="">Web 框架：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/fastapi">FastAPI笔记</a></li>
<li class="">Demo：
<ul>
<li class=""><code>example/db-design/slow_query_logger.py</code>（SQLAlchemy 慢查询埋点）</li>
<li class=""><code>example/db-design/alembic_add_index.py</code>（加索引完整 alembic revision）</li>
<li class=""><code>example/db-design/redis_key_examples.py</code>（7 种典型 key 模板 + Hash Tag）</li>
</ul>
</li>
</ul>
<p>标签：#mysql #postgres #redis</p>]]></content>
        <category label="MySQL" term="MySQL"/>
        <category label="PostgreSQL" term="PostgreSQL"/>
        <category label="Redis" term="Redis"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[权限模型笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/权限模型与Casbin实践笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/权限模型与Casbin实践笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[原 旧稿（RBAC / ABAC / ReBAC 三模型对比）的重写。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>原 旧稿（RBAC / ABAC / ReBAC 三模型对比）的重写。
原笔记是定性对比，本笔记在此基础上<strong>补充 Casbin 库的落地实现</strong>（Python 版 PERM 模型、policy 文件、FastAPI 集成、RBAC with Domains、ReBAC 关系建模），让模型能真正用起来。</p>
<p>登录与鉴权流程见 <code>[[鉴权与登录笔记]]</code>。
网关中的鉴权中间件见 <code>[[API网关原理与选型笔记]]</code>。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录">目录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#%E7%9B%AE%E5%BD%95" class="hash-link" aria-label="目录的直接链接" title="目录的直接链接" translate="no">​</a></h2>
<ol>
<li class="">三模型对比（RBAC / ReBAC / ABAC）</li>
<li class="">RBAC 模型详解</li>
<li class="">ReBAC 模型详解</li>
<li class="">ABAC 模型简述</li>
<li class="">Casbin 库核心（Python 版）</li>
<li class="">RBAC 最小可运行示例（含角色继承）</li>
<li class="">RBAC with Domains（多租户）</li>
<li class="">ReBAC 关系建模（Casbin g2）</li>
<li class="">RESTful 路径权限检查（keyMatch2）</li>
<li class="">Casbin 在 FastAPI 中集成</li>
<li class="">实战：RBAC + ReBAC 混合</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-三模型对比rbac--rebac--abac">1. 三模型对比（RBAC / ReBAC / ABAC）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#1-%E4%B8%89%E6%A8%A1%E5%9E%8B%E5%AF%B9%E6%AF%94rbac--rebac--abac" class="hash-link" aria-label="1. 三模型对比（RBAC / ReBAC / ABAC）的直接链接" title="1. 三模型对比（RBAC / ReBAC / ABAC）的直接链接" translate="no">​</a></h2>





























<table><thead><tr><th>模型</th><th>一句话</th><th>典型问题</th><th>典型场景</th></tr></thead><tbody><tr><td><strong>RBAC</strong></td><td>你<strong>是什么身份</strong></td><td>你是不是管理员？</td><td>后台菜单 / 按钮权限 / 组织架构</td></tr><tr><td><strong>ReBAC</strong></td><td>你<strong>和它什么关系</strong></td><td>你是这个文档的 owner 吗？</td><td>协作 / 项目 / 社交</td></tr><tr><td><strong>ABAC</strong></td><td>你<strong>满足什么条件</strong></td><td>你是不是这个部门 + 当前是工作时间？</td><td>数据权限 / 部门隔离 / 时段限制</td></tr></tbody></table>
<p><strong>口诀</strong>：</p>
<ul>
<li class="">RBAC → <strong>身份 / 角色</strong></li>
<li class="">ReBAC → <strong>关系 / 邻居</strong></li>
<li class="">ABAC → <strong>属性 / 规则</strong></li>
</ul>
<p><strong>现实项目里很少只用一种</strong>：</p>





















<table><thead><tr><th>场景</th><th>组合</th></tr></thead><tbody><tr><td>企业后台</td><td>RBAC（菜单/按钮） + ABAC（数据范围）</td></tr><tr><td>多租户协作</td><td>RBAC（平台角色） + ReBAC（项目成员）</td></tr><tr><td>复杂 SaaS</td><td>RBAC + ABAC + ReBAC 三者混合</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-rbac-模型详解">2. RBAC 模型详解<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#2-rbac-%E6%A8%A1%E5%9E%8B%E8%AF%A6%E8%A7%A3" class="hash-link" aria-label="2. RBAC 模型详解的直接链接" title="2. RBAC 模型详解的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="21-三层结构">2.1 三层结构<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#21-%E4%B8%89%E5%B1%82%E7%BB%93%E6%9E%84" class="hash-link" aria-label="2.1 三层结构的直接链接" title="2.1 三层结构的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">用户 ──绑定──► 角色 ──绑定──► 权限</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Alice ──► admin ──► [删除用户, 管理订单, 查看报表]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Bob   ──► editor ──► [创建文章, 修改文章]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Tom   ──► viewer ──► [查看文章]</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="22-角色继承">2.2 角色继承<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#22-%E8%A7%92%E8%89%B2%E7%BB%A7%E6%89%BF" class="hash-link" aria-label="2.2 角色继承的直接链接" title="2.2 角色继承的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">admin ──继承──► user</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">editor ──继承──► user</span><br></div></code></pre></div></div>
<p><code>admin</code> 自动拥有 <code>user</code> 的所有权限，不必重复配置。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="23-为什么-rbac-是后台系统的默认选择">2.3 为什么 RBAC 是后台系统的默认选择<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#23-%E4%B8%BA%E4%BB%80%E4%B9%88-rbac-%E6%98%AF%E5%90%8E%E5%8F%B0%E7%B3%BB%E7%BB%9F%E7%9A%84%E9%BB%98%E8%AE%A4%E9%80%89%E6%8B%A9" class="hash-link" aria-label="2.3 为什么 RBAC 是后台系统的默认选择的直接链接" title="2.3 为什么 RBAC 是后台系统的默认选择的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>管理简单</strong>：权限挂在角色上，增删用户不动权限</li>
<li class=""><strong>符合直觉</strong>：组织架构天然是角色化（部门 / 职位）</li>
<li class=""><strong>实现成本低</strong>：一张 user_role 表 + 一张 role_permission 表就够</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="24-rbac-不擅长什么">2.4 RBAC 不擅长什么<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#24-rbac-%E4%B8%8D%E6%93%85%E9%95%BF%E4%BB%80%E4%B9%88" class="hash-link" aria-label="2.4 RBAC 不擅长什么的直接链接" title="2.4 RBAC 不擅长什么的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">editor 可以修改文章</span><br></div></code></pre></div></div>
<p>但具体能改哪些文章？RBAC 答不了：</p>
<ul>
<li class="">所有文章？</li>
<li class="">自己部门的？</li>
<li class="">自己创建的？</li>
</ul>
<p><strong>答不了就走 ReBAC 或 ABAC</strong>（见下文）。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-rebac-模型详解">3. ReBAC 模型详解<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#3-rebac-%E6%A8%A1%E5%9E%8B%E8%AF%A6%E8%A7%A3" class="hash-link" aria-label="3. ReBAC 模型详解的直接链接" title="3. ReBAC 模型详解的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-核心思想">3.1 核心思想<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#31-%E6%A0%B8%E5%BF%83%E6%80%9D%E6%83%B3" class="hash-link" aria-label="3.1 核心思想的直接链接" title="3.1 核心思想的直接链接" translate="no">​</a></h3>
<p><strong>权限不是由角色或属性决定，而是由"用户和资源之间的关系"决定。</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">Alice ──[owner]──► doc_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Bob   ──[editor]──► doc_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Carol ──[viewer]──► doc_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Alice ──[member]──► team_A</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">team_A ──[owns]──► project_X</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">project_X ──[contains]──► doc_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        ↓ 推导</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Alice ──[viewer (继承)]──► doc_123   (因为她是 team_A 成员)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-rebac-的直觉理解">3.2 ReBAC 的直觉理解<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#32-rebac-%E7%9A%84%E7%9B%B4%E8%A7%89%E7%90%86%E8%A7%A3" class="hash-link" aria-label="3.2 ReBAC 的直觉理解的直接链接" title="3.2 ReBAC 的直觉理解的直接链接" translate="no">​</a></h3>





















<table><thead><tr><th>模型</th><th>问的问题</th></tr></thead><tbody><tr><td>RBAC</td><td>你是谁？</td></tr><tr><td>ABAC</td><td>你有哪些特征？</td></tr><tr><td>ReBAC</td><td><strong>你和这个对象是什么关系？</strong></td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-典型-rebac-场景">3.3 典型 ReBAC 场景<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#33-%E5%85%B8%E5%9E%8B-rebac-%E5%9C%BA%E6%99%AF" class="hash-link" aria-label="3.3 典型 ReBAC 场景的直接链接" title="3.3 典型 ReBAC 场景的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>场景</th><th>关系</th></tr></thead><tbody><tr><td>协作文档</td><td>owner / editor / viewer</td></tr><tr><td>GitHub 仓库</td><td>member / outside-collaborator</td></tr><tr><td>Notion / 飞书</td><td>workspace member + page permission</td></tr><tr><td>社交</td><td>friend / follower / blocked</td></tr><tr><td>项目</td><td>team member / project owner / approver</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="34-rebac-的关系链推导">3.4 ReBAC 的"关系链推导"<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#34-rebac-%E7%9A%84%E5%85%B3%E7%B3%BB%E9%93%BE%E6%8E%A8%E5%AF%BC" class="hash-link" aria-label="3.4 ReBAC 的&quot;关系链推导&quot;的直接链接" title="3.4 ReBAC 的&quot;关系链推导&quot;的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">用户 --[member]--&gt; 团队</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">团队 --[owns]--&gt; 项目</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">项目 --[contains]--&gt; 仓库</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        ↓ 推导</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">用户对该仓库有 [member] 权限</span><br></div></code></pre></div></div>
<p>这种"从关系图推导权限"是 ReBAC 的核心特点，也是它实现起来比 RBAC 复杂的地方。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-abac-模型简述">4. ABAC 模型简述<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#4-abac-%E6%A8%A1%E5%9E%8B%E7%AE%80%E8%BF%B0" class="hash-link" aria-label="4. ABAC 模型简述的直接链接" title="4. ABAC 模型简述的直接链接" translate="no">​</a></h2>
<p>ABAC 通过<strong>属性规则</strong>动态判断：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">IF user.department == resource.department</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   AND user.level &gt;= 2</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">   AND action == "read"</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">THEN allow</span><br></div></code></pre></div></div>
<p><strong>四类属性</strong>：</p>
<ul>
<li class=""><strong>用户属性</strong>：部门 / 岗位 / 级别 / 地区</li>
<li class=""><strong>资源属性</strong>：创建人 / 所属部门 / 敏感等级 / 状态</li>
<li class=""><strong>操作属性</strong>：read / write / approve</li>
<li class=""><strong>环境属性</strong>：时间 / IP / 地理位置 / 设备</li>
</ul>
<p><strong>适用</strong>：规则复杂多变（金融 / 医疗 / 政务）、需要细粒度条件。</p>
<p><strong>代价</strong>：规则易膨胀，调试难。所以实际项目通常 RBAC 主导 + ABAC 补充。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-casbin-库核心python-版">5. Casbin 库核心（Python 版）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#5-casbin-%E5%BA%93%E6%A0%B8%E5%BF%83python-%E7%89%88" class="hash-link" aria-label="5. Casbin 库核心（Python 版）的直接链接" title="5. Casbin 库核心（Python 版）的直接链接" translate="no">​</a></h2>
<p><a href="https://casbin.apache.org/" target="_blank" rel="noopener noreferrer" class="">Casbin</a> 是一个<strong>通用的授权库</strong>，支持多种模型（RBAC / ABAC / ReBAC / RESTful），多种语言（Go / Java / Python / Node.js / PHP）。</p>
<p><strong>核心思想</strong>：<strong>配置文件定义模型 + 策略文件定义数据</strong>，库帮你做"请求 → 决策"。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-perm-模型policy--effect--request--matchers">5.1 PERM 模型（Policy / Effect / Request / Matchers）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#51-perm-%E6%A8%A1%E5%9E%8Bpolicy--effect--request--matchers" class="hash-link" aria-label="5.1 PERM 模型（Policy / Effect / Request / Matchers）的直接链接" title="5.1 PERM 模型（Policy / Effect / Request / Matchers）的直接链接" translate="no">​</a></h3>
<p>任何 Casbin 模型都包含 4 段：</p>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 1. 请求定义：用户要做什么请求</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">request_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">r</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 2. 策略定义：一条权限规则是什么样子</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">p</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 3. 角色定义（RBAC 用）：用户到角色的映射</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">role_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 4. 匹配器：请求和策略如何匹配（核心规则）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">matchers</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">m</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">g(r.sub, p.sub) &amp;&amp; r.obj == p.obj &amp;&amp; r.act == p.act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 5. 效果：满足策略时的最终决定</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_effect</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">e</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">some(where (p.eft == allow))</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-策略文件">5.2 策略文件<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#52-%E7%AD%96%E7%95%A5%E6%96%87%E4%BB%B6" class="hash-link" aria-label="5.2 策略文件的直接链接" title="5.2 策略文件的直接链接" translate="no">​</a></h3>
<div class="language-csv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-csv codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain"># policy.csv</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, alice, data1, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, bob, data2, write</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, data2_admin, data2, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, data2_admin, data2, write</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, data2_admin        # alice 继承 data2_admin 的所有权限</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-python-api-速查">5.3 Python API 速查<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#53-python-api-%E9%80%9F%E6%9F%A5" class="hash-link" aria-label="5.3 Python API 速查的直接链接" title="5.3 Python API 速查的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> casbin</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> casbin</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Enforcer</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"model.conf"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"policy.csv"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 鉴权（核心）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># True（直接策略）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"write"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic"># True（通过 g 继承）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">         </span><span class="token comment" style="color:#999988;font-style:italic"># False</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 运行时增删策略</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_policy</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"eve"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data3"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">remove_policy</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"eve"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data3"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 角色绑定</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">add_grouping_policy</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data2_admin"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">remove_grouping_policy</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data2_admin"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get_roles_for_user</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">             </span><span class="token comment" style="color:#999988;font-style:italic"># ["data2_admin"]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get_implicit_roles_for_user</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 含继承传递</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get_users_for_role</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"data2_admin"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># ["alice"]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 持久化</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">save_policy</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">                            </span><span class="token comment" style="color:#999988;font-style:italic"># 写回 adapter</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="54-adapter-选型">5.4 Adapter 选型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#54-adapter-%E9%80%89%E5%9E%8B" class="hash-link" aria-label="5.4 Adapter 选型的直接链接" title="5.4 Adapter 选型的直接链接" translate="no">​</a></h3>

























<table><thead><tr><th>Adapter</th><th>适用</th></tr></thead><tbody><tr><td><code>FileAdapter</code>（CSV）</td><td>demo / 小项目</td></tr><tr><td><code>casbin-sqlalchemy-adapter</code></td><td>关系型数据库（推荐生产）</td></tr><tr><td><code>casbin-redis-adapter</code></td><td>高频读 + 集群</td></tr><tr><td><code>casbin-mongodb-adapter</code></td><td>文档型场景</td></tr></tbody></table>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># SQLAlchemy adapter 用法</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> casbin_sqlalchemy_adapter </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> Adapter</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> casbin</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">adapter </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> Adapter</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"postgresql://user:pass@host/db"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> casbin</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Enforcer</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"model.conf"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> adapter</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">load_policy</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">  </span><span class="token comment" style="color:#999988;font-style:italic"># 从 DB 加载</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-rbac-最小可运行示例含角色继承">6. RBAC 最小可运行示例（含角色继承）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#6-rbac-%E6%9C%80%E5%B0%8F%E5%8F%AF%E8%BF%90%E8%A1%8C%E7%A4%BA%E4%BE%8B%E5%90%AB%E8%A7%92%E8%89%B2%E7%BB%A7%E6%89%BF" class="hash-link" aria-label="6. RBAC 最小可运行示例（含角色继承）的直接链接" title="6. RBAC 最小可运行示例（含角色继承）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-modelconf">6.1 <code>model.conf</code><a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#61-modelconf" class="hash-link" aria-label="61-modelconf的直接链接" title="61-modelconf的直接链接" translate="no">​</a></h3>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">request_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">r</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">p</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">role_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_effect</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">e</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">some(where (p.eft == allow))</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">matchers</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">m</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">g(r.sub, p.sub) &amp;&amp; r.obj == p.obj &amp;&amp; r.act == p.act</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-policycsv">6.2 <code>policy.csv</code><a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#62-policycsv" class="hash-link" aria-label="62-policycsv的直接链接" title="62-policycsv的直接链接" translate="no">​</a></h3>
<div class="language-csv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-csv codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">p, alice, data1, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, bob, data2, write</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, data2_admin, data2, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, data2_admin, data2, write</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, data2_admin</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-验证">6.3 验证<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#63-%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="6.3 验证的直接链接" title="6.3 验证的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> casbin</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> casbin</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Enforcer</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"model.conf"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"policy.csv"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># True（直接）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"write"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># True（继承自 data2_admin）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"write"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic"># True（直接）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># False</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-rbac-with-domains多租户">7. RBAC with Domains（多租户）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#7-rbac-with-domains%E5%A4%9A%E7%A7%9F%E6%88%B7" class="hash-link" aria-label="7. RBAC with Domains（多租户）的直接链接" title="7. RBAC with Domains（多租户）的直接链接" translate="no">​</a></h2>
<p><strong>问题</strong>：同一用户在<strong>不同租户</strong>有不同角色（如：Alice 在公司 A 是 admin，在公司 B 只是 user）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-modelconf域扩展">7.1 model.conf（域扩展）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#71-modelconf%E5%9F%9F%E6%89%A9%E5%B1%95" class="hash-link" aria-label="7.1 model.conf（域扩展）的直接链接" title="7.1 model.conf（域扩展）的直接链接" translate="no">​</a></h3>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">request_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">r</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, dom, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">p</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, dom, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">role_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _, _</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_effect</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">e</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">some(where (p.eft == allow))</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">matchers</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">m</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">g(r.sub, p.sub, r.dom) &amp;&amp; r.dom == p.dom &amp;&amp; r.obj == p.obj &amp;&amp; r.act == p.act</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-policycsv">7.2 policy.csv<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#72-policycsv" class="hash-link" aria-label="7.2 policy.csv的直接链接" title="7.2 policy.csv的直接链接" translate="no">​</a></h3>
<div class="language-csv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-csv codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">p, admin, tenant1, data1, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, admin, tenant2, data2, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, user, tenant2, data2, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, admin, tenant1</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, user, tenant2</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, bob, user, tenant2</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="73-验证">7.3 验证<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#73-%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="7.3 验证的直接链接" title="7.3 验证的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"tenant1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># True（admin@tenant1）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"tenant2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># True（user@tenant2）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"tenant2"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># False（tenant1 的 admin 不跨租户）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"tenant1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"data1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># False（bob 不是 tenant1 成员）</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-rebac-关系建模casbin-g2">8. ReBAC 关系建模（Casbin g2）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#8-rebac-%E5%85%B3%E7%B3%BB%E5%BB%BA%E6%A8%A1casbin-g2" class="hash-link" aria-label="8. ReBAC 关系建模（Casbin g2）的直接链接" title="8. ReBAC 关系建模（Casbin g2）的直接链接" translate="no">​</a></h2>
<p>Casbin 默认 <code>g</code> 是用户-角色继承；<strong><code>g2</code> 用于角色-角色继承</strong>，但更常见的用法是<strong>用 g 模拟"对象-关系"</strong>。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-思路把关系建模为-policy">8.1 思路：把"关系"建模为 policy<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#81-%E6%80%9D%E8%B7%AF%E6%8A%8A%E5%85%B3%E7%B3%BB%E5%BB%BA%E6%A8%A1%E4%B8%BA-policy" class="hash-link" aria-label="8.1 思路：把&quot;关系&quot;建模为 policy的直接链接" title="8.1 思路：把&quot;关系&quot;建模为 policy的直接链接" translate="no">​</a></h3>
<div class="language-csv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-csv codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain"># 用户与资源的关系</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, doc_owner, doc_123, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, doc_owner, doc_123, write</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, doc_owner, doc_123, delete</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, doc_editor, doc_123, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, doc_editor, doc_123, write</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, doc_viewer, doc_123, read</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"># 谁是什么关系</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, doc_owner, doc_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, bob, doc_editor, doc_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, carol, doc_viewer, doc_123</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-modelconf">8.2 model.conf<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#82-modelconf" class="hash-link" aria-label="8.2 model.conf的直接链接" title="8.2 model.conf的直接链接" translate="no">​</a></h3>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">request_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">r</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">p</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">role_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _, _        # 用户, 关系角色, 资源</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_effect</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">e</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">some(where (p.eft == allow))</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">matchers</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">m</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">g(r.sub, p.sub, r.obj) &amp;&amp; r.obj == p.obj &amp;&amp; r.act == p.act</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="83-验证">8.3 验证<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#83-%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="8.3 验证的直接链接" title="8.3 验证的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"doc_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"delete"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># True（owner）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"doc_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"write"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic"># True（editor）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"carol"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"doc_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"read"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># True（viewer）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"carol"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"doc_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"write"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># False</span><br></div></code></pre></div></div>
<blockquote>
<p>生产环境关系数量爆炸（每个文档 × 3 种关系），需要把关系存数据库（adapter），
不要写 CSV 文件。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-restful-路径权限检查keymatch2">9. RESTful 路径权限检查（keyMatch2）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#9-restful-%E8%B7%AF%E5%BE%84%E6%9D%83%E9%99%90%E6%A3%80%E6%9F%A5keymatch2" class="hash-link" aria-label="9. RESTful 路径权限检查（keyMatch2）的直接链接" title="9. RESTful 路径权限检查（keyMatch2）的直接链接" translate="no">​</a></h2>
<p><strong>场景</strong>：权限按 URL 路径 + HTTP 方法控制（如 <code>alice</code> 能访问 <code>/api/users/*</code> GET，admin 能访问 <code>/api/*</code> 任意方法）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="91-modelconf">9.1 model.conf<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#91-modelconf" class="hash-link" aria-label="9.1 model.conf的直接链接" title="9.1 model.conf的直接链接" translate="no">​</a></h3>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">request_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">r</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">p</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">role_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_effect</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">e</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">some(where (p.eft == allow))</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">matchers</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">m</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">g(r.sub, p.sub) &amp;&amp; keyMatch2(r.obj, p.obj) &amp;&amp; (r.act == p.act || r.act == "ANY")</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="92-policycsv">9.2 policy.csv<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#92-policycsv" class="hash-link" aria-label="9.2 policy.csv的直接链接" title="9.2 policy.csv的直接链接" translate="no">​</a></h3>
<div class="language-csv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-csv codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">p, alice, /api/users/*, GET</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, bob, /api/orders/*, GET</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, admin, /api/*, ANY</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, admin                # alice 继承 admin 所有权限</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="93-验证">9.3 验证<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#93-%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="9.3 验证的直接链接" title="9.3 验证的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/users/123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"GET"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># True</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/orders/1"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"GET"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic"># True（admin 继承）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/users/123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"GET"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># False</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"admin"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/anything"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"DELETE"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># True（ANY）</span><br></div></code></pre></div></div>
<p><code>keyMatch2</code> 支持的路径模式：</p>
<ul>
<li class=""><code>/foo/:id</code> 匹配 <code>/foo/123</code></li>
<li class=""><code>/foo/*</code> 匹配 <code>/foo/anything/more</code></li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="10-casbin-在-fastapi-中集成">10. Casbin 在 FastAPI 中集成<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#10-casbin-%E5%9C%A8-fastapi-%E4%B8%AD%E9%9B%86%E6%88%90" class="hash-link" aria-label="10. Casbin 在 FastAPI 中集成的直接链接" title="10. Casbin 在 FastAPI 中集成的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="101-单例-enforcer">10.1 单例 Enforcer<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#101-%E5%8D%95%E4%BE%8B-enforcer" class="hash-link" aria-label="10.1 单例 Enforcer的直接链接" title="10.1 单例 Enforcer的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># deps.py</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> casbin</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> functools </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> lru_cache</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token decorator annotation punctuation" style="color:#393A34">@lru_cache</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">get_enforcer</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> casbin</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Enforcer</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> casbin</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Enforcer</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"policy/model.conf"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"policy/policy.csv"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 用 SQLAlchemy adapter</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># from casbin_sqlalchemy_adapter import Adapter</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># @lru_cache()</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># def get_enforcer():</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">#     adapter = Adapter("sqlite:///casbin.db")</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">#     return casbin.Enforcer("policy/model.conf", adapter)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="102-依赖链先鉴权jwt-再鉴权casbin">10.2 依赖链：先鉴权（JWT）→ 再鉴权（Casbin）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#102-%E4%BE%9D%E8%B5%96%E9%93%BE%E5%85%88%E9%89%B4%E6%9D%83jwt-%E5%86%8D%E9%89%B4%E6%9D%83casbin" class="hash-link" aria-label="10.2 依赖链：先鉴权（JWT）→ 再鉴权（Casbin）的直接链接" title="10.2 依赖链：先鉴权（JWT）→ 再鉴权（Casbin）的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># main.py</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> fastapi </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> Depends</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> FastAPI</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> HTTPException</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> deps </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> get_enforcer</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> auth </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> get_current_user          </span><span class="token comment" style="color:#999988;font-style:italic"># 见 [[鉴权与登录笔记]]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">app </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> FastAPI</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">enforcer </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> get_enforcer</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">check_permission</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> act</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> enforcer</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> act</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">raise</span><span class="token plain"> HTTPException</span><span class="token punctuation" style="color:#393A34">(</span><span class="token number" style="color:#36acaa">403</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Forbidden"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token decorator annotation punctuation" style="color:#393A34">@app</span><span class="token decorator annotation punctuation" style="color:#393A34">.</span><span class="token decorator annotation punctuation" style="color:#393A34">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"/api/users/{user_id}"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">get_user</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    user_id</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    user</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> Depends</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">get_current_user</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    check_permission</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">user</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:#e3116c">f"/api/users/</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">user_id</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"GET"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"user_id"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> user_id</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token decorator annotation punctuation" style="color:#393A34">@app</span><span class="token decorator annotation punctuation" style="color:#393A34">.</span><span class="token decorator annotation punctuation" style="color:#393A34">delete</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"/api/users/{user_id}"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">delete_user</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    user_id</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    user</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> Depends</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">get_current_user</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    check_permission</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">user</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string-interpolation string" style="color:#e3116c">f"/api/users/</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">user_id</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"DELETE"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># ... 业务逻辑</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"deleted"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> user_id</span><span class="token punctuation" style="color:#393A34">}</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="103-多租户-casbin">10.3 多租户 Casbin<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#103-%E5%A4%9A%E7%A7%9F%E6%88%B7-casbin" class="hash-link" aria-label="10.3 多租户 Casbin的直接链接" title="10.3 多租户 Casbin的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">check_permission_with_tenant</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> tenant</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> act</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> enforcer</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> tenant</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> obj</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> act</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># 见 §7 模型</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">raise</span><span class="token plain"> HTTPException</span><span class="token punctuation" style="color:#393A34">(</span><span class="token number" style="color:#36acaa">403</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"Forbidden"</span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-实战rbac--rebac-混合">11. 实战：RBAC + ReBAC 混合<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#11-%E5%AE%9E%E6%88%98rbac--rebac-%E6%B7%B7%E5%90%88" class="hash-link" aria-label="11. 实战：RBAC + ReBAC 混合的直接链接" title="11. 实战：RBAC + ReBAC 混合的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="111-场景">11.1 场景<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#111-%E5%9C%BA%E6%99%AF" class="hash-link" aria-label="11.1 场景的直接链接" title="11.1 场景的直接链接" translate="no">​</a></h3>
<p>某 SaaS 平台：</p>
<ul>
<li class="">平台层面：用户有 <strong>admin / member</strong> 角色（RBAC）</li>
<li class="">项目层面：用户与项目有 <strong>owner / collaborator / viewer</strong> 关系（ReBAC）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="112-modelconf同时定义-rbac-和-rebac">11.2 model.conf（同时定义 RBAC 和 ReBAC）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#112-modelconf%E5%90%8C%E6%97%B6%E5%AE%9A%E4%B9%89-rbac-%E5%92%8C-rebac" class="hash-link" aria-label="11.2 model.conf（同时定义 RBAC 和 ReBAC）的直接链接" title="11.2 model.conf（同时定义 RBAC 和 ReBAC）的直接链接" translate="no">​</a></h3>
<div class="language-ini codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ini codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">request_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">r</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">p</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">sub, obj, act</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">role_definition</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _                    # RBAC: 用户 - 平台角色</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">g2</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">_, _, _                # ReBAC: 用户 - 资源关系 - 资源 ID</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">policy_effect</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">e</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">some(where (p.eft == allow))</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token section punctuation" style="color:#393A34">[</span><span class="token section section-name selector" style="color:#00009f">matchers</span><span class="token section punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token key attr-name" style="color:#00a4db">m</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token plain"> </span><span class="token value attr-value" style="color:#e3116c">(g(r.sub, p.sub) || g2(r.sub, p.sub, r.obj)) \</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token key attr-name" style="color:#00a4db">&amp;&amp; r.obj</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token value attr-value" style="color:#e3116c">= p.obj \</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token key attr-name" style="color:#00a4db">&amp;&amp; r.act</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">=</span><span class="token value attr-value" style="color:#e3116c">= p.act</span><br></div></code></pre></div></div>
<blockquote>
<p>含义：用户要么通过平台角色（RBAC）要么通过资源关系（ReBAC）满足权限。</p>
</blockquote>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="113-policycsv">11.3 policy.csv<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#113-policycsv" class="hash-link" aria-label="11.3 policy.csv的直接链接" title="11.3 policy.csv的直接链接" translate="no">​</a></h3>
<div class="language-csv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-csv codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain"># RBAC: 平台角色权限</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, admin, /api/projects/*, ANY</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, member, /api/projects/*, GET</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"># ReBAC: 项目关系 → 项目权限</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, owner, /api/projects/proj_123, ANY</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, collaborator, /api/projects/proj_123, GET</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, collaborator, /api/projects/proj_123, POST</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">p, viewer, /api/projects/proj_123, GET</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"># 平台角色绑定</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g, alice, admin</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"># ReBAC 关系绑定</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g2, alice, owner, proj_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g2, bob, collaborator, proj_123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">g2, carol, viewer, proj_123</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="114-验证">11.4 验证<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#114-%E9%AA%8C%E8%AF%81" class="hash-link" aria-label="11.4 验证的直接链接" title="11.4 验证的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># alice 是 admin，能操作任何项目</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/projects/proj_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"DELETE"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">   </span><span class="token comment" style="color:#999988;font-style:italic"># True（admin）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"alice"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/projects/proj_999"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"POST"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># True（admin）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># bob 是 proj_123 的 collaborator</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/projects/proj_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"POST"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># True（collaborator）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/projects/proj_123"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"DELETE"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">     </span><span class="token comment" style="color:#999988;font-style:italic"># False（collaborator 没 DELETE）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">e</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">enforce</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"bob"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/api/projects/proj_999"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"GET"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">        </span><span class="token comment" style="color:#999988;font-style:italic"># False（不是 proj_999 成员）</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关联笔记">关联笔记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#%E5%85%B3%E8%81%94%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="关联笔记的直接链接" title="关联笔记的直接链接" translate="no">​</a></h2>
<ul>
<li class="">登录鉴权流程（拿到用户身份）：<code>[[鉴权与登录笔记]]</code></li>
<li class="">网关（鉴权中间件放哪）：<code>[[API网关原理与选型笔记]]</code></li>
<li class="">数据库设计（角色表 / 权限表怎么设计）：<code>[[数据库设计与索引优化笔记]]</code></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="demo">Demo<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#demo" class="hash-link" aria-label="Demo的直接链接" title="Demo的直接链接" translate="no">​</a></h2>
<p>完整代码：</p>
<ul>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/policy/model.conf" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/policy/model.conf</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/policy/policy.csv" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/policy/policy.csv</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/auth_demo.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/auth_demo.py</code></a></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="sources">Sources<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%9D%83%E9%99%90%E6%A8%A1%E5%9E%8B%E4%B8%8ECasbin%E5%AE%9E%E8%B7%B5%E7%AC%94%E8%AE%B0#sources" class="hash-link" aria-label="Sources的直接链接" title="Sources的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><a href="https://casbin.apache.org/zh/docs/overview" target="_blank" rel="noopener noreferrer" class="">Casbin 官方文档（Apache）</a></li>
<li class=""><a href="https://casbin.apache.org/zh/docs/rbac-with-domains" target="_blank" rel="noopener noreferrer" class="">Casbin RBAC with Domains</a></li>
<li class=""><a href="https://github.com/casbin/pycasbin" target="_blank" rel="noopener noreferrer" class="">pycasbin GitHub</a></li>
</ul>
<p>标签：#fastapi</p>]]></content>
        <category label="FastAPI" term="FastAPI"/>
        <category label="鉴权" term="鉴权"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[消息队列对比与选型笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/消息队列选型对比笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/消息队列选型对比笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[RabbitMQ vs Kafka 横向对比 + 选型决策 + 可视化平台 + CLI/UI 操作实践。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>RabbitMQ vs Kafka 横向对比 + 选型决策 + 可视化平台 + CLI/UI 操作实践。
单库详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/rabbitmq">RabbitMQ笔记</a> · <a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/kafka">Kafka笔记</a>。
本笔记聚焦"什么场景选哪个"和"生产环境怎么用"，避免把两者当同类产品对比。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录">目录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#%E7%9B%AE%E5%BD%95" class="hash-link" aria-label="目录的直接链接" title="目录的直接链接" translate="no">​</a></h2>
<ol>
<li class="">一句话定位</li>
<li class="">维度对比表</li>
<li class="">性能 / 吞吐对比</li>
<li class="">消息模型本质差异</li>
<li class="">场景选型决策</li>
<li class="">可视化平台对比</li>
<li class="">CLI vs UI 操作实践</li>
<li class="">反向场景 + 共存架构</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-一句话定位">1. 一句话定位<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#1-%E4%B8%80%E5%8F%A5%E8%AF%9D%E5%AE%9A%E4%BD%8D" class="hash-link" aria-label="1. 一句话定位的直接链接" title="1. 一句话定位的直接链接" translate="no">​</a></h2>

















<table><thead><tr><th>消息队列</th><th>一句话</th></tr></thead><tbody><tr><td><strong>RabbitMQ</strong></td><td>复杂路由 + 低延迟 + 传统任务队列的<strong>消息代理</strong>（Broker 范式）</td></tr><tr><td><strong>Kafka</strong></td><td>高吞吐 + 持久化 + 可重放的<strong>分布式日志</strong>（Log 范式）</td></tr></tbody></table>
<p><strong>最本质差异</strong>：RabbitMQ 投递后默认<strong>删除</strong>消息（队列消费）；Kafka 默认<strong>保留</strong>消息（日志消费，consumer 各自维护 offset）。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-维度对比表">2. 维度对比表<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#2-%E7%BB%B4%E5%BA%A6%E5%AF%B9%E6%AF%94%E8%A1%A8" class="hash-link" aria-label="2. 维度对比表的直接链接" title="2. 维度对比表的直接链接" translate="no">​</a></h2>




































































































<table><thead><tr><th>维度</th><th>RabbitMQ</th><th>Kafka</th></tr></thead><tbody><tr><td>架构范式</td><td>消息代理（Broker）</td><td>分布式日志（Log）</td></tr><tr><td>消息模型</td><td>队列（消费后删除）</td><td>日志（保留期 + offset）</td></tr><tr><td>路由能力</td><td>✅ 4 种 Exchange（direct/topic/fanout/headers）</td><td>❌ 仅按 topic + partition</td></tr><tr><td>投递语义</td><td>At-most-once / At-least-once</td><td>At-most-once / At-least-once / <strong>Exactly-Once</strong></td></tr><tr><td>消息保留</td><td>投递后删除</td><td>保留期（默认 7 天，可设数月）</td></tr><tr><td>顺序保证</td><td>单队列单消费者 FIFO</td><td>单 partition 内严格有序</td></tr><tr><td>单机吞吐</td><td>万~十万 QPS</td><td>十万~百万 TPS</td></tr><tr><td>延迟</td><td>微秒~毫秒级</td><td>毫秒~十几毫秒</td></tr><tr><td>协议</td><td>AMQP 0.9.1 / 1.0 / MQTT / STOMP</td><td>自定义二进制协议</td></tr><tr><td>集群协调</td><td>Erlang 分布式（4.0+ Quorum）</td><td>KRaft（4.x）/ ZK（≤3.9）</td></tr><tr><td>持久化</td><td>可选</td><td>始终</td></tr><tr><td>多消费者</td><td>抢消费（一条消息只给一个 consumer）</td><td>各自消费（每 group 一份）</td></tr><tr><td>重放历史</td><td>❌ 不支持</td><td>✅ offset 可回退</td></tr><tr><td>适用规模</td><td>中小规模（百万级 QPS 以下）</td><td>大规模（百万 TPS+）</td></tr><tr><td>运维复杂度</td><td>中（集群 + 镜像）</td><td>中（KRaft / ZK 复杂度转移）</td></tr><tr><td>生态成熟度</td><td>老牌、传统企业广泛使用</td><td>互联网 / 大数据领域事实标准</td></tr><tr><td>客户端库</td><td>所有主流语言</td><td>所有主流语言</td></tr><tr><td>云厂商支持</td><td>AWS MQ / Azure Service Bus</td><td>Confluent Cloud / MSK / 所有云厂</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-性能--吞吐对比">3. 性能 / 吞吐对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#3-%E6%80%A7%E8%83%BD--%E5%90%9E%E5%90%90%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="3. 性能 / 吞吐对比的直接链接" title="3. 性能 / 吞吐对比的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-数量级参考">3.1 数量级参考<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#31-%E6%95%B0%E9%87%8F%E7%BA%A7%E5%8F%82%E8%80%83" class="hash-link" aria-label="3.1 数量级参考的直接链接" title="3.1 数量级参考的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>指标</th><th>RabbitMQ（Quorum Queue 3 节点）</th><th>Kafka（3 broker + RF=3）</th></tr></thead><tbody><tr><td>峰值吞吐</td><td>5~10 万 msg/s</td><td>50~100 万 msg/s</td></tr><tr><td>单消息延迟</td><td>&lt; 1ms</td><td>5~15ms</td></tr><tr><td>消息体大小</td><td>推荐 &lt; 1MB</td><td>推荐 &lt; 1MB（默认 1MB，可调到数 MB）</td></tr><tr><td>堆积能力</td><td>弱（百万级就开始告警）</td><td>强（TB 级常态）</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-性能特征差异">3.2 性能特征差异<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#32-%E6%80%A7%E8%83%BD%E7%89%B9%E5%BE%81%E5%B7%AE%E5%BC%82" class="hash-link" aria-label="3.2 性能特征差异的直接链接" title="3.2 性能特征差异的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>RabbitMQ</strong>：每条消息走队列、ack、DLX 等流程，<strong>单条延迟低</strong>，但堆积后性能急剧下降</li>
<li class=""><strong>Kafka</strong>：顺序写 + 零拷贝 + 页缓存，<strong>批量吞吐高</strong>，延迟主要来自 batch + fsync</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-选型参考">3.3 选型参考<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#33-%E9%80%89%E5%9E%8B%E5%8F%82%E8%80%83" class="hash-link" aria-label="3.3 选型参考的直接链接" title="3.3 选型参考的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>场景</th><th>性能指标</th><th>推荐</th></tr></thead><tbody><tr><td>高频交易（万 TPS + 毫秒延迟）</td><td>延迟 &lt; 10ms</td><td>RabbitMQ</td></tr><tr><td>日志聚合（10 万+ TPS）</td><td>吞吐优先</td><td>Kafka</td></tr><tr><td>事件溯源（消息可重放）</td><td>历史可重读</td><td>Kafka</td></tr><tr><td>复杂任务路由（多 Exchange）</td><td>路由能力</td><td>RabbitMQ</td></tr><tr><td>实时数据管道（流处理）</td><td>吞吐 + 重放</td><td>Kafka</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-消息模型本质差异">4. 消息模型本质差异<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#4-%E6%B6%88%E6%81%AF%E6%A8%A1%E5%9E%8B%E6%9C%AC%E8%B4%A8%E5%B7%AE%E5%BC%82" class="hash-link" aria-label="4. 消息模型本质差异的直接链接" title="4. 消息模型本质差异的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-队列消费rabbitmq">4.1 队列消费（RabbitMQ）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#41-%E9%98%9F%E5%88%97%E6%B6%88%E8%B4%B9rabbitmq" class="hash-link" aria-label="4.1 队列消费（RabbitMQ）的直接链接" title="4.1 队列消费（RabbitMQ）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[Producer] → Exchange → [Queue: msg1, msg2, msg3]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                              ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          Consumer A</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          （msg1 被 ack 后从队列删除）</span><br></div></code></pre></div></div>
<ul>
<li class="">消息<strong>消费后即删除</strong>（ack 后）</li>
<li class="">多个 consumer 抢同一条消息</li>
<li class="">适合<strong>任务分发</strong>（一个任务被一个 worker 消费）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="42-日志消费kafka">4.2 日志消费（Kafka）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#42-%E6%97%A5%E5%BF%97%E6%B6%88%E8%B4%B9kafka" class="hash-link" aria-label="4.2 日志消费（Kafka）的直接链接" title="4.2 日志消费（Kafka）的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[Producer] → Topic partition: [msg0, msg1, msg2, msg3, ...]  (append-only)</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                              ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  Consumer Group A: offset=2</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  Consumer Group B: offset=0</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                  （两个 group 各自维护 offset，互不影响）</span><br></div></code></pre></div></div>
<ul>
<li class="">消息<strong>保留期内不删除</strong></li>
<li class="">多个 Consumer Group 各自维护 offset，<strong>各看各的</strong></li>
<li class="">适合<strong>事件流</strong>（同一事件被多个服务消费：搜索 + 缓存 + 审计）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="43-业务影响">4.3 业务影响<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#43-%E4%B8%9A%E5%8A%A1%E5%BD%B1%E5%93%8D" class="hash-link" aria-label="4.3 业务影响的直接链接" title="4.3 业务影响的直接链接" translate="no">​</a></h3>
<ul>
<li class="">想"消费完删掉" → RabbitMQ</li>
<li class="">想"消费完还能查" → Kafka（offset 可回放、replay 历史）</li>
<li class="">想"一条事件被多服务处理" → Kafka</li>
<li class="">想"一个任务被一个 worker 抢走" → RabbitMQ</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-场景选型决策">5. 场景选型决策<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#5-%E5%9C%BA%E6%99%AF%E9%80%89%E5%9E%8B%E5%86%B3%E7%AD%96" class="hash-link" aria-label="5. 场景选型决策的直接链接" title="5. 场景选型决策的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-决策流程图">5.1 决策流程图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#51-%E5%86%B3%E7%AD%96%E6%B5%81%E7%A8%8B%E5%9B%BE" class="hash-link" aria-label="5.1 决策流程图的直接链接" title="5.1 决策流程图的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">业务核心诉求是什么？</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 复杂路由 / 多 Exchange / 主题分发 ──→ ✅ RabbitMQ</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── RPC 风格 / 同步请求-响应 ──→ ✅ RabbitMQ（原生支持）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 消息保留 + 可重放 + 流处理 ──→ ✅ Kafka</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 事件溯源 / 日志聚合 / CDC ──→ ✅ Kafka</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 延迟敏感（毫秒级） ──→ ✅ RabbitMQ</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 极致吞吐（10 万+ TPS） ──→ ✅ Kafka</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 与大数据生态对接（Spark/Flink） ──→ ✅ Kafka</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">├── 简单任务队列（小规模） ──→ ✅ RabbitMQ（Quorum）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">└── 不确定 ──→ 简单用 RabbitMQ；需要扩展时再考虑 Kafka</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-按场景列表">5.2 按场景列表<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#52-%E6%8C%89%E5%9C%BA%E6%99%AF%E5%88%97%E8%A1%A8" class="hash-link" aria-label="5.2 按场景列表的直接链接" title="5.2 按场景列表的直接链接" translate="no">​</a></h3>




























































<table><thead><tr><th>场景</th><th>推荐</th><th>理由</th></tr></thead><tbody><tr><td>订单 / 支付核心业务</td><td><strong>RabbitMQ</strong></td><td>低延迟、强可靠投递、复杂路由</td></tr><tr><td>异步通知（短信 / 邮件）</td><td><strong>RabbitMQ</strong></td><td>简单、延迟不敏感</td></tr><tr><td>微服务间事件总线</td><td><strong>Kafka</strong></td><td>多服务订阅、消息可重放</td></tr><tr><td>日志聚合</td><td><strong>Kafka</strong></td><td>高吞吐、可被多个消费者解析</td></tr><tr><td>用户行为埋点</td><td><strong>Kafka</strong></td><td>高吞吐、可重放计算</td></tr><tr><td>CDC（数据库变更捕获）</td><td><strong>Kafka</strong></td><td>Debezium → Kafka 是业界标准</td></tr><tr><td>实时流处理</td><td><strong>Kafka</strong></td><td>Flink / Spark Streaming 原生支持</td></tr><tr><td>IoT 设备数据</td><td><strong>Kafka</strong></td><td>高吞吐、消息保留可追溯</td></tr><tr><td>RPC 同步请求</td><td><strong>RabbitMQ</strong></td><td>原生 RPC 支持</td></tr><tr><td>大文件传输</td><td><strong>都不合适</strong></td><td>走对象存储 / 大文件专用通道</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="53-两者共存业界常见">5.3 两者共存（业界常见）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#53-%E4%B8%A4%E8%80%85%E5%85%B1%E5%AD%98%E4%B8%9A%E7%95%8C%E5%B8%B8%E8%A7%81" class="hash-link" aria-label="5.3 两者共存（业界常见）的直接链接" title="5.3 两者共存（业界常见）的直接链接" translate="no">​</a></h3>
<p>大型系统<strong>两个都用</strong>是常态：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[Web 业务] ──→ RabbitMQ（核心交易，复杂路由）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  ├──→ [订单服务]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  ├──→ [库存服务]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                  └──→ [审计服务（同时投递到 Kafka 归档）]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                       Kafka（事件流 / 大数据 / 风控）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          ├──→ [实时风控]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          ├──→ [BI 分析]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          ├──→ [数据湖归档]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                          └──→ [实时推荐]</span><br></div></code></pre></div></div>
<p><strong>典型分层</strong>：</p>
<ul>
<li class="">业务关键路径 → RabbitMQ（强一致）</li>
<li class="">跨域事件流 / 数据管道 → Kafka（高吞吐 + 重放）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-可视化平台对比">6. 可视化平台对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#6-%E5%8F%AF%E8%A7%86%E5%8C%96%E5%B9%B3%E5%8F%B0%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="6. 可视化平台对比的直接链接" title="6. 可视化平台对比的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="61-rabbitmq-工具">6.1 RabbitMQ 工具<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#61-rabbitmq-%E5%B7%A5%E5%85%B7" class="hash-link" aria-label="6.1 RabbitMQ 工具的直接链接" title="6.1 RabbitMQ 工具的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>工具</th><th>类型</th><th>优势</th><th>限制</th></tr></thead><tbody><tr><td><strong>Management UI</strong></td><td>官方自带</td><td>装 RMQ 就有，队列/连接/Channel 可视化</td><td>大集群性能差</td></tr><tr><td><strong>Prometheus + Grafana</strong></td><td>监控</td><td>指标丰富、告警灵活</td><td>需自建</td></tr><tr><td><strong>rabbitmqadmin</strong></td><td>CLI</td><td>批量操作、API 化</td><td>学习曲线</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="62-kafka-工具">6.2 Kafka 工具<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#62-kafka-%E5%B7%A5%E5%85%B7" class="hash-link" aria-label="6.2 Kafka 工具的直接链接" title="6.2 Kafka 工具的直接链接" translate="no">​</a></h3>





















































<table><thead><tr><th>工具</th><th>类型</th><th>优势</th><th>限制</th></tr></thead><tbody><tr><td><strong>AKHQ</strong>（<a href="https://akhq.io/" target="_blank" rel="noopener noreferrer" class="">akhq.io</a>）</td><td>开源 Web UI</td><td>多集群 + Schema Registry + Connect</td><td>中等规模</td></tr><tr><td><strong>Redpanda Console</strong></td><td>开源 Web UI</td><td>轻量、UI 简洁</td><td>功能较基础</td></tr><tr><td><strong>Confluent Control Center</strong></td><td>商业</td><td>官方最全、监控 + 告警 + 治理</td><td>重 + 付费</td></tr><tr><td><strong>Conduktor</strong></td><td>桌面端</td><td>桌面级 + 企业功能</td><td>商业</td></tr><tr><td><strong>Kowl</strong>（已被 Redpanda 收购）</td><td>开源</td><td>轻量</td><td>已停更</td></tr><tr><td><strong>kafka-ui</strong>（UI for Apache Kafka）</td><td>开源</td><td>部署简单</td><td>维护节奏一般</td></tr><tr><td><strong>Prometheus JMX Exporter + Grafana</strong></td><td>监控</td><td>指标丰富</td><td>需自建</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="63-推荐组合">6.3 推荐组合<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#63-%E6%8E%A8%E8%8D%90%E7%BB%84%E5%90%88" class="hash-link" aria-label="6.3 推荐组合的直接链接" title="6.3 推荐组合的直接链接" translate="no">​</a></h3>

























<table><thead><tr><th>团队规模</th><th>RMQ</th><th>Kafka</th></tr></thead><tbody><tr><td>小团队 / 中小规模</td><td>Management UI + Prometheus</td><td><strong>AKHQ</strong>（开源免费）</td></tr><tr><td>中大型</td><td>Prometheus + Grafana</td><td>Redpanda Console + Prometheus</td></tr><tr><td>企业付费</td><td>Prometheus + Grafana + 商业 APM</td><td><strong>Confluent Control Center</strong></td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-cli-vs-ui-操作实践">7. CLI vs UI 操作实践<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#7-cli-vs-ui-%E6%93%8D%E4%BD%9C%E5%AE%9E%E8%B7%B5" class="hash-link" aria-label="7. CLI vs UI 操作实践的直接链接" title="7. CLI vs UI 操作实践的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="71-生产实践原则">7.1 生产实践原则<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#71-%E7%94%9F%E4%BA%A7%E5%AE%9E%E8%B7%B5%E5%8E%9F%E5%88%99" class="hash-link" aria-label="7.1 生产实践原则的直接链接" title="7.1 生产实践原则的直接链接" translate="no">​</a></h3>
<blockquote>
<p><strong>日常查问题用 UI，批量操作 / 灾备 / 监控告警用 CLI + 自动化脚本。</strong></p>
</blockquote>













































<table><thead><tr><th>场景</th><th>用什么</th><th>原因</th></tr></thead><tbody><tr><td>查看消息内容（debug）</td><td><strong>UI</strong></td><td>直观、过滤方便</td></tr><tr><td>看队列长度、Consumer Lag</td><td><strong>UI / Grafana</strong></td><td>实时面板</td></tr><tr><td>创建/删除队列/Topic</td><td><strong>CLI</strong>（脚本化）</td><td>可审计、可批量</td></tr><tr><td>调整 partition / 配额</td><td><strong>CLI</strong></td><td>UI 容易误操作</td></tr><tr><td>灾备数据导入导出</td><td><strong>CLI</strong></td><td>可写脚本、可定时</td></tr><tr><td>监控告警</td><td><strong>Prometheus + Alertmanager</strong></td><td>自动化</td></tr><tr><td>跨环境同步配置</td><td><strong>CLI</strong> + IaC（Terraform）</td><td>幂等、可追溯</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="72-rabbitmq-cli-速查">7.2 RabbitMQ CLI 速查<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#72-rabbitmq-cli-%E9%80%9F%E6%9F%A5" class="hash-link" aria-label="7.2 RabbitMQ CLI 速查的直接链接" title="7.2 RabbitMQ CLI 速查的直接链接" translate="no">​</a></h3>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 查看队列列表</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">rabbitmqctl list_queues name messages_ready messages_unacknowledged</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 启用 Prometheus 插件</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">rabbitmq-plugins </span><span class="token builtin class-name">enable</span><span class="token plain"> rabbitmq_prometheus</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 设置 Policy（动态改 DLX）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">rabbitmqctl set_policy DLX </span><span class="token string" style="color:#e3116c">"orders.*"</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  </span><span class="token string" style="color:#e3116c">'{"dead-letter-exchange":"orders.dlx"}'</span><span class="token plain"> --apply-to queues </span><span class="token parameter variable" style="color:#36acaa">--priority</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">7</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># rabbitmqadmin（HTTP API 封装）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">rabbitmqadmin </span><span class="token parameter variable" style="color:#36acaa">-u</span><span class="token plain"> admin </span><span class="token parameter variable" style="color:#36acaa">-p</span><span class="token plain"> admin list queues</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">rabbitmqadmin </span><span class="token parameter variable" style="color:#36acaa">-u</span><span class="token plain"> admin </span><span class="token parameter variable" style="color:#36acaa">-p</span><span class="token plain"> admin publish </span><span class="token assign-left variable" style="color:#36acaa">exchange</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">orders </span><span class="token assign-left variable" style="color:#36acaa">routing_key</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">order.created </span><span class="token assign-left variable" style="color:#36acaa">payload</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">'{"id":1}'</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="73-kafka-cli-速查">7.3 Kafka CLI 速查<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#73-kafka-cli-%E9%80%9F%E6%9F%A5" class="hash-link" aria-label="7.3 Kafka CLI 速查的直接链接" title="7.3 Kafka CLI 速查的直接链接" translate="no">​</a></h3>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 启动 kafka-shell 容器后操作（或在 broker 容器内）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Topic 管理</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-topics.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--create</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--topic</span><span class="token plain"> orders </span><span class="token parameter variable" style="color:#36acaa">--partitions</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">6</span><span class="token plain"> --replication-factor </span><span class="token number" style="color:#36acaa">3</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-topics.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--list</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-topics.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--describe</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--topic</span><span class="token plain"> orders</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-topics.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--alter</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--topic</span><span class="token plain"> orders </span><span class="token parameter variable" style="color:#36acaa">--partitions</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">12</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 生产/消费</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-console-producer.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--topic</span><span class="token plain"> orders</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-console-consumer.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--topic</span><span class="token plain"> orders --from-beginning</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># Consumer Group 管理</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-consumer-groups.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--list</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-consumer-groups.sh --bootstrap-server localhost:9092 </span><span class="token parameter variable" style="color:#36acaa">--describe</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--group</span><span class="token plain"> order-processor</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">kafka-consumer-groups.sh --bootstrap-server localhost:9092 --reset-offsets </span><span class="token parameter variable" style="color:#36acaa">--group</span><span class="token plain"> order-processor </span><span class="token parameter variable" style="color:#36acaa">--topic</span><span class="token plain"> orders --to-earliest </span><span class="token parameter variable" style="color:#36acaa">--execute</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="74-生产实践-tips">7.4 生产实践 tips<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#74-%E7%94%9F%E4%BA%A7%E5%AE%9E%E8%B7%B5-tips" class="hash-link" aria-label="7.4 生产实践 tips的直接链接" title="7.4 生产实践 tips的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>Topic 创建走 IaC</strong>（Terraform / Ansible），不靠人肉 CLI</li>
<li class=""><strong>监控告警</strong> 100% CLI + Prometheus，不用 UI 报警（UI 是给人看的）</li>
<li class=""><strong>生产变更</strong> 全留操作记录（CLI 配 shell history / audit log）</li>
<li class=""><strong>查问题</strong> 先 UI 看现象，再 CLI 拉日志，再加 debug</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-反向场景--共存架构">8. 反向场景 + 共存架构<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#8-%E5%8F%8D%E5%90%91%E5%9C%BA%E6%99%AF--%E5%85%B1%E5%AD%98%E6%9E%B6%E6%9E%84" class="hash-link" aria-label="8. 反向场景 + 共存架构的直接链接" title="8. 反向场景 + 共存架构的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-什么时候不选-rabbitmq">8.1 什么时候不选 RabbitMQ<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#81-%E4%BB%80%E4%B9%88%E6%97%B6%E5%80%99%E4%B8%8D%E9%80%89-rabbitmq" class="hash-link" aria-label="8.1 什么时候不选 RabbitMQ的直接链接" title="8.1 什么时候不选 RabbitMQ的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ 消息要保留几天到几周（用 Kafka）</li>
<li class="">❌ 日志 / 事件流（用 Kafka）</li>
<li class="">❌ 单集群 &gt; 50 万 QPS（Kafka 集群更划算）</li>
<li class="">❌ 需要多个服务独立消费同一事件流（Kafka 多 Consumer Group）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-什么时候不选-kafka">8.2 什么时候不选 Kafka<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#82-%E4%BB%80%E4%B9%88%E6%97%B6%E5%80%99%E4%B8%8D%E9%80%89-kafka" class="hash-link" aria-label="8.2 什么时候不选 Kafka的直接链接" title="8.2 什么时候不选 Kafka的直接链接" translate="no">​</a></h3>
<ul>
<li class="">❌ 复杂路由（topic + partition 不够灵活）</li>
<li class="">❌ RPC / 同步请求-响应</li>
<li class="">❌ 极小消息量（运维成本不划算）</li>
<li class="">❌ 团队完全没接触过（学习曲线陡）</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="83-共存架构">8.3 共存架构<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#83-%E5%85%B1%E5%AD%98%E6%9E%B6%E6%9E%84" class="hash-link" aria-label="8.3 共存架构的直接链接" title="8.3 共存架构的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">[Web 业务]</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ↓</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">[RabbitMQ 集群]  ← 核心交易，Quorum Queue，复杂路由</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ├── 订单服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ├── 支付服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ├── 库存服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  └── 审计服务</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        ↓ (投递到 Kafka 归档)</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  [Kafka 集群]  ← 事件流，跨域，高吞吐</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ├── 实时风控</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ├── 数据湖</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    ├── 推荐系统</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    └── BI 报表</span><br></div></code></pre></div></div>
<p><strong>优点</strong>：</p>
<ul>
<li class="">业务关键路径用 RMQ（强一致）</li>
<li class="">数据管道用 Kafka（高吞吐 + 重放）</li>
<li class="">各取所长</li>
</ul>
<p><strong>代价</strong>：</p>
<ul>
<li class="">两套运维</li>
<li class="">数据双写一致性要自己处理</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关联笔记">关联笔记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97%E9%80%89%E5%9E%8B%E5%AF%B9%E6%AF%94%E7%AC%94%E8%AE%B0#%E5%85%B3%E8%81%94%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="关联笔记的直接链接" title="关联笔记的直接链接" translate="no">​</a></h2>
<ul>
<li class="">RabbitMQ 详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/rabbitmq">RabbitMQ笔记</a></li>
<li class="">Kafka 详情：<a class="" href="https://software-tech-notebook.lovefreedom1128.workers.dev/kafka">Kafka笔记</a></li>
<li class="">Demo：<code>example/mq/</code>（docker-compose + 生产级 Producer/Consumer + 事务示例）</li>
</ul>
<p>标签：#rabbitmq #kafka</p>]]></content>
        <category label="RabbitMQ" term="RabbitMQ"/>
        <category label="Kafka" term="Kafka"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[鉴权与登录笔记]]></title>
        <id>https://software-tech-notebook.lovefreedom1128.workers.dev/blog/鉴权与登录笔记</id>
        <link href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/鉴权与登录笔记"/>
        <updated>2026-11-06T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[原 旧稿（JWT 概念）+ 旧稿（OAuth2 + GitHub 第三方登录）的合并重写。]]></summary>
        <content type="html"><![CDATA[<blockquote>
<p>原 旧稿（JWT 概念）+ 旧稿（OAuth2 + GitHub 第三方登录）的合并重写。
原笔记是概念罗列，本笔记在此基础上<strong>补全 4 种主流登录方式的完整流程</strong>、<strong>JWT 生产级实践</strong>（双 Token / 撤销 / 攻击防御）、<strong>扫码登录的时序设计</strong>。</p>
<p>权限模型（RBAC / ReBAC / Casbin）见 <code>[[权限模型与Casbin实践笔记]]</code>。
API 网关与鉴权中间件见 <code>[[API网关原理与选型笔记]]</code>。</p>
</blockquote>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="目录">目录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#%E7%9B%AE%E5%BD%95" class="hash-link" aria-label="目录的直接链接" title="目录的直接链接" translate="no">​</a></h2>
<ol>
<li class="">登录方式全景对比</li>
<li class="">账号密码 + JWT（最常用）</li>
<li class="">OAuth2 第三方登录（含 GitHub 完整流程）</li>
<li class="">扫码登录（PC + 移动 App）</li>
<li class="">手机号验证码登录</li>
<li class="">Token 存储位置安全对比</li>
<li class="">JWT 安全攻击与防御（RFC 8725）</li>
<li class="">Token 撤销 / 黑名单</li>
<li class="">JWT 完整代码示例 + 选型</li>
</ol>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-登录方式全景对比">1. 登录方式全景对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#1-%E7%99%BB%E5%BD%95%E6%96%B9%E5%BC%8F%E5%85%A8%E6%99%AF%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="1. 登录方式全景对比的直接链接" title="1. 登录方式全景对比的直接链接" translate="no">​</a></h2>






















































<table><thead><tr><th>方式</th><th>用户体验</th><th>安全性</th><th>适用场景</th><th>关键技术</th></tr></thead><tbody><tr><td><strong>账号密码 + JWT</strong></td><td>中（要注册）</td><td>中（密码泄漏风险）</td><td>通用 Web / App</td><td>bcrypt + JWT 双 Token</td></tr><tr><td><strong>手机号验证码</strong></td><td>好（无需密码）</td><td>中（短信劫持）</td><td>国内移动端</td><td>短信网关 + 验证码缓存</td></tr><tr><td><strong>OAuth2 第三方登录</strong></td><td>最好（点一下）</td><td>高（委托给第三方）</td><td>通用 Web / App</td><td>授权码模式</td></tr><tr><td><strong>扫码登录</strong></td><td>好（无需输入）</td><td>高（依赖 App 端鉴权）</td><td>PC 端 + 已装 App</td><td>二维码 + 轮询 / WebSocket</td></tr><tr><td><strong>SSO 单点登录</strong></td><td>好（一次登录多处用）</td><td>高（统一 IdP）</td><td>企业内部 / 跨产品</td><td>SAML / OIDC / CAS</td></tr><tr><td><strong>密钥 / Passkey</strong></td><td>最好（指纹 / 面部）</td><td>最高</td><td>高安全场景</td><td>WebAuthn / FIDO2</td></tr></tbody></table>
<p><strong>选型原则：</strong></p>
<ul>
<li class="">通用 Web → 账号密码 + JWT，<strong>第三方登录作为补充</strong>（降低注册门槛）</li>
<li class="">国内移动 App → 手机号验证码是主流</li>
<li class="">PC + 移动 App 联动 → 扫码登录</li>
<li class="">企业内多产品 → SSO</li>
<li class="">高安全 / 支付 → Passkey 补充</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-账号密码--jwt最常用">2. 账号密码 + JWT（最常用）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#2-%E8%B4%A6%E5%8F%B7%E5%AF%86%E7%A0%81--jwt%E6%9C%80%E5%B8%B8%E7%94%A8" class="hash-link" aria-label="2. 账号密码 + JWT（最常用）的直接链接" title="2. 账号密码 + JWT（最常用）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="21-完整流程时序图">2.1 完整流程时序图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#21-%E5%AE%8C%E6%95%B4%E6%B5%81%E7%A8%8B%E6%97%B6%E5%BA%8F%E5%9B%BE" class="hash-link" aria-label="2.1 完整流程时序图的直接链接" title="2.1 完整流程时序图的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">用户              前端                网关              用户服务           Redis</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │  输入密码        │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ──────────────► │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ POST /login       │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ ────────────────► │ 转发             │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │ ────────────────►│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │                  │ 查 user + bcrypt  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │                  │ 校验密码          │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │                  │ 生成 access+refresh│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │                  │ save refresh ───►│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │ ◄────────────────│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ ◄────────────────│ 返回 tokens      │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ 存 token         │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ──────────────► │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ 访问受保护资源   │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ──────────────► │ GET /api/orders   │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ Authorization:    │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ Bearer eyJhbG...  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ ────────────────► │ 校验 JWT 签名    │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │ 转发 + X-User-Id │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │ ────────────────►│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │                   │ ◄────────────────│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                 │ ◄────────────────│ 返回数据         │                  │</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="22-jwt-三段结构">2.2 JWT 三段结构<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#22-jwt-%E4%B8%89%E6%AE%B5%E7%BB%93%E6%9E%84" class="hash-link" aria-label="2.2 JWT 三段结构的直接链接" title="2.2 JWT 三段结构的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.   ← Header  (Base64Url)</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJBbGljZSIsImlhdCI6MTUxMjIzOTAyMn0.  ← Payload</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c                   ← Signature</span><br></div></code></pre></div></div>
<p><strong>Header</strong>：</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"alg"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token property" style="color:#36acaa">"typ"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"JWT"</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><br></div></code></pre></div></div>
<p><strong>Payload</strong>（claims）：</p>


















































<table><thead><tr><th>claim</th><th>含义</th><th>必填？</th></tr></thead><tbody><tr><td><code>sub</code></td><td>subject（用户 ID）</td><td>✅</td></tr><tr><td><code>iat</code></td><td>issued at（签发时间）</td><td>推荐</td></tr><tr><td><code>exp</code></td><td>expiration time（过期时间）</td><td>✅</td></tr><tr><td><code>iss</code></td><td>issuer（签发方）</td><td>推荐</td></tr><tr><td><code>aud</code></td><td>audience（接收方）</td><td>推荐</td></tr><tr><td><code>jti</code></td><td>JWT ID（唯一标识，用于黑名单）</td><td>推荐</td></tr><tr><td><code>nbf</code></td><td>not before（生效时间）</td><td>可选</td></tr><tr><td>自定义</td><td><code>user_id</code> / <code>roles</code> / <code>tenant_id</code></td><td>视业务</td></tr></tbody></table>
<blockquote>
<p>⚠️ JWT payload 是<strong>明文 Base64Url 编码，不是加密</strong>！<strong>禁止放密码等敏感信息</strong>。需要加密用 JWE（RFC 7516）。</p>
</blockquote>
<p><strong>Signature</strong>：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">HMACSHA256(</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  base64UrlEncode(header) + "." + base64UrlEncode(payload),</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  secret</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">)</span><br></div></code></pre></div></div>
<p>服务端用相同算法 + secret 重算，对比签名 → 验签通过 = 数据未被篡改。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="23-生产实践双-token-模式">2.3 生产实践：双 Token 模式<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#23-%E7%94%9F%E4%BA%A7%E5%AE%9E%E8%B7%B5%E5%8F%8C-token-%E6%A8%A1%E5%BC%8F" class="hash-link" aria-label="2.3 生产实践：双 Token 模式的直接链接" title="2.3 生产实践：双 Token 模式的直接链接" translate="no">​</a></h3>
<blockquote>
<p>单 Token 模式有死结：短过期 → 用户频繁登录；长过期 → token 泄露后无法撤销。</p>
</blockquote>
<p><strong>Access Token + Refresh Token 双 Token</strong>：</p>






























<table><thead><tr><th></th><th>Access Token</th><th>Refresh Token</th></tr></thead><tbody><tr><td>过期时间</td><td>15 分钟 ~ 2 小时</td><td>7 ~ 30 天</td></tr><tr><td>用途</td><td>访问受保护 API</td><td>换新的 Access Token</td></tr><tr><td>存储</td><td>内存 / httpOnly cookie</td><td>httpOnly cookie / 加密存储</td></tr><tr><td>泄露后影响</td><td>时间窗有限（短过期）</td><td>可撤销（jti 黑名单）</td></tr></tbody></table>
<p><strong>Refresh Token 轮换（rotation）</strong>：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">客户端 → /token/refresh (refresh_token)</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       ← { access_token: new1, refresh_token: new2 }   ← 同时返回新的 refresh</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">       ← 旧 refresh_token 立即失效</span><br></div></code></pre></div></div>
<p>每次刷新都换新的 refresh，旧 refresh 入黑名单 → 即使被窃也只能用一次。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="24-密码安全">2.4 密码安全<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#24-%E5%AF%86%E7%A0%81%E5%AE%89%E5%85%A8" class="hash-link" aria-label="2.4 密码安全的直接链接" title="2.4 密码安全的直接链接" translate="no">​</a></h3>
<p><strong>必须用 bcrypt / argon2 哈希，不能用 MD5/SHA1</strong>：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> bcrypt</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 注册</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">password_bytes </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> password</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">salt </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> bcrypt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">gensalt</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">rounds</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">12</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">              </span><span class="token comment" style="color:#999988;font-style:italic"># cost factor 12~14</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">hashed </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> bcrypt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">hashpw</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">password_bytes</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> salt</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">db</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">save</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">user</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">password_hash</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">hashed</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># 登录</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> bcrypt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">checkpw</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">input_password</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> stored_hash</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 正确</span><br></div></code></pre></div></div>
<p><strong>bcrypt 哈希里包含 salt，无需单独存</strong>。cost factor 12 大约 250ms，够慢且安全。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-oauth2-第三方登录">3. OAuth2 第三方登录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#3-oauth2-%E7%AC%AC%E4%B8%89%E6%96%B9%E7%99%BB%E5%BD%95" class="hash-link" aria-label="3. OAuth2 第三方登录的直接链接" title="3. OAuth2 第三方登录的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="31-oauth2-四种授权模式">3.1 OAuth2 四种授权模式<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#31-oauth2-%E5%9B%9B%E7%A7%8D%E6%8E%88%E6%9D%83%E6%A8%A1%E5%BC%8F" class="hash-link" aria-label="3.1 OAuth2 四种授权模式的直接链接" title="3.1 OAuth2 四种授权模式的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>模式</th><th>令牌存放位置</th><th>适用</th><th>推荐度</th></tr></thead><tbody><tr><td><strong>授权码</strong> (authorization_code)</td><td>后端</td><td><strong>有后端的 Web 应用（首选）</strong></td><td>⭐⭐⭐⭐⭐</td></tr><tr><td>隐藏式 (implicit)</td><td>前端 URL fragment</td><td>纯前端 SPA（<strong>已不推荐</strong>，OAuth2.1 已废弃）</td><td>⭐</td></tr><tr><td>密码式 (password)</td><td>—</td><td>高度信任的自家应用（同公司产品）</td><td>⭐⭐</td></tr><tr><td>客户端凭证 (client_credentials)</td><td>—</td><td><strong>服务对服务</strong>（无用户参与）</td><td>⭐⭐⭐⭐</td></tr></tbody></table>
<blockquote>
<p>现代实践：<strong>Authorization Code + PKCE</strong>（防止拦截攻击，前端 SPA 也能用）。</p>
</blockquote>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="32-github-oauth-第三方登录完整流程5-步">3.2 GitHub OAuth 第三方登录完整流程（5 步）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#32-github-oauth-%E7%AC%AC%E4%B8%89%E6%96%B9%E7%99%BB%E5%BD%95%E5%AE%8C%E6%95%B4%E6%B5%81%E7%A8%8B5-%E6%AD%A5" class="hash-link" aria-label="3.2 GitHub OAuth 第三方登录完整流程（5 步）的直接链接" title="3.2 GitHub OAuth 第三方登录完整流程（5 步）的直接链接" translate="no">​</a></h3>
<blockquote>
<p>基于由旧稿内容补全与校正。</p>
</blockquote>
<p><strong>前置：注册应用</strong></p>
<p>到 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App：</p>

















<table><thead><tr><th>字段</th><th>填什么</th></tr></thead><tbody><tr><td>Homepage URL</td><td><code>https://yourapp.com</code></td></tr><tr><td>Authorization Callback URL</td><td><code>https://yourapp.com/oauth/callback</code></td></tr></tbody></table>
<p>提交后获得 <code>client_id</code>（公开）和 <code>client_secret</code>（<strong>必须保密，只放服务端</strong>）。</p>
<hr>
<p><strong>第 1 步：用户点击"GitHub 登录"</strong></p>
<p>前端跳转：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">https://github.com/login/oauth/authorize</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ?client_id=Iv1.abc123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;redirect_uri=https://yourapp.com/oauth/callback</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;scope=read:user user:email</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;state=random_csrf_token           ← 防 CSRF，必带</span><br></div></code></pre></div></div>
<p><strong>第 2 步：用户在 GitHub 上同意授权</strong></p>
<p>GitHub 显示应用名 + 申请的 scope，用户点 Authorize。</p>
<p><strong>第 3 步：GitHub 回调到 <code>redirect_uri</code></strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">https://yourapp.com/oauth/callback</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  ?code=859310e7cecc9196f4af        ← 一次性授权码（10 分钟过期）</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;state=random_csrf_token           ← 必须校验等于第 1 步的 state</span><br></div></code></pre></div></div>
<p><strong>第 4 步：服务端用 code 换 token</strong></p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">POST https://github.com/login/oauth/access_token</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Headers:</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  Accept: application/json</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Body:</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  client_id=Iv1.abc123</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;client_secret=&lt;your_secret&gt;</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;code=859310e7cecc9196f4af</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  &amp;redirect_uri=https://yourapp.com/oauth/callback</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Response:</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">{</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  "access_token": "gho_xxxxxxxxxxxxxxxxxxxx",</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  "scope": "read:user,user:email",</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  "token_type": "bearer"</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">}</span><br></div></code></pre></div></div>
<p><strong>第 5 步：服务端用 access_token 拉用户信息</strong></p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">GET https://api.github.com/user</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Headers:</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  Authorization: Bearer gho_xxxxxxxxxxxxxxxxxxxx</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">Response:</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">{ "id": 12345, "login": "alice", "name": "Alice", "email": "..." }</span><br></div></code></pre></div></div>
<p>服务端据此自动注册 / 登录本地账户，签发<strong>自己的</strong> access + refresh token 给前端。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="33-oauth2-关键安全点">3.3 OAuth2 关键安全点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#33-oauth2-%E5%85%B3%E9%94%AE%E5%AE%89%E5%85%A8%E7%82%B9" class="hash-link" aria-label="3.3 OAuth2 关键安全点的直接链接" title="3.3 OAuth2 关键安全点的直接链接" translate="no">​</a></h3>





























<table><thead><tr><th>风险</th><th>防御</th></tr></thead><tbody><tr><td><code>client_secret</code> 泄露</td><td><strong>只在服务端用</strong>，前端绝不能出现</td></tr><tr><td><code>redirect_uri</code> 被劫持</td><td><strong>必须预注册</strong>且严格匹配（GitHub 不允许 query string 差异）</td></tr><tr><td>CSRF 攻击</td><td>用 <code>state</code> 参数（随机字符串，登录后校验一致）</td></tr><tr><td>授权码被重用</td><td>授权码 10 分钟过期 + 一次性</td></tr><tr><td>scope 越权</td><td>只申请必要的 scope（如 <code>read:user</code> 而非全部）</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="34-oauth2--oidc--jwt-关系">3.4 OAuth2 / OIDC / JWT 关系<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#34-oauth2--oidc--jwt-%E5%85%B3%E7%B3%BB" class="hash-link" aria-label="3.4 OAuth2 / OIDC / JWT 关系的直接链接" title="3.4 OAuth2 / OIDC / JWT 关系的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">OAuth 2.0  = 授权框架（"你能做什么"）   → RFC 6749</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">OIDC       = OAuth 2.0 之上的身份层（"你是谁"）   → OpenID Connect Core 1.0</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">JWT        = Token 格式（OAuth2 不限定 Token 格式，OIDC 用 JWT 标准化 ID Token）</span><br></div></code></pre></div></div>
<p>第三方登录走的是 OAuth2 流程；最终给用户签发的 token 通常是 JWT。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-扫码登录pc--移动-app">4. 扫码登录（PC + 移动 App）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#4-%E6%89%AB%E7%A0%81%E7%99%BB%E5%BD%95pc--%E7%A7%BB%E5%8A%A8-app" class="hash-link" aria-label="4. 扫码登录（PC + 移动 App）的直接链接" title="4. 扫码登录（PC + 移动 App）的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="41-核心思想">4.1 核心思想<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#41-%E6%A0%B8%E5%BF%83%E6%80%9D%E6%83%B3" class="hash-link" aria-label="4.1 核心思想的直接链接" title="4.1 核心思想的直接链接" translate="no">​</a></h3>
<p>PC 端显示二维码 → 手机 App 扫码 → App 已登录态自动确认 → PC 端登录成功。</p>
<p><strong>不需要 PC 端输入账号密码</strong>——App 已经登录，凭 App 端身份为 PC 授权。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="42-5-步时序图">4.2 5 步时序图<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#42-5-%E6%AD%A5%E6%97%B6%E5%BA%8F%E5%9B%BE" class="hash-link" aria-label="4.2 5 步时序图的直接链接" title="4.2 5 步时序图的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">PC 浏览器       后端              手机 App           Redis / DB</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ 1. 生成二维码  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ GET /qr/gen  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ ────────────►│                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 生成 qr_id       │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 存 status=等待扫码                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ ────────────────────────────────►   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ ◄────────────│ 返回 {qr_id, qr_token (含临时密钥)}│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ 显示二维码    │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │ 扫码（解码出 URL │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │ + qr_token）     │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 2. App 上确认登录 │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ POST /qr/scan    │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ + qr_token       │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ + App 用户身份   │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ ◄────────────────│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 校验 qr_token    │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 存 status=已确认                   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ + 临时 login_code                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ ────────────────────────────────►   │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ 3. PC 轮询状态 │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ GET /qr/status/{qr_id}         │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ ────────────►│                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ ◄────查 status ──┼──────────────────│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ ◄────────────│ {status:已确认,  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │  login_code}     │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ 4. 用 login_code 换 token        │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ POST /qr/login {login_code}    │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ ────────────►│                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 校验 login_code  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │ 返回 access+refresh                 │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │ ◄────────────│                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  │              │                  │                  │</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="43-关键设计点">4.3 关键设计点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#43-%E5%85%B3%E9%94%AE%E8%AE%BE%E8%AE%A1%E7%82%B9" class="hash-link" aria-label="4.3 关键设计点的直接链接" title="4.3 关键设计点的直接链接" translate="no">​</a></h3>

































<table><thead><tr><th>步骤</th><th>关键点</th></tr></thead><tbody><tr><td>生成二维码</td><td><code>qr_id</code> 唯一 + <code>qr_token</code> 含临时密钥（HMAC 签名，防伪造）</td></tr><tr><td>二维码内容</td><td>通常是 URL：<code>https://yourapp.com/qr/scan?qr_id=xxx&amp;sig=xxx</code></td></tr><tr><td>PC 轮询 vs 长连接</td><td>简单场景用 2s 轮询；体验好场景用 <strong>WebSocket 推送</strong>（见 <code>[[websocket笔记]]</code>）</td></tr><tr><td>扫码过期</td><td>二维码 60~120 秒过期，防恶意截屏</td></tr><tr><td>login_code</td><td>一次性，使用后立即失效</td></tr><tr><td>已扫码未确认 vs 已确认</td><td>两个状态，前端 UI 要区分（"已扫码，请在手机上确认"）</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="44-防伪关键">4.4 防伪关键<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#44-%E9%98%B2%E4%BC%AA%E5%85%B3%E9%94%AE" class="hash-link" aria-label="4.4 防伪关键的直接链接" title="4.4 防伪关键的直接链接" translate="no">​</a></h3>
<p><strong>qr_token 必须服务端签发 + App 端校验签名</strong>：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">qr_token </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"qr_id"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> qr_id</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> now </span><span class="token operator" style="color:#393A34">+</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">90</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    algorithm</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<p>App 端不信任二维码内容（因为可以伪造截图），但信任服务端签名。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-手机号验证码登录">5. 手机号验证码登录<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#5-%E6%89%8B%E6%9C%BA%E5%8F%B7%E9%AA%8C%E8%AF%81%E7%A0%81%E7%99%BB%E5%BD%95" class="hash-link" aria-label="5. 手机号验证码登录的直接链接" title="5. 手机号验证码登录的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="51-流程">5.1 流程<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#51-%E6%B5%81%E7%A8%8B" class="hash-link" aria-label="5.1 流程的直接链接" title="5.1 流程的直接链接" translate="no">​</a></h3>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">前端                后端              短信网关           Redis</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ POST /sms/send   │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ {phone: 138...}  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ────────────────►│                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 检查 60s 间隔    │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 检查单日上限      │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 生成 6 位验证码  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 存 redis ────────┼─────────────────►│</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 调用短信网关     │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ ────────────────►│                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │                  │ 发短信            │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ◄────────────────│ 返回 ok          │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ POST /login      │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ {phone, code}    │                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ────────────────►│                  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 查 redis 验证码  │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 校验 + 删除      │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │                  │ 自动注册/登录    │                  │</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"> │ ◄────────────────│ 返回 tokens     │                  │</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="52-防刷要点">5.2 防刷要点<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#52-%E9%98%B2%E5%88%B7%E8%A6%81%E7%82%B9" class="hash-link" aria-label="5.2 防刷要点的直接链接" title="5.2 防刷要点的直接链接" translate="no">​</a></h3>
<ul>
<li class=""><strong>图形验证码</strong>：调 <code>/sms/send</code> 前必须通过滑块 / 点选验证</li>
<li class=""><strong>60 秒间隔</strong>：同一手机号 60 秒内只能发一次</li>
<li class=""><strong>单日上限</strong>：同一手机号每天最多 5~10 条</li>
<li class=""><strong>IP 限流</strong>：同一 IP 每小时最多 20 条</li>
<li class=""><strong>验证码 5 分钟过期</strong>，且<strong>只能用一次</strong></li>
<li class=""><strong>错误次数限制</strong>：连续 3 次错误验证码 → 该手机号当日锁定</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-token-存储位置安全对比">6. Token 存储位置安全对比<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#6-token-%E5%AD%98%E5%82%A8%E4%BD%8D%E7%BD%AE%E5%AE%89%E5%85%A8%E5%AF%B9%E6%AF%94" class="hash-link" aria-label="6. Token 存储位置安全对比的直接链接" title="6. Token 存储位置安全对比的直接链接" translate="no">​</a></h2>








































<table><thead><tr><th>位置</th><th>XSS 风险</th><th>CSRF 风险</th><th>适用</th><th>推荐度</th></tr></thead><tbody><tr><td><strong>localStorage</strong></td><td>❌ 高（JS 可读）</td><td>✅ 低</td><td>—</td><td>❌ 不推荐</td></tr><tr><td><strong>sessionStorage</strong></td><td>❌ 高（JS 可读）</td><td>✅ 低</td><td>短期敏感操作</td><td>⚠️ 一般</td></tr><tr><td><strong>httpOnly Cookie</strong></td><td>✅ 低（JS 读不到）</td><td>❌ 高（自动携带）</td><td><strong>Web 主流方案</strong></td><td>⭐⭐⭐⭐</td></tr><tr><td><strong>内存（React state）</strong></td><td>✅ 低</td><td>✅ 低</td><td>高安全 SPA</td><td>⭐⭐⭐⭐</td></tr></tbody></table>
<p><strong>推荐方案</strong>：<strong>httpOnly + Secure + SameSite=Lax Cookie 存 Refresh Token，Access Token 存内存</strong>。</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># 后端 Set-Cookie</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">response</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">set_cookie</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    key</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"refresh_token"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    value</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">refresh_token</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    httponly</span><span class="token operator" style="color:#393A34">=</span><span class="token boolean" style="color:#36acaa">True</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    secure</span><span class="token operator" style="color:#393A34">=</span><span class="token boolean" style="color:#36acaa">True</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain">             </span><span class="token comment" style="color:#999988;font-style:italic"># 仅 HTTPS</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    samesite</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"lax"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    max_age</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">7</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">24</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3600</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<blockquote>
<p>Access Token 放内存（React state / Pinia）：刷新页面就丢，重新用 refresh 换。<strong>XSS 拿不到，安全性高</strong>。</p>
</blockquote>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-jwt-安全攻击与防御rfc-8725">7. JWT 安全攻击与防御（RFC 8725）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#7-jwt-%E5%AE%89%E5%85%A8%E6%94%BB%E5%87%BB%E4%B8%8E%E9%98%B2%E5%BE%A1rfc-8725" class="hash-link" aria-label="7. JWT 安全攻击与防御（RFC 8725）的直接链接" title="7. JWT 安全攻击与防御（RFC 8725）的直接链接" translate="no">​</a></h2>













































<table><thead><tr><th>攻击</th><th>原理</th><th>防御</th></tr></thead><tbody><tr><td><strong><code>alg=none</code> 绕过</strong></td><td>攻击者改 header <code>alg: none</code>，服务器若没校验就直接放过</td><td><strong>强制算法白名单</strong> <code>algorithms=["HS256"]</code></td></tr><tr><td><strong>RS256 → HS256 密钥混淆</strong></td><td>服务端用公钥验签，攻击者把 alg 改成 HS256、用公钥作 HMAC secret</td><td><strong>强制密钥与算法绑定</strong>（pyjwt 自动）</td></tr><tr><td><strong>弱对称密钥</strong></td><td>短 secret 被暴力破解</td><td><code>enforce_minimum_key_length=True</code>（HS256 ≥ 256 bit）</td></tr><tr><td><strong>嵌套 JWT 漏验</strong></td><td>内层 JWT 没递归验签</td><td>库实现需逐层验签</td></tr><tr><td><strong><code>kid</code> 注入</strong></td><td><code>kid</code> 字段指向攻击者控制的路径 / SQL</td><td>kid 白名单 / 不解析为路径</td></tr><tr><td><strong><code>jku</code> / <code>x5u</code> SSRF</strong></td><td>指向恶意 JWKS endpoint</td><td>不支持这些 header / 严格白名单</td></tr><tr><td><strong>跨 JWT 替代</strong></td><td>同一 secret 签发不同用途 JWT 互相替代</td><td>用不同 <code>aud</code> / <code>typ</code> / <code>iss</code> 隔离</td></tr></tbody></table>
<p><strong>pyjwt 防御示例</strong>：</p>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">decode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    token</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    algorithms</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain">      </span><span class="token comment" style="color:#999988;font-style:italic"># 强制白名单（关键！）</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    audience</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"myapp"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    issuer</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"my-auth-server"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    options</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"require"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-token-撤销--黑名单">8. Token 撤销 / 黑名单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#8-token-%E6%92%A4%E9%94%80--%E9%BB%91%E5%90%8D%E5%8D%95" class="hash-link" aria-label="8. Token 撤销 / 黑名单的直接链接" title="8. Token 撤销 / 黑名单的直接链接" translate="no">​</a></h2>
<p>JWT 本身<strong>无状态</strong>，签发后无法主动失效。生产必须做撤销机制。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="81-撤销策略按效果递减">8.1 撤销策略（按效果递减）<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#81-%E6%92%A4%E9%94%80%E7%AD%96%E7%95%A5%E6%8C%89%E6%95%88%E6%9E%9C%E9%80%92%E5%87%8F" class="hash-link" aria-label="8.1 撤销策略（按效果递减）的直接链接" title="8.1 撤销策略（按效果递减）的直接链接" translate="no">​</a></h3>






























<table><thead><tr><th>策略</th><th>实现</th><th>适用</th></tr></thead><tbody><tr><td><strong>短 Access + Refresh 轮换</strong></td><td>access 15min，refresh 每次换新</td><td>所有生产</td></tr><tr><td><strong>jti 黑名单（Redis）</strong></td><td>登出时 <code>SET jwt:blacklist:{jti} 1 EX &lt;剩余exp&gt;</code></td><td>主动登出 / 改密</td></tr><tr><td><strong>Refresh Token 撤销表</strong></td><td>DB 存有效 refresh，校验时查</td><td>高安全场景</td></tr><tr><td><strong>全局密钥轮换</strong></td><td>紧急事件立刻换 secret（所有 token 失效）</td><td>极端情况</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="82-实现jti-黑名单">8.2 实现：jti 黑名单<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#82-%E5%AE%9E%E7%8E%B0jti-%E9%BB%91%E5%90%8D%E5%8D%95" class="hash-link" aria-label="8.2 实现：jti 黑名单的直接链接" title="8.2 实现：jti 黑名单的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> jwt</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> redis</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> uuid</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">r </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> redis</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Redis</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">issue_access</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> sub</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">uuid</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">uuid4</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> datetime</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">tz</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">timezone</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">utc</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">+</span><span class="token plain"> timedelta</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">minutes</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">15</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"type"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"access"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithm</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">issue_refresh</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    jti </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">uuid</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">uuid4</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    r</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">setex</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string-interpolation string" style="color:#e3116c">f"jwt:active:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">jti</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">7</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">24</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">3600</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> sub</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain">       </span><span class="token comment" style="color:#999988;font-style:italic"># 存 7 天</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> sub</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> jti</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> datetime</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">tz</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">timezone</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">utc</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">+</span><span class="token plain"> timedelta</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">days</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">7</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token string" style="color:#e3116c">"type"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"refresh"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithm</span><span class="token operator" style="color:#393A34">=</span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">revoke</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">jti</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    r</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">delete</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string-interpolation string" style="color:#e3116c">f"jwt:active:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">jti</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">verify_with_blacklist</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">token</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    payload </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">decode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">token</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithms</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    jti </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> payload</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> jti </span><span class="token keyword" style="color:#00009f">and</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> r</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">exists</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string-interpolation string" style="color:#e3116c">f"jwt:active:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">jti</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">raise</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">InvalidTokenError</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"revoked"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> payload</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-jwt-完整代码示例--选型">9. JWT 完整代码示例 + 选型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#9-jwt-%E5%AE%8C%E6%95%B4%E4%BB%A3%E7%A0%81%E7%A4%BA%E4%BE%8B--%E9%80%89%E5%9E%8B" class="hash-link" aria-label="9. JWT 完整代码示例 + 选型的直接链接" title="9. JWT 完整代码示例 + 选型的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="91-算法选型">9.1 算法选型<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#91-%E7%AE%97%E6%B3%95%E9%80%89%E5%9E%8B" class="hash-link" aria-label="9.1 算法选型的直接链接" title="9.1 算法选型的直接链接" translate="no">​</a></h3>



































<table><thead><tr><th>算法</th><th>类型</th><th>密钥</th><th>适用</th></tr></thead><tbody><tr><td><strong>HS256</strong></td><td>HMAC 对称</td><td>单一密钥</td><td>单服务 / 内部系统</td></tr><tr><td><strong>RS256</strong></td><td>RSA 非对称</td><td>私钥签 / 公钥验</td><td>多服务 / 对外提供 SSO</td></tr><tr><td><strong>ES256</strong></td><td>ECDSA</td><td>更短</td><td>移动端 / 高性能</td></tr><tr><td><strong>EdDSA</strong></td><td>Ed25519</td><td>现代高性能</td><td>新系统</td></tr></tbody></table>
<p><strong>原则</strong>：<strong>单服务用 HS256</strong>，<strong>多服务 / 对外交互用 RS256</strong>（公钥可对外发布验签）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="92-pyjwt-双-token-完整示例">9.2 pyjwt 双 Token 完整示例<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#92-pyjwt-%E5%8F%8C-token-%E5%AE%8C%E6%95%B4%E7%A4%BA%E4%BE%8B" class="hash-link" aria-label="9.2 pyjwt 双 Token 完整示例的直接链接" title="9.2 pyjwt 双 Token 完整示例的直接链接" translate="no">​</a></h3>
<div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> jwt</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> uuid</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> redis</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> datetime </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> datetime</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> timezone</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> timedelta</span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">SECRET </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"your-256-bit-secret-from-env"</span><span class="token plain">  </span><span class="token comment" style="color:#999988;font-style:italic"># ≥ 32 字节</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">ALG </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"HS256"</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">ACCESS_TTL </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> timedelta</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">minutes</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">15</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">REFRESH_TTL </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> timedelta</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">days</span><span class="token operator" style="color:#393A34">=</span><span class="token number" style="color:#36acaa">7</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">r </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> redis</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Redis</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">_now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> datetime</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> datetime</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">tz</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">timezone</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">utc</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">issue_tokens</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">sub</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> extra</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">|</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">None</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">None</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token triple-quoted-string string" style="color:#e3116c">"""签发 access + refresh 双 token。"""</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    base </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> sub</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"iat"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> _now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> extra</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        base</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">update</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">extra</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    access_jti </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">uuid</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">uuid4</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    access </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token punctuation" style="color:#393A34">{</span><span class="token operator" style="color:#393A34">**</span><span class="token plain">base</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> access_jti</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         </span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> _now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">+</span><span class="token plain"> ACCESS_TTL</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"type"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"access"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithm</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">ALG</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    refresh_jti </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">uuid</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">uuid4</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    refresh </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">encode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token punctuation" style="color:#393A34">{</span><span class="token operator" style="color:#393A34">**</span><span class="token plain">base</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> refresh_jti</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">         </span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> _now</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">+</span><span class="token plain"> REFRESH_TTL</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"type"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"refresh"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithm</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">ALG</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    r</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">setex</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string-interpolation string" style="color:#e3116c">f"jwt:active:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">refresh_jti</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">REFRESH_TTL</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">total_seconds</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> sub</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"access_token"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> access</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"refresh_token"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> refresh</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"token_type"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"bearer"</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">refresh</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">refresh_token</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token triple-quoted-string string" style="color:#e3116c">"""用 refresh 换新的双 token（旧 refresh 立即失效）。"""</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    payload </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">decode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">refresh_token</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithms</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain">ALG</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> payload</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"type"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">!=</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"refresh"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">raise</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">InvalidTokenError</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"not a refresh token"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    jti </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> payload</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> r</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">exists</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string-interpolation string" style="color:#e3116c">f"jwt:active:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">jti</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        </span><span class="token keyword" style="color:#00009f">raise</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">InvalidTokenError</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"refresh token revoked or expired"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token comment" style="color:#999988;font-style:italic"># 撤销旧 refresh + 颁发新双 token</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    r</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">delete</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string-interpolation string" style="color:#e3116c">f"jwt:active:</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">{</span><span class="token string-interpolation interpolation">jti</span><span class="token string-interpolation interpolation punctuation" style="color:#393A34">}</span><span class="token string-interpolation string" style="color:#e3116c">"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> issue_tokens</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">payload</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">k</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> v </span><span class="token keyword" style="color:#00009f">for</span><span class="token plain"> k</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> v </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> payload</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">items</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">                                         </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> k </span><span class="token keyword" style="color:#00009f">not</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"iat"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"jti"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"type"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">verify_access</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">token</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">str</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">&gt;</span><span class="token plain"> </span><span class="token builtin">dict</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token triple-quoted-string string" style="color:#e3116c">"""校验 access token（不做黑名单校验，因为 access TTL 短）。"""</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> jwt</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">decode</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        token</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> SECRET</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> algorithms</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain">ALG</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">        options</span><span class="token operator" style="color:#393A34">=</span><span class="token punctuation" style="color:#393A34">{</span><span class="token string" style="color:#e3116c">"require"</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"exp"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"sub"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">    </span><span class="token punctuation" style="color:#393A34">)</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="93-与-oauth2--oidc-的边界">9.3 与 OAuth2 / OIDC 的边界<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#93-%E4%B8%8E-oauth2--oidc-%E7%9A%84%E8%BE%B9%E7%95%8C" class="hash-link" aria-label="9.3 与 OAuth2 / OIDC 的边界的直接链接" title="9.3 与 OAuth2 / OIDC 的边界的直接链接" translate="no">​</a></h3>
<ul>
<li class="">自己的账号系统（账号密码 / 手机号 / 扫码登录）→ 直接发 JWT</li>
<li class="">第三方登录 → <strong>走 OAuth2 流程</strong>（让用户授权），最终仍发<strong>自己的 JWT</strong></li>
<li class="">对外提供登录能力（SSO） → 自己是 OAuth2 Server + OIDC（返回标准 ID Token / UserInfo）</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="关联笔记">关联笔记<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#%E5%85%B3%E8%81%94%E7%AC%94%E8%AE%B0" class="hash-link" aria-label="关联笔记的直接链接" title="关联笔记的直接链接" translate="no">​</a></h2>
<ul>
<li class="">权限模型（拿到 token 后能做什么）：<code>[[权限模型与Casbin实践笔记]]</code></li>
<li class="">API 网关（鉴权中间件放在哪）：<code>[[API网关原理与选型笔记]]</code></li>
<li class="">WebSocket 扫码登录长连接：<code>[[websocket笔记]]</code></li>
<li class="">网络安全（TLS / HTTPS）：<code>[[TCP_IP四层网络模型笔记]]</code></li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="demo">Demo<a href="https://software-tech-notebook.lovefreedom1128.workers.dev/blog/%E9%89%B4%E6%9D%83%E4%B8%8E%E7%99%BB%E5%BD%95%E7%AC%94%E8%AE%B0#demo" class="hash-link" aria-label="Demo的直接链接" title="Demo的直接链接" translate="no">​</a></h2>
<p>完整代码（JWT + 扫码登录 + Casbin 鉴权）：</p>
<ul>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/auth_demo.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/auth_demo.py</code></a></li>
<li class=""><a href="https://github.com/HiRidgewalker/soft-tech-notebook/blob/main/example/gateway/scan_login_demo.py" target="_blank" rel="noopener noreferrer" class=""><code>example/gateway/scan_login_demo.py</code></a></li>
</ul>
<p>标签：#fastapi #redis</p>]]></content>
        <category label="FastAPI" term="FastAPI"/>
        <category label="Redis" term="Redis"/>
    </entry>
</feed>